Re: [PATCH] doc: make clear --assume-unchanged's user contract

[Junio C Hamano <gitster@pobox.com>]

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.

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

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