[PATCH] Improve --assume-unchanged in the git update-index man page

[PATCH] Improve --assume-unchanged in the git update-index man page

[Philip Oakley]

Hi Junio, this is my quick attempt at a patch for the man page.


In $gmane/260837 the --assume-unchanged flag was reported as buggy because
of a misunderstanding about what it is being promised.

This patch looks to be more assertive in stating what promise is being made.

While at it correct a confusing pluralisation of the option.

Philip Oakley (1):
  doc: make clear --assume-unchanged's user contract

 Documentation/git-update-index.txt | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

-- 
1.9.4.msysgit.0

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

[Philip Oakley]

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, fore example, lstat(2) cycles)

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
 	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
+	paths.  When the "assume unchanged" bit is on, the user promise
+	is not to change the file, so 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
+	modifications, so when you change the working tree file you
+	need to manually 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).
-- 
1.9.4.msysgit.0

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

[Junio C Hamano]

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.

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

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

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

So here is what I came up to squash into your version when queuing
it to 'pu'.

-- >8 --
Subject: [PATCH] SQUASH???

 - Further matching of number and verb; we are talking about a single
   flag bit.

 - The bit tells Git that it can assume that the files marked as
   such are unchanged.  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.

 - Drop the stale and incorrect information about "poor-man's
   ignore", which is not this bit is about at all.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-update-index.txt | 17 +++++++----------
 1 file changed, 7 insertions(+), 10 deletions(-)

diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt
index f1f5f7f..da1ccbc 100644
--- a/Documentation/git-update-index.txt
+++ b/Documentation/git-update-index.txt
@@ -79,20 +79,17 @@ OPTIONS
 
 --[no-]assume-unchanged::
 	When this flag is 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, the user promise
-	is not to change the file, so Git stops
-	checking the working tree files for possible
-	modifications, so when you change the working tree file you
-	need to manually unset the bit to tell Git . This is
+	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,
-- 
2.2.0-155-g395db3e