git fast-import --export-marks flag

Question

git fast-import --export-marks is able to export a file associating the marks with the commit hashes it created.

So far I've seen the marks are not the ones provided in the input but some "internal ones" not related with the input.

Wouldn't it be much better, for import/export interop, if it keeps the original marks?

Answer 1

The purpose of the marks exported by fast-import is to list the commits and the blobs for subsequent verification and synchronisation. The purpose of the marks imported by fast-import is to skip commits in an incremental export-import scenario.

╔════════════════╦══════════════════════════════════╗
║                ║        git fast-export           ║
╠════════════════╬══════════════════════════════════╣
║ --import-marks ║ 1) commits to skip during export ║
║ --export-marks ║ 2) exported commits              ║
╚════════════════╩══════════════════════════════════╝
╔════════════════╦══════════════════════════════════════╗
║                ║          git fast-import             ║
╠════════════════╬══════════════════════════════════════╣
║ --import-marks ║ 3) commits to skip during import     ║
║ --export-marks ║ 4) a) blobs                          ║
║                ║    b) imported commits, same as (2)  ║
╚════════════════╩══════════════════════════════════════╝

You can see from the tables above how the flags might be combined in a scenario where repos are incrementally synchronised. One might export a repo, import it elsewhere, then either create incremental export files by skipping previously exported commits, or create full exports and incrementally import by skipping commits already known.

Here's a short example to clarify.

$ cd /tmp && git init example && cd example &&  touch README && \
git add README && git commit -m "first commit"
$ git fast-export --all --export-marks=/tmp/example-repo.marks > /tmp/example-repo.export
--- /tmp/example-repo.export ---
blob
mark :1
...
reset refs/heads/master
commit refs/heads/master
mark :2
...
reset refs/heads/master
from :2

--- /tmp/example-repo.marks ---
:2 610432e74c554d783ff5f9edd1bb18548d68e533

Only one mark has been exported, the mark for the single commit added to the repo.

$ git show 610432e74c554d783ff5f9edd1bb18548d68e533
commit 610432e74c554d783ff5f9edd1bb18548d68e533
...

When you proceed to recreate the repository, the exported marks will list not only the commits, but also the new blobs. These new blobs have been re-created, and are present in the marks for you to check, the commits are also listed to compare against all the import referenced commits.

$ cd /tmp && git init example-import && cd example-import && \
cat /tmp/example-repo.export | git fast-import --export-marks=/tmp/example-import-repo.marks

--- /tmp/example-import-repo.marks ---
:1 e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
:2 610432e74c554d783ff5f9edd1bb18548d68e533

The blob :1 has been recreated and is newly listed in the marks file (using the first available mark which happens to be :1), but note that the marked commit :2 retained its mark and its hash from the original exported repo.