Re: Git issue

From: Junio C Hamano <gitster@pobox.com>
Date: Nov 1, 2016, 21:23 UTC
Message-ID: <xmqq8tt2opw0.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <20161101210310.sqrhvviry7iyyjrm@sigill.intra.peff.net>

Jeff King <peff@peff.net> writes:

Show 13 quoted lines

> On Tue, Nov 01, 2016 at 08:50:23PM -0000, Philip Oakley wrote:
>
>> > 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. ...
>
> 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.

I tend to agree; the biggest problem with this part of the description I think is that it starts by saying what it does not do, which may help people who expect the command to do its usual thing but otherwise is a secondary information. How about ripping it out and moving it after the primary description, i.e.

	Set or unset the "assume unchanged" bit for the paths,
	without changing the object names recorded for them, in the
	index.

Show 11 quoted lines

>> 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.

I share the same reaction, and I find that the update in ccadb25f73 ("doc: make clear --assume-unchanged's user contract", 2014-12-06) that introduced the "the user promises not to change and allows Git to assume" is sufficiently clear.