Re: [PATCH v3 3/4] doc: dissuade users from trying to ignore tracked files

[Jakub Narebski <jnareb@gmail.com>]

"brian m. carlson" <sandals@crustytoothpaste.net> 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@crustytoothpaste.net>
> ---
>  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