1DARCS(1)                    General Commands Manual                   DARCS(1)
2
3
4

NAME

6       darcs - an advanced revision control system
7

SYNOPSIS

9       darcs command <arguments|[options]>...
10
11       Where the commands and their respective arguments are
12
13       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 rebase upgrade
47       darcs rollback [file|directory]...
48       darcs unrecord
49       darcs obliterate
50       darcs tag [tagname]
51       darcs setpref <pref> <value>
52       darcs send [repository]
53       darcs apply <patchfile>
54       darcs optimize clean
55       darcs optimize http
56       darcs optimize reorder
57       darcs optimize enable-patch-index
58       darcs optimize disable-patch-index
59       darcs optimize compress
60       darcs optimize uncompress
61       darcs optimize relink
62       darcs optimize pristine
63       darcs optimize upgrade
64       darcs optimize cache <directory> ...
65       darcs dist
66       darcs mark-conflicts [file|directory]...
67       darcs repair
68       darcs convert darcs-2 <source> [<destination>]
69       darcs convert export
70       darcs convert import [<directory>]
71       darcs fetch [repository]...
72

DESCRIPTION

74       Unlike  conventional revision control systems, Darcs is based on track‐
75       ing changes, rather than versions: it can and does automatically re-or‐
76       der independent changes when needed. This means that in Darcs the state
77       of a repository should be regarded as a set of patches  rather  than  a
78       sequence of versions.
79
80       Another  distinguishing  feature of darcs is that most commands are in‐
81       teractive by default. For instance, `darcs record' (the  equivalent  of
82       what  is  usually  called  `commit')  presents you with each unrecorded
83       change and asks you whether it should be included in the  patch  to  be
84       recorded.  Similarly,  `darcs  push'  and `darcs pull' present you with
85       each patch, allowing you to select which patches to push or pull.
86

OPTIONS

