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 -@node Introduction, Access methods, Top, Top +@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. -@node Access methods, Getting a repository, Introduction, Top +@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 @@ -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 -@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 @@ -126,6 +138,21 @@ @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 @@ -145,6 +172,17 @@ 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 @@ -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. +@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 @@ -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''. +@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.