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

[Thomas Rast <trast@student.ethz.ch>]

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.

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

Signed-off-by: Thomas Rast <trast@student.ethz.ch>
---

Ron, please don't drop the Cc lists, it's customary around here to Cc
everyone involved so far.

On Wednesday 03 February 2010 21:34:05 you wrote:
> In article <4B69D897.2060908@pcharlan.com>,
>  Pete Harlan <pgit@pcharlan.com> wrote:
> > Unlike "git rm", "git mv" could still perform the operation even without
> > "-f", but the semantics of "git mv" differ enough from plain "mv" that a
> > short blurb from Git in that case might help.
> 
> I think that a simple tweak to the docs would be enough.  Right now it 
> says:
> 
> "The index is updated after successful completion, but the change must 
> still be committed."
> 
> I'm pretty sure I would have been less confused if it had said something 
> like:
> 
> "The index is updated to reflect the new name of the file, but NOT any 
> new content that file may contain.  Changed content must be added to the 
> index separately with git add, and all changes must still be commited."

How about this change instead, which formulates it in terms of what
does happen, instead of what does not.

BTW, I'm wondering whether the "move or rename" distinction is really
worth it.  Does the user care?  I always figured it was a technical
detail whether rename() works or you actually need to move anything.


 Documentation/git-mv.txt |   14 +++++++-------
 1 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt
index bdcb585..eff11b7 100644
--- a/Documentation/git-mv.txt
+++ b/Documentation/git-mv.txt
@@ -8,22 +8,22 @@ git-mv - Move or rename a file, a directory, or a symlink
 
 SYNOPSIS
 --------
-'git mv' <options>... <args>...
+'git mv' [-f] [-n] <source> <destination>
+'git mv' [-f] [-n] [-k] <source>... <destination directory>
 
 DESCRIPTION
 -----------
-This script is used to move or rename a file, directory or symlink.
-
- git mv [-f] [-n] <source> <destination>
- git mv [-f] [-n] [-k] <source> ... <destination directory>
+'git-mv' renames files, directories, and symlinks in worktree and
+index.
 
 In the first form, it renames <source>, which must exist and be either
 a file, symlink or directory, to <destination>.
 In the second form, the last argument has to be an existing
 directory; the given sources will be moved into this directory.
 
-The index is updated after successful completion, but the change must still be
-committed.
+For every renamed file or symlink, the worktree and index contents are
+renamed separately, preserving both staged and unstaged changes.  You
+will still have to commit the rename.
 
 OPTIONS
 -------
-- 
1.7.0.rc1.166.g7cae7