darcs backend for fast data importers
Shell Python
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


= darcs backend for fast data importers
Miklos Vajna <vmiklos-at-frugalware-dot-org>

NOTE: This page is here only for historical reasons. The project got merged to
bzt-fastimport. You can get that code using

bzr branch lp:bzr-fastimport

== Purpose and Features

darcs-fast-export is a tool to dump a http://darcs.net/[darcs]
repository in a format understood by "fast-importers" such as
It exhibits the following _features:_

	darcs-fast-export provides a fast darcs backend for fast-import.
	See link:t/bench-results/bench-results.png[here] for exact details.

	darcs-fast-export produces correct results in any extreme cases.
	It has been tested with a collection of large darcs repos (called
	http://code.haskell.org/darcs/big-zoo/[big-zoo]). And several testcases
	under the `t/` directory.

	Ideally it should work with any fast importer, but actually it has been
	tested with git fast-import, bzr fast-import and hg fastimport. (These
	are the three fast-import implementations available ATM.)
	hg fastimport needs three patches. While they are not in the upstream,
	you can get it from my repository using
$ hg clone static-http://frugalware.org/~vmiklos/hg/hg-fastimport

	It supports the 'darcs-2', 'hashed', and 'old-fashioned-inventory' darcs
	repository formats.

Incremental conversions::
	It supports the usual `--export-marks` / `--import-marks` switches to
	allow incremental conversion.

Wrapper scripts::
	A wrapper script called `d2x` is available if you find typing
	`--export-marks` / `--import-marks` all the time boring. A similar one
	is also provided for the other direction, called `x2d`.  Finally, if you
	want to work on darcs repos with git, you can use the `git-darcs`

Author mappings::
	Supports `--authors-file` option like Git's SVN adaptor, for DARCS
	repositories that originated in CVS or SVN.

Import script::
	The pair of `darcs-fast-export`, `darcs-fast-import` is also
	included in this repo. It has been tested with the fast-expoters of Git,
	Hg, Bzr and - of course - Darcs itself.

Two-way sync::
	Using `darcs-fast-export` / `darcs-fast-import`, it is possible to
	convert a darcs repo to an other VCS, work there, then convert your work
	back to Darcs (or vica versa). This has been tested with "darcs -> git;
	hack hack; git -> darcs".

== Usage

See the manpages:

* link:darcs-fast-export.html[darcs-fast-export]
* link:darcs-fast-import.html[darcs-fast-import]
* link:d2x.html[d2x]
* link:x2d.html[x2d]
* link:git-darcs.html[git-darcs]

=== Example

Assuming that `test/` is a darcs repo, you could do this:
$ mkdir test.git
$ cd test.git
$ git --bare init
$ cd ..
$ darcs-fast-export test |(cd test.git; git fast-import)

For more examples (especially for bzr and hg), see the `t/` directory.

== Download

Using git:
$ git clone git://github.com/vmiklos/darcs-fast-export.git

== Status

In general, darcs-fast-export should work fine. darcs-fast-import has
known problems with tags - other than that it should be okay. git-darcs
should work properly as long as you are not paying too much attention to
the imported tags (newly created tags won't be pushed back).

darcs-fast-export has been tested with the following versions:

Darcs version (see http://bugs.darcs.net/issue844[this bug] on why do
you need such a new version):
$ darcs --version
2.2.0 (release)

Git version:
$ git --version
git version

Bzr versions:
$ bzr version
Bazaar (bzr) 1.12
$ (cd ~/bzr/fastimport; bzr log --limit 1|grep revno)
revno: 181

Yes, you need the fastiport plugin from BZR, the last hg release series
supported by fastimport-0.6 is hg-1.0.x.

Mercurial (Hg) version:
$ hg version
Mercurial Distributed SCM (version 1.2.1)

Strictly speaking this document is a wrong place to talk about enabling
hg plugins. However...

$ cat ~/.hgrc

and once you installed the plugin correctly, you should have something like:

$ ls /usr/lib/python*/site-packages/hgext/fastimport/__init__.py

== Additional resources

You can reach the Changelog link:Changelog[here], and a gitweb interface

The fast-import stream format documentation is
if you're interested.

== Alternatives

- http://repo.or.cz/w/darcs2git.git[darcs2git] tries to find conflict
  resolutions (to map them to merge commits), but it's rather slow
  because of this. It does not support the darcs2 format and/or
  incremental conversions, either. darcs-fast-export may support mapping
  to merge commits later, but not before
  http://bugs.darcs.net/issue1261[this issue] is addressed.

- http://progetti.arstecnica.it/tailor[tailor] is an any2any VCS
  converter, but it produces corrupted results when converting the
  big-zoo - see http://progetti.arstecnica.it/tailor/ticket/171[this

- http://git.sanityinc.com/?p=darcs-to-git.git[darcs-to-git] is similar
  to darcs2git, but it fails for the testcases found in the testsuite of

- http://github.com/freshtonic/undarcs/tree/master[undarcs] claims to be
  fast, but its own README says it produces incorrect results. When I
  tried, it did not handle the darcs2 format, binary files and incremental

- http://hackage.haskell.org/package/darcs-fastconvert[darcs-fastconvert] is
  written in native Haskell and in the 'long term' probably will be better and
  faster than darcs-fast-export.

== Thanks

- Jason Dagit for helping me with darcs2 issues
- Shawn O. Pearce and Johannes Schindelin for writing `git-fast-import`
  / `git-fast-export`
- Ian Clatworthy for writing bzr fast-import
- Paul Crowley for writing hg fast-import
- Matthias Andree for assorted improvements, among them the --help,
  --encoding and --authors-file features (using Python's optparse), support
  for hashed repositories, `_darcs/format` interpretation, and mangling
  whitespace in tags to cope with repos imported into DARCS from CVS.
- Pieter de Bie for writing git-bzr, which was the base of git-darcs