source: cl-darcs/trunk/doc/cl-darcs.texi

\input texinfo
@setfilename cl-darcs.info
@settitle cl-darcs 0.3.0 manual

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

Copyright @copyright{} 2007, 2008 Magnus Henoch

@quotation
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.
@end quotation
@end copying

@dircategory Software development
@direntry
* Cl-darcs: (cl-darcs).       Darcs version control system client
@end direntry

@titlepage
@title cl-darcs 0.3.0
@subtitle a darcs client in Common Lisp
@author Magnus Henoch

@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top, Introduction, (dir), (dir)
@top cl-darcs manual

@insertcopying

@end ifnottex


@menu
* Introduction::                
* Running cl-darcs::            
* Access methods::              
* Getting a repository::        
* Creating a new repository::   
* Pulling new patches::         
* Recording a patch::           
* Working directory layout::    
@end menu

@node Introduction, Running cl-darcs, Top, Top
@chapter 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 @uref{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.@footnote{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.

@node Running cl-darcs, Access methods, Introduction, Top
@chapter Running cl-darcs

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

@section From the shell

If you have successfully compiled the @file{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.

@section From the REPL

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

@node Access methods, Getting a repository, Running cl-darcs, Top
@chapter 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
@command{scp} or @command{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 @samp{"/path/to/repo/"}, not @samp{"/path/to/repo"}.  Most
functions can handle both forms (using
@code{CL-FAD:PATHNAME-AS-DIRECTORY}), though.

@defopt DARCS:*HTTP-PROXY*
If you want to use a proxy for HTTP access, set this variable to
e.g. @samp{"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 @file{darcs}
executable.
@end defopt

@node Getting a repository, Creating a new repository, Access methods, Top
@chapter 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
@file{_darcs/prefs/defaultrepo}), and is used as default repository to
pull from.  @xref{Pulling new patches}.

@deffn Command @command{darcs get} [@kbd{--repodir=}@var{to}] from
Get a local copy of the tree at @var{from}, and write it to @var{to}.
If @var{to} is not specified, a subdirectory of the current directory is
created, based on the last path element of @var{from}.
@end deffn

@defun DARCS:GET-REPO in-path out-path &key query
Get a local copy of the tree at @var{in-path}, and write it to
@var{out-path}.  @var{in-path} may be an HTTP URL or a local directory.
@var{out-path} must be a local nonexistent directory.

If @var{query} is true, ask for a range of patches to download and
apply.
@end defun

@node Creating a new repository, Pulling new patches, Getting a repository, Top
@chapter Creating a new repository

@deffn Command @command{darcs init}
Create a new empty repository in the current directory.
@end deffn

@defun DARCS:CREATE-REPO repodir
Create a new empty repository in @var{repodir}.  @var{repodir} must be
a local nonexistent directory.
@end defun

After creating a repository, create or copy the files it should contain,
and record a patch; see @ref{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.

@node Pulling new patches, Recording a patch, Creating a new repository, Top
@chapter Pulling new patches

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

@deffn Command @command{darcs pull} [@kbd{--all-patches}|@kbd{-a}] [@kbd{--repodir=}@var{local}] [@var{foreign}]

Pull new patches from repository @var{foreign} into repository
@var{local}.  If @var{local} is not specified, it defaults to the
current directory.  If @var{foreign} is not specified, it defaults to
the repository you pulled from last time.

If you specify @kbd{-a} or @kbd{--all-patches}, all new patches are
pulled; otherwise you will be asked for which ones to pull.
@end deffn

@defun DARCS:PULL our-repo &optional their-repo
Pull new patches from @var{their-repo} into @var{our-repo}.
@var{our-repo} must be a local darcs tree.  @var{their-repo} can be a
local directory or an HTTP URL.

If @var{their-repo} is not specified, use the default repository
specified in preferences, as set when getting the initial copy.
@end defun

Currently @code{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 (@pxref{Working directory layout}),
from where you can recover the changed file and merge it with your
changes.

@node Recording a patch, Working directory layout, Pulling new patches, Top
@chapter 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.

@deffn Command @command{darcs whatsnew}
Find changes in the repository in the current directory, and print them.
@end deffn

@defun DARCS:DIFF-REPO-DISPLAY repo
Find changes in @var{repo} and print them.
@end defun

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

@deffn Command @command{darcs record}
Interactively ask which changes to record, what name to give the patch,
and who the author is.
@end deffn

@defun DARCS:RECORD-CHANGES repo name author date log
Interactively ask which changes to @var{repo} to record.

@var{repo} is the local directory containing the repository.  @var{name}
is the ``name'' of the patch, usually a one-line summary of the change.
@var{author} is an author identifier, usually an e-mail address.
@var{date} is usually the keyword @samp{:NOW}, but can also be a string
in @samp{YYYYMMDDHHMMSS} format.  @var{log} is a string (possibly
multi-line) containing a longer description of the patch, or @samp{NIL}.

@end defun

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.

@menu
* Boring files::                
* Binary files::                
@end menu

@node Boring files, Binary files, Recording a patch, Recording a patch
@section 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.  @code{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
@file{_darcs/prefs/boring} contains such regexps, one per line.  Lines
starting with @samp{#} 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.

@node Binary files,  , Boring files, Recording a patch
@section 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
@file{_darcs/prefs/binaries}.  Each line, except those starting with
@samp{#}, 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.

@node Working directory layout,  , Recording a patch, Top
@chapter Working directory layout

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

This directory contains a directory called
@file{pristine}.@footnote{Older versions of the original darcs client
call it @file{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 @file{inventory} file, which lists all patches that
have been applied, in the correct order.  The actual patches are stored
in the @file{patches} directory.  The @file{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 @file{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 @file{prefs} directory contains files that the user is free to
edit.  The files @file{boring} and @file{binaries} were described above;
see @ref{Boring files}, and @ref{Binary files}.  The file
@file{defaultrepo} contains the default repository to pull from, and
@file{repos} contains repositories you have pulled from at some time.
@file{motd} contains the ``message of the day'', which is printed when
you get or pull from this repository.

@bye