Skip to main content
Use Git for branches and commits. Run gat add after editing large files, then publish their bytes with gat push before publishing commits.
Run gat init in every clone. Git does not copy Gat’s local hooks or configuration.

​
Typical workflows

Commit gat.yaml too if shared configuration changed. gat push normally uploads only the current selection. Use history selectors when earlier commits introduce other objects teammates will need.

​
Switching branches

The checkout hook syncs files from the local cache. If objects are missing, run gat pull. Preserve local edits before switching; Gat reports conflicts when reconciliation would overwrite them.

​
Merging branches

Merge with Git as usual:
When both branches changed gat.lock, Gat’s semantic merge driver compares the lock by tracked path, not by text line.

​
What merges automatically?

Independent path changes, identical additions, and one-sided changes merge automatically. Different edits to the same path, or an edit versus deletion, require a decision. Gat does not merge binary contents.
Gat compares each path’s content ID, treating absence as deletion:
See the lock specification for the complete model.

​
Why you may not see conflict markers

The semantic merge driver fails closed. When it cannot resolve a path, Git records gat.lock as unresolved, but Gat leaves the current lock content untouched instead of writing <<<<<<< / ======= / >>>>>>> markers into it.
Use git status as the source of truth for whether gat.lock is unresolved. A conflicted lock can still look syntactically valid on disk.

​
Resolve a same-path conflict

1

Find the conflicted lock file

Most repositories use a flat gat.lock. If lock sharding is enabled, Git may report a specific file below gat.lock/ instead.
2

Inspect ours and theirs

For a flat lock:
Identify the path named by Gat’s conflict diagnostic and decide which content ID—or deletion—belongs in the merged result.
3

Produce the final semantic lock

Edit the lock to retain independent changes from both sides and resolve the conflicting paths. Keep the two-field lock format: quoted path, a tab, and content ID. Remove an entry to choose deletion.
Do not delete gat.lock and try to recreate it from whichever files happen to be in your working tree. gat.lock is the authoritative versioned map; the working tree may represent only one side of the merge.
4

Mark the lock resolved

If Git reported a sharded lock file, add the affected shard path instead.
5

Materialize the chosen result

Fetch any selected objects that are not in your cache and reconcile the worktree:
6

Finish the Git operation

For a merge:
For a rebase:
This replaces the whole conflicted lock file or shard, discarding changes from the other side, including unrelated entries.
Then finish the merge or rebase. During rebase, “ours” is the branch you are rebasing onto; “theirs” is the commit being replayed.

​
Rebasing and amending

Use git rebase and git commit --amend normally. The merge driver resolves independent path changes during rebase; resolve incompatible changes using the steps above, then run git rebase --continue.
During a rebase, Git’s “ours” is the branch you are rebasing onto and “theirs” is the commit being replayed. Inspect both stages before choosing a whole side.
The post-rewrite hook syncs after rebase or amend. After operations without a matching hook, such as git reset --hard or git restore, run gat sync yourself, or gat pull if objects are missing. See Automatic sync.

​
Troubleshooting collaboration

From a clone that has the required object, run gat push and check gat status --remote. Then the teammate can retry gat pull. Use history selectors if the missing object belongs to an earlier commit.
Run gat init to install the semantic merge driver, then retry the merge from a clean Git state. Every clone needs this local setup.
A stopped merge does not run the successful post-merge hook. After resolving and staging the lock, run gat pull explicitly.

Automatic sync

Handle missing files and local edits after Git operations.

History selection

Publish objects needed by earlier commits.