README

   1 = darcs backend for fast data importers
   2 Miklos Vajna <vmiklos-at-frugalware-dot-org>
   3
   4 == Purpose and Features
   5
   6 darcs-fast-export is a tool to dump a http://darcs.net/[darcs]
   7 repository in a format understood by "fast-importers" such as
   8 http://git.or.cz/[git]
   9 http://www.kernel.org/pub/software/scm/git/docs/git-fast-import.html[fast-import].
  10 It exhibits the following _features:_
  11
  12 Fast::
  13         darcs-fast-export provides a fast darcs backend for fast-import.
  14         See link:t/bench-results/[here] for exact details.
  15
  16 Correct::
  17         darcs-fast-export produces correct results in any extreme cases.
  18         It has been tested with a collection of large darcs repos (called
  19         http://code.haskell.org/darcs/big-zoo/[big-zoo]). And several testcases
  20         under the `t/` directory.
  21
  22 Independent::
  23         Ideally it should work with any fast importer, but actually it has been
  24         tested with git fast-import, bzr fast-import and hg fastimport. (These
  25         are the three fast-import implementations available ATM.)
  26
  27 Formats::
  28         It supports the 'darcs-2', 'hashed', and 'old-fashioned-inventory' darcs
  29         repository formats.
  30
  31 Incremental conversions::
  32         It supports the usual `--export-marks` / `--import-marks` switches to
  33         allow incremental conversion.
  34
  35 Wrapper scripts::
  36         A wrapper script called `d2x` is available if you find typing
  37         `--export-marks` / `--import-marks` all the time boring. A similar one
  38         is also provided for the other direction, called `x2d`.  Finally, if you
  39         want to work on darcs repos with git, you can use the `git-darcs`
  40         wrapper.
  41
  42 Author mappings::
  43         Supports `--authors-file` option like Git's SVN adaptor, for DARCS
  44         repositories that originated in CVS or SVN.
  45
  46 Import script::
  47         The pair of `darcs-fast-export`, `darcs-fast-import` is also
  48         included in this repo. It has been tested with the fast-expoters of Git,
  49         Hg, Bzr and - of course - Darcs itself.
  50
  51 Two-way sync::
  52         Using `darcs-fast-export` / `darcs-fast-import`, it is possible to
  53         convert a darcs repo to an other VCS, work there, then convert your work
  54         back to Darcs (or vica versa). This has been tested with "darcs -> git;
  55         hack hack; git -> darcs".
  56
  57 == Usage
  58
  59 See the manpages:
  60
  61 * link:darcs-fast-export.html[darcs-fast-export]
  62 * link:darcs-fast-import.html[darcs-fast-import]
  63 * link:d2x.html[d2x]
  64 * link:x2d.html[x2d]
  65 * link:git-darcs.html[git-darcs]
  66
  67 === Example
  68
  69 Assuming that `test/` is a darcs repo, you could do this:
  70 ----
  71 $ mkdir test.git
  72 $ cd test.git
  73 $ git --bare init
  74 $ cd ..
  75 $ darcs-fast-export test |(cd test.git; git fast-import)
  76 ----
  77
  78 For more examples (especially for bzr and hg), see the `t/` directory.
  79
  80 == Download
  81
  82 Using git:
  83 ----
  84 $ git clone git://vmiklos.hu/darcs-fast-export
  85 ----
  86
  87 == Status
  88
  89 In general, darcs-fast-export should work fine. darcs-fast-import has
  90 known problems with tags - other than that it should be okay. git-darcs
  91 should work properly as long as you are not paying too much attention to
  92 the imported tags (newly created tags won't be pushed back).
  93
  94 darcs-fast-export has been tested with the following versions:
  95
  96 Darcs version (see http://bugs.darcs.net/issue844[this bug] on why do
  97 you need such a new version):
  98 ----
  99 $ darcs --version
 100 2.2.0 (release)
 101 ----
 102
 103 Git version:
 104 ----
 105 $ git --version
 106 git version 1.6.0.2
 107 ----
 108
 109 Bzr versions:
 110 ----
 111 $ bzr version
 112 Bazaar (bzr) 1.12
 113 $ (cd ~/bzr/fastimport; bzr log --limit 1|grep revno)
 114 revno: 181
 115 ----
 116
 117 Yes, you need the fastiport plugin from BZR, the last hg release series
 118 supported by fastimport-0.6 is hg-1.0.x.
 119
 120 Mercurial (Hg) version:
 121 ----
 122 $ hg version
 123 Mercurial Distributed SCM (version 1.3)
 124 ----
 125
 126 Strictly speaking this document is a wrong place to talk about
 127 configuring hg fastimport. However... you will need something like:
 128
 129 ----
 130 $ hg clone http://vc.gerg.ca/hg/pyfastimport
 131 $ hg clone http://vc.gerg.ca/hg/hg-fastimport
 132 $ sudo ln -s /path/to/pyfastimport/fastimport /usr/lib/python2.6/site-packages/fastimport
 133 $ sudo ln -s /path/to/hg-fastimport/hgfastimport /usr/lib/python2.6/site-packages/hgfastimport
 134 echo -e "[extensions]\nfastimport = /usr/lib/python2.6/site-packages/hgfastimport" > ~/.hgrc
 135 ----
 136
 137 and once you installed the plugin correctly, you should have something like:
 138
 139 ----
 140 $ ls /usr/lib/python*/site-packages/hgext/fastimport/__init__.py
 141 /usr/lib/python2.5/site-packages/hgext/fastimport/__init__.py
 142 ----
 143
 144 == Additional resources
 145
 146 You can reach the Changelog link:Changelog[here], and a gitweb interface
 147 http://vmiklos.hu/gitweb/?p=darcs-fast-export.git[here].
 148
 149 The fast-import stream format documentation is
 150 http://git.kernel.org/?p=git/git.git;a=blob;f=fast-import.c;hb=HEAD[here]
 151 if you're interested.
 152
 153 == Alternatives
 154
 155 - http://repo.or.cz/w/darcs2git.git[darcs2git] tries to find conflict
 156   resolutions (to map them to merge commits), but it's rather slow
 157   because of this. It does not support the darcs2 format and/or
 158   incremental conversions, either. darcs-fast-export may support mapping
 159   to merge commits later, but not before
 160   http://bugs.darcs.net/issue1261[this issue] is addressed.
 161
 162 - http://progetti.arstecnica.it/tailor[tailor] is an any2any VCS
 163   converter, but it produces corrupted results when converting the
 164   big-zoo - see http://progetti.arstecnica.it/tailor/ticket/171[this
 165   ticket].
 166
 167 - http://git.sanityinc.com/?p=darcs-to-git.git[darcs-to-git] is similar
 168   to darcs2git, but it fails for the testcases found in the testsuite of
 169   darcs-fast-export.
 170
 171 - http://github.com/freshtonic/undarcs/tree/master[undarcs] claims to be
 172   fast, but its own README says it produces incorrect results. When I
 173   tried, it did not handle the darcs2 format, binary files and incremental
 174   support.
 175
 176 == Thanks
 177
 178 - Jason Dagit for helping me with darcs2 issues
 179 - Shawn O. Pearce and Johannes Schindelin for writing `git-fast-import`
 180   / `git-fast-export`
 181 - Ian Clatworthy for writing bzr fast-import
 182 - Paul Crowley for writing hg fast-import
 183 - Matthias Andree for assorted improvements, among them the --help,
 184   --encoding and --authors-file features (using Python's optparse), support
 185   for hashed repositories, `_darcs/format` interpretation, and mangling
 186   whitespace in tags to cope with repos imported into DARCS from CVS.
 187 - Pieter de Bie for writing git-bzr, which was the base of git-darcs