preserving-git-histories.md: Move files _before_ merging (#20289)

Co-authored-by: Isaac Mann <[email protected]>

Author: nocnokneo

docs/shared/migration/preserving-git-histories.md

@@ -10,36 +10,31 @@ Git has some helpful tools for this, and we'll walk through some of the common p
 
 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:
+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](/recipes/adopting-nx/manual) page, but when migrating an existing project, you'll want to ensure that you use [`git mv`](https://git-scm.com/docs/git-mv) when moving a file or directory to ensure that file history from the old standalone repo is not lost!
+
+In order to avoid merge conflicts later, it's best to first do the folder reorganization in the _standalone project repo_. For example, assuming you want the standalone app to end up at `apps/my-standalone-app` in the monorepo and your main branch is called `master`:
 
 ```shell
-git remote add my-standalone-app <repository url>
+cd my-standalone-app
+git fetch
+git checkout -b monorepo-migration origin/master
+mkdir -p apps/my-standalone-app
+git ls-files | sed 's!/.*!!'| uniq | xargs -i git mv {} apps/my-standalone-app
+git commit -m "Move files in preparation for monorepo migration"
+git push -u
 ```
 
-Now we must fetch the branches from the new remote
+Next, in your monorepo, we'll add a remote repository url for where the standalone app is located:
 
 ```shell
+git remote add my-standalone-app <repository url>
 git fetch my-standalone-app
 ```
 
-Assuming that our main branch on this repo is called 'master', then we'll run
+Then we'll run
 
 ```shell
-git merge my-standalone-app/master --allow-unrelated-histories
+git merge my-standalone-app/monorepo-migration --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`, `project.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 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](/recipes/adopting-nx/manual) page, but when migrating an existing project, you'll want to ensure that you use [`git mv`](https://git-scm.com/docs/git-mv) when moving a file or directory to ensure that file history from the old standalone repo is not lost!