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