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. See also Windows.

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.

The configuration files can be split in three categories:

• remote prefs:
  • motd
  • email
  • post
• local prefs:
  • author
  • defaults
  • sources
  • boring
  • binaries
  • defaultrepo
  • tmpdir
• internal metadata:
  • prefs

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 does not 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 did not in previous versions. A command like obliterate could be devastating with the “wrong” flags (for example –all). Only use safe flags with ALL.

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:

• Without the second line you will get errors, because the sub process that runs apply cannot prompt interactively.

• Whatever script is run by the post apply command should not be added to the repository with darcs add; doing so would allow people to modify that file and then run arbitrary scripts on your main repository, possibly damaging or violating security.

  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, add the following line to _darcs/prefs/defaults:

amend 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, 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, which will be used with all of your darcs repositories.

Any file not already managed by darcs and whose repository path 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.

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. This file contains lines such as:

cache:/home/droundy/.cache/darcs
readonly:/home/otheruser/.cache/darcs
repo:http://darcs.net

This would indicate that darcs should first look in /home/droundy/.cache/darcs for patches that might be missing, and if the patch is not there, it should save a copy there for future use. In that case, darcs will look in /home/otheruser/.cache/darcs to see if that user might have downloaded a copy, but will not 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 clone 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 clone or pull from the repository without the --quiet option.

post

If _darcs/prefs/post exists in the target repository, darcs send 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.

tmpdir

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.

defaultrepo

Contains the URL of the default remote repository used by commands pull, push, send and optimize relink. Darcs handles this file automatically or when the flag --set-default is used.

prefs

Contains the preferences set by the command darcs setprefs. Do not edit manually.