OXYGENHUB

Git Interoperability

Andy McCall edited this page · 1 revision

Git Interoperability

Oxygen works alongside Git: you can bring a Git history in, keep following a Git remote, publish back to it, and write a plain Git mirror.

flowchart LR
    G[(Git repository)] -->|oxy git import| O[(Oxygen repository)]
    O -->|oxy git export| G2[(Plain Git mirror)]
    GR[(Git remote)] -->|oxy git fetch URL| O
    O -->|oxy git push URL| GR

oxy git import ~/src/project project     # convert a whole history
oxy git verify ~/src/project/.git        # check it, commit by commit
oxy git fetch https://github.com/x/y     # bring new commits into the bookmark
oxy git push https://github.com/x/y      # publish the bookmark as commits on top
oxy git export ../project-git            # a plain Git mirror

How a commit becomes a change

flowchart TD
    C[Git commit] --> P[Union of its parents' states]
    C --> T[Its tree]
    P --> D{Diff the union against the tree}
    T --> D
    D --> Ch["One change: the edits,<br/>Git-Author and Git-Commit trailers"]
    D -->|the parents conflict here| R[The change is a resolution]
  • Each Git commit becomes one change: the difference between the union of its parents' states and its tree.
  • A merge commit becomes an ordinary change, or a resolution where its parents genuinely conflict in Oxygen's model.
  • The author is recorded as a Git-Author trailer, and the change is left unsigned (the zero key), because nobody can sign for the original author. Your first push seals it.
  • ChangeIds and file identities are derived from the Git commit hash, so importing the same history twice gives the same changes.
  • Renames are detected as in a snapshot (half alike or more), then tracked exactly.
  • Git submodules become subrepos with a Git pin.

Round trips

  • Import then export reproduces every Git tree.
  • Export then import reproduces every ChangeId.
  • oxy git verify rebuilds each commit's state and compares it with Git's tree: content, executable bits, symlinks and submodule pins.

Fetching and pushing against Git

oxy git fetch keeps a bare Git mirror under .oxy/git/, imports only commits the bookmark does not have yet, and joins them in as a pull would. oxy git push exports the bookmark's newer states as commits on top of the remote's tip, so a push is always a fast-forward.