413

From what I understand, Git doesn't really need to track file rename/move/copy operations, so what's the real purpose of git mv? The man page isn't particularly descriptive...

Is it obsolete? Is it an internal command, not meant to be used by regular users?

8 Answers 8

548
git mv oldname newname

is just shorthand for:

mv oldname newname
git add newname
git rm oldname

i.e. it updates the index for both old and new paths automatically.

12
  • 56
    Also it has a few safeties built in. Commented Jul 8, 2009 at 0:16
  • 11
    Thanks @CharlesBailey - Does git then consider the files newNameFile and oldNameFile as different? If yes, what happens if we want to merge them? Say we branch an ant project on branch A and create Branch B then mavenize projects on B. The file names are the same but put on different paths as the project structure changed. Say both branches grew for some time in parallel. At some point if we want to merge the projects how will git know that it's the same file just renamed it's path? (if "git mv" == "git add + git rm")
    – Rose
    Commented Dec 27, 2012 at 0:22
  • 7
    @SergeyOrshanskiy If auto detection goes wrong for mv oldname newname; git add newname; git rm oldname, it will also go wrong for git mv oldname newname (see this answer).
    – Ajedi32
    Commented Jun 11, 2014 at 21:28
  • 12
    Note that git mv is slightly different from the mv oldname newname; git add newname; git rm oldname, in that if you made changes to the file before git mving it, those changes won't be staged until you git add the new file.
    – Ajedi32
    Commented Jun 11, 2014 at 21:31
  • 5
    git mv is doing something different, as it handles changes in filename case (foo.txt to Foo.txt) while those commands run individually do not (on OSX) Commented Sep 2, 2016 at 19:37
99

From the official GitFaq:

Git has a rename command git mv, but that is just a convenience. The effect is indistinguishable from removing the file and adding another with different name and the same content

7
  • 19
    So do you loose the file history? I was presume rename would keep the old history for that directory... Commented Apr 12, 2013 at 9:52
  • 25
    Well, yes and no. Read the official GitFaq link above about renames, and then read Linus Torvalds lengthy e-mail about why he doesn't like the notion of an SCM tool tracking files: permalink.gmane.org/gmane.comp.version-control.git/217 Commented May 7, 2013 at 15:05
  • 5
    @WillHancock I have used git a bit more now, and can answer you more definitively: depending on your git client and its options, you will be able to trace the file past the rename if the file changed internally little enough that it considers it a rename. If you change the file too much AND rename it though, git won't detect it - in a sense it is saying "no, you might as well consider that a completely different file!" Commented Mar 6, 2015 at 22:09
  • 13
    @AdamNofsinger that link is dead. Here's a mirror: web.archive.org/web/20150209075907/http://…
    – Carl Walsh
    Commented Nov 14, 2017 at 7:33
  • 6
    A better mirror that doesn't stress the Archive.org as much : lore.kernel.org/git/…
    – Milind R
    Commented Dec 10, 2021 at 5:42
48

Git is just trying to guess for you what you are trying to do. It is making every attempt to preserve unbroken history. Of course, it is not perfect. So git mv allows you to be explicit with your intention and to avoid some errors.

Consider this example. Starting with an empty repo,

git init
echo "First" >a
echo "Second" >b
git add *
git commit -m "initial commit"
mv a c
mv b a
git status

Result:

# On branch master
# Changes not staged for commit:
#   (use "git add/rm <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#   modified:   a
#   deleted:    b
#
# Untracked files:
#   (use "git add <file>..." to include in what will be committed)
#
#   c
no changes added to commit (use "git add" and/or "git commit -a")

