What s the purpose of git-mv

Question

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 specially descriptive    Is it obsolete  Is it an internal command  not meant to be used by regular users

User · Answer

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

User · Answer

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

User · Answer

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  lt file gt      to unstage       renamed     Mytest txt - gt  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  lt file gt      to unstage       renamed     Mytest txt - gt  MyTest txt

User · Answer

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   The file  directory  or symlink is moved in the filesystem   git-mv - Move or rename a file  a directory  or a symlink   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    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  lt name gt  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

User · Answer

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   gt a echo  Second   gt 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  lt file gt      to update what will be committed       use  git checkout --  lt file gt      to discard changes in working directory        modified    a     deleted     b     Untracked files       use  git add  lt file gt      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  lt       gmail com gt  Date    Sat Oct 12 00 24 56 2013 -0400      change   and then     git log --follow c  Author  Sergey Orshanskiy  lt       gmail com gt  Date    Sat Oct 12 00 24 56 2013 -0400      change  commit 50c2a4604a27be2a1f4b95399d5e0f96c3dbf70a Author  Sergey Orshanskiy  lt       gmail com gt  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   gt a echo  Second   gt 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  lt file gt      to unstage        renamed     a - gt  c   git mv b a git status   Now  nobody is perfect     On branch master   Changes to be committed       use  git reset HEAD  lt file gt      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   gt a git add a git commit -m  initial a  echo  Second   gt 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  lt       gmail com gt  Date    Sat Oct 12 00 35 58 2013 -0400      second move  commit f284fba9dc8455295b1abdaae9cc6ee941b66e7f Author  Sergey Orshanskiy  lt       gmail com gt  Date    Sat Oct 12 00 34 54 2013 -0400      initial b   Contrast it with   git init echo  First   gt a git add a git commit -m  initial a  echo  Second   gt 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  lt       gmail com gt  Date    Sat Oct 12 00 37 13 2013 -0400      both moves at the same time  commit ec0de3c5358758ffda462913f6e6294731400455 Author  Sergey Orshanskiy  lt       gmail com gt  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

User · Answer

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

User · Answer

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

User · Answer

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

[git] What's the purpose of git-mv?

Examples related to git

Examples related to git-mv