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-record [file|directory]...
darcs mark-conflicts
darcs tag [tagname]
darcs setpref <pref> <value>
darcs diff [file|directory]...
darcs changes [file|directory]...
darcs annotate [file|directory]...
darcs dist
darcs trackdown [[initialization] command]
darcs show contents [file]...
darcs show files
darcs show index
darcs show pristine
darcs show repo
darcs show authors
darcs show tags
darcs pull [repository]...
darcs obliterate
darcs rollback [file|directory]...
darcs push [repository]
darcs send [repository]
darcs apply <patchfile>
darcs get <repository> [<directory>]
darcs put <new repository>
darcs initialize
darcs optimize
darcs check
darcs repair
darcs convert <source> [<destination>]
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’
--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.
hash - match the darcs hash 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 ’hash
20040403105958-53a90-c719567e92c3b0ab9eddd5290b705712b8b918ef’
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!
The --date-trick option allows you to enable an experimental trick
to make add conflicts, in which two users each add a file or
directory with the same name, less problematic. While this trick
is completely safe, it is not clear to what extent it is
beneficial.
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’).
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.
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.
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 by default (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\t] declares all characters except
the space, tab and newline as valid within a word. Unlike the
tr(1) and grep(1) utilities, character classes (such as
[[:alnum:]]) are NOT supported.
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.
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.
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]...
Record is used to name a set of changes and record the patch to the
repository.
darcs unrecord
Unrecord does the opposite of record in that it makes the changes
from patches active changes again which you may record or revert
later. The working copy itself will not change. Beware that you
should not use this command if you are going to re-record the
changes in any way and there is a possibility that another user may
have already pulled the patch.
darcs amend-record [file|directory]...
Amend-record updates a ‘draft’ patch with additions or
improvements, resulting in a single ‘finished’ patch. This is
better than recording the additions and improvements as separate
patches, because then whenever the ‘draft’ patch is copied between
repositories, you would need to make sure all the extra patches are
copied, too.
Do not copy draft patches between repositories, because a finished
patch cannot be copied into a repository that contains a draft of
the same patch. If this has already happened, ‘darcs obliterate’
can be used to remove the draft patch.
Do not run amend-record in repository that other developers can
pull from, because if they pull while an amend-record is in
progress, their repository may be corrupted.
When recording a draft patch, it is a good idea to start the name
with ‘DRAFT:’ so that other developers know it is not finished.
When finished, remove it with ‘darcs amend-record
--edit-long-comment’. To change the patch name without starting an
editor, use --patch-name.
Like ‘darcs record’, if you call amend-record 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-record --match ’touch foo.c’ bar.c
It is usually a bad idea to amend another developer’s patch. To
make amend-record only ask about your own patches by default, you
can add something like ‘amend-record match David Roundy’ to
~/.darcs/defaults, where ‘David Roundy’ is your name. On Windows
use C:/Documents And Settings/user/Application Data/darcs/defaults
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 both
choices to the working tree, delimited by the markers ‘v v v’, ‘* *
*’ and ‘^ ^ ^’.
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 any unresolved conflicts.
It is also useful if ‘darcs apply’ is called with
--apply-conflicts, where conflicts aren’t marked initially.
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.
This command was historically called ‘resolve’, and this deprecated
alias still exists for backwards-compatibility.
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 get --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.
The ‘darcs tag’ command accepts the --pipe and --checkpoint
options, which behave as described in ‘darcs record’ and ‘darcs
optimize’ respectively.
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]...
Diff can be used to create a diff between two versions which are in
your repository. Specifying just --from-patch will get you a diff
against your working copy. If you give diff no version arguments,
it gives you the same information as whatsnew except that the patch
is formatted as the output of a diff command
darcs changes [file|directory]...
Changes gives a changelog-style summary of the repository history,
including options for altering how the patches are selected and
displayed.
darcs annotate [file|directory]...
Annotate displays which patches created or last modified a
directory file or line. It can also display the contents of a
particular patch in darcs format.
darcs dist
The ‘darcs dist’ command creates a compressed archive (a ‘tarball’)
in the repository’s root directory, containing the recorded state
of the working tree (unrecorded changes and the _darcs directory
are excluded).
If a predist command is set (see ‘darcs setpref’), that command
will be run on the tarball contents prior to archiving. For
example, autotools projects would set it to ‘autoconf && automake’.
By default, the tarball (and the top-level directory within the
tarball) has the same name as the repository, but this can be
overridden with the --dist-name option.
darcs trackdown [[initialization] command]
Trackdown tries to find the most recent version in the repository
which passes a test. Given no arguments, it uses the default
repository test. Given one argument, it treats it as a test
command. Given two arguments, the first is an initialization
command with is run only once, and the second is the test command.
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
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 aroudn 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 pristine’ command is an alias for ‘darcs index’. 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 repo command displays information about the current repository
(location, type, etc.). Some of this information is already
available by inspecting files within the _darcs directory and some
is internal information that is informational only (i.e. for
developers). This command collects all of the repository
information into a readily available source.
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 and zero or more extended
regular expressions, separated by commas. Blank lines and lines
beginning with two hyphens, are ignored.
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).
Currently this canonicalization step is done only in ‘darcs show
authors’. Other commands, such as ‘darcs changes’ 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
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.
Copying patches between repositories with working copy update:
darcs pull [repository]...
Pull is used to bring changes 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.
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!
darcs rollback [file|directory]...
Rollback is used to undo the effects of one or more patches without
actually deleting them. Instead, it creates a new patch reversing
selected portions. of those changes. Unlike obliterate and
unrecord (which accomplish a similar goal) rollback is perfectly
safe, since it leaves in the repository a record of its changes.
darcs push [repository]
Push is the opposite of pull. Push allows you to copy changes from
the current repository into another repository.
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 sent by email, although you
may save it to a file.
darcs apply <patchfile>
Apply is used to apply a bundle of patches to this repository.
Such a bundle may be created using send.
darcs get <repository> [<directory>]
Get creates a local 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.
The --lazy option isn’t as useful for local copies, because Darcs
will automatically use ‘hard linking’ where possible. As well as
saving time and space, you can move or delete the original
repository without affecting a complete, hard-linked copy. Hard
linking requires that the copy be on the same filesystem and the
original repository, and that the filesystem support hard linking.
This includes NTFS, HFS+ and all general-purpose Unix filesystems
(such as ext3, UFS and ZFS). FAT does not support hard links.
Darcs get will not copy unrecorded changes to the source
repository’s working tree.
It is often desirable to make a copy of a repository that excludes
some patches. For example, if releases are tagged then ‘darcs get
--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 changes --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.
If the source repository is in a legacy darcs-1 format and contains
at least one checkpoint (see ‘darcs optimize’), the --partial
option will create a partial repository. A partial repository
discards history from before the checkpoint in order to reduce
resource requirements. For modern darcs-2 repositories, --partial
is a deprecated alias for the --lazy option.
A repository created by ‘darcs get’ will be in the best available
format: it will be able to exchange patches with the source
repository, but will not be directly readable by Darcs binaries
older than 2.0.0. Use the ‘--old-fashioned-inventory’ option if
the latter is required.
darcs put <new repository>
The ‘darcs put’ command creates a copy of the current repository.
It is currently very inefficient, so when creating local copies you
should use ‘darcs get . x’ instead of ‘darcs put x’.
Currently this command just uses ‘darcs init’ to create the target
repository, then ‘darcs push --all’ to copy patches to it. Options
passed to ‘darcs put’ are passed to the init and/or push commands
as appropriate. See those commands for an explanation of each
option.
Administrating repositories:
darcs initialize
The ‘darcs initialize’ command turns the current directory into a
Darcs repository. Any existing files and subdirectories become
UNSAVED changes in the working tree: record them with ‘darcs add
-r’ and ‘darcs record’.
When converting a project to Darcs from some other VCS, translating
the full revision history to native Darcs patches is recommended.
(The Darcs wiki lists utilities for this.) Because Darcs is
optimized for small patches, simply importing the latest revision
as a single large patch can PERMANENTLY degrade Darcs performance
in your repository by an order of magnitude.
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.
In addition to the default ‘darcs-2’ format, there are two backward
compatibility formats for the _darcs directory. These formats are
only useful if some of your contributors do not have access to
Darcs 2.0 or higher. In that case, you need to use the original
format (called ‘old-fashioned inventory’ or ‘darcs-1’) for any
repositories those contributors access.
As patches cannot be shared between darcs-2 and darcs-1
repositories, you cannot use the darcs-2 format for private
branches of such a project. Instead, you should use the ‘hashed’
format, which provides most of the features of the darcs-2 format,
while retaining the ability to share patches with darcs-1
repositories. The ‘darcs get’ command will do this by default.
Once all contributors have access to Darcs 2.0 or higher, a darcs-1
project can be migrated to darcs-2 using the ‘darcs convert’
command.
Darcs will create a hashed repository by default when you ‘darcs
get’ a repository in old-fashioned inventory format. Once all
contributors have upgraded to Darcs 2.0 or later, use ‘darcs
convert’ to convert the project to the darcs-2 format.
Initialize is commonly abbreviated to ‘init’.
darcs optimize
The ‘darcs optimize’ command modifies the current repository in an
attempt to reduce its resource requirements. By default a single
fast, safe optimization is performed; additional optimization
techniques can be enabled by passing options to ‘darcs optimize’.
The default optimization 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.
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
get’ to copy a repository, or if you pulled the same patch from a
remote repository into multiple local repositories.
A ‘darcs optimize --relink-pristine’ command is also available, but
generally SHOULD NOT be used. It results in a relatively small
space saving at the cost of making many Darcs commands MUCH slower.
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. Note that
repositories in the legacy ‘old-fashioned-inventory’ format have a
.gz extension on patch files even when uncompressed.
If the repository is in ‘old-fashioned-inventory’ format, the
‘darcs optimize --checkpoint’ command creates a checkpoint of the
latest tag. This checkpoint is used by ‘darcs get --partial’ to
create partial repositories. With the ‘--tag’ option, checkpoints
for older tags can be created. In newer repository formats, this
feature has been replaced by ‘darcs get --lazy’, which does not
require checkpoints.
There is one more optimization which CAN NOT be performed by this
command. Every time your record a patch, a new inventory file is
written to _darcs/inventories/, and old inventories are never
reaped.
If _darcs/inventories/ is consuming a relatively large amount of
space, you can safely reclaim it by using ‘darcs get’ to make a
complete copy of the repo. When doing so, don’t forget to copy
over any unsaved changes you have made to the working tree or to
unversioned files in _darcs/prefs/ (such as _darcs/prefs/author).
darcs check
This command verifies that the patches in the repository, when
applied successively to an empty tree, result in the pristine tree.
If not, the differences are printed and Darcs exits unsucessfully
(with a non-zero exit status).
If the repository is in darcs-1 format and has a checkpoint, you
can use the --partial option to start checking from the latest
checkpoint. This is the default for partial darcs-1 repositories;
the --complete option to forces a full check.
If a regression test is defined (see ‘darcs setpref’) it will be
run by ‘darcs check’. Use the --no-test option to disable this.
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.
darcs convert <source> [<destination>]
The current repository format is called ‘darcs-2’. It was
introduced in Darcs 2.0 and became the default for new projects in
Darcs 2.2. The ‘darcs convert’ command allows existing projects to
migrate to this format from the older ‘darcs-1’ format.
This command DOES NOT modify the source repository; a new
destination repository is created. It is safe to run this command
more than once on a repository (e.g. for testing), before the final
conversion.
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, darcs 2 repositories created by different invocations
of this command SHOULD NOT exchange patches, unless those
repositories had no patches in common when they were converted.
(That is, within a set of repos that exchange patches, no patch
should be converted more than once.)
Due to this limitation, migrating a multi-branch project is a
little awkward. Sorry! Here is the recommended process:
1. for each branch ‘foo’, tag that branch with ‘foo-final’;
2. merge all branches together (--allow-conflicts may help);
3. run ‘darcs optimize --reorder’ on the result;
4. run ‘darcs convert’ to create a merged darcs-2 repository;
5. re-create each branch by calling ‘darcs get --tag foo-final’ on
the darcs-2 repository; and finally
6. use ‘darcs obliterate’ to delete the foo-final tags.
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, 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.
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_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.
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.
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
A user manual is included with Darcs, in PDF and HTML form. It can
also be found at http://darcs.net/manual/.
2.3.0 (release)