cl-darcs manual
***************

This is the manual for cl-darcs, version 0.3.0.

Copyright © 2007, 2008 Magnus Henoch

     Permission is granted to make and distribute verbatim copies or modified versions of this manual, provided the copyright notice and this permission notice are preserved on all copies.

Introduction
************

cl-darcs is an implementation of the darcs version control system written in Common Lisp.

Darcs was originally developed by David Roundy.  Its distinguishing features among other version control systems are that it is distributed and based on a system of patch algebra.  The distributedness means that unlike CVS and SVN, every checked-out copy of a tree is a branch or an archive in its full right, where patches can be recorded and shared.  This makes new models of distributed development easy.  The patch algebra means that the program can in many cases be smart about how patches interact with eachother.  You can pull patches from one archive to another, perhaps in different order or leaving some patches behind, and the program will try to figure out how those patches would look in this new context.  See http://www.darcs.net, the official web page.

The original darcs implementation is written in Haskell, and requires extensions present only in GHC, the Glasgow Haskell Compiler.  However, GHC is not available for all platforms, and can be different to port as it requires itself as compiler.  Therefore I started to write cl-darcs in (mostly) portable Common Lisp, to be able to use darcs on my favourite system. (That is, NetBSD/powerpc.  CLISP runs well there, and recently SBCL has been ported as well.)

cl-darcs is still in an early stage of development, so expect to find bugs and unhandled corner cases (or, just as likely, unhandled middle-of-the-room cases).  However, it is already useful for simple usage.

Running cl-darcs
****************

There are two ways of running cl-darcs, from the shell, or from the REPL.

From the shell
==============

If you have successfully compiled the darcs binary, you can use it much like you'd use the original darcs client, except that it only supports a small subset of the commands.

From the REPL
=============

Of course, all functionality is equally available from the REPL, though sometimes with different syntax or semantics.

Access methods
**************

cl-darcs can access repositories on a local disk (read and write) and on an HTTP server (read-only).  Unlike the original darcs client, it doesn't yet support access through SSH; you can emulate that with scp or rsync.

When passing a path of a local repository to cl-darcs, it should usually be a directory pathname, not a file pathname.  That is, add a trailing slash, as in "/path/to/repo/", not "/path/to/repo".  Most functions can handle both forms (using CL-FAD:PATHNAME-AS-DIRECTORY), though.

 -- User Option: DARCS:*HTTP-PROXY*
     If you want to use a proxy for HTTP access, set this variable to e.g. "proxy.example.com:3128".  When NIL, no proxy is used.

     Using a caching proxy (e.g. Squid) can be a good idea, since cl-darcs is sometimes a bit wasteful about how much it downloads, and bugs might make it lose what it already has downloaded.

     This variable is not available in the standalone darcs executable.

Getting a repository
********************

Getting a copy of a repository involves getting all the patches from that repository, and applying them one by one to the local tree.  This can be a lot of data, if the repository has long history.  Darcs has a concept of ``checkpoints'', which cl-darcs doesn't yet support.

The location of the repository is saved (in _darcs/prefs/defaultrepo), and is used as default repository to pull from.  See Pulling new patches.

 -- Command: darcs get [--repodir=TO] from
     Get a local copy of the tree at FROM, and write it to TO. If TO is not specified, a subdirectory of the current directory is created, based on the last path element of FROM.

 -- Function: DARCS:GET-REPO in-path out-path &key query
     Get a local copy of the tree at IN-PATH, and write it to OUT-PATH.  IN-PATH may be an HTTP URL or a local directory. OUT-PATH must be a local nonexistent directory.

     If QUERY is true, ask for a range of patches to download and apply.

Creating a new repository
*************************

 -- Command: darcs init
     Create a new empty repository in the current directory.

 -- Function: DARCS:CREATE-REPO repodir
     Create a new empty repository in REPODIR.  REPODIR must be a local nonexistent directory.

After creating a repository, create or copy the files it should contain, and record a patch; see Recording a patch.  You may want to make this directory accessible to others through HTTP, SSH or other protocols; how to do that is outside the scope of this manual.

Pulling new patches
*******************

