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.
At this point, it is very likely that you'll have merge conflicts in your root files.
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
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.
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!