Re: [PATCH] Documentation: clarify git-mv behaviour wrt dirty files

Thomas Rast [off-list ref] writes:

Clearly point out that the rename happens separately for worktree and
index.  This confused users, as they are apparently told that git-mv
== git-rm && mv && git-add, which it is not.

I may be confused too as I had to read these three lines three times and I
do not think these two sentences mesh well together.

What happens with "git mv A B" is that it moves a work tree file A to B
and moves the index entry for A to B, hence all of:

 (1) the fact that you do not have A anymore;

 (2) the fact that you now have B instead; and

 (3) the fact that your work tree file B (which used to be A) has changes
     from its corresponding index entry

are _consistently_ kept between the work tree and the index.

I don't think "happens separately for" makes sense.  At best, it is an
implementation detail that doesn't help users understand what the command
does and what it is used for better.

Of course, it is different from

    "git rm -f --cached A && mv A B && git add B"

which would add changes that you were not prepared to add (i.e. you had
output from "git diff A" before you started).  I think that was a buggy
way old scripted version of "git mv" used to work, by the way.

While there, move the synposis to the synopsis section, which so far
was rather useless, and reword the first sentence to eliminate the
mentions of 'script'.

That's a good change regardless.

+For every renamed file or symlink, the worktree and index contents are
+renamed separately, preserving both staged and unstaged changes....

I'd just say:

    While renaming paths, changes in the files in the work tree that you
    have not added are preserved.

+....  You
+will still have to commit the rename.

I don't understand why you want to say "You will still have to commit the
rename" here.  It is like saying in "git add" manpage that "You will still
have to commit the added contents" because "add" only affects the index
and does not make a commit.  Drop it.