Preserving Git Histories when Migrating other Projects to your Nx Workspace

The nature of a monorepo is to swallow up standalone projects as your organization buys into the benefits of a monorepo workflow.

As your monorepo consumes other projects though, it's important to ensure that git history for those projects is preserved inside of our Nx Workspace.

Git has some helpful tools for this, and we'll walk through some of the common pitfalls and gotchas of this task!

Merging in a standalone project

To merge in another project, we'll essentially use the standard git merge command, but with a few lesser known options/caveats.

To start we'll add a remote repository url for where the standalone app is located:

git remote add my-standalone-app <repository url>

Assuming that our main branch on this repo is called 'master', then we'll run

git merge my-standalone-app/master --allow-unrelated-histories

Note that without the --allow-unrelated-histories option, the command would fail with the message: fatal: refusing to merge unrelated histories.

Merge Conflicts

At this point, it is very likely that you'll have merge conflicts in your root files.

For your package-lock.json or yarn.lock, it's likely best to remove those entirely and allow a new lock file to be generated by installing when the merge is complete.

For other files (think nx.json, workspace.json, angular.json, package.json, tsconfig.base.json, etc.) you'll need to resolve these conflicts manually to ensure that considerations for both your existing workspace and the newly added project are accounted for.

Note that for these files, the file history of the standalone project will be not be present after merging. You would see all changes from resolving conflicts in the single merge commit, and any further back would simply be the file history of your workspace.

Using git mv

If your standalone project was not an Nx workspace, it's likely that your migration work will also entail moving directories to match a typical Nx Workspace structure. You can find more information in the Manual migration page, but when migrating an existing project, you'll want to ensure that you use git mv when moving a file or directory to ensure that file history from the old standalone repo is not lost!