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

["Philip Oakley" <philipoakley@iee.org>]

From: "Sérgio Basto" <sergio@serjux.com>
> 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,

The misunderstanding (which even I had until recently), was the same as 
your misunderstanding, and is also repeated (wrongly) in the 
documentation that the flag is about ignoring changes to files.

That is completely wrong, and not why the flag was invented (as I 
understand it).

The flag was invented because Git bran very slowly on some file systems 
(e.g. cifs lstat(2) system calls) to the point that it was deemed 
unacceptable. The solution was to tell git to stop doing those lstat 
calls because the user had flagged it's unchanged nature.

The problem was then that, as a side effect, in the main, Git wouldn't 
notice any changes to such marked files (but some commands do notice;-) 
so some people used it as a "poor man's ignore" flag, and that 
misinformation stuck. Unfortunately you have been caught in that trap.

While many seek code (change) based solutions, I see clearer 
documentation (especially for the intermediate rather than expert users) 
as a good first step. People do read the documentation, though often in 
retrospect, so my patch seeks to clarify the existing situation. That is 
"please git, update the index, you can assume these files are 
unchanged".

Another thread has pointed out that the misunderstanding as also 
repeated on another page, so I'll need to see if a patch is forthcoming 
for that!

> 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 .
>
> 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 )
>
I hope my explanation helps in explaining how we have come to this 
perhaps unhelpful situation.
--
Philip