Re: [PATCH] doc: core.ignoreStat clarify the --assume-unchanged effect
From: "Johannes Schindelin" <Johannes.Schindelin@gmx.de> Friday,
December 12, 2014 10:56 AM
Show 34 quoted lines
> Hi Philip,
>
> On Thu, 11 Dec 2014, Philip Oakley wrote:
>
>> diff --git a/Documentation/config.txt b/Documentation/config.txt
>> index c26a7c8..81570b7 100644
>> --- a/Documentation/config.txt
>> +++ b/Documentation/config.txt
>> @@ -354,10 +354,11 @@ proxy use, while defaulting to a common proxy
>> for external domains.
>> core.ignoreStat::
>> If true, commands which modify both the working tree and the index
>> will mark the updated paths with the "assume unchanged" bit in the
>> - index. These marked files are then assumed to stay unchanged in the
>> - working tree, until you mark them otherwise manually - Git will not
>> - detect the file changes by lstat() calls. This is useful on systems
>> - where those are very slow, such as Microsoft Windows.
>> + index. These marked files are then expected to stay unchanged in
>> the
>> + working tree. If you change them you should mark their update
>> manually.
>> + Git will normally not detect the file changes by lstat() calls.
>> + This is useful on systems where those calls are very slow, such as
>> + cifs/Microsoft Windows.
>> See linkgit:git-update-index[1].
>> False by default.
>
> I think that the new wording is better, but still can be
> misunderstood.
> How about this instead:
>
> -- snip --
> core.ignoreStat::
> If true, Git will not try to detect when files were modified.
"not _normally_ try"? - is there a guarantee that ignoreStat will
switch off ALL checks?
Is there a list of those commands which will, implicitly, check?
> When Git commands are used to modify files, Git will know that
> they were modified, but when files are modified outside of Git,
+ e.g. by the user, external SDK or other tools,
> the user will need to stage the modified files explicitly; they
> will not be reported as changed e.g. by linkgit:git-status[1].
The git-status man page give no indication either way as to the effect of this ignoreStat or the --assume-unchanged flags (or --skip-worktree). User expectations can go either way.
I was thinking I'd need to reference 'git update-index --really-refresh <file>' (but filenames beginning with . are discarded, so no '--all' equivalence !)
Show 10 quoted lines
> +
> This is useful on systems where lstat() calls are very slow, such as
> CIFS/Microsoft Windows.
> See linkgit:git-update-index[1].
> False by default.
> -- snap --
>
> In other words, I would try to skip the "assume unchanged" flag
> altogether, it is prone to confuse readers unfamiliar with the inner
> workings of the index.
It's certainly confused many, to the point that the false information has become the accepted truth.
I'll take on board most of the suggestions.
This documenation clarification problem (users asking "how to temporarily mark files such that git will ignore their changes" getting confused) has grown arms and legs. In Duy's code fix, I see a repeated pattern that should have a macro; If only there was a good name for what it means (ce->ce_flags & (CE_VALID | CE_SKIP_WORKTREE)), which extends ce_skip_worktree(ce).
Longer term I'm also looking for a method for the situation that would indicate that the local repo)doesn't even have a copy of 'that sha1' blob or tree (in the same way as a submodule sha1s) so that one can do a narrow clone/fetch for privacy/security reasons.
-- Philip
Philip Oakley