😻 Herding Cats 😻

A CLI for managing multi-repo workspaces.

Why Herding Cats?

• You have a workspace containing multiple repos that you develop concurrently.
• You need a handy utility that clones all of the repos in the workspace when onboarding new developers.
• When feature development requires changes to multiple repos, you'd like a convenient way to check out the same branch in each repo.
• You don't want to use a monorepo because each repo has a different version number and you want use GitHub releases.

Why not a monorepo?

• Monorepos are great when all of the packages share the same version number. Not so much when packages have different versions.
• When packages have different version numbers, it's difficult to release them independently using GitHub releases.
• The version of the monorepo is meaningless when child packages have different versions.

Installation

# npm
$ npm i -g herding-cats

# yarn
$ yarn global add herding-cats

Usage

To pull down an existing project, run:

$ herd clone <leader-repo-url> <target-dir>

Concepts

Herding cats manages a workspace containing multiple repos. We call the workspace the "herd". One of the repos is the "herd leader". It holds the herding-cats.config.js file that lists all of the other repos in the herd. When you clone the herd using:

$ herd clone <leader-repo-url> <workspace-dir>

The second argument (workspace-dir) is the name of the new workspace directory that will be created. You should open your IDE here. The leader repo and all other repos in the herd will be cloned into the workspace directory. After cloning, if any repo has an init config in it's herding-cats.config.js, that script will be run to initialize tooling for that repo. You can put whatever you want in the init script. Generally it's used to download dependencies, for example by running npm install, or brew installing some packages.

Once the herd is cloned, you can run any of the following commands in any subdirectory of the workspace:

Commands

branch

$ herd branch

Shows the branch name currently checked out for each repo and flags the modified repos

cargo link

$ herd cargo link

Converts cargo depedencies that use git URLs to local relative paths so that all crates in the herd use their local counterparts if available.

clone

$ herd clone <leader-repo-url> <target-dir>

Clones the leader repo and all other repos into the specified directory. Use this command to pull down an existing herd.

checkout

$ herd checkout <branch>

Checks out the specified branch in the parent repo and each child repo, if it exists, otherwise keeps the repo on the current branch.

Use herd checkout --default to checkout the default branch in each repo.

init

$ herd init

Pulls down all child repos listed in the herd leader's herding-cats.config.js

pull

$ herd pull

Pulls down the latest commits for the parent repo and each child repo. Any additional options will be passed along to git pull.

run

$ herd run [some command...]

Runs the specified command in each repo

status

$ herd status

Outputs git status for the parent repo and each child repo that has local changes

Config

Herding-cats is configured via the herding-cats.config.js file in each repo in the workspace. Here are the supported keys:

repos

(Optional, leader repo only)

An array of child repo URLs. The array can contain a mix of strings and objects. To override the default branch that is checked out for each repo, use:

module.exports = {
  repos: [
    '[email protected]:some-org/some-repo.git', // will check out the main branch,
    { repo: '[email protected]:some-org/some-other-repo.git', branch: 'master' }, // will check out the master branch
  ],
}

defaultBranch

(Optional, leader repo only)

Sets the default branch to checkout for each child repo. Defaults to main.

module.exports = {
  defaultBranch: 'master',
  repos: [
    '[email protected]:some-org/some-repo.git', // will check out the master branch,
    { repo: '[email protected]:some-org/some-other-repo.git', branch: 'main' }, // will check out the main branch
  ],
}

init

(Optional)

The path to a shell script to run when the repo is checked out.

module.exports = {
  init: './some/shell/script.sh',
}