[v2,2/3] doc: dissuade users from trying to ignore tracked files
diff mbox series

Message ID 20191017005330.9021-3-sandals@crustytoothpaste.net
State New
Headers show
Series
  • Documentation for common user misconceptions
Related show

Commit Message

brian m. carlson Oct. 17, 2019, 12:53 a.m. UTC
It is quite common for users to want to ignore the changes to a file
that Git tracks.  Common scenarios for this case are IDE settings and
configuration files, which should generally not be tracked and possibly
generated from tracked files using a templating mechanism.

However, users learn about the assume-unchanged and skip-worktree bits
and try to use them to do this anyway.  This is problematic, because
when these bits are set, many operations behave as the user expects, but
they usually do not help when git checkout needs to replace a file.

There is no sensible behavior in this case, because sometimes the data
is precious, such as certain configuration files, and sometimes it is
irrelevant data that the user would be happy to discard.

Since this is not a supported configuration and users are prone to
misuse the existing features for unintended purposes, causing general
sadness and confusion, let's document the existing behavior and the
pitfalls in the documentation for git update-index so that users know
they should explore alternate solutions.

Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
 Documentation/git-update-index.txt | 10 ++++++++++
 1 file changed, 10 insertions(+)

Comments

Jeff King Oct. 17, 2019, 5:44 a.m. UTC | #1
On Thu, Oct 17, 2019 at 12:53:29AM +0000, brian m. carlson wrote:

> There is no sensible behavior in this case, because sometimes the data
> is precious, such as certain configuration files, and sometimes it is
> irrelevant data that the user would be happy to discard.
> 
> Since this is not a supported configuration and users are prone to
> misuse the existing features for unintended purposes, causing general
> sadness and confusion, let's document the existing behavior and the
> pitfalls in the documentation for git update-index so that users know
> they should explore alternate solutions.

I think this is an improvement. It would be nice if we had some specific
alternatives to point them to. But as you note, Git doesn't really have
a good solution for this built-in. And I don't know offhand of a
complete one that we could recommend. So this is probably the best we
can do for now.

-Peff

Patch
diff mbox series

diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt
index 1c4d146a41..502e06abc0 100644
--- a/Documentation/git-update-index.txt
+++ b/Documentation/git-update-index.txt
@@ -543,6 +543,16 @@  The untracked cache extension can be enabled by the
 `core.untrackedCache` configuration variable (see
 linkgit:git-config[1]).
 
+NOTES
+-----
+
+Users often try to use the ``assume unchanged'' and skip-worktree bits
+to tell Git to ignore changes to files that are tracked.  This does not
+work as expected, since Git may still check working tree files against
+the index when performing certain operations.  In general, Git does not
+provide a way to ignore changes to tracked files, so alternate solutions
+are recommended.
+
 SEE ALSO
 --------
 linkgit:git-config[1],