88       Different options are accepted by different Darcs commands.  Each  com‐
89       mand's  most important options are listed in the COMMANDS section.  For
90       a full list of all options accepted by a particular command, run `darcs
91       command --help'.
92
93   Selecting Patches:
94       The  --patches  option yields patches with names matching an *extended*
95       regular expression.  See regex(7) for details.   The  --matches  option
96       yields  patches  that match a logical (Boolean) expression: one or more
97       primitive expressions combined by grouping (parentheses) and  the  com‐
98       plement (not), conjunction (and) and disjunction (or) operators.  The C
99       notation for logic operators (!, && and ||) can also be used.
100
101           --patches=regex is a synonym for --matches='name regex'
102           --hash=HASH is a synonym for --matches='hash HASH'
103           --from-patch and --to-patch are synonyms for
104             --from-match='name... and --to-match='name...
105           --from-patch and --to-match can be unproblematically combined:
106             `darcs log --from-patch='html.*docu' --to-match='date 20040212'`
107
108       The following primitive Boolean expressions are supported:
109
110           exact STRING - check literal STRING is equal to patch name.
111           name REGEX - match REGEX against patch name.
112           author REGEX - match REGEX against patch author.
113           hunk REGEX - match REGEX against contents of a hunk patch.
114           comment REGEX - match REGEX against the full log message.
115           hash HASH - match HASH against (a prefix of) the hash of a patch.
116           date DATE - match DATE against the patch date.
117           touch REGEX - match file paths for a patch.
118
119       Here are some examples:
120
121           darcs log --match 'exact "Resolve issue17: use dynamic memory allo‐
122       cation."'
123           darcs log --match 'name issue17'
124           darcs log --match 'name "^[Rr]esolve issue17>"'
125           darcs log --match 'author "David Roundy"'
126           darcs log --match 'author droundy'
127           darcs log --match 'author droundy@darcs.net'
128           darcs log --match 'hunk "foo = 2"'
129           darcs log --match 'hunk "^instance .* Foo where$"'
130           darcs log --match 'comment "prevent deadlocks"'
131           darcs log --match 'hash c719567e92c3b0ab9eddd5290b705712b8b918ef'
132           darcs log --match 'hash c7195'
133           darcs log --match 'date "2006-04-02 22:41"'
134           darcs log --match 'date "tea time yesterday"'
135           darcs log --match 'touch src/foo.c'
136           darcs log --match 'touch src/'
137           darcs log --match 'touch "src/*.(c|h)"'
138

COMMANDS

140       darcs help [<darcs_command> [darcs_subcommand]]
141           Without  arguments, `darcs help` prints a categorized list of darcs
142           commands and a short description of each one. With an  extra  argu‐
143           ment, `darcs help foo` prints detailed help about the darcs command
144           foo.
145
146
147   Most used/starting out:
148       darcs initialize [<directory>]
149           The `darcs initialize` command creates an empty repository  in  the
150           current  directory.  This repository lives in a new `_darcs` direc‐
151           tory, which stores version control metadata and settings.
152
153           Existing files and subdirectories are not touched. You  can  record
154           them with `darcs record --look-for-adds`.
155
156           Initialize is commonly abbreviated to `init`.
157
158           Darcs  currently supports three kinds of patch semantics. These are
159           called `darcs-1`, `darcs-2`, and `darcs-3`. They are  mutually  in‐
160           compatible, that is, you cannot exchange patches between repos with
161           different semantics.
162
163           By default, patches of the new repository are in the darcs-2 seman‐
164           tics.  However it is possible to create a repository in darcs-1 se‐
165           mantics with the flag `--darcs-1`, althought  this  is  not  recom‐
166           mended  except for sharing patches with a project that uses patches
167           in the darcs-1 semantics.
168
169           The `darcs-3` semantics is EXPERIMENTAL and new in version 2.16. It
170           is included only as a technology preview and we do NOT recommend to
171           use it for any serious work. The on-disk format is not  yet  final‐
172           ized  and  we  cannot and will not promise that later releases will
173           work with darcs-3 repos created with any darcs version before 3.0.
174
175       darcs add <file|directory> ...
176           Generally the working tree contains both files that should be  ver‐
177           sion  controlled  (such as source code) and files that Darcs should
178           ignore (such as executables compiled from the  source  code).   The
179           `darcs  add`  command  is used to tell Darcs which files to version
180           control.
181
182           When an existing project is first imported into a Darcs repository,
183           it  is  common  to run `darcs add -r *` or `darcs record -l` to add
184           all initial source files into darcs.
185
186           Adding symbolic links (symlinks) is not supported.
187
188           Darcs will ignore all files and folders that  look  "boring".   The
189           `--boring` option overrides this behaviour.
190
191           Darcs  will not add file if another file in the same folder has the
192           same name, except for case.  The `--case-ok` option overrides  this
193           behaviour.   Windows  and  OS X usually use filesystems that do not
194           allow files a folder to have the same name except for case (for ex‐
195           ample, `ReadMe` and `README`).  If `--case-ok` is used, the reposi‐
196           tory might be unusable on those systems!
197
198
199
200       darcs whatsnew [file|directory]...
201           The `darcs whatsnew` command lists unrecorded changes to the  work‐
202           ing  tree.  If you specify a set of files and directories, only un‐
203           recorded changes to those files and directories are listed.
204
205           With the `--summary` option, the changes are condensed to one  line
206           per  file,  with mnemonics to indicate the nature and extent of the
207           change. The `--look-for-adds` option causes candidates  for  `darcs
208           add`  to  be included in the summary output.  WithSummary mnemonics
209           are as follows:
210
211             * `A f` and `A d/` respectively mean an added file or directory.
212             * `R f` and `R d/` respectively mean a removed file or directory.
213             * `M f -N +M rP` means a modified file, with `N`  lines  deleted,
214           `M`
215               lines added, and `P` lexical replacements.
216             * `f -> g` means a moved file or directory.
217             * `a f` and `a d/` respectively mean a new, but unadded, file or
218               directory, when using `--look-for-adds`.
219             * An exclamation mark (!) as in `R! foo.c`, means the change
220               conflicts with a change in an earlier patch. The phrase `dupli‐
221           cated`
222               means the change is identical to a change in an earlier patch.
223
224           The `--machine-readable` option implies `--summary` while making it
225           more  parsable.  Modified  files are only shown as `M f`, and moves
226           are shown in two lines: `F f` and `T g` (as in 'From f To g').
227
228           By default,  `darcs  whatsnew`  uses  Darcs'  internal  format  for
229           changes.  To see some context (unchanged lines) around each change,
230           use the `--unified` option. To view changes in conventional  `diff`
231           format,  use  the  `darcs diff` command; but note that `darcs what‐
232           snew` is faster.
233
234           This command exits unsuccessfully (returns a non-zero exit  status)
235           if there are no unrecorded changes.
236
237       darcs record [file|directory]...
238           The  `darcs  record` command is used to create a patch from changes
239           in the working tree. If you specify a set of files and directories,
240           changes to other files will be skipped.
241
242           Every  patch  has  a name, an optional description, an author and a
243           date.
244
245           Darcs will launch a text editor (see `darcs help environment`)  af‐
246           ter  the  interactive  selection,  to  let you enter the patch name
247           (first line) and the patch description (subsequent lines).
248
249           You can supply the patch name in advance with the `-m`  option,  in
250           which case no text editor is launched, unless you use `--edit-long-
251           comment`.
252
253           The patch description is an optional block of free-form text. It is
254           used to supply additional information that doesn't fit in the patch
255           name. For example, it might include a rationale of WHY  the  change
256           was necessary.
257
258           A technical difference between patch name and patch description, is
259           that matching with the flag `-p` is only done on patch names.
260
261           Finally, the `--logfile` option allows you to supply  a  file  that
262           already  contains the patch name and description. This is useful if
263           a previous record failed and left a  `_darcs/patch_description.txt`
264           file.
265
266           Each  patch  is  attributed to its author, usually by email address
267           (for example, `Fred Bloggs  <fred@example.net>`).  Darcs  looks  in
268           several  places  for this author string: the `--author` option, the
269           files `_darcs/prefs/author` (in the repository)  and  `~/.darcs/au‐
270           thor`  (in  your  home  directory),  and  the environment variables
271           `$DARCS_EMAIL` and `$EMAIL`. If none of  those  exist,  Darcs  will
272           prompt  you for an author string and write it to `~/.darcs/author`.
273           Note that if you have more than one email address, you can put them
274           all  in  `~/.darcs/author`,  one  author per line. Darcs will still
275           prompt you for an author, but it allows  you  to  select  from  the
276           list, or to type in an alternative.
277
278           If  you  want to manually define any explicit dependencies for your
279           patch, you can use the `--ask-deps` flag. Some dependencies may  be
280           automatically  inferred  from the patch's content and cannot be re‐
281           moved. A patch with specific dependencies can be empty.
282
283           The patch date is generated automatically. It can only  be  spoofed
284           by using the `--pipe` option.
285
286           If  you  run  record with the `--pipe` option, you will be prompted
287           for the patch date, author, and the long comment. The long  comment
288           will  extend until the end of file or stdin is reached. This inter‐
289           face is intended for scripting darcs,  in  particular  for  writing
290           repository conversion scripts. The prompts are intended mostly as a
291           useful guide (since scripts won't need them), to  help  you  under‐
292           stand  the  input  format.  Here's  an example of what the `--pipe`
293           prompts look like:
294
295               What is the date? Mon Nov 15 13:38:01 EST 2004
296               Who is the author? David Roundy
297               What is the log? One or more comment lines
298
299           If a test command has been defined with `darcs setpref`, attempting
300           to  record a patch will cause the test command to be run in a clean
301           copy  of  the  working  tree  (that  is,  including  only  recorded
302           changes).  If  the  test  fails,  you  will be offered to abort the
303           record operation.
304
305           The `--set-scripts-executable` option causes scripts to be made ex‐
306           ecutable  in  the  clean copy of the working tree, prior to running
307           the test. See `darcs  clone`  for  an  explanation  of  the  script
308           heuristic.
309
310           If  your  test  command is tediously slow (e.g. `make all`) and you
311           are recording several patches in a row, you may wish to use  `--no-
312           test` to skip all but the final test.
313
314           To  see  some context (unchanged lines) around each change, use the
315           `--unified` option.
316
317       darcs clone <repository> [<directory>]
318           Clone creates a copy of a repository. The optional second  argument
319           specifies  a destination directory for the new copy; if omitted, it
320           is inferred from the source location.
321
322           By default Darcs will copy every patch from  the  original  reposi‐
323           tory.  If  you expect the original repository to remain accessible,
324           you can use `--lazy` to avoid copying patches until they are needed
325           ('copy  on demand'). This is particularly useful when copying a re‐
326           mote repository with a long history that you don't care about.
327
328           When cloning locally, Darcs automatically uses hard  linking  where
329           possible. As well as saving time and space, this enables to move or
330           delete the original repository without  affecting  the  copy.  Hard
331           linking  requires  that  the  copy be on the same filesystem as the
332           original repository, and that the filesystem support hard  linking.
333           This  includes  NTFS, HFS+ and all general-purpose Unix filesystems
334           (such as ext, UFS and ZFS). FAT does not support hard links.
335
336           When cloning from a remote location, Darcs will look  for  and  at‐
337           tempt  to  use packs created by `darcs optimize http` in the remote
338           repository. Packs are single  big  files  that  can  be  downloaded
339           faster than many little files.
340
341           Darcs  clone will not copy unrecorded changes to the source reposi‐
342           tory's working tree.
343
344           You can copy a repository to a ssh  url,  in  which  case  the  new
345           repository will always be complete.
346
347           It  is often desirable to make a copy of a repository that excludes
348           some patches.  For example, if  releases  are  tagged  then  `darcs
349           clone --tag .` would make a copy of the repository as at the latest
350           release. An untagged repository state can still be identified unam‐
351           biguously by a context file, as generated by `darcs log --context`.
352           Given the name of such a file, the `--context` option will create a
353           repository that includes only the patches from that context. When a
354           user reports a bug in an unreleased version of  your  project,  the
355           recommended  way to find out exactly what version they were running
356           is to have them include a context file in the bug report.  You  can
357           also  make  a  copy  of an untagged state using the `--to-patch` or
358           `--to-match` options,  which  exclude  patches  *after*  the  first
359           matching  patch.  Because these options treat the set of patches as
360           an ordered sequence, you may get different results after reordering
361           with `darcs optimize reorder`.
362
363           The `--set-scripts-executable` option causes scripts to be made ex‐
364           ecutable in the working tree. A script is any file that starts with
365           a shebang ("#!").
366
367           The  --inherit-default option is meant to support a work flow where
368           you have different branches of the  same  upstream  repository  and
369           want  all  your  branches to have the same upstream repo as the de‐
370           faultrepo. It is most useful when enabled globally by  adding  'ALL
371           --inherit-default' to your ~/darcs/defaults file.
372
373           For the clone command it means the following: If the source reposi‐
374           tory already has a defaultrepo set (either because you cloned it or
375           because  you  explicitly  used  the --set-default option), and both
376           source and target are locally valid paths on the  same  host,  then
377           the  target  repo will get the same defaultrepo as the source repo.
378           Otherwise the target repo gets the source repo itself  as  default‐
379           repo,  i.e.  we  fall back to the defalt behavior (--no-inherit-de‐
380           fault).
381
382       darcs pull [repository]...
383           Pull is used to bring patches made in another repository  into  the
384           current  repository  (that is, either the one in the current direc‐
385           tory, or the one specified with the `--repodir` option).  Pull  ac‐
386           cepts arguments, which are URLs from which to pull, and when called
387           without an argument, pull will  use  the  repository  specified  at
388           `_darcs/prefs/defaultrepo`.
389
390           The default (`--union`) behavior is to pull any patches that are in
391           any of the specified repositories. If you specify the  `--intersec‐
392           tion` flag, darcs will only pull those patches which are present in
393           all source repositories. If you specify  the  `--complement`  flag,
394           darcs  will  only pull elements in the first repository that do not
395           exist in any of the remaining repositories.
396
397           If `--reorder` is supplied, the set of patches that exist  only  in
398           the  current  repository  is brought at the top of the current his‐
399           tory. This will work even if there are no new patches to pull.
400
401           The --inherit-default option is meant to support a work flow  where
402           you  have  different  branches  of the same upstream repository and
403           want all your branches to have the same upstream repo  as  the  de‐
404           faultrepo.  It  is most useful when enabled globally by adding 'ALL
405           --inherit-default' to your ~/darcs/defaults file.
406
407           For the commands push, pull,  and  send  it  means  the  following:
408           Changes the meaning of the --set-default option so that it sets the
409           (local) defaultrepo to the defaultrepo of the remote repo,  instead
410           of  the  remote  repo  itself. This happens only if the remote repo
411           does have a defaultrepo set and both local and remote  repositories
412           are  locally  valid  paths on the same host, otherwise fall back to
413           the default behavior (--no-inherit-default).
414
415           See `darcs help apply` for detailed description of many options.
416
417       darcs push [repository]
418           Push is the opposite of pull. Push allows you to copy patches  from
419           the current repository into another repository.
420
421           If  you  give the `--apply-as` flag, darcs will use `sudo` to apply
422           the patches as a different user. This can be useful if you want  to
423           set up a system where several users can modify the same repository,
424           but you don't want to allow them full write access. This isn't  se‐
425           cure  against skilled malicious attackers, but at least can protect
426           your repository from clumsy, inept or lazy users.
427
428           `darcs push` will compress the patch data before sending  it  to  a
429           remote  location via ssh. This works as long as the remote darcs is
430           not older than version 2.5. If you get errors that indicate a  cor‐
431           rupt  patch  bundle,  you should try again with the `--no-compress`
432           option.
433
434           The --inherit-default option is meant to support a work flow  where
435           you  have  different  branches  of the same upstream repository and
436           want all your branches to have the same upstream repo  as  the  de‐
437           faultrepo.  It  is most useful when enabled globally by adding 'ALL
438           --inherit-default' to your ~/darcs/defaults file.
439
440           For the commands push, pull,  and  send  it  means  the  following:
441           Changes the meaning of the --set-default option so that it sets the
442           (local) defaultrepo to the defaultrepo of the remote repo,  instead
443           of  the  remote  repo  itself. This happens only if the remote repo
444           does have a defaultrepo set and both local and remote  repositories
445           are  locally  valid  paths on the same host, otherwise fall back to
446           the default behavior (--no-inherit-default).
447
448
449   Preparing patches before recording:
450       darcs move <source> ... <destination>
451           Darcs cannot reliably distinguish between a file being deleted  and
452           a  new  one  added, and a file being moved.  Therefore Darcs always
453           assumes the former, and provides the  `darcs  mv`  command  to  let
454           Darcs  know  when you want the latter.  This command will also move
455           the file in the working tree (unlike `darcs remove`), unless it has
456           already been moved.
457
458           Darcs will not rename a file if another file in the same folder has
459           the same name, except for case.  The `--case-ok`  option  overrides
460           this  behaviour.   Windows and OS X usually use filesystems that do
461           not allow files a folder to have the same name except for case (for
462           example,  `ReadMe`  and  `README`).   If  `--case-ok`  is used, the
463           repository might be unusable on those systems!
464
465
466       darcs remove <file|directory> ...
467           The `darcs remove`  command  exists  primarily  for  symmetry  with
468           `darcs  add`,  as the normal way to remove a file from version con‐
469           trol is simply to delete it from the working tree.  This command is
470           only useful in the unusual case where one wants to record a removal
471           patch WITHOUT deleting the copy in the working tree (which  can  be
472           re-added).
473
474           Note that applying a removal patch to a repository (e.g. by pulling
475           the patch) will ALWAYS affect the working tree of that repository.
476
477
478       darcs replace <old> <new> <file> ...
479           In addition to line-based patches, Darcs supports a limited form of
480           lexical substitution.  Files are treated as sequences of words, and
481           each occurrence of the old word is replaced by the new word.   This
482           is  intended  to  provide a clean way to rename a function or vari‐
483           able.  Such renamings typically affect lines all through the source
484           code,  so  a  traditional  line-based patch would be very likely to
485           conflict with other branches, requiring manual merging.
486
487           Files are tokenized according to one simple rule: words are strings
488           of valid token characters, and everything between them (punctuation
489           and whitespace) is discarded.  By default, valid  token  characters
490           are  letters,  numbers  and  the  underscore (i.e. `[A-Za-z0-9_]`).
491           However if the old and/or new token contains either a hyphen or pe‐
492           riod,  BOTH  hyphen  and  period are treated as valid (i.e. `[A-Za-
493           z0-9_.-]`).
494
495           The set of valid characters can be customized using  the  `--token-
496           chars` option.  The argument must be surrounded by square brackets.
497           If a hyphen occurs between two characters in the set, it is treated
498           as  a  set range.  For example, in most locales `[A-Z]` denotes all
499           uppercase letters.  If the first character is a caret, valid tokens
500           are  taken  to  be the complement of the remaining characters.  For
501           example, `[^:0` could be used to match  fields  in  the  passwd(5),
502           where  records  and fields are separated by newlines and colons re‐
503           spectively.
504
505           If you choose to use `--token-chars`, you are  STRONGLY  encouraged
506           to  do so consistently.  The consequences of using multiple replace
507           patches with different `--token-chars` arguments on the  same  file
508           are not well tested nor well understood.
509
510           By  default  Darcs  will refuse to perform a replacement if the new
511           token is already in use, because the replacements would be  not  be
512           distinguishable  from  the  existing tokens.  This behaviour can be
513           overridden by supplying the `--force` option,  but  an  attempt  to
514           `darcs rollback` the resulting patch will affect these existing to‐
515           kens.
516
517           Limitations:
518
519           The tokenizer treats files as byte strings, so it is  not  possible
520           for  `--token-chars`  to include multi-byte characters, such as the
521           non-ASCII parts of UTF-8.  Similarly, trying to  replace  a  "high-
522           bit" character from a unibyte encoding will also result in replace‐
523           ment of the same byte in files with different encodings.  For exam‐
524           ple,  an  acute a from ISO 8859-1 will also match an alpha from ISO
525           8859-7.
526
527           Due to limitations in the patch file format, `--token-chars`  argu‐
528           ments  cannot contain literal whitespace.  For example, `[^ ]` can‐
529           not be used to declare all characters except  the  space,  tab  and
530           newline  as  valid  within  a  word,  because it contains a literal
531           space.
532
533           Unlike POSIX regex(7) bracket expressions, character classes  (such
534           as `[[:alnum:]]`) are NOT supported by `--token-chars`, and will be
535           silently treated as a simple set of characters.
536
537
538
539   Querying the repository:
540       darcs log [file|directory]...
541           The `darcs log` command lists patches of the current repository or,
542           with  `--repo`,  a remote repository. Without options or arguments,
543           ALL patches will be listed.
544
545           When given files or directories paths as  arguments,  only  patches
546           which  affect  those  paths  are listed. This includes patches that
547           happened to files before they were moved or renamed.
548
549           When given `--from-tag` or `--from-patch`, only patches since  that
550           tag or patch are listed. Similarly, the `--to-tag` and `--to-patch`
551           options restrict the list to older patches.
552
553           The `--last` and `--max-count` options both  limit  the  number  of
554           patches  listed.   The former applies BEFORE other filters, whereas
555           the latter applies AFTER other  filters.  For  example  `darcs  log
556           foo.c  --max-count 3` will print the last three patches that affect
557           foo.c, whereas `darcs log --last 3 foo.c` will, of the  last  three
558           patches, print only those that affect foo.c.
559
560           Four  output  formats exist. The default is `--human-readable`. The
561           slightly different `--machine-readable` format enables to see patch
562           dependencies  in  non-interactive mode. You can also select `--con‐
563           text`, which is an internal format that can  be  re-read  by  Darcs
564           (e.g. `darcs clone --context`).
565
566           Finally, there is `--xml-output`, which emits valid XML... unless a
567           the patch metadata (author, name or description)  contains  a  non-
568           ASCII character and was recorded in a non-UTF8 locale.
569
570       darcs annotate [file|directory]
571           When  `darcs  annotate` is called on a file, it will find the patch
572           that last modified each line in that file. This also works  on  di‐
573           rectories.
574
575           The  `--machine-readable` option can be used to generate output for
576           machine postprocessing.
577
578
579       darcs diff [file|directory]...
580           The `darcs diff` command compares two versions of the working  tree
581           of   the   current   repository.   Without  options,  the  pristine
582           (recorded) and unrecorded working  trees  are  compared.   This  is
583           lower-level  than  the `darcs whatsnew` command, since it outputs a
584           line-by-line diff, and it is also slower.   As  with  `darcs  what‐
585           snew`,  if you specify files or directories, changes to other files
586           are not listed.  The command always uses an external diff utility.
587
588           With the `--patch` option, the  comparison  will  be  made  between
589           working trees with and without that patch.  Patches *after* the se‐
590           lected patch are not present in  either  of  the  compared  working
591           trees.   The  `--from-patch` and `--to-patch` options allow the set
592           of patches in the `old' and `new' working  trees  to  be  specified
593           separately.
594
595           The  associated  tag  and  match  options are also understood, e.g.
596           `darcs diff --from-tag 1.0 --to-tag 1.1`.  All these options assume
597           an  ordering of the patch set, so results may be affected by opera‐
598           tions such as `darcs optimize reorder`.
599
600           diff(1) is always called with the arguments `-rN`  and  by  default
601           also  with `-u` to show the differences in unified format. This can
602           be turned off by passing `--no-unified`. An additional argument can
603           be   passed  using  `--diff-opts`,  such  as  `--diff-opts=-ud`  or
604           `--diff-opts=-wU9`.
605
606           The `--diff-command` option can be used to specify  an  alternative
607           utility.  Arguments  may be included, separated by whitespace.  The
608           value is not interpreted by a shell, so shell constructs cannot  be
609           used.   The arguments %1 and %2 MUST be included, these are substi‐
610           tuted for the two working trees being compared. For instance:
611
612               darcs diff -p . --diff-command "meld %1 %2"
613
614           If this option is used, `--diff-opts` is ignored.
615
616
617       darcs show subcommand
618           Display various information about a repository. See description  of
619           the subcommands for details.
620
621       darcs show contents [file]...
622           Show  contents  can  be  used to display an earlier version of some
623           file(s).  If you give show contents no version arguments,  it  dis‐
624           plays the recorded version of the file(s).
625
626
627       darcs show dependencies
628           This  command  creates a graph of the dependencies between patches.
629           The    output    format    is     the     Dot     Language,     see
630           https://www.graphviz.org/doc/info/lang.html. The resulting graph is
631           transitively reduced, in other words, it contains only  the  direct
632           dependencies, not the indirect ones.
633
634           By  default  all patches in your repository are considered. You can
635           limit this to a range of patches using patch matching options,  see
636           `darcs  help  patterns`  and the options avaiable for this command.
637           For instance, to visualize the  dependencies  between  all  patches
638           since the last tag, do:
639
640               darcs show dependencies --from-tag=. | dot -Tpdf -o FILE.pdf
641
642           This  command  can  take a very(!) long time to compute its result,
643           depending on the number of patches in the  selected  range.  For  N
644           patches  it  needs  to  do  on the order of N^3 commutations in the
645           worst case.
646
647       darcs show files [file|directory]...
648           The `darcs show files` command lists those files and directories in
649           the  working  tree that are under version control.  This command is
650           primarily for scripting purposes;  end  users  will  probably  want
651           `darcs whatsnew --summary`.
652
653           A  file is "pending" if it has been added but not recorded.  By de‐
654           fault, pending files (and directories) are listed; the  `--no-pend‐
655           ing` option prevents this.
656
657           By default `darcs show files` lists both files and directories, but
658           the `--no-files` and `--no-directories` flags  modify  this  behav‐
659           iour.
660
661           By default entries are one-per-line (i.e. newline separated).  This
662           can cause problems if the  files  themselves  contain  newlines  or
663           other  control characters.  To get around this, the `--null` option
664           uses the null character instead.  The  script  interpreting  output
665           from  this  command  needs  to understand this idiom; `xargs -0` is
666           such a command.
667
668           For example, to list version-controlled files by size:
669
670               darcs show files -0 | xargs -0 ls -ldS
671
672
673       darcs show index
674           The `darcs show index` command lists all  version-controlled  files
675           and  directories  along  with their hashes as stored in `_darcs/in‐
676           dex`. For files, the fields correspond to file size, sha256 of  the
677           current file content and the filename.
678
679       darcs show pristine
680           The  `darcs  show  pristine`  command  lists all version-controlled
681           files and directories along  with  the  hashes  of  their  pristine
682           copies.  For  files,  the fields correspond to file size, sha256 of
683           the pristine file content and the filename.
684
685       darcs show repo
686           The `darcs show repo` command displays statistics about the current
687           repository, allowing third-party scripts to access this information
688           without inspecting `_darcs` directly (and without breaking when the
689           `_darcs` format changes).
690
691           The 'Weak Hash' identifies the set of patches of a repository inde‐
692           pendently of ordering. It can be used to easily compare two reposi‐
693           tories of a same project. It is not cryptographically secure.
694
695           By default, output includes statistics that require walking through
696           the patches recorded in the repository, namely the 'Weak Hash'  and
697           the  count  of patches.  If this data isn't needed, use `--no-enum-
698           patches` to accelerate this command from O(n) to O(1).
699
700           By default, output is in a human-readable format.  The  `--xml-out‐
701           put` option can be used to generate output for machine postprocess‐
702           ing.
703
704
705       darcs show authors
706           The `darcs show authors` command lists the authors of  the  current
707           repository,  sorted by the number of patches contributed.  With the
708           `--verbose` option, this command simply lists the  author  of  each
709           patch (without aggregation or sorting).
710
711           An  author's  name  or email address may change over time.  To tell
712           Darcs when multiple author strings refer to  the  same  individual,
713           create  an `.authorspellings` file in the root of the working tree.
714           Each line in this file begins with an author's canonical  name  and
715           address,  and may be followed by a comma separated list of extended
716           regular expressions.  Blank lines and lines beginning with two  hy‐
717           phens  are  ignored.   The  format  of `.authorspelling` can be de‐
718           scribed by this pattern:
719
720               name <address> [, regexp ]*
721
722           There are some pitfalls concerning special characters:  Whitespaces
723           are  stripped,  if you need space in regexp use [ ].  Because comma
724           serves as a separator you have to escape it if you want it in  reg‐
725           exp.  Note  that `.authorspelling` use extended regular expressions
726           so +, ? and so on are metacharacters and you need to escape them to
727           be interpreted literally.
728
729           Any  patch with an author string that matches the canonical address
730           or any of the associated regexps is considered to be  the  work  of
731           that  author.  All matching is case-insensitive and partial (it can
732           match a substring). Use ^,$ to match the whole string in regexps
733
734           Currently this canonicalization step is done only  in  `darcs  show
735           authors`.   Other  commands, such as `darcs log` use author strings
736           verbatim.
737
738           An example `.authorspelling` file is:
739
740               -- This is a comment.
741               Fred Nurk <fred@example.com>
742               John Snagge <snagge@bbc.co.uk>, John, snagge@, js@(si|mit).edu
743               Chuck Jones Jr. <chuck@pobox.com>, cj+user@example.com
744
745
746       darcs show tags
747           The tags command writes a list of all tags  in  the  repository  to
748           standard output.
749
750           Tab characters (ASCII character 9) in tag names are changed to spa‐
751           ces for better interoperability with  shell  tools.  A  warning  is
752           printed if this happens.
753
754       darcs show patch-index
755           When  given  the  `--verbose`  flag, the command dumps the complete
756           content of the patch index and checks its integrity.
757
758       darcs test [[initialization] command]
759           Run test on the current recorded state of the repository.  Given no
760           arguments,  it  uses  the  default repository test (see `darcs set‐
761           pref`).  Given one argument, it treats it as a test command.  Given
762           two  arguments, the first is an initialization command and the sec‐
763           ond is the test (meaning the exit code of the first command is  not
764           taken into account to determine success of the test).  If given the
765           `--linear` or `--bisect` flags, it tries to find  the  most  recent
766           version in the repository which passes a test.
767
768           `--linear`  does  linear search starting from head, and moving away
769           from head. This strategy is best when the test runs very quickly or
770           the patch you're seeking is near the head.
771
772           `--bisect` does binary search.  This strategy is best when the test
773           runs very slowly or the patch you're seeking is likely to be in the
774           repository's distant past.
775
776           `--backoff`  starts  searching from head, skipping further and fur‐
777           ther into the past until the test succeeds.  It then does a  binary
778           search  on  a subset of those skipped patches.  This strategy works
779           well unless the patch you're seeking is in the repository's distant
780           past.
781
782           Under  the  assumption  that  failure is monotonous, `--linear` and
783           `--bisect` produce the same result.  (Monotonous  means  that  when
784           moving  away  from  head,  the  test  result changes only once from
785           "fail" to "ok".)  If failure is not  monotonous,  any  one  of  the
786           patches that break the test is found at random.
787
788
789
790   Undoing and correcting:
791       darcs revert [file|directory]...
792           The  `darcs revert` command discards unrecorded changes the working
793           tree.  As with `darcs  record`,  you  will  be  asked  which  hunks
794           (changes)  to revert.  The `--all` switch can be used to avoid such
795           prompting. If files or directories are specified,  other  parts  of
796           the working tree are not reverted.
797
798           In  you accidentally reverted something you wanted to keep (for ex‐
799           ample, typing `darcs rev -a` instead of `darcs rec  -a`),  you  can
800           immediately run `darcs unrevert` to restore it.  This is only guar‐
801           anteed to work if the repository has not changed since  `darcs  re‐
802           vert` ran.
803
804
805       darcs unrevert
806           Unrevert  is  a  rescue  command  in case you accidentally reverted
807           something you wanted to keep (for example, typing  `darcs  rev  -a`
808           instead of `darcs rec -a`).
809
810           This  command  may fail if the repository has changed since the re‐
811           vert took place.  Darcs will ask for confirmation before  executing
812           an interactive command that will DEFINITELY prevent unreversion.
813
814
815       darcs amend [file|directory]...
816           Amend  updates  a "draft" patch with additions or improvements, re‐
817           sulting in a single "finished" patch.
818
819           By default `amend` proposes you to record  additional  changes.  If
820           instead you want to remove changes, use the flag `--unrecord`.
821
822           When  recording  a draft patch, it is a good idea to start the name
823           with `DRAFT:`.  When done, remove it with `darcs amend --edit-long-
824           comment`.  Alternatively, to change the patch name without starting
825           an editor, use the `--name`/`-m` flag:
826
827               darcs amend --match 'name "DRAFT: foo"' --name 'foo2'
828
829           Like `darcs record`, if you call amend with files as arguments, you
830           will  only  be  asked  about  changes to those files. So to amend a
831           patch to foo.c with improvements in bar.c, you would run:
832
833               darcs amend --match 'touch foo.c' bar.c
834
835           Note that this command edits the history of your repo. It  is  pri‐
836           marily  intended  to  be used on patches that you authored yourself
837           and did not yet publish. Using it for patches that are already pub‐
838           lished,  or even ones you did not author yourself, may cause confu‐
839           sion and can disrupt your own and other  people's  work-flow.  This
840           depends  a  lot  on how your project is organized, though, so there
841           may be valid exceptions to this rule.
842
843           Using the `--not-in-remote` option is a good way to  guard  against
844           accidentally editing published patches. Without arguments, this de‐
845           selects any patches that are also present in the `defaultrepo`.  If
846           you work in a clone of some publically hosted repository, then your
847           `defaultrepo` will be that public repo. You can also give  the  op‐
848           tion  an  argument which is a path or URL of some other repository;
849           you can use the option multiple times with different  repositories,
850           which  has  the  effect of treating all of them as "upstream", that
851           is, it prevents you from selecting a patch that is contained in any
852           of these repos.
853
854           You  can  also guard only against editing another developer's patch
855           by using an appropriate `--match` option with the `author` keyword.
856           For  instance, you could add something like `<cmd> match Your Name`
857           to your `~/.darcs/defaults`.
858
859       darcs rebase subcommand
860           The `darcs rebase' command is used to edit a  collection  of  darcs
861           patches.
862
863           The  basic  idea  is that you can suspend patches from the end of a
864           repository.  These patches are no longer part of  the  history  and
865           have no effect on the working tree. Suspended patches are invisible
866           to commands that access the repository from the  outside,  such  as
867           push, pull, clone, send, etc.
868
869           The  sequence  of suspended patches can be manipulated in ways that
870           are not allowed for normal patches.  For  instance,  `darcs  rebase
871           obliterate`  allows you to remove a patch in this sequence, even if
872           other suspended patches depend on it. These other patches will as a
873           result become conflicted.
874
875           You can also operate on the normal patches in the usual way. If you
876           add or remove normal patches, the suspended patches will  be  auto‐
877           matically  adapted  to  still apply to the pristine state, possibly
878           becoming conflicted in the course.
879
880           Note that as soon as a patch gets suspended,  it  will  irrevocably
881           loose  its  identity. This means that suspending a patch is subject
882           to the usual warnings about editing the history of your project.
883
884           The opposite of suspending a patch is to unsuspend it.  This  turns
885           it back into a normal patch. If the patch is conflicted as a result
886           of previous operations on either the normal  patches  or  the  sus‐
887           pended  patches,  unsuspending  will  create  appropriate  conflict
888           markup. Note, however, that the unsuspended patch itself  WILL  NOT
889           BE  CONFLICTED itself. This means that there is no way to re-gener‐
890           ate the conflict markup. Once you removed it, by editing  files  or
891           using `darcs revert`, any information about the conflict is lost.
892
893           As  long  as you have suspended patches, darcs will display a short
894           message after each command to remind you that  your  patch  editing
895           operation is still in progress.
896
897       darcs rebase pull [repository]...
898           Copy  and apply patches from another repository, suspending any lo‐
899           cal patches that conflict.
900
901       darcs rebase apply <patchfile>
902           Apply a patch bundle, suspending any local patches that conflict.
903
904       darcs rebase suspend
905           Select patches to move into a suspended state at  the  end  of  the
906           repo.
907
908           Note  that  this command edits the history of your repo. It is pri‐
909           marily intended to be used on patches that  you  authored  yourself
910           and did not yet publish. Using it for patches that are already pub‐
911           lished, or even ones you did not author yourself, may cause  confu‐
912           sion  and  can  disrupt your own and other people's work-flow. This
913           depends a lot on how your project is organized,  though,  so  there
914           may be valid exceptions to this rule.
915
916           Using  the  `--not-in-remote` option is a good way to guard against
917           accidentally editing published patches. Without arguments, this de‐
918           selects  any patches that are also present in the `defaultrepo`. If
919           you work in a clone of some publically hosted repository, then your
920           `defaultrepo`  will  be that public repo. You can also give the op‐
921           tion an argument which is a path or URL of some  other  repository;
922           you  can use the option multiple times with different repositories,
923           which has the effect of treating all of them  as  "upstream",  that
924           is, it prevents you from selecting a patch that is contained in any
925           of these repos.
926
927           You can also guard only against editing another  developer's  patch
928           by using an appropriate `--match` option with the `author` keyword.
929           For instance, you could add something like `<cmd> match Your  Name`
930           to your `~/.darcs/defaults`.
931
932       darcs rebase unsuspend
933           Select suspended patches to restore to the end of the repo.
934
935       darcs rebase obliterate
936           Obliterate a patch that is currently suspended.
937
938       darcs rebase log
939           List the currently suspended changes.
940
941       darcs rebase upgrade
942           Upgrade a repo with an old-style rebase in progress.
943
944           Doing this means you won't be able to use darcs version < 2.15 with
945           this repository until the rebase is finished.
946
947       darcs rollback [file|directory]...
948           Rollback is used to undo the effects of some changes  from  patches
949           in  the repository. The selected changes are undone in your working
950           tree, but the repository is left unchanged. First you are offered a
951           choice  of  which  patches  to  undo, then which changes within the
952           patches to undo.
953
954           Before doing `rollback`, you  may  want  to  temporarily  undo  the
955           changes of your working tree (if there are) and save them for later
956           use.  To do so, you can run `revert`, then run `rollback`, record a
957           patch,  and  run  `unrevert` to restore the saved changes into your
958           working tree.
959
960
961       darcs unrecord
962           Unrecord does the opposite of record: it deletes patches  from  the
963           repository  without  changing the working tree. The changes are now
964           again visible with `darcs whatsnew` and you can  record  or  revert
965           them as you please.
966
967           Note  that  this command edits the history of your repo. It is pri‐
968           marily intended to be used on patches that  you  authored  yourself
969           and did not yet publish. Using it for patches that are already pub‐
970           lished, or even ones you did not author yourself, may cause  confu‐
971           sion  and  can  disrupt your own and other people's work-flow. This
972           depends a lot on how your project is organized,  though,  so  there
973           may be valid exceptions to this rule.
974
975           Using  the  `--not-in-remote` option is a good way to guard against
976           accidentally editing published patches. Without arguments, this de‐
977           selects  any patches that are also present in the `defaultrepo`. If
978           you work in a clone of some publically hosted repository, then your
979           `defaultrepo`  will  be that public repo. You can also give the op‐
980           tion an argument which is a path or URL of some  other  repository;
981           you  can use the option multiple times with different repositories,
982           which has the effect of treating all of them  as  "upstream",  that
983           is, it prevents you from selecting a patch that is contained in any
984           of these repos.
985
986           You can also guard only against editing another  developer's  patch
987           by using an appropriate `--match` option with the `author` keyword.
988           For instance, you could add something like `<cmd> match Your  Name`
989           to your `~/.darcs/defaults`.
990
991       darcs obliterate
992           Obliterate  completely  removes  recorded  patches  from your local
993           repository. The changes will be undone in your working tree and the
994           patches will not be shown in your changes list anymore. Beware that
995           you can lose precious code by obliterating!
996
997           One way to save obliterated patches is to use the -O flag. A  patch
998           bundle  will  be  created  locally,  that you will be able to apply
999           later to your repository with `darcs apply`. See `darcs send` for a
1000           more detailed description.
1001
1002           Note  that  this command edits the history of your repo. It is pri‐
1003           marily intended to be used on patches that  you  authored  yourself
1004           and did not yet publish. Using it for patches that are already pub‐
1005           lished, or even ones you did not author yourself, may cause  confu‐
1006           sion  and  can  disrupt your own and other people's work-flow. This
1007           depends a lot on how your project is organized,  though,  so  there
1008           may be valid exceptions to this rule.
1009
1010           Using  the  `--not-in-remote` option is a good way to guard against
1011           accidentally editing published patches. Without arguments, this de‐
1012           selects  any patches that are also present in the `defaultrepo`. If
1013           you work in a clone of some publically hosted repository, then your
1014           `defaultrepo`  will  be that public repo. You can also give the op‐
1015           tion an argument which is a path or URL of some  other  repository;
1016           you  can use the option multiple times with different repositories,
1017           which has the effect of treating all of them  as  "upstream",  that
1018           is, it prevents you from selecting a patch that is contained in any
1019           of these repos.
1020
1021           You can also guard only against editing another  developer's  patch
1022           by using an appropriate `--match` option with the `author` keyword.
1023           For instance, you could add something like `<cmd> match Your  Name`
1024           to your `~/.darcs/defaults`.
1025
1026
1027   Direct modification of the repository:
1028       darcs tag [tagname]
1029           The `darcs tag` command names the current repository state, so that
1030           it can easily be referred to later.  Every *important* state should
1031           be tagged; in particular it is good practice to tag each stable re‐
1032           lease with a number or codename.  Advice on release  numbering  can
1033           be found at <http://producingoss.com/en/development-cycle.html>.
1034
1035           To  reproduce  the state of a repository `R` as at tag `t`, use the
1036           command `darcs clone --tag t R`.  The  command  `darcs  show  tags`
1037           lists all tags in the current repository.
1038
1039           Tagging  also provides significant performance benefits: when Darcs
1040           reaches a shared tag that depends on all antecedent patches, it can
1041           simply stop processing.
1042
1043           Like  normal  patches, a tag has a name, an author, a timestamp and
1044           an optional long description, but it does not  change  the  working
1045           tree.   A tag can have any name, but it is generally best to pick a
1046           naming scheme and stick to it.
1047
1048           By default a tag names the entire repository state at the time  the
1049           tag  is  created.  If the --ask-deps option is used, the patches to
1050           include as part of the tag can be explicitly selected.
1051
1052           The `darcs tag` command accepts the `--pipe` option, which  behaves
1053           as described in `darcs record`.
1054
1055
1056       darcs setpref <pref> <value>
1057           When  working  on  project with multiple repositories and contribu‐
1058           tors, it is sometimes desirable for a preference to be set  consis‐
1059           tently project-wide.  This is achieved by treating a preference set
1060           with `darcs setpref` as an unrecorded change,  which  can  then  be
1061           recorded and then treated like any other patch.
1062
1063           Valid preferences are:
1064
1065           * test -- a shell command that runs regression tests * predist -- a
1066           shell command to run before `darcs dist' * boringfile --  the  path
1067           to a version-controlled boring file * binariesfile -- the path to a
1068           version-controlled binaries file
1069
1070           For example, a project using GNU autotools, with a `make test` tar‐
1071           get to perform regression tests, might enable Darcs' integrated re‐
1072           gression testing with the following command:
1073
1074               darcs setpref test 'autoconf && ./configure  &&  make  &&  make
1075           test'
1076
1077           Note  that merging is not currently implemented for preferences: if
1078           two patches attempt to set the same preference, the last patch  ap‐
1079           plied  to the repository will always take precedence.  This is con‐
1080           sidered a low-priority bug, because preferences are seldom set.
1081
1082
1083
1084   Exchanging patches by e-mail:
1085       darcs send [repository]
1086           Send is used to prepare a bundle of patches that can be applied  to
1087           a  target  repository. Send accepts the URL of the repository as an
1088           argument. When called without an argument, send will use  the  most
1089           recent  repository  that  was either pushed to, pulled from or sent
1090           to. By default, the patch bundle is saved to a file,  although  you
1091           may directly send it by mail.
1092
1093           The  `--output`,  `--output-auto-name`,  and `--to` flags determine
1094           what darcs does with the patch bundle after  creating  it.  If  you
1095           provide  an  `--output` argument, the patch bundle is saved to that
1096           file. If you specify  `--output-auto-name`,  the  patch  bundle  is
1097           saved  to  a file with an automatically generated name. If you give
1098           one or more `--to` arguments, the bundle  of  patches  is  sent  to
1099           those  locations.   The  locations may either be email addresses or
1100           urls that the patch should be submitted to via HTTP.
1101
1102           If you provide the `--mail` flag, darcs will look at  the  contents
1103           of  the  `_darcs/prefs/email`  file in the target repository (if it
1104           exists), and send the patch by email to that address. In this case,
1105           you  may  use  the  `--cc`  option to specify additional recipients
1106           without overriding the default repository email address.
1107
1108           If `_darcs/prefs/post` exists in the target repository, darcs  will
1109           upload  to  the  URL  contained in that file, which may either be a
1110           `mailto:` URL, or an `http://` URL. In the latter case,  the  patch
1111           is posted to that URL.
1112
1113           If  there is no email address associated with the repository, darcs
1114           will prompt you for an email address.
1115
1116           Use the `--subject` flag to set the subject of  the  e-mail  to  be
1117           sent.  If  you  don't  provide a subject on the command line, darcs
1118           will make one up based on names of the patches in the patch bundle.
1119
1120           Use the `--in-reply-to` flag to set the In-Reply-To and  References
1121           headers  of the e-mail to be sent. By default no additional headers
1122           are included so e-mail will not be treated as reply by  mail  read‐
1123           ers.
1124
1125           If  you want to include a description or explanation along with the
1126           bundle of patches, you need  to  specify  the  `--edit-description`
1127           flag,  which  will  cause darcs to open up an editor with which you
1128           can compose a message to go along with your patches.
1129
1130           If you want to use a command different from  the  default  one  for
1131           sending email, you need to specify a command line with the `--send‐
1132           mail-command` option. The command  line  can  contain  some  format
1133           specifiers which are replaced by the actual values. Accepted format
1134           specifiers are `%s` for subject, `%t` for to, `%c` for cc, `%b` for
1135           the  body of the mail, `%f` for from, `%a` for the patch bundle and
1136           the same specifiers in uppercase for the URL-encoded values.  Addi‐
1137           tionally  you  can  add  `%<` to the end of the command line if the
1138           command expects the complete email message on standard input.  E.g.
1139           the command lines for evolution and msmtp look like this:
1140
1141               evolution "mailto:%T?subject=%S&attach=%A&cc=%C&body=%B"
1142               msmtp -t %<
1143
1144           Do  not confuse the `--author` options with the return address that
1145           `darcs send` will set for your patch bundle.
1146
1147           For example, if you have two email addresses A and B:
1148
1149             * If you use `--author A` but your machine is configured to send
1150               mail from address B by default, then the return address on your
1151               message will be B.
1152             * If you use `--from A` and your mail client supports setting the
1153               From: address arbitrarily (some non-Unix-like mail clients,
1154               especially, may not support this), then the return address will
1155               be A; if it does not support this, then the return address will
1156               be B.
1157             * If you supply neither `--from` nor `--author` then the return
1158               address will be B.
1159
1160           In addition, unless you specify the sendmail command with  `--send‐
1161           mail-command`, darcs sends email using the default email command on
1162           your computer. This default command is determined by  the  `config‐
1163           ure`  script.  Thus, on some non-Unix-like OSes, `--from` is likely
1164           to not work at all.
1165
1166           The --inherit-default option is meant to support a work flow  where
1167           you  have  different  branches  of the same upstream repository and
1168           want all your branches to have the same upstream repo  as  the  de‐
1169           faultrepo.  It  is most useful when enabled globally by adding 'ALL
1170           --inherit-default' to your ~/darcs/defaults file.
1171
1172           For the commands push, pull,  and  send  it  means  the  following:
1173           Changes the meaning of the --set-default option so that it sets the
1174           (local) defaultrepo to the defaultrepo of the remote repo,  instead
1175           of  the  remote  repo  itself. This happens only if the remote repo
1176           does have a defaultrepo set and both local and remote  repositories
1177           are  locally  valid  paths on the same host, otherwise fall back to
1178           the default behavior (--no-inherit-default).
1179
1180       darcs apply <patchfile>
1181           The `darcs apply` command takes a patch bundle and attempts to  in‐
1182           sert it into the current repository. In addition to invoking it di‐
1183           rectly on bundles created by `darcs send`, it is used internally by
1184           `darcs push` on the remote end of an SSH connection.
1185
1186           If no file is supplied, the bundle is read from standard input.
1187
1188           If  given  an  email instead of a patch bundle, Darcs will look for
1189           the bundle as a MIME attachment to that email. Currently this  will
1190           fail  if  the  MIME  boundary  is rewritten, such as in Courier and
1191           Mail.app.
1192
1193           If gpg(1) is installed, you can use `--verify pubring.gpg`  to  re‐
1194           ject bundles that aren't signed by a key in `pubring.gpg`.
1195
1196           If  `--test`  is  supplied  and  a test is defined (see `darcs set‐
1197           pref`), the bundle will be rejected if the test fails after  apply‐
1198           ing it.
1199
1200           A  patch  bundle  may  introduce unresolved conflicts with existing
1201           patches or with the working tree. By default, Darcs will  add  con‐
1202           flict markers (see `darcs mark-conflicts`).
1203
1204           The  `--external-merge` option lets you resolve these conflicts us‐
1205           ing an external merge tool. In the option, `%a`  is  replaced  with
1206           the common ancestor (merge base), `%1` with the first version, `%2`
1207           with the second version, and `%o` with the path where your resolved
1208           content should go. For example, to use the xxdiff visual merge tool
1209           you'd specify: `--external-merge='xxdiff -m -O -M %o %1 %a %2'`
1210
1211           The `--allow-conflicts` option will skip conflict marking; this  is
1212           useful  when  you  want  to  treat  a repository as just a bunch of
1213           patches, such as using `darcs pull --union` to download of your co-
1214           workers patches before going offline.
1215
1216           This  can  mess  up unrecorded changes in the working tree, forcing
1217           you to resolve the conflict immediately. To simply  reject  bundles
1218           that  introduce  unresolved conflicts, using the `--dont-allow-con‐
1219           flicts` option. Making this the default in push-based workflows  is
1220           strongly recommended.
1221
1222           Unlike  most Darcs commands, `darcs apply` defaults to `--all`. Use
1223           the `--interactive` option to pick which patches to  apply  from  a
1224           bundle.
1225
1226
1227   Other commands:
1228       darcs optimize subcommand
1229           The  `darcs  optimize` command modifies internal data structures of
1230           the current repository in an attempt to  reduce  its  resource  re‐
1231           quirements.
1232
1233           For further details see the descriptions of the subcommands.
1234
1235       darcs optimize clean
1236           Darcs normally does not delete hashed files that are no longer ref‐
1237           erenced by the current repository state. This command can be use to
1238           get rid of these files to save some disk space.
1239
1240       darcs optimize http
1241           Using  this option creates 'repository packs' that can dramatically
1242           speed up performance when a user does a `darcs clone` of the repos‐
1243           itory  over  HTTP.  To  make  use of packs, the clients must have a
1244           darcs of at least version 2.10.
1245
1246       darcs optimize reorder
1247           This command moves recent patches (those not included in the latest
1248           tag) to the "front", reducing the amount that a typical remote com‐
1249           mand needs to download. It should also reduce the CPU  time  needed
1250           for some operations.
1251
1252       darcs optimize enable-patch-index
1253           Build  the patch index, an internal data structure that accelerates
1254           commands that need to know what patches touch a given file. Such as
1255           annotate and log.
1256
1257       darcs optimize disable-patch-index
1258           Delete and stop maintaining the patch index from the repository.
1259
1260       darcs optimize compress
1261           By  default  patches  are compressed with zlib (RFC 1951) to reduce
1262           storage (and download) size. In exceptional circumstances,  it  may
1263           be  preferable  to avoid compression. In this case the `--dont-com‐
1264           press` option can be used (e.g. with `darcs record`) to avoid  com‐
1265           pression.
1266
1267           The  `darcs optimize uncompress` and `darcs optimize compress` com‐
1268           mands can be used to ensure existing patches in the current reposi‐
1269           tory are respectively uncompressed or compressed.
1270
1271       darcs optimize uncompress
1272           By  default  patches  are compressed with zlib (RFC 1951) to reduce
1273           storage (and download) size. In exceptional circumstances,  it  may
1274           be  preferable  to avoid compression. In this case the `--dont-com‐
1275           press` option can be used (e.g. with `darcs record`) to avoid  com‐
1276           pression.
1277
1278           The  `darcs optimize uncompress` and `darcs optimize compress` com‐
1279           mands can be used to ensure existing patches in the current reposi‐
1280           tory are respectively uncompressed or compressed.
1281
1282       darcs optimize relink
1283           The  `darcs  optimize  relink`  command hard-links patches that the
1284           current repository has in common with its peers.  Peers  are  those
1285           repositories  listed in `_darcs/prefs/sources`, or defined with the
1286           `--sibling` option (which can be used multiple times).
1287
1288           Darcs uses hard-links automatically,  so  this  command  is  rarely
1289           needed.  It  is  most  useful if you used `cp -r` instead of `darcs
1290           clone` to copy a repository, or if you pulled the same patch from a
1291           remote repository into multiple local repositories.
1292
1293       darcs optimize pristine
1294           This  command updates the format of `_darcs/pristine.hashed`, which
1295           was different before darcs 2.3.1.
1296
1297       darcs optimize upgrade
1298           Convert old-fashioned repositories to the  current  default  hashed
1299           format.
1300
1301       darcs optimize cache <directory> ...
1302           This  command  deletes  obsolete  files within the global cache. It
1303           takes  one  or  more  directories  as  arguments,  and  recursively
1304           searches all repositories within these directories. Then it deletes
1305           all files in the global cache not belonging to these  repositories.
1306           When  no directory is given, it searches repositories in the user's
1307           home directory.
1308
1309           It also automatically migrates the global cache  to  the  (default)
1310           bucketed format.
1311
1312       darcs dist
1313           `darcs  dist` creates a compressed archive in the repository's root
1314           directory, containing the recorded state of the working  tree  (un‐
1315           recorded  changes  and  the  `_darcs` directory are excluded).  The
1316           command accepts matchers to create an archive of some past  reposi‐
1317           tory state, for instance `--tag`.
1318
1319           By default, the archive (and the top-level directory within the ar‐
1320           chive) has the same name as the repository, but this can  be  over‐
1321           ridden with the `--dist-name` option.
1322
1323           If  a  predist  command  is set (see `darcs setpref`), that command
1324           will be run on the recorded state prior to archiving.  For example,
1325           autotools projects would set it to `autoconf && automake`.
1326
1327           If `--zip` is used, matchers and the predist command are ignored.
1328
1329
1330       darcs mark-conflicts [file|directory]...
1331           Darcs  requires human guidance to unify changes to the same part of
1332           a source file.  When a conflict first occurs, darcs  will  add  the
1333           initial  state  and  both choices to the working tree, delimited by
1334           the markers `v v v`, `=====`,  `* * *` and `^ ^ ^`, as follows:
1335
1336               v v v v v v v
1337               Initial state.
1338               =============
1339               First choice.
1340               *************
1341               Second choice.
1342               ^ ^ ^ ^ ^ ^ ^
1343
1344           However, you might revert or manually delete these markers  without
1345           actually  resolving  the  conflict.  In this case, `darcs mark-con‐
1346           flicts` is useful to show where are the unresolved  conflicts.   It
1347           is  also  useful  if  `darcs  apply` or `darcs pull` is called with
1348           `--allow-conflicts`, where conflicts aren't marked initially.
1349
1350           Unless you use the `--dry-run` flag, any unrecorded changes to  the
1351           affected files WILL be lost forever when you run this command!  You
1352           will be prompted for confirmation before this takes place.
1353
1354
1355       darcs repair
1356           The `darcs repair` command attempts to fix corruption in  the  cur‐
1357           rent  repository.  It works by successively applying all patches in
1358           the repository to an empty tree, each time checking that the  patch
1359           can be cleanly applied to the current pristine tree. If we detect a
1360           problem, we try to repair the patch. Finally we compare the  exist‐
1361           ing  pristine  with the newly reconstructed one and if they differ,
1362           replace the existing one.  Any  problem  encountered  is  reported.
1363           The  flag  `--dry-run` makes this operation read-only and causes it
1364           to exit unsuccessfully (with a non-zero exit status)  in  case  any
1365           problems are enountered.
1366
1367
1368       darcs convert subcommand
1369           Convert repositories between various formats.
1370
1371           See description of the subcommands for details.
1372
1373       darcs convert darcs-2 <source> [<destination>]
1374           This  command  converts a repository that uses the old patch seman‐
1375           tics `darcs-1` to a new repository with  current  `darcs-2`  seman‐
1376           tics.
1377
1378           WARNING:  the repository produced by this command is not understood
1379           by Darcs 1.x, and patches cannot be exchanged between  repositories
1380           in darcs-1 and darcs-2 formats.
1381
1382           Furthermore,  repositories created by different invocations of this
1383           command SHOULD NOT exchange patches.
1384
1385
1386
1387       darcs convert export
1388           This command enables you to export darcs repositories into git.
1389
1390           For a one-time export you can use the recipe:
1391
1392               $ cd repo
1393               $ git init ../mirror
1394               $ darcs convert export | (cd ../mirror && git fast-import)
1395
1396           For incremental export using marksfiles:
1397
1398               $ cd repo
1399               $ git init ../mirror
1400               $ touch ../mirror/git.marks
1401               $ darcs convert export --read-marks  darcs.marks  --write-marks
1402           darcs.marks
1403                  |  (cd ../mirror && git fast-import --import-marks=git.marks
1404           --export-marks=git.marks)
1405
1406           In the case of incremental  export,  be  careful  to  never  amend,
1407           delete or reorder patches in the source darcs repository.
1408
1409           Also,  be  aware that exporting a darcs repo to git will not be ex‐
1410           actly faithful in terms of history if the darcs repository contains
1411           conflicts.
1412
1413           Limitations:
1414
1415             *  Empty  directories are not supported by the fast-export proto‐
1416           col.
1417             * Unicode filenames are currently not correctly handled.
1418               See http://bugs.darcs.net/issue2359 .
1419
1420
1421       darcs convert import [<directory>]
1422           This command imports git repositories into new darcs  repositories.
1423           Further options are accepted (see `darcs help init`).
1424
1425           To convert a git repo to a new darcs one you may run:
1426
1427               $  (cd gitrepo && git fast-export --all -M) | darcs convert im‐
1428           port darcsmirror
1429
1430           WARNING: git repositories with branches will produce weird results,
1431                    use at your own risks.
1432
1433           Incremental import with marksfiles is currently not supported.
1434
1435
1436       darcs fetch [repository]...
1437           Fetch is similar to `pull`  except  that  it  does  not  apply  any
1438           patches  to  the  current repository. Instead, it generates a patch
1439           bundle that you can apply later with `apply`.
1440
1441           Fetch's behaviour is essentially similar to pull's, so please  con‐
1442           sult the help of `pull` to know more.
1443

ENVIRONMENT

1445   HOME and APPDATA
1446       Per-user  preferences  are  set  in  $HOME/.darcs  (on  Unix)  or %APP‐
1447       DATA%/darcs (on Windows).  This is also the  default  location  of  the
1448       cache.
1449
1450   DARCS_EDITOR, VISUAL, and EDITOR
1451       To  edit a patch description of email comment, Darcs will invoke an ex‐
1452       ternal editor.  Your preferred editor can be set as any of the environ‐
1453       ment variables $DARCS_EDITOR, $VISUAL or $EDITOR.  If none of these are
1454       set, nano is used.  If nano crashes or is not found in your  PATH,  vi,
1455       emacs, emacs -nw and (on Windows) edit are each tried in turn.
1456
1457   DARCS_PAGER and PAGER
1458       Darcs  will invoke a pager if the output of some command is longer than
1459       20 lines. Darcs will use the pager specified by $DARCS_PAGER or $PAGER.
1460       If neither are set, `less` will be used.
1461
1462   DARCS_DONT_COLOR, DARCS_ALWAYS_COLOR, and DARCS_ALTERNATIVE_COLOR
1463       If  the  terminal  understands  ANSI color escape sequences, darcs will
1464       highlight certain keywords and delimiters when  printing  patches,  and
1465       also print hunk lines in color according to whether they are removed or
1466       added. This can be turned  off  by  setting  the  environment  variable
1467       DARCS_DONT_COLOR  to  1.  If you use a pager that happens to understand
1468       ANSI colors, like `less -R`, darcs can be forced  always  to  highlight
1469       the  output by setting DARCS_ALWAYS_COLOR to 1. If you can't see colors
1470       you can set DARCS_ALTERNATIVE_COLOR to 1, and darcs will use ANSI codes
1471       for bold and reverse video instead of colors.
1472
1473   DARCS_DONT_ESCAPE_TRAILING_SPACES and DARCS_DONT_ESCAPE_TRAILING_CR
1474       By  default darcs will escape (by highlighting if possible) any kind of
1475       spaces at the end of lines when showing patch contents.  If  you  don't
1476       want  this  you  can  turn  it  off by setting DARCS_DONT_ESCAPE_TRAIL‐
1477       ING_SPACES to 1. A special  case  exists  for  only  carriage  returns:
1478       DARCS_DONT_ESCAPE_TRAILING_CR
1479
1480   DARCS_DONT_ESCAPE_ANYTHING,   DARCS_DONT_ESCAPE_EXTRA,  DARCS_ESCAPE_EXTRA,
1481       DARCS_DONT_ESCAPE_ISPRINT, and DARCS_ESCAPE_8BIT
1482       Darcs needs to escape certain characters when printing  patch  contents
1483       to  a terminal, depending on the encoding specified in your locale set‐
1484       ting.
1485
1486       By default, darcs assumes that your locale encoding is  ASCII  compati‐
1487       ble.   This  includes  UTF-8 and some 8-bit encodings like ISO/IEC-8859
1488       (including its variants). Since ASCII contains control characters  like
1489       backspace  (which  could  hide patch content from the user when printed
1490       literally to the terminal), and even ones that may  introduce  security
1491       risks  such as redirecting commands to the shell, darcs needs to escape
1492       such characters.  They are printed  as  `^<control  letter>`  or  `<hex
1493       code>`.  Darcs  also uses special markup for line endings that are pre‐
1494       ceeded by white space, since the white space  would  otherwise  not  be
1495       recognizable.
1496
1497       If  you  use an encoding that is not ASCII compatible, things are some‐
1498       what less smooth. Such encodings include UTF-16 and UTF-32, as well  as
1499       many  of  the encodings that became obsolete with unicode. In this case
1500       you have two options: you can set DARCS_DONT_ESCAPE_ANYTHING to 1. Then
1501       everything that doesn't flip code sets should work, and so will all the
1502       bells and whistles in your terminal. This environment variable can also
1503       be  handy  if  you  pipe  the output to a pager or external filter that
1504       knows better than darcs how to handle your encoding. Note that all  es‐
1505       caping,  including the special escaping of any line ending spaces, will
1506       be turned off by this setting.
1507
1508       Another possibility is to explicitly tell darcs to not escape or escape
1509       certain  bytes,  using  DARCS_DONT_ESCAPE_EXTRA and DARCS_ESCAPE_EXTRA.
1510       Their values should be strings consisting  of  the  verbatim  bytes  in
1511       question.  The  do-escapes take precedence over the dont-escapes. Space
1512       characters are still escaped at line endings though. The special  envi‐
1513       ronment  variable  DARCS_DONT_ESCAPE_TRAILING_CR  turns off escaping of
1514       carriage return last on the line (DOS style).
1515
1516       For historical reasons, darcs also  supports  DARCS_DONT_ESCAPE_ISPRINT
1517       and  DARCS_USE_ISPRINT  (which are synonyms). These make sense only for
1518       8-bit encodings like ISO-8859 and are no longer needed  since  nowadays
1519       darcs does the right thing here by default.
1520
1521       Finally,  if  you are in a highly security sensitive situation (or just
1522       paranoid for other reasons), you can set DARCS_ESCAPE_8BIT to  1.  This
1523       will  cause  darcs  to escape every non-ASCII byte in addition to ASCII
1524       control characters.
1525
1526   DARCS_TMPDIR and TMPDIR
1527       Darcs often creates temporary directories.   For  example,  the  `darcs
1528       diff`  command  creates two for the working trees to be diffed.  By de‐
1529       fault temporary directories are created in /tmp, or if that doesn't ex‐
1530       ist,  in  _darcs  (within the current repo).  This can be overridden by
1531       specifying some other directory in the file _darcs/prefs/tmpdir or  the
1532       environment variable $DARCS_TMPDIR or $TMPDIR.
1533
1534   DARCS_KEEP_TMPDIR
1535       If  the  environment  variable DARCS_KEEP_TMPDIR is defined, darcs will
1536       not remove the temporary directories it creates.  This is intended pri‐
1537       marily for debugging Darcs itself, but it can also be useful, for exam‐
1538       ple, to determine why your test preference  (see  `darcs  setpref`)  is
1539       failing when you run `darcs record`, but working when run manually.
1540
1541   DARCS_EMAIL and EMAIL
1542       Each  patch  is attributed to its author, usually by email address (for
1543       example, `Fred Bloggs <fred@example.net>`).   Darcs  looks  in  several
1544       places  for  this  author  string:  the  `--author`  option,  the files
1545       `_darcs/prefs/author` (in the  repository)  and  `~/.darcs/author`  (in
1546       your  home directory), and the environment variables `$DARCS_EMAIL` and
1547       `$EMAIL`.  If none of those exist, Darcs will prompt you for an  author
1548       string  and  write it to `~/.darcs/author`.  Note that if you have more
1549       than one email address, you can put them all in `~/.darcs/author`,  one
1550       author per line.  Darcs will still prompt you for an author, but it al‐
1551       lows you to select from the list, or to type in an alternative.
1552
1553   SENDMAIL
1554       On Unix, the `darcs send` command relies on sendmail(8).  The  `--send‐
1555       mail-command`  or $SENDMAIL environment variable can be used to provide
1556       an explicit path to this  program;  otherwise  the  standard  locations
1557       /usr/sbin/sendmail and /usr/lib/sendmail will be tried.
1558
1559   DARCS_SLOPPY_LOCKS
1560       If on some filesystems you get an error of the kind:
1561
1562           darcs: takeLock [...]: atomic_create [...]: unsupported operation
1563
1564       you may want to try to export DARCS_SLOPPY_LOCKS=True.
1565
1566   DARCS_SSH
1567       Repositories  of  the  form  [user@]host:[dir]  are  taken to be remote
1568       repositories, which Darcs accesses with the external program ssh(1).
1569
1570       The environment variable $DARCS_SSH can be used to specify an  alterna‐
1571       tive  SSH  client.  Arguments may be included, separated by whitespace.
1572       The value is not interpreted by a shell, so shell constructs cannot  be
1573       used; in particular, it is not possible for the program name to contain
1574       whitespace by using quoting or escaping.
1575
1576   DARCS_SCP and DARCS_SFTP
1577       When reading from a remote repository, Darcs will attempt to run `darcs
1578       transfer-mode`  on  the remote host.  This will fail if the remote host
1579       only has Darcs 1 installed, doesn't have Darcs  installed  at  all,  or
1580       only allows SFTP.
1581
1582       If  transfer-mode  fails,  Darcs  will fall back on scp(1) and sftp(1).
1583       The commands invoked can be customized with the  environment  variables
1584       $DARCS_SCP  and $DARCS_SFTP respectively, which behave like $DARCS_SSH.
1585       If the remote end allows only sftp, try setting DARCS_SCP=sftp.
1586
1587   SSH_PORT
1588       If this environment variable is set, it will be used as the port number
1589       for  all  SSH  calls  made by Darcs (when accessing remote repositories
1590       over SSH).  This is useful if your SSH server does not run on  the  de‐
1591       fault  port,  and  your  SSH  client  does  not  support ssh_config(5).
1592       OpenSSH users will probably prefer to put something like `Host  *.exam‐
1593       ple.net Port 443` into their ~/.ssh/config file.
1594
1595   HTTP_PROXY, HTTPS_PROXY, FTP_PROXY, ALL_PROXY, and NO_PROXY
1596       If  Darcs was built with libcurl, the environment variables HTTP_PROXY,
1597       HTTPS_PROXY and FTP_PROXY can be set to the URL of a proxy in the form
1598
1599           [protocol://]<host>[:port]
1600
1601       In which case libcurl will use the proxy for  the  associated  protocol
1602       (HTTP,  HTTPS  and FTP). The environment variable ALL_PROXY can be used
1603       to set a single proxy for all libcurl requests.
1604
1605       If the environment variable NO_PROXY is a comma-separated list of  host
1606       names,  access  to those hosts will bypass proxies defined by the above
1607       variables. For example, it is quite common to avoid  proxying  requests
1608       to machines on the local network with
1609
1610           NO_PROXY=localhost,*.localdomain
1611
1612       For compatibility with lynx et al, lowercase equivalents of these envi‐
1613       ronment variables (e.g. $http_proxy) are also understood and  are  used
1614       in preference to the uppercase versions.
1615
1616       If  Darcs  was  not built with libcurl, all these environment variables
1617       are silently ignored, and there is no way to use a web proxy.
1618
1619   DARCS_PROXYUSERPWD
1620       If Darcs was built with libcurl, and you are using a web proxy that re‐
1621       quires  authentication, you can set the $DARCS_PROXYUSERPWD environment
1622       variable to the username and password expected by the proxy,  separated
1623       by a colon.  This environment variable is silently ignored if Darcs was
1624       not built with libcurl.
1625
1626   DARCS_CONNECTION_TIMEOUT
1627       Set the maximum time in seconds that darcs  allows  and  connection  to
1628       take.  If  the  variable  is  not specified the default are 30 seconds.
1629       This option only works with curl.
1630

FILES

1632   _darcs/prefs/motd
1633       The `_darcs/prefs/motd` file may contain a 'message of the  day'  which
1634       will  be displayed to users who clone or pull from the repository with‐
1635       out the `--quiet` option.
1636
1637
1638   _darcs/prefs/email
1639       The `_darcs/prefs/email` file is used to provide the e-mail address for
1640       your  repository  that  others  will use when they `darcs send` a patch
1641       back to you. The contents of the file should simply be  an  e-mail  ad‐
1642       dress.
1643
1644
1645   _darcs/prefs/post
1646       If  `_darcs/prefs/post`  exists in the target repository, `darcs send `
1647       will upload to the URL contained in that file, which may  either  be  a
1648       `mailto:`  URL,  or  an `http://` URL. In the latter case, the patch is
1649       posted to that URL.
1650
1651
1652   _darcs/prefs/author
1653       The `_darcs/prefs/author` file contains the email address (or name)  to
1654       be  used  as  the  author when patches are recorded in this repository,
1655       e.g. `David Roundy <droundy@abridgegame.org>`. This file overrides  the
1656       contents of the environment variables `$DARCS_EMAIL` and `$EMAIL`.
1657
1658
1659   _darcs/prefs/defaults
1660       Default options for darcs commands. Each line of this file has the fol‐
1661       lowing form:
1662
1663           COMMAND FLAG VALUE
1664
1665       where `COMMAND` is either the name of the command to which the  default
1666       applies,  or `ALL` to indicate that the default applies to all commands
1667       accepting that flag. The `FLAG` term is the name of the  long  argument
1668       option  with  or  without the `--`, i.e. `verbose` or `--verbose`.  Fi‐
1669       nally, the `VALUE` option can be omitted if the flag does not involve a
1670       value.  If  the  value  has spaces in it, use single quotes, not double
1671       quotes, to surround it. Each line only takes one flag. To set  multiple
1672       defaults  for  the  same  command (or for `ALL` commands), use multiple
1673       lines.
1674
1675       Options listed in the defaults file are just that:  defaults.  You  can
1676       override any default on the command line.
1677
1678       Note  that  the  use of `ALL` easily can have unpredicted consequences,
1679       especially if commands in newer versions of darcs  accepts  flags  that
1680       they did not in previous versions. Only use safe flags with `ALL`.
1681
1682       For  example, if your system clock is bizarre, you could instruct darcs
1683       to always ignore the file modification times by  adding  the  following
1684       line:
1685
1686           ALL ignore-times
1687
1688       There  are  some  options  which  are  meant  specifically  for  use in
1689       `_darcs/prefs/defaults`. One of them is `--disable`. As the  name  sug‐
1690       gests,  this option will disable every command that got it as argument.
1691       So, if you are afraid that you could damage your repositories by  inad‐
1692       vertent use of a command like amend, add the following line:
1693
1694           amend disable
1695
1696       A  global  defaults file can be created with the name `.darcs/defaults`
1697       in your home directory. In case of conflicts, the defaults for  a  spe‐
1698       cific repository take precedence.
1699
1700
1701   _darcs/prefs/boring
1702       The  `_darcs/prefs/boring`  file  may contain a list of regular expres‐
1703       sions describing files, such as object files, that you do not expect to
1704       add  to your project. A newly created repository has a boring file that
1705       includes many common source control, backup,  temporary,  and  compiled
1706       files.
1707
1708       You  may want to have the boring file under version control. To do this
1709       you can use darcs setpref to set the value 'boringfile' to the name  of
1710       your  desired  boring  file  (e.g.  `darcs setpref boringfile .boring`,
1711       where `.boring` is the repository path of a file that  has  been  darcs
1712       added   to   your  repository).  The  boringfile  preference  overrides
1713       `_darcs/prefs/boring`, so be sure to copy that file to the boringfile.
1714
1715       You can also set up a 'boring' regexps file  in  your  home  directory,
1716       named  `~/.darcs/boring`,  which  will  be  used with all of your darcs
1717       repositories.
1718
1719       Any file not already managed by darcs and whose repository path matches
1720       any  of the boring regular expressions is considered boring. The boring
1721       file is used to filter the files provided to darcs add, to allow you to
1722       use  a simple `darcs add newdir newdir/*` without accidentally adding a
1723       bunch of object files. It is also used when the `--look-for-adds`  flag
1724       is given to whatsnew or record. Note that once a file has been added to
1725       darcs, it is not considered boring, even if it matches the boring  file
1726       filter.
1727
1728
1729   _darcs/prefs/binaries
1730       The  `_darcs/prefs/binaries` file may contain a list of regular expres‐
1731       sions describing files that should be treated as  binary  files  rather
1732       than text files. Darcs automatically treats files containing characters
1733       `^Z` or `NULL` within the first 4096 bytes as being binary files.   You
1734       probably will want to have the binaries file under version control.  To
1735       do this you can use `darcs setpref` to set the value 'binariesfile'  to
1736       the  name  of your desired binaries file (e.g. `darcs setpref binaries‐
1737       file ./.binaries`, where `.binaries` is a  file  that  has  been  darcs
1738       added to your repository). As with the boring file, you can also set up
1739       a `~/.darcs/binaries` file if you like.
1740
1741
1742   _darcs/prefs/defaultrepo
1743       Contains the URL of the default  remote  repository  used  by  commands
1744       `pull`, `push`, `send` and `optimize relink`. Darcs edits this file au‐
1745       tomatically or when the flag `--set-default` is used.
1746
1747
1748   _darcs/prefs/sources
1749       Besides the defaultrepo, darcs also keeps track of any other  locations
1750       used in commands for exchanging patches (e.g. push, pull, send).  These
1751       are subsequently used as alternatives from which to  download  patches.
1752       The file contains lines such as:
1753
1754           cache:/home/droundy/.cache/darcs
1755           readonly:/home/otheruser/.cache/darcs
1756           repo:http://darcs.net
1757
1758       The  prefix  `cache:` indicates that darcs can use this as a read-write
1759       cache for patches, `read-only:` indicates a cache that  is  only  read‐
1760       able,  and `repo:` denotes a (possibly remote) repository. The order of
1761       the entries is immaterial: darcs will always try local paths before re‐
1762       mote ones, and only local ones will be used as potentially writable.
1763
1764       A  global  cache  is  enabled  by  default in your home directory under
1765       `.cache/darcs` (older versions of darcs used `.darcs/cache` for  this),
1766       or  `$XDG_CACHE_HOME/darcs`  if  the  environment  variable is set, see
1767       https://specifications.freedesktop.org/basedir-spec/basedir-spec-lat
1768       est.html.   The cache allows darcs to avoid re-downloading patches (for
1769       example, when doing a second darcs clone of the same  repository),  and
1770       also allows darcs to use hard links to reduce disk usage.
1771
1772       Note  that  the cache directory should reside on the same filesystem as
1773       your repositories, so you may need to vary this. You can also use  mul‐
1774       tiple  cache  directories on different filesystems, if you have several
1775       filesystems on which you use darcs.
1776
1777       While darcs automatically adds entries  to  `_darcs/prefs/sources`,  it
1778       does  not  currently  remove them. If one or more of the entries aren't
1779       accessible (e.g. because they resided on a removable media), then darcs
1780       will  bugger you with a hint, suggesting you remove those entries. This
1781       is done because certain systems have extremely long timeouts associated
1782       with  some  remotely  accessible  media  (e.g.  NFS over automounter on
1783       Linux), which can slow down darcs operations considerably. On the other
1784       hand, when you clone a repo with --lazy from a no longer accessible lo‐
1785       cation, then the hint may give you an idea where the patches  could  be
1786       found, so you can try to restore access to them.
1787
1788
1789   _darcs/prefs/tmpdir
1790       By  default  temporary  directories  are  created in `/tmp`, or if that
1791       doesn't exist, in `_darcs` (within the  current  repo).   This  can  be
1792       overridden   by   specifying   some   other   directory   in  the  file
1793       `_darcs/prefs/tmpdir` or the environment  variable  `$DARCS_TMPDIR`  or
1794       `$TMPDIR`.
1795
1796
1797   _darcs/prefs/prefs
1798       Contains  the  preferences set by the command `darcs setprefs`.  Do not
1799       edit manually.
1800
1801

BUGS

1803       At http://bugs.darcs.net/ you can find a list of known bugs  in  Darcs.
1804       Unknown  bugs  can be reported at that site (after creating an account)
1805       or by emailing the report to bugs@darcs.net.
1806

SEE ALSO

1808       The Darcs website provides a lot of additional information.  It can  be
1809       found at http://darcs.net/
1810

LICENSE

1812       Darcs  is free software; you can redistribute it and/or modify it under
1813       the terms of the GNU General Public License as published  by  the  Free
1814       Software  Foundation;  either  version 2, or (at your option) any later
1815       version.
1816
1817
1818
1819                               2.16.4 (release)                       DARCS(1)
Impressum