Config
You edit the crossrepo config by hand, in YAML. xr codebase init writes the first codebase config for you. xr codebase repo add and xr codebase repo remove change the repos: list. There is no command to set a value.
Three levels
Section titled “Three levels”xr reads up to three files, in this order. A later level wins.
| Level | File | Use it for |
|---|---|---|
| user | ~/.crossrepo/config.yaml |
Your own defaults for every codebase. |
| codebase | <codebase>/.crossrepo/config.yaml |
The repos and hooks of one codebase. You can share it with your team, see Keep the codebase config in git. |
| local | <codebase>/.crossrepo/config.local.yaml |
Your own changes for one codebase. xr never writes this file. |
- Each file can end in
.yamlor.yml. Both at one level is the errorconfig-conflict, and the message names both files. - A missing file is skipped.
- A config file that is a symlink is followed.
Merge rules
Section titled “Merge rules”- A later level wins: local over codebase, codebase over user.
- Maps merge key by key. For example, a local file can set only
repos.api.remote, andrepos.api.default-branchstill comes from the codebase config. - Lists are replaced whole. A
project.post-createlist in the local file replaces the whole list of the codebase config. An empty list,[], gives no hook lines. - A key with no value, or with
null, counts as not set at that level. It does not clear the value of an earlier level.
To see the merged result and the file that gives each value, run xr config show.
| Key | What it is |
|---|---|
name |
The codebase name. Hooks get it as CROSSREPO_CODEBASE_NAME. When it is not set, the name is the codebase folder name. |
projects-dir |
The folder that holds the projects. The default is .projects. A relative path is relative to the codebase folder, also in the user config. See the projects-dir rules. |
repos.<name>.remote |
The URL of the repo. xr codebase clone clones it, exactly as written. |
repos.<name>.default-branch |
The branch that new project branches start from and that xr project sync merges. When it is not set, xr uses the branch that origin/HEAD points to. |
repos.<name>.description |
A short text about the repo. xr puts it in AGENTS.md and shows it in the repo lists. |
repos.<name>.always |
true or false; not set is false. With true, xr project create adds the repo to each new project, also when you do not name it, and the picker shows it as already marked. Use it for a shared repo, such as one with specs, docs or helper scripts. xr codebase init and xr codebase repo add never write it; add it by hand. always: false in config.local.yaml (or the user config) turns off an always: true of the codebase config. |
project.pre-create |
A list of shell commands to run in xr project create before it makes anything. See the hooks guide. |
project.post-create |
A list of shell commands to run after xr project create. See the hooks guide. |
project.pre-remove |
A list of shell commands to run before xr project remove deletes anything. See the hooks guide. |
project.post-remove |
A list of shell commands to run after xr project remove has removed the project. See the hooks guide. |
project.vars |
Your own variables for hooks. See the hooks guide. |
The repos: list decides which repos the codebase has. A repo folder that is not in the list is not a repo of the codebase.
Every key can go in every level. For example, a user config can set projects-dir for all your codebases.
A value with the wrong type is the error invalid-config, for example always: "yes", and the message names the file and the key. A key that xr does not know gives the warning unknown-config-key with a “did you mean” hint, and the command still runs.
A codebase config looks like this:
name: acmerepos: api: remote: git@github.com:acme/api.git default-branch: main description: Public REST API web: remote: git@github.com:acme/web.git default-branch: main description: Frontend specs: remote: git@github.com:acme/specs.git default-branch: main description: Specs and docs always: trueproject: post-create: - npm ci vars: PORT: 3000The other remote protocol
Section titled “The other remote protocol”xr uses each remote exactly as written. When the team config has SSH URLs and you use HTTPS, or the other way round, there are two ways to fix it on your machine.
1. Set the remote in config.local.yaml. Maps merge key by key, so you only set the remote:
# <codebase>/.crossrepo/config.local.yamlrepos: api: remote: https://github.com/acme/api.git2. Use a git insteadOf rule. git then changes the URL for every repo, also outside crossrepo:
git config --global url."https://github.com/".insteadOf "git@github.com:"Keep the codebase config in git
Section titled “Keep the codebase config in git”crossrepo does not put its config in git for you. The .crossrepo/ folder is outside every repo. To share the codebase config with your team, move it into a repo and make a symlink to it. You make the symlink. xr only follows it: when xr writes the codebase config, it writes the file that the link points to and never replaces the link.
1. In a repo you have already. Good when one repo already holds shared setup.
cd ~/work/acmemv .crossrepo/config.yaml api/crossrepo.yamlln -s ../api/crossrepo.yaml .crossrepo/config.yamlThen commit and push crossrepo.yaml in api.
2. In a new meta repo. Good when the config, hook scripts and shared files such as AGENTS.md belong together. Make an empty repo meta on your git host, then:
cd ~/work/acmegit clone git@github.com:acme/meta.gitmv .crossrepo/config.yaml meta/crossrepo.yamlln -s ../meta/crossrepo.yaml .crossrepo/config.yamlThen commit and push crossrepo.yaml in meta. meta is a normal repo for crossrepo. To have a worktree of it in your projects, add it with xr codebase repo add ./meta (see xr codebase repo add). Like every repo, it needs an origin remote and origin/HEAD. A clone of an empty repo has no origin/HEAD, so after the first push run git -C meta remote set-head origin --auto.
A teammate clones the repo with the config into a new codebase folder, makes the same symlink, and runs xr codebase clone to clone the other repos:
mkdir -p ~/work/acme/.crossrepo && cd ~/work/acmegit clone git@github.com:acme/meta.gitln -s ../meta/crossrepo.yaml .crossrepo/config.yamlxr codebase cloneOn Windows, make the symlink in cmd with mklink. It needs Developer Mode turned on, or a shell run as administrator:
mklink .crossrepo\config.yaml ..\meta\crossrepo.yaml