Configuring darcs
Keywords: darcs

Subsections

- prefs
  - defaults
  - repos
  - author
  - boring
  - binaries
- Environment variables
  - DARCS_EMAIL
  - DARCS_EDITOR
  - DARCS_TMPDIR
  - HOME
  - TERM
  - SSH_PORT
  - DARCS_SSH
  - DARCS_SCP and DARCS_SFTP
  - DARCS_PROXYUSERPWD
  - DARCS_USE_ISPRINT
  - DARCS_GET_FOO, DARCS_MGET_FOO and DARCS_APPLY_FOO
  - DARCS_MGETMAX
  - DARCS_WGET

#
Configuring darcs

There are sevaral ways you can adjust darcs' behavior to suit your needs. The first is to edit files in the `_darcs/prefs/` directory of a repository. Such configuration only applies when working with that repository. To configure darcs on a per-user rather than per-repository basis (but with essentially the same methods), you can edit (or create) files in the `~/.darcs/` directory. Finally, the behavior of some darcs commands can be modified by setting appropriate environment variables.

# prefs

The `_darcs` directory contains a `prefs` directory. This directory exists simply to hold user configuration settings specific to this repository. The contents of this directory are intended to be modifiable by the user, although in some cases a mistake in such a modification may cause darcs to behave strangely.

####
defaults

Default values for darcs commands can be configured on a per-repository basis by editing (and possibly creating) the `_darcs/prefs/defaults` file. Each line of this file has the following form:

    COMMAND FLAG VALUE

where `COMMAND` is either the name of the command to which the default applies, or `ALL` to indicate that the default applies to all commands accepting that flag. The `FLAG` term is the name of the long argument option without the ```--`'', i.e. `verbose` rather than `--verbose`. Finally, the `VALUE` option can be omitted if the flag is one such as `verbose` that doesn't involve a value. Each line only takes one flag. To set multiple defaults for the same command (or for `ALL` commands), use multiple lines.

``~/.darcs/defaults`` | `provides defaults for this user account`
``project/_darcs/pref/defaults`` | `provides defaults for one project, overrules changes per user`

For example, if your system clock is bizarre, you could instruct darcs to always ignore the file modification times by adding the following line to your `_darcs/prefs/defaults` file. (Note that this would have to be done for each repository!)

    ALL ignore-times

If you never want to run a test when recording to a particular repository (but still want to do so when running check on that repo), and like to name all your patches ``Stupid patch'', you could use the following:

    record no-test
    record patch-name Stupid patch

There are some options which are meant specifically for use in `_darcs/prefs/defaults`. One of them is `--disable`. As the name suggests, this option will disable every command that got it as argument. So, if you are afraid that you could damage your repositories by inadvertant use of a command like amend-record, add the following line to `_darcs/prefs/defaults`:

    amend-record disable

Also, a global preferences file can be created with the name `.darcs/defaults` in your home directory. Options present there will be added to the repository-specific preferences. If they conflict with repository-specific options, the repository-specific ones will take precedence.

#### repos

The `_darcs/prefs/repos` file contains a list of repositories you have pulled from or pushed to, and is used for autocompletion of pull and push commands in bash. Feel free to delete any lines from this list that might get in there, or to delete the file as a whole.

####
author

The `_darcs/prefs/author` file contains the email address (or name) to be used as the author when patches are recorded in this repository, e.g. ``David Roundy <droundy@abridgegame.org>''. This file overrides the contents of the environment variables `$DARCS_EMAIL` and `$EMAIL`.

#### boring

The `_darcs/prefs/boring` file may contain a list of regular expressions describing files, such as object files, that you do not expect to add to your project. As an example, the boring file that I use with my darcs repository is:

    \.hi$
    \.o$
    ^\.[^/]
    ^_
    ~$
    (^|/)CVS($|/)

The last line is actually irrelevant because I don't use CVS, but if I did it would be handy. A newly created repository has a longer boring file that includes many common source control, backup, temporary, and compiled files.

You may want to have the boring file under version control. To do this you can use darcs setpref to set the value ``boringfile'' to the name of your desired boring file (e.g. ``darcs setpref boringfile .boring'', where .boring is the repository path of a file that has been darcs added to your repository). The boringfile pref overrides `_darcs/prefs/boring`, so be sure to copy that file to the boringfile.

You can also set up a ``boring'' regexps file in your home directory, named `~/.darcs/boring`, which will be used with all of your darcs repositories.

