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

Local overrides Project; Project overrides Global. General settings inherit field by field; same-name resources replace whole definitions. Default choices inherit independently. Adding a resource never chooses a default.

Choose a configuration command

General settings control Gat’s behavior. use their own commands for inspection and changes.

Configuration	Command
Cache, sync, lock layout, and Git exclusions	gat config
Named storage locations and the default remote	gat remote
Path-to-remote mappings	gat route
Imported snapshots	gat mount
Saved path filters and the default selection	gat selection

gat config does not read or write individual resource fields. 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
network:
  readiness_timeout_seconds: 5
  operation_timeout_seconds: 30
  io_timeout_seconds: 60
  request_concurrency: 256
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

Choose a provider below for URL examples and authentication:

Storage	URL scheme	Setup
Amazon S3 or compatible service	`s3://`	Region, credentials, and custom endpoints
Azure Blob	`azblob://`	Account endpoint and credentials
Google Cloud Storage	`gcs://`	Application Default Credentials
Alibaba OSS	`oss://`	Regional endpoint and credentials
Local or mounted directory	`file://`	Absolute paths on Unix and Windows

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_LOCATION
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
Environment override: GAT_CACHE_MATERIALIZATION_STRATEGY
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
Environment override: GAT_CACHE_INGEST_STRATEGY
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
Environment override: GAT_SYNC_TRUST_STATE
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
Environment override: GAT_SYNC_AUTO_FETCH
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
Environment override: GAT_SYNC_AUTO_REPAIR
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. 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
Environment override: GAT_LOCK_SHARD_LEVELS
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 — use git.ignore_patterns instead. See Feature lifecycle.

Configuration details

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

Network

integer

Total budget in seconds for establishing remote readiness.Default: 5Set with: gat config network.readiness_timeout_seconds <value>

Configuration details

Range: 1-86400
Persisted default: unset
Environment override: GAT_NETWORK_READINESS_TIMEOUT_SECONDS
Example: 5

integer

Timeout in seconds for one backend operation attempt, not an entire transfer.Default: 30Set with: gat config network.operation_timeout_seconds <value>

Configuration details

Range: 1-86400
Persisted default: unset
Environment override: GAT_NETWORK_OPERATION_TIMEOUT_SECONDS
Example: 60

integer

Timeout in seconds for one read, write, or body operation.Default: 60Set with: gat config network.io_timeout_seconds <value>

Configuration details

Range: 1-86400
Persisted default: unset
Environment override: GAT_NETWORK_IO_TIMEOUT_SECONDS
Example: 60

integer

Maximum simultaneous physical network requests per operation; logical scheduling is derived internally.Default: 256Set with: gat config network.request_concurrency <value>

Configuration details

Range: 1-65535
Persisted default: unset
Environment override: GAT_NETWORK_REQUEST_CONCURRENCY
Example: 256

Getting Started

Concepts

Guides

References

Commands

Configuration

How configuration works

Configuration locations

Global

Project (default)

Local

Choose a configuration command

Configuration examples

Configuration reference

Remotes

Cache

Sync

Selections

Lock

Mounts

Routes

Git integration

Network

​How configuration works

​Configuration locations

Global

Project (default)

Local

​Choose a configuration command

​Configuration examples

​Configuration reference

​Remotes

​Cache

​Sync

​Selections

​Lock

​Mounts

​Routes

​Git integration

​Network

How configuration works

Configuration locations

Choose a configuration command

Configuration examples

Configuration reference

Remotes

Cache

Sync

Selections

Lock

Mounts

Routes

Git integration

Network