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

[mhenoch at common-lisp.net]

Author: mhenoch
Date: Wed Apr  2 18:50:10 2008
New Revision: 202

Modified:
   cl-darcs/trunk/doc/cl-darcs.texi
Log:
Document command line tool


Modified: cl-darcs/trunk/doc/cl-darcs.texi
==============================================================================
--- cl-darcs/trunk/doc/cl-darcs.texi	(original)
+++ cl-darcs/trunk/doc/cl-darcs.texi	Wed Apr  2 18:50:10 2008
@@ -42,6 +42,7 @@
 
 @menu
 * Introduction::                
+* Running cl-darcs::            
 * Access methods::              
 * Getting a repository::        
 * Creating a new repository::   
@@ -50,7 +51,7 @@
 * Working directory layout::    
 @end menu
 
- at node Introduction, Access methods, Top, Top
+ at node Introduction, Running cl-darcs, Top, Top
 @chapter Introduction
 
 cl-darcs is an implementation of the darcs version control system
@@ -82,7 +83,24 @@
 middle-of-the-room cases).  However, it is already useful for simple
 usage.
 
- at node Access methods, Getting a repository, Introduction, Top
+ at node Running cl-darcs, Access methods, Introduction, Top
+ at chapter Running cl-darcs
+
+There are two ways of running cl-darcs, from the shell, or from the
+REPL.
+
+ at 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.
+
+ at section From the REPL
+
+Of course, all functionality is equally available from the REPL, though
+sometimes with different syntax or semantics.
+
+ at 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
@@ -103,20 +121,14 @@
 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
 
- 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
@@ -126,6 +138,21 @@
 @file{_darcs/prefs/defaultrepo}), and is used as default repository to
 pull from.  @xref{Pulling new patches}.
 
+ at 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}.
+ at end deffn
+
+ 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
+
 @node Creating a new repository, Pulling new patches, Getting a repository, Top
 @chapter Creating a new repository
 
@@ -145,6 +172,17 @@
 Updating your working copy with new patches from the original repository
 is called ``pulling'' these patches.
 
+ at 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
+ at 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.
+ at 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
@@ -162,9 +200,6 @@
 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
 
@@ -172,6 +207,10 @@
 called ``recording'' in darcs.  Before doing that, you may want to
 review your local changes.
 
+ at deffn Command @command{darcs whatsnew}
+Find changes in the repository in the current directory, and print them.
+ at end deffn
+
 @defun DARCS:DIFF-REPO-DISPLAY repo
 Find changes in @var{repo} and print them.
 @end defun
@@ -181,6 +220,11 @@
 ignored; see @ref{Boring files}.  New files in your tree are
 automatically included in the diff output, unless they are ``boring''.
 
+ at deffn Command @command{darcs record}
+Interactively ask which changes to record, what name to give the patch,
+and who the author is.
+ at end deffn
+
 @defun DARCS:RECORD-CHANGES repo name author date log
 Interactively ask which changes to @var{repo} to record.