patchdoc: fix location of index in worktree scenatio

> When setting `.gitattributes` in a second worktree, a plain `rm .git/index`
> does not actually delete the index.
>
> Signed-off-by: Andreas Heiduk <asheiduk@gmail.com>
> ---
>  Documentation/gitattributes.txt | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)

> diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
> index 473648386..4c6b74fa6 100644
> --- a/Documentation/gitattributes.txt
> +++ b/Documentation/gitattributes.txt
> @@ -229,7 +229,7 @@ From a clean working directory:
>  
>  -------------------------------------------------
>  $ echo "* text=auto" >.gitattributes
> -$ rm .git/index     # Remove the index to re-scan the working directory
> +$ rm "$(git rev-parse --git-path index)"  # Remove the index to re-scan the working directory
>  $ git add .
>  $ git status        # Show files that will be normalized
>  $ git commit -m "Introduce end-of-line normalization"

> Andreas Heiduk <asheiduk@gmail.com> writes:
> 
>> When setting `.gitattributes` in a second worktree, a plain `rm .git/index`
>> does not actually delete the index.
>>

> Right.  
> 
> I however have to wonder if we can do the same without futzing
> directly with the "index" file as a filesystem entity.  With or
> without your update, what is taught in the document feels like
> munging a disk block with binary editor to correct a corrupted
> filesystem X-<.

> or
> 
>     $ git read-tree --empty
> 
> instead?

> 
> Signed-off-by: Andreas Heiduk <asheiduk@gmail.com>
> Helped-by: Junio C Hamano <gitster@pobox.com>
> ---
>   Documentation/gitattributes.txt | 2 +-
>   1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
> index 473648386..2a2d7e2a4 100644
> --- a/Documentation/gitattributes.txt
> +++ b/Documentation/gitattributes.txt
> @@ -229,7 +229,7 @@ From a clean working directory:
>   
>   -------------------------------------------------
>   $ echo "* text=auto" >.gitattributes
> -$ rm .git/index     # Remove the index to re-scan the working directory
> +$ git read-tree --empty   # Clean index, force re-scan of working directory
>   $ git add .
>   $ git status        # Show files that will be normalized
>   $ git commit -m "Introduce end-of-line normalization"
> 

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

> On 10/06/17 19:38, Andreas Heiduk wrote:
>> When setting `.gitattributes` in a second worktree, a plain `rm
>> .git/index`
>> does not actually delete the index.
> This feels somewhat short. setting .gitattributes is (in general)
> independent of the index.
> In normalizing line endings case the user needs to do both, fix
> attribiutes, and re-read the work tree, discarding the index.
> 
> How about this:
> 
> When line endings are normalized in a second worktree, a plain `rm
> .git/index`
> does not actually delete the index.
> Fix a long standing bug in the documentaton and use "git read-tree
> --empty" instead-

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

> 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).
>

>
> 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`.

> 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 mess around with the internal
>     implementation of Git using raw file system tools like `rm`.
> 
>   - Within a submodule or an additional working tree `.git` is just a
>     file containing a `gitdir: <path>` pointer into the real `.git`
>     directory.  Therefore `rm .git/index` does not work.
> 
> The purpose or `rm .git/index` instruction is to remove all entries