Re: Git issue

From: Jeff King <peff@peff.net>
Date: Nov 1, 2016, 21:03 UTC
Message-ID: <20161101210310.sqrhvviry7iyyjrm@sigill.intra.peff.net>
In-Reply-To: <7CE3166CFD244DAABF554451E8B0800F@PhilipOakley>

On Tue, Nov 01, 2016 at 08:50:23PM -0000, Philip Oakley wrote:

Show 23 quoted lines

> > From "git help update-index":
> > 
> >      --[no-]assume-unchanged
> >    When this flag is specified, the object names recorded for
> >    the paths are not updated. Instead, this option sets/unsets
> >    the "assume unchanged" bit for the paths. When the "assume
> >    unchanged" bit is on, the user promises not to change the
> >    file and allows Git to assume that the working tree file
> >    matches what is recorded in the index. If you want to change
> >    the working tree file, you need to unset the bit to tell Git.
> >    This is sometimes helpful when working with a big project on
> >    a filesystem that has very slow lstat(2) system call (e.g.
> >    cifs).
> > 
> >    Git will fail (gracefully) in case it needs to modify this
> >    file in the index e.g. when merging in a commit; thus, in
> >    case the assumed-untracked file is changed upstream, you will
> >    need to handle the situation manually.
> > 
> 
> The whole section (including the ones above this quote) are often confused
> between the promises of the user, and the alleged promises of Git. Even in
> the quote above the "Instead" probably shouldn't be there.

I think the "Instead" is "we are not doing the usual update-index thing of reading the new data from disk; instead, we are _just_ setting the bit". Perhaps that can be spelled out more clearly, but I think just dropping "Instead" is a step backwards.

> Given the number of misrepresentations (on the web) of what the bit does,
> and the ongoing misunderstandings of users it does feel like the man page
> article could be refreshed to be more assertive about the users promise, and
> Git's cautions.

I dunno. I know this has long been a source of confusion, but I specifically dug in the docs to see what we had, and I thought what I quoted above was pretty clear. That has "only" been around for about 2 years, and is fighting against other mis-advice on the Internet, though. So I'm not sure if it is badly worded, or if people simply do not see it.

-Peff