@matheusbsbs / matheus-bagliano / commits / ccadb25f73

doc: make clear --assume-unchanged's user contract

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> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Philip Oakley committed Dec 6, 2014 at 15:04 UTC ccadb25f730de775660c82695c5fcf9169f0aae7
1 file changed +8 -10
Documentation/git-update-index.txt
+8 -10
@@ -78,20 +78,18 @@ OPTIONS
78 Set the execute permissions on the updated files.
79
80 --[no-]assume-unchanged::
81 - When these flags are specified, the object names recorded
82 - for the paths are not updated. Instead, these options
83 - set and unset the "assume unchanged" bit for the
84 - paths. When the "assume unchanged" bit is on, Git stops
85 - checking the working tree files for possible
86 - modifications, so you need to manually unset the bit to
87 - tell Git when you change the working tree file. This is
81 + When this flag is specified, the object names recorded
82 + for the paths are not updated. Instead, this option
83 + sets/unsets the "assume unchanged" bit for the
84 + paths. When the "assume unchanged" bit is on, the user
85 + promises not to change the file and allows Git to assume
86 + that the working tree file matches what is recorded in
87 + the index. If you want to change the working tree file,
88 + you need to unset the bit to tell Git. This is
89 sometimes helpful when working with a big project on a
90 filesystem that has very slow lstat(2) system call
91 (e.g. cifs).
92 +
92 -This option can be also used as a coarse file-level mechanism
93 -to ignore uncommitted changes in tracked files (akin to what
94 -`.gitignore` does for untracked files).
93 Git will fail (gracefully) in case it needs to modify this file
94 in the index e.g. when merging in a commit;
95 thus, in case the assumed-untracked file is changed upstream,