Keywords: darcs

Subsections

- Introduction
- Darcs 1 format
- Hashed format
- Darcs 2 format

# Repository formats

# Introduction

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

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 format

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

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