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