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.
old-fashioned-inventory
is now deprecated and should be avoided if at
all possible.
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. It also enables the use of a global patch cache (see the Best Practices section for more).
Hashed format is recommend for all repositories used with darcs 2 that need to interoperate with darcs 1 branches or darcs 1 developers.
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
hashed
Offers several features while still being compatible with old-fashioned repositories. The specific features are:
_darcs/pristine
directory no longer holds the pristine
cache. This disallows certain hackish short-cuts, but also dramatically
reduces the danger of third-party programs (e.g. DreamWeaver) recursing
into the pristine cache and corrupting darcs repositories.
^C
). Secondly, if the source repository disappears,
or you lose network connectivity, some operations may fail.
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.
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
darcs-2
Is the default. It enables all available features, and
requiring that all repos for a project use the same format. In addition to the
features of the hashed
format described above, the darcs-2
format
also enables the following: