"brian m. carlson" <sandals@xxxxxxxxxxxxxxxxxxxx> writes: > 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. > > In additon, let's provide a recommended solution to dealing with the > common case of configuration files, since there are well-known > approaches used successfully in many environments. All right, looks sensible and good thing to have. > Signed-off-by: brian m. carlson <sandals@xxxxxxxxxxxxxxxxxxxx> > --- > Documentation/git-update-index.txt | 16 ++++++++++++++++ > 1 file changed, 16 insertions(+) > > diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt > index 1c4d146a41..11230376c8 100644 > --- a/Documentation/git-update-index.txt > +++ b/Documentation/git-update-index.txt > @@ -543,6 +543,22 @@ 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 Why the change between formatting '``assume unchanged''' (with double quotes and space separated) and 'skip-worktree' (without quotes, and kebab-cased)? In the commit message you write about assume-unchanged and skip-worktree. I guess that follows the inconsistency in git-update-index(1) headers, namely we have USING ``ASSUME UNCHANGED'' BIT ------------------------------ but SKIP-WORKTREE BIT ----------------- This incconsistency is much more viible when both names are on the same line, however. This is a minor nit. > +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. I'm not sure if it is a place for it, but the proposed text treats assume-unchanged and skip-worktree as similarly unsuited for intended purpose. However, their failure modes are different: (ab)using the assume-unchanged for "ignore changed to tracked files" may lead to data loss (as changes are overwritten), while with skip-worktree the trouble is that some operations that should succeed (like unstashing) are unnecessarily blocked - but no data loss. > + > +If the file you want to change is some sort of configuration file (say, > +for a build tool, IDE, or editor), a common solution is to use a > +templating mechanism, such as Ruby's ERB, to generate the ignored > +configuration file from a template stored in the repository and a source > +of data using a script or build step. I would really like to see a simple example of such template, so that even people who are unfamiliar with Ruby's ERB can think of equivalent solution for their language or toolchain of choice. > + > SEE ALSO > -------- > linkgit:git-config[1], Best, -- Jakub Narębski
