xenial (1) darcs.1.gz

Provided by: darcs_2.10.2-1_amd64 bug

NAME

       darcs - an advanced revision control system

SYNOPSIS

       darcs command <arguments|[options]>...

       Where the commands and their respective arguments are

       darcs help [<darcs_command> [darcs_subcommand]]
       darcs add <file|directory> ...
       darcs remove <file|directory> ...
       darcs move <source> ... <destination>
       darcs replace <old> <new> <file> ...
       darcs revert [file|directory]...
       darcs unrevert
       darcs whatsnew [file|directory]...
       darcs record [file|directory]...
       darcs unrecord
       darcs amend [file|directory]...
       darcs mark-conflicts
       darcs tag [tagname]
       darcs setpref <pref> <value>
       darcs diff [file|directory]...
       darcs log [file|directory]...
       darcs annotate [file|directory]...
       darcs dist
       darcs test [[initialization] command]
       darcs show contents [file]...
       darcs show files [file|directory]...
       darcs show index
       darcs show pristine
       darcs show repo
       darcs show authors
       darcs show tags
       darcs show patch-index-all
       darcs show patch-index-files
       darcs show patch-index-status
       darcs show patch-index-test
       darcs pull [repository]...
       darcs fetch [repository]...
       darcs obliterate
       darcs rollback [file|directory]...
       darcs push [repository]
       darcs send [repository]
       darcs apply <patchfile>
       darcs clone <repository> [<directory>]
       darcs initialize [<directory>]
       darcs optimize clean
       darcs optimize http
       darcs optimize reorder
       darcs optimize enable-patch-index
       darcs optimize disable-patch-index
       darcs optimize compress
       darcs optimize uncompress
       darcs optimize relink
       darcs optimize pristine
       darcs optimize upgrade
       darcs optimize cache <directory> ...
       darcs repair
       darcs convert darcs-2 <source> [<destination>]
       darcs convert export
       darcs convert import [<directory>]
       darcs rebase pull [repository]...
       darcs rebase apply <patchfile>
       darcs rebase suspend
       darcs rebase unsuspend
       darcs rebase obliterate
       darcs rebase log

DESCRIPTION

       Darcs is a free, open source revision control system. It is:

       •  Distributed:  Every  user  has  access to the full command set, removing boundaries between server and
          client or committer and non‐committers.

       •  Interactive: Darcs is easy to learn and efficient to use because it asks you questions in response  to
          simple  commands, giving you choices in your work flow. You can choose to record one change in a file,
          while ignoring another. As you update from upstream, you can review each patch  name,  even  the  full
          `diff' for interesting patches.

       •  Smart:  Originally developed by physicist David Roundy, darcs is based on a unique algebra of patches.
          This smartness lets you respond to changing demands in ways that  would  otherwise  not  be  possible.
          Learn more about spontaneous branches with darcs.

OPTIONS

       Different  options  are  accepted by different Darcs commands.  Each command's most important options are
       listed in the COMMANDS section.  For a full list of all options accepted by  a  particular  command,  run
       `darcs command --help'.

   Selecting Patches:
       The  --patches  option yields patches with names matching an *extended* regular expression.  See regex(7)
       for details.  The --matches option yields patches that match a logical (Boolean) expression: one or  more
       primitive  expressions combined by grouping (parentheses) and the complement (not), conjunction (and) and
       disjunction (or) operators.  The C notation for logic operators (!, && and ||) can also be used.

       - --patches=regex is a synonym for --matches='name regex' - --hash=HASH is a synonym for  --matches='hash
       HASH'  -  --from-patch  and  --to-patch are synonyms for --from-match='name... and --to-match='name...  -
       --from-patch and --to-match can be unproblematically combined:
         `darcs changes --from-patch='html.*documentation' --to-match='date 20040212'`

       The following primitive Boolean expressions are supported:

       - exact - check a literal string against the patch name.  - name - check a regular expression against the
       patch  name.   -  author  - check a regular expression against the author name.  - hunk - check a regular
       expression against the contents of a hunk patch.  - comment - check a regular expression against the  log
       message.   - hash - match a full hash or a prefix for a patch.  - date - match the patch date.  - touch -
       match file paths for a patch.

       Here are some examples:

           darcs annotate --summary --match 'exact "Resolve issue17: use dynamic memory allocation."'
           darcs annotate --summary --match 'name issue17'
           darcs annotate --summary --match 'name "^[Rr]esolve issue17\>"'
           darcs annotate --summary --match 'author "David Roundy"'
           darcs annotate --summary --match 'author droundy'
           darcs annotate --summary --match 'author droundy@darcs.net'
           darcs annotate --summary --match 'hunk "foo = 2"'
           darcs annotate --summary --match 'hunk "^instance .* Foo where$"'
           darcs annotate --summary --match 'comment "prevent deadlocks"'
           darcs annotate --summary --match 'hash c719567e92c3b0ab9eddd5290b705712b8b918ef'
           darcs annotate --summary --match 'hash c7195'
           darcs annotate --summary --match 'date "2006-04-02 22:41"'
           darcs annotate --summary --match 'date "tea time yesterday"'
           darcs annotate --summary --match 'touch src/foo.c'
           darcs annotate --summary --match 'touch src/'
           darcs annotate --summary --match 'touch "src/*.(c|h)"'

