Skip to content

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.

Terminal window
cd ~/code/shop
xr codebase init

Run it in a folder that is not a codebase or a project yet. In any other folder, use --codebase-path <path>.

  1. It finds the repos: each folder directly in the codebase folder that has a .git file or folder, sorted by name. A .git in the codebase folder itself is ignored, and subfolders deeper down are not searched. A symlink to a repo folder is skipped.
  2. It reads two things from each repo, with no network call:
    • the origin remote URL, exactly as it is written in the repo’s git config;
    • the default branch, from origin/HEAD.
  3. It makes the .crossrepo/ folder.
  4. It writes .crossrepo/config.yaml.
  5. It writes the ## Codebase section of AGENTS.md. The rest of AGENTS.md stays as it is. When there is no AGENTS.md, it makes one. It never writes CLAUDE.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.

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.

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 || true

With 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.

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: main
Create .crossrepo/…
✓ Create .crossrepo/
Write .crossrepo/config.yaml…
✓ Write .crossrepo/config.yaml
Write AGENTS.md…
✓ Write AGENTS.md
~/code/shop
api git@github.com:acme/api.git main
web git@github.com:acme/web.git main

With --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.

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.