Author: mhenoch
Date: Thu Feb 15 23:59:50 2007
New Revision: 95
Added:
cl-darcs/trunk/doc/
cl-darcs/trunk/doc/cl-darcs.texi
Log:
Start writing documentation
Added: cl-darcs/trunk/doc/cl-darcs.texi
==============================================================================
--- (empty file)
+++ cl-darcs/trunk/doc/cl-darcs.texi Thu Feb 15 23:59:50 2007
@@ -0,0 +1,265 @@
+\input texinfo
+@setfilename cl-darcs.info
+@settitle cl-darcs 0.2.0 manual
+
+@copying
+This is the manual for cl-darcs, version 0.2.0.
+
+Copyright @copyright{} 2007 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
+
+@titlepage
+@title cl-darcs 0.2.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::
+* Access methods::
+* Getting a repository::
+* Creating a new repository::
+* Pulling new patches::
+* Recording a patch::
+* Working directory layout::
+@end menu
+
+@node Introduction, Access methods, 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 Access methods, Getting a repository, Introduction, 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.
+@end defopt
+
+@node Getting a repository, Creating a new repository, Access methods, Top
+@chapter Getting a repository
+
+@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
+
+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}.
+
+@node Creating a new repository, Pulling new patches, Getting a repository, Top
+@chapter Creating a new repository
+
+@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.
+
+@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.
+
+Also, all new patches will be pulled without asking. This is
+suboptimal; selecting some of the patches should be supported.
+
+@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.
+
+@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''.
+
+@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
