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

From: Philip Oakley <philipoakley@iee.org>
Date: Jan 9, 2015, 08:44 UTC
Message-ID: <1ED88DC1DCC2463782B4F4167DC85D5D@PhilipOakley>
In-Reply-To: <xmqqbnmajwd9.fsf@gitster.dls.corp.google.com>

From: "Junio C Hamano" <gitster@pobox.com>

Show 49 quoted lines

> 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.
>>
>> 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.
>>
>> Signed-off-by: Philip Oakley <philipoakley@iee.org>
>> ---
>>
>> This is the corrected patch which now applies on top of next and has 
>> been
>> checked on AsciiDoc. (was $gmane/261974/focus=262022)
>>
>> I have included the previous 'after three-dashes' comment and 
>> included
>> them in the commit message. I'm happy for it to be tweaked as 
>> appropriate.
>
> Thanks.
>
>> diff --git a/Documentation/config.txt b/Documentation/config.txt
>> index 52eeadd..fe179d0 100644
>> --- a/Documentation/config.txt
>> +++ b/Documentation/config.txt
>> @@ -375,15 +375,18 @@ 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, 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.
>
> I wonder if this is better stated in two seemingly independent
> sentences (like your version), or "... if files have changed by
> setting the assume-unchanged bit ...." to clarify where the setting
> of the bits to these files come into the big picture, but it is
> minor.  Either way, I think it is a lot easier to understand than
> what we have in 'master'.

I had considered a number of different wordings, and wanted to keep the tricky parts separate to ease cognition.

On a separte note, this patch was a development from the problem noticed by Sérgio of the different actions of 'git commit .'and 'git commit -a' when --assume-unchanged was used. Did you have any thoughts regarding Duy's patch (05 December 2014 10:56) to his code given in $gmane/260865.

I wasn't sure if it had just been missed, or if there was some other issue?

Show 15 quoted lines

>> ++
>> +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.
>
> I think you are trying to make the result more readable by using
> separate paragraphs for separate conceptual points, but then isn't
> it wrong to have "False by default" as part of stating which
> platforms are intended targets?  I wonder if we want to have that
> last line as its own paragraph instead.

I was happy with it being a simple separate sentence.

Show 7 quoted lines

>
> Thanks.
>
>>
>>  core.preferSymlinkRefs::
>>  Instead of the default "symref" format for HEAD
> --

Philip