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

DESCRIPTION

74       Darcs is a free, open source revision control system. It is:
75
76       ·  Distributed: Every user has access to the full command set, removing
77          boundaries between server and client or  committer  and  non‐commit‐
78          ters.
79
80       ·  Interactive:  Darcs is easy to learn and efficient to use because it
81          asks you questions  in  response  to  simple  commands,  giving  you
82          choices  in your work flow. You can choose to record one change in a
83          file, while ignoring another. As you update from upstream,  you  can
84          review  each  patch  name,  even  the  full  `diff'  for interesting
85          patches.
86
87       ·  Smart: Originally developed by  physicist  David  Roundy,  darcs  is
88          based  on  a  unique  algebra  of  patches.  This smartness lets you
89          respond to changing demands in ways that would otherwise not be pos‐
90          sible. Learn more about spontaneous branches with darcs.
91

OPTIONS

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

COMMANDS

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

ENVIRONMENT

1213   HOME and APPDATA
1214       Per-user preferences  are  set  in  $HOME/.darcs  (on  Unix)  or  %APP‐
1215       DATA%/darcs  (on  Windows).   This  is also the default location of the
1216       cache.
1217
1218   DARCS_EDITOR, VISUAL, and EDITOR
1219       To edit a patch description of email  comment,  Darcs  will  invoke  an
1220       external  editor.  Your preferred editor can be set as any of the envi‐
1221       ronment variables $DARCS_EDITOR, $VISUAL or $EDITOR.  If none of  these
1222       are  set,  nano is used.  If nano crashes or is not found in your PATH,
1223       vi, emacs, emacs -nw and (on Windows) edit are each tried in turn.
1224
1225   DARCS_PAGER and PAGER
1226       Darcs will invoke a pager if the output of some command is longer  than
1227       20 lines. Darcs will use the pager specified by $DARCS_PAGER or $PAGER.
1228       If neither are set, `less` will be used.
1229
1230   DARCS_DONT_COLOR,    DARCS_ALWAYS_COLOR,    DARCS_ALTERNATIVE_COLOR,    and
1231       DARCS_DO_COLOR_LINES
1232       If  the  terminal  understands  ANSI color escape sequences, darcs will
1233       highlight certain keywords and delimiters when printing  patches.  This
1234       can  be turned off by setting the environment variable DARCS_DONT_COLOR
1235       to 1. If you use a pager that happens to understand ANSI  colors,  like
1236       `less  -R`,  darcs can be forced always to highlight the output by set‐
1237       ting DARCS_ALWAYS_COLOR to 1. If you  can't  see  colors  you  can  set
1238       DARCS_ALTERNATIVE_COLOR  to  1,  and darcs will use ANSI codes for bold
1239       and  reverse  video  instead  of  colors.  In  addition,  there  is  an
1240       extra-colorful  mode,  which  is  not  enabled by default, which can be
1241       activated with DARCS_DO_COLOR_LINES
1242
1243   DARCS_DONT_ESCAPE_TRAILING_SPACES and DARCS_DONT_ESCAPE_TRAILING_CR
1244       By default darcs will escape (by highlighting if possible) any kind  of
1245       spaces  at  the end of lines when showing patch contents.  If you don't
1246       want this you can  turn  it  off  by  setting  DARCS_DONT_ESCAPE_TRAIL‐
1247       ING_SPACES  to  1.  A  special  case  exists for only carriage returns:
1248       DARCS_DONT_ESCAPE_TRAILING_CR
1249
1250   DARCS_DONT_ESCAPE_ANYTHING,  DARCS_DONT_ESCAPE_EXTRA,   DARCS_ESCAPE_EXTRA,
1251       DARCS_DONT_ESCAPE_ISPRINT, and DARCS_ESCAPE_8BIT
1252       Darcs  needs  to escape certain characters when printing patch contents
1253       to a terminal, depending on the encoding specified in your locale  set‐
1254       ting.
1255
1256       By  default,  darcs assumes that your locale encoding is ASCII compati‐
1257       ble.  This includes UTF-8 and some 8-bit  encodings  like  ISO/IEC-8859
1258       (including  its variants). Since ASCII contains control characters like
1259       backspace (which could hide patch content from the  user  when  printed
1260       literally  to  the terminal), and even ones that may introduce security
1261       risks such as redirecting commands to the shell, darcs needs to  escape
1262       such  characters.   They  are  printed as `^<control letter>` or `\<hex
1263       code>`. Darcs also uses special markup for line endings that  are  pre‐
1264       ceeded  by  white  space,  since the white space would otherwise not be
1265       recognizable.
1266
1267       If you use an encoding that is not ASCII compatible, things  are  some‐
1268       what  less smooth. Such encodings include UTF-16 and UTF-32, as well as
1269       many of the encodings that became obsolete with unicode. In  this  case
1270       you have two options: you can set DARCS_DONT_ESCAPE_ANYTHING to 1. Then
1271       everything that doesn't flip code sets should work, and so will all the
1272       bells and whistles in your terminal. This environment variable can also
1273       be handy if you pipe the output to a  pager  or  external  filter  that
1274       knows  better  than  darcs  how  to handle your encoding. Note that all
1275       escaping, including the special escaping of  any  line  ending  spaces,
1276       will be turned off by this setting.
1277
1278       Another possibility is to explicitly tell darcs to not escape or escape
1279       certain bytes, using  DARCS_DONT_ESCAPE_EXTRA  and  DARCS_ESCAPE_EXTRA.
1280       Their  values  should  be  strings  consisting of the verbatim bytes in
1281       question. The do-escapes take precedence over the  dont-escapes.  Space
1282       characters  are still escaped at line endings though. The special envi‐
1283       ronment variable DARCS_DONT_ESCAPE_TRAILING_CR turns  off  escaping  of
1284       carriage return last on the line (DOS style).
1285
1286       For  historical  reasons, darcs also supports DARCS_DONT_ESCAPE_ISPRINT
1287       and DARCS_USE_ISPRINT (which are synonyms). These make sense  only  for
1288       8-bit  encodings  like ISO-8859 and are no longer needed since nowadays
1289       darcs does the right thing here by default.
1290
1291       Finally, if you are in a highly security sensitive situation  (or  just
1292       paranoid  for  other reasons), you can set DARCS_ESCAPE_8BIT to 1. This
1293       will cause darcs to escape every non-ASCII byte in  addition  to  ASCII
1294       control characters.
1295
1296   DARCS_TMPDIR and TMPDIR
1297       Darcs  often  creates  temporary  directories.  For example, the `darcs
1298       diff` command creates two for the  working  trees  to  be  diffed.   By
1299       default  temporary  directories are created in /tmp, or if that doesn't
1300       exist, in _darcs (within the current repo).  This can be overridden  by
1301       specifying  some other directory in the file _darcs/prefs/tmpdir or the
1302       environment variable $DARCS_TMPDIR or $TMPDIR.
1303
1304   DARCS_KEEP_TMPDIR
1305       If the environment variable DARCS_KEEP_TMPDIR is  defined,  darcs  will
1306       not remove the temporary directories it creates.  This is intended pri‐
1307       marily for debugging Darcs itself, but it can also be useful, for exam‐
1308       ple,  to  determine  why  your test preference (see `darcs setpref`) is
1309       failing when you run `darcs record`, but working when run manually.
1310
1311   DARCS_EMAIL and EMAIL
1312       Each patch is attributed to its author, usually by email  address  (for
1313       example,  `Fred  Bloggs  <fred@example.net>`).   Darcs looks in several
1314       places for  this  author  string:  the  `--author`  option,  the  files
1315       `_darcs/prefs/author`  (in  the  repository)  and `~/.darcs/author` (in
1316       your home directory), and the environment variables `$DARCS_EMAIL`  and
1317       `$EMAIL`.   If none of those exist, Darcs will prompt you for an author
1318       string and write it to `~/.darcs/author`.  Note that if you  have  more
1319       than  one email address, you can put them all in `~/.darcs/author`, one
1320       author per line.  Darcs will still prompt you for  an  author,  but  it
1321       allows you to select from the list, or to type in an alternative.
1322
1323   SENDMAIL
1324       On  Unix, the `darcs send` command relies on sendmail(8).  The `--send‐
1325       mail-command` or $SENDMAIL environment variable can be used to  provide
1326       an  explicit  path  to  this  program; otherwise the standard locations
1327       /usr/sbin/sendmail and /usr/lib/sendmail will be tried.
1328
1329   DARCS_SLOPPY_LOCKS
1330       If on some filesystems you get an error of the kind:
1331
1332           darcs: takeLock [...]: atomic_create [...]: unsupported operation
1333
1334       you may want to try to export DARCS_SLOPPY_LOCKS=True.
1335
1336   DARCS_SSH
1337       Repositories of the form  [user@]host:[dir]  are  taken  to  be  remote
1338       repositories, which Darcs accesses with the external program ssh(1).
1339
1340       The  environment variable $DARCS_SSH can be used to specify an alterna‐
1341       tive SSH client.  Arguments may be included, separated  by  whitespace.
1342       The  value is not interpreted by a shell, so shell constructs cannot be
1343       used; in particular, it is not possible for the program name to contain
1344       whitespace by using quoting or escaping.
1345
1346   DARCS_SCP and DARCS_SFTP
1347       When reading from a remote repository, Darcs will attempt to run `darcs
1348       transfer-mode` on the remote host.  This will fail if the  remote  host
1349       only  has  Darcs  1  installed, doesn't have Darcs installed at all, or
1350       only allows SFTP.
1351
1352       If transfer-mode fails, Darcs will fall back  on  scp(1)  and  sftp(1).
1353       The  commands  invoked can be customized with the environment variables
1354       $DARCS_SCP and $DARCS_SFTP respectively, which behave like  $DARCS_SSH.
1355       If the remote end allows only sftp, try setting DARCS_SCP=sftp.
1356
1357   SSH_PORT
1358       If this environment variable is set, it will be used as the port number
1359       for all SSH calls made by Darcs  (when  accessing  remote  repositories
1360       over  SSH).   This  is  useful  if  your SSH server does not run on the
1361       default port, and your  SSH  client  does  not  support  ssh_config(5).
1362       OpenSSH  users will probably prefer to put something like `Host *.exam‐
1363       ple.net Port 443` into their ~/.ssh/config file.
1364
1365   HTTP_PROXY, HTTPS_PROXY, FTP_PROXY, ALL_PROXY, and NO_PROXY
1366       If Darcs was built with libcurl, the environment variables  HTTP_PROXY,
1367       HTTPS_PROXY and FTP_PROXY can be set to the URL of a proxy in the form
1368
1369           [protocol://]<host>[:port]
1370
1371       In  which  case  libcurl will use the proxy for the associated protocol
1372       (HTTP, HTTPS and FTP). The environment variable ALL_PROXY can  be  used
1373       to set a single proxy for all libcurl requests.
1374
1375       If  the environment variable NO_PROXY is a comma-separated list of host
1376       names, access to those hosts will bypass proxies defined by  the  above
1377       variables.  For  example, it is quite common to avoid proxying requests
1378       to machines on the local network with
1379
1380           NO_PROXY=localhost,*.localdomain
1381
1382       For compatibility with lynx et al, lowercase equivalents of these envi‐
1383       ronment  variables  (e.g. $http_proxy) are also understood and are used
1384       in preference to the uppercase versions.
1385
1386       If Darcs was not built with libcurl, all  these  environment  variables
1387       are silently ignored, and there is no way to use a web proxy.
1388
1389   DARCS_PROXYUSERPWD
1390       If  Darcs  was  built  with libcurl, and you are using a web proxy that
1391       requires authentication, you can set the  $DARCS_PROXYUSERPWD  environ‐
1392       ment variable to the username and password expected by the proxy, sepa‐
1393       rated by a colon.  This environment variable  is  silently  ignored  if
1394       Darcs was not built with libcurl.
1395
1396   DARCS_CONNECTION_TIMEOUT
1397       Set  the  maximum  time  in seconds that darcs allows and connection to
1398       take. If the variable is not specified  the  default  are  30  seconds.
1399       This option only works with curl.
1400
1401

FILES

1403   _darcs/prefs/motd
1404       The  `_darcs/prefs/motd`  file may contain a 'message of the day' which
1405       will be displayed to users who clone or pull from the repository  with‐
1406       out the `--quiet` option.
1407
1408
1409   _darcs/prefs/email
1410       The `_darcs/prefs/email` file is used to provide the e-mail address for
1411       your repository that others will use when they  `darcs  send`  a  patch
1412       back  to  you.  The  contents  of  the  file should simply be an e-mail
1413       address.
1414
1415
1416   _darcs/prefs/post
1417       If `_darcs/prefs/post` exists in the target repository, `darcs  send  `
1418       will  upload  to  the URL contained in that file, which may either be a
1419       `mailto:` URL, or an `http://` URL. In the latter case,  the  patch  is
1420       posted to that URL.
1421
1422
1423   _darcs/prefs/author
1424       The  `_darcs/prefs/author` file contains the email address (or name) to
1425       be used as the author when patches are  recorded  in  this  repository,
1426       e.g.  `David Roundy <droundy@abridgegame.org>`. This file overrides the
1427       contents of the environment variables `$DARCS_EMAIL` and `$EMAIL`.
1428
1429
1430   _darcs/prefs/defaults
1431       Default values for darcs commands. Each line of this file has the  fol‐
1432       lowing form:
1433
1434           COMMAND FLAG VALUE
1435
1436       where  `COMMAND` is either the name of the command to which the default
1437       applies, or `ALL` to indicate that the default applies to all  commands
1438       accepting  that  flag. The `FLAG` term is the name of the long argument
1439       option without  the  `--`,  i.e.  `verbose`  rather  than  `--verbose`.
1440       Finally, the `VALUE` option can be omitted if the flag does not involve
1441       a value. If the value has spaces in it, use single quotes,  not  double
1442       quotes,  to surround it. Each line only takes one flag. To set multiple
1443       defaults for the same command (or for  `ALL`  commands),  use  multiple
1444       lines.
1445
1446       Note  that  the  use of `ALL` easily can have unpredicted consequences,
1447       especially if commands in newer versions of darcs  accepts  flags  that
1448       they did not in previous versions. Only use safe flags with `ALL`.
1449
1450       For  example, if your system clock is bizarre, you could instruct darcs
1451       to always ignore the file modification times by  adding  the  following
1452       line:
1453
1454           ALL ignore-times
1455
1456       There  are  some  options  which  are  meant  specifically  for  use in
1457       `_darcs/prefs/defaults`. One of them is `--disable`. As the  name  sug‐
1458       gests,  this option will disable every command that got it as argument.
1459       So, if you are afraid that you could damage your repositories by  inad‐
1460       vertent use of a command like amend, add the following line:
1461
1462           amend disable
1463
1464       Also,   a  global  preferences  file  can  be  created  with  the  name
1465       `.darcs/defaults` in your home directory. Options present there will be
1466       added to the repository-specific preferences if they do not conflict.
1467
1468
1469   _darcs/prefs/sources
1470       The  `_darcs/prefs/sources`  file is used to indicate alternative loca‐
1471       tions from which to download patches. This file contains lines such as:
1472
1473           cache:/home/droundy/.cache/darcs
1474           readonly:/home/otheruser/.cache/darcs
1475           repo:http://darcs.net
1476
1477       This   would   indicate   that   darcs    should    first    look    in
1478       `/home/droundy/.cache/darcs`  for patches that might be missing, and if
1479       the patch is not there, it should save a copy there for future use.  In
1480       that  case, darcs will look in `/home/otheruser/.cache/darcs` to see if
1481       that user might have downloaded a copy, but will not try to save a copy
1482       there,  of  course.  Finally,  it will look in `http://darcs.net`. Note
1483       that the `sources` file can also exist in `~/.darcs/`. Also  note  that
1484       the sources mentioned in your `sources` file will be tried *before* the
1485       repository you are pulling from. This can be useful in  avoiding  down‐
1486       loading  patches  multiple times when you pull from a remote repository
1487       to more than one local repository.
1488
1489       A global cache is enabled by default in your home directory. The  cache
1490       allows darcs to avoid re-downloading patches (for example, when doing a
1491       second darcs clone of the same repository), and also  allows  darcs  to
1492       use hard links to reduce disk usage.
1493
1494       Note  that  the cache directory should reside on the same filesystem as
1495       your repositories, so you may need to vary this. You can also use  mul‐
1496       tiple  cache  directories on different filesystems, if you have several
1497       filesystems on which you use darcs.
1498
1499
1500   _darcs/prefs/boring
1501       The `_darcs/prefs/boring` file may contain a list  of  regular  expres‐
1502       sions describing files, such as object files, that you do not expect to
1503       add to your project. A newly created repository has a boring file  that
1504       includes  many  common  source control, backup, temporary, and compiled
1505       files.
1506
1507       You may want to have the boring file under version control. To do  this
1508       you  can use darcs setpref to set the value 'boringfile' to the name of
1509       your desired boring file  (e.g.  `darcs  setpref  boringfile  .boring`,
1510       where  `.boring`  is  the repository path of a file that has been darcs
1511       added  to  your  repository).  The  boringfile   preference   overrides
1512       `_darcs/prefs/boring`, so be sure to copy that file to the boringfile.
1513
1514       You  can  also  set  up a 'boring' regexps file in your home directory,
1515       named `~/.darcs/boring`, which will be used  with  all  of  your  darcs
1516       repositories.
1517
1518       Any file not already managed by darcs and whose repository path matches
1519       any of the boring regular expressions is considered boring. The  boring
1520       file is used to filter the files provided to darcs add, to allow you to
1521       use a simple `darcs add newdir newdir/*` without accidentally adding  a
1522       bunch  of object files. It is also used when the `--look-for-adds` flag
1523       is given to whatsnew or record. Note that once a file has been added to
1524       darcs,  it is not considered boring, even if it matches the boring file
1525       filter.
1526
1527
1528   _darcs/prefs/binaries
1529       The `_darcs/prefs/binaries` file may contain a list of regular  expres‐
1530       sions  describing  files  that should be treated as binary files rather
1531       than text files. Darcs automatically treats files containing characters
1532       `^Z`  or `NULL` within the first 4096 bytes as being binary files.  You
1533       probably will want to have the binaries file under version control.  To
1534       do  this you can use `darcs setpref` to set the value 'binariesfile' to
1535       the name of your desired binaries file (e.g. `darcs  setpref  binaries‐
1536       file  ./.binaries`,  where  `.binaries`  is  a file that has been darcs
1537       added to your repository). As with the boring file, you can also set up
1538       a `~/.darcs/binaries` file if you like.
1539
1540
1541   _darcs/prefs/defaultrepo
1542       Contains  the  URL  of  the  default remote repository used by commands
1543       `pull`, `push`, `send` and `optimize relink`.  Darcs  edits  this  file
1544       automatically or when the flag `--set-default` is used.
1545
1546
1547   _darcs/prefs/tmpdir
1548       By  default  temporary  directories  are  created in `/tmp`, or if that
1549       doesn't exist, in `_darcs` (within the  current  repo).   This  can  be
1550       overridden   by   specifying   some   other   directory   in  the  file
1551       `_darcs/prefs/tmpdir` or the environment  variable  `$DARCS_TMPDIR`  or
1552       `$TMPDIR`.
1553
1554
1555   _darcs/prefs/prefs
1556       Contains  the  preferences set by the command `darcs setprefs`.  Do not
1557       edit manually.
1558
1559
1560

BUGS

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

SEE ALSO

1567       The Darcs website provides a lot of additional information.  It can  be
1568       found at http://darcs.net/
1569

LICENSE

1571       Darcs  is free software; you can redistribute it and/or modify it under
1572       the terms of the GNU General Public License as published  by  the  Free
1573       Software  Foundation;  either  version 2, or (at your option) any later
1574       version.
1575
1576
1577
1578                               2.14.4 (release)                       DARCS(1)
Impressum