Forge-to-Gitlab-migration-FAQ.md

@@ -44,6 +44,8 @@ INRIA gitlab is restricted to git (no subversion anymore), so for subversion use
 
 You need to decide if you want to migrate just the tip of your development history (last version on the repository) or if you want to migrate the whole commits / branching / tags history. Note that in several situations, there is no real need to migrate the whole history. For example if you keep a project only for historical reference, you may not need all the commit history.
 
+In the following examples, we assume that the gitlab project is already created, correctly setup, and empty. The user performing the migration has a gforge account <forge_user>, a gforge project with unixname <forge_project>, a gitlab account <gitlab_user> and a gitlab project in the <gitlab_user> namespace, with name <gitlab_project>.
+
 ### Migrating only the last version of the repository
 
 Get the last version of the development tree (git or subversion), and import this in a new gitlab repository. All history is lost.
@@ -52,9 +54,7 @@ Get the last version of the development tree (git or subversion), and import thi
 
 #### From Subversion
 
-Checkout the subversion repository with git-svn (https://git-scm.com/docs/git-svn). It creates a git repository from the subversion repository (with all the history). You can then add your gitlab project as a git remote and push to that project.
-
-example with a user with forge account <forge_user>, a forge project with unixname <forge_project>, a gitlab account <gitlab_user> and a gitlab project in the <gitlab_user> namespace, with name <gitlab_project>:
+Checkout the subversion repository with git-svn (https://git-scm.com/docs/git-svn). It creates a git repository from the subversion repository (with all the history). You can then add your gitlab project as a git remote and push to that project:
 
 ```
 git svn clone svn+ssh://<forge_user>@scm.gforge.inria.fr/svnroot/<forge_project>/
@@ -65,7 +65,13 @@ git push --set-upstream origin master
 
 #### From Git
 
-Checkout all relevant branches of the git repository, add the gitlab project as a new remote, and push all branches to that remote.
+A convenient way to migrate everything (all branches, all tags) in a single operation is to use a mirror checkout:
+
+```
+git clone --mirror git+ssh://<forge_user>@scm.gforge.inria.fr/gitroot/<forge_project>/<forge_project>.git
+cd <forge_project>.git
+git push --mirror git@gitlab.inria.fr:<gitlab_user>/<gitlab_project>.git
+```
 
 #### Filtering history