COMMANDS

       darcs help [<darcs_command> [darcs_subcommand]]
           Without arguments, `darcs help` prints a categorized list of darcs commands and a  short  description
           of  each  one.  With an extra argument, `darcs help foo` prints detailed help about the darcs command
           foo.

   Changing and querying the working copy:
       darcs add <file|directory> ...
           Generally a repository contains both files that should be version controlled (such  as  source  code)
           and  files  that Darcs should ignore (such as executables compiled from the source code).  The `darcs
           add` command is used to tell Darcs which files to version control.

           When an existing project is first imported into a Darcs repository, it is common to run `darcs add -r
           *` or `darcs record -l` to add all initial source files into darcs.

           Adding symbolic links (symlinks) is not supported.

           Darcs  will  ignore  all  files and folders that look "boring".  The `--boring` option overrides this
           behaviour.

           Darcs will not add file if another file in the same folder has the same name, except for  case.   The
           `--case-ok`  option  overrides  this behaviour.  Windows and OS X usually use filesystems that do not
           allow files a folder to have the same name except for case (for example, `ReadMe` and `README`).   If
           `--case-ok` is used, the repository might be unusable on those systems!

       darcs remove <file|directory> ...
           The  `darcs  remove`  command  exists  primarily  for symmetry with `darcs add`, as the normal way to
           remove a file from version control is simply to delete it from the working  tree.   This  command  is
           only  useful  in the unusual case where one wants to record a removal patch WITHOUT deleting the copy
           in the working tree (which can be re-added).

           Note that applying a removal patch to a repository (e.g. by pulling the patch) will ALWAYS affect the
           working tree of that repository.

       darcs move <source> ... <destination>
           Darcs  cannot reliably distinguish between a file being deleted and a new one added, and a file being
           moved.  Therefore Darcs always assumes the former, and provides the `darcs mv` command to  let  Darcs
           know  when  you  want  the  latter.  This command will also move the file in the working tree (unlike
           `darcs remove`), unless it has already been moved.

           Darcs will not rename a file if another file in the same folder has the same name, except  for  case.
           The  `--case-ok`  option  overrides this behaviour.  Windows and OS X usually use filesystems that do
           not allow files a folder to have the same name except for case (for example, `ReadMe` and  `README`).
           If `--case-ok` is used, the repository might be unusable on those systems!

       darcs replace <old> <new> <file> ...
           In  addition to line-based patches, Darcs supports a limited form of lexical substitution.  Files are
           treated as sequences of words, and each occurrence of the old word is replaced by the new word.  This
           is intended to provide a clean way to rename a function or variable.  Such renamings typically affect
           lines all through the source code, so a traditional line-based patch would be very likely to conflict
           with other branches, requiring manual merging.

           Files  are  tokenized  according to one simple rule: words are strings of valid token characters, and
           everything between  them  (punctuation  and  whitespace)  is  discarded.   By  default,  valid  token
           characters  are letters, numbers and the underscore (i.e. `[A-Za-z0-9_]`).  However if the old and/or
           new token contains either a hyphen or period, BOTH hyphen and  period  are  treated  as  valid  (i.e.
           `[A-Za-z0-9_.-]`).

           The set of valid characters can be customized using the `--token-chars` option.  The argument must be
           surrounded by square brackets.  If a hyphen occurs between two characters in the set, it  is  treated
           as  a  set  range.  For example, in most locales `[A-Z]` denotes all uppercase letters.  If the first
           character is a caret, valid tokens are taken to be the complement of the remaining  characters.   For
           example,  `[^:\n]`  could  be  used  to  match  fields in the passwd(5), where records and fields are
           separated by newlines and colons respectively.

           If you choose to use `--token-chars`, you  are  STRONGLY  encouraged  to  do  so  consistently.   The
           consequences  of  using multiple replace patches with different `--token-chars` arguments on the same
           file are not well tested nor well understood.

           By default Darcs will refuse to perform a replacement if the new token is already in use, because the
           replacements  would  be  not  be  distinguishable  from  the  existing tokens.  This behaviour can be
           overridden by supplying the `--force` option, but an attempt to `darcs rollback` the resulting  patch
           will affect these existing tokens.

           Limitations:

           The  tokenizer  treats  files  as  byte strings, so it is not possible for `--token-chars` to include
           multi-byte characters, such as the  non-ASCII  parts  of  UTF-8.   Similarly,  trying  to  replace  a
           "high-bit"  character  from  a  unibyte  encoding will also result in replacement of the same byte in
           files with different encodings.  For example, an acute a from ISO 8859-1 will  also  match  an  alpha
           from ISO 8859-7.

           Due  to  limitations  in  the  patch  file  format,  `--token-chars` arguments cannot contain literal
           whitespace.  For example, `[^ \n\t]` cannot be used to declare all characters except the  space,  tab
           and newline as valid within a word, because it contains a literal space.

           Unlike  POSIX  regex(7)  bracket  expressions,  character  classes  (such  as  `[[:alnum:]]`) are NOT
           supported by `--token-chars`, and will be silently treated as a simple set of characters.

       darcs revert [file|directory]...
           The `darcs revert` command discards unrecorded changes the working tree.  As with `darcs record`, you
           will  be  asked  which  hunks  (changes)  to  revert.   The  `--all` switch can be used to avoid such
           prompting. If files or directories are specified, other parts of the working tree are not reverted.

           In you accidentally reverted something you wanted to keep (for example, typing `darcs rev -a` instead
           of  `darcs rec -a`), you can immediately run `darcs unrevert` to restore it.  This is only guaranteed
           to work if the repository has not changed since `darcs revert` ran.

       darcs unrevert
           Unrevert is a rescue command in case you accidentally reverted something  you  wanted  to  keep  (for
           example, typing `darcs rev -a` instead of `darcs rec -a`).

           This  command may fail if the repository has changed since the revert took place.  Darcs will ask for
           confirmation before executing an interactive command that will DEFINITELY prevent unreversion.

       darcs whatsnew [file|directory]...
           The `darcs whatsnew` command lists unrecorded changes to the working tree.  If you specify a  set  of
           files and directories, only unrecorded changes to those files and directories are listed.

           With  the  `--summary`  option,  the  changes  are  condensed to one line per file, with mnemonics to
           indicate the nature and extent of the change.  The `--look-for-adds`  option  causes  candidates  for
           `darcs add` to be included in the summary output.  Summary mnemonics are as follows:

           *  `A  f`  and  `A d/` respectively mean an added file or directory.  * `R f` and `R d/` respectively
           mean a removed file or directory.  * `M f -N +M rP` means a modified file, with  `N`  lines  deleted,
           `M`
             lines  added,  and  `P` lexical replacements.  * `f -> g` means a moved file or directory.  * `a f`
           and `a d/` respectively mean a new, but unadded, file or
             directory, when using `--look-for-adds`.

             An exclamation mark (!) as in `R! foo.c`, means the hunk is known to
             conflict with a hunk in another patch.  The phrase `duplicated`
             means the hunk is known to be identical to a hunk in another patch.

           By default, `darcs whatsnew` uses Darcs' internal format for changes.  To see some context (unchanged
           lines)  around  each  change,  use  the  `--unified`  option.  To view changes in conventional `diff`
           format, use the `darcs diff` command; but note that `darcs whatsnew` is faster.

           This command exits unsuccessfully (returns a  non-zero  exit  status)  if  there  are  no  unrecorded
           changes.

   Copying changes between the working copy and the repository:
       darcs record [file|directory]...
           The  `darcs  record`  command  is  used  to  create a patch from changes in the working tree.  If you
           specify a set of files and directories, changes to other files will be skipped.

           Every patch has a name, an optional description, an author and a date.

           Darcs will launch a text editor (see `darcs help environment`) after the  interactive  selection,  to
           let you enter the patch name (first line) and the patch description (subsequent lines).

           The  patch  name  should  be  a short sentence that concisely describes the patch, such as "Add error
           handling to main event loop."  You can supply it in advance with the `-m` option, in  which  case  no
           text editor is launched, unless you use the `--edit-long-comment` option.

           The  patch  description  is  an  optional  block  of free-form text.  It is used to supply additional
           information that doesn't fit in the patch name.  For example, it might include a rationale of WHY the
           change was necessary.

           A  technical difference between patch name and patch description, is that matching with the flag `-p`
           is only done on patch names.

           Finally, the `--logfile` option allows you to supply a file that already contains the patch name  and
           patch description.  This is useful if a previous record failed and left a `darcs-record-0` file.

           Each  patch  is  attributed  to  its  author,  usually  by  email  address (for example, `Fred Bloggs
           <fred@example.net>`).  Darcs looks in several places for this author string: the  `--author`  option,
           the  files  `_darcs/prefs/author` (in the repository) and `~/.darcs/author` (in your home directory),
           and the environment variables `$DARCS_EMAIL` and `$EMAIL`.  If none of those exist, Darcs will prompt
           you  for  an  author  string  and write it to `~/.darcs/author`.  Note that if you have more than one
           email address, you can put them all in `~/.darcs/author`, one author  per  line.   Darcs  will  still
           prompt you for an author, but it allows you to select from the list, or to type in an alternative.

           If  you  want  to manually define any extra dependencies for your patch, you can use the `--ask-deps`
           flag, and darcs will ask you for the patch's dependencies.  Some dependencies  may  be  automatically
           inferred  from  the patch's content and cannot be removed.  A patch with specific dependencies can be
           empty.

           The patch date is generated automatically.  It can only be spoofed by using the `--pipe` option.

           If you run record with the `--pipe` option, you will be prompted for the patch date, author, and  the
           long comment. The long comment will extend until the end of file or stdin is reached (ctrl-D on Unixy
           systems, ctrl-Z on systems running a Microsoft OS).

           This interface is intended for scripting darcs,  in  particular  for  writing  repository  conversion
           scripts.   The prompts are intended mostly as a useful guide (since scripts won't need them), to help
           you understand the format in which to provide the input. Here's  an  example  of  what  the  `--pipe`
           prompts look like:

               What is the date? Mon Nov 15 13:38:01 EST 2004
               Who is the author? David Roundy
               What is the log? One or more comment lines

           If  a test command has been defined with `darcs setpref`, attempting to record a patch will cause the
           test command to be run in a clean copy  of  the  working  tree  (that  is,  including  only  recorded
           changes).  If the test fails, you will be offered to abort the record operation.

           The  `--set-scripts-executable`  option causes scripts to be made executable in the clean copy of the
           working tree, prior to running the test.   See  `darcs  clone`  for  an  explanation  of  the  script
           heuristic.

           If  your  test command is tediously slow (e.g. `make all`) and you are recording several patches in a
           row, you may wish to use `--no-test` to skip all but the final test.

           To see some context (unchanged lines) around each change, use the `--unified` option.

       darcs unrecord
           Unrecord does the opposite of record: it deletes patches from the repository,  without  changing  the
           working  copy.   Deleting patches from the repository makes active changes again which you may record
           or revert later.  Beware that you should not use this command if there is a possibility that  another
           user may have already pulled the patch.

       darcs amend [file|directory]...
           Amend updates a "draft" patch with additions or improvements, resulting in a single "finished" patch.

           By default `amend` proposes you to record additional changes.  If instead you want to remove changes,
           use the flag `--unrecord`.

           When recording a draft patch, it is a good idea to start the name with `DRAFT:`. When done, remove it
           with  `darcs amend --edit-long-comment`.  Alternatively, to change the patch name without starting an
           editor, use the `--name`/`-m` flag:

               darcs amend --match 'name "DRAFT: foo"' --name 'foo2'

           Like `darcs record`, if you call amend with files as arguments, you will only be asked about  changes
           to those files.  So to amend a patch to foo.c with improvements in bar.c, you would run:

               darcs amend --match 'touch foo.c' bar.c

           It  is  usually a bad idea to amend another developer's patch.  To make amend only ask about your own
           patches by default, you can add something like `amend match  David  Roundy`  to  `~/.darcs/defaults`,
           where `David Roundy` is your name.

       darcs mark-conflicts
           Darcs  requires  human  guidance to unify changes to the same part of a source file.  When a conflict
           first occurs, darcs will add the initial state and both choices to the working tree, delimited by the
           markers `v v v`, `=====`,  `* * *` and `^ ^ ^`, as follows:

               v v v v v v v
               Initial state.
               =============
               First choice.
               *************
               Second choice.
               ^ ^ ^ ^ ^ ^ ^

           However,  you  might revert or manually delete these markers without actually resolving the conflict.
           In this case, `darcs mark-conflicts` is useful to show where are the  unresolved  conflicts.   It  is
           also  useful  if  `darcs  apply`  is  called  with `--apply-conflicts`, where conflicts aren't marked
           initially.

           Unless you use the `--dry-run` flag, any unrecorded changes to the working tree WILL be lost  forever
           when you run this command!  You will be prompted for confirmation before this takes place.

   Direct modification of the repository:
       darcs tag [tagname]
           The  `darcs  tag`  command  names  the current repository state, so that it can easily be referred to
           later.  Every *important* state should be tagged; in particular it  is  good  practice  to  tag  each
           stable   release  with  a  number  or  codename.   Advice  on  release  numbering  can  be  found  at
           <http://producingoss.com/en/development-cycle.html>.

           To reproduce the state of a repository `R` as at tag `t`, use the command `darcs clone  --tag  t  R`.
           The command `darcs show tags` lists all tags in the current repository.

           Tagging  also provides significant performance benefits: when Darcs reaches a shared tag that depends
           on all antecedent patches, it can simply stop processing.

           Like normal patches, a tag has a name, an author, a timestamp and an optional long  description,  but
           it  does  not  change  the working tree.  A tag can have any name, but it is generally best to pick a
           naming scheme and stick to it.

           By default a tag names the entire repository state at the time the tag is created. If the  --ask-deps
           option is used, the patches to include as part of the tag can be explicitly selected.

           The `darcs tag` command accepts the `--pipe` option, which behaves as described in `darcs record`.

       darcs setpref <pref> <value>
           When  working on project with multiple repositories and contributors, it is sometimes desirable for a
           preference to be set consistently project-wide.  This is achieved by treating a preference  set  with
           `darcs  setpref`  as an unrecorded change, which can then be recorded and then treated like any other
           patch.

           Valid preferences are:

           * test -- a shell command that runs regression tests * predist --  a  shell  command  to  run  before
           `darcs  dist' * boringfile -- the path to a version-controlled boring file * binariesfile -- the path
           to a version-controlled binaries file

           For example, a project using GNU autotools, with a `make test` target to  perform  regression  tests,
           might enable Darcs' integrated regression testing with the following command:

               darcs setpref test 'autoconf && ./configure && make && make test'

           Note  that  merging  is  not currently implemented for preferences: if two patches attempt to set the
           same preference, the last patch applied to the repository  will  always  take  precedence.   This  is
           considered a low-priority bug, because preferences are seldom set.

   Querying the repository:
       darcs diff [file|directory]...
           The  `darcs  diff`  command  compares  two  versions  of  the working tree of the current repository.
           Without options, the pristine  (recorded)  and  unrecorded  working  trees  are  compared.   This  is
           lower-level  than  the `darcs whatsnew` command, since it outputs a line-by-line diff, and it is also
           slower.  As with `darcs whatsnew`, if you specify files or directories, changes to  other  files  are
           not listed.  The command always uses an external diff utility.

           With  the  `--patch`  option, the comparison will be made between working trees with and without that
           patch.  Patches *after* the selected patch are not present in either of the compared  working  trees.
           The  `--from-patch`  and `--to-patch` options allow the set of patches in the `old' and `new' working
           trees to be specified separately.

           The associated tag and match options are also understood, e.g. `darcs diff  --from-tag  1.0  --to-tag
           1.1`.   All  these  options  assume  an  ordering  of  the  patch  set, so results may be affected by
           operations such as `darcs optimize --reorder`.

           diff(1) is called with the arguments `-rN`.  The `--unified` option  causes  `-u`  to  be  passed  to
           diff(1).   An  additional  argument  can  be passed using `--diff-opts`, such as `--diff-opts=-ud` or
           `--diff-opts=-wU9`.

           The `--diff-command` option can be used to specify an alternative utility, such as  meld  (GNOME)  or
           opendiff  (OS  X).  Arguments may be included, separated by whitespace.  The value is not interpreted
           by a shell, so shell constructs cannot be used.  The arguments %1 and %2 MUST be included, these  are
           substituted  for  the  two  working  trees  being compared.  If this option is used, `--diff-opts` is
           ignored.

       darcs log [file|directory]...
           The `darcs log` command lists the patches that constitute the current repository or, with `--repo`, a
           remote repository.  Without options or arguments, ALL patches will be listed.

           When  given  one  or more files or directories as arguments, only patches which affect those files or
           directories are listed. This includes patches that happened  to  files  before  they  were  moved  or
           renamed.

           When given a `--from-tag`, `--from-patch` or `--from-match`, only patches since that tag or patch are
           listed.  Similarly, the `--to-tag`, `--to-patch` and `--to-match` options restrict the list to  older
           patches.

           The  `--last`  and `--max-count` options both limit the number of patches listed.  The former applies
           BEFORE other filters, whereas the latter applies AFTER other filters.  For example `darcs  log  foo.c
           --max-count  3`  will  print  the  last  three patches that affect foo.c, whereas `darcs log --last 3
           foo.c` will, of the last three patches, print only those that affect foo.c.

           Three output formats exist.  The default is `--human-readable`.  You  can  also  select  `--context`,
           which  is  the  internal  format (as seen in patch bundles) that can be re-read by Darcs (e.g. `darcs
           clone --context`).

           Finally, there is `--xml-output`, which emits valid XML... unless a the patch metadata (author,  name
           or description) contains a non-ASCII character and was recorded in a non-UTF8 locale.

           Note   that   while  the  `--context`  flag  may  be  used  in  conjunction  with  `--xml-output`  or
           `--human-readable`, in neither case will darcs clone be able to read the output.  On the other  hand,
           sufficient  information WILL be output for a knowledgeable human to recreate the current state of the
           repository.

       darcs annotate [file|directory]...
           The `darcs annotate` command provides two unrelated operations.  When called on a file, it will  find
           the  patch that last modified each line in that file.  When called on a patch (e.g. using `--patch`),
           it will print the internal representation of that patch.

           The `--summary` option will result in a summarized patch annotation, similar to `darcs whatsnew`.  It
           has no effect on file annotations.

           By  default,  output  is  in a human-readable format.  The `--machine-readable` option can be used to
           generate output for machine postprocessing.

       darcs dist
           `darcs dist` creates a compressed archive in the repository's root directory, containing the recorded
           state  of the working tree (unrecorded changes and the `_darcs` directory are excluded).  The command
           accepts matchers to create an archive of some past repository state, for instance `--tag`.

           By default, the archive (and the top-level directory within the archive) has the  same  name  as  the
           repository, but this can be overridden with the `--dist-name` option.

           If  a  predist  command  is set (see `darcs setpref`), that command will be run on the recorded state
           prior to archiving.  For example, autotools projects would set it to `autoconf && automake`.

           If `--zip` is used, matchers and the predist command are ignored.

       darcs test [[initialization] command]
           Run test on the current recorded state of the repository.  Given no arguments, it  uses  the  default
           repository  test  (see  `darcs setpref`).  Given one argument, it treats it as a test command.  Given
           two arguments, the first is an initialization command and the second is the test  (meaning  the  exit
           code  of the first command is not taken into account to determine success of the test).  If given the
           `--linear` or `--bisect` flags, it tries to find the most recent  version  in  the  repository  which
           passes a test.

           `--linear`  does  linear  search starting from head, and moving away from head. This strategy is best
           when the test runs very quickly or the patch you're seeking is near the head.

           `--bisect` does binary search.  This strategy is best when the test runs very  slowly  or  the  patch
           you're seeking is likely to be in the repository's distant past.

           `--backoff`  starts  searching  from  head, skipping further and further into the past until the test
           succeeds.  It then does a binary search on a subset of those skipped patches.   This  strategy  works
           well unless the patch you're seeking is in the repository's distant past.

           Under  the  assumption that failure is monotonous, `--linear` and `--bisect` produce the same result.
           (Monotonous means that when moving away from head, the test result changes only once from  "fail"  to
           "ok".)  If failure is not monotonous, any one of the patches that break the test is found at random.

       darcs show contents [file]...
           Show  contents  can be used to display an earlier version of some file(s).  If you give show contents
           no version arguments, it displays the recorded version of the file(s).

       darcs show files [file|directory]...
           The `darcs show files` command lists those files and directories in the working tree that  are  under
           version  control.   This  command  is  primarily for scripting purposes; end users will probably want
           `darcs whatsnew --summary`.

           A file is "pending" if it  has  been  added  but  not  recorded.   By  default,  pending  files  (and
           directories) are listed; the `--no-pending` option prevents this.

           By  default  `darcs show files` lists both files and directories, but the alias `darcs show manifest`
           only lists files.  The `--files`, `--directories`, `--no-files` and  `--no-directories`  modify  this
           behaviour.

           By  default  entries are one-per-line (i.e. newline separated).  This can cause problems if the files
           themselves contain newlines or other control characters.  To get around  this,  the  `--null`  option
           uses  the  null  character  instead.   The  script  interpreting  output  from  this command needs to
           understand this idiom; `xargs -0` is such a command.

           For example, to list version-controlled files by size:

               darcs show files -0 | xargs -0 ls -ldS

       darcs show index
           The `darcs show index` command lists all version-controlled files and directories  along  with  their
           hashes  as  stored  in  `_darcs/index`.  For files, the fields correspond to file size, sha256 of the
           current file content and the filename.
       darcs show pristine
           The `darcs show pristine` command lists all version-controlled files and directories along  with  the
           hashes  of  their  pristine  copies.  For  files,  the  fields correspond to file size, sha256 of the
           pristine file content and the filename.
       darcs show repo
           The `darcs show repo` command displays statistics about the current repository, allowing  third-party
           scripts  to  access  this information without inspecting `_darcs` directly (and without breaking when
           the `_darcs` format changes).

           By default, the number of patches  is  shown.   If  this  data  isn't  needed,  use  `--no-files`  to
           accelerate this command from O(n) to O(1).

           By  default, output is in a human-readable format.  The `--xml-output` option can be used to generate
           output for machine postprocessing.

       darcs show authors
           The `darcs show authors` command lists the authors of the current repository, sorted by the number of
           patches contributed.  With the `--verbose` option, this command simply lists the author of each patch
           (without aggregation or sorting).

           An author's name or email address may change over time.  To tell Darcs when multiple  author  strings
           refer  to  the  same  individual,  create an `.authorspellings` file in the root of the working tree.
           Each line in this file begins with an author's canonical name and address, and may be followed  by  a
           comma  separated  list  of  extended  regular  expressions.  Blank lines and lines beginning with two
           hyphens are ignored.  The format of `.authorspelling` can be described by this pattern:

               name <address> [, regexp ]*

           There are some pitfalls concerning special characters: Whitespaces are stripped, if you need space in
           regexp  use [ ].  Because comma serves as a separator you have to escape it if you want it in regexp.
           Note that `.authorspelling` use extended regular expressions so +, ? and so on are metacharacters and
           you need to escape them to be interpreted literally.

           Any  patch  with an author string that matches the canonical address or any of the associated regexps
           is considered to be the work of that author.  All matching is case-insensitive and  partial  (it  can
           match a substring). Use ^,$ to match the whole string in regexps

           Currently  this  canonicalization step is done only in `darcs show authors`.  Other commands, such as
           `darcs log` use author strings verbatim.

           An example `.authorspelling` file is:

               -- This is a comment.
               Fred Nurk <fred@example.com>
               John Snagge <snagge@bbc.co.uk>, John, snagge@, js@(si|mit).edu
               Chuck Jones\, Jr. <chuck@pobox.com>, cj\+user@example.com

       darcs show tags
           The tags command writes a list of all tags in the repository to standard output.

           Tab characters (ASCII character 9) in tag names are changed to  spaces  for  better  interoperability
           with shell tools. A warning is printed if this happens.

       darcs show patch-index-all
           The `darcs show patch-index all' command lists all information in the patch index
       darcs show patch-index-files
           The `darcs show patch-index files' command lists all current files registered in the patch index
       darcs show patch-index-status
           The  `darcs  show patch-index-status' reports if the patch index is in sync, out of sync, or does not
           exist
       darcs show patch-index-test
           The `darcs show patch-index-test' tests patch index

   Copying patches between repositories with working copy update:
       darcs pull [repository]...
           Pull is used to bring patches made in another repository into the current repository (that is, either
           the  one in the current directory, or the one specified with the `--repodir` option). Pull allows you
           to bring over all or some of the patches that are in that  repository  but  not  in  this  one.  Pull
           accepts  arguments, which are URLs from which to pull, and when called without an argument, pull will
           use the repository from which you have most recently either pushed or pulled.

           The default (`--union`)  behavior  is  to  pull  any  patches  that  are  in  any  of  the  specified
           repositories.  If you specify the `--intersection` flag, darcs will only pull those patches which are
           present in all source repositories.  If you specify the `--complement` flag,  darcs  will  only  pull
           elements in the first repository that do not exist in any of the remaining repositories.

           If  `--reorder`  is supplied, the set of patches that exist only in the current repository is brought
           at the top of the current history. This will work even if there are no new patches to pull.

           See `darcs help apply` for detailed description of many options.

       darcs fetch [repository]...
           Fetch is similar to `pull` except that it does not apply  any  patches  to  the  current  repository.
           Instead, it generates a patch bundle that you can apply later with `apply`.

           Fetch's  behaviour  is  essentially  similar  to pull's, so please consult the help of `pull` to know
           more.

       darcs obliterate
           Obliterate completely removes recorded patches from your local repository. The changes will be undone
           in  your working copy and the patches will not be shown in your changes list anymore. Beware that you
           can lose precious code by obliterating!

           One way to save obliterated patches is to use the -O flag. A patch bundle will  be  created  locally,
           that you will be able to apply later to your repository with `darcs apply`.

       darcs rollback [file|directory]...
           Rollback  is  used  to  undo the effects of some changes from patches in the repository. The selected
           changes are undone in your working copy, but the repository is left unchanged. First you are  offered
           a choice of which patches to undo, then which changes within the patches to undo.

           Before  doing `rollback`, you may want to temporarily undo the changes of your working copy (if there
           are) and save them for later use.  To do so, you can run `revert`,  then  run  `rollback`,  record  a
           patch, and run `unrevert` to restore the saved changes into your working copy.

       darcs push [repository]
           Push  is  the  opposite  of  pull.   Push allows you to copy patches from the current repository into
           another repository.

           If you give the `--apply-as` flag, darcs will use sudo to apply the  patches  as  a  different  user.
           This can be useful if you want to set up a system where several users can modify the same repository,
           but you don't want to allow them full write access.  This  isn't  secure  against  skilled  malicious
           attackers, but at least can protect your repository from clumsy, inept or lazy users.

           Darcs  push  will  by default compress the patch data before sending it to a remote location via ssh.
           This works as long as the remote darcs is not older than version 2.5. If you get errors that indicate
           a  corrupt  patch  bundle,  you  should try again with the `--no-compress` option to send the data in
           un-compressed form (which is a lot slower for large patches, but should always work).

       darcs send [repository]
           Send is used to prepare a bundle of patches that can be applied to a target repository.  Send accepts
           the  URL  of  the repository as an argument.  When called without an argument, send will use the most
           recent repository that was either pushed to, pulled from or sent to.  By default, the patch bundle is
           saved to a file, although you may directly send it by mail.

           The  `--output`,  `--output-auto-name`,  and  `--to`  flags  determine what darcs does with the patch
           bundle after creating it.  If you provide an `--output` argument, the patch bundle is saved  to  that
           file.  If you specify `--output-auto-name`, the patch bundle is saved to a file with an automatically
           generated name.  If you give one or more `--to` arguments, the bundle of patches  is  sent  to  those
           locations.  The locations may either be email addresses or urls that the patch should be submitted to
           via HTTP.

           If you provide the `--mail` flag, darcs will look at the contents of the `_darcs/prefs/email` file in
           the target repository (if it exists), and send the patch by email to that address.  In this case, you
           may use the `--cc` option to specify additional recipients without overriding the default  repository
           email address.

           If  `_darcs/prefs/post`  exists  in  the target repository, darcs will upload to the URL contained in
           that file, which may either be a `mailto:` URL, or an `http://` URL.  In the latter case,  the  patch
           is posted to that URL.

           If  there  is  no  email  address  associated with the repository, darcs will prompt you for an email
           address.

           Use the `--subject` flag to set the subject of the e-mail to be sent.  If you don't provide a subject
           on the command line, darcs will make one up based on names of the patches in the patch bundle.

           Use  the `--in-reply-to` flag to set the In-Reply-To and References headers of the e-mail to be sent.
           By default no additional headers are included so e-mail will not be treated as reply by mail readers.

           If you want to include a description or explanation along with the bundle of  patches,  you  need  to
           specify the `--edit-description` flag, which will cause darcs to open up an editor with which you can
           compose a message to go along with your patches.

           If you want to use a command different from the default one for sending email, you need to specify  a
           command  line  with  the  `--sendmail-command`  option.  The  command  line  can  contain some format
           specifiers which are replaced by the actual values. Accepted format specifiers are `%s` for  subject,
           `%t` for to, `%c` for cc, `%b` for the body of the mail, `%f` for from, `%a` for the patch bundle and
           the same specifiers in uppercase for the URL-encoded values.  Additionally you can add  `%<`  to  the
           end of the command line if the command expects the complete email message on standard input. E.g. the
           command lines for evolution and msmtp look like this:

               evolution "mailto:%T?subject=%S&attach=%A&cc=%C&body=%B"
               msmtp -t %<

           Do not confuse the `--author` options with the return address that `darcs send`  will  set  for  your
           patch bundle.

           For example, if you have two email addresses A and B:

           * If you use `--author A` but your machine is configured to send mail from
             address  B  by default, then the return address on your message will be B.  * If you use `--from A`
           and your mail client supports setting the
             From: address arbitrarily (some non-Unix-like mail clients, especially,
             may not support this), then the return address will be A; if it does
             not support this, then the return address will  be  B.   *  If  you  supply  neither  `--from`  nor
           `--author` then the return
             address will be B.

           In  addition,  unless  you  specify the sendmail command with `--sendmail-command`, darcs sends email
           using the default email command  on  your  computer.  This  default  command  is  determined  by  the
           `configure` script. Thus, on some non-Unix-like OSes, `--from` is likely to not work at all.

       darcs apply <patchfile>
           The `darcs apply` command takes a patch bundle and attempts to insert it into the current repository.
           In addition to invoking it directly on bundles created by `darcs send`,  it  is  used  internally  by
           `darcs push` on the remote end of an SSH connection.

           If no file is supplied, the bundle is read from standard input.

           If  given  an email instead of a patch bundle, Darcs will look for the bundle as a MIME attachment to
           that email.  Currently this will fail if the MIME boundary is  rewritten,  such  as  in  Courier  and
           Mail.app.

           If  the  `--reply  noreply@example.net` option is used, and the bundle is attached to an email, Darcs
           will send a report (indicating success or failure) to the sender of the bundle (the `To` field).  The
           argument to noreply is the address the report will appear to originate FROM.

           The  `--cc`  option  will  cause  the  report  to  be  CC'd  to  another  address,  for example `--cc
           reports@lists.example.net,admin@lists.example.net`.  Using `--cc` without `--reply` is undefined.

           If you want to use a command different from the default one for sending mail, you need to  specify  a
           command line with the `--sendmail-command` option.  The command line can contain the format specifier
           `%t` for to and you can add `%<` to the end of the command line if the command expects  the  complete
           mail on standard input. For example, the command line for msmtp looks like this:

               msmtp -t %<

           If  gpg(1) is installed, you can use `--verify pubring.gpg` to reject bundles that aren't signed by a
           key in `pubring.gpg`.

           If `--test` is supplied and a test is defined (see `darcs setpref`), the bundle will be  rejected  if
           the  test fails after applying it.  In that case, the rejection email from `--reply` will include the
           test output.

           A patch bundle may introduce unresolved conflicts with existing patches or with the working tree.  By
           default, Darcs will add conflict markers (see `darcs mark-conflicts`).

           The  `--external-merge` option lets you resolve these conflicts using an external merge tool.  In the
           option, `%a` is replaced with the common ancestor (merge base), `%1` with  the  first  version,  `%2`
           with  the second version, and `%o` with the path where your resolved content should go.  For example,
           to use the xxdiff visual merge tool you'd specify: `--external-merge='xxdiff -m -O -M %o %1 %a %2'`

           The `--allow-conflicts` option will skip conflict marking; this is useful when you want  to  treat  a
           repository  as  just  a  bunch  of  patches,  such  as using `darcs pull --union` to download of your
           co-workers patches before going offline.

           This can mess up unrecorded changes in  the  working  tree,  forcing  you  to  resolve  the  conflict
           immediately.    To   simply   reject   bundles   that   introduce  unresolved  conflicts,  using  the
           `--dont-allow-conflicts` option.  Making  this  the  default  in  push-based  workflows  is  strongly
           recommended.

           Unlike  most  Darcs  commands,  `darcs apply` defaults to `--all`.  Use the `--interactive` option to
           pick which patches to apply from a bundle.

       darcs clone <repository> [<directory>]
           Clone creates a copy of a repository.  The optional second argument specifies a destination directory
           for the new copy; if omitted, it is inferred from the source location.

           By  default  Darcs  will  copy  every  patch  from  the  original repository.  This means the copy is
           completely independent of the original; you can operate on the new repository even when the  original
           is inaccessible.  If you expect the original repository to remain accessible, you can use `--lazy` to
           avoid copying patches until they are needed (`copy on demand').  This  is  particularly  useful  when
           copying a remote repository with a long history that you don't care about.

           When  cloning  locally, Darcs automatically uses hard linking where possible.  As well as saving time
           and space, this enables to move or delete the original repository without affecting the  copy.   Hard
           linking  requires  that  the  copy be on the same filesystem as the original repository, and that the
           filesystem support hard linking.  This includes NTFS, HFS+ and all general-purpose  Unix  filesystems
           (such as ext, UFS and ZFS). FAT does not support hard links.

           When  cloning  from a remote location, Darcs will look for and attempt to use packs created by `darcs
           optimize http` in the remote repository.  Packs are single big files that can be  downloaded  instead
           of many little files, which makes cloning faster over HTTP.

           Darcs clone will not copy unrecorded changes to the source repository's working tree.

           You can copy a repository to a ssh url, in which case the new repository will always be complete.

           It  is  often  desirable  to make a copy of a repository that excludes some patches.  For example, if
           releases are tagged then `darcs clone --tag .` would make a copy of the repository as at  the  latest
           release.

           An untagged repository state can still be identified unambiguously by a context file, as generated by
           `darcs log --context`.  Given the name  of  such  a  file,  the  `--context`  option  will  create  a
           repository  that  includes  only  the  patches  from  that  context.  When a user reports a bug in an
           unreleased version of your project, the recommended way to find out exactly what  version  they  were
           running is to have them include a context file in the bug report.

           You  can  also make a copy of an untagged state using the `--to-patch` or `--to-match` options, which
           exclude patches *after* the first matching patch.  Because these options treat the set of patches  as
           an ordered sequence, you may get different results after reordering with `darcs optimize`, so tagging
           is preferred.

           The `--set-scripts-executable` option causes scripts to be made executable in  the  working  tree.  A
           script is any file that starts with a shebang ("#!").

   Administrating repositories:
       darcs initialize [<directory>]
           The  `darcs  initialize`  command  turns the current directory into a Darcs repository.  Any existing
           files and subdirectories become UNSAVED changes: record them with `darcs record --look-for-adds`.

           This command creates the `_darcs` directory, which stores version control metadata.  It also contains
           per-repository settings in `_darcs/prefs/`, which you can read about in the user manual.

           By  default,  patches  of the new repository are in the darcs-2 semantics.  However it is possible to
           create a repository in darcs-1 semantics with the flag `--darcs-1`, althought this is not recommended
           except for sharing patches with a project that uses patches in the darcs-1 semantics.

           Initialize is commonly abbreviated to `init`.

       darcs optimize clean
           This command deletes obsolete files within the repository.
       darcs optimize http
           Using this option creates 'repository packs' that could dramatically speed up performance when a user
           does a `darcs clone` of the repository over HTTP. To make use of packs, the clients must have a darcs
           of at least version 2.10.

       darcs optimize reorder
           This command moves recent patches (those not included in the latest tag) to the "front", reducing the
           amount that a typical remote command needs to download.  It should also reduce the  CPU  time  needed
           for some operations.
       darcs optimize enable-patch-index
           Build  the  patch  index, an internal data structure that accelerates commands that need to know what
           patches touch a given file. Such as annotate and log.
       darcs optimize disable-patch-index
           Delete and stop maintaining the patch index from the repository.
       darcs optimize compress
           By default patches are compressed with zlib (RFC 1951) to reduce storage  (and  download)  size.   In
           exceptional   circumstances,   it  may  be  preferable  to  avoid  compression.   In  this  case  the
           `--dont-compress` option can be used (e.g. with `darcs record`) to avoid compression.

           The `darcs optimize uncompress` and `darcs optimize compress` commands can be used to ensure existing
           patches in the current repository are respectively uncompressed or compressed.
       darcs optimize uncompress
           By  default  patches  are  compressed with zlib (RFC 1951) to reduce storage (and download) size.  In
           exceptional  circumstances,  it  may  be  preferable  to  avoid  compression.   In  this   case   the
           `--dont-compress` option can be used (e.g. with `darcs record`) to avoid compression.

           The `darcs optimize uncompress` and `darcs optimize compress` commands can be used to ensure existing
           patches in the current repository are respectively uncompressed or compressed.
       darcs optimize relink
           The `darcs optimize relink` command hard-links patches that the current repository has in common with
           its  peers.   Peers  are  those  repositories  listed  in `_darcs/prefs/sources`, or defined with the
           `--sibling` option (which can be used multiple times).

           Darcs uses hard-links automatically, so this command is rarely needed.  It is most useful if you used
           `cp  -r` instead of `darcs clone` to copy a repository, or if you pulled the same patch from a remote
           repository into multiple local repositories.
       darcs optimize pristine
           This command updates the format of `_darcs/pristine.hashed/`, which was different before darcs 2.3.1.
       darcs optimize upgrade
           Convert old-fashioned repositories to the current default hashed format.
       darcs optimize cache <directory> ...
           This command deletes obsolete files within the global cache.  It takes one  or  more  directories  as
           arguments,  and  recursively  searches all repositories within these directories. Then it deletes all
           files in the global cache not belonging to these  repositories.   When  no  directory  is  given,  it
           searches repositories in the user's home directory.

           It also automatically migrates the global cache to the (default) bucketed format.

       darcs repair
           The  `darcs  repair`  command attempts to fix corruption in the current repository.  Currently it can
           only repair damage to the pristine tree,  which  is  where  most  corruption  occurs.   This  command
           rebuilds a pristine tree by applying successively the patches in the repository to an empty tree.

           The flag `--dry-run` make this operation read-only, making darcs exit unsuccessfully (with a non-zero
           exit status) if the rebuilt pristine is different from the current pristine.

       darcs convert darcs-2 <source> [<destination>]
           This command converts a repository that uses the old patch semantics `darcs-1` to  a  new  repository
           with current `darcs-2` semantics.

           WARNING:  the  repository produced by this command is not understood by Darcs 1.x, and patches cannot
           be exchanged between repositories in darcs-1 and darcs-2 formats.

           Furthermore, repositories created by different  invocations  of  this  command  SHOULD  NOT  exchange
           patches.

       darcs convert export
           This command enables you to export darcs repositories into git.

           For a one-time export you can use the recipe:

               $ cd repo
               $ git init ../mirror
               $ darcs convert export | (cd ../mirror && git fast-import)

           For incremental export using marksfiles:

               $ cd repo
               $ git init ../mirror
               $ touch ../mirror/git.marks
               $ darcs convert export --read-marks darcs.marks --write-marks darcs.marks
                  | (cd ../mirror && git fast-import --import-marks=git.marks --export-marks=git.marks)

           In the case of incremental export, be careful to never amend, delete or reorder patches in the source
           darcs repository.

           Also, be aware that exporting a darcs repo to git will not be exactly faithful in terms of history if
           the darcs repository contains conflicts.

           Limitations:

           * Empty directories are not supported by the fast-export protocol.  * Unicode filenames are currently
           not correctly handled.
             See http://bugs.darcs.net/issue2359 .

       darcs convert import [<directory>]
           This command imports git repositories into new darcs repositories.  Further options are accepted (see
           `darcs help init`).

           To convert a git repo to a new darcs one you may run:
               $ (cd gitrepo && git fast-export --all) | darcs convert import darcsmirror

           WARNING: git repositories with branches will produce weird results,
                    use at your own risks.

           Incremental import with marksfiles is currently not supported.

       darcs rebase pull [repository]...
           Copy and apply patches from another repository, suspending any local patches that conflict.
       darcs rebase apply <patchfile>
           Apply a patch bundle, suspending any local patches that conflict.
       darcs rebase suspend
           Select patches to move into a suspended state at the end of the repo.

       darcs rebase unsuspend
           Selected patches to restore from a suspended state to the end of the repo.

       darcs rebase obliterate
           Obliterate a patch that is currently suspended.

       darcs rebase log
           List the currently suspended changes.

ENVIRONMENT

   HOME and APPDATA
       Per-user preferences are set in $HOME/.darcs (on Unix) or %APPDATA%/darcs (on Windows).  This is also the
       default location of the cache.

   DARCS_EDITOR, DARCSEDITOR, VISUAL and EDITOR
       To edit a patch description of email comment, Darcs will  invoke  an  external  editor.   Your  preferred
       editor  can  be  set as any of the environment variables $DARCS_EDITOR, $DARCSEDITOR, $VISUAL or $EDITOR.
       If none of these are set, editor(1) is used.

   DARCS_PAGER and PAGER
       Darcs will sometimes invoke a pager if it deems output to be too long to fit onscreen.   Darcs  will  use
       the pager specified by $DARCS_PAGER or $PAGER.  If neither are set, pager(1) will be used.

   DARCS_DONT_COLOR, DARCS_ALWAYS_COLOR, DARCS_ALTERNATIVE_COLOR and DARCS_DO_COLOR_LINES
       If  the  terminal  understands  ANSI  color  escape  sequences, darcs will highlight certain keywords and
       delimiters  when  printing  patches.  This  can  be  turned  off  by  setting  the  environment  variable
       DARCS_DONT_COLOR  to  1. If you use a pager that happens to understand ANSI colors, like `less -R`, darcs
       can be forced always to highlight the output by setting DARCS_ALWAYS_COLOR to 1. If you can't see  colors
       you  can  set  DARCS_ALTERNATIVE_COLOR  to  1,  and  darcs will use ANSI codes for bold and reverse video
       instead of colors. In addition, there is an extra-colorful mode, which is not enabled by  default,  which
       can be activated with DARCS_DO_COLOR_LINES

   DARCS_DONT_ESCAPE_TRAILING_SPACES and DARCS_DONT_ESCAPE_TRAILING_CR
       By  default  darcs  will escape (by highlighting if possible) any kind of spaces at the end of lines when
       showing  patch   contents.    If   you   don't   want   this   you   can   turn   it   off   by   setting
       DARCS_DONT_ESCAPE_TRAILING_SPACES   to   1.   A   special   case   exists   for  only  carriage  returns:
       DARCS_DONT_ESCAPE_TRAILING_CR

   DARCS_DONT_ESCAPE_ANYTHING, DARCS_DONT_ESCAPE_ISPRINT,  DARCS_DONT_ESCAPE_8BIT,  DARCS_DONT_ESCAPE_EXTRA  and
       DARCS_ESCAPE_EXTRA
       Darcs  needs  to  escape  certain  characters when printing patch contents to a terminal. Characters like
       backspace can otherwise hide patch content from the user, and other character sequences can even in  some
       cases redirect commands to the shell if the terminal allows it.

       By  default darcs will only allow printable 7-bit ASCII characters (including space), and the two control
       characters tab and newline. All other octets are printed in quoted form (as `^<control letter>` or `\<hex
       code>`).

       Darcs  has  some limited support for locales. If the system's locale is a single-byte character encoding,
       like the Latin encodings, you can set the environment variable DARCS_DONT_ESCAPE_ISPRINT to 1  and  darcs
       will  display  all the printables in the current system locale instead of just the ASCII ones. NOTE: This
       curently does not work on some architectures if darcs is compiled with GHC 6.4 or later.  Some  non-ASCII
       control characters might be printed and can possibly spoof the terminal.

       For   multi-byte   character   encodings   things   are   less   smooth.  UTF-8  will  work  if  you  set
       DARCS_DONT_ESCAPE_8BIT to 1, but non-printables outside the 7-bit ASCII  range  are  no  longer  escaped.
       E.g.,  the  extra  control  characters  from  Latin-1 might leave your terminal at the mercy of the patch
       contents. Space characters outside the 7-bit ASCII range  are  no  longer  recognized  and  will  not  be
       properly escaped at line endings.

       As a last resort you can set DARCS_DONT_ESCAPE_ANYTHING to 1. Then everything that doesn't flip code sets
       should work, and so will all the bells and whistles in your terminal. This environment variable can  also
       be  handy if you pipe the output to a pager or external filter that knows better than darcs how to handle
       your encoding. Note that all escaping, including the special escaping of any line ending spaces, will  be
       turned off by this setting.

       There  are two environment variables you can set to explicitly tell darcs to not escape or escape octets.
       They are DARCS_DONT_ESCAPE_EXTRA and DARCS_ESCAPE_EXTRA. Their values should be strings consisting of the
       verbatim  octets  in question. The do-escapes take precedence over the dont-escapes. Space characters are
       still escaped at line endings though.  The  special  environment  variable  DARCS_DONT_ESCAPE_TRAILING_CR
       turns off escaping of carriage return last on the line (DOS style).

   DARCS_TMPDIR and TMPDIR
       Darcs  often  creates  temporary  directories.  For example, the `darcs diff` command creates two for the
       working trees to be diffed.  By default temporary directories are created in /tmp,  or  if  that  doesn't
       exist, in _darcs (within the current repo).  This can be overridden by specifying some other directory in
       the file _darcs/prefs/tmpdir or the environment variable $DARCS_TMPDIR or $TMPDIR.

   DARCS_KEEP_TMPDIR
       If the environment variable DARCS_KEEP_TMPDIR is defined, darcs will not remove the temporary directories
       it  creates.   This  is  intended  primarily  for  debugging Darcs itself, but it can also be useful, for
       example, to determine why your test preference (see `darcs setpref`)  is  failing  when  you  run  `darcs
       record`, but working when run manually.

   DARCS_EMAIL and EMAIL
       Each  patch  is  attributed  to  its  author,  usually  by  email  address  (for  example,  `Fred  Bloggs
       <fred@example.net>`).  Darcs looks in several places for this author string: the `--author`  option,  the
       files  `_darcs/prefs/author`  (in the repository) and `~/.darcs/author` (in your home directory), and the
       environment variables `$DARCS_EMAIL` and `$EMAIL`.  If none of those exist, Darcs will prompt you for  an
       author  string and write it to `~/.darcs/author`.  Note that if you have more than one email address, you
       can put them all in `~/.darcs/author`, one author per line.  Darcs will still prompt you for  an  author,
       but it allows you to select from the list, or to type in an alternative.

   SENDMAIL
       On  Unix,  the  `darcs  send`  command  relies  on  sendmail(8).   The  `--sendmail-command` or $SENDMAIL
       environment variable can be used to provide an explicit path to  this  program;  otherwise  the  standard
       locations /usr/sbin/sendmail and /usr/lib/sendmail will be tried.

   DARCS_SLOPPY_LOCKS
       If on some filesystems you get an error of the kind:

           darcs: takeLock [...]: atomic_create [...]: unsupported operation

       you may want to try to export DARCS_SLOPPY_LOCKS=True.

   DARCS_SSH
       Repositories of the form [user@]host:[dir] are taken to be remote repositories, which Darcs accesses with
       the external program ssh(1).

       The environment variable $DARCS_SSH can be used to specify an alternative SSH client.  Arguments  may  be
       included,  separated  by whitespace.  The value is not interpreted by a shell, so shell constructs cannot
       be used; in particular, it is not possible for the program name to contain whitespace by using quoting or
       escaping.

   DARCS_SCP and DARCS_SFTP
       When  reading  from  a  remote  repository, Darcs will attempt to run `darcs transfer-mode` on the remote
       host.  This will fail if the remote host only has Darcs 1 installed, doesn't have Darcs installed at all,
       or only allows SFTP.

       If  transfer-mode  fails,  Darcs  will  fall  back  on  scp(1)  and sftp(1).  The commands invoked can be
       customized with the environment variables $DARCS_SCP and  $DARCS_SFTP  respectively,  which  behave  like
       $DARCS_SSH.  If the remote end allows only sftp, try setting DARCS_SCP=sftp.

   SSH_PORT
       If  this  environment variable is set, it will be used as the port number for all SSH calls made by Darcs
       (when accessing remote repositories over SSH).  This is useful if your SSH server does  not  run  on  the
       default  port, and your SSH client does not support ssh_config(5).  OpenSSH users will probably prefer to
       put something like `Host *.example.net Port 443` into their ~/.ssh/config file.

   HTTP_PROXY, HTTPS_PROXY, FTP_PROXY, ALL_PROXY and NO_PROXY
       If Darcs was built with libcurl, the environment variables HTTP_PROXY, HTTPS_PROXY and FTP_PROXY  can  be
       set to the URL of a proxy in the form

           [protocol://]<host>[:port]

       In  which  case  libcurl  will  use  the  proxy  for  the  associated protocol (HTTP, HTTPS and FTP). The
       environment variable ALL_PROXY can be used to set a single proxy for all libcurl requests.

       If the environment variable NO_PROXY is a comma-separated list of host names, access to those hosts  will
       bypass proxies defined by the above variables. For example, it is quite common to avoid proxying requests
       to machines on the local network with

           NO_PROXY=localhost,*.localdomain

       For  compatibility  with  lynx  et  al,  lowercase  equivalents  of  these  environment  variables  (e.g.
       $http_proxy) are also understood and are used in preference to the uppercase versions.

       If  Darcs  was not built with libcurl, all these environment variables are silently ignored, and there is
       no way to use a web proxy.

   DARCS_PROXYUSERPWD
       If Darcs was built with libcurl, and you are using a web proxy that requires authentication, you can  set
       the  $DARCS_PROXYUSERPWD  environment  variable  to  the  username  and  password  expected by the proxy,
       separated by a colon.  This environment variable is silently ignored if Darcs was not built with libcurl.

   DARCS_GET_FOO and DARCS_APPLY_FOO
       When trying to access a repository with a URL beginning foo://, darcs will invoke the  program  specified
       by  the  DARCS_GET_FOO environment variable (if defined) to download each file, and the command specified
       by the DARCS_APPLY_FOO environment variable (if defined) when pushing to a foo:// URL.

       This method overrides all other ways of getting `foo://xxx` URLs.

       Note that each command should be constructed so that it sends the downloaded content to STDOUT,  and  the
       next argument to it should be the URL.  Here are some examples that should work for DARCS_GET_HTTP:

           fetch -q -o -
           curl -s -f
           lynx -source
           wget -q -O -

       Apart  from  such toy examples, it is likely that you will need to manipulate the argument before passing
       it to the actual fetcher program.  For example,  consider  the  problem  of  getting  read  access  to  a
       repository on a CIFS (SMB) share without mount privileges:

           export DARCS_GET_SMB='smbclient -c get'
           darcs get smb://fs/twb/Desktop/hello-world

       The  above  command will not work for several reasons.  Firstly, Darcs will pass it an argument beginning
       with `smb:`, which smbclient does not understand.  Secondly,  the  host  and  share  `//fs/twb`  must  be
       presented  as  a  separate  argument to the path `Desktop/hello-world`.  Thirdly, smbclient requires that
       `get` and the path be a single  argument  (including  a  space),  rather  than  two  separate  arguments.
       Finally,  smbclient's  `get`  command  writes  the  file to disk, while Darcs expects it to be printed to
       standard output.

       In principle, we could get  around  such  problems  by  making  the  variable  contain  a  shell  script,
       unfortunately,  Darcs  splits  the  command  on whitespace and does not understand quotation or escaping.
       Therefore, we instead need to put commands in separate, executable scripts.

       Continuing our smbclient example, we create an  executable  script  `~/.darcs/libexec/get_smb`  with  the
       following contents:

           #!/bin/bash -e
           IFS=/ read host share file <<<'${1#smb://}'
           smbclient //$host/$share -c 'get $file -'

       And at last we can say

           export DARCS_GET_SMB=~/.darcs/libexec/get_smb
           darcs get smb://fs/twb/Desktop/hello-world

       The APPLY command will be called with a darcs patchfile piped into its standard input.

   DARCS_CONNECTION_TIMEOUT
       Set  the  maximum  time  in  seconds  that  darcs  allows  and connection to take. If the variable is not
       specified the default are 30 seconds. This option only works with curl.

FILES

   _darcs/prefs/binaries
       This file contains a list of extended regular expressions, one per line.  A file  path  matching  any  of
       these  expressions  is assumed to contain binary data (not text). The entries in ~/.darcs/binaries (if it
       exists) supplement those in this file.

       Blank lines, and lines beginning with an octothorpe (#) are ignored.  See regex(7) for a  description  of
       extended regular expressions.

   _darcs/prefs/boring
       This  file  contains  a  list  of extended regular expressions, one per line. A file path matching any of
       these expressions will be filtered out during `darcs add', or when the `--look-for-adds' flag  is  passed
       to  `darcs whatsnew' and `record'. The entries in ~/.darcs/boring (if it exists) supplement those in this
       file.

       Blank lines, and lines beginning with an octothorpe (#) are ignored.  See regex(7) for a  description  of
       extended regular expressions.

BUGS

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

SEE ALSO

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

LICENSE

       Darcs is free software; you can redistribute it and/or modify it under  the  terms  of  the  GNU  General
       Public  License  as  published by the Free Software Foundation; either version 2, or (at your option) any
       later version.

                                                2.10.2 (release)                                        DARCS(1)