[PATCH v2] doc: core.ignoreStat update, and clarify the --assume-unchanged effect

[PATCH v2] doc: core.ignoreStat update, and clarify the --assume-unchanged effect

[Philip Oakley]

The assume-unchanged bit, and consequently core.ignoreStat, can be
misunderstood. Be assertive about the expectation that file changes should
notified to Git.

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
Overhaul the general wording thus:
    1. direct description of what is ignored given first.
    2. example instruction of the user manual action required.
    3. use sideways indirection for assume-unchanged and update-index references.
    4. add a 'normally' to give leeway for the change detection.

This version is on top of the current master, and replaces the patch in next.
---
 Documentation/config.txt | 18 +++++++++++-------
 1 file changed, 11 insertions(+), 7 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 6862e3e..32e42dd 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -375,13 +375,17 @@ This is useful for excluding servers inside a firewall from
 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.
-	See linkgit:git-update-index[1].
+	If true, Git will avoid using lstat() calls to detect if files have
+	changed. Git will set the "assume-unchanged" bit for those tracked files
+	which it has updated identically in both the index and working tree.
++
+	When files are modified outside of Git, the user will need to stage
+	the modified files explicitly (e.g. see 'Examples' section in
+	linkgit:git-update-index[1]).
+	Git will not normally detect changes to those files.
++
+	This is useful on systems where lstat() calls are very slow, such as
+	CIFS/Microsoft Windows.
 	False by default.
 
 core.preferSymlinkRefs::
-- 
1.9.5.msysgit.0

Re: [PATCH v2] doc: core.ignoreStat update, and clarify the --assume-unchanged effect

[Junio C Hamano]

Philip Oakley <philipoakley@iee.org> writes:

> The assume-unchanged bit, and consequently core.ignoreStat, can be
> misunderstood. Be assertive about the expectation that file changes should
> notified to Git.
>
> Signed-off-by: Philip Oakley <philipoakley@iee.org>
> ---
> Overhaul the general wording thus:
>     1. direct description of what is ignored given first.
>     2. example instruction of the user manual action required.
>     3. use sideways indirection for assume-unchanged and update-index references.
>     4. add a 'normally' to give leeway for the change detection.
>
> This version is on top of the current master, and replaces the patch in next.

Sorry, you do not replace anything in 'next', once it is in.

I was about to say that I'll try to see if I turn it into
incremental (at which point some of the above four points after the
three-dash line might want to be in the log message proper), but the
AsciiDoc mark-up looks somewhat suspect (we usually do not see
indentation in the paragraphs continued with "+").  Does this format
fine for manpage and HTML?

Thanks.

> ---
>  Documentation/config.txt | 18 +++++++++++-------
>  1 file changed, 11 insertions(+), 7 deletions(-)
>
> diff --git a/Documentation/config.txt b/Documentation/config.txt
> index 6862e3e..32e42dd 100644
> --- a/Documentation/config.txt
> +++ b/Documentation/config.txt
> @@ -375,13 +375,17 @@ This is useful for excluding servers inside a firewall from
>  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.
> -	See linkgit:git-update-index[1].
> +	If true, Git will avoid using lstat() calls to detect if files have
> +	changed. Git will set the "assume-unchanged" bit for those tracked files
> +	which it has updated identically in both the index and working tree.
> ++
> +	When files are modified outside of Git, the user will need to stage
> +	the modified files explicitly (e.g. see 'Examples' section in
> +	linkgit:git-update-index[1]).
> +	Git will not normally detect changes to those files.
> ++
> +	This is useful on systems where lstat() calls are very slow, such as
> +	CIFS/Microsoft Windows.
>  	False by default.
>  
>  core.preferSymlinkRefs::

Re: [PATCH v2] doc: core.ignoreStat update, and clarify the --assume-unchanged effect

[Philip Oakley]

From: "Junio C Hamano" <gitster@pobox.com>
> Philip Oakley <philipoakley@iee.org> writes:
>
>> The assume-unchanged bit, and consequently core.ignoreStat, can be
>> misunderstood. Be assertive about the expectation that file changes 
>> should
>> notified to Git.
>>
>> Signed-off-by: Philip Oakley <philipoakley@iee.org>
>> ---
>> Overhaul the general wording thus:
>>     1. direct description of what is ignored given first.
>>     2. example instruction of the user manual action required.
>>     3. use sideways indirection for assume-unchanged and update-index 
>> references.
>>     4. add a 'normally' to give leeway for the change detection.
>>
>> This version is on top of the current master, and replaces the patch 
>> in next.
>
> Sorry, you do not replace anything in 'next', once it is in.

My apologies. I'd been too quick to read the 'expecting reroll' to 
properly notice the promotion to next.
>
> I was about to say that I'll try to see if I turn it into
> incremental (at which point some of the above four points after the
> three-dash line might want to be in the log message proper), but the
> AsciiDoc mark-up looks somewhat suspect (we usually do not see
> indentation in the paragraphs continued with "+").  Does this format
> fine for manpage and HTML?

I didn't have access to AsciiDoc at the time.

You are right, it doesn't format correctly, I shouldn't have continued 
with the indentation tabs in the continuation paragraphs. My mistake. I 
can re-roll if that's easiest

>
> Thanks.
>
>> ---
>>  Documentation/config.txt | 18 +++++++++++-------
>>  1 file changed, 11 insertions(+), 7 deletions(-)
>>
>> diff --git a/Documentation/config.txt b/Documentation/config.txt
>> index 6862e3e..32e42dd 100644
>> --- a/Documentation/config.txt
>> +++ b/Documentation/config.txt
>> @@ -375,13 +375,17 @@ This is useful for excluding servers inside a 
>> firewall from
>>  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.
>> - See linkgit:git-update-index[1].
>> + If true, Git will avoid using lstat() calls to detect if files have
>> + changed. Git will set the "assume-unchanged" bit for those tracked 
>> files
>> + which it has updated identically in both the index and working 
>> tree.
>> ++
>> + When files are modified outside of Git, the user will need to stage
>> + the modified files explicitly (e.g. see 'Examples' section in
>> + linkgit:git-update-index[1]).
>> + Git will not normally detect changes to those files.
>> ++
>> + This is useful on systems where lstat() calls are very slow, such 
>> as
>> + CIFS/Microsoft Windows.
>>  False by default.
>>
>>  core.preferSymlinkRefs::
> --


Philip