Configuration

How configuration works

Unset keys are normally omitted from gat.yaml. Reads use the ; mutating commands write only the selected layer, with Project as the default.

Configuration locations

Global

~/.gat/gat.yamlUser-wide defaults shared by every repository.Committed: No

Project (default)

<repo>/gat.yamlRepository configuration shared with clones.Committed: Yes

Local

<repo>/.gat/gat.yamlMachine-specific repository overrides.Committed: No

Configuration precedence is Global → Project → Local. Named selections, mounts, routes, and remotes replace whole definitions on a same-name collision; different names coexist. Optional default pointers for selections and remotes inherit independently. Adding a resource never chooses a default. Other settings inherit field by field.

Use gat config for general settings and gat remote, gat mount, gat route, or gat selection for named resources. See Config inheritance for overrides and defaults.

Configuration examples

version: 1
remotes:
  default: origin
  origin:
    url: s3://example-bucket/project?region=eu-west-1
cache:
  materialization_strategy:
  - reflink
  - copy
sync:
  auto_fetch: true
selections:
  default: runtime
  runtime:
    exclude:
    - tmp/**

version: 1
remotes:
  default: origin
  backup:
    url: file:///mnt/backup/prefix
  origin:
    url: s3://bucket/prefix?region=eu-west-1
cache:
  location: /var/cache/gat
  materialization_strategy:
  - hardlink
  - copy
  ingest_strategy: hybrid
sync:
  trust_state: true
  auto_fetch: true
  auto_repair: true
selections:
  default: runtime
  runtime:
    path: data
    include:
    - '**'
    exclude:
    - tmp/**
lock:
  shard_levels: 2
mounts:
  resnet50:
    url: ../models
    target: releases/resnet50
    path: exports/resnet50
    rev: main
    rev_lock: 6c73875a1b2c3d4e5f60718293a4b5c6d7e8f901
    include:
    - '**/*.onnx'
    exclude:
    - tests/**
routes:
  datasets:
    path: datasets
    remote: backup
  resnet50:
    path: releases/resnet50
    remote: origin
git:
  ignore_patterns:
  - '*.safetensors'
  - /artifacts/**/*.bin

Configuration reference

Remotes

Each named remote has a url. remotes.default chooses the fallback by name; gat remote add never selects it automatically.

remotes:
  default: origin
  origin:
    url: file:///mnt/storage/project

Remote URL examples

Choose a provider and replace its storage names. For authentication and supported URL options, see Remote providers.

S3
Azure
GCS
OSS
Local

gat remote add origin 's3://example-bucket/project?region=eu-west-1'

S3-compatible services also need an :

gat remote add minio 's3://example-bucket/project?region=us-east-1&endpoint=http://localhost:9000'

gat remote add origin 'azblob://example-container/project?endpoint=https://myaccount.blob.core.windows.net'

gat remote add origin 'gcs://example-bucket/project'

gat remote add origin 'oss://example-bucket/project?endpoint=https://oss-cn-hangzhou.aliyuncs.com'

gat remote add origin 'file:///mnt/backup/project'

gat remote add origin 'file:///C:/gat-storage/project'

Use gat remote default to select a default and gat remote update to change an existing URL. Explicit --remote overrides routes, which override the default. See routing precedence for path-based storage, or Set up a remote for the full workflow.

Keep literal credentials out of committed URLs. Use provider credentials or single-quoted ${NAME} references. Set referenced variables before validating or using the URL. See URL templates.

remotes:
  default: <value>
  <name>:
    url: <value>

string

Name of the remote used when no explicit remote or more-specific route applies.Set with: gat remote default

Configuration details

Persisted default: unset
Example: origin

remote URL

Object-storage URL for one named remote.Set with: gat remote add

Configuration details

Persisted default: unset
Example: s3://example-bucket/project

Cache

path

Absolute cache path or a path relative to the repository root.Default: <repo>/.gat/objectsSet with: gat config cache.location <value>

Configuration details

Persisted default: unset
Environment override: GAT_CACHE_DIR (not persisted to gat.yaml)
Example: /mnt/gat-cache

list

Ordered fallback modes used to materialize cached objects into the working tree.Default: [copy]Set with: gat config cache.materialization_strategy <value>...

Configuration details

Elements: materialization mode
Values: reflink | hardlink | symlink | copy
Empty list: not allowed
Order is significant.
Duplicate values are not allowed.
Persisted default: unset
Example: [reflink, copy]

enum

Copy-and-hash strategy used when publishing local files into the content-addressed cache.Values:

safe Stable
hybrid Experimental
mmap Deprecated

See Feature lifecycle for the guarantees attached to each status.Default: safeSet with: gat config cache.ingest_strategy <value>

Configuration details

