meta — Multi-Repo Orchestration

meta solves the mono-repo vs. many-repos dilemma by saying "both". A meta repo is a thin git repository that contains a .meta config file listing child repositories; meta commands then fan out across all those children at once. Unlike git submodules or subtree, child repos remain independent first-class git repos — different teams can clone just the slice they need. The plugin architecture (commander.js, meta-* npm packages) means you can extend meta to wrap any CLI tool, not just git.

---

When to use this skill

Trigger this skill when the user:

• Wants to clone an entire multi-repo project in one command
• Needs to run a git command (status, checkout, pull) across all child repos
• Wants to run an arbitrary shell command against every repo (meta exec)
• Is migrating a monorepo into many repos using meta project migrate
• Needs to run npm install or yarn across all repos at once
• Asks how to add or import a child repo into a meta project
• Wants to onboard a new developer to a multi-repo architecture
• Needs to filter commands to a subset of repos (--include-only)

Do NOT trigger this skill for:

• Single-repo builds managed with Turborepo or Nx — use the monorepo-management skill
• Docker/container orchestration even when containers span many repos

---

Setup & authentication

# Install meta globally
npm i -g meta

# Initialise a brand-new meta repo
mkdir my-meta-repo && cd my-meta-repo && git init
meta init

# Add child repos
meta project create services/api git@github.com:yourorg/api.git
meta project import packages/ui git@github.com:yourorg/ui.git

# Clone an existing meta repo (clones meta repo + all children)
meta git clone git@github.com:yourorg/my-meta-repo.git

The .meta file (JSON) is the only config that meta requires. It is committed to the meta repo and checked out with the meta repo itself. Child directories are automatically added to .gitignore — they are not nested inside the meta repo's git object store.

{
  "projects": {
    "services/api": "git@github.com:yourorg/api.git",
    "packages/ui":  "git@github.com:yourorg/ui.git"
  }
}

---

Core concepts

The meta repo vs. child repos

The meta repo is a regular git repository that contains only orchestration artifacts: the .meta config, a root package.json (optional), a docker-compose.yml, a Makefile, etc. Child repos live at the paths listed in .meta and are independent git repos — each with its own remote, branches, and history. The meta repo never tracks child files.

.meta config file

The .meta file is plain JSON with a single projects map from local path to git remote URL. Editing it manually is valid; meta project create/import edits it for you and also updates .gitignore. Do not commit child directories.

Plugin architecture

Every meta sub-command is contributed by a plugin — an npm package named meta-<plugin>. Core plugins ship with meta: meta-init, meta-project, meta-git, meta-exec, meta-npm, meta-yarn. Install third-party plugins globally or as devDependencies in the meta repo.

loop under the hood

meta is built on loop, which provides --include-only and --exclude filtering so commands can target a subset of child repos. This is useful for running commands only on repos that have changed or belong to a particular team.

---

Common tasks

1. Clone a meta project (new developer onboarding)

meta git clone git@github.com:yourorg/my-meta-repo.git
cd my-meta-repo
# All child repos are now cloned into their configured paths

2. Run a git command across all repos

meta git status          # status in every child repo
meta git pull            # pull latest in every child repo
meta git checkout main   # check out main in every child repo

3. Execute an arbitrary shell command

# Run any shell command in every child repo
meta exec "npm ci"
meta exec "npm run build" --parallel   # run in parallel
meta exec "echo \$(pwd)"               # use shell expansions (escape $)

4. Run npm/yarn commands across all repos

meta npm install         # npm install in every child repo
meta npm run test        # run the test script everywhere
meta yarn install        # yarn equivalent

5. Add or import a child repo

# Create a new repo entry (registers remote, does NOT init a new git repo)
meta project create services/worker git@github.com:yourorg/worker.git

# Import an existing repo that is already cloned locally
meta project import packages/shared git@github.com:yourorg/shared.git

Both commands update .meta and .gitignore automatically.

6. Migrate a monorepo to a meta repo

cd existing-monorepo
meta init
# For each package to extract:
meta project migrate packages/auth git@github.com:yourorg/auth.git
meta project migrate packages/api  git@github.com:yourorg/api.git

meta project migrate moves the directory out of the monorepo's git history into a fresh repo at the given remote URL, then registers it in .meta.

7. Target a subset of repos

# Only run in specific repos
meta git status --include-only services/api,services/worker

# Exclude a repo
meta exec "npm run lint" --exclude packages/legacy

8. Update child repos after pulling new meta config

# After someone else added a new child repo to .meta:
git pull origin main
meta git update   # clones any new repos listed in .meta

---

Error handling

Error	Cause	Resolution
fatal: destination path already exists	Child repo directory exists but is not registered in .meta	Delete the directory or run meta project import to register it
Command runs in meta root but not in children	.meta projects map may be empty or path is wrong	Check .meta contents; ensure paths match actual directory layout
meta: command not found	meta is not installed globally	Run npm i -g meta
Child repos not cloned after git pull	New entries added to .meta without running update	Run meta git update to clone newly listed repos
Shell expression expands in meta context, not child	$VAR or backticks unescaped	Escape: meta exec "echo \$(pwd)" or meta exec "echo \pwd`"`

---

Gotchas

1. Child repo directories are in .gitignore but still show up as untracked if .gitignore was edited manually - meta project create/import appends to .gitignore automatically. If you manually edit .meta without using the meta project command, the corresponding path is never added to .gitignore, and the child repo's contents leak into the meta repo's git status. Always use meta project create or meta project import rather than editing .meta directly.

2. meta git clone requires SSH key access to every child repo - The clone command attempts to clone all repos listed in .meta in parallel. If your SSH key lacks access to even one child repo, that clone fails and the error is easy to miss in the parallel output. Check that the cloning user has access to all repos before running meta git clone for a new developer.

3. Shell variable expansion happens in the meta context, not the child repo context - meta exec "echo $PWD" expands $PWD to the meta repo root before fanout, so every child repo prints the same (wrong) path. Escape the variable: meta exec "echo \$PWD" to expand it inside each child's shell.

4. meta git update does not pull - it only clones missing repos - After a teammate adds a new child repo to .meta and you pull the meta repo, your existing child repos are not updated. You need to run meta git update to clone the newly listed repos, then separately run meta git pull to update all existing repos. Confusing these two commands is a common source of stale code.

5. Plugins must be installed globally, not just as devDependencies - meta resolves plugin commands from the global node_modules. A plugin listed only in the meta repo's package.json devDependencies will not be found when running meta commands unless it is also installed globally or the repo's node_modules/.bin is in PATH. Install frequently used plugins with npm i -g meta-<plugin>.

---

References

• references/commands.md — complete command reference with all flags for meta git, meta exec, meta project, meta npm, and meta yarn

Load references/commands.md when the user asks about a specific flag or wants a full list of available sub-commands.