On Sáb, 2014-12-06 at 15:04 +0000, Philip Oakley wrote: > 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@xxxxxxx> > --- > 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, I don't understand why you insist that we have a contract, when : "git diff .", "git diff -a" and "git commit -a" have a different behavior of "git commit ." , this is not about any contract this is about coherency and be user friendly . At least if you want keep things like that, wrote in doc, clearly, that assume-unchanged flag *is not*, to git ignoring changes in tracked files and currently not ignore files for git commit <path> and may not work in other cases . Also don't understand why --assumed-untracked shouldn't deal with changed files instead fallback in "the user promises not to change the file" and sometimes works others not. Also if this is the contract when a file is different from commit, should warning the user that is not in contract (modify files that are assumed-untracked ) Thanks, -- Sérgio M. B. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html