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

From: Philip Oakley <philipoakley@iee.org>
Date: Dec 6, 2014, 15:04 UTC
Message-ID: <1417878270-4364-2-git-send-email-philipoakley@iee.org>
In-Reply-To: <1417878270-4364-1-git-send-email-philipoakley@iee.org>

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,

-- 
1.9.4.msysgit.0