Introduction

Migrating to a monorepo architecture is becoming increasingly popular for managing multiple related projects. If you're working with Turborepo and need to merge an existing repository while preserving its git history, this guide will walk you through the entire process step by step.

This approach is particularly useful when consolidating multiple standalone repositories into a unified Turborepo workspace, ensuring you don't lose valuable commit history and maintaining proper project structure.

Note: This guide assumes you have basic familiarity with git commands and Turborepo concepts. If you're new to monorepos, consider reading about monorepo benefits first.

Prerequisites

git clone <repo-url> source-repo

Change the directory to the cloned repository:

cd source-repo

Step 2: Filter the source repository into its own subdirectory

For this step we will use the git filter-repo tool to filter the source repository into its own subdirectory, this will also filter the history of the repository.

git filter-repo --to-subdirectory-filter folder-name

Replace folder-name with the desired subdirectory for this repository in the monorepo.

Step 3: Push the Filtered Repo to the Monorepo

Add the monorepo as a remote:

git remote add monorepo <monorepo-url>

Push the filtered history to a unique branch (e.g., old-repo-1):

git push monorepo HEAD:refs/heads/old-repo-1

In the monorepo

Fetch and merge the source repository history into the monorepo:

git fetch origin old-repo-1
git merge --allow-unrelated-histories old-repo-1

This command will merge the source repository history into our Turborepo, now you just need to move your files to the correct location in the monorepo and you are good to go.

I hope this article was helpful to you, if you have any questions or suggestions, feel free to reach out to me in the comments below.