From: Jakub Narebski <jnareb@gmail.com>
To: "brian m. carlson" <sandals@crustytoothpaste.net>
Cc: <git@vger.kernel.org>, Junio C Hamano <gitster@pobox.com>,
Jeff King <peff@peff.net>
Subject: Re: [PATCH v3 3/4] doc: dissuade users from trying to ignore tracked files
Date: Sun, 03 Nov 2019 16:04:44 +0100 [thread overview]
Message-ID: <86h83lhugj.fsf@gmail.com> (raw)
In-Reply-To: <20191102192615.10013-4-sandals@crustytoothpaste.net> (brian m. carlson's message of "Sat, 2 Nov 2019 19:26:14 +0000")
"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
next prev parent reply other threads:[~2019-11-03 15:04 UTC|newest]
Thread overview: 25+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-11-02 19:26 [PATCH v3 0/4] Documentation for common user misconceptions brian m. carlson
2019-11-02 19:26 ` [PATCH v3 1/4] doc: move author and committer information to git-commit(1) brian m. carlson
2019-11-03 11:13 ` Jakub Narebski
2019-11-04 22:18 ` Jeff King
2019-11-06 1:55 ` Junio C Hamano
2019-11-02 19:26 ` [PATCH v3 2/4] doc: provide guidance on user.name format brian m. carlson
2019-11-03 13:13 ` Jakub Narebski
2019-11-03 19:23 ` brian m. carlson
2019-11-02 19:26 ` [PATCH v3 3/4] doc: dissuade users from trying to ignore tracked files brian m. carlson
2019-11-02 20:14 ` rsbecker
2019-11-03 15:46 ` Jakub Narebski
2019-11-03 15:04 ` Jakub Narebski [this message]
2019-11-03 18:59 ` brian m. carlson
2019-11-03 19:40 ` Jakub Narebski
2019-11-03 21:46 ` brian m. carlson
2019-11-05 0:21 ` Jakub Narebski
2019-11-04 22:24 ` Jeff King
2019-11-04 23:52 ` brian m. carlson
2019-11-02 19:26 ` [PATCH v3 4/4] docs: mention when increasing http.postBuffer is valuable brian m. carlson
2019-11-04 22:26 ` [PATCH v3 0/4] Documentation for common user misconceptions Jeff King
2019-11-06 1:58 ` Junio C Hamano
2019-11-06 2:19 ` brian m. carlson
2019-11-06 3:15 ` Junio C Hamano
2020-01-16 21:08 ` Emily Shaffer
2020-01-16 23:35 ` brian m. carlson
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=86h83lhugj.fsf@gmail.com \
--to=jnareb@gmail.com \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=peff@peff.net \
--cc=sandals@crustytoothpaste.net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).