git-filter-repo
creates entries that point to refs/replace
in the .git/packed-refs
file. Example after running git-filter-repo
:
$ cat .git/packed-refs
# pack-refs with: peeled fully-peeled sorted
bea0c96834381824ddf6cae6c79563754b0b73a2 refs/heads/some_branch
fb1be5a13f5a4acc051f4a8f9a1603446aa3e509 refs/heads/master
e3d3e5a8a7505bbf36e0c28a053cacaf3c4a9415 refs/replace/02613a4d07596a4c1f4d1b4e4c09a0b436a85404
ad87b74813174f0f04a29429e34a1fb188f83a07 refs/replace/186f2152f9359b58243bf53734ab9e587f9ee638
f5b3103f64af52a8a1012422d7fadf6d70811702 refs/replace/1aed8be9aa47c70ce9e34981322baec06a716260
220f491e1a20b595214891ff20621cc6efbc4b86 refs/replace/1aed9894e93b7d5cd93e427a48d9264b95840838
<more `refs/replace` entries here>
These are called "replace refs". As far as I understand, replace refs in Git are only a convenience mechanism that allows one to refer to a ref (e.g, a commit ID) using its old ID. That is, AFAICT, they are not required for correct functionality of a Git repository, but only as a way conveniently refer to a new commit using its old ID.
I got the impression that replace refs are are only a convenience mechanism (as opposed to something necessary for correct functionality) from the following paragraph in the DISCUSSION section in the manual of git-filter-repo
:
6. (Optional) Some additional considerations
filter-repo by default creates replace refs (see git-replace(1)) for each rewritten commit ID, allowing you to use old (unabbreviated) commit hashes to refer to the newly rewritten commits. If you want to use these replace refs, push them to the relevant clone URL and tell users to adjust their fetch refspec (e.g.
git config --add remote.origin.fetch +refs/replace/*:refs/replace/*
) Sadly, some existing git servers (e.g. Gerrit, GitHub) do not yet understand replace refs, and thus one can’t use old commit hashes within their UI; this may change in the future. But replace refs at least help users locally within the git CLI.
At least, the sentence that says some Git servers (such as Gerrit and GitHub) not understanding the replace refs made me think that they are not required for the correct functionality of a Git repository, but only as a convenience mechanism.