source: cl-darcs/trunk/doc/cl-darcs.texi

Last change on this file was 205, checked in by Magnus Henoch, 14 years ago

Document "darcs init"

File size: 12.0 KB
Line 
1\input texinfo
2@setfilename cl-darcs.info
3@settitle cl-darcs 0.3.0 manual
4
5@copying
6This is the manual for cl-darcs, version 0.3.0.
7
8Copyright @copyright{} 2007, 2008 Magnus Henoch
9
10@quotation
11Permission is granted to make and distribute verbatim copies or
12modified versions of this manual, provided the copyright notice and
13this permission notice are preserved on all copies.
14@end quotation
15@end copying
16
17@dircategory Software development
18@direntry
19* Cl-darcs: (cl-darcs).       Darcs version control system client
20@end direntry
21
22@titlepage
23@title cl-darcs 0.3.0
24@subtitle a darcs client in Common Lisp
25@author Magnus Henoch
26
27@page
28@vskip 0pt plus 1filll
29@insertcopying
30@end titlepage
31
32@contents
33
34@ifnottex
35@node Top, Introduction, (dir), (dir)
36@top cl-darcs manual
37
38@insertcopying
39
40@end ifnottex
41
42
43@menu
44* Introduction::               
45* Running cl-darcs::           
46* Access methods::             
47* Getting a repository::       
48* Creating a new repository::   
49* Pulling new patches::         
50* Recording a patch::           
51* Working directory layout::   
52@end menu
53
54@node Introduction, Running cl-darcs, Top, Top
55@chapter Introduction
56
57cl-darcs is an implementation of the darcs version control system
58written in Common Lisp.
59
60Darcs was originally developed by David Roundy.  Its distinguishing
61features among other version control systems are that it is
62distributed and based on a system of patch algebra.  The distributedness
63means that unlike CVS and SVN, every checked-out copy of a tree is a
64branch or an archive in its full right, where patches can be recorded
65and shared.  This makes new models of distributed development easy.  The
66patch algebra means that the program can in many cases be smart about
67how patches interact with eachother.  You can pull patches from one
68archive to another, perhaps in different order or leaving some patches
69behind, and the program will try to figure out how those patches would
70look in this new context.  See @uref{http://www.darcs.net}, the official
71web page.
72
73The original darcs implementation is written in Haskell, and requires
74extensions present only in GHC, the Glasgow Haskell Compiler.  However,
75GHC is not available for all platforms, and can be different to port as
76it requires itself as compiler.  Therefore I started to write cl-darcs
77in (mostly) portable Common Lisp, to be able to use darcs on my
78favourite system.@footnote{That is, NetBSD/powerpc.  CLISP runs well
79there, and recently SBCL has been ported as well.}
80
81cl-darcs is still in an early stage of development, so expect to find
82bugs and unhandled corner cases (or, just as likely, unhandled
83middle-of-the-room cases).  However, it is already useful for simple
84usage.
85
86@node Running cl-darcs, Access methods, Introduction, Top
87@chapter Running cl-darcs
88
89There are two ways of running cl-darcs, from the shell, or from the
90REPL.
91
92@section From the shell
93
94If you have successfully compiled the @file{darcs} binary, you can use
95it much like you'd use the original darcs client, except that it only
96supports a small subset of the commands.
97
98@section From the REPL
99
100Of course, all functionality is equally available from the REPL, though
101sometimes with different syntax or semantics.
102
103@node Access methods, Getting a repository, Running cl-darcs, Top
104@chapter Access methods
105
106cl-darcs can access repositories on a local disk (read and write) and on
107an HTTP server (read-only).  Unlike the original darcs client, it
108doesn't yet support access through SSH; you can emulate that with
109@command{scp} or @command{rsync}.
110
111When passing a path of a local repository to cl-darcs, it should usually
112be a directory pathname, not a file pathname.  That is, add a trailing
113slash, as in @samp{"/path/to/repo/"}, not @samp{"/path/to/repo"}.  Most
114functions can handle both forms (using
115@code{CL-FAD:PATHNAME-AS-DIRECTORY}), though.
116
117@defopt DARCS:*HTTP-PROXY*
118If you want to use a proxy for HTTP access, set this variable to
119e.g. @samp{"proxy.example.com:3128"}.  When NIL, no proxy is used.
120
121Using a caching proxy (e.g. Squid) can be a good idea, since cl-darcs is
122sometimes a bit wasteful about how much it downloads, and bugs might
123make it lose what it already has downloaded.
124
125This variable is not available in the standalone @file{darcs}
126executable.
127@end defopt
128
129@node Getting a repository, Creating a new repository, Access methods, Top
130@chapter Getting a repository
131
132Getting a copy of a repository involves getting all the patches from
133that repository, and applying them one by one to the local tree.  This
134can be a lot of data, if the repository has long history.  Darcs has a
135concept of ``checkpoints'', which cl-darcs doesn't yet support.
136
137The location of the repository is saved (in
138@file{_darcs/prefs/defaultrepo}), and is used as default repository to
139pull from.  @xref{Pulling new patches}.
140
141@deffn Command @command{darcs get} [@kbd{--repodir=}@var{to}] from
142Get a local copy of the tree at @var{from}, and write it to @var{to}.
143If @var{to} is not specified, a subdirectory of the current directory is
144created, based on the last path element of @var{from}.
145@end deffn
146
147@defun DARCS:GET-REPO in-path out-path &key query
148Get a local copy of the tree at @var{in-path}, and write it to
149@var{out-path}.  @var{in-path} may be an HTTP URL or a local directory.
150@var{out-path} must be a local nonexistent directory.
151
152If @var{query} is true, ask for a range of patches to download and
153apply.
154@end defun
155
156@node Creating a new repository, Pulling new patches, Getting a repository, Top
157@chapter Creating a new repository
158
159@deffn Command @command{darcs init}
160Create a new empty repository in the current directory.
161@end deffn
162
163@defun DARCS:CREATE-REPO repodir
164Create a new empty repository in @var{repodir}.  @var{repodir} must be
165a local nonexistent directory.
166@end defun
167
168After creating a repository, create or copy the files it should contain,
169and record a patch; see @ref{Recording a patch}.  You may want to make
170this directory accessible to others through HTTP, SSH or other
171protocols; how to do that is outside the scope of this manual.
172
173@node Pulling new patches, Recording a patch, Creating a new repository, Top
174@chapter Pulling new patches
175
176Updating your working copy with new patches from the original repository
177is called ``pulling'' these patches.
178
179@deffn Command @command{darcs pull} [@kbd{--all-patches}|@kbd{-a}] [@kbd{--repodir=}@var{local}] [@var{foreign}]
180
181Pull new patches from repository @var{foreign} into repository
182@var{local}.  If @var{local} is not specified, it defaults to the
183current directory.  If @var{foreign} is not specified, it defaults to
184the repository you pulled from last time.
185
186If you specify @kbd{-a} or @kbd{--all-patches}, all new patches are
187pulled; otherwise you will be asked for which ones to pull.
188@end deffn
189
190@defun DARCS:PULL our-repo &optional their-repo
191Pull new patches from @var{their-repo} into @var{our-repo}.
192@var{our-repo} must be a local darcs tree.  @var{their-repo} can be a
193local directory or an HTTP URL.
194
195If @var{their-repo} is not specified, use the default repository
196specified in preferences, as set when getting the initial copy.
197@end defun
198
199Currently @code{DARCS:PULL} doesn't handle unrecorded local changes
200well.  It is recommended that you record your changes or revert them
201before pulling.  If you don't, and your changes conflict with the newly
202pulled patches, you will be presented with the option of applying
203patches only to the pristine tree (@pxref{Working directory layout}),
204from where you can recover the changed file and merge it with your
205changes.
206
207@node Recording a patch, Working directory layout, Pulling new patches, Top
208@chapter Recording a patch
209
210What is called ``committing'' in some other version control systems, is
211called ``recording'' in darcs.  Before doing that, you may want to
212review your local changes.
213
214@deffn Command @command{darcs whatsnew}
215Find changes in the repository in the current directory, and print them.
216@end deffn
217
218@defun DARCS:DIFF-REPO-DISPLAY repo
219Find changes in @var{repo} and print them.
220@end defun
221
222This command compares the files in your working directory to the
223pristine tree; see @ref{Working directory layout}.  ``Boring'' files are
224ignored; see @ref{Boring files}.  New files in your tree are
225automatically included in the diff output, unless they are ``boring''.
226
227@deffn Command @command{darcs record}
228Interactively ask which changes to record, what name to give the patch,
229and who the author is.
230@end deffn
231
232@defun DARCS:RECORD-CHANGES repo name author date log
233Interactively ask which changes to @var{repo} to record.
234
235@var{repo} is the local directory containing the repository.  @var{name}
236is the ``name'' of the patch, usually a one-line summary of the change.
237@var{author} is an author identifier, usually an e-mail address.
238@var{date} is usually the keyword @samp{:NOW}, but can also be a string
239in @samp{YYYYMMDDHHMMSS} format.  @var{log} is a string (possibly
240multi-line) containing a longer description of the patch, or @samp{NIL}.
241
242@end defun
243
244Unlike many other version control systems, you can commit just some of
245the changes in a file, by answering yes to some hunks and no to others.
246
247@menu
248* Boring files::               
249* Binary files::               
250@end menu
251
252@node Boring files, Binary files, Recording a patch, Recording a patch
253@section Boring files
254
255There are many files that you usually don't want to have under version
256control.  That includes editor backups and compiled or otherwise
257autogenerated files.  @code{DARCS:RECORD-CHANGES} will not record a file
258unless you tell it to, but on the other hand it will ask about all files
259that are not yet recorded, which can be annoying.
260
261Thus you can define files and directories matching certain regexps as
262``boring'', not to be included in patches.  The file
263@file{_darcs/prefs/boring} contains such regexps, one per line.  Lines
264starting with @samp{#} are ignored.
265
266The original darcs client supports choosing another file as the list of
267boring regexps, and keeping this file under version control in the
268tree.  cl-darcs doesn't yet support that.
269
270@node Binary files,  , Boring files, Recording a patch
271@section Binary files
272
273The default diff format used by darcs makes sense for text files, but
274usually not for binary files.  Therefore, patches to binary files
275simply consist of the content before the change, and the content after
276the change.
277
278Which files are treated as binary is specified in the file
279@file{_darcs/prefs/binaries}.  Each line, except those starting with
280@samp{#}, is treated as a regexp matching binary files.
281
282The original darcs client supports choosing another file as the list of
283binary regexps, and keeping this file under version control in the
284tree.  cl-darcs doesn't yet support that.
285
286@node Working directory layout,  , Recording a patch, Top
287@chapter Working directory layout
288
289A darcs working tree (or a repository; the difference is only in your
290mind) keeps some special files in the directory @file{_darcs} in the top
291level, and nowhere else.
292
293This directory contains a directory called
294@file{pristine}.@footnote{Older versions of the original darcs client
295call it @file{current} instead.}  In this directory, an unchanged copy
296of your files is stored.  This is used to find what has been changed
297from what has been recorded.
298
299There is also an @file{inventory} file, which lists all patches that
300have been applied, in the correct order.  The actual patches are stored
301in the @file{patches} directory.  The @file{inventories} directory
302contains older inventory files, which describe the history before
303certain ``tags'' in the tree.  cl-darcs can read repositories with tags,
304but can't yet create them.
305
306The directory @file{checkpoints} contains checkpoints that have been
307made to eliminate the need of getting every patch since the tree was
308created.  cl-darcs can neither use nor create such checkpoints, though.
309
310The @file{prefs} directory contains files that the user is free to
311edit.  The files @file{boring} and @file{binaries} were described above;
312see @ref{Boring files}, and @ref{Binary files}.  The file
313@file{defaultrepo} contains the default repository to pull from, and
314@file{repos} contains repositories you have pulled from at some time.
315@file{motd} contains the ``message of the day'', which is printed when
316you get or pull from this repository.
317
318@bye
Note: See TracBrowser for help on using the repository browser.