How to Spin Out From A Monorepo

Are you using a monorepo in git? Do you need to spin out a project to its own repo. This quick guide will walk you through the process.

Step 1: Create the Spinoff Repo

If you’ve not done so already, you can go ahead and create the new repo where you want to land the project. We’re going to fully replace the default contents, but it’s easiest if you go ahead and accept defaults to create a Readme. (Otherwise, you won’t have a branch to push to.)

Step 2: Make a new clone of the monorepo and filter its results

Important: DO NOT do this on your existing clone of the repo. Instead, create a subfolder called ‘temp-deleteme’ and then clone your monorepo into this subdirectory. It may also be a good idea to rename the repo directory after you clone it, which will ensure you don’t confuse this copy with your ‘real’ copy.

Step 3: Install and Run ‘git-filter-repo’

Note: these code samples use ‘airbyte’ as the monorepo name and ‘airbyte-lib’ is the project we want to spin out into its own repo.

# Install the filter-repo tool
brew install git-filter-repo

# Move to your newly cloned copy of the monorepo
cd temp-deleteme/airbyte

# Filter the copy of the monorepo, and move the subdirectory to root
git filter-repo --force --path airbyte-lib/  --path-rename airbyte-lib/:

Step 4: Pull in Changes to the New Repo

# Move to the clone of the new (mostly empty) repo
cd temp-deleteme/airbyte-lib

# Create a 'monorepo' remote based on the filtered local clone
git remote add monorepo ../airbyte
git fetch monorepo
git merge monorepo/master --allow-unrelated-histories

Step 5: Double-check Your Changes and then Push Changes

At this point, you can double-check the new repo has the content you expected.

If so, then you can push to your new repo.

# Make sure you are in the new repo and not the monorepo
cd temp-deleteme/airbyte-lib

# Push your changes to origin
git push origin master

You should now have a new repo with all the relevant commits from your subdirectory and with none of the extra history from unrelated directories.

Step 6: Clean Up

If everything looks good, you can delete the directory that holds the filtered copy of your repo and remove the ‘monorepo’ remote from your clone of the repo.

Nice work!