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

From: Johannes Schindelin <johannes.schindelin@gmx.de>
Date: Dec 12, 2014, 10:56 UTC
Message-ID: <alpine.DEB.1.00.1412121149040.13845@s15462909.onlinehome-server.info>
In-Reply-To: <1418341733-1656-2-git-send-email-philipoakley@iee.org>

Hi Philip,

On Thu, 11 Dec 2014, Philip Oakley wrote:

Show 19 quoted lines

> 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