Quick start
This page goes from a folder of repos to a first project and back. It takes four xr commands. Install xr first, see Install.
The output on this page comes from a real run of xr in a test folder. The test repos have local origin remotes, so the remotes show as ~/origins/api.git. Yours show your real URLs, such as git@github.com:acme/api.git. Your commit ids differ too.
1. Start with a folder of repos
Section titled “1. Start with a folder of repos”Put the repos you work on side by side in one folder. Clone each one with git clone, so each has an origin remote and origin/HEAD:
~/work/acme/ api/ web/If a repo has no origin/HEAD, for example because you made it with git init and git remote add, the next step fails with repos-not-ready, writes nothing, and prints the fix for each repo:
$ xr codebase init✓ api: main✗ web: no origin/HEADerror: 1 repo is not ready: web.Run the fix for each repo, then run `xr codebase init` again.
web no origin/HEAD git -C "/Users/you/work/acme/web" remote set-head origin --auto2. Make the folder a codebase
Section titled “2. Make the folder a codebase”$ cd ~/work/acme$ xr codebase init✓ api: main✓ web: mainCreate .crossrepo/…✓ Create .crossrepo/Write .crossrepo/config.yaml…✓ Write .crossrepo/config.yamlWrite AGENTS.md…✓ Write AGENTS.md~/work/acme
api ~/origins/api.git mainweb ~/origins/web.git mainxr codebase init writes the codebase config .crossrepo/config.yaml with each repo, its remote and its default branch. It also writes a ## Codebase section in AGENTS.md. It never commits. See xr codebase init and the config guide.
3. Create a project
Section titled “3. Create a project”A project is one branch in many repos. --all takes every repo of the codebase, so no picker opens:
$ xr project create feat/login --allFetch api…✓ Fetch apiFetch web…✓ Fetch webMake project folder…✓ Make project folderAdd worktree api…✓ Add worktree apiAdd worktree web…✓ Add worktree webWrite project record…✓ Write project recordWrite AGENTS.md…✓ Write AGENTS.md.projects/feat--login
feat/login
✓ api: new branch from origin/main✓ web: new branch from origin/mainThe project folder is .projects/feat--login/: each / of the branch becomes --. It has one git worktree of each repo, all on the branch feat/login:
~/work/acme/.projects/feat--login/ .crossrepo/ AGENTS.md api/ web/To take only some repos, give their names instead of --all, such as xr project create feat/login api. See xr project create.
4. Work in the project folder
Section titled “4. Work in the project folder”Each repo folder in the project is a normal git worktree. Edit, commit and push there as usual. Your repos in ~/work/acme/ stay on their own branch.
cd ~/work/acme/.projects/feat--login/api# edit filesgit commit -am "Add login"cd ~/work/acmexr does not look in parent folders. Run xr in the codebase folder or in the project folder, not in a worktree folder inside it.
5. Sync the project
Section titled “5. Sync the project”When the default branch gets new commits, bring them into the project. Give the project name, so no picker opens:
$ xr project sync feat--login✓ api: up to dateremote: Enumerating objects: 5, done.remote: Counting objects: 100% (5/5), done.remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0 (from 0)From ~/origins/web dd24034..474093f main -> origin/main✓ web: fast-forwarded to origin/main.projects/feat--login
feat/loginIn each worktree, xr project sync fetches origin and merges the default branch into the project branch. Your uncommitted changes stay. When a merge has a conflict, that repo shows conflict; see xr project sync for what to do.
6. Remove the project
Section titled “6. Remove the project”When the work is done, remove the project:
$ xr project remove feat--loginRemove worktree api…✓ Remove worktree apiRemove worktree web…✓ Remove worktree webRemove project folder…✓ Remove project folder.projects/feat--login
feat/login
✓ api: worktree removed, branch kept✓ web: worktree removed, branch keptThe worktrees and the project folder are gone. The branch feat/login stays in each repo. To delete merged branches too, add --delete-branch. When a worktree has uncommitted changes, the remove stops and changes nothing, unless you add --force. See xr project remove.
- Config guide: the config levels and keys, and how to keep the codebase config in git.
- Hooks guide: run your own commands before and after create and remove (
pre-create,post-create,pre-removeandpost-remove), for example to copy.envfiles. - Output and errors: text and JSON output, and the exit codes.
- xr doctor: when a step fails, check the codebase or the project and get the fix for each problem.