xr codebase init
xr codebase init makes the current folder a codebase. It finds the git repos directly in the folder and writes them to the codebase config.
cd ~/code/shopxr codebase initRun it in a folder that is not a codebase or a project yet. In any other folder, use --codebase-path <path>.
What it does
Section titled “What it does”- It finds the repos: each folder directly in the codebase folder that has a
.gitfile or folder, sorted by name. A.gitin the codebase folder itself is ignored, and subfolders deeper down are not searched. A symlink to a repo folder is skipped. - It reads two things from each repo, with no network call:
- the
originremote URL, exactly as it is written in the repo’s git config; - the default branch, from
origin/HEAD.
- the
- It makes the
.crossrepo/folder. - It writes
.crossrepo/config.yaml. - It writes the
## Codebasesection ofAGENTS.md. The rest ofAGENTS.mdstays as it is. When there is noAGENTS.md, it makes one. It never writesCLAUDE.md.
Steps 3 to 5 are all-or-nothing. When a step fails, the steps that are done are undone, so the folder is as it was before. When an undo also fails, the error lists what is left and the command to remove it.
It never runs git init, never commits and never changes .gitignore. If any repo has no origin remote or no origin/HEAD, nothing is written, and the error lists each such repo with the git command that fixes it.
It needs git 2.27 or newer.
Lock and Ctrl-C
Section titled “Lock and Ctrl-C”xr codebase init takes the codebase lock, .crossrepo/xr.lock, right after step 3 makes .crossrepo/, and deletes it at the end. While it runs, another xr command that changes files in this folder fails with lock-held.
Ctrl-C during steps 3 to 5 undoes the steps that are done: .crossrepo/ is deleted, a new AGENTS.md is deleted, and an old AGENTS.md gets its old text back. Then xr exits with code 130 and the interrupted error. Ctrl-C during steps 1 and 2 stops xr at once, before anything is written. See Lock and Ctrl-C.
The config
Section titled “The config”Each repo gets its remote, its default-branch and an empty description. The file also has 4 hook examples that are commented out, one for each hook: pre-create stops the create when a tool is missing, post-create copies untracked files such as .env into each new worktree, pre-remove stops a remove when a worktree has commits that are not pushed, and post-remove cleans up what post-create started outside the project folder. See the hooks guide.
# crossrepo codebase config. Docs: https://alexsuprun.github.io/crossrepo/repos: api: remote: git@github.com:acme/api.git default-branch: main description: ""
# project:# pre-create:# # Stop the create before it makes anything when a tool is missing.# - command -v node >/dev/null || { echo "node is not installed"; exit 1; }# post-create:# # Copy untracked files, such as .env, into each new worktree.# - |# printf '%s\n' "$CROSSREPO_PROJECT_REPOS" | while read -r repo; do# cp "$CROSSREPO_CODEBASE_PATH/$repo/.env" "$CROSSREPO_PROJECT_PATH/$repo/" 2>/dev/null || true# done# pre-remove:# # Stop the remove when a worktree has commits that are not pushed.# - |# printf '%s\n' "$CROSSREPO_PROJECT_REPOS" | while read -r repo; do# if [ -n "$(git -C "$CROSSREPO_PROJECT_PATH/$repo" log '@{upstream}..' --oneline)" ]; then# echo "$repo has unpushed commits"; exit 1# fi# done# post-remove:# # Clean up outside the project folder after it is removed, such as a tmux session with the name of the project.# - tmux kill-session -t "$CROSSREPO_PROJECT_NAME" 2>/dev/null || trueWith no repos, the config has repos: {}. Add repos later with xr codebase repo add <url>|<folder>.
Edit the file by hand to add a description or other keys. See xr config show for how the config files work.
Output
Section titled “Output”stderr gets one line for each repo with its default branch, then one line for each step. stdout gets the codebase folder and one line for each repo added: its name, its remote and its default branch.
✓ api: main✓ web: mainCreate .crossrepo/…✓ Create .crossrepo/Write .crossrepo/config.yaml…✓ Write .crossrepo/config.yamlWrite AGENTS.md…✓ Write AGENTS.md~/code/shop
api git@github.com:acme/api.git mainweb git@github.com:acme/web.git mainWith --json, stdout is one JSON object. codebase is the absolute path of the folder. added has one item for each repo.
{ "ok": true, "warnings": [], "codebase": "/home/me/code/shop", "added": [ { "repo": "api", "remote": "git@github.com:acme/api.git", "defaultBranch": "main" } ]}With no repos, added is empty and notes has the hint to add a repo.
Errors
Section titled “Errors”| Code | When |
|---|---|
already-a-codebase |
The folder has .crossrepo/config.yaml or config.yml, or a .crossrepo/ folder with no config. Nothing changes. The hint says how to add a repo or start again. |
inside-a-project |
The folder is a project. Nothing changes. |
repos-not-ready |
A repo has no origin remote or no origin/HEAD. Nothing is written. error.details.repos lists each repo as { "repo", "problem", "fix" }, where fix is the git command to run. |
git-too-old |
git is older than 2.27. The message has the version found. |
git-failed |
A git command failed, for example in a broken repo. |
lock-held |
Another xr command holds the lock of this folder. Nothing is written. |
interrupted |
You pressed Ctrl-C during steps 3 to 5. The steps that were done are undone. The exit code is 130. |
When a step fails and an undo also fails, error.details.leftovers lists each thing left as { "what", "path", "command" }. The same is true after Ctrl-C.
See Output and errors for the exit codes.