Re: [PATCH v2] doc: fix location of index in worktree scenatio

From: Torsten Bögershausen <tboegi@web.de>
Date: Jun 13, 2017, 04:29 UTC
Message-ID: <04ad4189-8575-2f0f-2c99-c98672513293@web.de>
In-Reply-To: <xmqqfuf5p4wk.fsf@gitster.mtv.corp.google.com>

On 06/12/2017 06:06 PM, Junio C Hamano wrote:

Show 49 quoted lines

> Torsten Bögershausen <tboegi@web.de> writes:
>
>> Thanks for working on this (and keeping me in cc)
>>
>> The commit head line does not fully match my expactions:
>> "doc: fix location of index in worktree scenatio"
>> "doc:" is OK, but is the "location of index" fixed ?
>> Actually something that includes the important stuff:
>>
>> "doc"
>> "fix"
>> "normalize the line endings"
>> "worktree scenatio"
>>
>> could be more helpful.
>>
>> How about this as a header for the commit:
>> "doc: normalize the line endings in a worktree scenatio"
> Andreas's patch does not "normalize" anything, though.
>
>      doc: do not encourage `rm .git/index` in an example
>
>      When illustrating how to force normalizing the line endings,
>      gitattributes documentation tells the user to `rm .git/index`.
>
>      This is incorrect for two reasons.  We shouldn't be encouraging
>      users to futz with the internal implementation of Git using raw
>      filesystem tools like "rm" too much.  Also, when ".git" is not a
>      directory but a "gitfile" pointing at the real location of the
>      real ".git" directory, `rm .git/index` would not work anyway.
>
>      The point of the step in the illustration is to remove all
>      entries from the index without touching the working tree, and
>      the way to do it with Git is to use `read-tree --empty`.
>
> perhaps?
>
> You _could_ mention "worktree scenario" but that is not the sole
> user of the gitfile facility (e.g. a submodule working tree also
> uses ".git" that is a gitfile pointing at the real repository
> location), and "worktree" is not the real root cause of the problem
> ("gitfile" is), so I do not think it is essential to do so.  If we
> really want to, we can add to the second from the paragraph
> something like this:
>
>      ... would not work anyway (the use of ".git" that is "gitfile"
>      is often seen in a secondary working tree managed by "git
>      worktree" and in a working tree of a submodule).
>

That's better ... here is my attempt to improve

doc: do not use `rm .git/index` when normalizing line endings

     When illustrating how to normalize the line endings, the
     documentation in gitattributes tells the user to `rm .git/index`.

     This is incorrect for two reasons.  Users shouldn't be instructed
     to futz with the internal implementation of Git using raw
     file system tools like "rm".
     Second, when submodules or second working trees are used, ".git"
     is a not a directory but a "gitfile" pointing at the location of the
     real ".git" directory, `rm .git/index` does not work.

     The point of the step in the illustration is to remove all
     entries from the index without touching the working tree, and
     the way to do it with Git is to use `read-tree --empty`.