Autodetection failed :( Or did it?

$ git add *
$ git commit -m "change"
$ git log c

commit 0c5425be1121c20cc45df04734398dfbac689c39
Author: Sergey Orshanskiy <*****@gmail.com>
Date:   Sat Oct 12 00:24:56 2013 -0400

    change

and then

$ git log --follow c

Author: Sergey Orshanskiy <*****@gmail.com>
Date:   Sat Oct 12 00:24:56 2013 -0400

    change

commit 50c2a4604a27be2a1f4b95399d5e0f96c3dbf70a
Author: Sergey Orshanskiy <*****@gmail.com>
Date:   Sat Oct 12 00:24:45 2013 -0400

    initial commit

Now try instead (remember to delete the .git folder when experimenting):

git init
echo "First" >a
echo "Second" >b
git add *
git commit -m "initial commit"
git mv a c
git status

So far so good:

# On branch master
# Changes to be committed:
#   (use "git reset HEAD <file>..." to unstage)
#
#   renamed:    a -> c


git mv b a
git status

Now, nobody is perfect:

# On branch master
# Changes to be committed:
#   (use "git reset HEAD <file>..." to unstage)
#
#   modified:   a
#   deleted:    b
#   new file:   c
#

Really? But of course...

git add *
git commit -m "change"
git log c
git log --follow c

...and the result is the same as above: only --follow shows the full history.


Now, be careful with renaming, as either option can still produce weird effects. Example:

git init
echo "First" >a
git add a
git commit -m "initial a"
echo "Second" >b
git add b
git commit -m "initial b"

git mv a c
git commit -m "first move"
git mv b a
git commit -m "second move"

git log --follow a

commit 81b80f5690deec1864ebff294f875980216a059d
Author: Sergey Orshanskiy <*****@gmail.com>
Date:   Sat Oct 12 00:35:58 2013 -0400

    second move

commit f284fba9dc8455295b1abdaae9cc6ee941b66e7f
Author: Sergey Orshanskiy <*****@gmail.com>
Date:   Sat Oct 12 00:34:54 2013 -0400

    initial b

Contrast it with:

git init
echo "First" >a
git add a
git commit -m "initial a"
echo "Second" >b
git add b
git commit -m "initial b"

git mv a c
git mv b a
git commit -m "both moves at the same time"

git log --follow a

Result:

commit 84bf29b01f32ea6b746857e0d8401654c4413ecd
Author: Sergey Orshanskiy <*****@gmail.com>
Date:   Sat Oct 12 00:37:13 2013 -0400

    both moves at the same time

commit ec0de3c5358758ffda462913f6e6294731400455
Author: Sergey Orshanskiy <*****@gmail.com>
Date:   Sat Oct 12 00:36:52 2013 -0400

    initial a

Ups... Now the history is going back to initial a instead of initial b, which is wrong. So when we did two moves at a time, Git became confused and did not track the changes properly. By the way, in my experiments the same happened when I deleted/created files instead of using git mv. Proceed with care; you've been warned...

2
  • 7
    +1 for the detailed explanation. I've been looking for problems that might happen in log history if files are moved in git, your answer was really interesting. Thank you! Btw, do you know any other pitfalls that we should avoid while moving files in git? (or any reference you could point to.... not very lucky googling for it)
    – pabrantes
    Commented Mar 21, 2014 at 16:24
  • 2
    Well, my examples are pessimistic. When the files are empty, it is much more difficult to properly interpret the changes. I imagine that if you just commit after every set of renames, you should be fine. Commented Mar 23, 2014 at 1:43
41

As @Charles says, git mv is a shorthand.

The real question here is "Other version control systems (eg. Subversion and Perforce) treat file renames specially. Why doesn't Git?"

Linus explains at http://permalink.gmane.org/gmane.comp.version-control.git/217 with characteristic tact:

Please stop this "track files" crap. Git tracks exactly what matters, namely "collections of files". Nothing else is relevant, and even thinking that it is relevant only limits your world-view. Notice how the notion of CVS "annotate" always inevitably ends up limiting how people use it. I think it's a totally useless piece of crap, and I've described something that I think is a million times more useful, and it all fell out exactly because I'm not limiting my thinking to the wrong model of the world.

0
20

There's a niche case where git mv remains very useful: when you want to change the casing of a file name on a case-insensitive file system. Both APFS (mac) and NTFS (windows) are, by default, case-insensitive (but case-preserving).

greg.kindel mentions this in a comment on CB Bailey's answer.

Suppose you are working on a mac and have a file Mytest.txt managed by git. You want to change the file name to MyTest.txt.

You could try:

$ mv Mytest.txt MyTest.txt
overwrite MyTest.txt? (y/n [n]) y
$ git status
On branch master
Your branch is up to date with 'origin/master'.

nothing to commit, working tree clean

Oh dear. Git doesn't acknowledge there's been any change to the file.

You could work around this with by renaming the file completely then renaming it back:

$ mv Mytest.txt temp.txt
$ git rm Mytest.txt
rm 'Mytest.txt'
$ mv temp.txt MyTest.txt
$ git add MyTest.txt 
$ git status
On branch master
Your branch is up to date with 'origin/master'.

Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)

    renamed:    Mytest.txt -> MyTest.txt

Hurray!

Or you could save yourself all that bother by using git mv:

$ git mv Mytest.txt MyTest.txt
$ git status
On branch master
Your branch is up to date with 'origin/master'.

Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)

    renamed:    Mytest.txt -> MyTest.txt
18

git mv moves the file, updating the index to record the replaced file path, as well as updating any affected git submodules. Unlike a manual move, it also detects case-only renames that would not otherwise be detected as a change by git.

