Two new patches to amplify the previous two documentation patches using a
few suggestions from darcs-users and a little bit of my own tweaking.
Thu Aug 7 15:39:18 EDT 2008 Max Battcher <[EMAIL PROTECTED]>
* Highlight the global cache as a best practice
Thu Aug 7 15:54:29 EDT 2008 Max Battcher <[EMAIL PROTECTED]>
* Add user-focused documentation of repository format options
Sat Aug 9 14:14:24 EDT 2008 Max Battcher <[EMAIL PROTECTED]>
* Fixes to global cache text based on darcs-users suggestions
Sat Aug 9 14:40:43 EDT 2008 Max Battcher <[EMAIL PROTECTED]>
* Expand formats text based in part on suggestions from darcs-users
New patches:
[Highlight the global cache as a best practice
Max Battcher <[EMAIL PROTECTED]>**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
+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 <[EMAIL PROTECTED]>**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
+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
+repositories, as converting each branch separately may result in
+corrupted repositories that cannot exchange patches. 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| and \verb|darcs unpull|.
+
+The command for conversion:
+
+\begin{verbatim}
+$ darcs convert d1repo d2repo
+\end{verbatim}
[Fixes to global cache text based on darcs-users suggestions
Max Battcher <[EMAIL PROTECTED]>**20080809181424] hunk ./src/best_practices.tex 398
-this one of the biggest performance enhancing tools of darcs 2. The
+this is one of the biggest performance enhancing tools of darcs 2. The
hunk ./src/best_practices.tex 413
-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.
+In Windows you can run just about the same commands from \verb|cmd.exe|
+(Command Prompt under Accessories):
+
+\begin{verbatim}
+> md %UserProfile%\.darcs\cache
+> echo cache:%UserProfile%\.darcs\cache > %UserProfile%\.darcs\sources
+\end{verbatim}
[Expand formats text based in part on suggestions from darcs-users
Max Battcher <[EMAIL PROTECTED]>**20080809184043] hunk ./src/formats.tex 8
-Darcs 2 introduces a couple of new formats of repositories and this
-chapter is intended to serve as brief introduction to them and as an
-overview of inter-operation between them.
+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.
hunk ./src/formats.tex 44
-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.
+various improvements of the hashed repository format, with additional
+benefits including an increased efficiency and robustness when dealing
+with conflicting patches.
hunk ./src/formats.tex 59
-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
-repositories, as converting each branch separately may result in
-corrupted repositories that cannot exchange patches. The recommendation
+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
hunk ./src/formats.tex 67
-repository via \verb|darcs get| and \verb|darcs unpull|.
+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.
Context:
[Downplay quantum mechanics link.
Eric Kow <[EMAIL PROTECTED]>**20080806124109
Besides, darcs has far more than 3 users by now.
]
[Make patch theory intro more inviting to math people.
Eric Kow <[EMAIL PROTECTED]>**20080806123411]
[cleanup and slight rewrite of the test docs
Simon Michael <[EMAIL PROTECTED]>**20080806165949]
[make order of running tests consistent
Simon Michael <[EMAIL PROTECTED]>**20080806172123]
[small makefile refactoring: allow just the normal tests to be run, without bugs/*
Simon Michael <[EMAIL PROTECTED]>**20080805203242]
[Rectify dist help
[EMAIL PROTECTED]
Removed the "make dist" suggestion, the manual is a better place for that.
Instead, make clear that it operates on a clean copy of the tree, and
mention the "predist" functionality.
]
[website: explain that darcs 2 is required to get the darcs source.
Simon Michael <[EMAIL PROTECTED]>**20080803181216]
[Canonize Gaetan Lehmann and Daniel Buenzli.
Eric Kow <[EMAIL PROTECTED]>**20080730104357
(for Daniel B, avoid an accent in his name)
]
[configure: check for packages needed with split base.
Eric Kow <[EMAIL PROTECTED]>**20080730103840
Now that all packages must be used explicitly.
]
[fix type witness compile errors specific to ghc 6.8
Jason Dagit <[EMAIL PROTECTED]>**20080722182729]
[avoid import of unused function fromMaybe.
David Roundy <[EMAIL PROTECTED]>**20080729172825]
[configure: suggest regex-compat before text
Eric Kow <[EMAIL PROTECTED]>**20080725095336]
[configure: mention Haskell in 'try installing' suggestion
Eric Kow <[EMAIL PROTECTED]>**20080725095015]
[Typo (Text.Regex)
Eric Kow <[EMAIL PROTECTED]>**20080715121708]
[Use haskeline to have a readline-like behavior when asking something to the user
[EMAIL PROTECTED]
Unlike the implementations using readline or editline packages, this code
code doesn't break the Ctrl-C behavior.
]
[Improve generic rules for English plurals.
Eric Kow <[EMAIL PROTECTED]>**20080604123728]
[add configure check for Network.URI.
David Roundy <[EMAIL PROTECTED]>**20080711011914]
[add -hide-all-packages to default GHCFLAGS.
David Roundy <[EMAIL PROTECTED]>**20080711010952]
[add support for outputting patch numbers in darcs changes.
David Roundy <[EMAIL PROTECTED]>**20080710011211]
[add support for matching single patches by index.
David Roundy <[EMAIL PROTECTED]>**20080710004512]
[add support for matching ranges of patches (counting back from present).
David Roundy <[EMAIL PROTECTED]>**20080710003225]
[Better avoid silly manpage error.
Trent W. Buck <[EMAIL PROTECTED]>**20080704024920
It turned out only initialize's help string used 'quotes', so just
remove them. This makes init's docstring consistent with the others.
]
[Missing period at end of sentence.
Trent W. Buck <[EMAIL PROTECTED]>**20080704024232]
[darcs --overview no longer works, so don't document it.
Trent W. Buck <[EMAIL PROTECTED]>**20080704030804]
[Avoid silly manpage error.
Trent W. Buck <[EMAIL PROTECTED]>**20080703010733
man (nroff) treats an apostrophe in the first column specially,
resulting in a syntax error without this patch.
Ideally, all cases of 'foo' in the manpage (i.e. docstrings) should
become `foo', since man -Tps turns ` and ' into left and right single
quotes respectively.
]
[obliterate whitespace in Darcs.Commands.Get
[EMAIL PROTECTED]
'twas causing lhs/haddock difficulties where a \end{code} wasn't getting recognized.
]
[rm haddock CPP business
[EMAIL PROTECTED]
Try as I might, I can't see any reason to special-case some Haddock CPP logic to deal with some *commented-out guards*, unless CPP magically restores and uncomments the code if Haddock isn't being run.
]
[make pull less verbose when --verbose flag is given.
David Roundy <[EMAIL PROTECTED]>**20080624170035]
[fix makefile to remember to regenerate version information after running configure.
David Roundy <[EMAIL PROTECTED]>**20080624170001]
[TAG 2.0.2
David Roundy <[EMAIL PROTECTED]>**20080624012041]
Patch bundle hash:
727bbedccf0ddd59e9306a15c1bcec9740678271
_______________________________________________
darcs-users mailing list
[email protected]
http://lists.osuosl.org/mailman/listinfo/darcs-users
