Skip to content
Source
Sign inSign up

Clone and sync a monorepo

You change acme/web and acme/docs together, and you want to see both changes on your machine before you push. Cloning each repository by hand, in the right folders, takes time, and new members are easy to miss.

src monorepo clone gets the monorepo and every member, each in its own folder. src monorepo sync keeps the checkout up to date.

You need src, logged in, and read access to the monorepo.

1. Clone the monorepo

src monorepo clone acme/platform

The home page of the monorepo shows this command in its Members card.

src clones the monorepo, then each member in its folder, four at a time:

platform/            the monorepo's own clone
platform/web/        acme/web
platform/docs/       acme/docs
  • Each member folder is a normal git clone, with its own .git. Your editor, your scripts and git work as usual.
  • The root clone lists the member folders in its .git/info/exclude. So git status at the root does not show them.
  • If a member fails to clone, src names it, clones the others, and exits 1.

To clone into another folder, add it: src monorepo clone acme/platform work.

2. Make your change

Work in each member folder as in any clone:

cd platform/docs
git switch -c new-guide
# edit, then:
git commit -am "Add the new guide"
git push -u origin new-guide

To review and merge the changes of all folders together, open one monorepo pull request. See Change several members in one pull request.

3. Sync the checkout

At the root of the checkout, run:

src monorepo sync
  • It fetches each member. It does not change your branches. To update a branch, run git pull in its folder.
  • It clones the members that were added since your last sync.
  • It names the folders of members that were removed: docs: not a member any more; left in place. It never deletes a folder.
  • If the folder of a member is not a clone of that member, it skips that member, syncs the others, and exits 1.

Run src monorepo sync in the root clone, not in a member folder.

4. See where each folder is

src monorepo status
FOLDER  REPOSITORY      BRANCH     AHEAD  BEHIND
.       acme/platform   main       0      0
docs    acme/docs       new-guide  1      0
web     acme/web        main       0      2

Each row shows the branch of the folder, and how many commits it is ahead of and behind the default branch on origin. A member that is not in the checkout shows not cloned. Add --json for a script.

Done

All members are side by side on your machine. You change them together, and src monorepo status shows which folders have work to push.

Search across the members

  • src monorepo search issues "login fails" finds issues and pull requests in the monorepo and in every member.
  • src monorepo search code "createRouter" finds code on the default branch of each member. It shows each match under its folder.

The code search has caps on the bytes that it reads and on the size of the result. When it stops at a cap, it says that the result is cut.

Without src

The REST route GET /api/v1/repos/acme/platform/members gives the members and a recipe: the plain git commands that make the same checkout. For example:

git clone https://gitflare.t-zlak97.workers.dev/acme/platform.git platform
cd platform
git clone https://gitflare.t-zlak97.workers.dev/acme/web.git web
git clone https://gitflare.t-zlak97.workers.dev/acme/docs.git docs
printf '/web/\n' >> .git/info/exclude
printf '/docs/\n' >> .git/info/exclude