next up previous contents
Next: Best practices Up: Darcs User Manual Previous: Getting started   Contents

Subsections


Configuring darcs

There are several 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.


Microsoft Windows

The global darcs directory is %APPDATA%\darcs\. This typically expands to C:\Documents And Settings\user\Application Data\darcs\. This folder contains the cache, as well as all the per-user settings files: preferences, boring etc... These will became the new defaults that can be overridden on per-repository basis.

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. If the value has spaces in it, use single quotes, not double quotes, to surround it. Each line only takes one flag. To set multiple defaults for the same command (or for ALL commands), use multiple lines.

Note that the use of ALL easily can have unpredicted consequences, especially if commands in newer versions of darcs accepts flags that they didn't in previous versions. A command like obliterate could be devastating with the ``wrong'' flags (for example -all). Only use safe flags with ALL.

~/.darcs/defaults provides defaults for this user account (for MS Windows, see [*])
repo/_darcs/prefs/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 repository), and like to name all your patches ``Stupid patch'', you could use the following:

record no-test
record patch-name Stupid patch

If you would like a command to be run every time patches are recorded in a particular repository (for example if you have one central repository, that all developers contribute to), then you can set apply to always run a command when apply is successful. For example, if you need to make sure that the files in the repository have the correct access rights you might use the following. There are two things to note about using darcs this way:

apply posthook chmod -R a+r *
apply run-posthook

Similarly, if you need a command to run automatically before darcs performs an action you can use a prehook. Using prehooks it could be possible to canonicalize line endings before recording patches.

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 inadvertent 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, on MS Windows [*]. 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, you could have:
\.hi$
\.o$
^\.[^/]
^_
~$
(^|/)CVS($|/)
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 preference 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, (see [*] on MS Windows), which will be used with all of your darcs repositories.

Any file not already managed by darcs and 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. Note that once a file has been added to darcs, it is not considered boring, even if it matches the boring file filter.

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. Darcs automatically treats files containing ^Z\ or '\0' within the first 4096 bytes as being binary 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 (see [*] on MS Windows).

email

The _darcs/prefs/email file is used to provide the e-mail address for your repository that others will use when they darcs send a patch back to you. The contents of the file should simply be an e-mail address.

sources

The _darcs/prefs/sources file is used to indicate alternative locations from which to download patches when using a ``hashed'' repository. This file contains lines such as:
cache:/home/droundy/.darcs/cache
readonly:/home/otheruser/.darcs/cache
repo:http://darcs.net
This would indicate that darcs should first look in /home/droundy/.darcs/cache for patches that might be missing, and if the patch isn't there, it should save a copy there for future use. In that case, darcs will look in /home/otheruser/.darcs/cache to see if that user might have downloaded a copy, but won't try to save a copy there, of course. Finally, it will look in http://darcs.net. Note that the sources file can also exist in ~/.darcs/. Also note that the sources mentioned in your sources file will be tried before the repository you are pulling from. This can be useful in avoiding downloading patches multiple times when you pull from a remote repository to more than one local repository.

A global cache is enabled by default in your home directory. The cache allows darcs to avoid re-downloading patches (for example, when doing a second darcs get of the same repository), and also allows darcs to use hard links to reduce disk usage.

Note that the cache directory should reside on the same filesystem as your repositories, so you may need to vary this. You can also use multiple cache directories on different filesystems, if you have several filesystems on which you use darcs.


motd

The _darcs/prefs/motd file may contain a ``message of the day'' which will be displayed to users who get or pull from the repository without the --quiet option.

Environment variables

There are a few environment variables whose contents affect darcs' behavior. Here is a quick list of all the variables and their documentation in the rest of the manual:

Variable Section
DARCS_EDITOR, EDITOR, VISUAL [*]
DARCS_PAGER, PAGER [*]
HOME [*]
TERM [*]
DARCS_EMAIL, EMAIL [*]
DARCS_APPLY_FOO [*]
DARCS_GET_FOO [*]
DARCS_MGET_FOO [*]
DARCS_MGETMAX [*]
DARCS_PROXYUSERPWD [*]
DARCS_CONNECTION_TIMEOUT [*]
DARCS_SSH [*]
DARCS_SCP [*]
DARCS_SFTP [*]
SSH_PORT [*]
DARCS_ALTERNATIVE_COLOR [*]
DARCS_ALWAYS_COLOR [*]
DARCS_DO_COLOR_LINES [*]
DARCS_DONT_COLOR [*]
DARCS_DONT_ESCAPE_TRAILING_CR [*]
DARCS_DONT_ESCAPE_TRAILING_SPACES [*]
DARCS_DONT_ESCAPE_8BIT [*]
DARCS_DONT_ESCAPE_ANYTHING [*]
DARCS_DONT_ESCAPE_ISPRINT [*]
DARCS_ESCAPE_EXTRA [*]
DARCS_DONT_ESCAPE_EXTRA [*]

General-purpose variables


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, vi(1) is used. If vi crashes or is not found in your PATH, emacs, emacs -nw, nano and (on Windows) edit are each tried in turn.


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, `less' will be used.


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.


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.

Remote repositories


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.


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, 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 -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, e.g.

export DARCS_GET_SMB='sh -c "...; smbclient $x -c \"get $y\""'

Unfortunately, Darcs splits the command on whitespace and does not understand that quotation or escaping, so there is no way to make Darcs pass the text after `-c' to sh as a single argument. Therefore, we instead need to put such one-liners 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

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 file name 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.

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


Highlighted output

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.

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.


Character escaping and non-ASCII character encodings

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. (See the last paragraph in this section for a way to tailor this behavior.) 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).


next up previous contents
Next: Best practices Up: Darcs User Manual Previous: Getting started   Contents
Daniil 2014-02-06