Skip to main content
Gat combines three configuration layers. Local overrides project; project overrides global. Reads show the from all layers. --global, --project, and --local choose where a command writes; project is the default .

​
General settings and managed resources

Configuration contains both general settings, which control Gat’s behavior, and . They share the same configuration files and layers, but use different commands. Use gat config to read or change a general setting. Use a resource’s list or show command to inspect it, and add, update, or remove to manage its definition. gat config does not read or write individual resource fields. Choose default remotes and selections through their respective default commands. For example, these commands change a general setting and update a mount:
Resource commands let you change related fields together and validate the resulting definition. They also perform the work associated with the change: updating a mount imports a snapshot and updates its owned lock rows, while updating a selection changes only its saved filters. Keeping those operations in their resource commands makes their effects explicit.
A mount’s rev_lock records the commit resolved by gat mount add or gat mount update. Choose a branch, tag, or commit through rev; see pinning an upstream version.The document’s version identifies its file format. Neither field is an editable gat config setting.

​
What inherits?

A complete named definition comes from one layer. Omitted optional fields use that resource’s defaults, not fields from a lower layer. For example, a local selection’s path never inherits a project’s include or exclude patterns. An empty collection such as selections: {} adds no overrides; it does not clear inherited names or defaults. Removing a named override can reveal the lower-layer definition again.

​
Share definitions, choose your default

1

Share a definition

Save the selections in project configuration:
gat.yaml (excerpt)
2

Choose your default locally

Only the choice is saved locally:
.gat/gat.yaml (excerpt)
The project still supplies the training definition. Project updates to it apply automatically. A local definition also named training would replace it completely. A refers to a named definition. Adding a selection or remote never chooses a default. Choose explicitly with gat selection default or gat remote default, followed by the name. Unknown selection names and dangling selection defaults are errors. With no default selection, supported commands select the whole repository.
gat selection is experimental. Use --selection NAME for a single operation, or supply a complete inline selection with --path, --include, and --exclude. Named and inline selectors cannot be combined. See Path selection.

​
Update or restore inheritance

Use gat config for general settings, and gat selection, gat remote, gat route, or gat mount for named resources. Unsetting a default restores inheritance; it does not select an unrestricted repository:
To save an unrestricted selection, add a named selection with --path . and no filters, then choose it as the default. Removing a selection or remote is rejected if it would leave the effective default dangling. For general list settings, --clear saves an empty list where allowed; --unset restores inheritance. For example, gat config git.ignore_patterns --local --unset restores inherited Git exclusion patterns.

​
Check what is active

See the configuration reference for individual settings.