Re: [PATCH] doc: make clear --assume-unchanged's user contract
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Dec 5, 2014, 22:50 UTC
- Message-ID
- <xmqqtx19ogn9.fsf@gitster.dls.corp.google.com>
- In-Reply-To
- <1417818117-368-2-git-send-email-philipoakley@iee.org>
Philip Oakley <philipoakley@iee.org> writes:
> Many users misunderstand the --assume-unchanged contract, believing > it means Git won't look at the flagged file.
Yeah, I suspect that many of them come from how-tos floating on the 'net (e.g. stackoverflow) that are misguided or outright incorrect. I've stopped correcting people who advise "you can flip this bit and squelch your changes from appearing in diffs" number of years ago.
> Be explicit that the --assume-unchanged contract is by the user that > they will NOT change the file so that Git does not need to look (and > expend, fore example, lstat(2) cycles)
Yes, but "so that Git does not ..." part is already very clear in the existing part of the document. Stressing that this is the user making a promise to help Git help the user is indeed a good idea.
Show 15 quoted lines
> Signed-off-by: Philip Oakley <philipoakley@iee.org> > --- > Documentation/git-update-index.txt | 9 +++++---- > 1 file changed, 5 insertions(+), 4 deletions(-) > > diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt > index 929869b..c045509 100644 > --- a/Documentation/git-update-index.txt > +++ b/Documentation/git-update-index.txt > @@ -82,13 +82,14 @@ OPTIONS > Set the execute permissions on the updated files. > > --[no-]assume-unchanged:: > - When these flags are specified, the object names recorded > + When this flag is specified, the object names recorded
Thanks. We are talking about a single flag bit.
> for the paths are not updated. Instead, these options > set and unset the "assume unchanged" bit for the
"this option sets/unsets"?
> - paths. When the "assume unchanged" bit is on, Git stops > + paths. When the "assume unchanged" bit is on, the user promise > + is not to change the file, so Git stops
"the user promises not to".
Show 5 quoted lines
> checking the working tree files for possible > - modifications, so you need to manually unset the bit to > - tell Git when you change the working tree file. This is > + modifications, so when you change the working tree file you > + need to manually unset the bit to tell Git . This is
This reads much better than the original, but you may want to go a bit further. How about removing the original a bit more, like so:
... 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).
Thanks.