[Cl-darcs-cvs] r95 - cl-darcs/trunk/doc

[mhenoch at common-lisp.net]

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
+ at setfilename cl-darcs.info
+ at settitle cl-darcs 0.2.0 manual
+
+ at copying
+This is the manual for cl-darcs, version 0.2.0.
+
+Copyright @copyright{} 2007 Magnus Henoch
+
+ at 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.
+ at end quotation
+ at end copying
+
+ at titlepage
+ at title cl-darcs 0.2.0
+ at subtitle a darcs client in Common Lisp
+ at author Magnus Henoch
+
+ at page
+ at vskip 0pt plus 1filll
+ at insertcopying
+ at end titlepage
+
+ at contents
+
+ at ifnottex
+ at node Top, Introduction, (dir), (dir)
+ at top cl-darcs manual
+
+ at insertcopying
+
+ at end ifnottex
+
+
+ at menu
+* Introduction::                
+* Access methods::              
+* Getting a repository::        
+* Creating a new repository::   
+* Pulling new patches::         
+* Recording a patch::           
+* Working directory layout::    
+ at end menu
+
+ at node Introduction, Access methods, Top, Top
+ at 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. at 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.
+
+ at node Access methods, Getting a repository, Introduction, Top
+ at 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
+ at 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
+ at code{CL-FAD:PATHNAME-AS-DIRECTORY}), though.
+
+ at 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.
+ at end defopt
+
+ at node Getting a repository, Creating a new repository, Access methods, Top
+ at chapter Getting a repository
+
+ at 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
+ at var{out-path}.  @var{in-path} may be an HTTP URL or a local directory.
+ at var{out-path} must be a local nonexistent directory.
+
+If @var{query} is true, ask for a range of patches to download and
+apply.
+ at 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
+ at file{_darcs/prefs/defaultrepo}), and is used as default repository to
+pull from.  @xref{Pulling new patches}.
+
+ at node Creating a new repository, Pulling new patches, Getting a repository, Top
+ at chapter Creating a new repository
+
+ at defun DARCS:CREATE-REPO repodir
+Create a new empty repository in @var{repodir}.  @var{repodir} must be
+a local nonexistent directory.
+ at 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.
+
+ at node Pulling new patches, Recording a patch, Creating a new repository, Top
+ at chapter Pulling new patches
+
+Updating your working copy with new patches from the original repository
+is called ``pulling'' these patches.
+
+ at defun DARCS:PULL our-repo &optional their-repo
+Pull new patches from @var{their-repo} into @var{our-repo}.
+ at 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.
+ at 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.
+
+ at node Recording a patch, Working directory layout, Pulling new patches, Top
+ at 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.
+
+ at defun DARCS:DIFF-REPO-DISPLAY repo
+Find changes in @var{repo} and print them.
+ at 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''.
+
+ at defun DARCS:RECORD-CHANGES repo name author date log
+Interactively ask which changes to @var{repo} to record.
+
+ at 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.
+ at var{author} is an author identifier, usually an e-mail address.
+ at 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}.
+
+ at 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.
+
+ at menu
+* Boring files::                
+* Binary files::                
+ at end menu
+
+ at node Boring files, Binary files, Recording a patch, Recording a patch
+ at 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
+ at 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.
+
+ at node Binary files,  , Boring files, Recording a patch
+ at 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
+ at file{_darcs/prefs/binaries}.  Each line, except those starting with
+ at 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.
+
+ at node Working directory layout,  , Recording a patch, Top
+ at 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
+ at file{pristine}. at 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
+ at file{defaultrepo} contains the default repository to pull from, and
+ at file{repos} contains repositories you have pulled from at some time.
+ at file{motd} contains the ``message of the day'', which is printed when
+you get or pull from this repository.
+
+ at bye