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

From

Junio C Hamano <gitster@pobox.com>

Date

Dec 5, 2014, 23:32 UTC

Message-ID

<xmqqbnnhoepz.fsf@gitster.dls.corp.google.com>

In-Reply-To

<xmqqtx19ogn9.fsf@gitster.dls.corp.google.com>

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

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