[darcs-devel] Git-aware Darcs: a tutorial

[Juliusz Chroboczek]

0. What is Darcs-git

Darcs-git is a branch of Darcs that can work with Git repositories.

Darcs-git is deliberately Darcs, not Git.  All commands either work in
the same way on Git repositories as on Darcs repositories, or they
fail.  If you're a Darcs user, you'll like darcs-git.  If you're a Git
user, you'll probably find it infuriating.

On the other hand, Darcs-git uses stock Git repositories; a Darcs
command either works as-is on a Git repository, or fails.


1. What you can expect

The following should work reasonably well on Git repositories:

  darcs changes
  darcs whatsnew
  darcs pull
  darcs send
  darcs record

The following commands work, but have serious performance problems:

  darcs diff
  darcs changes with a file argument

The following commands should in principle work but haven't been tested:

  darcs add
  darcs remove
  darcs dist
  darcs trackdown

The following commands don't work because I'm lazy::

  darcs push
  darcs unrecord
  darcs unpull
  darcs amend-record
  darcs annotate
  darcs rollback

The following commands only work on native Darcs repositories, either
because they don't make sense on Git repositories, or because there
are perfectly good native Git tools to perform their function:

  darcs initialize
  darcs get/put
  darcs check
  darcs repair
  darcs optimize
  darcs mv
  darcs replace
  darcs resolve
  darcs tag
  darcs setpref

Remote Git repositories are not supported.


2. A tutorial

(0) Build darcs-git

  $ darcs get --partial http://www.pps.jussieu.fr/~jch/software/repos/darcs-git
  $ cd darcs-git
  $ make darcs
  $ make Context.hs
  $ make darcs
  $ cp darcs ~/bin/

(1) Get a copy of the Linux Git repository:

  $ cd /usr/local/src
  $ mkdir linux-2.6
  $ cd linux-2.6
  $ rsync -r rsync://rsync.kernel.org/pub/linux/kernel/people/torvalds/linux-2.6.git .git
  $ curl http://rsync.kernel.org/pub/linux/kernel/people/torvalds/linux-2.6.git/HEAD > .git/HEAD

We still need to bring the cache and working directory into a state
that Darcs will be happy with.  While this could in principle be done
with Darcs itself, it will be faster to do it with Git:

  $ read-tree `cat .git/HEAD`
  $ checkout-cache -a
  $ update-cache --refresh

(2) Check what the friendly Linux hackers have been up to:

  $ darcs changes | more
  $ darcs changes -s | more

(3) Create a local clone of the Linux repository:

  $ cd ..
  $ mkdir linux-2.6-local
  $ mkdir linux-2.6-local/.git
  $ ln -s `pwd`/linux-2.6/.git/objects linux-2.6-local/.git
  $ cp linux-2.6/.git/HEAD linux-2.6-local/.git
  $ cd linux-2.6-local
  $ read-tree `cat .git/HEAD`
  $ checkout-cache -a
  $ update-cache --refresh

(4) Commit some work

First, check that Darcs is happy with the new repository.

  $ darcs whatsnew

This should take a few seconds at most; if it takes minutes instead,
try running ``update-cache --refresh''.

Okay, let's add myself to the list of Linux maintainers.

  $ echo 'P:    Juliusz Chroboczek' >> MAINTAINERS

Let's see if Darcs agrees.

  $ darcs whatsnew -s
  $ darcs whatsnew

Everything looks fine, let's record (commit) this patch.

  $ darcs record -a
  $ darcs changes | more
  $ darcs changes -s | more

(5) Send it upstream

If Linus were using Darcs, we could just send him a Darcs patch, which
is a patch-like data structure that contains just enough context
information to allow Darcs to perform a history-sensitive merge:

  $ darcs send ../linux-2.6

However, until Linus switches to Darcs, we're stuck with old-fashioned
patches.

  $ darcs diff -u --patch='.' | mail bill at microsoft.com

Unfortunately, until I've spent some time optimising ``darcs diff'',
the above won't terminate on a repository the size of Linux'.


3. Caveats

There is little input validation.  In particular, if you enter an
e-mail address that doesn't end in ``>'', Darcs will write a commit
that neither Git nor Darcs itself will be able to parse.

Darcs never updates the Git cache.  If you perform many commits using
Darcs, you'll need to manually run ``update-cache --refresh''.

Darcs treats Git merges by reverse-engineering a Darcs merge (thanks
to David Roundy for outlining how that can be done).  In practice,
this means that Darcs will collapse as soon as it sees a nontrivial
Git merge.