It is similar (though not identical) in behavior to moving the file externally to git, removing the old path from the index using git rm, and adding the new one to the index using git add.

Answer Motivation

This question has a lot of great partial answers. This answer is an attempt to combine them into a single cohesive answer. Additionally, one thing not called out by any of the other answers is the fact that the man page actually does mostly answer the question, but it's perhaps less obvious than it could be.

Detailed Explanation

Three different effects are called out in the man page:

  1. The file, directory, or symlink is moved in the filesystem:

    git-mv - Move or rename a file, a directory, or a symlink

  2. The index is updated, adding the new path and removing the previous one:

    The index is updated after successful completion, but the change must still be committed.

  3. Moved submodules are updated to work at the new location:

    Moving a submodule using a gitfile (which means they were cloned with a Git version 1.7.8 or newer) will update the gitfile and core.worktree setting to make the submodule work in the new location. It also will attempt to update the submodule.<name>.path setting in the gitmodules(5) file and stage that file (unless -n is used).

As mentioned in this answer, git mv is very similar to moving the file, adding the new path to the index, and removing the previous path from the index:

mv oldname newname
git add newname
git rm oldname

However, as this answer points out, git mv is not strictly identical to this in behavior. Moving the file via git mv adds the new path to the index, but not any modified content in the file. Using the three individual commands, on the other hand, adds the entire file to the index, including any modified content. This could be relevant when using a workflow which patches the index, rather than adding all changes in the file.

Additionally, as mentioned in this answer and this comment, git mv has the added benefit of handling case-only renames on file systems that are case-insensitive but case-preserving, as is often the case in current macOS and Windows file systems. For example, in such systems, git would not detect that the file name has changed after moving a file via mv Mytest.txt MyTest.txt, whereas using git mv Mytest.txt MyTest.txt would successfully update its name.

1
  • How git mv in newer versions of git allows simplified relocation of submodules is massive workflow improvement. Commented Mar 6, 2021 at 5:21
11

There's another use I have for git mv not mentioned above.

Since discovering git add -p (git add's patch mode; see http://git-scm.com/docs/git-add), I like to use it to review changes as I add them to the index. Thus my workflow becomes (1) work on code, (2) review and add to index, (3) commit.

How does git mv fit in? If moving a file directly then using git rm and git add, all changes get added to the index, and using git diff to view changes is less easy (before committing). Using git mv, however, adds the new path to the index but not changes made to the file, thus allowing git diff and git add -p to work as usual.

2

Maybe git mv has changed since these answers were posted, so I will update briefly. In my view, git mv is not accurately described as short hand for:

 # not accurate: #
 mv oldname newname
 git add newname
 git rm oldname

I use git mv frequently for two reasons that have not been described in previous answers:

  1. Moving large directory structures, where I have mixed content of both tracked and untracked files. Both tracked and untracked files will move, and retain their tracking/untracking status

EDIT: as discussed in comments, likely point 2 below is not true. A smaller benefit would be that you get a "moved" status displayed on "git status", which IS handy, but will not be saved anywhere after you commit staged changes

  1. Moving files and directories that are large, I have always assumed that git mv will reduce the size of the repository DB history size. This is because moving/renaming a file is indexation/reference delta. I have not verified this assumption, but it seems logical.
13
  • Logic I too share, but as Spock would say, "It is not logical" (with the one eyebrow going up).
    – Adrian
    Commented Dec 7, 2022 at 22:58
  • 1
    #2 is definitely not correct. git addresses objects, including files, based on a hash of their contents, not their location. If two files have the same content, regardless of their name and location, they will be considered the same object, and only stored once. Not only does it not matter how you rename a file, you can have multiple copies at the same time, or reintroduce a file you deleted 20 commits ago, and git will simply calculate the hash, find that the object is already in the database, and not store anything new.
    – IMSoP
    Commented Dec 7, 2022 at 22:59
  • @IMSoP, I think your use of the term "addresses" is ambigous. of course Git handles locations of files and folders, and uses that to distinguish different files. If two files have the same content and even the same name filename (just different path), they canno t be connected by GIT in the way you say, because it would break tracking of history of the files. You can test this easily by checking git status on any repo. See the difference after doing a git mv, vs doing a regular mv, followed by a git add Commented Dec 8, 2022 at 11:41
  • spoiler... if you do git mv, your file will be listed by git status as "renamed" to a new location, while if you do mv + git add... you will have your old file listed as deleted, and the new file listed as a new file in staging Commented Dec 8, 2022 at 11:44
  • 1
    Point 1 in my answer still holds though, and is very easy to verify. Commented Dec 8, 2022 at 14:26

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.