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.
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.
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 VALUEwhere
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.
_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.
_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
.
_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.
_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.
There are a few environment variables whose contents affect darcs' behavior.
_darcs/prefs/author
exists. If
DARCS_EMAIL is undefined, the contents of the EMAIL environment variable
are used.
vi
, emacs
, emacs -nw
and
nano
in that order.
/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/.darcs
.
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.
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.
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_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.
David Roundy 2005-02-04