Skip to main content
History selection tells Gat which committed gat.lock to read. Use these flags with gat push, gat fetch, gat pull, gat status --remote, or gat gc.
gat pull can prefetch historical objects, but always restores the current checkout. To restore an older version, check it out with Git first.
Choose your starting commits, then decide how far back to look. Combine history with path selection to choose files within those snapshots. Before deleting stored content, review garbage-collection protection rules.
1

Choose where to start

Repeat --rev or combine it with --branches and --tags to include more starting points. Overlapping commits are counted once. --all-history cannot be combined with those three options.
2

Choose how far back to look

--rev, --branches, and --tags select only the starting commits by default, not their earlier history.Add --ancestors to include all , or --depth N to visit at most N commits per starting point, including the starting commit. These two options cannot be combined. --all-history already includes ancestry, but you can still limit it with --depth.
With no starting-point option, traversal starts at HEAD only. For example, --depth 5 visits HEAD and up to four closest ancestors, not five commits from every branch. Traversal is closest-first, not ordered by commit timestamp.
3

Refine the selection

Each of these options enables ancestry traversal, even without --ancestors. Without a starting-point option, they start at HEAD.
Depth limits work, not matches. --depth 5 --since "2 weeks ago" inspects at most five commits per starting point, then applies the date filter. It may select fewer than five commits—or none.

​
When a branch and tag share a name

If both are named release, --rev release selects the tag, not the branch or both. The collision does not cause an ambiguity error. Use full ref names to make your choice explicit.
To select both, pass both full names with separate --rev arguments.

​
Examples

Upload objects needed by the latest commit on the local main branch.
Each command keeps its own default. For example, gat push uses the current desired state, while gat gc uses a conservative all-ref history selection. Explicit history selection makes push use committed snapshots instead of the current desired state.
An explicit --rev must resolve to a commit; a missing revision or a tag pointing to a blob or tree fails. Aggregate selectors skip valid non-commit refs, but broken or unreadable refs cause an error.Only locally available Git history can be selected. A cannot provide commits beyond its shallow boundary. Fetch more Git history before asking Gat to select those snapshots.