% Give some user-focused documentation on the formats introduced by Darcs 2


\chapter{Repository formats}

\section{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.

\section{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.

\section{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
\verb|get| a new copy with the hashed flag:

\begin{verbatim}
$ darcs get --hashed old-repo new-repo
\end{verbatim}

\section{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:

\begin{verbatim}
$ darcs init --darcs-2
\end{verbatim}

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 \verb|darcs get|, particularly with the usage of its
selection flags such as \verb|--context|, \verb|--tag| and
\verb|--to-match|, and \verb|darcs obliterate|, which can be used to
interactively remove patches that are not intended in the recreated
branch.

The command for conversion:

\begin{verbatim}
$ darcs convert d1repo d2repo
\end{verbatim}
