This page is a working reference: every common shape you’d actually write under repositories:. For the conceptual model, see Concepts → Repositories.
Minimal git clone
Pin to a tag
Pin to a commit
SSH origin
Authentication uses your local SSH agent.
Mercurial / Subversion / Bazaar
These types require the matching system binary (svn, hg, bzr) on $PATH. Git uses a pure-Go backend with no system dependency.
Tarball release
version: for tar and zip is a strip-prefix string, gaal removes that leading directory during extraction so the contents land cleanly under src/data/dataset/.
Zip archive
Multiple repos at once
Behaviour at sync time
- A first sync clones (or extracts) each entry into its destination path.
- A subsequent sync fast-forwards or re-extracts based on
version: and the remote state.
- If the destination already exists and is not empty, gaal refuses to clone into it.
- For existing Git checkouts, the working copy’s
origin is authoritative. If gaal.yaml and origin disagree, sync stops with a remote URL mismatch error.
--dry-run reports + clone, ~ update, or = unchanged per entry.- Removing a repository entry from
gaal.yaml does not delete its directory, --prune ignores repositories.
gaal owns the contents of each repository directory. Don’t make local edits inside a managed path, they’ll be lost on the next update. Use a separate working clone for development.
