git, sure-fire way to move/rename files while keeping the history

Question

I know there are \"lots\" of existing questions that looks similar, so let me summarize them before asking mine.

• The answer to Is it possible to move/rename files

Answer 1

tl;dr; no

Longer version: In my experience, git is very good at detecting the move/rename as long as the file is unmodified. Git uses heuristics to attempt and locate the move. It can be fooled by having several files that are too similar, or if the file has been modified during the move, causing it to be too dissimilar from its original.

The best way I have found to do this is to do multi-stage commits, separating all of your moves into one commit, followed by the changes in another. For example...

git mv foo.txt bar.txt
git commit

... modify bar.txt ...

git add bar.txt
git commit

It will not guarantee your move is detected correctly, as it can still get confused when there are multiple candidates. However it has worked very well for me and catches the majority of cases.

Answer 2

Git doesn't track renames. Period. It also doesn't track adds. Or deletes. Or diffs. Or patches. Or moves. Or any sort of change, really.

Git is snapshot-based. Every commit records a snapshot of the entire project. That's it. How that snapshot came to be, Git neither knows nor cares.

Diffs, patches, adds, deletes, moves, renames, etc. are shown by various visualization tools, which infer them after the fact using heuristics (which is another way of saying "guessing"). Sometimes, they may guess correctly what you did, and sometimes they don't. It doesn't matter, though, because it's only visualization, it's not part of the history in any way, shape, or form.

Most tools use some form of similarity metric, and infer that a rename occurred if two files have a similarity greater than some threshold. In some tools, this threshold is configurable. In some tools, even the algorithm is configurable. (A slightly related example: git diff allows you to choose between different algorithms for inferring differences within files.)

Since Git doesn't record changes, it is possible to add new changes in later versions of the visualization tools which can infer those changes from older commits which were recorded before the new tools which understand new kinds of changes were even written. Imagine, for example, a tool which understands the syntax and semantics of the programming language you are using. It could visualize a certain commit not as a whole bunch of files each having a couple of lines changed, but as a single change which renames a subroutine and updates each callsite (i.e. the Rename Method Refactoring).

Renames are actually a good example of this. The rename detection heuristics and similarity metrics used by git log --follow, for example, were improved multiple times. IIRC, in the beginning, renames weren't inferred at all, that capability was added later. This would simply not have been possible, if Git recorded changes instead of snapshots.