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

From: Junio C Hamano <gitster@pobox.com>
Date: Jun 12, 2017, 16:06 UTC
Message-ID: <xmqqfuf5p4wk.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <b4906d3f-7e4d-f4dc-dc39-7eac5da8292d@web.de>

Torsten Bögershausen <tboegi@web.de> writes:

Show 16 quoted lines

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