Using multiple remotes

Use --remote NAME to choose storage for one command. Add routes when different paths should use different remotes automatically. A maps a subtree to storage. For a first remote, start with Set up a remote.

Routing is experimental. Routes choose storage; they do not restrict access, move existing objects, or change file ownership.

Remote selection at a glance

Gat uses the first applicable choice:

An explicit --remote NAME.
The route with the most-specific matching path.
The configured default remote.

Route names do not affect precedence. Paths match by segment: models covers models/a.bin, but not models-old/a.bin.

Set up multiple remotes

Initialize Gat first. Replace these buckets and regions with yours, and configure provider credentials.

Add storage locations

gat remote add origin 's3://company-main/gat?region=eu-west-1'
gat remote default origin
gat remote add model-store 's3://company-models/gat?region=eu-west-1'
gat remote add secure-store 's3://company-secure/gat?region=eu-west-1'

Adding a remote never selects a default.

Route the model paths

gat route add models model-store models
gat route add private-models secure-store models/private

Tracked path	Remote
`data/train.parquet`	`origin`
`models/base.onnx`	`model-store`
`models/private/customer.onnx`	`secure-store`

The nested models/private route wins over models.

Review and share the settings

gat route list
git add gat.yaml
git commit -m "Route model storage"

Project settings are shared through Git. Each user still needs storage credentials. Use --local for machine-specific overrides.

Transfer across several remotes

Normal transfers now follow the routes. Use --path to narrow the operation:

gat push --path models

gat fetch --path models

gat pull --path models

gat status --remote --path models

gat sync --fetch follows the same routing. Omit --path to use your default selection, or --path . to include all repository paths.

Override routing for one command

After configuring a remote named backup, choose it without changing routes:

gat fetch --path models --remote backup

gat push --path models --remote backup

gat status --path models --remote backup

A bare gat status --remote checks each path’s routed remote. gat status --remote backup checks every selected path against backup.

Routes do not copy existing objects

To move repository-owned model objects to another store, populate that store before changing the route:

Fetch from the existing storage

gat fetch --path models

This fills the local cache using the current routes.

Upload and verify the new store

gat remote add archive 's3://company-archive/gat?region=eu-west-1'
gat push --path models --remote archive
gat status --path models --remote archive

Confirm the required objects are present before continuing.

Change the route and commit

gat route update models --remote archive
git add gat.yaml
git commit -m "Move model storage to archive"

More-specific routes, such as models/private, still win. Change those separately if their storage should move too.

These commands copy the current selected objects. To preserve older revisions, include the required history selections when fetching and pushing. Keep the old store until you have verified every version you need. A selected remote with missing objects does not trigger an automatic search of other stores.

Inspect routing

Task	Command
List routes and the default fallback	`gat route list`
Inspect a route and its scope	`gat route show models`
Move a route to a new path	`gat route update models --path assets/models`
Remove a route	`gat route remove models`
Show the default remote	`gat remote default`
Choose a configured default	`gat remote default archive`

The * row in the route listing represents the ; it is not a removable route. Changing the default affects only paths without a route. Removing a route keeps the remote and tracked files.

Advanced behavior

One object appears under several routes

Identical bytes share one cached object. A downloads it once, using the first selected path’s remote. Push can publish the same object to each remote required by the selected paths.

Override shared routes locally

Add a complete definition with the same name in local configuration:

gat route add models model-store models --local

Reads use the effective configuration. Updates and removals must target the defining scope. See Config inheritance.

Routes overlap mounted paths

A route can serve repository-owned or mounted files. It changes storage selection, not ownership. Moving or removing a mount does not move or remove its route. See Consuming Gat assets.

Remote commands

Manage named storage locations.

Route commands

Manage path-based storage rules.

Getting Started

Concepts

Guides

References

Commands

Using multiple remotes

Remote selection at a glance

Set up multiple remotes

Transfer across several remotes

Override routing for one command

Routes do not copy existing objects

Inspect routing

Advanced behavior

Remote commands

Route commands

​Remote selection at a glance

​Set up multiple remotes

​Transfer across several remotes

​Override routing for one command

​Routes do not copy existing objects

​Inspect routing

​Advanced behavior

Remote commands

Route commands

Remote selection at a glance

Set up multiple remotes

Transfer across several remotes

Override routing for one command

Routes do not copy existing objects

Inspect routing

Advanced behavior