Persisted default: unset
Example: safe

Sync

boolean

Trust recorded materialized state without inspecting the working tree.Default: falseSet with: gat config sync.trust_state <value>

Configuration details

Values: true | false
Persisted default: unset
Example: true

boolean

Fetch missing objects before normal sync reconciliation.Default: falseSet with: gat config sync.auto_fetch <value>

Configuration details

Values: true | false
Persisted default: unset
Example: true

boolean

Re-fetch and rematerialize cache objects found corrupted during sync.Default: falseSet with: gat config sync.auto_repair <value>

Configuration details

Values: true | false
Persisted default: unset
Example: true

Selections

string

Optional default selection name. Inherits independently of named definitions. Without a default, operations select the whole repository. Adding a selection never chooses a default.Set with: gat selection default

Configuration details

Persisted default: unset
Example: runtime

path

Literal file or directory relative to the repository root. Same-name definitions replace as a whole across layers. An empty definition selects everything.Default: .Set with: gat selection add

Configuration details

Persisted default: unset
Example: models

list

Include patterns relative to the selected path for sync, pull, fetch, ls-files, status, diff, and push. Any explicit —path, —include, or —exclude replaces the complete configured selection.Default: all tracked paths under the selected pathSet with: gat selection add

Configuration details

Elements: glob
Empty list: selects everything
Order is significant.
Persisted default: unset
Example: [data/**, models/**]

list

Exclude patterns relative to the selected path. Exclusions win. Explicit CLI selection replaces the complete configured selection.Default: []Set with: gat selection add

Configuration details

Elements: glob
Empty list: allowed
Order is significant.
Persisted default: unset
Example: [tmp/**]

Lock

integer

lock.shard_levels is Experimental: its interface or behavior may change or be removed between releases. See Feature lifecycle.

Number of hash fan-out directory levels used by the persisted lock.Default: 0Set with: gat config lock.shard_levels <value>

Configuration details

Range: 0-2
Persisted default: unset
Example: 2

Mounts

mounts:
  <name>:
    url: <value>
    target: <value>
    path: <value>
    rev: <value>
    rev_lock: <value>
    include: <value>
    exclude: <value>

Git location

Git repository from which this mount imports tracked rows.Set with: gat mount add

Configuration details

Persisted default: unset
Example: ../models

path

Destination subtree owned by the mount.Default: repository name from the mount URLSet with: gat mount add

Configuration details

Persisted default: unset
Example: releases/resnet

path

Subtree inside the source repository from which rows are selected.Set with: gat mount add

Configuration details

Persisted default: .
Example: exports

string

Git revision the mount tracks.Default: source repository default branchSet with: gat mount add

Configuration details

Persisted default: unset
Example: main

string

Exact commit resolved from the requested mount revision.Set with: resolved automatically by gat mount add and gat mount update

Configuration details

Persisted default: unset

list

Glob patterns selecting source rows relative to the mount path.Default: all tracked paths under the selected pathSet with: gat mount add

Configuration details

Elements: glob
Empty list: selects everything
Order is significant.
Persisted default: unset
Example: [**/*.onnx]

list

Glob patterns excluded from the mount selection.Default: []Set with: gat mount add

Configuration details

Elements: glob
Empty list: allowed
Order is significant.
Persisted default: unset
Example: [tests/**]

Routes

routes:
  <name>:
    path: <value>
    remote: <value>

path

Root-relative tracked-path prefix served by the route.Set with: gat route add

Configuration details

Persisted default: unset
Example: data/datasets

string

Named remote that serves the route’s path.Set with: gat route add

Configuration details

Persisted default: unset
Example: backup

Git integration

list

Single-line, non-negated Git-ignore patterns used to derive Gat’s managed .git/info/exclude block.Default: []Set with: gat config git.ignore_patterns <value>...git.exclude_patterns Deprecated — this remains supported for compatibility. Use git.ignore_patterns instead. See Feature lifecycle.

Configuration details

Elements: Git-ignore pattern
Empty list: allowed
Order is significant.
Persisted default: unset
Example: [*.safetensors, /artifacts/**/*.bin]

Getting Started

Concepts

Guides

References

Commands

Configuration

How configuration works

Configuration locations

Global

Project (default)

Local

Configuration examples

Configuration reference

Remotes

Cache

Sync

Selections

Lock

Mounts

Routes

Git integration

​How configuration works

​Configuration locations

Global

Project (default)

Local

​Configuration examples

​Configuration reference

​Remotes

​Cache

​Sync

​Selections

​Lock

​Mounts

​Routes

​Git integration

How configuration works

Configuration locations

Configuration examples

Configuration reference

Remotes

Cache

Sync

Selections

Lock

Mounts

Routes

Git integration