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

[Michael J Gruber <git@drmicha.warpmail.net>]

Sérgio Basto schrieb am 09.12.2014 um 04:43:
> On Sáb, 2014-12-06 at 15:04 +0000, Philip Oakley wrote: 
>> Many users misunderstand the --assume-unchanged contract, believing
>> it means Git won't look at the flagged file.
>>
>> 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, for example, lstat(2) cycles)
>>
>> Mentioning "Git stops checking" does not help the reader, as it is
>> only one possible consequence of what that assumption allows Git to
>> do, but
>>
>>    (1) there are things other than "stop checking" that Git can do
>>        based on that assumption; and
>>    (2) Git is not obliged to stop checking; it merely is allowed to.
>>
>> Also, this is a single flag bit, correct the plural to singular, and
>> the verb, accordingly.
>>
>> Drop the stale and incorrect information about "poor-man's ignore",
>> which is not what this flag bit is about at all.
>>
>> Signed-off-by: Philip Oakley <philipoakley@iee.org>
>> ---
>>  Documentation/git-update-index.txt | 18 ++++++++----------
>>  1 file changed, 8 insertions(+), 10 deletions(-)
>>
>> diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt
>> index e0a8702..da1ccbc 100644
>> --- a/Documentation/git-update-index.txt
>> +++ b/Documentation/git-update-index.txt
>> @@ -78,20 +78,18 @@ OPTIONS
>>          Set the execute permissions on the updated files.
>>  
>>  --[no-]assume-unchanged::
>> -	When these flags are specified, the object names recorded
>> -	for the paths are not updated.  Instead, these options
>> -	set and unset the "assume unchanged" bit for the
>> -	paths.  When the "assume unchanged" bit is on, Git stops
>> -	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
>> +	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).
>>  +
>> -This option can be also used as a coarse file-level mechanism
>> -to ignore uncommitted changes in tracked files (akin to what
>> -`.gitignore` does for untracked files).
>>  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,
> 
> I don't understand why you insist that we have a contract, 

Buy setting the bit, you are making the promise to Git: "You can assume
the file is unchanged without even checking."

> when : 
> "git diff .", "git diff -a" and "git commit -a" have a different
> behavior of "git commit ." , this is not about any contract this is
> about coherency and be user friendly . 

Git does not make the promise that it will not check.

> At least if you want keep things like that, wrote in doc, clearly, that
> assume-unchanged flag *is not*, to git ignoring changes in tracked files
> and currently not ignore files for git commit <path> and may not work in
> other cases . 
> 
> Also don't understand why --assumed-untracked shouldn't deal with
> changed files instead fallback in "the user promises not to change the
> file" and sometimes works others not. 
> 
> Also if this is the contract when a file is different from commit,
> should warning the user that is not in contract (modify files that are
> assumed-untracked ) 
> 
> 
> Thanks, 
> 

git update-index is a plumbing command, not a user frontend. If you use
it and bring workdir/index into an inconsistent state it's simply the
wrong use of a plumbing tool. Things tend to break when you use a
plumbing tool incorrectly ;)

That being said, there is some wrong advice in gitignore.txt that we
should remove.

In git-update-index.txt, we could try and spell this out even more clearly:

..allows Git to assume... in the index; nonetheless Git may check the
working tree file under some circumstances.

And maybe we could specify in all man pages the category of a command,
or a warning for plumbing commands ("plumbing - use at own risk").

Michael