2192 lines
81 KiB
HTML
2192 lines
81 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of DARCS</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>DARCS</H1>
|
|
Section: User Commands (1)<BR>Updated: 2.14.2 (release)<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
darcs - an advanced revision control system
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<B>darcs</B>
|
|
|
|
<I>command</I>
|
|
|
|
<<I>arguments</I>|[<I>options</I>]>...
|
|
|
|
<P>
|
|
Where the
|
|
<I>commands</I>
|
|
|
|
and their respective
|
|
<I>arguments</I>
|
|
|
|
are
|
|
<P>
|
|
<B>darcs help</B>
|
|
|
|
[<<I>darcs</I>_<I>command</I>> [<I>darcs</I>_<I>subcommand</I>]]
|
|
|
|
<BR>
|
|
|
|
<B>darcs initialize</B>
|
|
|
|
[<<I>directory</I>>]
|
|
|
|
<BR>
|
|
|
|
<B>darcs add</B>
|
|
|
|
<<I>file</I>|<I>directory</I>> ...
|
|
|
|
<BR>
|
|
|
|
<B>darcs whatsnew</B>
|
|
|
|
[<I>file</I>|<I>directory</I>]...
|
|
|
|
<BR>
|
|
|
|
<B>darcs record</B>
|
|
|
|
[<I>file</I>|<I>directory</I>]...
|
|
|
|
<BR>
|
|
|
|
<B>darcs clone</B>
|
|
|
|
<<I>repository</I>>
|
|
|
|
[<<I>directory</I>>]
|
|
|
|
<BR>
|
|
|
|
<B>darcs pull</B>
|
|
|
|
[<I>repository</I>]...
|
|
|
|
<BR>
|
|
|
|
<B>darcs push</B>
|
|
|
|
[<I>repository</I>]
|
|
|
|
<BR>
|
|
|
|
<B>darcs move</B>
|
|
|
|
<<I>source</I>> ... <<I>destination</I>>
|
|
|
|
<BR>
|
|
|
|
<B>darcs remove</B>
|
|
|
|
<<I>file</I>|<I>directory</I>> ...
|
|
|
|
<BR>
|
|
|
|
<B>darcs replace</B>
|
|
|
|
<<I>old</I>>
|
|
|
|
<<I>new</I>>
|
|
|
|
<<I>file</I>> ...
|
|
|
|
<BR>
|
|
|
|
<B>darcs log</B>
|
|
|
|
[<I>file</I>|<I>directory</I>]...
|
|
|
|
<BR>
|
|
|
|
<B>darcs annotate</B>
|
|
|
|
[<I>file</I>|<I>directory</I>]
|
|
|
|
<BR>
|
|
|
|
<B>darcs diff</B>
|
|
|
|
[<I>file</I>|<I>directory</I>]...
|
|
|
|
<BR>
|
|
|
|
<B>darcs show contents</B>
|
|
|
|
[<I>file</I>]...
|
|
|
|
<BR>
|
|
|
|
<B>darcs show dependencies</B>
|
|
|
|
<BR>
|
|
|
|
<B>darcs show files</B>
|
|
|
|
[<I>file</I>|<I>directory</I>]...
|
|
|
|
<BR>
|
|
|
|
<B>darcs show index</B>
|
|
|
|
<BR>
|
|
|
|
<B>darcs show pristine</B>
|
|
|
|
<BR>
|
|
|
|
<B>darcs show repo</B>
|
|
|
|
<BR>
|
|
|
|
<B>darcs show authors</B>
|
|
|
|
<BR>
|
|
|
|
<B>darcs show tags</B>
|
|
|
|
<BR>
|
|
|
|
<B>darcs show patch-index</B>
|
|
|
|
<BR>
|
|
|
|
<B>darcs test</B>
|
|
|
|
[[<I>initialization</I>]
|
|
|
|
command<I>]</I>
|
|
|
|
<BR>
|
|
|
|
<B>darcs revert</B>
|
|
|
|
[<I>file</I>|<I>directory</I>]...
|
|
|
|
<BR>
|
|
|
|
<B>darcs unrevert</B>
|
|
|
|
<BR>
|
|
|
|
<B>darcs amend</B>
|
|
|
|
[<I>file</I>|<I>directory</I>]...
|
|
|
|
<BR>
|
|
|
|
<B>darcs rebase pull</B>
|
|
|
|
[<I>repository</I>]...
|
|
|
|
<BR>
|
|
|
|
<B>darcs rebase apply</B>
|
|
|
|
<<I>patchfile</I>>
|
|
|
|
<BR>
|
|
|
|
<B>darcs rebase suspend</B>
|
|
|
|
<BR>
|
|
|
|
<B>darcs rebase unsuspend</B>
|
|
|
|
<BR>
|
|
|
|
<B>darcs rebase obliterate</B>
|
|
|
|
<BR>
|
|
|
|
<B>darcs rebase log</B>
|
|
|
|
<BR>
|
|
|
|
<B>darcs rollback</B>
|
|
|
|
[<I>file</I>|<I>directory</I>]...
|
|
|
|
<BR>
|
|
|
|
<B>darcs unrecord</B>
|
|
|
|
<BR>
|
|
|
|
<B>darcs obliterate</B>
|
|
|
|
<BR>
|
|
|
|
<B>darcs tag</B>
|
|
|
|
[<I>tagname</I>]
|
|
|
|
<BR>
|
|
|
|
<B>darcs setpref</B>
|
|
|
|
<<I>pref</I>>
|
|
|
|
<<I>value</I>>
|
|
|
|
<BR>
|
|
|
|
<B>darcs send</B>
|
|
|
|
[<I>repository</I>]
|
|
|
|
<BR>
|
|
|
|
<B>darcs apply</B>
|
|
|
|
<<I>patchfile</I>>
|
|
|
|
<BR>
|
|
|
|
<B>darcs optimize clean</B>
|
|
|
|
<BR>
|
|
|
|
<B>darcs optimize http</B>
|
|
|
|
<BR>
|
|
|
|
<B>darcs optimize reorder</B>
|
|
|
|
<BR>
|
|
|
|
<B>darcs optimize enable-patch-index</B>
|
|
|
|
<BR>
|
|
|
|
<B>darcs optimize disable-patch-index</B>
|
|
|
|
<BR>
|
|
|
|
<B>darcs optimize compress</B>
|
|
|
|
<BR>
|
|
|
|
<B>darcs optimize uncompress</B>
|
|
|
|
<BR>
|
|
|
|
<B>darcs optimize relink</B>
|
|
|
|
<BR>
|
|
|
|
<B>darcs optimize pristine</B>
|
|
|
|
<BR>
|
|
|
|
<B>darcs optimize upgrade</B>
|
|
|
|
<BR>
|
|
|
|
<B>darcs optimize cache</B>
|
|
|
|
<<I>directory</I>> ...
|
|
|
|
<BR>
|
|
|
|
<B>darcs dist</B>
|
|
|
|
<BR>
|
|
|
|
<B>darcs mark-conflicts</B>
|
|
|
|
[<I>file</I>|<I>directory</I>]...
|
|
|
|
<BR>
|
|
|
|
<B>darcs repair</B>
|
|
|
|
<BR>
|
|
|
|
<B>darcs convert darcs-2</B>
|
|
|
|
<<I>source</I>>
|
|
|
|
[<<I>destination</I>>]
|
|
|
|
<BR>
|
|
|
|
<B>darcs convert export</B>
|
|
|
|
<BR>
|
|
|
|
<B>darcs convert import</B>
|
|
|
|
[<<I>directory</I>>]
|
|
|
|
<BR>
|
|
|
|
<B>darcs fetch</B>
|
|
|
|
[<I>repository</I>]...
|
|
|
|
<BR>
|
|
|
|
<P>
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
Darcs is a free, open source revision control
|
|
system. It is:
|
|
<DL COMPACT>
|
|
<DT id="1">•<DD>
|
|
Distributed: Every user has access to the full
|
|
command set, removing boundaries between server and
|
|
client or committer and non-committers.
|
|
<DT id="2">•<DD>
|
|
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.
|
|
<DT id="3">•<DD>
|
|
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.
|
|
</DL>
|
|
<A NAME="lbAE"> </A>
|
|
<H2>OPTIONS</H2>
|
|
|
|
Different options are accepted by different Darcs commands.
|
|
Each command's most important options are listed in the
|
|
<B>COMMANDS</B>
|
|
|
|
section. For a full list of all options accepted by
|
|
a particular command, run `darcs
|
|
<I>command</I>
|
|
|
|
--help'.
|
|
<A NAME="lbAF"> </A>
|
|
<H3>Selecting Patches:</H3>
|
|
|
|
<P>
|
|
The --patches option yields patches with names matching an *extended*
|
|
regular expression. See <A HREF="/cgi-bin/man/man2html?7+regex">regex</A>(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.
|
|
<P>
|
|
- --patches=regex is a synonym for --matches='name regex'
|
|
- --hash=HASH is a synonym for --matches='hash HASH'
|
|
- --from-patch and --to-patch are synonyms for --from-match='name... and --to-match='name...
|
|
- --from-patch and --to-match can be unproblematically combined:
|
|
<BR> `darcs log --from-patch='html.*documentation' --to-match='date 20040212'`
|
|
<P>
|
|
The following primitive Boolean expressions are supported:
|
|
<P>
|
|
<BR> exact STRING - check literal STRING is equal to patch name.
|
|
<BR> name REGEX - match REGEX against patch name.
|
|
<BR> author REGEX - match REGEX against patch author.
|
|
<BR> hunk REGEX - match REGEX against contents of a hunk patch.
|
|
<BR> comment REGEX - match REGEX against the full log message.
|
|
<BR> hash HASH - match HASH against (a prefix of) the hash of a patch.
|
|
<BR> date DATE - match DATE against the patch date.
|
|
<BR> touch REGEX - match file paths for a patch.
|
|
<P>
|
|
Here are some examples:
|
|
<P>
|
|
<BR> darcs log --match 'exact "Resolve issue17: use dynamic memory allocation."'
|
|
<BR> darcs log --match 'name issue17'
|
|
<BR> darcs log --match 'name "^[Rr]esolve issue17\>"'
|
|
<BR> darcs log --match 'author "David Roundy"'
|
|
<BR> darcs log --match 'author droundy'
|
|
<BR> darcs log --match 'author <A HREF="mailto:droundy@darcs.net">droundy@darcs.net</A>'
|
|
<BR> darcs log --match 'hunk "foo = 2"'
|
|
<BR> darcs log --match 'hunk "^instance .* Foo where$"'
|
|
<BR> darcs log --match 'comment "prevent deadlocks"'
|
|
<BR> darcs log --match 'hash c719567e92c3b0ab9eddd5290b705712b8b918ef'
|
|
<BR> darcs log --match 'hash c7195'
|
|
<BR> darcs log --match 'date "2006-04-02 22:41"'
|
|
<BR> darcs log --match 'date "tea time yesterday"'
|
|
<BR> darcs log --match 'touch src/foo.c'
|
|
<BR> darcs log --match 'touch src/'
|
|
<BR> darcs log --match 'touch "src/*.(c|h)"'
|
|
<P>
|
|
<A NAME="lbAG"> </A>
|
|
<H2>COMMANDS</H2>
|
|
|
|
<B>darcs help</B>
|
|
|
|
[<<I>darcs</I>_<I>command</I>> [<I>darcs</I>_<I>subcommand</I>]]
|
|
|
|
<DL COMPACT><DT id="4"><DD>
|
|
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.
|
|
<P>
|
|
</DL>
|
|
|
|
<A NAME="lbAH"> </A>
|
|
<H3>Most used/starting out:</H3>
|
|
|
|
<B>darcs initialize</B>
|
|
|
|
[<<I>directory</I>>]
|
|
|
|
<DL COMPACT><DT id="5"><DD>
|
|
The `darcs initialize` command creates an empty repository in the
|
|
current directory. This repository lives in a new `_darcs` directory,
|
|
which stores version control metadata and settings.
|
|
<P>
|
|
Any existing files and subdirectories become UNSAVED changes:
|
|
record them with `darcs record --look-for-adds`.
|
|
<P>
|
|
By default, patches of the new repository are in the darcs-2 semantics.
|
|
However it is possible to create a repository in darcs-1 semantics with
|
|
the flag `--darcs-1`, althought this is not recommended except for sharing
|
|
patches with a project that uses patches in the darcs-1 semantics.
|
|
<P>
|
|
Initialize is commonly abbreviated to `init`.
|
|
<P>
|
|
</DL>
|
|
|
|
<B>darcs add</B>
|
|
|
|
<<I>file</I>|<I>directory</I>> ...
|
|
|
|
<DL COMPACT><DT id="6"><DD>
|
|
Generally the working tree 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.
|
|
<P>
|
|
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.
|
|
<P>
|
|
Adding symbolic links (symlinks) is not supported.
|
|
<P>
|
|
Darcs will ignore all files and folders that look "boring". The
|
|
`--boring` option overrides this behaviour.
|
|
<P>
|
|
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!
|
|
<P>
|
|
<P>
|
|
</DL>
|
|
|
|
<B>darcs whatsnew</B>
|
|
|
|
[<I>file</I>|<I>directory</I>]...
|
|
|
|
<DL COMPACT><DT id="7"><DD>
|
|
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.
|
|
<P>
|
|
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. Summary mnemonics are as follows:
|
|
<P>
|
|
* `A f` and `A d/` respectively mean an added file or directory.
|
|
* `R f` and `R d/` respectively mean a removed file or directory.
|
|
* `M f -N +M rP` means a modified file, with `N` lines deleted, `M`
|
|
<BR> lines added, and `P` lexical replacements.
|
|
* `f -> g` means a moved file or directory.
|
|
* `a f` and `a d/` respectively mean a new, but unadded, file or
|
|
<BR> directory, when using `--look-for-adds`.
|
|
<P>
|
|
<BR> An exclamation mark (!) as in `R! foo.c`, means the change is known to
|
|
<BR> conflict with a change in another patch. The phrase `duplicated`
|
|
<BR> means the change is known to be identical to a change in another patch.
|
|
<P>
|
|
The `--machine-readable` option implies `--summary` while making it more
|
|
parsable. Modified files are only shown as `M f`, and moves are shown in
|
|
two lines: `F f` and `T g` (as in 'From f To g').
|
|
<P>
|
|
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.
|
|
<P>
|
|
This command exits unsuccessfully (returns a non-zero exit status) if
|
|
there are no unrecorded changes.
|
|
<P>
|
|
</DL>
|
|
|
|
<B>darcs record</B>
|
|
|
|
[<I>file</I>|<I>directory</I>]...
|
|
|
|
<DL COMPACT><DT id="8"><DD>
|
|
The `darcs record` command is used to create a patch from changes in
|
|
the working tree. If you specify a set of files and directories,
|
|
changes to other files will be skipped.
|
|
<P>
|
|
Every patch has a name, an optional description, an author and a date.
|
|
<P>
|
|
Darcs will launch a text editor (see `darcs help environment`) after the
|
|
interactive selection, to let you enter the patch name (first line) and
|
|
the patch description (subsequent lines).
|
|
<P>
|
|
You can supply the patch name in advance with the `-m` option, in which
|
|
case no text editor is launched, unless you use `--edit-long-comment`.
|
|
<P>
|
|
The patch description is an optional block of free-form text. It is
|
|
used to supply additional information that doesn't fit in the patch
|
|
name. For example, it might include a rationale of WHY the change was
|
|
necessary.
|
|
<P>
|
|
A technical difference between patch name and patch description, is
|
|
that matching with the flag `-p` is only done on patch names.
|
|
<P>
|
|
Finally, the `--logfile` option allows you to supply a file that already
|
|
contains the patch name and description. This is useful if a previous
|
|
record failed and left a `_darcs/patch_description.txt` file.
|
|
<P>
|
|
Each patch is attributed to its author, usually by email address (for
|
|
example, `Fred Bloggs <<A HREF="mailto:fred@example.net">fred@example.net</A>>`). Darcs looks in several
|
|
places for this author string: the `--author` option, the files
|
|
`_darcs/prefs/author` (in the repository) and `~/.darcs/author` (in your
|
|
home directory), and the environment variables `$DARCS_EMAIL` and
|
|
`$EMAIL`. If none of those exist, Darcs will prompt you for an author
|
|
string and write it to `~/.darcs/author`. Note that if you have more
|
|
than one email address, you can put them all in `~/.darcs/author`,
|
|
one author per line. Darcs will still prompt you for an author, but it
|
|
allows you to select from the list, or to type in an alternative.
|
|
<P>
|
|
If you want to manually define any explicit dependencies for your patch,
|
|
you can use the `--ask-deps` flag. Some dependencies may be automatically
|
|
inferred from the patch's content and cannot be removed. A patch with
|
|
specific dependencies can be empty.
|
|
<P>
|
|
The patch date is generated automatically. It can only be spoofed by
|
|
using the `--pipe` option.
|
|
<P>
|
|
If you run record with the `--pipe` option, you will be prompted for
|
|
the patch date, author, and the long comment. The long comment will extend
|
|
until the end of file or stdin is reached. This interface is intended for
|
|
scripting darcs, in particular for writing repository conversion scripts.
|
|
The prompts are intended mostly as a useful guide (since scripts won't
|
|
need them), to help you understand the input format. Here's an example of
|
|
what the `--pipe` prompts look like:
|
|
<P>
|
|
<BR> What is the date? Mon Nov 15 13:38:01 EST 2004
|
|
<BR> Who is the author? David Roundy
|
|
<BR> What is the log? One or more comment lines
|
|
<P>
|
|
If a test command has been defined with `darcs setpref`, attempting to
|
|
record a patch will cause the test command to be run in a clean copy
|
|
of the working tree (that is, including only recorded changes). If
|
|
the test fails, you will be offered to abort the record operation.
|
|
<P>
|
|
The `--set-scripts-executable` option causes scripts to be made
|
|
executable in the clean copy of the working tree, prior to running the
|
|
test. See `darcs clone` for an explanation of the script heuristic.
|
|
<P>
|
|
If your test command is tediously slow (e.g. `make all`) and you are
|
|
recording several patches in a row, you may wish to use `--no-test` to
|
|
skip all but the final test.
|
|
<P>
|
|
To see some context (unchanged lines) around each change, use the
|
|
`--unified` option.
|
|
<P>
|
|
</DL>
|
|
|
|
<B>darcs clone</B>
|
|
|
|
<<I>repository</I>>
|
|
|
|
[<<I>directory</I>>]
|
|
|
|
<DL COMPACT><DT id="9"><DD>
|
|
Clone creates a 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.
|
|
<P>
|
|
By default Darcs will copy every patch from the original repository.
|
|
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.
|
|
<P>
|
|
When cloning locally, Darcs automatically uses hard linking where
|
|
possible. As well as saving time and space, this enables to move or
|
|
delete the original repository without affecting the copy.
|
|
Hard linking requires that the copy be on the same filesystem as the
|
|
original repository, and that the filesystem support hard linking.
|
|
This includes NTFS, HFS+ and all general-purpose Unix filesystems
|
|
(such as ext, UFS and ZFS). FAT does not support hard links.
|
|
<P>
|
|
When cloning from a remote location, Darcs will look for and attempt
|
|
to use packs created by `darcs optimize http` in the remote repository.
|
|
Packs are single big files that can be downloaded faster than many
|
|
little files.
|
|
<P>
|
|
Darcs clone will not copy unrecorded changes to the source repository's
|
|
working tree.
|
|
<P>
|
|
You can copy a repository to a ssh url, in which case the new repository
|
|
will always be complete.
|
|
<P>
|
|
It is often desirable to make a copy of a repository that excludes
|
|
some patches. For example, if releases are tagged then `darcs clone
|
|
--tag .` would make a copy of the repository as at the latest release.
|
|
<P>
|
|
An untagged repository state can still be identified unambiguously by
|
|
a context file, as generated by `darcs log --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.
|
|
<P>
|
|
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 reorder`.
|
|
<P>
|
|
The `--set-scripts-executable` option causes scripts to be made
|
|
executable in the working tree. A script is any file that starts
|
|
with a shebang ("#!").
|
|
<P>
|
|
</DL>
|
|
|
|
<B>darcs pull</B>
|
|
|
|
[<I>repository</I>]...
|
|
|
|
<DL COMPACT><DT id="10"><DD>
|
|
Pull is used to bring patches 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 accepts arguments, which are
|
|
URLs from which to pull, and when called without an argument, pull will
|
|
use the repository specified at `_darcs/prefs/defaultrepo`.
|
|
<P>
|
|
The default (`--union`) behavior is to pull any patches that are in any of
|
|
the specified repositories. If you specify the `--intersection` flag, darcs
|
|
will only pull those patches which are present in all source repositories.
|
|
If you specify the `--complement` flag, darcs will only pull elements in the
|
|
first repository that do not exist in any of the remaining repositories.
|
|
<P>
|
|
If `--reorder` is supplied, the set of patches that exist only in the current
|
|
repository is brought at the top of the current history. This will work even
|
|
if there are no new patches to pull.
|
|
<P>
|
|
See `darcs help apply` for detailed description of many options.
|
|
<P>
|
|
</DL>
|
|
|
|
<B>darcs push</B>
|
|
|
|
[<I>repository</I>]
|
|
|
|
<DL COMPACT><DT id="11"><DD>
|
|
Push is the opposite of pull. Push allows you to copy patches from the
|
|
current repository into another repository.
|
|
<P>
|
|
If you give the `--apply-as` flag, darcs will use `sudo` to apply the
|
|
patches as a different user. This can be useful if you want to set up a
|
|
system where several users can modify the same repository, but you don't
|
|
want to allow them full write access. This isn't secure against skilled
|
|
malicious attackers, but at least can protect your repository from clumsy,
|
|
inept or lazy users.
|
|
<P>
|
|
`darcs push` will compress the patch data before sending it to a remote
|
|
location via ssh. This works as long as the remote darcs is not older
|
|
than version 2.5. If you get errors that indicate a corrupt patch bundle,
|
|
you should try again with the `--no-compress` option.
|
|
<P>
|
|
</DL>
|
|
|
|
<A NAME="lbAI"> </A>
|
|
<H3>Preparing patches before recording:</H3>
|
|
|
|
<B>darcs move</B>
|
|
|
|
<<I>source</I>> ... <<I>destination</I>>
|
|
|
|
<DL COMPACT><DT id="12"><DD>
|
|
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`), unless it has already been moved.
|
|
<P>
|
|
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!
|
|
<P>
|
|
</DL>
|
|
|
|
<B>darcs remove</B>
|
|
|
|
<<I>file</I>|<I>directory</I>> ...
|
|
|
|
<DL COMPACT><DT id="13"><DD>
|
|
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).
|
|
<P>
|
|
Note that applying a removal patch to a repository (e.g. by pulling
|
|
the patch) will ALWAYS affect the working tree of that repository.
|
|
<P>
|
|
</DL>
|
|
|
|
<B>darcs replace</B>
|
|
|
|
<<I>old</I>>
|
|
|
|
<<I>new</I>>
|
|
|
|
<<I>file</I>> ...
|
|
|
|
<DL COMPACT><DT id="14"><DD>
|
|
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.
|
|
<P>
|
|
Files are tokenized according to one simple rule: words are strings of
|
|
valid token characters, and everything between them (punctuation and
|
|
whitespace) is discarded. 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 (i.e. `[A-Za-z0-9_.-]`).
|
|
<P>
|
|
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]`
|
|
could be used to match fields in the <A HREF="/cgi-bin/man/man2html?5+passwd">passwd</A>(5), where records and
|
|
fields are separated by newlines and colons respectively.
|
|
<P>
|
|
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.
|
|
<P>
|
|
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.
|
|
<P>
|
|
Limitations:
|
|
<P>
|
|
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.
|
|
<P>
|
|
Due to limitations in the patch file format, `--token-chars` arguments
|
|
cannot contain literal whitespace. For example, `[^ \n\t]` cannot be
|
|
used to declare all characters except the space, tab and newline as
|
|
valid within a word, because it contains a literal space.
|
|
<P>
|
|
Unlike POSIX <A HREF="/cgi-bin/man/man2html?7+regex">regex</A>(7) bracket expressions, character classes (such as
|
|
`[[:alnum:]]`) are NOT supported by `--token-chars`, and will be silently
|
|
treated as a simple set of characters.
|
|
<P>
|
|
</DL>
|
|
|
|
<A NAME="lbAJ"> </A>
|
|
<H3>Querying the repository:</H3>
|
|
|
|
<B>darcs log</B>
|
|
|
|
[<I>file</I>|<I>directory</I>]...
|
|
|
|
<DL COMPACT><DT id="15"><DD>
|
|
The `darcs log` command lists patches of the current repository or,
|
|
with `--repo`, a remote repository. Without options or arguments,
|
|
ALL patches will be listed.
|
|
<P>
|
|
When given files or directories paths as arguments, only patches which
|
|
affect those paths are listed. This includes patches that happened to
|
|
files before they were moved or renamed.
|
|
<P>
|
|
When given `--from-tag` or `--from-patch`, only patches since that tag
|
|
or patch are listed. Similarly, the `--to-tag` and `--to-patch`
|
|
options restrict the list to older patches.
|
|
<P>
|
|
The `--last` and `--max-count` options both limit the number of patches
|
|
listed. The former applies BEFORE other filters, whereas the latter
|
|
applies AFTER other filters. For example `darcs log foo.c
|
|
--max-count 3` will print the last three patches that affect foo.c,
|
|
whereas `darcs log --last 3 foo.c` will, of the last three
|
|
patches, print only those that affect foo.c.
|
|
<P>
|
|
Four output formats exist. The default is `--human-readable`. The slightly
|
|
different `--machine-readable` format enables to see patch dependencies in
|
|
non-interactive mode. You can also select `--context`, which is an internal
|
|
format that can be re-read by Darcs (e.g. `darcs clone --context`).
|
|
<P>
|
|
Finally, there is `--xml-output`, which emits valid XML... unless a the
|
|
patch metadata (author, name or description) contains a non-ASCII
|
|
character and was recorded in a non-UTF8 locale.
|
|
<P>
|
|
</DL>
|
|
|
|
<B>darcs annotate</B>
|
|
|
|
[<I>file</I>|<I>directory</I>]
|
|
|
|
<DL COMPACT><DT id="16"><DD>
|
|
When `darcs annotate` is called on a file, it will find the patch that
|
|
last modified each line in that file. This also works on directories.
|
|
<P>
|
|
The `--machine-readable` option can be used to generate output for
|
|
machine postprocessing.
|
|
<P>
|
|
</DL>
|
|
|
|
<B>darcs diff</B>
|
|
|
|
[<I>file</I>|<I>directory</I>]...
|
|
|
|
<DL COMPACT><DT id="17"><DD>
|
|
The `darcs diff` command compares two versions of the working tree of
|
|
the current repository. Without options, the pristine (recorded) and
|
|
unrecorded working trees are compared. This is lower-level than
|
|
the `darcs whatsnew` command, since it outputs a line-by-line diff,
|
|
and it is also slower. As with `darcs whatsnew`, if you specify
|
|
files or directories, changes to other files are not listed.
|
|
The command always uses an external diff utility.
|
|
<P>
|
|
With the `--patch` option, the comparison will be made between working
|
|
trees with and without that patch. Patches *after* the selected patch
|
|
are not present in either of the compared working trees. The
|
|
`--from-patch` and `--to-patch` options allow the set of patches in the
|
|
`old' and `new' working trees to be specified separately.
|
|
<P>
|
|
The associated tag and match options are also understood, e.g. `darcs
|
|
diff --from-tag 1.0 --to-tag 1.1`. All these options assume an
|
|
ordering of the patch set, so results may be affected by operations
|
|
such as `darcs optimize reorder`.
|
|
<P>
|
|
<A HREF="/cgi-bin/man/man2html?1+diff">diff</A>(1) is called with the arguments `-rN`. The `--unified` option causes
|
|
`-u` to be passed to <A HREF="/cgi-bin/man/man2html?1+diff">diff</A>(1). An additional argument can be passed
|
|
using `--diff-opts`, such as `--diff-opts=-ud` or `--diff-opts=-wU9`.
|
|
<P>
|
|
The `--diff-command` option can be used to specify an alternative
|
|
utility. Arguments may be included, separated by whitespace. The value
|
|
is not interpreted by a shell, so shell constructs cannot be used. The
|
|
arguments %1 and %2 MUST be included, these are substituted for the two
|
|
working trees being compared. For instance:
|
|
<P>
|
|
<BR> darcs diff -p . --diff-command "meld %1 %2"
|
|
<P>
|
|
If this option is used, `--diff-opts` is ignored.
|
|
<P>
|
|
</DL>
|
|
|
|
<B>darcs show contents</B>
|
|
|
|
[<I>file</I>]...
|
|
|
|
<DL COMPACT><DT id="18"><DD>
|
|
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).
|
|
<P>
|
|
</DL>
|
|
|
|
<B>darcs show dependencies</B>
|
|
|
|
<DL COMPACT><DT id="19"><DD>
|
|
The `darcs show dependencies` command is used to create a graph of the
|
|
dependencies between patches of the repository (by default up to last tag).
|
|
<P>
|
|
The resulting graph is described in Dot Language, a general example of use
|
|
could be:
|
|
<P>
|
|
darcs show dependencies | dot -Tpdf -o FILE.pdf
|
|
<P>
|
|
</DL>
|
|
|
|
<B>darcs show files</B>
|
|
|
|
[<I>file</I>|<I>directory</I>]...
|
|
|
|
<DL COMPACT><DT id="20"><DD>
|
|
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`.
|
|
<P>
|
|
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.
|
|
<P>
|
|
By default `darcs show files` lists both files and directories, but the
|
|
`--no-files` and `--no-directories` flags modify this behaviour.
|
|
<P>
|
|
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 around 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.
|
|
<P>
|
|
For example, to list version-controlled files by size:
|
|
<P>
|
|
<BR> darcs show files -0 | xargs -0 ls -ldS
|
|
<P>
|
|
</DL>
|
|
|
|
<B>darcs show index</B>
|
|
|
|
<DL COMPACT><DT id="21"><DD>
|
|
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.
|
|
</DL>
|
|
|
|
<B>darcs show pristine</B>
|
|
|
|
<DL COMPACT><DT id="22"><DD>
|
|
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.
|
|
</DL>
|
|
|
|
<B>darcs show repo</B>
|
|
|
|
<DL COMPACT><DT id="23"><DD>
|
|
The `darcs show repo` command displays statistics about the current
|
|
repository, allowing third-party scripts to access this information
|
|
without inspecting `_darcs` directly (and without breaking when the
|
|
`_darcs` format changes).
|
|
<P>
|
|
The 'Weak Hash' identifies the set of patches of a repository independently
|
|
of ordering. It can be used to easily compare two repositories of a same
|
|
project. It is not cryptographically secure.
|
|
<P>
|
|
By default, output includes statistics that require walking through the patches
|
|
recorded in the repository, namely the 'Weak Hash' and the count of patches.
|
|
If this data isn't needed, use `--no-enum-patches` to accelerate this command
|
|
from <A HREF="/cgi-bin/man/man2html?n+O">O</A>(n) to <A HREF="/cgi-bin/man/man2html?1+O">O</A>(1).
|
|
<P>
|
|
By default, output is in a human-readable format. The `--xml-output`
|
|
option can be used to generate output for machine postprocessing.
|
|
<P>
|
|
</DL>
|
|
|
|
<B>darcs show authors</B>
|
|
|
|
<DL COMPACT><DT id="24"><DD>
|
|
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).
|
|
<P>
|
|
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 separated list of extended regular expressions.
|
|
Blank lines and lines beginning with two hyphens are ignored.
|
|
The format of `.authorspelling` can be described by this pattern:
|
|
<P>
|
|
<BR> name <address> [, regexp ]*
|
|
<P>
|
|
There are some pitfalls concerning special characters:
|
|
Whitespaces are stripped, if you need space in regexp use [ ].
|
|
Because comma serves as a separator you have to escape it if you want
|
|
it in regexp. Note that `.authorspelling` use extended regular
|
|
expressions so +, ? and so on are metacharacters and you need to
|
|
escape them to be interpreted literally.
|
|
<P>
|
|
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). Use ^,$ to match the whole string in regexps
|
|
<P>
|
|
Currently this canonicalization step is done only in `darcs show
|
|
authors`. Other commands, such as `darcs log` use author strings
|
|
verbatim.
|
|
<P>
|
|
An example `.authorspelling` file is:
|
|
<P>
|
|
<BR> -- This is a comment.
|
|
<BR> Fred Nurk <<A HREF="mailto:fred@example.com">fred@example.com</A>>
|
|
<BR> John Snagge <<A HREF="mailto:snagge@bbc.co.uk">snagge@bbc.co.uk</A>>, John, snagge@, js@(si|mit).edu
|
|
<BR> Chuck Jones\, Jr. <<A HREF="mailto:chuck@pobox.com">chuck@pobox.com</A>>, cj\<A HREF="mailto:+user@example.com">+user@example.com</A>
|
|
<P>
|
|
</DL>
|
|
|
|
<B>darcs show tags</B>
|
|
|
|
<DL COMPACT><DT id="25"><DD>
|
|
The tags command writes a list of all tags in the repository to standard
|
|
output.
|
|
<P>
|
|
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.
|
|
<P>
|
|
</DL>
|
|
|
|
<B>darcs show patch-index</B>
|
|
|
|
<DL COMPACT><DT id="26"><DD>
|
|
When given the `--verbose` flag, the command dumps the complete content
|
|
of the patch index and checks its integrity.
|
|
</DL>
|
|
|
|
<B>darcs test</B>
|
|
|
|
[[<I>initialization</I>]
|
|
|
|
command<I>]</I>
|
|
|
|
<DL COMPACT><DT id="27"><DD>
|
|
Run test on the current recorded state of the repository. Given no
|
|
arguments, it uses the default repository test (see `darcs setpref`).
|
|
Given one argument, it treats it as a test command.
|
|
Given two arguments, the first is an initialization command and the
|
|
second is the test (meaning the exit code of the first command is not
|
|
taken into account to determine success of the test).
|
|
If given the `--linear` or `--bisect` flags, it tries to find the most
|
|
recent version in the repository which passes a test.
|
|
<P>
|
|
`--linear` does linear search starting from head, and moving away
|
|
from head. This strategy is best when the test runs very quickly
|
|
or the patch you're seeking is near the head.
|
|
<P>
|
|
`--bisect` does binary search. This strategy is best when the test
|
|
runs very slowly or the patch you're seeking is likely to be in
|
|
the repository's distant past.
|
|
<P>
|
|
`--backoff` starts searching from head, skipping further and further
|
|
into the past until the test succeeds. It then does a binary search
|
|
on a subset of those skipped patches. This strategy works well unless
|
|
the patch you're seeking is in the repository's distant past.
|
|
<P>
|
|
Under the assumption that failure is monotonous, `--linear` and
|
|
`--bisect` produce the same result. (Monotonous means that when moving
|
|
away from head, the test result changes only once from "fail" to
|
|
"ok".) If failure is not monotonous, any one of the patches that
|
|
break the test is found at random.
|
|
<P>
|
|
</DL>
|
|
|
|
<A NAME="lbAK"> </A>
|
|
<H3>Undoing and correcting:</H3>
|
|
|
|
<B>darcs revert</B>
|
|
|
|
[<I>file</I>|<I>directory</I>]...
|
|
|
|
<DL COMPACT><DT id="28"><DD>
|
|
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.
|
|
<P>
|
|
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.
|
|
<P>
|
|
</DL>
|
|
|
|
<B>darcs unrevert</B>
|
|
|
|
<DL COMPACT><DT id="29"><DD>
|
|
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`).
|
|
<P>
|
|
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.
|
|
<P>
|
|
</DL>
|
|
|
|
<B>darcs amend</B>
|
|
|
|
[<I>file</I>|<I>directory</I>]...
|
|
|
|
<DL COMPACT><DT id="30"><DD>
|
|
Amend updates a "draft" patch with additions or improvements,
|
|
resulting in a single "finished" patch.
|
|
<P>
|
|
By default `amend` proposes you to record additional changes.
|
|
If instead you want to remove changes, use the flag `--unrecord`.
|
|
<P>
|
|
When recording a draft patch, it is a good idea to start the name with
|
|
`DRAFT:`. When done, remove it with `darcs amend --edit-long-comment`.
|
|
Alternatively, to change the patch name without starting an editor,
|
|
use the `--name`/`-m` flag:
|
|
<P>
|
|
<BR> darcs amend --match 'name "DRAFT: foo"' --name 'foo2'
|
|
<P>
|
|
Like `darcs record`, if you call amend 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:
|
|
<P>
|
|
<BR> darcs amend --match 'touch foo.c' bar.c
|
|
<P>
|
|
It is usually a bad idea to amend another developer's patch. To make
|
|
amend only ask about your own patches by default, you can add
|
|
something like `amend match David Roundy` to `~/.darcs/defaults`,
|
|
where `David Roundy` is your name.
|
|
<P>
|
|
</DL>
|
|
|
|
<B>darcs rebase pull</B>
|
|
|
|
[<I>repository</I>]...
|
|
|
|
<DL COMPACT><DT id="31"><DD>
|
|
Copy and apply patches from another repository, suspending any local patches that conflict.
|
|
</DL>
|
|
|
|
<B>darcs rebase apply</B>
|
|
|
|
<<I>patchfile</I>>
|
|
|
|
<DL COMPACT><DT id="32"><DD>
|
|
Apply a patch bundle, suspending any local patches that conflict.
|
|
</DL>
|
|
|
|
<B>darcs rebase suspend</B>
|
|
|
|
<DL COMPACT><DT id="33"><DD>
|
|
Select patches to move into a suspended state at the end of the repo.
|
|
<P>
|
|
</DL>
|
|
|
|
<B>darcs rebase unsuspend</B>
|
|
|
|
<DL COMPACT><DT id="34"><DD>
|
|
Selected patches to restore from a suspended state to the end of the repo.
|
|
<P>
|
|
</DL>
|
|
|
|
<B>darcs rebase obliterate</B>
|
|
|
|
<DL COMPACT><DT id="35"><DD>
|
|
Obliterate a patch that is currently suspended.
|
|
<P>
|
|
</DL>
|
|
|
|
<B>darcs rebase log</B>
|
|
|
|
<DL COMPACT><DT id="36"><DD>
|
|
List the currently suspended changes.
|
|
<P>
|
|
</DL>
|
|
|
|
<B>darcs rollback</B>
|
|
|
|
[<I>file</I>|<I>directory</I>]...
|
|
|
|
<DL COMPACT><DT id="37"><DD>
|
|
Rollback is used to undo the effects of some changes from patches
|
|
in the repository. The selected changes are undone in your working
|
|
tree, but the repository is left unchanged. First you are offered a
|
|
choice of which patches to undo, then which changes within the
|
|
patches to undo.
|
|
<P>
|
|
Before doing `rollback`, you may want to temporarily undo the changes
|
|
of your working tree (if there are) and save them for later use.
|
|
To do so, you can run `revert`, then run `rollback`, record a patch,
|
|
and run `unrevert` to restore the saved changes into your working tree.
|
|
<P>
|
|
</DL>
|
|
|
|
<B>darcs unrecord</B>
|
|
|
|
<DL COMPACT><DT id="38"><DD>
|
|
Unrecord does the opposite of record: it deletes patches from
|
|
the repository, without changing the working tree.
|
|
Deleting patches from the repository makes active changes again
|
|
which you may record or revert later.
|
|
Beware that you should not use this command if there is a
|
|
possibility that another user may have already pulled the patch.
|
|
<P>
|
|
</DL>
|
|
|
|
<B>darcs obliterate</B>
|
|
|
|
<DL COMPACT><DT id="39"><DD>
|
|
Obliterate completely removes recorded patches from your local
|
|
repository. The changes will be undone in your working tree and the
|
|
patches will not be shown in your changes list anymore. Beware that
|
|
you can lose precious code by obliterating!
|
|
<P>
|
|
One way to save obliterated patches is to use the -O flag. A patch
|
|
bundle will be created locally, that you will be able to apply
|
|
later to your repository with `darcs apply`.
|
|
<P>
|
|
</DL>
|
|
|
|
<A NAME="lbAL"> </A>
|
|
<H3>Direct modification of the repository:</H3>
|
|
|
|
<B>darcs tag</B>
|
|
|
|
[<I>tagname</I>]
|
|
|
|
<DL COMPACT><DT id="40"><DD>
|
|
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 <<A HREF="http://producingoss.com/en/development-cycle.html">http://producingoss.com/en/development-cycle.html</A>>.
|
|
<P>
|
|
To reproduce the state of a repository `R` as at tag `t`, use the
|
|
command `darcs clone --tag t R`. The command `darcs show tags` lists
|
|
all tags in the current repository.
|
|
<P>
|
|
Tagging also provides significant performance benefits: when Darcs
|
|
reaches a shared tag that depends on all antecedent patches, it can
|
|
simply stop processing.
|
|
<P>
|
|
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.
|
|
<P>
|
|
By default a tag names the entire repository state at the time the tag
|
|
is created. If the --ask-deps option is used, the patches to include
|
|
as part of the tag can be explicitly selected.
|
|
<P>
|
|
The `darcs tag` command accepts the `--pipe` option, which behaves as
|
|
described in `darcs record`.
|
|
<P>
|
|
</DL>
|
|
|
|
<B>darcs setpref</B>
|
|
|
|
<<I>pref</I>>
|
|
|
|
<<I>value</I>>
|
|
|
|
<DL COMPACT><DT id="41"><DD>
|
|
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.
|
|
<P>
|
|
Valid preferences are:
|
|
<P>
|
|
* 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
|
|
<P>
|
|
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:
|
|
<P>
|
|
<BR> darcs setpref test 'autoconf && ./configure && make && make test'
|
|
<P>
|
|
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.
|
|
<P>
|
|
</DL>
|
|
|
|
<A NAME="lbAM"> </A>
|
|
<H3>Exchanging patches by e-mail:</H3>
|
|
|
|
<B>darcs send</B>
|
|
|
|
[<I>repository</I>]
|
|
|
|
<DL COMPACT><DT id="42"><DD>
|
|
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 saved to a file, although you may directly send it by mail.
|
|
<P>
|
|
The `--output`, `--output-auto-name`, and `--to` flags determine
|
|
what darcs does with the patch bundle after creating it. If you provide an
|
|
`--output` argument, the patch bundle is saved to that file. If you
|
|
specify `--output-auto-name`, the patch bundle is saved to a file with an
|
|
automatically generated name. If you give one or more `--to` arguments,
|
|
the bundle of patches is sent to those locations. The locations may either
|
|
be email addresses or urls that the patch should be submitted to via HTTP.
|
|
<P>
|
|
If you provide the `--mail` flag, darcs will look at the contents
|
|
of the `_darcs/prefs/email` file in the target repository (if it exists),
|
|
and send the patch by email to that address. In this case, you may use
|
|
the `--cc` option to specify additional recipients without overriding the
|
|
default repository email address.
|
|
<P>
|
|
If `_darcs/prefs/post` exists in the target repository, darcs will
|
|
upload to the URL contained in that file, which may either be a
|
|
`mailto:` URL, or an `<A HREF="http://`">http://`</A> URL. In the latter case, the
|
|
patch is posted to that URL.
|
|
<P>
|
|
If there is no email address associated with the repository, darcs will
|
|
prompt you for an email address.
|
|
<P>
|
|
Use the `--subject` flag to set the subject of the e-mail to be sent.
|
|
If you don't provide a subject on the command line, darcs will make one up
|
|
based on names of the patches in the patch bundle.
|
|
<P>
|
|
Use the `--in-reply-to` flag to set the In-Reply-To and References headers
|
|
of the e-mail to be sent. By default no additional headers are included so
|
|
e-mail will not be treated as reply by mail readers.
|
|
<P>
|
|
If you want to include a description or explanation along with the bundle
|
|
of patches, you need to specify the `--edit-description` flag, which
|
|
will cause darcs to open up an editor with which you can compose a message
|
|
to go along with your patches.
|
|
<P>
|
|
If you want to use a command different from the default one for sending
|
|
email, you need to specify a command line with the `--sendmail-command`
|
|
option. The command line can contain some format specifiers which are
|
|
replaced by the actual values. Accepted format specifiers are `%s` for
|
|
subject, `%t` for to, `%c` for cc, `%b` for the body of the mail, `%f` for
|
|
from, `%a` for the patch bundle and the same specifiers in uppercase for the
|
|
URL-encoded values.
|
|
Additionally you can add `%<` to the end of the command line if the command
|
|
expects the complete email message on standard input. E.g. the command lines
|
|
for evolution and msmtp look like this:
|
|
<P>
|
|
<BR> evolution "mailto:%T?subject=%S&attach=%A&cc=%C&body=%B"
|
|
<BR> msmtp -t %<
|
|
<P>
|
|
Do not confuse the `--author` options with the return address
|
|
that `darcs send` will set for your patch bundle.
|
|
<P>
|
|
For example, if you have two email addresses A and B:
|
|
<P>
|
|
* If you use `--author A` but your machine is configured to send mail from
|
|
<BR> address B by default, then the return address on your message will be B.
|
|
* If you use `--from A` and your mail client supports setting the
|
|
<BR> From: address arbitrarily (some non-Unix-like mail clients, especially,
|
|
<BR> may not support this), then the return address will be A; if it does
|
|
<BR> not support this, then the return address will be B.
|
|
* If you supply neither `--from` nor `--author` then the return
|
|
<BR> address will be B.
|
|
<P>
|
|
In addition, unless you specify the sendmail command with
|
|
`--sendmail-command`, darcs sends email using the default email
|
|
command on your computer. This default command is determined by the
|
|
`configure` script. Thus, on some non-Unix-like OSes,
|
|
`--from` is likely to not work at all.
|
|
<P>
|
|
</DL>
|
|
|
|
<B>darcs apply</B>
|
|
|
|
<<I>patchfile</I>>
|
|
|
|
<DL COMPACT><DT id="43"><DD>
|
|
The `darcs apply` command takes a patch bundle and attempts to insert
|
|
it into the current repository. In addition to invoking it directly
|
|
on bundles created by `darcs send`, it is used internally by `darcs
|
|
push` on the remote end of an SSH connection.
|
|
<P>
|
|
If no file is supplied, the bundle is read from standard input.
|
|
<P>
|
|
If given an email instead of a patch bundle, Darcs will look for the
|
|
bundle as a MIME attachment to that email. Currently this will fail
|
|
if the MIME boundary is rewritten, such as in Courier and Mail.app.
|
|
<P>
|
|
If the `--reply <A HREF="mailto:noreply@example.net">noreply@example.net</A>` option is used, and the bundle is
|
|
attached to an email, Darcs will send a report (indicating success or
|
|
failure) to the sender of the bundle (the `To` field). The argument to
|
|
noreply is the address the report will appear to originate FROM.
|
|
<P>
|
|
The `--cc` option will cause the report to be CC'd to another address,
|
|
for example `--cc <A HREF="mailto:reports@lists.example.net">reports@lists.example.net</A>,<A HREF="mailto:admin@lists.example.net">admin@lists.example.net</A>`.
|
|
Using `--cc` without `--reply` is undefined.
|
|
<P>
|
|
If you want to use a command different from the default one for sending mail,
|
|
you need to specify a command line with the `--sendmail-command` option.
|
|
The command line can contain the format specifier `%t` for to
|
|
and you can add `%<` to the end of the command line if the command
|
|
expects the complete mail on standard input. For example, the command line
|
|
for msmtp looks like this:
|
|
<P>
|
|
<BR> msmtp -t %<
|
|
<P>
|
|
If <A HREF="/cgi-bin/man/man2html?1+gpg">gpg</A>(1) is installed, you can use `--verify pubring.gpg` to reject
|
|
bundles that aren't signed by a key in `pubring.gpg`.
|
|
<P>
|
|
If `--test` is supplied and a test is defined (see `darcs setpref`), the
|
|
bundle will be rejected if the test fails after applying it. In that
|
|
case, the rejection email from `--reply` will include the test output.
|
|
<P>
|
|
A patch bundle may introduce unresolved conflicts with existing
|
|
patches or with the working tree. By default, Darcs will add conflict
|
|
markers (see `darcs mark-conflicts`).
|
|
<P>
|
|
The `--external-merge` option lets you resolve these conflicts
|
|
using an external merge tool. In the option, `%a` is replaced with
|
|
the common ancestor (merge base), `%1` with the first version, `%2`
|
|
with the second version, and `%o` with the path where your resolved
|
|
content should go. For example, to use the xxdiff visual merge tool
|
|
you'd specify: `--external-merge='xxdiff -m -O -M %o %1 %a %2'`
|
|
<P>
|
|
The `--allow-conflicts` option will skip conflict marking; this is
|
|
useful when you want to treat a repository as just a bunch of patches,
|
|
such as using `darcs pull --union` to download of your co-workers
|
|
patches before going offline.
|
|
<P>
|
|
This can mess up unrecorded changes in the working tree, forcing you
|
|
to resolve the conflict immediately. To simply reject bundles that
|
|
introduce unresolved conflicts, using the `--dont-allow-conflicts`
|
|
option. Making this the default in push-based workflows is strongly
|
|
recommended.
|
|
<P>
|
|
Unlike most Darcs commands, `darcs apply` defaults to `--all`. Use the
|
|
`--interactive` option to pick which patches to apply from a bundle.
|
|
<P>
|
|
</DL>
|
|
|
|
<A NAME="lbAN"> </A>
|
|
<H3>Other commands:</H3>
|
|
|
|
<B>darcs optimize clean</B>
|
|
|
|
<DL COMPACT><DT id="44"><DD>
|
|
This command deletes obsolete files within the repository.
|
|
</DL>
|
|
|
|
<B>darcs optimize http</B>
|
|
|
|
<DL COMPACT><DT id="45"><DD>
|
|
Using this option creates 'repository packs' that could dramatically
|
|
speed up performance when a user does a `darcs clone` of the repository
|
|
over HTTP. To make use of packs, the clients must have a darcs of at
|
|
least version 2.10.
|
|
<P>
|
|
</DL>
|
|
|
|
<B>darcs optimize reorder</B>
|
|
|
|
<DL COMPACT><DT id="46"><DD>
|
|
This command 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.
|
|
</DL>
|
|
|
|
<B>darcs optimize enable-patch-index</B>
|
|
|
|
<DL COMPACT><DT id="47"><DD>
|
|
Build the patch index, an internal data structure that accelerates
|
|
commands that need to know what patches touch a given file. Such as
|
|
annotate and log.
|
|
</DL>
|
|
|
|
<B>darcs optimize disable-patch-index</B>
|
|
|
|
<DL COMPACT><DT id="48"><DD>
|
|
Delete and stop maintaining the patch index from the repository.
|
|
</DL>
|
|
|
|
<B>darcs optimize compress</B>
|
|
|
|
<DL COMPACT><DT id="49"><DD>
|
|
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.
|
|
<P>
|
|
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.
|
|
</DL>
|
|
|
|
<B>darcs optimize uncompress</B>
|
|
|
|
<DL COMPACT><DT id="50"><DD>
|
|
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.
|
|
<P>
|
|
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.
|
|
</DL>
|
|
|
|
<B>darcs optimize relink</B>
|
|
|
|
<DL COMPACT><DT id="51"><DD>
|
|
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).
|
|
<P>
|
|
Darcs uses hard-links automatically, so this command is rarely needed.
|
|
It is most useful if you used `cp -r` instead of `darcs clone` to copy a
|
|
repository, or if you pulled the same patch from a remote repository
|
|
into multiple local repositories.
|
|
</DL>
|
|
|
|
<B>darcs optimize pristine</B>
|
|
|
|
<DL COMPACT><DT id="52"><DD>
|
|
This command updates the format of `_darcs/pristine.hashed/`, which was different
|
|
before darcs 2.3.1.
|
|
</DL>
|
|
|
|
<B>darcs optimize upgrade</B>
|
|
|
|
<DL COMPACT><DT id="53"><DD>
|
|
Convert old-fashioned repositories to the current default hashed format.
|
|
</DL>
|
|
|
|
<B>darcs optimize cache</B>
|
|
|
|
<<I>directory</I>> ...
|
|
|
|
<DL COMPACT><DT id="54"><DD>
|
|
This command deletes obsolete files within the global cache.
|
|
It takes one or more directories as arguments, and recursively
|
|
searches all repositories within these directories. Then it deletes
|
|
all files in the global cache not belonging to these repositories.
|
|
When no directory is given, it searches repositories in the user's
|
|
home directory.
|
|
<P>
|
|
It also automatically migrates the global cache to the (default)
|
|
bucketed format.
|
|
<P>
|
|
</DL>
|
|
|
|
<B>darcs dist</B>
|
|
|
|
<DL COMPACT><DT id="55"><DD>
|
|
`darcs dist` creates a compressed archive in the repository's root
|
|
directory, containing the recorded state of the working tree
|
|
(unrecorded changes and the `_darcs` directory are excluded).
|
|
The command accepts matchers to create an archive of some past
|
|
repository state, for instance `--tag`.
|
|
<P>
|
|
By default, the archive (and the top-level directory within the
|
|
archive) has the same name as the repository, but this can be
|
|
overridden with the `--dist-name` option.
|
|
<P>
|
|
If a predist command is set (see `darcs setpref`), that command will
|
|
be run on the recorded state prior to archiving. For example,
|
|
autotools projects would set it to `autoconf && automake`.
|
|
<P>
|
|
If `--zip` is used, matchers and the predist command are ignored.
|
|
<P>
|
|
</DL>
|
|
|
|
<B>darcs mark-conflicts</B>
|
|
|
|
[<I>file</I>|<I>directory</I>]...
|
|
|
|
<DL COMPACT><DT id="56"><DD>
|
|
Darcs requires human guidance to unify changes to the same part of a
|
|
source file. When a conflict first occurs, darcs will add the
|
|
initial state and both choices to the working tree, delimited by the
|
|
markers `v v v`, `=====`, `* * *` and `^ ^ ^`, as follows:
|
|
<P>
|
|
<BR> v v v v v v v
|
|
<BR> Initial state.
|
|
<BR> =============
|
|
<BR> First choice.
|
|
<BR> *************
|
|
<BR> Second choice.
|
|
<BR> ^ ^ ^ ^ ^ ^ ^
|
|
<P>
|
|
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 are the unresolved conflicts. It is also
|
|
useful if `darcs apply` or `darcs pull` is called with
|
|
`--allow-conflicts`, where conflicts aren't marked initially.
|
|
<P>
|
|
Unless you use the `--dry-run` flag, any unrecorded changes to the
|
|
affected files WILL be lost forever when you run this command!
|
|
You will be prompted for confirmation before this takes place.
|
|
<P>
|
|
</DL>
|
|
|
|
<B>darcs repair</B>
|
|
|
|
<DL COMPACT><DT id="57"><DD>
|
|
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.
|
|
This command rebuilds a pristine tree by applying successively the
|
|
patches in the repository to an empty tree.
|
|
<P>
|
|
The flag `--dry-run` make this operation read-only, making darcs exit
|
|
unsuccessfully (with a non-zero exit status) if the rebuilt pristine is
|
|
different from the current pristine.
|
|
<P>
|
|
</DL>
|
|
|
|
<B>darcs convert darcs-2</B>
|
|
|
|
<<I>source</I>>
|
|
|
|
[<<I>destination</I>>]
|
|
|
|
<DL COMPACT><DT id="58"><DD>
|
|
This command converts a repository that uses the old patch semantics
|
|
`darcs-1` to a new repository with current `darcs-2` semantics.
|
|
<P>
|
|
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.
|
|
<P>
|
|
Furthermore, repositories created by different invocations of
|
|
this command SHOULD NOT exchange patches.
|
|
<P>
|
|
<P>
|
|
</DL>
|
|
|
|
<B>darcs convert export</B>
|
|
|
|
<DL COMPACT><DT id="59"><DD>
|
|
This command enables you to export darcs repositories into git.
|
|
<P>
|
|
For a one-time export you can use the recipe:
|
|
<P>
|
|
<BR> $ cd repo
|
|
<BR> $ git init ../mirror
|
|
<BR> $ darcs convert export | (cd ../mirror && git fast-import)
|
|
<P>
|
|
For incremental export using marksfiles:
|
|
<P>
|
|
<BR> $ cd repo
|
|
<BR> $ git init ../mirror
|
|
<BR> $ touch ../mirror/git.marks
|
|
<BR> $ darcs convert export --read-marks darcs.marks --write-marks darcs.marks
|
|
<BR> | (cd ../mirror && git fast-import --import-marks=git.marks --export-marks=git.marks)
|
|
<P>
|
|
In the case of incremental export, be careful to never amend, delete or
|
|
reorder patches in the source darcs repository.
|
|
<P>
|
|
Also, be aware that exporting a darcs repo to git will not be exactly
|
|
faithful in terms of history if the darcs repository contains conflicts.
|
|
<P>
|
|
Limitations:
|
|
<P>
|
|
* Empty directories are not supported by the fast-export protocol.
|
|
* Unicode filenames are currently not correctly handled.
|
|
<BR> See <A HREF="http://bugs.darcs.net/issue2359">http://bugs.darcs.net/issue2359</A> .
|
|
<P>
|
|
</DL>
|
|
|
|
<B>darcs convert import</B>
|
|
|
|
[<<I>directory</I>>]
|
|
|
|
<DL COMPACT><DT id="60"><DD>
|
|
This command imports git repositories into new darcs repositories.
|
|
Further options are accepted (see `darcs help init`).
|
|
<P>
|
|
To convert a git repo to a new darcs one you may run:
|
|
<BR> $ (cd gitrepo && git fast-export --all -M) | darcs convert import darcsmirror
|
|
<P>
|
|
WARNING: git repositories with branches will produce weird results,
|
|
<BR> use at your own risks.
|
|
<P>
|
|
Incremental import with marksfiles is currently not supported.
|
|
<P>
|
|
</DL>
|
|
|
|
<B>darcs fetch</B>
|
|
|
|
[<I>repository</I>]...
|
|
|
|
<DL COMPACT><DT id="61"><DD>
|
|
Fetch is similar to `pull` except that it does not apply any patches
|
|
to the current repository. Instead, it generates a patch bundle that
|
|
you can apply later with `apply`.
|
|
<P>
|
|
Fetch's behaviour is essentially similar to pull's, so please consult
|
|
the help of `pull` to know more.
|
|
<P>
|
|
</DL>
|
|
|
|
<P>
|
|
<A NAME="lbAO"> </A>
|
|
<H2>ENVIRONMENT</H2>
|
|
|
|
<A NAME="lbAP"> </A>
|
|
<H3>HOME and APPDATA</H3>
|
|
|
|
Per-user preferences are set in $HOME/.darcs (on Unix) or
|
|
%APPDATA%/darcs (on Windows). This is also the default location of
|
|
the cache.
|
|
<A NAME="lbAQ"> </A>
|
|
<H3>DARCS_EDITOR, VISUAL, and EDITOR</H3>
|
|
|
|
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, $VISUAL or $EDITOR.
|
|
If none of these are set, nano is used. If nano crashes or is not
|
|
found in your PATH, vi, emacs, emacs -nw and (on Windows) edit are
|
|
each tried in turn.
|
|
<A NAME="lbAR"> </A>
|
|
<H3>DARCS_PAGER and PAGER</H3>
|
|
|
|
Darcs will invoke a pager if the output of some command is longer
|
|
than 20 lines. Darcs will use the pager specified by $DARCS_PAGER
|
|
or $PAGER. If neither are set, `less` will be used.
|
|
<A NAME="lbAS"> </A>
|
|
<H3>DARCS_DONT_COLOR, DARCS_ALWAYS_COLOR, DARCS_ALTERNATIVE_COLOR, and DARCS_DO_COLOR_LINES</H3>
|
|
|
|
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
|
|
<A NAME="lbAT"> </A>
|
|
<H3>DARCS_DONT_ESCAPE_TRAILING_SPACES and DARCS_DONT_ESCAPE_TRAILING_CR</H3>
|
|
|
|
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
|
|
<A NAME="lbAU"> </A>
|
|
<H3>DARCS_DONT_ESCAPE_ANYTHING, DARCS_DONT_ESCAPE_EXTRA, DARCS_ESCAPE_EXTRA, DARCS_DONT_ESCAPE_ISPRINT, and DARCS_ESCAPE_8BIT</H3>
|
|
|
|
Darcs needs to escape certain characters when printing patch contents to
|
|
a terminal, depending on the encoding specified in your locale setting.
|
|
<P>
|
|
By default, darcs assumes that your locale encoding is ASCII compatible.
|
|
This includes UTF-8 and some 8-bit encodings like ISO/IEC-8859 (including
|
|
its variants). Since ASCII contains control characters like backspace
|
|
(which could hide patch content from the user when printed literally to
|
|
the terminal), and even ones that may introduce security risks such as
|
|
redirecting commands to the shell, darcs needs to escape such characters.
|
|
They are printed as `^<control letter>` or `\<hex code>`. Darcs also uses
|
|
special markup for line endings that are preceeded by white space, since
|
|
the white space would otherwise not be recognizable.
|
|
<P>
|
|
If you use an encoding that is not ASCII compatible, things are somewhat
|
|
less smooth. Such encodings include UTF-16 and UTF-32, as well as many of
|
|
the encodings that became obsolete with unicode. In this case you have two
|
|
options: 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.
|
|
<P>
|
|
Another possibility is to explicitly tell darcs to not escape or escape
|
|
certain bytes, using DARCS_DONT_ESCAPE_EXTRA and DARCS_ESCAPE_EXTRA. Their
|
|
values should be strings consisting of the verbatim bytes 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).
|
|
<P>
|
|
For historical reasons, darcs also supports DARCS_DONT_ESCAPE_ISPRINT and
|
|
DARCS_USE_ISPRINT (which are synonyms). These make sense only for 8-bit
|
|
encodings like ISO-8859 and are no longer needed since nowadays darcs does
|
|
the right thing here by default.
|
|
<P>
|
|
Finally, if you are in a highly security sensitive situation (or just
|
|
paranoid for other reasons), you can set DARCS_ESCAPE_8BIT to 1. This will
|
|
cause darcs to escape every non-ASCII byte in addition to ASCII control
|
|
characters.
|
|
<A NAME="lbAV"> </A>
|
|
<H3>DARCS_TMPDIR and TMPDIR</H3>
|
|
|
|
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.
|
|
<A NAME="lbAW"> </A>
|
|
<H3>DARCS_KEEP_TMPDIR</H3>
|
|
|
|
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.
|
|
<A NAME="lbAX"> </A>
|
|
<H3>DARCS_EMAIL and EMAIL</H3>
|
|
|
|
Each patch is attributed to its author, usually by email address (for
|
|
example, `Fred Bloggs <<A HREF="mailto:fred@example.net">fred@example.net</A>>`). Darcs looks in several
|
|
places for this author string: the `--author` option, the files
|
|
`_darcs/prefs/author` (in the repository) and `~/.darcs/author` (in your
|
|
home directory), and the environment variables `$DARCS_EMAIL` and
|
|
`$EMAIL`. If none of those exist, Darcs will prompt you for an author
|
|
string and write it to `~/.darcs/author`. Note that if you have more
|
|
than one email address, you can put them all in `~/.darcs/author`,
|
|
one author per line. Darcs will still prompt you for an author, but it
|
|
allows you to select from the list, or to type in an alternative.
|
|
<A NAME="lbAY"> </A>
|
|
<H3>SENDMAIL</H3>
|
|
|
|
On Unix, the `darcs send` command relies on <A HREF="/cgi-bin/man/man2html?8+sendmail">sendmail</A>(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.
|
|
<A NAME="lbAZ"> </A>
|
|
<H3>DARCS_SLOPPY_LOCKS</H3>
|
|
|
|
If on some filesystems you get an error of the kind:
|
|
<P>
|
|
<BR> darcs: takeLock [...]: atomic_create [...]: unsupported operation
|
|
<P>
|
|
you may want to try to export DARCS_SLOPPY_LOCKS=True.
|
|
<A NAME="lbBA"> </A>
|
|
<H3>DARCS_SSH</H3>
|
|
|
|
Repositories of the form [user@]host:[dir] are taken to be remote
|
|
repositories, which Darcs accesses with the external program <A HREF="/cgi-bin/man/man2html?1+ssh">ssh</A>(1).
|
|
<P>
|
|
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.
|
|
<A NAME="lbBB"> </A>
|
|
<H3>DARCS_SCP and DARCS_SFTP</H3>
|
|
|
|
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.
|
|
<P>
|
|
If transfer-mode fails, Darcs will fall back on <A HREF="/cgi-bin/man/man2html?1+scp">scp</A>(1) and <A HREF="/cgi-bin/man/man2html?1+sftp">sftp</A>(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.
|
|
<A NAME="lbBC"> </A>
|
|
<H3>SSH_PORT</H3>
|
|
|
|
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
|
|
<A HREF="/cgi-bin/man/man2html?5+ssh_config">ssh_config</A>(5). OpenSSH users will probably prefer to put something
|
|
like `Host *.example.net Port 443` into their ~/.ssh/config file.
|
|
<A NAME="lbBD"> </A>
|
|
<H3>HTTP_PROXY, HTTPS_PROXY, FTP_PROXY, ALL_PROXY, and NO_PROXY</H3>
|
|
|
|
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
|
|
<P>
|
|
<BR> [protocol://]<host>[:port]
|
|
<P>
|
|
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.
|
|
<P>
|
|
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
|
|
<P>
|
|
<BR> NO_PROXY=localhost,*.localdomain
|
|
<P>
|
|
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.
|
|
<P>
|
|
If Darcs was not built with libcurl, all these environment variables
|
|
are silently ignored, and there is no way to use a web proxy.
|
|
<A NAME="lbBE"> </A>
|
|
<H3>DARCS_PROXYUSERPWD</H3>
|
|
|
|
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.
|
|
<A NAME="lbBF"> </A>
|
|
<H3>DARCS_CONNECTION_TIMEOUT</H3>
|
|
|
|
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.
|
|
<P>
|
|
<A NAME="lbBG"> </A>
|
|
<H2>FILES</H2>
|
|
|
|
<A NAME="lbBH"> </A>
|
|
<H3>_darcs/prefs/motd</H3>
|
|
|
|
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.
|
|
<P>
|
|
<A NAME="lbBI"> </A>
|
|
<H3>_darcs/prefs/email</H3>
|
|
|
|
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.
|
|
<P>
|
|
<A NAME="lbBJ"> </A>
|
|
<H3>_darcs/prefs/post</H3>
|
|
|
|
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 `<A HREF="http://`">http://`</A> URL. In the latter case, the patch is posted to that URL.
|
|
<P>
|
|
<A NAME="lbBK"> </A>
|
|
<H3>_darcs/prefs/author</H3>
|
|
|
|
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 <<A HREF="mailto:droundy@abridgegame.org">droundy@abridgegame.org</A>>`. This file overrides the
|
|
contents of the environment variables `$DARCS_EMAIL` and `$EMAIL`.
|
|
<P>
|
|
<A NAME="lbBL"> </A>
|
|
<H3>_darcs/prefs/defaults</H3>
|
|
|
|
Default values for darcs commands. Each line of this file has the
|
|
following form:
|
|
<P>
|
|
<BR> COMMAND FLAG VALUE
|
|
<P>
|
|
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 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.
|
|
<P>
|
|
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. Only use safe flags with `ALL`.
|
|
<P>
|
|
For example, if your system clock is bizarre, you could instruct darcs to
|
|
always ignore the file modification times by adding the following line:
|
|
<P>
|
|
<BR> ALL ignore-times
|
|
<P>
|
|
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:
|
|
<P>
|
|
<BR> amend disable
|
|
<P>
|
|
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 do not conflict.
|
|
<P>
|
|
<A NAME="lbBM"> </A>
|
|
<H3>_darcs/prefs/sources</H3>
|
|
|
|
The `_darcs/prefs/sources` file is used to indicate alternative locations
|
|
from which to download patches. This file contains lines such as:
|
|
<P>
|
|
<BR> cache:/home/droundy/.cache/darcs
|
|
<BR> readonly:/home/otheruser/.cache/darcs
|
|
<BR> repo:<A HREF="http://darcs.net">http://darcs.net</A>
|
|
<P>
|
|
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 `<A HREF="http://darcs.net`.">http://darcs.net`.</A> 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.
|
|
<P>
|
|
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.
|
|
<P>
|
|
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.
|
|
<P>
|
|
<A NAME="lbBN"> </A>
|
|
<H3>_darcs/prefs/boring</H3>
|
|
|
|
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. A newly created repository has a boring file that includes
|
|
many common source control, backup, temporary, and compiled files.
|
|
<P>
|
|
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.
|
|
<P>
|
|
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.
|
|
<P>
|
|
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.
|
|
<P>
|
|
<A NAME="lbBO"> </A>
|
|
<H3>_darcs/prefs/binaries</H3>
|
|
|
|
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 characters
|
|
`^Z` or `NULL` 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.
|
|
<P>
|
|
<A NAME="lbBP"> </A>
|
|
<H3>_darcs/prefs/defaultrepo</H3>
|
|
|
|
Contains the URL of the default remote repository used by commands `pull`,
|
|
`push`, `send` and `optimize relink`. Darcs edits this file automatically
|
|
or when the flag `--set-default` is used.
|
|
<P>
|
|
<A NAME="lbBQ"> </A>
|
|
<H3>_darcs/prefs/tmpdir</H3>
|
|
|
|
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`.
|
|
<P>
|
|
<A NAME="lbBR"> </A>
|
|
<H3>_darcs/prefs/prefs</H3>
|
|
|
|
Contains the preferences set by the command `darcs setprefs`.
|
|
Do not edit manually.
|
|
<P>
|
|
<P>
|
|
<A NAME="lbBS"> </A>
|
|
<H2>BUGS</H2>
|
|
|
|
At <A HREF="http://bugs.darcs.net/">http://bugs.darcs.net/</A> 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 <A HREF="mailto:bugs@darcs.net">bugs@darcs.net</A>.
|
|
<A NAME="lbBT"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
The Darcs website provides a lot of additional information.
|
|
It can be found at <A HREF="http://darcs.net/">http://darcs.net/</A>
|
|
<A NAME="lbBU"> </A>
|
|
<H2>LICENSE</H2>
|
|
|
|
Darcs is free software; you can redistribute it and/or modify
|
|
it under the terms of the GNU General Public License as published by
|
|
the Free Software Foundation; either version 2, or (at your option)
|
|
any later version.
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="62"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="63"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="64"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="65"><A HREF="#lbAE">OPTIONS</A><DD>
|
|
<DL>
|
|
<DT id="66"><A HREF="#lbAF">Selecting Patches:</A><DD>
|
|
</DL>
|
|
<DT id="67"><A HREF="#lbAG">COMMANDS</A><DD>
|
|
<DL>
|
|
<DT id="68"><A HREF="#lbAH">Most used/starting out:</A><DD>
|
|
<DT id="69"><A HREF="#lbAI">Preparing patches before recording:</A><DD>
|
|
<DT id="70"><A HREF="#lbAJ">Querying the repository:</A><DD>
|
|
<DT id="71"><A HREF="#lbAK">Undoing and correcting:</A><DD>
|
|
<DT id="72"><A HREF="#lbAL">Direct modification of the repository:</A><DD>
|
|
<DT id="73"><A HREF="#lbAM">Exchanging patches by e-mail:</A><DD>
|
|
<DT id="74"><A HREF="#lbAN">Other commands:</A><DD>
|
|
</DL>
|
|
<DT id="75"><A HREF="#lbAO">ENVIRONMENT</A><DD>
|
|
<DL>
|
|
<DT id="76"><A HREF="#lbAP">HOME and APPDATA</A><DD>
|
|
<DT id="77"><A HREF="#lbAQ">DARCS_EDITOR, VISUAL, and EDITOR</A><DD>
|
|
<DT id="78"><A HREF="#lbAR">DARCS_PAGER and PAGER</A><DD>
|
|
<DT id="79"><A HREF="#lbAS">DARCS_DONT_COLOR, DARCS_ALWAYS_COLOR, DARCS_ALTERNATIVE_COLOR, and DARCS_DO_COLOR_LINES</A><DD>
|
|
<DT id="80"><A HREF="#lbAT">DARCS_DONT_ESCAPE_TRAILING_SPACES and DARCS_DONT_ESCAPE_TRAILING_CR</A><DD>
|
|
<DT id="81"><A HREF="#lbAU">DARCS_DONT_ESCAPE_ANYTHING, DARCS_DONT_ESCAPE_EXTRA, DARCS_ESCAPE_EXTRA, DARCS_DONT_ESCAPE_ISPRINT, and DARCS_ESCAPE_8BIT</A><DD>
|
|
<DT id="82"><A HREF="#lbAV">DARCS_TMPDIR and TMPDIR</A><DD>
|
|
<DT id="83"><A HREF="#lbAW">DARCS_KEEP_TMPDIR</A><DD>
|
|
<DT id="84"><A HREF="#lbAX">DARCS_EMAIL and EMAIL</A><DD>
|
|
<DT id="85"><A HREF="#lbAY">SENDMAIL</A><DD>
|
|
<DT id="86"><A HREF="#lbAZ">DARCS_SLOPPY_LOCKS</A><DD>
|
|
<DT id="87"><A HREF="#lbBA">DARCS_SSH</A><DD>
|
|
<DT id="88"><A HREF="#lbBB">DARCS_SCP and DARCS_SFTP</A><DD>
|
|
<DT id="89"><A HREF="#lbBC">SSH_PORT</A><DD>
|
|
<DT id="90"><A HREF="#lbBD">HTTP_PROXY, HTTPS_PROXY, FTP_PROXY, ALL_PROXY, and NO_PROXY</A><DD>
|
|
<DT id="91"><A HREF="#lbBE">DARCS_PROXYUSERPWD</A><DD>
|
|
<DT id="92"><A HREF="#lbBF">DARCS_CONNECTION_TIMEOUT</A><DD>
|
|
</DL>
|
|
<DT id="93"><A HREF="#lbBG">FILES</A><DD>
|
|
<DL>
|
|
<DT id="94"><A HREF="#lbBH">_darcs/prefs/motd</A><DD>
|
|
<DT id="95"><A HREF="#lbBI">_darcs/prefs/email</A><DD>
|
|
<DT id="96"><A HREF="#lbBJ">_darcs/prefs/post</A><DD>
|
|
<DT id="97"><A HREF="#lbBK">_darcs/prefs/author</A><DD>
|
|
<DT id="98"><A HREF="#lbBL">_darcs/prefs/defaults</A><DD>
|
|
<DT id="99"><A HREF="#lbBM">_darcs/prefs/sources</A><DD>
|
|
<DT id="100"><A HREF="#lbBN">_darcs/prefs/boring</A><DD>
|
|
<DT id="101"><A HREF="#lbBO">_darcs/prefs/binaries</A><DD>
|
|
<DT id="102"><A HREF="#lbBP">_darcs/prefs/defaultrepo</A><DD>
|
|
<DT id="103"><A HREF="#lbBQ">_darcs/prefs/tmpdir</A><DD>
|
|
<DT id="104"><A HREF="#lbBR">_darcs/prefs/prefs</A><DD>
|
|
</DL>
|
|
<DT id="105"><A HREF="#lbBS">BUGS</A><DD>
|
|
<DT id="106"><A HREF="#lbBT">SEE ALSO</A><DD>
|
|
<DT id="107"><A HREF="#lbBU">LICENSE</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:09 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|