Index: llvm/docs/Proposals/GitHubMove.rst
===================================================================
--- llvm/docs/Proposals/GitHubMove.rst
+++ llvm/docs/Proposals/GitHubMove.rst
@@ -853,6 +853,94 @@
 less like to encounter a build failure where a commit change an API in LLVM and
 another later one "fixes" the build in clang.
 
+Moving Branches to the Monorepo
+===============================
+
+Suppose you have been developing against an LLVM git repository -- either the
+multirepo or one of the existing monorepos.  You have one or more git branches
+that you want to migrate to the "final monorepo".
+
+One Monorepo to Another, No Merges
+----------------------------------
+
+The simplest case is if you have a branch with linear history (i.e. no merges
+between the branch and upstream) and you're migrating from one monorepo to
+another.  We'll first explain how to handle this, then expand it to more
+complicated cases.::
+
+  # Check that my-branch has linear history, i.e. never merges with
+  # `origin/master`.  A hacky way to do this is to find all merge commits in
+  # my-branch that are not in origin/master.
+  $ diff <(git log --pretty=%H --merges origin/master | sort) \
+         <(git log --pretty=%H --merges my-branch | sort) | grep '^>'
+
+  # If the output above is not empty, then skip down to the `With Merges`
+  # section below.  If the output *is* empty, continue below.
+
+  # Check that the set of commits in your branch looks right.
+  git log $(git merge-base origin/master my-branch)..my-branch
+
+  # Looks good, let's export a patch for each of the commits!
+  $ git format-patch -o /tmp/my-branch-patches \
+    $(git merge-base origin/master my-branch)..my-branch
+
+  # Make a note of the commit metadata of the merge-base, i.e. the newest
+  # common ancestor between your branch and origin/master.  Call this commit
+  # <old-base-commit>.
+  $ git log -n1 --pretty="%aD %at" $(git merge-base origin/master my-branch)
+
+  # Now we're ready to move into the new monorepo!
+  $ cd ../new-monorepo
+
+  # First we have to figure out which commit corresponds to the commit we
+  # showed above.  Call this <new-base-commit>.
+  $ git checkout origin/master
+  $ git log -n1 --since <date from old-base-commit> \
+      --author <author from old-base-commit>
+
+  # <new-base-commit> and <old-base-commit> will have different hashes, but
+  # they should point to the same logical commit.  Double-check this manually.
+
+  # Make the new branch in the new monorepo and import the patches.
+  $ git checkout -b my-branch <new-base-commit>
+  $ git am /tmp/my-branch-patches/*
+
+Multirepo to Monorepo, No Merges
+--------------------------------
+
+To do the same thing as above but from a multirepo to a monorepo (e.g. from
+https://github.com/llvm-mirror/llvm to the monorepo), follow the same steps
+above, just add `--directory=llvm` to the `git am` call.
+
+One Monorepo to Another, With Merges
+------------------------------------
+
+Suppose you have a branch on an old monorepo that *has* merges between it and
+`origin/master`, and you want to migrate this branch to the new monorepo.  In
+this case we recommend pulling the old and new monorepos into the one
+repository and doing a merge between them.::
+
+  $ git remote add final-monorepo https://github.com/<final monorepo>
+  $ git fetch final-monorepo
+  $ git checkout my-branch
+
+  # You could do `git merge final-monorepo/master`, but this will require
+  # updating your branch to HEAD.  Alternatively, we can figure out the merge
+  # base between my-branch and origin/master, translate that hash into
+  # final-monorepo, and merge with that.
+  #
+  # As above, we find the merge-base and then translate it:
+  $ git log -n1 --pretty="%aD %at" $(git merge-base origin/master my-branch)
+  $ git log -n1 --since <date from old-base-commit> \
+      --author <author from old-base-commit>
+  $ git merge <new-base-commit>
+
+Multirepo to Monorepo, With Merges
+----------------------------------
+
+If you have a branch on an old *multirepo* and have merges, you'll want to
+follow the steps above but pass `-s subtree` to do a subtree-merge, see
+https://git-scm.com/book/en/v1/Git-Tools-Subtree-Merging.
 
 References
 ==========