Set up a remote

A Gat stores large-file bytes. It is separate from the Git remote that stores your commits and gat.lock. Run these commands inside a repository initialized with gat init. For the relationship between commits, storage, and working files, see How Gat works.

Add a storage location

Choose one example and replace its bucket, container, region, or path. Create cloud storage and configure provider credentials before transferring files. Local storage needs no cloud credentials.

Local directory
S3
Azure Blob
Google Cloud
Alibaba OSS

Use an absolute path with three slashes. The directory must be accessible to each machine that will use this remote.

gat remote add origin 'file:///mnt/shared/gat-storage'

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

Set a signing region explicitly. For S3-compatible services, also supply the service’s endpoint.

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

The host names the container. The required endpoint identifies the storage account.

gat remote add origin 'azblob://assets/gat?endpoint=https://myaccount.blob.core.windows.net'

Configure , then add the bucket:

gat remote add origin 'gcs://my-bucket/gat'

Set the endpoint for your bucket’s region:

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

Select the default

gat remote default origin
gat remote show origin

Adding a remote never selects a default. Transfers use this default unless a route or --remote NAME selects another.

add validates configuration, and show displays it with secrets redacted. Neither proves connectivity or storage permissions.

Upload a tracked file

Replace this path with a file Git does not already track:

gat add assets/model.bin
gat push
gat status --remote

This uploads the object and checks remote presence. An empty selection or already-cached download is not an access test.

Network remotes require permission to list the configured storage root during the connection check, plus permission for the transfers you run.

Share the configuration

git add gat.yaml gat.lock
git commit -m "Configure Gat storage"
git push

Remote changes use project configuration by default. Credentials belong in each user’s environment or provider credential store.

Verify from a fresh clone

In a fresh clone of the published repository:

gat init
gat pull

Open the restored file to confirm download access and its contents. A local file:// remote must be accessible at its configured path.

Keep credentials out of Git

Prefer your provider’s credential environment or identity authentication. For a secret URL option, save a ${NAME} reference and single-quote the URL so your shell preserves it.

# Set SAS_TOKEN in your environment before running this command.
gat remote update origin --url 'azblob://assets/gat?endpoint=https://myaccount.blob.core.windows.net&sas_token=${SAS_TOKEN}'

This Azure example replaces the existing remote URL. Supply the original token without extra URL encoding. Variables must be set when adding, changing, or using the URL. Read-only commands display redacted templates without expanding them.

Redacted output does not remove literal secrets from gat.yaml. See URL templates for syntax and credential examples.

Manage storage

Change or remove a remote

Task	Command
List remotes	`gat remote list`
Inspect a remote	`gat remote show origin`
Change its URL	`gat remote update origin --url '<new-url>'`
Restore an inherited default	`gat remote default --unset`
Remove a remote	`gat remote remove origin`

Change or unset references to a remote before removing it. Use the scope that defines it; an update does not create a local override.

Keep a remote on this machine only

gat remote add backup 'file:///mnt/backup/gat' --local
gat push --remote backup

--local writes .gat/gat.yaml, which is not committed. --global writes user-wide settings. See Config inheritance.

Provider credentials

Authentication, endpoints, and connection troubleshooting.

Use multiple remotes

Route paths to different stores or copy objects to a backup.

Getting Started

Concepts

Guides

References

Commands

Set up a remote

Keep credentials out of Git

Manage storage

Provider credentials

Use multiple remotes

​Keep credentials out of Git

​Manage storage

Provider credentials

Use multiple remotes

Keep credentials out of Git

Manage storage