Skip to main content
A mount places another repository’s Gat-tracked files under a local directory, such as vendor/models. Your repository the snapshot it consumes.
Mounts are experimental. “Read-only” refers to , not filesystem permissions: tools can still edit these working files, but gat add, gat rm, and gat mv cannot change mount-owned entries.

​
Before you start

Initialize the destination with gat init. You need access to the source Git repository for metadata, and its Gat storage for bytes. The source must have committed its lock and uploaded the referenced objects. See how Git metadata and Gat storage work together.

​
Mount and use upstream data

Replace the source URL below with your asset repository.
1

Import the snapshot

models is the mount name; vendor/models is its target directory. Without a target, Gat uses the source repository name (model-assets/).
2

Check storage setup

Gat preserves an existing route at the target. Otherwise, it reuses or imports the source default remote and creates a route. The destination’s default remote is unchanged.
Configure storage using the URL supplied by the asset publisher:
Git authentication and storage credentials are separate.
3

Restore the working files

Open a restored file to confirm its contents. Your application can use the directory like any other working directory.
4

Commit the snapshot

Other clones need gat init and gat pull. Source Git access is needed again when creating or refreshing a mount, not for ordinary pulls.

​
Mount only the data you need

Use source filters when adding a mount, or change the existing one:
--path is relative to the source repository. Include and exclude patterns are relative to that path; exclusions win. The destination stays vendor/models. Omitted settings are preserved. Supplying an include or exclude list replaces that list only. See Mount options to clear saved filters. Repository named selections do not apply to mount source filters.

​
Pin the upstream version

Choose a revision when adding or updating a mount. Replace <commit-hash> with the full hash for a fixed version:
Every update records the . A branch or tag can resolve to another commit on a later update; use a full commit hash for a fixed revision. Upstream changes never silently refresh your snapshot.

​
Refresh mounted data

Review the metadata diff and restored files before committing. update chooses the snapshot; gat pull fetches and restores its bytes. Use path filters to preview which imported files are selected, and review sync conflicts if local edits prevent restoration.

​
Use an existing Gat remote

To choose a configured remote for this mount:
Use --no-setup on add or update to skip remote and route changes for that invocation. It cannot be combined with --remote.

​
Local modifications

Make shared asset changes in the source repository, then refresh the mount. To inspect local differences that affect reconciliation:
This can overwrite or remove modified files. Save any local work you need first.

​
Stop using a mount

Remove the mount definition and its imported tracking entries.
Routes and remotes are independent. Moving or removing a mount keeps them; inspect gat route list before changing storage policy. See routing precedence to check which remote will serve the retained files.

​
Troubleshooting

Choose a non-root target that does not overlap another mount or contain repository-owned Gat entries. Move or remove conflicting tracking first.
Check gat mount show models for the effective route and remote. Verify storage credentials separately from Git access. If objects are missing, the publisher must upload them from the source repository.
Run gat mount update models, then gat pull --path vendor/models. A fixed commit revision stays pinned until you change --rev.

Mount reference

Source filters, revisions, targets, and removal options.

Storage routing

Choose where mounted paths fetch their bytes.