A multi-repo workspace groups several repositories into one workspace, so agents can work across related repos at the same time. This article covers the two ways to set one up and how you work in it.
Why multi-repo
Real systems are often split across repositories — an application in one, its infrastructure in another — that still have overlapping needs. A multi-repo workspace lets you pull them together and work on them side by side instead of hopping between separate workspaces.
Two ways to combine repos
- Permanent — define a multi-repo workspace that always exists in source. Here the parent workspace is itself a repo, with the other repos nested under it.
- On the fly — join repos together temporarily for whatever you're doing right now. This creates a workspace whose top level is just a container (not a repo itself), with the joined repos as children. Handy when repos have overlapping needs only occasionally.
Talk to one repo or the whole system
In a multi-repo workspace you can direct work at a specific repository or at the whole set at once. Each repo's worktrees are nested under it and stay isolated, so you can make changes and open separate pull requests in different repos side by side without them interfering.
Next steps
- Create your first worktree — worktrees work the same way inside a multi-repo workspace.
- Hooks: automate the busywork — scope hooks per repository in a multi-repo workspace.
- Core concepts & vocabulary — the terms behind workspaces and worktrees.