README-SUBMODULES.md

   1 # How to convert Mercurial Repositories with subrepos
   2
   3 ## Introduction
   4
   5 hg-fast-export supports migrating mercurial subrepositories in the
   6 repository being converted into git submodules in the converted repository.
   7
   8 Git submodules must be git repositories while mercurial's subrepositories can
   9 be git, mercurial or subversion repositories. hg-fast-export will handle any
  10 git subrepositories automatically, any other kinds must first be converted
  11 to git repositories. Currently hg-fast-export does not support the conversion
  12 of subversion subrepositories. The rest of this page covers the conversion of
  13 mercurial subrepositories which require some manual steps:
  14
  15 The first step for mercurial subrepositories involves converting the
  16 subrepository into a git repository using hg-fast-export.  When all
  17 subrepositories have been converted, a mapping file that maps the mercurial
  18 subrepository path to a converted git submodule path must be created. The
  19 format for this file is:
  20
  21 "<mercurial subrepo path>"="<git submodule path>"
  22 "<mercurial subrepo path2>"="<git submodule path2>"
  23 ...
  24
  25 The path of this mapping file is then provided with the --subrepo-map
  26 command line option.
  27
  28 ## Example
  29
  30 Example mercurial repo folder structure (~/mercurial) containing two subrepos:
  31     src/...
  32     subrepos/subrepo1
  33     subrepos/subrepo2
  34
  35 ### Setup
  36 Create an empty new folder where all the converted git modules will be imported:
  37     mkdir ~/imported-gits
  38     cd ~/imported-gits
  39
  40 ### Convert all submodules to git:
  41     mkdir submodule1
  42     cd submodule1
  43     git init
  44     hg-fast-export.sh -r ~/mercurial/subrepos/subrepo1
  45     cd ..
  46     mkdir submodule2
  47     cd submodule2
  48     git init
  49     hg-fast-export.sh -r ~/mercurial/subrepos/subrepo2
  50
  51 ### Create mapping file
  52     cd ~/imported-gits
  53     cat > submodule-mappings << EOF
  54     "subrepos/subrepo1"="../submodule1"
  55     "subrepos/subrepo2"="../submodule2"
  56     EOF
  57
  58 ### Convert main repository
  59     cd ~/imported-gits
  60     mkdir git-main-repo
  61     cd git-main-repo
  62     git init
  63     hg-fast-export.sh -r ~/mercurial --subrepo-map=~/imported-gits/submodule-mappings
  64
  65 ### Result
  66 The resulting repository will now contain the submodules at the paths
  67 `subrepos/subrepo1` and `subrepos/subrepo2`. The created .gitmodules
  68 file will look like:
  69
  70     [submodule "subrepos/subrepo1"]
  71           path = subrepos/subrepo1
  72           url = ../submodule1
  73     [submodule "subrepos/subrepo2"]
  74           path = subrepos/subrepo2
  75           url = ../submodule2