gat

gat [-o | --full-output] command [options]

gat versions large files next to a Git repository. Git commits `gat.lock`, a map from each path to a BLAKE3 hash of the file bytes. The bytes themselves live in a local cache (`.gat/objects` by default) and in storage you configure: a directory, S3, Azure Blob, Google Cloud Storage, or Alibaba OSS.`gat add` hashes the file, writes the lock row, and keeps the working file out of ordinary `git add` through `.git/info/exclude`. Commit `gat.lock` and, when it changed, `gat.yaml`. `gat push` uploads the objects. In another clone, `gat init` then `gat pull` downloads those objects and writes the working files for the checked-out lock.`gat init` also installs `post-checkout`, `post-merge`, and `post-rewrite` hooks so `gat sync` restores files after checkout, merge, and rebase. Git does not copy those hooks, so each clone runs `gat init` itself. After `git reset --hard` or `git restore`, run `gat sync` directly. `gat fetch` fills the cache and leaves the working tree alone. `gat pull` fetches, then syncs.A Gat remote is separate from a Git remote. `gat remote add` never selects a default, even for a remote named `origin`. Set one with `gat remote default`, or pass `--remote` on `push`, `fetch`, and `pull`.

-o, --full-output

Show every row and the full detail. Applies to every subcommand.

Create the local cache and install Git hooks plus a semantic merge driver for `gat.lock`. --example-config writes a commented `gat.yaml` only when none exists. --no-hooks removes Gat's managed hook blocks. Run this in every clone.

Hash files, directories, or globs into the local cache and record them in `gat.lock`. Refuses a path Git already tracks. --force includes paths ignored by `.gatignore` or Git ignore rules inside the selected scope.

Stop tracking paths and delete the working files. --cached drops the lock rows and leaves the files on disk.

Rename a tracked file or directory, move it on disk, and update `gat.lock`. Name the destination explicitly. --force replaces an existing destination file.

Add named object storage. URLs may be `file://`, `s3://`, `azblob://`, `gcs://`, or `oss://`, and may contain `${VAR}` references. Adding a remote does not select a default.

Show or choose the default remote. --unset clears this scope's choice.

Inspect or change remotes. remove also accepts rm. Writes go to the project `gat.yaml` unless --global or --local is set.

Upload objects required by the current `gat.lock`. --remote overrides path routing. History flags upload objects from committed locks.

Download objects into `.gat/objects`. Working files stay as they are.

Fetch missing objects, then materialize the files selected by the current checkout.

Make the working tree match `gat.lock` from the local cache. --dry-run prints the plan. --force overwrites locally modified managed files. --fetch downloads missing objects first. Hooks run this after checkout, merge, and rebase.

Compare the current lock with the staged lock. File bytes are not inspected. --remote checks whether required objects are present in storage.

Show tracked paths added, removed, or changed between revisions. With no revisions, compare `HEAD` with the working tree.

List paths recorded in the current `gat.lock`.

Delete objects outside the selected history and the current lock. Remote deletion requires --unsafe.

Print or set a `gat.yaml` key such as `cache.location`. --unset removes the key from the selected scope. --clear stores an empty list.

Manage a saved path selection, send paths to different remotes, import files from another Git repository, or inspect and repair local Gat state.

Print the version.

Display help. -h prints the short form.

gat.lock

Committed map of repository-relative paths to BLAKE3 content IDs. A very large lock can be a `gat.lock/` directory of shards. Git merges it with the driver installed by `gat init`.

Project settings committed with the repository: remotes, routes, mounts, selections, and keys such as cache location and materialization strategy.

Global settings for every repository of this user (`gat config --global`, `gat remote add --global`).

Settings for this clone only. The `.gat/` directory is not committed.

Local cache of file bytes, one object per content ID. Identical bytes are stored once.

Gat-only exclude file, using `.gitignore` syntax. `gat add` skips matching paths unless --force is passed.

Requires a Git repository. `gat add` refuses paths Git already tracks, and refuses the repository's own `.git`, `.gat`, `gat.lock`, and `gat.yaml` paths. `gat status` compares lock metadata, so an edited file stays invisible until `gat add`.Upload with `gat push` before `git push` when other clones need those bytes. A missing default remote makes transfers fail until you set one or pass `--remote`. Remote `gat gc` deletes objects only with `--unsafe`, and it cannot see repositories you did not list.The published series is still 0.0.x (v0.0.14 on 2026-09-26). The installer places the binary in `~/.local/bin` and warns when another `gat` is already earlier on `PATH`. `gat --version` identifies this build.Homebrew, nixpkgs, and the AUR package named `gat` are koki-develop/gat, a separate cat alternative. This program is installed from https://getgat.dev/ or with `cargo install --locked --bin gat --git https://github.com/getgat-dev/gat gat`.

gat is published by the getgat-dev project. The repository was opened in September 2026, and releases through that month stayed in the 0.0.x series. It records large-file versions as BLAKE3 content IDs in `gat.lock` and keeps the bytes in a cache and in object storage. The license is Apache-2.0.

git(1), git-lfs(1), dvc(1), git-annex(1)

Source code · Homepage · Documentation