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

["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, 
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 ) 


Thanks, 
-- 
Sérgio M. B.