Any file whose repository path (such as `manual/index.html`) matches any of the boring regular expressions is considered boring. The boring file is used to filter the files provided to darcs add, to allow you to use a simple ``darcs add newdir newdir/*'' without accidentally adding a bunch of object files. It is also used when the `--look-for-adds` flag is given to whatsnew or record.

#### binaries

The `_darcs/prefs/binaries` file may contain a list of regular expressions describing files that should be treated as binary files rather than text files. You probably will want to have the binaries file under version control. To do this you can use darcs setpref to set the value ``binariesfile'' to the name of your desired binaries file (e.g. ``darcs setpref binariesfile ./.binaries'', where .binaries is a file that has been darcs added to your repository). As with the boring file, you can also set up a `~/.darcs/binaries` file if you like.

# Environment variables

There are a few environment variables whose contents affect darcs' behavior.

#### DARCS_EMAIL

The DARCS_EMAIL environment variable determines the ``author'' name used by darcs when recording if no `_darcs/prefs/author` exists. If DARCS_EMAIL is undefined, the contents of the EMAIL environment variable are used.

#### DARCS_EDITOR

When pulling up an editor (for example, when adding a long comment in record), darcs uses the contents of DARCS_EDITOR if it is defined. If not, it tries the contents of VISUAL, and if that isn't defined (or fails for some reason), it tries EDITOR. If none of those environment variables are defined, darcs tries `vi`, `emacs`, `emacs -nw` and `nano` in that order.

#### DARCS_TMPDIR

If the environment variable DARCS_TMPDIR is defined, darcs will use that directory for its temporaries. Otherwise it will use TMPDIR, if that is defined, and if not that then `/tmp` and if `/tmp` doesn't exist, it'll put the temporaries in `_darcs`.

This is very helpful, for example, when recording with a test suite that uses MPI, in which case using `/tmp` to hold the test copy is no good, as `/tmp` isn't shared over NFS and thus the `mpirun` call will fail, since the binary isn't present on the compute nodes.

#### HOME

HOME is used to find the per-user prefs directory, which is located at `$HOME/.darcs`.

#### TERM

If darcs is compiled with libcurses support and support for color output, it uses the environment variable TERM to decide whether or not color is supported on the output terminal.

#### SSH_PORT

When using ssh, if the SSH_PORT environment variable is defined, darcs will use that port rather than the default ssh port (which is 22).

####
DARCS_SSH

The DARCS_SSH environment variable defines the command that darcs will use when asked to run ssh. This command is not interpreted by a shell, so you cannot use shell metacharacters, and the first word in the command must be the name of an executable located in your path.

#### DARCS_SCP and DARCS_SFTP

The DARCS_SCP and DARCS_SFTP environment variables define the commands that darcs will use when asked to run scp or sftp. Note that scp and sftp is how darcs accesses repositories whose URL is of the form `user@foo.org:foo` or `foo.org:foo`. Darcs will use scp to copy single files (e.g. repository meta-information), and sftp to copy multiple files in batches (e.g. patches). These commands are not interpreted by a shell, so you cannot use shell metacharacters, and the first word in the command must be the name of an executable located in your path.

#### DARCS_PROXYUSERPWD

This environment variable allows DARCS and libcurl to access remote repositories via a password-protected HTTP proxy. The proxy itself is specified with the standard environment variable for this purpose, namely 'http_proxy'. The DARCS_PROXYUSERPWD environment variable specifies the proxy username and password. It must be given in the form username:password.

#### DARCS_USE_ISPRINT

There is currently no way to specify the character encoding of a darcs repository, so darcs will by default print everything that is not printable ASCII characters as hexadecimal escape codes. This protects the terminal from (possibly malicious) control codes.

If the repository is encoded in the system's locale and it is an 8-bit, single-byte encoding, (e.g. ISO 8859-1), darcs can use the library function `isPrint` to check for printable characters, including non-ASCII. Setting the environment variable DARCS_USE_ISPRINT=1 enables this. It does not work for multi-byte encodings like UTF-8.

#### DARCS_GET_FOO, DARCS_MGET_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
    lynx -source
    wget -q -O -

If set, DARCS_MGET_FOO will be used to fetch many files from a single repository simultaneously. Replace FOO and foo as appropriate to handle other URL schemes. These commands are not interpreted by a shell, so you cannot use shell metacharacters, and the first word in the command must be the name of an executable located in your path. The GET command will be called with a url for each file, the MGET command will be invoked with a number of urls and is expected to download the files to the current directory, preserving the filename but not the path, the APPLY command will be called with a darcs patchfile piped into its standard input. Example:

    wget -q

#### DARCS_MGETMAX

When invoking a DARCS_MGET_FOO command, darcs will limit the number of urls presented to the command to the value of this variable, if set, or 200.

#### DARCS_WGET

This is a very old option that is only used if libcurl is not compiled in and one of the `DARCS_GET_FOO` is not used. Using one of those is recommended instead.

The DARCS_WGET environment variable defines the command that darcs will use to fetch all URLs for remote repositories. The first word in the command must be the name of an executable located in your path. Extra arguments can be included as well, such as:

    wget -q

Darcs will append `-i` to the argument list, which it uses to provide a list of URLS to download. This allows wget to download multiple patches at the same time. It's possible to use another command besides `wget` with this environment variable, but it must support the `-i` option in the same way.

These commands are not interpreted by a shell, so you cannot use shell meta-characters.