Updating your working copy with new patches from the original repository is called ``pulling'' these patches.

 -- Command: darcs pull [--all-patches|-a] [--repodir=LOCAL] [FOREIGN]

     Pull new patches from repository FOREIGN into repository LOCAL.  If LOCAL is not specified, it defaults to the current directory.  If FOREIGN is not specified, it defaults to the repository you pulled from last time.

     If you specify -a or --all-patches, all new patches are pulled; otherwise you will be asked for which ones to pull.

 -- Function: DARCS:PULL our-repo &optional their-repo
     Pull new patches from THEIR-REPO into OUR-REPO. OUR-REPO must be a local darcs tree.  THEIR-REPO can be a local directory or an HTTP URL.

     If THEIR-REPO is not specified, use the default repository specified in preferences, as set when getting the initial copy.

Currently DARCS:PULL doesn't handle unrecorded local changes well.  It is recommended that you record your changes or revert them before pulling.  If you don't, and your changes conflict with the newly pulled patches, you will be presented with the option of applying patches only to the pristine tree (see Working directory layout), from where you can recover the changed file and merge it with your changes.

Recording a patch
*****************

What is called ``committing'' in some other version control systems, is called ``recording'' in darcs.  Before doing that, you may want to review your local changes.

 -- Command: darcs whatsnew
     Find changes in the repository in the current directory, and print them.

 -- Function: DARCS:DIFF-REPO-DISPLAY repo
     Find changes in REPO and print them.

This command compares the files in your working directory to the pristine tree; see Working directory layout.  ``Boring'' files are ignored; see Boring files.  New files in your tree are automatically included in the diff output, unless they are ``boring''.

 -- Command: darcs record
     Interactively ask which changes to record, what name to give the patch, and who the author is.

 -- Function: DARCS:RECORD-CHANGES repo name author date log
     Interactively ask which changes to REPO to record.

     REPO is the local directory containing the repository.  NAME is the ``name'' of the patch, usually a one-line summary of the change. AUTHOR is an author identifier, usually an e-mail address. DATE is usually the keyword :NOW, but can also be a string in YYYYMMDDHHMMSS format.  LOG is a string (possibly multi-line) containing a longer description of the patch, or NIL.

Unlike many other version control systems, you can commit just some of the changes in a file, by answering yes to some hunks and no to others.

Boring files
============

There are many files that you usually don't want to have under version control.  That includes editor backups and compiled or otherwise autogenerated files.  DARCS:RECORD-CHANGES will not record a file unless you tell it to, but on the other hand it will ask about all files that are not yet recorded, which can be annoying.

Thus you can define files and directories matching certain regexps as ``boring'', not to be included in patches.  The file _darcs/prefs/boring contains such regexps, one per line.  Lines starting with # are ignored.

The original darcs client supports choosing another file as the list of boring regexps, and keeping this file under version control in the tree.  cl-darcs doesn't yet support that.

Binary files
============

The default diff format used by darcs makes sense for text files, but usually not for binary files.  Therefore, patches to binary files simply consist of the content before the change, and the content after the change.

Which files are treated as binary is specified in the file _darcs/prefs/binaries.  Each line, except those starting with #, is treated as a regexp matching binary files.

The original darcs client supports choosing another file as the list of binary regexps, and keeping this file under version control in the tree.  cl-darcs doesn't yet support that.

Working directory layout
************************

A darcs working tree (or a repository; the difference is only in your mind) keeps some special files in the directory _darcs in the top level, and nowhere else.

This directory contains a directory called pristine. (Older versions of the original darcs client call it current instead.)  In this directory, an unchanged copy of your files is stored.  This is used to find what has been changed from what has been recorded.

There is also an inventory file, which lists all patches that have been applied, in the correct order.  The actual patches are stored in the patches directory.  The inventories directory contains older inventory files, which describe the history before certain ``tags'' in the tree.  cl-darcs can read repositories with tags, but can't yet create them.

The directory checkpoints contains checkpoints that have been made to eliminate the need of getting every patch since the tree was created.  cl-darcs can neither use nor create such checkpoints, though.

The prefs directory contains files that the user is free to edit.  The files boring and binaries were described above; see Boring files, and Binary files.  The file defaultrepo contains the default repository to pull from, and repos contains repositories you have pulled from at some time. motd contains the ``message of the day'', which is printed when you get or pull from this repository.