src/formats.tex

   1 % Give some user-focused documentation on the formats introduced by Darcs 2
   2
   3
   4 \chapter{Repository formats}
   5
   6 \section{Introduction}
   7
   8 Darcs 2 introduces a couple of new repository formats and this chapter
   9 is intended to serve as brief introduction to them and as an overview of
  10 inter-operation between them.
  11
  12 \section{Darcs 1 format}
  13
  14 Darcs 1 format is the only format supported by 1.0.x versions of darcs.
  15 Darcs 2 is capable of entirely interacting with darcs 1 format and still
  16 defaults to darcs 1 format, but to take full advantage of new
  17 capabilities of darcs 2 it be will necessary to upgrade to the newer
  18 formats.
  19
  20 \section{Hashed format}
  21
  22 Hashed repository format is an intermediate format that interoperates
  23 well with darcs 1 repositories.  Darcs 2 can push/pull between darcs 1
  24 format and hashed format repositories and can easily convert from one to
  25 the other.  Among its benefits, one of the most user obvious changes is
  26 that the hashed format provides a more robust pristine format, that is
  27 less susceptible to corruption from IDEs and automated tools. It also
  28 enables the use of a global patch cache (see the Best Practices section
  29 for more).
  30
  31 Hashed format is recommend for all repositories used with darcs 2 that
  32 need to interoperate with darcs 1 branches or darcs 1 developers.
  33
  34 To convert an existing darcs 1 repository to hashed format simply
  35 \verb|get| a new copy with the hashed flag:
  36
  37 \begin{verbatim}
  38 $ darcs get --hashed old-repo new-repo
  39 \end{verbatim}
  40
  41 \section{Darcs 2 format}
  42
  43 Darcs 2 format is the successor to darcs 1 format.  It makes use of the
  44 various improvements of the hashed repository format, with additional
  45 benefits including an increased efficiency and robustness when dealing
  46 with conflicting patches.
  47
  48 Darcs 2 format is recommended for projects that do not need to
  49 interoperate with darcs 1 repositories or developers with versions of
  50 darcs less than 2.0.0 installed.
  51
  52 Initialize a new repository in darcs 2 format:
  53
  54 \begin{verbatim}
  55 $ darcs init --darcs-2
  56 \end{verbatim}
  57
  58 Projects in darcs 1 format ready to move all development to darcs 2 can
  59 convert an existing repository to darcs 2 format.  This should be done
  60 only once per family tree of related repositories, as converting each
  61 branch separately may result in inter-repository corruption that can
  62 lead to subtle and hard to diagnose problems when attempting to exchange
  63 patches between seperately converted repositories.  The recommendation
  64 is to convert the branch of a project with the largest superset of
  65 patches in the project and then recreate the branches from this superset
  66 repository via \verb|darcs get|, particularly with the usage of its
  67 selection flags such as \verb|--context|, \verb|--tag| and
  68 \verb|--to-match|, and \verb|darcs obliterate|, which can be used to
  69 interactively remove patches that are not intended in the recreated
  70 branch.
  71
  72 The command for conversion:
  73
  74 \begin{verbatim}
  75 $ darcs convert d1repo d2repo
  76 \end{verbatim}