1DARCS(1) General Commands Manual DARCS(1)
2
6 darcs - an advanced revision control system
7
9 darcs command <arguments|[options]>...
10 Where the commands and their respective arguments are
12 darcs help [<darcs_command> [darcs_subcommand]]
14 darcs initialize [<directory>]
15 darcs add <file|directory> ...
16 darcs whatsnew [file|directory]...
17 darcs record [file|directory]...
18 darcs clone <repository> [<directory>]
19 darcs pull [repository]...
20 darcs push [repository]
21 darcs move <source> ... <destination>
22 darcs remove <file|directory> ...
23 darcs replace <old> <new> <file> ...
24 darcs log [file|directory]...
25 darcs annotate [file|directory]
26 darcs diff [file|directory]...
27 darcs show contents [file]...
28 darcs show dependencies
29 darcs show files [file|directory]...
30 darcs show index
31 darcs show pristine
32 darcs show repo
33 darcs show authors
34 darcs show tags
35 darcs show patch-index
36 darcs test [[initialization] command]
37 darcs revert [file|directory]...
38 darcs unrevert
39 darcs amend [file|directory]...
40 darcs rebase pull [repository]...
41 darcs rebase apply <patchfile>
42 darcs rebase suspend
43 darcs rebase unsuspend
44 darcs rebase obliterate
45 darcs rebase log
46 darcs rollback [file|directory]...
47 darcs unrecord
48 darcs obliterate
49 darcs tag [tagname]
50 darcs setpref <pref> <value>
51 darcs send [repository]
52 darcs apply <patchfile>
53 darcs optimize clean
54 darcs optimize http
55 darcs optimize reorder
56 darcs optimize enable-patch-index
57 darcs optimize disable-patch-index
58 darcs optimize compress
59 darcs optimize uncompress
60 darcs optimize relink
61 darcs optimize pristine
62 darcs optimize upgrade
63 darcs optimize cache <directory> ...
64 darcs dist
65 darcs mark-conflicts [file|directory]...
66 darcs repair
67 darcs convert darcs-2 <source> [<destination>]
68 darcs convert export
69 darcs convert import [<directory>]
70 darcs fetch [repository]...
71
74 Darcs is a free, open source revision control system. It is:
75 · Distributed: Every user has access to the full command set, removing
77 boundaries between server and client or committer and non‐commit‐
78 ters.
79 · Interactive: Darcs is easy to learn and efficient to use because it
81 asks you questions in response to simple commands, giving you
82 choices in your work flow. You can choose to record one change in a
83 file, while ignoring another. As you update from upstream, you can
84 review each patch name, even the full `diff' for interesting
85 patches.
86 · Smart: Originally developed by physicist David Roundy, darcs is
88 based on a unique algebra of patches. This smartness lets you
89 respond to changing demands in ways that would otherwise not be pos‐
90 sible. Learn more about spontaneous branches with darcs.
91
93 Different options are accepted by different Darcs commands. Each com‐
94 mand's most important options are listed in the COMMANDS section. For
95 a full list of all options accepted by a particular command, run `darcs
96 command --help'.
97 Selecting Patches:
99 The --patches option yields patches with names matching an *extended*
100 regular expression. See regex(7) for details. The --matches option
101 yields patches that match a logical (Boolean) expression: one or more
102 primitive expressions combined by grouping (parentheses) and the com‐
103 plement (not), conjunction (and) and disjunction (or) operators. The C
104 notation for logic operators (!, && and ||) can also be used.
105 - --patches=regex is a synonym for --matches='name regex' - --hash=HASH
107 is a synonym for --matches='hash HASH' - --from-patch and --to-patch
108 are synonyms for --from-match='name... and --to-match='name... -
109 --from-patch and --to-match can be unproblematically combined:
110 `darcs log --from-patch='html.*documentation' --to-match='date
111 20040212'`
112 The following primitive Boolean expressions are supported:
114 exact STRING - check literal STRING is equal to patch name.
116 name REGEX - match REGEX against patch name.
117 author REGEX - match REGEX against patch author.
118 hunk REGEX - match REGEX against contents of a hunk patch.
119 comment REGEX - match REGEX against the full log message.
120 hash HASH - match HASH against (a prefix of) the hash of a patch.
121 date DATE - match DATE against the patch date.
122 touch REGEX - match file paths for a patch.
123 Here are some examples:
125 darcs log --match 'exact "Resolve issue17: use dynamic memory alloca‐
127 tion."'
128 darcs log --match 'name issue17'
129 darcs log --match 'name "^[Rr]esolve issue17\>"'
130 darcs log --match 'author "David Roundy"'
131 darcs log --match 'author droundy'
132 darcs log --match 'author droundy@darcs.net'
133 darcs log --match 'hunk "foo = 2"'
134 darcs log --match 'hunk "^instance .* Foo where$"'
135 darcs log --match 'comment "prevent deadlocks"'
136 darcs log --match 'hash c719567e92c3b0ab9eddd5290b705712b8b918ef'
137 darcs log --match 'hash c7195'
138 darcs log --match 'date "2006-04-02 22:41"'
139 darcs log --match 'date "tea time yesterday"'
140 darcs log --match 'touch src/foo.c'
141 darcs log --match 'touch src/'
142 darcs log --match 'touch "src/*.(c|h)"'
143
146 darcs help [<darcs_command> [darcs_subcommand]]
147 Without arguments, `darcs help` prints a categorized list of darcs
148 commands and a short description of each one. With an extra argu‐
149 ment, `darcs help foo` prints detailed help about the darcs command
150 foo.
151 Most used/starting out:
154 darcs initialize [<directory>]
155 The `darcs initialize` command creates an empty repository in the
156 current directory. This repository lives in a new `_darcs` direc‐
157 tory, which stores version control metadata and settings.
158 Any existing files and subdirectories become UNSAVED changes:
160 record them with `darcs record --look-for-adds`.
161 By default, patches of the new repository are in the darcs-2 seman‐
163 tics. However it is possible to create a repository in darcs-1
164 semantics with the flag `--darcs-1`, althought this is not recom‐
165 mended except for sharing patches with a project that uses patches
166 in the darcs-1 semantics.
167 Initialize is commonly abbreviated to `init`.
169 darcs add <file|directory> ...
171 Generally the working tree contains both files that should be ver‐
172 sion controlled (such as source code) and files that Darcs should
173 ignore (such as executables compiled from the source code). The
174 `darcs add` command is used to tell Darcs which files to version
175 control.
176 When an existing project is first imported into a Darcs repository,
178 it is common to run `darcs add -r *` or `darcs record -l` to add
179 all initial source files into darcs.
180 Adding symbolic links (symlinks) is not supported.
182 Darcs will ignore all files and folders that look "boring". The
184 `--boring` option overrides this behaviour.
185 Darcs will not add file if another file in the same folder has the
187 same name, except for case. The `--case-ok` option overrides this
188 behaviour. Windows and OS X usually use filesystems that do not
189 allow files a folder to have the same name except for case (for
190 example, `ReadMe` and `README`). If `--case-ok` is used, the
191 repository might be unusable on those systems!
192 darcs whatsnew [file|directory]...
195 The `darcs whatsnew` command lists unrecorded changes to the work‐
196 ing tree. If you specify a set of files and directories, only
197 unrecorded changes to those files and directories are listed.
198 With the `--summary` option, the changes are condensed to one line
200 per file, with mnemonics to indicate the nature and extent of the
201 change. The `--look-for-adds` option causes candidates for `darcs
202 add` to be included in the summary output. Summary mnemonics are
203 as follows:
204 * `A f` and `A d/` respectively mean an added file or directory. *
206 `R f` and `R d/` respectively mean a removed file or directory. *
207 `M f -N +M rP` means a modified file, with `N` lines deleted, `M`
208 lines added, and `P` lexical replacements. * `f -> g` means a
209 moved file or directory. * `a f` and `a d/` respectively mean a
210 new, but unadded, file or
211 directory, when using `--look-for-adds`.
212 An exclamation mark (!) as in `R! foo.c`, means the change is
214 known to
215 conflict with a change in another patch. The phrase `duplicated`
216 means the change is known to be identical to a change in another
217 patch.
218 The `--machine-readable` option implies `--summary` while making it
220 more parsable. Modified files are only shown as `M f`, and moves
221 are shown in two lines: `F f` and `T g` (as in 'From f To g').
222 By default, `darcs whatsnew` uses Darcs' internal format for
224 changes. To see some context (unchanged lines) around each change,
225 use the `--unified` option. To view changes in conventional `diff`
226 format, use the `darcs diff` command; but note that `darcs what‐
227 snew` is faster.
228 This command exits unsuccessfully (returns a non-zero exit status)
230 if there are no unrecorded changes.
231 darcs record [file|directory]...
233 The `darcs record` command is used to create a patch from changes
234 in the working tree. If you specify a set of files and directo‐
235 ries, changes to other files will be skipped.
236 Every patch has a name, an optional description, an author and a
238 date.
239 Darcs will launch a text editor (see `darcs help environment`)
241 after the interactive selection, to let you enter the patch name
242 (first line) and the patch description (subsequent lines).
243 You can supply the patch name in advance with the `-m` option, in
245 which case no text editor is launched, unless you use
246 `--edit-long-comment`.
247 The patch description is an optional block of free-form text. It
249 is used to supply additional information that doesn't fit in the
250 patch name. For example, it might include a rationale of WHY the
251 change was necessary.
252 A technical difference between patch name and patch description, is
254 that matching with the flag `-p` is only done on patch names.
255 Finally, the `--logfile` option allows you to supply a file that
257 already contains the patch name and description. This is useful if
258 a previous record failed and left a `_darcs/patch_description.txt`
259 file.
260 Each patch is attributed to its author, usually by email address
262 (for example, `Fred Bloggs <fred@example.net>`). Darcs looks in
263 several places for this author string: the `--author` option, the
264 files `_darcs/prefs/author` (in the repository) and
265 `~/.darcs/author` (in your home directory), and the environment
266 variables `$DARCS_EMAIL` and `$EMAIL`. If none of those exist,
267 Darcs will prompt you for an author string and write it to
268 `~/.darcs/author`. Note that if you have more than one email
269 address, you can put them all in `~/.darcs/author`, one author per
270 line. Darcs will still prompt you for an author, but it allows you
271 to select from the list, or to type in an alternative.
272 If you want to manually define any explicit dependencies for your
274 patch, you can use the `--ask-deps` flag. Some dependencies may be
275 automatically inferred from the patch's content and cannot be
276 removed. A patch with specific dependencies can be empty.
277 The patch date is generated automatically. It can only be spoofed
279 by using the `--pipe` option.
280 If you run record with the `--pipe` option, you will be prompted
282 for the patch date, author, and the long comment. The long comment
283 will extend until the end of file or stdin is reached. This inter‐
284 face is intended for scripting darcs, in particular for writing
285 repository conversion scripts. The prompts are intended mostly as
286 a useful guide (since scripts won't need them), to help you under‐
287 stand the input format. Here's an example of what the `--pipe`
288 prompts look like:
289 What is the date? Mon Nov 15 13:38:01 EST 2004
291 Who is the author? David Roundy
292 What is the log? One or more comment lines
293 If a test command has been defined with `darcs setpref`, attempting
295 to record a patch will cause the test command to be run in a clean
296 copy of the working tree (that is, including only recorded
297 changes). If the test fails, you will be offered to abort the
298 record operation.
299 The `--set-scripts-executable` option causes scripts to be made
301 executable in the clean copy of the working tree, prior to running
302 the test. See `darcs clone` for an explanation of the script
303 heuristic.
304 If your test command is tediously slow (e.g. `make all`) and you
306 are recording several patches in a row, you may wish to use
307 `--no-test` to skip all but the final test.
308 To see some context (unchanged lines) around each change, use the
310 `--unified` option.
311 darcs clone <repository> [<directory>]
313 Clone creates a copy of a repository. The optional second argument
314 specifies a destination directory for the new copy; if omitted, it
315 is inferred from the source location.
316 By default Darcs will copy every patch from the original reposi‐
318 tory. If you expect the original repository to remain accessible,
319 you can use `--lazy` to avoid copying patches until they are needed
320 ('copy on demand'). This is particularly useful when copying a
321 remote repository with a long history that you don't care about.
322 When cloning locally, Darcs automatically uses hard linking where
324 possible. As well as saving time and space, this enables to move
325 or delete the original repository without affecting the copy. Hard
326 linking requires that the copy be on the same filesystem as the
327 original repository, and that the filesystem support hard linking.
328 This includes NTFS, HFS+ and all general-purpose Unix filesystems
329 (such as ext, UFS and ZFS). FAT does not support hard links.
330 When cloning from a remote location, Darcs will look for and
332 attempt to use packs created by `darcs optimize http` in the remote
333 repository. Packs are single big files that can be downloaded
334 faster than many little files.
335 Darcs clone will not copy unrecorded changes to the source reposi‐
337 tory's working tree.
338 You can copy a repository to a ssh url, in which case the new
340 repository will always be complete.
341 It is often desirable to make a copy of a repository that excludes
343 some patches. For example, if releases are tagged then `darcs
344 clone --tag .` would make a copy of the repository as at the latest
345 release.
346 An untagged repository state can still be identified unambiguously
348 by a context file, as generated by `darcs log --context`. Given
349 the name of such a file, the `--context` option will create a
350 repository that includes only the patches from that context. When
351 a user reports a bug in an unreleased version of your project, the
352 recommended way to find out exactly what version they were running
353 is to have them include a context file in the bug report.
354 You can also make a copy of an untagged state using the
356 `--to-patch` or `--to-match` options, which exclude patches *after*
357 the first matching patch. Because these options treat the set of
358 patches as an ordered sequence, you may get different results after
359 reordering with `darcs optimize reorder`.
360 The `--set-scripts-executable` option causes scripts to be made
362 executable in the working tree. A script is any file that starts
363 with a shebang ("#!").
364 darcs pull [repository]...
366 Pull is used to bring patches made in another repository into the
367 current repository (that is, either the one in the current direc‐
368 tory, or the one specified with the `--repodir` option). Pull
369 accepts arguments, which are URLs from which to pull, and when
370 called without an argument, pull will use the repository specified
371 at `_darcs/prefs/defaultrepo`.
372 The default (`--union`) behavior is to pull any patches that are in
374 any of the specified repositories. If you specify the `--intersec‐
375 tion` flag, darcs will only pull those patches which are present in
376 all source repositories. If you specify the `--complement` flag,
377 darcs will only pull elements in the first repository that do not
378 exist in any of the remaining repositories.
379 If `--reorder` is supplied, the set of patches that exist only in
381 the current repository is brought at the top of the current his‐
382 tory. This will work even if there are no new patches to pull.
383 See `darcs help apply` for detailed description of many options.
385 darcs push [repository]
387 Push is the opposite of pull. Push allows you to copy patches from
388 the current repository into another repository.
389 If you give the `--apply-as` flag, darcs will use `sudo` to apply
391 the patches as a different user. This can be useful if you want to
392 set up a system where several users can modify the same repository,
393 but you don't want to allow them full write access. This isn't
394 secure against skilled malicious attackers, but at least can pro‐
395 tect your repository from clumsy, inept or lazy users.
396 `darcs push` will compress the patch data before sending it to a
398 remote location via ssh. This works as long as the remote darcs is
399 not older than version 2.5. If you get errors that indicate a cor‐
400 rupt patch bundle, you should try again with the `--no-compress`
401 option.
402 Preparing patches before recording:
405 darcs move <source> ... <destination>
406 Darcs cannot reliably distinguish between a file being deleted and
407 a new one added, and a file being moved. Therefore Darcs always
408 assumes the former, and provides the `darcs mv` command to let
409 Darcs know when you want the latter. This command will also move
410 the file in the working tree (unlike `darcs remove`), unless it has
411 already been moved.
412 Darcs will not rename a file if another file in the same folder has
414 the same name, except for case. The `--case-ok` option overrides
415 this behaviour. Windows and OS X usually use filesystems that do
416 not allow files a folder to have the same name except for case (for
417 example, `ReadMe` and `README`). If `--case-ok` is used, the
418 repository might be unusable on those systems!
419 darcs remove <file|directory> ...
421 The `darcs remove` command exists primarily for symmetry with
422 `darcs add`, as the normal way to remove a file from version con‐
423 trol is simply to delete it from the working tree. This command is
424 only useful in the unusual case where one wants to record a removal
425 patch WITHOUT deleting the copy in the working tree (which can be
426 re-added).
427 Note that applying a removal patch to a repository (e.g. by pulling
429 the patch) will ALWAYS affect the working tree of that repository.
430 darcs replace <old> <new> <file> ...
432 In addition to line-based patches, Darcs supports a limited form of
433 lexical substitution. Files are treated as sequences of words, and
434 each occurrence of the old word is replaced by the new word. This
435 is intended to provide a clean way to rename a function or vari‐
436 able. Such renamings typically affect lines all through the source
437 code, so a traditional line-based patch would be very likely to
438 conflict with other branches, requiring manual merging.
439 Files are tokenized according to one simple rule: words are strings
441 of valid token characters, and everything between them (punctuation
442 and whitespace) is discarded. By default, valid token characters
443 are letters, numbers and the underscore (i.e. `[A-Za-z0-9_]`).
444 However if the old and/or new token contains either a hyphen or
445 period, BOTH hyphen and period are treated as valid (i.e.
446 `[A-Za-z0-9_.-]`).
447 The set of valid characters can be customized using the
449 `--token-chars` option. The argument must be surrounded by square
450 brackets. If a hyphen occurs between two characters in the set, it
451 is treated as a set range. For example, in most locales `[A-Z]`
452 denotes all uppercase letters. If the first character is a caret,
453 valid tokens are taken to be the complement of the remaining char‐
454 acters. For example, `[^:\n]` could be used to match fields in the
455 passwd(5), where records and fields are separated by newlines and
456 colons respectively.
457 If you choose to use `--token-chars`, you are STRONGLY encouraged
459 to do so consistently. The consequences of using multiple replace
460 patches with different `--token-chars` arguments on the same file
461 are not well tested nor well understood.
462 By default Darcs will refuse to perform a replacement if the new
464 token is already in use, because the replacements would be not be
465 distinguishable from the existing tokens. This behaviour can be
466 overridden by supplying the `--force` option, but an attempt to
467 `darcs rollback` the resulting patch will affect these existing
468 tokens.
469 Limitations:
471 The tokenizer treats files as byte strings, so it is not possible
473 for `--token-chars` to include multi-byte characters, such as the
474 non-ASCII parts of UTF-8. Similarly, trying to replace a
475 "high-bit" character from a unibyte encoding will also result in
476 replacement of the same byte in files with different encodings.
477 For example, an acute a from ISO 8859-1 will also match an alpha
478 from ISO 8859-7.
479 Due to limitations in the patch file format, `--token-chars` argu‐
481 ments cannot contain literal whitespace. For example, `[^ \n\t]`
482 cannot be used to declare all characters except the space, tab and
483 newline as valid within a word, because it contains a literal
484 space.
485 Unlike POSIX regex(7) bracket expressions, character classes (such
487 as `[[:alnum:]]`) are NOT supported by `--token-chars`, and will be
488 silently treated as a simple set of characters.
489 Querying the repository:
492 darcs log [file|directory]...
493 The `darcs log` command lists patches of the current repository or,
494 with `--repo`, a remote repository. Without options or arguments,
495 ALL patches will be listed.
496 When given files or directories paths as arguments, only patches
498 which affect those paths are listed. This includes patches that
499 happened to files before they were moved or renamed.
500 When given `--from-tag` or `--from-patch`, only patches since that
502 tag or patch are listed. Similarly, the `--to-tag` and
503 `--to-patch` options restrict the list to older patches.
504 The `--last` and `--max-count` options both limit the number of
506 patches listed. The former applies BEFORE other filters, whereas
507 the latter applies AFTER other filters. For example `darcs log
508 foo.c --max-count 3` will print the last three patches that affect
509 foo.c, whereas `darcs log --last 3 foo.c` will, of the last three
510 patches, print only those that affect foo.c.
511 Four output formats exist. The default is `--human-readable`. The
513 slightly different `--machine-readable` format enables to see patch
514 dependencies in non-interactive mode. You can also select `--con‐
515 text`, which is an internal format that can be re-read by Darcs
516 (e.g. `darcs clone --context`).
517 Finally, there is `--xml-output`, which emits valid XML... unless a
519 the patch metadata (author, name or description) contains a
520 non-ASCII character and was recorded in a non-UTF8 locale.
521 darcs annotate [file|directory]
523 When `darcs annotate` is called on a file, it will find the patch
524 that last modified each line in that file. This also works on
525 directories.
526 The `--machine-readable` option can be used to generate output for
528 machine postprocessing.
529 darcs diff [file|directory]...
531 The `darcs diff` command compares two versions of the working tree
532 of the current repository. Without options, the pristine
533 (recorded) and unrecorded working trees are compared. This is
534 lower-level than the `darcs whatsnew` command, since it outputs a
535 line-by-line diff, and it is also slower. As with `darcs what‐
536 snew`, if you specify files or directories, changes to other files
537 are not listed. The command always uses an external diff utility.
538 With the `--patch` option, the comparison will be made between
540 working trees with and without that patch. Patches *after* the
541 selected patch are not present in either of the compared working
542 trees. The `--from-patch` and `--to-patch` options allow the set
543 of patches in the `old' and `new' working trees to be specified
544 separately.
545 The associated tag and match options are also understood, e.g.
547 `darcs diff --from-tag 1.0 --to-tag 1.1`. All these options assume
548 an ordering of the patch set, so results may be affected by opera‐
549 tions such as `darcs optimize reorder`.
550 diff(1) is called with the arguments `-rN`. The `--unified` option
552 causes `-u` to be passed to diff(1). An additional argument can be
553 passed using `--diff-opts`, such as `--diff-opts=-ud` or
554 `--diff-opts=-wU9`.
555 The `--diff-command` option can be used to specify an alternative
557 utility. Arguments may be included, separated by whitespace. The
558 value is not interpreted by a shell, so shell constructs cannot be
559 used. The arguments %1 and %2 MUST be included, these are substi‐
560 tuted for the two working trees being compared. For instance:
561 darcs diff -p . --diff-command "meld %1 %2"
563 If this option is used, `--diff-opts` is ignored.
565 darcs show contents [file]...
567 Show contents can be used to display an earlier version of some
568 file(s). If you give show contents no version arguments, it dis‐
569 plays the recorded version of the file(s).
570 darcs show dependencies
572 The `darcs show dependencies` command is used to create a graph of
573 the dependencies between patches of the repository (by default up
574 to last tag).
575 The resulting graph is described in Dot Language, a general example
577 of use could be:
578 darcs show dependencies | dot -Tpdf -o FILE.pdf
580 darcs show files [file|directory]...
582 The `darcs show files` command lists those files and directories in
583 the working tree that are under version control. This command is
584 primarily for scripting purposes; end users will probably want
585 `darcs whatsnew --summary`.
586 A file is "pending" if it has been added but not recorded. By
588 default, pending files (and directories) are listed; the
589 `--no-pending` option prevents this.
590 By default `darcs show files` lists both files and directories, but
592 the `--no-files` and `--no-directories` flags modify this behav‐
593 iour.
594 By default entries are one-per-line (i.e. newline separated). This
596 can cause problems if the files themselves contain newlines or
597 other control characters. To get around this, the `--null` option
598 uses the null character instead. The script interpreting output
599 from this command needs to understand this idiom; `xargs -0` is
600 such a command.
601 For example, to list version-controlled files by size:
603 darcs show files -0 | xargs -0 ls -ldS
605 darcs show index
607 The `darcs show index` command lists all version-controlled files
608 and directories along with their hashes as stored in
609 `_darcs/index`. For files, the fields correspond to file size,
610 sha256 of the current file content and the filename.
611 darcs show pristine
612 The `darcs show pristine` command lists all version-controlled
613 files and directories along with the hashes of their pristine
614 copies. For files, the fields correspond to file size, sha256 of
615 the pristine file content and the filename.
616 darcs show repo
617 The `darcs show repo` command displays statistics about the current
618 repository, allowing third-party scripts to access this information
619 without inspecting `_darcs` directly (and without breaking when the
620 `_darcs` format changes).
621 The 'Weak Hash' identifies the set of patches of a repository inde‐
623 pendently of ordering. It can be used to easily compare two reposi‐
624 tories of a same project. It is not cryptographically secure.
625 By default, output includes statistics that require walking through
627 the patches recorded in the repository, namely the 'Weak Hash' and
628 the count of patches. If this data isn't needed, use
629 `--no-enum-patches` to accelerate this command from O(n) to O(1).
630 By default, output is in a human-readable format. The `--xml-out‐
632 put` option can be used to generate output for machine postprocess‐
633 ing.
634 darcs show authors
636 The `darcs show authors` command lists the authors of the current
637 repository, sorted by the number of patches contributed. With the
638 `--verbose` option, this command simply lists the author of each
639 patch (without aggregation or sorting).
640 An author's name or email address may change over time. To tell
642 Darcs when multiple author strings refer to the same individual,
643 create an `.authorspellings` file in the root of the working tree.
644 Each line in this file begins with an author's canonical name and
645 address, and may be followed by a comma separated list of extended
646 regular expressions. Blank lines and lines beginning with two
647 hyphens are ignored. The format of `.authorspelling` can be
648 described by this pattern:
649 name <address> [, regexp ]*
651 There are some pitfalls concerning special characters: Whitespaces
653 are stripped, if you need space in regexp use [ ]. Because comma
654 serves as a separator you have to escape it if you want it in reg‐
655 exp. Note that `.authorspelling` use extended regular expressions
656 so +, ? and so on are metacharacters and you need to escape them to
657 be interpreted literally.
658 Any patch with an author string that matches the canonical address
660 or any of the associated regexps is considered to be the work of
661 that author. All matching is case-insensitive and partial (it can
662 match a substring). Use ^,$ to match the whole string in regexps
663 Currently this canonicalization step is done only in `darcs show
665 authors`. Other commands, such as `darcs log` use author strings
666 verbatim.
667 An example `.authorspelling` file is:
669 -- This is a comment.
671 Fred Nurk <fred@example.com>
672 John Snagge <snagge@bbc.co.uk>, John, snagge@, js@(si|mit).edu
673 Chuck Jones\, Jr. <chuck@pobox.com>, cj\+user@example.com
674 darcs show tags
676 The tags command writes a list of all tags in the repository to
677 standard output.
678 Tab characters (ASCII character 9) in tag names are changed to spa‐
680 ces for better interoperability with shell tools. A warning is
681 printed if this happens.
682 darcs show patch-index
684 When given the `--verbose` flag, the command dumps the complete
685 content of the patch index and checks its integrity.
686 darcs test [[initialization] command]
687 Run test on the current recorded state of the repository. Given no
688 arguments, it uses the default repository test (see `darcs set‐
689 pref`). Given one argument, it treats it as a test command. Given
690 two arguments, the first is an initialization command and the sec‐
691 ond is the test (meaning the exit code of the first command is not
692 taken into account to determine success of the test). If given the
693 `--linear` or `--bisect` flags, it tries to find the most recent
694 version in the repository which passes a test.
695 `--linear` does linear search starting from head, and moving away
697 from head. This strategy is best when the test runs very quickly or
698 the patch you're seeking is near the head.
699 `--bisect` does binary search. This strategy is best when the test
701 runs very slowly or the patch you're seeking is likely to be in the
702 repository's distant past.
703 `--backoff` starts searching from head, skipping further and fur‐
705 ther into the past until the test succeeds. It then does a binary
706 search on a subset of those skipped patches. This strategy works
707 well unless the patch you're seeking is in the repository's distant
708 past.
709 Under the assumption that failure is monotonous, `--linear` and
711 `--bisect` produce the same result. (Monotonous means that when
712 moving away from head, the test result changes only once from
713 "fail" to "ok".) If failure is not monotonous, any one of the
714 patches that break the test is found at random.
715 Undoing and correcting:
718 darcs revert [file|directory]...
719 The `darcs revert` command discards unrecorded changes the working
720 tree. As with `darcs record`, you will be asked which hunks
721 (changes) to revert. The `--all` switch can be used to avoid such
722 prompting. If files or directories are specified, other parts of
723 the working tree are not reverted.
724 In you accidentally reverted something you wanted to keep (for
726 example, typing `darcs rev -a` instead of `darcs rec -a`), you can
727 immediately run `darcs unrevert` to restore it. This is only guar‐
728 anteed to work if the repository has not changed since `darcs
729 revert` ran.
730 darcs unrevert
732 Unrevert is a rescue command in case you accidentally reverted
733 something you wanted to keep (for example, typing `darcs rev -a`
734 instead of `darcs rec -a`).
735 This command may fail if the repository has changed since the
737 revert took place. Darcs will ask for confirmation before execut‐
738 ing an interactive command that will DEFINITELY prevent unrever‐
739 sion.
740 darcs amend [file|directory]...
742 Amend updates a "draft" patch with additions or improvements,
743 resulting in a single "finished" patch.
744 By default `amend` proposes you to record additional changes. If
746 instead you want to remove changes, use the flag `--unrecord`.
747 When recording a draft patch, it is a good idea to start the name
749 with `DRAFT:`. When done, remove it with `darcs amend
750 --edit-long-comment`. Alternatively, to change the patch name
751 without starting an editor, use the `--name`/`-m` flag:
752 darcs amend --match 'name "DRAFT: foo"' --name 'foo2'
754 Like `darcs record`, if you call amend with files as arguments, you
756 will only be asked about changes to those files. So to amend a
757 patch to foo.c with improvements in bar.c, you would run:
758 darcs amend --match 'touch foo.c' bar.c
760 It is usually a bad idea to amend another developer's patch. To
762 make amend only ask about your own patches by default, you can add
763 something like `amend match David Roundy` to `~/.darcs/defaults`,
764 where `David Roundy` is your name.
765 darcs rebase pull [repository]...
767 Copy and apply patches from another repository, suspending any
768 local patches that conflict.
769 darcs rebase apply <patchfile>
770 Apply a patch bundle, suspending any local patches that conflict.
771 darcs rebase suspend
772 Select patches to move into a suspended state at the end of the
773 repo.
774 darcs rebase unsuspend
776 Selected patches to restore from a suspended state to the end of
777 the repo.
778 darcs rebase obliterate
780 Obliterate a patch that is currently suspended.
781 darcs rebase log
783 List the currently suspended changes.
784 darcs rollback [file|directory]...
786 Rollback is used to undo the effects of some changes from patches
787 in the repository. The selected changes are undone in your working
788 tree, but the repository is left unchanged. First you are offered a
789 choice of which patches to undo, then which changes within the
790 patches to undo.
791 Before doing `rollback`, you may want to temporarily undo the
793 changes of your working tree (if there are) and save them for later
794 use. To do so, you can run `revert`, then run `rollback`, record a
795 patch, and run `unrevert` to restore the saved changes into your
796 working tree.
797 darcs unrecord
799 Unrecord does the opposite of record: it deletes patches from the
800 repository, without changing the working tree. Deleting patches
801 from the repository makes active changes again which you may record
802 or revert later. Beware that you should not use this command if
803 there is a possibility that another user may have already pulled
804 the patch.
805 darcs obliterate
807 Obliterate completely removes recorded patches from your local
808 repository. The changes will be undone in your working tree and the
809 patches will not be shown in your changes list anymore. Beware that
810 you can lose precious code by obliterating!
811 One way to save obliterated patches is to use the -O flag. A patch
813 bundle will be created locally, that you will be able to apply
814 later to your repository with `darcs apply`.
815 Direct modification of the repository:
818 darcs tag [tagname]
819 The `darcs tag` command names the current repository state, so that
820 it can easily be referred to later. Every *important* state should
821 be tagged; in particular it is good practice to tag each stable
822 release with a number or codename. Advice on release numbering can
823 be found at <http://producingoss.com/en/development-cycle.html>.
824 To reproduce the state of a repository `R` as at tag `t`, use the
826 command `darcs clone --tag t R`. The command `darcs show tags`
827 lists all tags in the current repository.
828 Tagging also provides significant performance benefits: when Darcs
830 reaches a shared tag that depends on all antecedent patches, it can
831 simply stop processing.
832 Like normal patches, a tag has a name, an author, a timestamp and
834 an optional long description, but it does not change the working
835 tree. A tag can have any name, but it is generally best to pick a
836 naming scheme and stick to it.
837 By default a tag names the entire repository state at the time the
839 tag is created. If the --ask-deps option is used, the patches to
840 include as part of the tag can be explicitly selected.
841 The `darcs tag` command accepts the `--pipe` option, which behaves
843 as described in `darcs record`.
844 darcs setpref <pref> <value>
846 When working on project with multiple repositories and contribu‐
847 tors, it is sometimes desirable for a preference to be set consis‐
848 tently project-wide. This is achieved by treating a preference set
849 with `darcs setpref` as an unrecorded change, which can then be
850 recorded and then treated like any other patch.
851 Valid preferences are:
853 * test -- a shell command that runs regression tests * predist -- a
855 shell command to run before `darcs dist' * boringfile -- the path
856 to a version-controlled boring file * binariesfile -- the path to a
857 version-controlled binaries file
858 For example, a project using GNU autotools, with a `make test` tar‐
860 get to perform regression tests, might enable Darcs' integrated
861 regression testing with the following command:
862 darcs setpref test 'autoconf && ./configure && make && make
864 test'
865 Note that merging is not currently implemented for preferences: if
867 two patches attempt to set the same preference, the last patch
868 applied to the repository will always take precedence. This is
869 considered a low-priority bug, because preferences are seldom set.
870 Exchanging patches by e-mail:
873 darcs send [repository]
874 Send is used to prepare a bundle of patches that can be applied to
875 a target repository. Send accepts the URL of the repository as an
876 argument. When called without an argument, send will use the most
877 recent repository that was either pushed to, pulled from or sent
878 to. By default, the patch bundle is saved to a file, although you
879 may directly send it by mail.
880 The `--output`, `--output-auto-name`, and `--to` flags determine
882 what darcs does with the patch bundle after creating it. If you
883 provide an `--output` argument, the patch bundle is saved to that
884 file. If you specify `--output-auto-name`, the patch bundle is
885 saved to a file with an automatically generated name. If you give
886 one or more `--to` arguments, the bundle of patches is sent to
887 those locations. The locations may either be email addresses or
888 urls that the patch should be submitted to via HTTP.
889 If you provide the `--mail` flag, darcs will look at the contents
891 of the `_darcs/prefs/email` file in the target repository (if it
892 exists), and send the patch by email to that address. In this
893 case, you may use the `--cc` option to specify additional recipi‐
894 ents without overriding the default repository email address.
895 If `_darcs/prefs/post` exists in the target repository, darcs will
897 upload to the URL contained in that file, which may either be a
898 `mailto:` URL, or an `http://` URL. In the latter case, the patch
899 is posted to that URL.
900 If there is no email address associated with the repository, darcs
902 will prompt you for an email address.
903 Use the `--subject` flag to set the subject of the e-mail to be
905 sent. If you don't provide a subject on the command line, darcs
906 will make one up based on names of the patches in the patch bundle.
907 Use the `--in-reply-to` flag to set the In-Reply-To and References
909 headers of the e-mail to be sent. By default no additional headers
910 are included so e-mail will not be treated as reply by mail read‐
911 ers.
912 If you want to include a description or explanation along with the
914 bundle of patches, you need to specify the `--edit-description`
915 flag, which will cause darcs to open up an editor with which you
916 can compose a message to go along with your patches.
917 If you want to use a command different from the default one for
919 sending email, you need to specify a command line with the `--send‐
920 mail-command` option. The command line can contain some format
921 specifiers which are replaced by the actual values. Accepted format
922 specifiers are `%s` for subject, `%t` for to, `%c` for cc, `%b` for
923 the body of the mail, `%f` for from, `%a` for the patch bundle and
924 the same specifiers in uppercase for the URL-encoded values. Addi‐
925 tionally you can add `%<` to the end of the command line if the
926 command expects the complete email message on standard input. E.g.
927 the command lines for evolution and msmtp look like this:
928 evolution "mailto:%T?subject=%S&attach=%A&cc=%C&body=%B"
930 msmtp -t %<
931 Do not confuse the `--author` options with the return address that
933 `darcs send` will set for your patch bundle.
934 For example, if you have two email addresses A and B:
936 * If you use `--author A` but your machine is configured to send
938 mail from
939 address B by default, then the return address on your message
940 will be B. * If you use `--from A` and your mail client supports
941 setting the
942 From: address arbitrarily (some non-Unix-like mail clients, espe‐
943 cially,
944 may not support this), then the return address will be A; if it
945 does
946 not support this, then the return address will be B. * If you
947 supply neither `--from` nor `--author` then the return
948 address will be B.
949 In addition, unless you specify the sendmail command with `--send‐
951 mail-command`, darcs sends email using the default email command on
952 your computer. This default command is determined by the `config‐
953 ure` script. Thus, on some non-Unix-like OSes, `--from` is likely
954 to not work at all.
955 darcs apply <patchfile>
957 The `darcs apply` command takes a patch bundle and attempts to
958 insert it into the current repository. In addition to invoking it
959 directly on bundles created by `darcs send`, it is used internally
960 by `darcs push` on the remote end of an SSH connection.
961 If no file is supplied, the bundle is read from standard input.
963 If given an email instead of a patch bundle, Darcs will look for
965 the bundle as a MIME attachment to that email. Currently this will
966 fail if the MIME boundary is rewritten, such as in Courier and
967 Mail.app.
968 If the `--reply noreply@example.net` option is used, and the bundle
970 is attached to an email, Darcs will send a report (indicating suc‐
971 cess or failure) to the sender of the bundle (the `To` field). The
972 argument to noreply is the address the report will appear to origi‐
973 nate FROM.
974 The `--cc` option will cause the report to be CC'd to another
976 address, for example `--cc reports@lists.exam‐
977 ple.net,admin@lists.example.net`. Using `--cc` without `--reply`
978 is undefined.
979 If you want to use a command different from the default one for
981 sending mail, you need to specify a command line with the `--send‐
982 mail-command` option. The command line can contain the format
983 specifier `%t` for to and you can add `%<` to the end of the com‐
984 mand line if the command expects the complete mail on standard
985 input. For example, the command line for msmtp looks like this:
986 msmtp -t %<
988 If gpg(1) is installed, you can use `--verify pubring.gpg` to
990 reject bundles that aren't signed by a key in `pubring.gpg`.
991 If `--test` is supplied and a test is defined (see `darcs set‐
993 pref`), the bundle will be rejected if the test fails after apply‐
994 ing it. In that case, the rejection email from `--reply` will
995 include the test output.
996 A patch bundle may introduce unresolved conflicts with existing
998 patches or with the working tree. By default, Darcs will add con‐
999 flict markers (see `darcs mark-conflicts`).
1000 The `--external-merge` option lets you resolve these conflicts
1002 using an external merge tool. In the option, `%a` is replaced with
1003 the common ancestor (merge base), `%1` with the first version, `%2`
1004 with the second version, and `%o` with the path where your resolved
1005 content should go. For example, to use the xxdiff visual merge
1006 tool you'd specify: `--external-merge='xxdiff -m -O -M %o %1 %a
1007 %2'`
1008 The `--allow-conflicts` option will skip conflict marking; this is
1010 useful when you want to treat a repository as just a bunch of
1011 patches, such as using `darcs pull --union` to download of your
1012 co-workers patches before going offline.
1013 This can mess up unrecorded changes in the working tree, forcing
1015 you to resolve the conflict immediately. To simply reject bundles
1016 that introduce unresolved conflicts, using the `--dont-allow-con‐
1017 flicts` option. Making this the default in push-based workflows is
1018 strongly recommended.
1019 Unlike most Darcs commands, `darcs apply` defaults to `--all`. Use
1021 the `--interactive` option to pick which patches to apply from a
1022 bundle.
1023 Other commands:
1026 darcs optimize clean
1027 This command deletes obsolete files within the repository.
1028 darcs optimize http
1029 Using this option creates 'repository packs' that could dramati‐
1030 cally speed up performance when a user does a `darcs clone` of the
1031 repository over HTTP. To make use of packs, the clients must have a
1032 darcs of at least version 2.10.
1033 darcs optimize reorder
1035 This command moves recent patches (those not included in the latest
1036 tag) to the "front", reducing the amount that a typical remote com‐
1037 mand needs to download. It should also reduce the CPU time needed
1038 for some operations.
1039 darcs optimize enable-patch-index
1040 Build the patch index, an internal data structure that accelerates
1041 commands that need to know what patches touch a given file. Such as
1042 annotate and log.
1043 darcs optimize disable-patch-index
1044 Delete and stop maintaining the patch index from the repository.
1045 darcs optimize compress
1046 By default patches are compressed with zlib (RFC 1951) to reduce
1047 storage (and download) size. In exceptional circumstances, it may
1048 be preferable to avoid compression. In this case the `--dont-com‐
1049 press` option can be used (e.g. with `darcs record`) to avoid com‐
1050 pression.
1051 The `darcs optimize uncompress` and `darcs optimize compress` com‐
1053 mands can be used to ensure existing patches in the current reposi‐
1054 tory are respectively uncompressed or compressed.
1055 darcs optimize uncompress
1056 By default patches are compressed with zlib (RFC 1951) to reduce
1057 storage (and download) size. In exceptional circumstances, it may
1058 be preferable to avoid compression. In this case the `--dont-com‐
1059 press` option can be used (e.g. with `darcs record`) to avoid com‐
1060 pression.
1061 The `darcs optimize uncompress` and `darcs optimize compress` com‐
1063 mands can be used to ensure existing patches in the current reposi‐
1064 tory are respectively uncompressed or compressed.
1065 darcs optimize relink
1066 The `darcs optimize relink` command hard-links patches that the
1067 current repository has in common with its peers. Peers are those
1068 repositories listed in `_darcs/prefs/sources`, or defined with the
1069 `--sibling` option (which can be used multiple times).
1070 Darcs uses hard-links automatically, so this command is rarely
1072 needed. It is most useful if you used `cp -r` instead of `darcs
1073 clone` to copy a repository, or if you pulled the same patch from a
1074 remote repository into multiple local repositories.
1075 darcs optimize pristine
1076 This command updates the format of `_darcs/pristine.hashed/`, which
1077 was different before darcs 2.3.1.
1078 darcs optimize upgrade
1079 Convert old-fashioned repositories to the current default hashed
1080 format.
1081 darcs optimize cache <directory> ...
1082 This command deletes obsolete files within the global cache. It
1083 takes one or more directories as arguments, and recursively
1084 searches all repositories within these directories. Then it deletes
1085 all files in the global cache not belonging to these repositories.
1086 When no directory is given, it searches repositories in the user's
1087 home directory.
1088 It also automatically migrates the global cache to the (default)
1090 bucketed format.
1091 darcs dist
1093 `darcs dist` creates a compressed archive in the repository's root
1094 directory, containing the recorded state of the working tree
1095 (unrecorded changes and the `_darcs` directory are excluded). The
1096 command accepts matchers to create an archive of some past reposi‐
1097 tory state, for instance `--tag`.
1098 By default, the archive (and the top-level directory within the ar‐
1100 chive) has the same name as the repository, but this can be over‐
1101 ridden with the `--dist-name` option.
1102 If a predist command is set (see `darcs setpref`), that command
1104 will be run on the recorded state prior to archiving. For example,
1105 autotools projects would set it to `autoconf && automake`.
1106 If `--zip` is used, matchers and the predist command are ignored.
1108 darcs mark-conflicts [file|directory]...
1110 Darcs requires human guidance to unify changes to the same part of
1111 a source file. When a conflict first occurs, darcs will add the
1112 initial state and both choices to the working tree, delimited by
1113 the markers `v v v`, `=====`, `* * *` and `^ ^ ^`, as follows:
1114 v v v v v v v
1116 Initial state.
1117 =============
1118 First choice.
1119 *************
1120 Second choice.
1121 ^ ^ ^ ^ ^ ^ ^
1122 However, you might revert or manually delete these markers without
1124 actually resolving the conflict. In this case, `darcs mark-con‐
1125 flicts` is useful to show where are the unresolved conflicts. It
1126 is also useful if `darcs apply` or `darcs pull` is called with
1127 `--allow-conflicts`, where conflicts aren't marked initially.
1128 Unless you use the `--dry-run` flag, any unrecorded changes to the
1130 affected files WILL be lost forever when you run this command! You
1131 will be prompted for confirmation before this takes place.
1132 darcs repair
1134 The `darcs repair` command attempts to fix corruption in the cur‐
1135 rent repository. Currently it can only repair damage to the pris‐
1136 tine tree, which is where most corruption occurs. This command
1137 rebuilds a pristine tree by applying successively the patches in
1138 the repository to an empty tree.
1139 The flag `--dry-run` make this operation read-only, making darcs
1141 exit unsuccessfully (with a non-zero exit status) if the rebuilt
1142 pristine is different from the current pristine.
1143 darcs convert darcs-2 <source> [<destination>]
1145 This command converts a repository that uses the old patch seman‐
1146 tics `darcs-1` to a new repository with current `darcs-2` seman‐
1147 tics.
1148 WARNING: the repository produced by this command is not understood
1150 by Darcs 1.x, and patches cannot be exchanged between repositories
1151 in darcs-1 and darcs-2 formats.
1152 Furthermore, repositories created by different invocations of this
1154 command SHOULD NOT exchange patches.
1155 darcs convert export
1158 This command enables you to export darcs repositories into git.
1159 For a one-time export you can use the recipe:
1161 $ cd repo
1163 $ git init ../mirror
1164 $ darcs convert export | (cd ../mirror && git fast-import)
1165 For incremental export using marksfiles:
1167 $ cd repo
1169 $ git init ../mirror
1170 $ touch ../mirror/git.marks
1171 $ darcs convert export --read-marks darcs.marks --write-marks
1172 darcs.marks
1173 | (cd ../mirror && git fast-import --import-marks=git.marks
1174 --export-marks=git.marks)
1175 In the case of incremental export, be careful to never amend,
1177 delete or reorder patches in the source darcs repository.
1178 Also, be aware that exporting a darcs repo to git will not be
1180 exactly faithful in terms of history if the darcs repository con‐
1181 tains conflicts.
1182 Limitations:
1184 * Empty directories are not supported by the fast-export protocol.
1186 * Unicode filenames are currently not correctly handled.
1187 See http://bugs.darcs.net/issue2359 .
1188 darcs convert import [<directory>]
1190 This command imports git repositories into new darcs repositories.
1191 Further options are accepted (see `darcs help init`).
1192 To convert a git repo to a new darcs one you may run:
1194 $ (cd gitrepo && git fast-export --all -M) | darcs convert
1195 import darcsmirror
1196 WARNING: git repositories with branches will produce weird results,
1198 use at your own risks.
1199 Incremental import with marksfiles is currently not supported.
1201 darcs fetch [repository]...
1203 Fetch is similar to `pull` except that it does not apply any
1204 patches to the current repository. Instead, it generates a patch
1205 bundle that you can apply later with `apply`.
1206 Fetch's behaviour is essentially similar to pull's, so please con‐
1208 sult the help of `pull` to know more.
1209
1213 HOME and APPDATA
1214 Per-user preferences are set in $HOME/.darcs (on Unix) or %APP‐
1215 DATA%/darcs (on Windows). This is also the default location of the
1216 cache.
1217 DARCS_EDITOR, VISUAL, and EDITOR
1219 To edit a patch description of email comment, Darcs will invoke an
1220 external editor. Your preferred editor can be set as any of the envi‐
1221 ronment variables $DARCS_EDITOR, $VISUAL or $EDITOR. If none of these
1222 are set, nano is used. If nano crashes or is not found in your PATH,
1223 vi, emacs, emacs -nw and (on Windows) edit are each tried in turn.
1224 DARCS_PAGER and PAGER
1226 Darcs will invoke a pager if the output of some command is longer than
1227 20 lines. Darcs will use the pager specified by $DARCS_PAGER or $PAGER.
1228 If neither are set, `less` will be used.
1229 DARCS_DONT_COLOR, DARCS_ALWAYS_COLOR, DARCS_ALTERNATIVE_COLOR, and
1231 DARCS_DO_COLOR_LINES
1232 If the terminal understands ANSI color escape sequences, darcs will
1233 highlight certain keywords and delimiters when printing patches. This
1234 can be turned off by setting the environment variable DARCS_DONT_COLOR
1235 to 1. If you use a pager that happens to understand ANSI colors, like
1236 `less -R`, darcs can be forced always to highlight the output by set‐
1237 ting DARCS_ALWAYS_COLOR to 1. If you can't see colors you can set
1238 DARCS_ALTERNATIVE_COLOR to 1, and darcs will use ANSI codes for bold
1239 and reverse video instead of colors. In addition, there is an
1240 extra-colorful mode, which is not enabled by default, which can be
1241 activated with DARCS_DO_COLOR_LINES
1242 DARCS_DONT_ESCAPE_TRAILING_SPACES and DARCS_DONT_ESCAPE_TRAILING_CR
1244 By default darcs will escape (by highlighting if possible) any kind of
1245 spaces at the end of lines when showing patch contents. If you don't
1246 want this you can turn it off by setting DARCS_DONT_ESCAPE_TRAIL‐
1247 ING_SPACES to 1. A special case exists for only carriage returns:
1248 DARCS_DONT_ESCAPE_TRAILING_CR
1249 DARCS_DONT_ESCAPE_ANYTHING, DARCS_DONT_ESCAPE_EXTRA, DARCS_ESCAPE_EXTRA,
1251 DARCS_DONT_ESCAPE_ISPRINT, and DARCS_ESCAPE_8BIT
1252 Darcs needs to escape certain characters when printing patch contents
1253 to a terminal, depending on the encoding specified in your locale set‐
1254 ting.
1255 By default, darcs assumes that your locale encoding is ASCII compati‐
1257 ble. This includes UTF-8 and some 8-bit encodings like ISO/IEC-8859
1258 (including its variants). Since ASCII contains control characters like
1259 backspace (which could hide patch content from the user when printed
1260 literally to the terminal), and even ones that may introduce security
1261 risks such as redirecting commands to the shell, darcs needs to escape
1262 such characters. They are printed as `^<control letter>` or `\<hex
1263 code>`. Darcs also uses special markup for line endings that are pre‐
1264 ceeded by white space, since the white space would otherwise not be
1265 recognizable.
1266 If you use an encoding that is not ASCII compatible, things are some‐
1268 what less smooth. Such encodings include UTF-16 and UTF-32, as well as
1269 many of the encodings that became obsolete with unicode. In this case
1270 you have two options: you can set DARCS_DONT_ESCAPE_ANYTHING to 1. Then
1271 everything that doesn't flip code sets should work, and so will all the
1272 bells and whistles in your terminal. This environment variable can also
1273 be handy if you pipe the output to a pager or external filter that
1274 knows better than darcs how to handle your encoding. Note that all
1275 escaping, including the special escaping of any line ending spaces,
1276 will be turned off by this setting.
1277 Another possibility is to explicitly tell darcs to not escape or escape
1279 certain bytes, using DARCS_DONT_ESCAPE_EXTRA and DARCS_ESCAPE_EXTRA.
1280 Their values should be strings consisting of the verbatim bytes in
1281 question. The do-escapes take precedence over the dont-escapes. Space
1282 characters are still escaped at line endings though. The special envi‐
1283 ronment variable DARCS_DONT_ESCAPE_TRAILING_CR turns off escaping of
1284 carriage return last on the line (DOS style).
1285 For historical reasons, darcs also supports DARCS_DONT_ESCAPE_ISPRINT
1287 and DARCS_USE_ISPRINT (which are synonyms). These make sense only for
1288 8-bit encodings like ISO-8859 and are no longer needed since nowadays
1289 darcs does the right thing here by default.
1290 Finally, if you are in a highly security sensitive situation (or just
1292 paranoid for other reasons), you can set DARCS_ESCAPE_8BIT to 1. This
1293 will cause darcs to escape every non-ASCII byte in addition to ASCII
1294 control characters.
1295 DARCS_TMPDIR and TMPDIR
1297 Darcs often creates temporary directories. For example, the `darcs
1298 diff` command creates two for the working trees to be diffed. By
1299 default temporary directories are created in /tmp, or if that doesn't
1300 exist, in _darcs (within the current repo). This can be overridden by
1301 specifying some other directory in the file _darcs/prefs/tmpdir or the
1302 environment variable $DARCS_TMPDIR or $TMPDIR.
1303 DARCS_KEEP_TMPDIR
1305 If the environment variable DARCS_KEEP_TMPDIR is defined, darcs will
1306 not remove the temporary directories it creates. This is intended pri‐
1307 marily for debugging Darcs itself, but it can also be useful, for exam‐
1308 ple, to determine why your test preference (see `darcs setpref`) is
1309 failing when you run `darcs record`, but working when run manually.
1310 DARCS_EMAIL and EMAIL
1312 Each patch is attributed to its author, usually by email address (for
1313 example, `Fred Bloggs <fred@example.net>`). Darcs looks in several
1314 places for this author string: the `--author` option, the files
1315 `_darcs/prefs/author` (in the repository) and `~/.darcs/author` (in
1316 your home directory), and the environment variables `$DARCS_EMAIL` and
1317 `$EMAIL`. If none of those exist, Darcs will prompt you for an author
1318 string and write it to `~/.darcs/author`. Note that if you have more
1319 than one email address, you can put them all in `~/.darcs/author`, one
1320 author per line. Darcs will still prompt you for an author, but it
1321 allows you to select from the list, or to type in an alternative.
1322 SENDMAIL
1324 On Unix, the `darcs send` command relies on sendmail(8). The `--send‐
1325 mail-command` or $SENDMAIL environment variable can be used to provide
1326 an explicit path to this program; otherwise the standard locations
1327 /usr/sbin/sendmail and /usr/lib/sendmail will be tried.
1328 DARCS_SLOPPY_LOCKS
1330 If on some filesystems you get an error of the kind:
1331 darcs: takeLock [...]: atomic_create [...]: unsupported operation
1333 you may want to try to export DARCS_SLOPPY_LOCKS=True.
1335 DARCS_SSH
1337 Repositories of the form [user@]host:[dir] are taken to be remote
1338 repositories, which Darcs accesses with the external program ssh(1).
1339 The environment variable $DARCS_SSH can be used to specify an alterna‐
1341 tive SSH client. Arguments may be included, separated by whitespace.
1342 The value is not interpreted by a shell, so shell constructs cannot be
1343 used; in particular, it is not possible for the program name to contain
1344 whitespace by using quoting or escaping.
1345 DARCS_SCP and DARCS_SFTP
1347 When reading from a remote repository, Darcs will attempt to run `darcs
1348 transfer-mode` on the remote host. This will fail if the remote host
1349 only has Darcs 1 installed, doesn't have Darcs installed at all, or
1350 only allows SFTP.
1351 If transfer-mode fails, Darcs will fall back on scp(1) and sftp(1).
1353 The commands invoked can be customized with the environment variables
1354 $DARCS_SCP and $DARCS_SFTP respectively, which behave like $DARCS_SSH.
1355 If the remote end allows only sftp, try setting DARCS_SCP=sftp.
1356 SSH_PORT
1358 If this environment variable is set, it will be used as the port number
1359 for all SSH calls made by Darcs (when accessing remote repositories
1360 over SSH). This is useful if your SSH server does not run on the
1361 default port, and your SSH client does not support ssh_config(5).
1362 OpenSSH users will probably prefer to put something like `Host *.exam‐
1363 ple.net Port 443` into their ~/.ssh/config file.
1364 HTTP_PROXY, HTTPS_PROXY, FTP_PROXY, ALL_PROXY, and NO_PROXY
1366 If Darcs was built with libcurl, the environment variables HTTP_PROXY,
1367 HTTPS_PROXY and FTP_PROXY can be set to the URL of a proxy in the form
1368 [protocol://]<host>[:port]
1370 In which case libcurl will use the proxy for the associated protocol
1372 (HTTP, HTTPS and FTP). The environment variable ALL_PROXY can be used
1373 to set a single proxy for all libcurl requests.
1374 If the environment variable NO_PROXY is a comma-separated list of host
1376 names, access to those hosts will bypass proxies defined by the above
1377 variables. For example, it is quite common to avoid proxying requests
1378 to machines on the local network with
1379 NO_PROXY=localhost,*.localdomain
1381 For compatibility with lynx et al, lowercase equivalents of these envi‐
1383 ronment variables (e.g. $http_proxy) are also understood and are used
1384 in preference to the uppercase versions.
1385 If Darcs was not built with libcurl, all these environment variables
1387 are silently ignored, and there is no way to use a web proxy.
1388 DARCS_PROXYUSERPWD
1390 If Darcs was built with libcurl, and you are using a web proxy that
1391 requires authentication, you can set the $DARCS_PROXYUSERPWD environ‐
1392 ment variable to the username and password expected by the proxy, sepa‐
1393 rated by a colon. This environment variable is silently ignored if
1394 Darcs was not built with libcurl.
1395 DARCS_CONNECTION_TIMEOUT
1397 Set the maximum time in seconds that darcs allows and connection to
1398 take. If the variable is not specified the default are 30 seconds.
1399 This option only works with curl.
1400
1403 _darcs/prefs/motd
1404 The `_darcs/prefs/motd` file may contain a 'message of the day' which
1405 will be displayed to users who clone or pull from the repository with‐
1406 out the `--quiet` option.
1407 _darcs/prefs/email
1410 The `_darcs/prefs/email` file is used to provide the e-mail address for
1411 your repository that others will use when they `darcs send` a patch
1412 back to you. The contents of the file should simply be an e-mail
1413 address.
1414 _darcs/prefs/post
1417 If `_darcs/prefs/post` exists in the target repository, `darcs send `
1418 will upload to the URL contained in that file, which may either be a
1419 `mailto:` URL, or an `http://` URL. In the latter case, the patch is
1420 posted to that URL.
1421 _darcs/prefs/author
1424 The `_darcs/prefs/author` file contains the email address (or name) to
1425 be used as the author when patches are recorded in this repository,
1426 e.g. `David Roundy <droundy@abridgegame.org>`. This file overrides the
1427 contents of the environment variables `$DARCS_EMAIL` and `$EMAIL`.
1428 _darcs/prefs/defaults
1431 Default values for darcs commands. Each line of this file has the fol‐
1432 lowing form:
1433 COMMAND FLAG VALUE
1435 where `COMMAND` is either the name of the command to which the default
1437 applies, or `ALL` to indicate that the default applies to all commands
1438 accepting that flag. The `FLAG` term is the name of the long argument
1439 option without the `--`, i.e. `verbose` rather than `--verbose`.
1440 Finally, the `VALUE` option can be omitted if the flag does not involve
1441 a value. If the value has spaces in it, use single quotes, not double
1442 quotes, to surround it. Each line only takes one flag. To set multiple
1443 defaults for the same command (or for `ALL` commands), use multiple
1444 lines.
1445 Note that the use of `ALL` easily can have unpredicted consequences,
1447 especially if commands in newer versions of darcs accepts flags that
1448 they did not in previous versions. Only use safe flags with `ALL`.
1449 For example, if your system clock is bizarre, you could instruct darcs
1451 to always ignore the file modification times by adding the following
1452 line:
1453 ALL ignore-times
1455 There are some options which are meant specifically for use in
1457 `_darcs/prefs/defaults`. One of them is `--disable`. As the name sug‐
1458 gests, this option will disable every command that got it as argument.
1459 So, if you are afraid that you could damage your repositories by inad‐
1460 vertent use of a command like amend, add the following line:
1461 amend disable
1463 Also, a global preferences file can be created with the name
1465 `.darcs/defaults` in your home directory. Options present there will be
1466 added to the repository-specific preferences if they do not conflict.
1467 _darcs/prefs/sources
1470 The `_darcs/prefs/sources` file is used to indicate alternative loca‐
1471 tions from which to download patches. This file contains lines such as:
1472 cache:/home/droundy/.cache/darcs
1474 readonly:/home/otheruser/.cache/darcs
1475 repo:http://darcs.net
1476 This would indicate that darcs should first look in
1478 `/home/droundy/.cache/darcs` for patches that might be missing, and if
1479 the patch is not there, it should save a copy there for future use. In
1480 that case, darcs will look in `/home/otheruser/.cache/darcs` to see if
1481 that user might have downloaded a copy, but will not try to save a copy
1482 there, of course. Finally, it will look in `http://darcs.net`. Note
1483 that the `sources` file can also exist in `~/.darcs/`. Also note that
1484 the sources mentioned in your `sources` file will be tried *before* the
1485 repository you are pulling from. This can be useful in avoiding down‐
1486 loading patches multiple times when you pull from a remote repository
1487 to more than one local repository.
1488 A global cache is enabled by default in your home directory. The cache
1490 allows darcs to avoid re-downloading patches (for example, when doing a
1491 second darcs clone of the same repository), and also allows darcs to
1492 use hard links to reduce disk usage.
1493 Note that the cache directory should reside on the same filesystem as
1495 your repositories, so you may need to vary this. You can also use mul‐
1496 tiple cache directories on different filesystems, if you have several
1497 filesystems on which you use darcs.
1498 _darcs/prefs/boring
1501 The `_darcs/prefs/boring` file may contain a list of regular expres‐
1502 sions describing files, such as object files, that you do not expect to
1503 add to your project. A newly created repository has a boring file that
1504 includes many common source control, backup, temporary, and compiled
1505 files.
1506 You may want to have the boring file under version control. To do this
1508 you can use darcs setpref to set the value 'boringfile' to the name of
1509 your desired boring file (e.g. `darcs setpref boringfile .boring`,
1510 where `.boring` is the repository path of a file that has been darcs
1511 added to your repository). The boringfile preference overrides
1512 `_darcs/prefs/boring`, so be sure to copy that file to the boringfile.
1513 You can also set up a 'boring' regexps file in your home directory,
1515 named `~/.darcs/boring`, which will be used with all of your darcs
1516 repositories.
1517 Any file not already managed by darcs and whose repository path matches
1519 any of the boring regular expressions is considered boring. The boring
1520 file is used to filter the files provided to darcs add, to allow you to
1521 use a simple `darcs add newdir newdir/*` without accidentally adding a
1522 bunch of object files. It is also used when the `--look-for-adds` flag
1523 is given to whatsnew or record. Note that once a file has been added to
1524 darcs, it is not considered boring, even if it matches the boring file
1525 filter.
1526 _darcs/prefs/binaries
1529 The `_darcs/prefs/binaries` file may contain a list of regular expres‐
1530 sions describing files that should be treated as binary files rather
1531 than text files. Darcs automatically treats files containing characters
1532 `^Z` or `NULL` within the first 4096 bytes as being binary files. You
1533 probably will want to have the binaries file under version control. To
1534 do this you can use `darcs setpref` to set the value 'binariesfile' to
1535 the name of your desired binaries file (e.g. `darcs setpref binaries‐
1536 file ./.binaries`, where `.binaries` is a file that has been darcs
1537 added to your repository). As with the boring file, you can also set up
1538 a `~/.darcs/binaries` file if you like.
1539 _darcs/prefs/defaultrepo
1542 Contains the URL of the default remote repository used by commands
1543 `pull`, `push`, `send` and `optimize relink`. Darcs edits this file
1544 automatically or when the flag `--set-default` is used.
1545 _darcs/prefs/tmpdir
1548 By default temporary directories are created in `/tmp`, or if that
1549 doesn't exist, in `_darcs` (within the current repo). This can be
1550 overridden by specifying some other directory in the file
1551 `_darcs/prefs/tmpdir` or the environment variable `$DARCS_TMPDIR` or
1552 `$TMPDIR`.
1553 _darcs/prefs/prefs
1556 Contains the preferences set by the command `darcs setprefs`. Do not
1557 edit manually.
1558
1562 At http://bugs.darcs.net/ you can find a list of known bugs in Darcs.
1563 Unknown bugs can be reported at that site (after creating an account)
1564 or by emailing the report to bugs@darcs.net.
1565
1567 The Darcs website provides a lot of additional information. It can be
1568 found at http://darcs.net/
1569
1571 Darcs is free software; you can redistribute it and/or modify it under
1572 the terms of the GNU General Public License as published by the Free
1573 Software Foundation; either version 2, or (at your option) any later
1574 version.
1575 2.14.2 (release) DARCS(1)