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 Git invokes the installed semantic driver for a changed lock file or shard, Gat merges by decoded path and emits strictly path-ordered rows. Fast-forwards and one-sided file changes can bypass the driver. Git’s default text merge does not validate lock ordering. Do not use merge=union: it can concatenate conflicting additions out of order.

​
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. The combined lock must also satisfy file/directory-prefix constraints: for example, it cannot track both data and data/model.bin. The driver rejects these conflicts within each merged file before writing output. It does not certify conflicts across shards or files Git resolves without invoking the driver; subsequent Gat reads validate the complete lock.
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

When the merge driver cannot resolve a path, Git records gat.lock as unresolved. Gat leaves the current lock content untouched instead of writing .
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: 64 lowercase hexadecimal digest characters, a tab, and an unquoted escaped path. Encode path controls as lowercase \xhh; quotes and spaces are literal. Keep rows strictly sorted by decoded path bytes, and terminate the header and every row with LF (CRLF is also accepted). 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. 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.