From: "Sérgio Basto" <sergio@xxxxxxxxxx>
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,
The misunderstanding (which even I had until recently), was the same as
your misunderstanding, and is also repeated (wrongly) in the
documentation that the flag is about ignoring changes to files.
That is completely wrong, and not why the flag was invented (as I
understand it).
The flag was invented because Git bran very slowly on some file systems
(e.g. cifs lstat(2) system calls) to the point that it was deemed
unacceptable. The solution was to tell git to stop doing those lstat
calls because the user had flagged it's unchanged nature.
The problem was then that, as a side effect, in the main, Git wouldn't
notice any changes to such marked files (but some commands do notice;-)
so some people used it as a "poor man's ignore" flag, and that
misinformation stuck. Unfortunately you have been caught in that trap.
While many seek code (change) based solutions, I see clearer
documentation (especially for the intermediate rather than expert users)
as a good first step. People do read the documentation, though often in
retrospect, so my patch seeks to clarify the existing situation. That is
"please git, update the index, you can assume these files are
unchanged".
Another thread has pointed out that the misunderstanding as also
repeated on another page, so I'll need to see if a patch is forthcoming
for that!
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 )
I hope my explanation helps in explaining how we have come to this
perhaps unhelpful situation.
--
Philip
--
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