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

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

[Andreas Heiduk]

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

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

[Junio C Hamano]

Andreas Heiduk <asheiduk@gmail.com> writes:

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

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

For example, can we do this "empty the index" step with things like

    $ git rm --cached .

or

    $ git read-tree --empty

instead?

Thanks.

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

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

[Andreas Heiduk]

Am 10.06.2017 um 13:17 schrieb Junio C Hamano:
> 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-<.

IMO `rm .git/index` is like munging a disk block WITHOUT a binary
editor but with plain `dd seek=... skip=... count=...`, `hexdump`,
`ed` and back - every step is clear in principle but painful and
dangerous. :-)

> For example, can we do this "empty the index" step with things like
> 
>     $ git rm --cached .

That would be `git rm --cached -rq .`?

Executing this in the git repo gives me an index file with 2.1kb. I
don't know whether or not this index still contains something relevant
for this case.

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

Nice! The `index` file contains 46 bytes.

For me THAT one is like a nice binary editor apt for the job :-)
I'll queue that.

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

[Andreas Heiduk]

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

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

[Torsten Bögershausen]

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-





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

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

[Andreas Heiduk]

Am 12.06.2017 um 12:03 schrieb Torsten Bögershausen:
> 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"

Well, my patch does not document nor enhance the documentation
about EOL normalization per se.


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

Before `git worktree` the description was correct. So what about this
subject and body:

----
doc: fix location of index while normalizing EOLs

When line endings are normalized in a second worktree, a plain
`rm .git/index` does not actually delete the index. Fix the
documentation by using `git read-tree --empty` instead.
----

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

[Junio C Hamano]

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

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

[Torsten Bögershausen]

On 06/12/2017 06:06 PM, Junio C Hamano wrote:
> 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`.

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

[Junio C Hamano]

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

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

That reads well.  Thanks.

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

[PATCH v3] doc: do not use `rm .git/index` when normalizing line endings

[Andreas Heiduk]

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
from the index without touching the working tree.  The way to do this
with Git is to use `read-tree --empty`.

Signed-off-by: Andreas Heiduk <asheiduk@gmail.com>
Helped-by: Junio C Hamano <gitster@pobox.com>
Helped-by: Torsten Bögershausen <tboegi@web.de>
---
 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"
-- 
2.13.0

Re: [PATCH v3] doc: do not use `rm .git/index` when normalizing line endings

[Torsten Bögershausen]

On 14/06/17 00:15, Andreas Heiduk wrote:
Looks good to me, one minor typo below

> 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
               ^^
> from the index without touching the working tree.  The way to do this
> with Git is to use `read-tree --empty`.
[]

[PATCH v4] doc: do not use `rm .git/index` when normalizing line endings

[Andreas Heiduk]

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 of the `rm .git/index` instruction is to remove all entries
from the index without touching the working tree.  The way to do this
with Git is to use `read-tree --empty`.

Signed-off-by: Andreas Heiduk <asheiduk@gmail.com>
Helped-by: Junio C Hamano <gitster@pobox.com>
Helped-by: Torsten Bögershausen <tboegi@web.de>
---
 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"
-- 
2.13.0