README-SUBMODULES.md

   1 # How to convert Mercurial Repositories with subrepos
   2
   3 ## Introduction
   4
   5 Subrepositories must first be converted in order for the conversion of
   6 the super repository to know how hg commits map to git commits in the
   7 sub repositories.  When all subrepositories have been converted, a
   8 mapping file that maps the mercurial subrepository path to a converted
   9 git submodule path must be created. The format for this file is:
  10
  11 "<mercurial subrepo path>"="<git submodule path>"
  12 "<mercurial subrepo path2>"="<git submodule path2>"
  13 ...
  14
  15 The path of this mapping file is then provided with the --subrepo-map
  16 command line option.
  17
  18 ## Example
  19
  20 Example mercurial repo folder structure (~/mercurial):
  21     src/...
  22     subrepo/subrepo1
  23     subrepo/subrepo2
  24
  25 ### Setup
  26 Create an empty new folder where all the converted git modules will be imported:
  27     mkdir ~/imported-gits
  28     cd ~/imported-gits
  29
  30 ### Convert all submodules to git:
  31     mkdir submodule1
  32     cd submodule1
  33     git init
  34     hg-fast-export.sh -r ~/mercurial/subrepo1
  35     cd ..
  36     mkdir submodule2
  37     cd submodule2
  38     git init
  39     hg-fast-export.sh -r ~/mercurial/subrepo2
  40
  41 ### Create mapping file
  42     cd ~/imported-gits
  43     cat > submodule-mappings << EOF
  44     "subrepo/subrepo1"="../submodule1"
  45     "subrepo/subrepo2"="../submodule2"
  46     EOF
  47
  48 ### Convert main repository
  49     cd ~/imported-gits
  50     mkdir git-main-repo
  51     cd git-main-repo
  52     git init
  53     hg-fast-export.sh -r ~/mercurial --subrepo-map=../submodule-mappings
  54
  55 ### Result
  56 The resulting repository will now contain the subrepo/subrepo1 and
  57 subrepo/subrepo1 submodules. The created .gitmodules file will look
  58 like:
  59
  60     [submodule "subrepo/subrepo1"]
  61           path = subrepo/subrepo1
  62           url = ../submodule1
  63     [submodule "subrepo/subrepo2"]
  64           path = subrepo/subrepo2
  65           url = ../submodule2