patchImprove --assume-unchanged in the git update-index man page

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

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

Philip Oakley <philipoakley@iee.org> writes:

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.

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.

Thanks.  We are talking about a single flag bit.

"this option sets/unsets"?

"the user promises not to".

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

Thanks.

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

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