Clarify git lfs migrate handling of local and remote references

[chrisd8088]

When using the git lfs migrate command with its --everything option, all commits reachable from any refs, local or remote, are considered for migration; however, per PR #2559, only local refs are updated after the migration to avoid desynchronizing remote refs with the origin.

We therefore clarify this distinction in the command's manual page, as well as clarifying that the git push command's --all option refers only to local branches.

Resolves the documentation issue noted in #5316.

[bk2204]

Thanks for clarifying this. I think this is going to be help people understand the way things work much better.

[chrisd8088]

I thought it might be useful, for future reference, to detail an example which shows how a commit reachable only from a remote reference will be migrated when --everything is used, but is then left unreachable because it is not reachable from any local references.

Note that all three matching files matching the --include="*.bin" pattern are converted into blobs, and the commits where they were introduced are rewritten, but only the local refs are updated and so the one commit which is reachable only from refs/remotes/origin/other is left unreachable.

$ git init test-origin
$ cd test-origin
$ echo init >init.bin
$ git add init.bin
$ git commit -m init
$ git checkout -b other
$ echo foo >foo.bin
$ git add foo.bin
$ git commit -m foo
$ echo bar >bar.bin
$ git add bar.bin
$ git commit -m bar

$ cd ..
$ git clone test-origin test-clone
$ cd test-clone
$ git reset --hard HEAD^
HEAD is now at f4303e8 foo
$ git checkout main
branch 'main' set up to track 'origin/main'.

$ git lfs migrate import --everything --include="*.bin"
migrate: Sorting commits: ..., done.                                            
migrate: Rewriting commits: 100% (3/3), done.                                   
  main	efddaae30c09e756686832d34a7dd69427b7fcd4 -> bd56ad43eb62db78fadbf51d0d5eb1c91b71d0c3
  other 	41d4dd8a12ddb445843adbf8f52f6aae877007e7 -> 4daa4eff655003d395e20d16960e186c4342e14c
migrate: Updating refs: ..., done.                                              
migrate: checkout: ..., done.        

$ find .git/lfs/objects -type f
.git/lfs/objects/b5/bb/b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c
.git/lfs/objects/7d/86/7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded97730
.git/lfs/objects/06/11/06111c6797d5e5932b792d0c3afdf13bc912ba44af806058bbca4770d8915305

$ cat .git/lfs/objects/7d/86/7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded97730
bar

$ git fsck --unreachable
Checking object directories: 100% (256/256), done.
unreachable blob 01613474789de934ab15077e96fb168c6a14f694
unreachable commit ccb4958973a439675849756ce055866970223612
unreachable tree 24125f03bace9df92575e9c10f981bdebb546917

$ git show ccb4958973a439675849756ce055866970223612:bar.bin
version https://git-lfs.github.com/spec/v1
oid sha256:7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded97730
size 4

$ git show other:foo.bin
version https://git-lfs.github.com/spec/v1
oid sha256:b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c
size 4
$ git show other:bar.bin
fatal: path 'bar.bin' does not exist in 'other'

$ git show refs/remotes/origin/other:foo.bin
foo
$ git show refs/remotes/origin/other:bar.bin
bar