[PATCH] core.ignoreStat is affected by --assume-unchanged misunderstandings

[PATCH] core.ignoreStat is affected by --assume-unchanged misunderstandings

[Philip Oakley]

A recent thread on the Msysgit mailing list 
https://groups.google.com/forum/#!topic/msysgit/d9CltDxx11g noted the
config core.ignoreStat flag as a solution to slow performance on
Windows 8.1 for their system.

This config flag uses the --assume-unchanged flag to speed up systems
with slow lstat(2) calls. Just like the regular --assume-changed
documentation, this need some tweaking to be clear that it is not a
"poor man's .gitignore".

Philip Oakley (1):
  doc: core.ignoreStat clarify the --assume-unchanged effect

 Documentation/config.txt | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

-- 
1.9.4.msysgit.0

[PATCH] doc: core.ignoreStat clarify the --assume-unchanged effect

[Philip Oakley]

The assume-unchanged bit can be misunderstood. Be assertive about
the expectation that file changes should update that flag.

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 Documentation/config.txt | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

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.
 
-- 
1.9.4.msysgit.0

Re: [PATCH] doc: core.ignoreStat clarify the --assume-unchanged effect

[Johannes Schindelin]

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.
	When Git commands are used to modify files, Git will know that
	they were modified, but when files are modified outside of Git,
	the user will need to stage the modified files explicitly; they
	will not be reported as changed e.g. by linkgit:git-status[1].
+
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.

Ciao,
Dscho

Re: [PATCH] doc: core.ignoreStat clarify the --assume-unchanged effect

[Philip Oakley]

From: "Johannes Schindelin" <Johannes.Schindelin@gmx.de>  Friday, 
December 12, 2014 10:56 AM
> 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 !)

> +
> 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