Darcs 2 introduces a couple of new repository formats and this chapter is intended to serve as brief introduction to them and as an overview of inter-operation between them.
Darcs 1 format is the only format supported by 1.0.x versions of darcs. Darcs 2 is capable of entirely interacting with darcs 1 format and still defaults to darcs 1 format, but to take full advantage of new capabilities of darcs 2 it be will necessary to upgrade to the newer formats.
Hashed repository format is an intermediate format that interoperates well with darcs 1 repositories. Darcs 2 can push/pull between darcs 1 format and hashed format repositories and can easily convert from one to the other. Among its benefits, one of the most user obvious changes is that the hashed format provides a more robust pristine format, that is less susceptible to corruption from IDEs and automated tools.
Hashed format is recommend for all repositories used with darcs 2 that need to interoperate with darcs 1 branches or darcs 1 developers. To get the most out of hashed format usage it is recommended to enable a global cache.
To convert an existing darcs 1 repository to hashed format simply
get
a new copy with the hashed flag:
$ darcs get --hashed old-repo new-repo
Darcs 2 format is the successor to darcs 1 format. It makes use of the various improvements of the hashed repository format, with additional benefits including an increased efficiency and robustness when dealing with conflicting patches.
Darcs 2 format is recommended for projects that do not need to interoperate with darcs 1 repositories or developers with versions of darcs less than 2.0.0 installed. To get the most out of darcs 2 format usage it is recommended to enable a global cache.
Initialize a new repository in darcs 2 format:
$ darcs init --darcs-2
Projects in darcs 1 format ready to move all development to darcs 2 can
convert an existing repository to darcs 2 format. This should be done
only once per family tree of related repositories, as converting each
branch separately may result in inter-repository corruption that can
lead to subtle and hard to diagnose problems when attempting to exchange
patches between seperately converted repositories. The recommendation
is to convert the branch of a project with the largest superset of
patches in the project and then recreate the branches from this superset
repository via darcs get
, particularly with the usage of its
selection flags such as --context
, --tag
and
--to-match
, and darcs obliterate
, which can be used to
interactively remove patches that are not intended in the recreated
branch.
The command for conversion:
$ darcs convert d1repo d2repo