[darcs-users] darcs patch: Highlight the global cache as a best pra... (and 1 more)

[Simon Michael]

Practicing patch review..

Max, this looks good to me. A few small notes below.

> New patches:
> 
> [Highlight the global cache as a best practice
> Max Battcher <me at worldmaker.net>**20080807193918] hunk ./src/best_practices.tex 395
> +\section{Enable a Global Cache}
> +
> +When working with darcs 2 it is recommended to enable a global cache, as
> +this one of the biggest performance enhancing tools of darcs 2.  The

"this is one"

> +global cache acts as a giant patch pool where darcs first looks for a
> +patch when grabbing new patches, thus you want it to be on the same file
> +system as your repositories.  On file systems that support it, the
> +cached patches are going to be hardlinked (the patch is only stored
> +once, but represented in multiple places) across all of your
> +repositories.
> +
> +To enable a Global Cache:
> +
> +\begin{verbatim}
> +$ mkdir -p $HOME/.darcs/cache
> +$ echo cache:$HOME/.darcs/cache > $HOME/.darcs/sources
> +\end{verbatim}
> +
> +In Windows you can run the same commands from \texttt{cmd.exe} (Command
> +Prompt) ignore the \texttt{{\$}} prompts and drop the \texttt{-p} from the \texttt{mkdir},
> +replacing \texttt{{\$}HOME} with \texttt{C:{\textbackslash}Documents and Settings{\textbackslash}*Username*} or
> +\texttt{C:{\textbackslash}Users{\textbackslash}*Username*}, respectively.
> +
> +There are some other advanced things you can do in \verb!_darcs/prefs/sources!,
> +such as create per-repository caches, read-only caches and even set a
> +primary source repository above any used in a \verb|darcs get| or 
> +\verb|darcs pull| command.
> 
> [Add user-focused documentation of repository format options
> Max Battcher <me at worldmaker.net>**20080807195429] hunk ./GNUmakefile 290
> -	src/best_practices.tex
> +	src/best_practices.tex src/formats.tex
> hunk ./src/darcs.lhs 655
> +\input{formats.tex}
> +
> addfile ./src/formats.tex
> hunk ./src/formats.tex 1
> +% Give some user-focused documentation on the formats introduced by Darcs 2
> +
> +
> +\chapter{Repository formats}
> +
> +\section{Introduction}
> +
> +Darcs 2 introduces a couple of new formats of repositories and this

"a couple of new repository formats" ?

> +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.  Darcs 2's major
> +benefit over darcs 1 format is 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 that can push all development to versions
> +that support darcs 2 format can convert an existing repository to darcs
> +2 format.  This should be done only once per family of related

I didn't understand the above sentence..

> +repositories, as converting each branch separately may result in
> +corrupted repositories that cannot exchange patches.  The recommendation

change corrupted to "incompatible" or "unsynchronised" ? The repos are 
not corrupt, just not longer inter-pullable.

> +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| and \verb|darcs unpull|.

Did you mean unpull ? If so, I'm not sure why you'd use it.

> +
> +The command for conversion:
> +
> +\begin{verbatim}
> +$ darcs convert d1repo d2repo
> +\end{verbatim}
> 
> Context: