ssh
to write to a remote file
system. A darcs executable is called on the remote system to apply the patches.
Arbitrary other transport protocols are supported, through an environment
variable describing a command that will run darcs on the remote system.
See the documentation for DARCS_APPLY_FOO in Chapter ??
for details.--dry-run
(summarize remote changes)
--summary
(summarize local changes)
^a
(list potential files to add)
tla
get
,
update
, commit
, archive-mirror
and so on.darcs
record
, which stores edits into your local
repository, and pull
, which moves data between repositories.
(darcs
push
is merely the opposite of pull
;
send
and apply
are just the two halves of push
).diff
command of darcs, a diff
program supporting
options -r
(recursive diff) and -N
(show new files as
differences against an empty file) is required. The configure
script will look for gdiff
, gnudiff
and diff
in this
order. You can force the use of another program by setting the DIFF
environment variable before running configure
.<ghc-dir>/gcc-lib/include
and libraries in
<ghc-dir>/gcc-lib
. MinGW stores headers in
<mingw-dir>/include
and libraries in <mingw-dir>/lib
.<msys-dir>/bin
, <mingw-dir>/bin
,
<curl-dir>
, and a directory containing a pre-built darcs.exe if you
want the build's patch context stored for `darcs --exact-version
'.
C:\darcs> cd <darcs-source-dir> C:\darcs> sh $ export GHC=/c/<ghc-dir>/bin/ghc.exe $ autoconf $ ./configure --target=mingw $ make
% ./configure % make # Optional, but recommended % make test % make installThere are options to configure that you may want to check out with
% ./configure --helpIf your header files are installed in a non-standard location, you may need to define the
CFLAGS
and CPPFLAGS
environment variables to
include the path to the headers. e.g. on NetBSD, you may need to run
% CFLAGS=-I/usr/pkg/include CPPFLAGS=-I/usr/pkg/include ./configure
% darcs get -v http://darcs.net/and once you have the darcs repository you can bring it up to date with a
% darcs pullThe repository doesn't hold automatically generated files, which include the configure script and the HTML documentation, so you need to run
autoconf
first.autoconf
2.50 or higher. Some systems have more than one
version of autoconf
installed. For example, autoconf
may point to
version 2.13, while autoconf259
runs version 2.59.make
is really "GNU make". On some systems, such as
the *BSDs, you may need to type gmake
instead of make for this to work.% autoconf % ./configure % make % make installIf you want to tweak the configure options, you'll need to run ./configure yourself after the make, and then run make again.
building_darcs.tex
) based
on your experience building darcs...% darcs record --no-testmaking sure to give the patch a nice descriptive name. The
--no-test
options keeps darcs from trying to run the unit tests,
which can be rather time-consuming. Then you can send the patch to the
darcs-devel mailing list by email by
% darcs send -uThe darcs repository stores the email address to which patches should be sent by default. The email address you see is actually my own, but when darcs notices that you haven't signed the patch with my GPG key, it will forward the message to darcs-devel.
% cd my_project/ % darcs initialize --darcs-2This creates the
_darcs
directory and populates it with whatever
files and directories are needed to describe an empty project. You now
need to tell darcs what files and directories in your project should be
under revision control. You do this using the command darcs add
1:
% darcs add *.c Makefile.am configure.acWhen you have added all your files (or at least, think you have), you will want to record your changes. “Recording” always includes adding a note as to why the change was made, or what it does. In this case, we'll just note that this is the initial version.
% darcs record --all What is the patch name? Initial revision.Note that since we didn't specify a patch name on the command line we were prompted for one. If the environment variable `EMAIL' isn't set, you will also be prompted for your email address. Each patch that is recorded is given a unique identifier consisting of the patch name, its creator's email address, and the date when it was created.
% darcs whatsnewThis should show you the modifications that you just made, in the darcs patch format. If you prefer to see your changes in a different format, read Section ??, which describes the whatsnew command in detail.
% darcs recorddarcs will then prompt you with all the changes that you have made that have not yet been recorded, asking you which ones you want to include in the new patch. Finally, darcs will ask you for a name for the patch.
% cd /var/www/repos % ln -s /home/username/myproject .As long as you're running a web server and making your repository available to the world, you may as well make it easy for people to see what changes you've made. You can do this by running
make installserver
, which
installs the program darcs_cgi
at /usr/lib/cgi-bin/darcs
. You
also will need to create a cache directory named
/var/cache/darcs_cgi
, and make sure the owner of that directory is
the same user that your web server runs its cgi scripts as. For me,
this is www-data. Now your friends and enemies should be able to easily
browse your repositories by pointing their web browsers at
http://your.server.org/cgi-bin/darcs
.cd
into my repository,
and there type:
% darcs pull http://your.server.org/repos/yourprojectDarcs will check to see if you have recorded any changes that aren't in my current repository. If so, it'll prompt me for each one, to see which ones I want to add to my repository. Note that you may see a different series of prompts depending on your answers, since sometimes one patch depends on another, so if you answer yes to the first one, you won't be prompted for the second if the first depends on it.
% darcs get http://your.server.org/repos/yourprojectwhich gets the whole repository.
[username@]host:/path/to/repository
.darcs pull
in the repository you want to move the patch to. This is nice,
as it doesn't require you to give write access to anyone else, and is
reasonably simple.darcs send
from that computer to generate a patch bundle destined for another
repository. You can either let darcs email the patch for you, or save it
as a file and transfer it by hand. Then in the destination repository you
(or the owner of that repository) run darcs apply
to apply the patches contained
in the bundle. This is also quite a simple method since, like the all-pull
method, it doesn't require that you give anyone write access to your
repository. But it's less convenient, since you have to keep track of the
patch bundle (in the email, or whatever)._darcs/prefs/email
file containing your email address.
This way anyone who sends to your repository will automatically send the
patch bundle to your email address..muttrc
the following:
auto_view text/x-patch text/x-darcs-patch macro pager A "<pipe-entry>darcs apply --verbose --mark-conflicts \ --reply droundy@abridgegame.org --repodir ~/darcs"which allows me to view a sent patch, and then apply the patch directly from
mutt
, sending a
confirmation email to the person who sent me the patch. The autoview line relies on on the following
lines, or something like them, being present in one's .mailcap
:
text/x-patch; cat; copiousoutput text/x-darcs-patch; cat; copiousoutput
.ssh/authorized_keys
. Then they run
% darcs push repouser@repo.server:repo/directory
--apply-as
can run on either a local repository or one accessed
with ssh, but uses sudo
to run a darcs apply command (having created
a patch bundle as in send) as another user. You can add the following line
in your sudoers
file to allow the users to apply their patches to a
centralized repository:
ALL ALL = (repo-user) NOPASSWD: /usr/bin/darcs apply --all --repodir /repo/path*This method is ideal for a centralized repository when all the users have accounts on the same computer, if you don't want your users to be able to run arbitrary commands as repo-user.
--test
option
of darcs apply, since it allows you to run the test suite (assuming you
have one) and reject patches that fail—and it's all done on the server,
so you can happily go on working on your development machine without
slowdown while the server runs the tests.--no-test
flag to darcs apply (and this is not
the default), you are also allowing anyone with write access to that
repository to run arbitrary code on your machine (since they can run a test
suite—which they can modify however they like). This is quite a
potential security hole.% gpg --gen-keyYou will be prompted for your name and email address, among other options. Of course, you can skip this step if you already have a gpg key you wish to use.
% gpg --export "email@address" > /tmp/exported_keyAnd now we can add your key to the
allowed_keys
:
(as root)> gpg --keyring /var/lib/darcs/repos/myproject/allowed_keys \ --no-default-keyring --import /tmp/exported_keyYou can repeat this process any number of times to authorize multiple users to send patches to the repository.
% darcs send --sign http://your.computer/repos/myprojectYou may want to add “send sign” to the file
_darcs/prefs/defaults
so that you won't need to type --sign
every time you want to
send...send
with the --sign
option might give you the following error:
darcs failed: Error running external program 'gpg'The most likely cause of this error is that you have a misconfigured gpg that tries to automatically use a non-existent gpg-agent program. GnuPG will still work without gpg-agent when you try to sign or encrypt your data with a passphrase protected key. However, it will exit with an error code 2 (
ENOENT
) causing darcs
to
fail. To fix this, you will need to edit your ~/.gnupg/gpg.conf
file and comment out or remove the line that says:
use-agentIf after commenting out or removing the
use-agent
line in your
gpg configuration file you still get the same error, then you probably
have a modified GnuPG with use-agent as a hard-coded option. In that
case, you should change use-agent
to no-use-agent
to
disable it explicitly./path/to/your/repo/_darcs/prefs
called email
containing your email address. As a trick (to be explained below), we will
create the email address with “darcs repo” as your name, in an email
address of the form “David Roundy <droundy@abridgegame.org>.”
% echo 'my darcs repo <user@host.com>' \ > /path/to/your/repo/_darcs/prefs/emailThe next step is to set up a gnupg keyring containing the public keys of people authorized to send to your repository. Here I'll give a second way of going about this (see above for the first). This time I'll assume you want to give me write access to your repository. You can do this by:
gpg --no-default-keyring \ --keyring /path/to/the/allowed_keys --recv-keys D3D5BCECThis works because “D3D5BCEC” is the ID of my gpg key, and I have uploaded my key to the gpg keyservers. Actually, this also requires that you have configured gpg to access a valid keyserver. You can, of course, repeat this command for all keys you want to allow access to.
.procmailrc
:
:0 * ^TOmy darcs repo |(umask 022; darcs apply --reply user@host.com \ --repodir /path/to/your/repo --verify /path/to/the/allowed_keys)The purpose for the “my darcs repo” trick is partially to make it easier to recognize patches sent to the repository, but is even more crucial to avoid nasty bounce loops by making the
--reply
option have an email
address that won't go back to the repository. This means that unsigned
patches that are sent to your repository will be forwarded to your ordinary
email.UMASK
variable
to a more suitable value.)darcs send
, you may not receive any feedback,
even if the patch is applied. You can confirm whether or not your patch was applied
to the remote repository by pointing darcs changes
at a remote repository:
darcs changes --last=10 --repo=http://darcs.net/That shows you the last 10 changes in the remote repository. You can adjust the options given to
changes
if a more advanced query is needed.darcs get
to copy a repository from a local
filesystem onto the same filesystem, Darcs will link patches whenever
possible.darcs get
does not link pristine trees
even when individual files are identical. Additionally, as you pull
patches into trees, patches will become unlinked. This will result in
a lot of wasted space if two repositories have been living for a long
time but are similar. In such a case, you should relink files
between the two repositories.darcs optimize --relink
, with
–the --sibling
flag specifying the sibling.
$ cd /var/repos/darcs.net $ darcs optimize --relink --sibling /var/repos/darcsThe
--sibling
flag can be repeated multiple times, in which
case Darcs will try to find a file to link to in all of the siblings.
If a default repository is defined, Darcs will try, as a last resort,
to link against the default repository.--relink-pristine
flag.
However, doing this prevents Darcs from having precise timestamps on
the pristine files, which carries a moderate performance penalty.--no-pristine-tree
flag to darcs initialize
or
darcs get
. There is currently no way to switch an existing
repository to use no pristine tree.--no-pristine-tree
repositories is fairly new,
and has not been extensively optimized yet. Please let us know if you
use this functionality, and which operations you find are too slow._darcs/prefs/
directory of a
repository. Such configuration only applies when working with that
repository. To configure darcs on a per-user rather than per-repository
basis (but with essentially the same methods), you can edit (or create)
files in the ~/.darcs/
directory. Finally, the behavior of some
darcs commands can be modified by setting appropriate environment
variables._darcs
directory contains a prefs
directory. This
directory exists simply to hold user configuration settings specific to
this repository. The contents of this directory are intended to be
modifiable by the user, although in some cases a mistake in such a
modification may cause darcs to behave strangely._darcs/prefs/defaults
file. Each line of this file has the following form:
COMMAND FLAG VALUEwhere
COMMAND
is either the name of the command to which the default
applies, or ALL
to indicate that the default applies to all commands
accepting that flag. The FLAG
term is the name of the long argument
option without the “--
”, i.e. verbose
rather than
--verbose
. Finally, the VALUE
option can be omitted if the
flag is one such as verbose
that doesn't involve a value.
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.ALL
easily can have unpredicted consequences,
especially if commands in newer versions of darcs accepts flags that they
didn't in previous versions. A command like obliterate
could be
devastating with the “wrong” flags (for example –all). Only use safe
flags with ALL
.~/.darcs/defaults |
provides defaults for this user account |
repo/_darcs/prefs/defaults |
provides defaults for one project, |
overrules changes per user |
_darcs/prefs/defaults
file. (Note that this would have to be
done for each repository!)
ALL ignore-timesIf you never want to run a test when recording to a particular repository (but still want to do so when running
check
on that repository), and like to name
all your patches “Stupid patch”, you could use the following:
record no-test record patch-name Stupid patchIf you would like a command to be run every time patches are recorded in a particular repository (for example if you have one central repository, that all developers contribute to), then you can set apply to always run a command when apply is successful. For example, if you need to make sure that the files in the repository have the correct access rights you might use the following. There are two things to note about using darcs this way:
darcs add
; doing so would
allow people to modify that file and then run arbitrary scripts on
your main repository, possibly damaging or violating security.
apply posthook chmod -R a+r * apply run-posthookSimilarly, if you need a command to run automatically before darcs performs an action you can use a prehook. Using prehooks it could be possible to canonicalize line endings before recording patches.
_darcs/prefs/defaults
. One of them is --disable
. As the name
suggests, this option will disable every command that got it as argument. So,
if you are afraid that you could damage your repositories by inadvertent use of
a command like amend-record, add the following line to
_darcs/prefs/defaults
:
amend-record disableAlso, a global preferences file can be created with the name
.darcs/defaults
in your home directory. Options present there will
be added to the repository-specific preferences.
If they conflict with repository-specific options, the repository-specific
ones will take precedence._darcs/prefs/repos
file contains a list of repositories you have
pulled from or pushed to, and is used for autocompletion of pull and push
commands in bash. Feel free to delete any lines from this list that might
get in there, or to delete the file as a whole._darcs/prefs/author
file contains the email address (or name) to
be used as the author when patches are recorded in this repository,
e.g. David Roundy <droundy@abridgegame.org>
. This
file overrides the contents of the environment variables
$DARCS_EMAIL
and $EMAIL
._darcs/prefs/boring
file may contain a list of regular
expressions describing files, such as object files, that you do not expect
to add to your project. As an example, the boring file that I use with
my darcs repository is:
\.hi$ \.o$ ^\.[^/] ^_ ~$ (^|/)CVS($|/)A newly created repository has a longer boring file that includes many common source control, backup, temporary, and compiled files.
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.~/.darcs/boring
, which will be
used with all of your darcs repositories.manual/index.html
) matches any of
the boring regular expressions is considered boring. The boring file is
used to filter the files provided to darcs add, to allow you to use a
simple darcs add newdir newdir/*
without accidentally adding a bunch of
object files. It is also used when the --look-for-adds
flag is
given to whatsnew or record.
Note that once a file has been added to darcs, it is not considered
boring, even if it matches the boring file filter._darcs/prefs/binaries
file may contain a list of regular
expressions describing files that should be treated as binary files rather
than text files. Darcs automatically treats files containing
^Z\
or '\0'
within the first 4096 bytes as being binary files.
You probably will want to have the binaries file under
version control. To do this you can use darcs setpref to set the value
“binariesfile” to the name of your desired binaries file
(e.g. darcs setpref binariesfile ./.binaries
, where
.binaries
is a file that has been
darcs added to your repository). As with the boring file, you can also set
up a ~/.darcs/binaries
file if you like._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._darcs/prefs/sources
file is used to indicate alternative
locations from which to download patches when using a “hashed”
repository. This file contains lines such as:
cache:/home/droundy/.darcs/cache readonly:/home/otheruser/.darcs/cache repo:http://darcs.netThis would indicate that darcs should first look in
/home/droundy/.darcs/cache
for patches that might be missing, and if
the patch isn't there, it should save a copy there for future use. In that
case, darcs will look in /home/otheruser/.darcs/cache
to see if that
user might have downloaded a copy, but won't try to save a copy there, of
course. Finally, it will look in http://darcs.net
. Note that the
sources
file can also exist in ~/.darcs/
. Also note that the
sources mentioned in your sources
file will be tried before
the repository you are pulling from. This can be useful in avoiding
downloading patches multiple times when you pull from a remote repository
to more than one local repository.mkdir -p $HOME/.darcs/cache echo cache:$HOME/.darcs/cache > $HOME/.darcs/sourcesNote 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.
_darcs/prefs/motd
file may contain a “message of the day”
which will be displayed to users who get or pull from the repository without the
--quiet
option.Variable | Section |
DARCS_EDITOR, EDITOR, VISUAL | ?? |
DARCS_PAGER, PAGER | ?? |
HOME | ?? |
TERM | ?? |
DARCS_EMAIL, EMAIL | ?? |
DARCS_APPLY_FOO | ?? |
DARCS_GET_FOO | ?? |
DARCS_MGET_FOO | ?? |
DARCS_MGETMAX | ?? |
DARCS_PROXYUSERPWD | ?? |
DARCS_WGET | ?? |
DARCS_SSH | ?? |
DARCS_SCP | ?? |
DARCS_SFTP | ?? |
SSH_PORT | ?? |
DARCS_ALTERNATIVE_COLOR | ?? |
DARCS_ALWAYS_COLOR | ?? |
DARCS_DO_COLOR_LINES | ?? |
DARCS_DONT_COLOR | ?? |
DARCS_DONT_ESCAPE_TRAILING_CR | ?? |
DARCS_DONT_ESCAPE_TRAILING_SPACES | ?? |
DARCS_DONT_ESCAPE_8BIT | ?? |
DARCS_DONT_ESCAPE_ANYTHING | ?? |
DARCS_DONT_ESCAPE_ISPRINT | ?? |
DARCS_ESCAPE_EXTRA | ?? |
DARCS_DONT_ESCAPE_EXTRA | ?? |
vi
, emacs
, emacs -nw
and
nano
in that order.more
./tmp
and if /tmp
doesn't exist,
it'll put the temporaries in _darcs
./tmp
to hold the test copy is no good,
as /tmp
isn't shared over NFS and thus the mpirun
call will
fail, since the binary isn't present on the compute nodes.$HOME/.darcs
.user@foo.org:foo
or foo.org:foo
. Darcs will use
scp to copy single files (e.g. repository meta-information), and sftp
to copy multiple files in batches (e.g. patches). These commands are
not interpreted by a shell, so you cannot use shell
metacharacters, and the first word in the command must be the name of
an executable located in your path. By default, scp
and sftp
are used. When you can use sftp, but not scp (e.g. some ISP web sites), it
works to set DARCS_SCP to `sftp'. The other way around does not work, i.e.
DARCS_FTP must reference an sftp program, not scp.foo://xxx
URLs.fetch -q -o - curl -s -f lynx -source wget -q -O -If set, DARCS_MGET_FOO will be used to fetch many files from a single repository simultaneously. Replace FOO and foo as appropriate to handle other URL schemes. These commands are not interpreted by a shell, so you cannot use shell metacharacters, and the first word in the command must be the name of an executable located in your path. The GET command will be called with a URL for each file. The MGET command will be invoked with a number of URLs and is expected to download the files to the current directory, preserving the file name but not the path. The APPLY command will be called with a darcs patchfile piped into its standard input. Example:
wget -q
wget -qDarcs will append
-i
to the argument list, which it uses to provide a
list of URLS to download. This allows wget to download multiple patches at the
same time. It's possible to use another command besides wget
with this
environment variable, but it must support the -i
option in the same way. 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.^<control letter>
or
\
<hex code>
)._darcs
directory in its root.
Pristine is the recorded state of the source tree.
The pristine tree is constructed from groups of changes,
called patches (some other version control systems use the
term changeset instead of patch).1
Darcs will create and store these patches
based on the changes you make in working.whatsnew
(as well as diff
) can show
the difference between working and pristine to you.
It will be shown as a difference in working.
In advanced cases it need not be working that has changed;
it can just as well have been pristine, or both.
The important thing is the difference and what darcs can do with it.record
it to keep it, or revert
it to lose the changes. 2whatsnew
will show some “unrecorded changes”.
To save these changes, use record
.
It will create a new patch in pristine with the same changes,
so working and pristine are no longer different.
To instead undo the changes in working, use revert
.
It will modify the files in working to be the same as in pristine
(where the changes do not exist).unrecord
is a command meant to be run only in private
repositories. Its intended purpose is to allow developers the flexibility
to undo patches that haven't been distributed yet.unrecord
a patch, that patch will be deleted from pristine.
This will cause working to be different from pristine,
and whatsnew
to report unrecorded changes.
The difference will be the same as just before that patch was record
ed.
Think about it.
record
examines what's different with working
and constructs a patch with the same changes in pristine
so they are no longer different.
unrecord
deletes this patch;
the changes in pristine disappear and the difference is back.revert
.
revert
will update working to the state of pristine,
in which the changes do no longer exist after the patch was deleted.unrecord
makes it impossible to track
what changes you really made.
Redoing the patches is how you “cover the tracks”.
On the other hand,
it can be a very convenient way to manage and organize changes
while you try them out in your private repository.
When all is ready for shipping,
the changes can be reorganized in what seems as useful and impressive patches.
Use it with care.whatsnew
or record
.
But other types of primitive patches need to be explicitly created
with a darcs command.
They are kept in pending3
until they are either recorded or reverted.replace
command,
the replace is performed on the files in working
and at the same time a replace patch is put in pending.
Patches in pending describe special changes made in working.
The diff algorithm will fictively apply these changes to pristine
before it compares it to working,
so all lines in working that are changed by a replace
command
will also be changed in pending+pristine
when the hunks are calculated.
That's why no hunks with the replaced lines will be shown by whatsnew
;
it only shows the replace patch in pending responsible for the change.revert
the addfile.
Instead use remove
, which cancels out the addfile in pending.--ask-deps
option to darcs record
.
This is good for assuring that logical dependencies hold between patches.
It can also be used to group patches—a patch with explicit dependencies doesn't need to change anything—and pulling the patch also pulls all patches it was made to depend on.get
someone's repository from the Internet,
you are actually creating a branch of it.
It may first seem inefficient (or if you come from CVS—frightening),
not to say plain awkward.
But darcs is designed this way, and it has means to make it efficient.
The answer to many questions about how to do a thing with darcs is: “use a branch”.
It is a simple and elegant solution with great power and flexibility,
which contributes to darcs' uncomplicated user interface.get
and put
commands.pull
and removed from the repositories with obliterate
.
Don't confuse these two commands with record
and unrecord
,
which constructs and deconstructs patches.pull
needs a source repository to copy the patch from,
whereas obliterate
just erases the patch.
Beware that if you obliterate all copies of a patch
it is completely lost—forever.
Therefore you should work with branches when you obliterate patches.
The obliterate
command can wisely be disabled in a dedicated main repository
by adding obliterate disable
to the repository's defaults file.push
command.
It works like pull
but in the other direction.
It also differs from pull
in an important way:
it starts a second instance of darcs to apply the patch in the target repository,
even if it's on the same computer.
It can cause surprises if you have a “wrong” darcs in your PATH.pull
and obliterate
can be used to
construct different “versions” in a repository,
it is often desirable to name specific configurations of patches
so they can be identified and retrieved easily later.
This is how darcs implements what is usually known as versions.
The command for this is tag
,
and it records a tag in the current repository.--tag
to get
you can easily get
a named version in the repository
as a new branch.mark-conflicts
.
Conflicts are marked such that both conflicting changes
are inserted with special delimiter lines around them.
Then you can merge the two changes by hand,
and remove the delimiters.mark-conflicts
for you if a conflict happens.
You can remove the markup with revert
,
Remember that the result will be the lines from
the previous version common to both conflicting patches.
The conflict marking can be redone again with mark-conflicts
.resolve
will not be able to redo this markup later if you remove it.
It is good practice to record important changes before pulling.mark-conflicts
can't mark complicated conflicts.
In that case you'll have to use darcs diff
and other commands
to understand what the conflict is all about.
If for example two conflicting patches create the same file,
mark-conflicts
will pick just one of them,
and no delimiters are inserted.
So watch out if darcs tells you about a conflict.mark-conflicts
can also be used to check for unresolved conflicts.
If there are none, darcs replies “No conflicts to resolve”.
While pull
reports when a conflict happens,
obliterate
and get
don't.mark-conflicts
)
as soon as some new patch depends on the conflicting patches.
This will usually be the resolve patch you record after manually putting together the pieces
from the conflict markup produced by mark-conflicts
(or pull
).
But it can just as well be a tag.
So don't forget to fix conflicts before you accidently “resolve” them by recording other patches.obliterate
the conflicting patch you just pulled.
Before you can do that you have to revert
the conflict markups
that pull
inserted when the conflict happened.$ mkdir -p $HOME/.darcs/cache $ echo cache:$HOME/.darcs/cache > $HOME/.darcs/sourcesIn Windows you can run just about the same commands from
cmd.exe
(Command Prompt under Accessories):
> md %UserProfile%\.darcs\cache > echo cache:%UserProfile%\.darcs\cache > %UserProfile%\.darcs\sourcesThere are some other advanced things you can do in
_darcs/prefs/sources
,
such as create per-repository caches, read-only caches and even set a
primary source repository above any used in a darcs get
or
darcs pull
command.darcs send
is ideal, since the barrier for
contributions is very low, which helps encourage contributors._darcs/prefs/email
value to the project
mailing list, but I also use darcs send to send my changes to the main
server, so instead the email address is set to
“Davids Darcs Repo <droundy@abridgegame.org>
”. My
.procmailrc
file on the server has the following rule:
:0 * ^TODavids Darcs Repo |(umask 022; darcs apply --reply darcs-devel@abridgegame.org \ --repodir /path/to/repo --verify /path/to/allowed_keys)This causes darcs apply to be run on any email sent to “Davids Darcs Repo”.
apply
actually applies them only if they are signed by an
authorized key. Currently, the only authorized key is mine, but of course
this could be extended easily enough._darcs/prefs/defaults
:
apply test apply verbose apply happy-forwardingThe first line tells apply to always run the test suite. The test suite is in fact the main reason I use send rather than push, since it allows me to easily continue working (or put my computer to sleep) while the tests are being run on the main server. The second line is just there to improve the email response that I get when a patch has either been applied or failed the tests. The third line makes darcs not complain about unsigned patches, but just to forward them to
darcs-devel
..muttrc
the following
alias, which allows me to easily apply patches that I get via email
directly to my darcs working directory:
macro pager A "<pipe-entry>(umask 022; darcs apply --no-test -v \ --repodir ~/darcs)"
http://dft.physics.cornell.edu/dft
./home
via NFS.
We created a special “dft” user, with the central repository living in that
user's home directory. The ssh public keys of authorized persons are added to
the “dft” user's .ssh/allowed_keys
, and we commit patches to this
repository using
darcs push
. As in Section ??,
we have the central repository set to run the test suite before the push goes
through.$DARCS_TMPDIR
environment variable to ~/tmp
.push
to the central repository.--complement
flag for the “darcs pull” operation can
further simplify this effort. If the developer copies (via “darcs
push” or “darcs pull”) all private patches into a special
repository/working tree (Rp), then those patches are easily
disregarded for pulling by adding --complement
to the “darcs
pull” line and listing Rp after the primary source repository.--complement
flag is only available for “darcs pull”, and
not “darcs push” or “darcs send”, requiring the user to have pull
access to the target repository. While the actual public repository
is often not shared in this manner, it's simple to create a local
version of the public repository to act as the staging area for that
public repository.$ cd working-dir $ darcs get http://server/repos/Rc Rl $ darcs get Rl R1 $ cd R1 ...development of f1 $ darcs record -m'p1: f1 initial work' ... $ darcs record -m'p2: my debugging tracepoints' ... $ cd .. $ darcs get http://server/repos/Rc R2 $ cd R2 $ darcs pull -p p2 ../R1 ... development of f2 $ darcs record -m'p3: f2 finished' $ cd .. $ darcs get Rl Rp $ cd Rp $ darcs pull -p p2 ../R2 $ cd ../Rl $ darcs pull --complement ../R2 ../Rp $ darcs send ... for publishing f2 patches to Rc $ cd ../R1 $ darcs pull ../R2 ... updates R1 with f2 changes from R2 ... more development of f1 $ darcs record -m'p4: f1 feature finished.' $ cd ../Rl $ darcs pull --complement ../R1 ../Rp $ darcs send
get
a new copy with the hashed flag:
$ darcs get --hashed old-repo new-repo
$ darcs init --darcs-2Projects in darcs 1 format ready to move all development to darcs 2 can convert an existing repository to darcs 2 format. This should be done only once per family tree of related repositories, as converting each branch separately may result in inter-repository corruption that can lead to subtle and hard to diagnose problems when attempting to exchange patches between seperately converted repositories. The recommendation is to convert the branch of a project with the largest superset of patches in the project and then recreate the branches from this superset repository via
darcs get
, particularly with the usage of its
selection flags such as --context
, --tag
and
--to-match
, and darcs obliterate
, which can be used to
interactively remove patches that are not intended in the recreated
branch.$ darcs convert d1repo d2repo
% darcs COMMAND OPTIONS ARGUMENTS ...Here
COMMAND
is a command such as add
or record
, which of
course may have one or more arguments. Options have the form
--option
or -o
, while arguments vary from command to
command. There are many options which are common to a number of different
commands, which will be summarized here.darcs record
, you could type darcs recor
or
darcs rec
, but not darcs re
since that could be confused with
darcs replace
, darcs revert
and darcs remove
.COMMAND
actually consists of two words, a
super-command and a subcommand. For example, the “display the
manifest” command has the form darcs query manifest
.affects | patches | working directory |
record | yes | no |
unrecord | yes | no |
rollback | yes | yes |
revert | no | yes |
unrevert | no | yes |
pull | yes | yes |
obliterate | yes | yes |
apply | yes | yes |
push1 | no | no |
send2 | no | no |
put3 | no | no |
|
COMMAND
accepts --help
as an argument, which tells it to
provide a bit of help. Among other things, this help always provides an
accurate listing of the options available with that command, and is
guaranteed never to be out of sync with the version of darcs you actually
have installed (unlike this manual, which could be for an entirely
different version of darcs).
% darcs COMMAND --help
|
--disable
option, which can be used in
_darcs/prefs/defaults
to disable some commands in the repository. This
can be helpful if you want to protect the repository from accidental use of
advanced commands like obliterate, unpull, unrecord or amend-record.
|
--verbose
option, which tells darcs to
provide additional output. The amount of verbosity varies from command to
command. Commands that accept --verbose\verb
also accept --quiet\verb
,
which surpresses non-error output, and --normal-verbosity\verb
which can be
used to restore the default verbosity if --verbose
or --quiet
is in
the defaults file.
|
--debug
option, which causes darcs to generate
additional output that may be useful for debugging its behavior, but which otherwise
would not be interesting. Option --debug-http
makes darcs output debugging
info for curl and libwww.
|
--repodir
option, which allows you to
specify the directory of the repository in which to perform the command.
This option is used with commands, such as whatsnew, that ordinarily would
be performed within a repository directory, and allows you to use those
commands without actually being in the repository directory when calling the
command. This is useful when running darcs in a pipe, as might be the case
when running apply
from a mailer.
|
pull
require a remote repository to be specified,
either from the command line or as a default. The --remote-repo
provides an alternative way to supply this remote repository path. This flag
can be seen as temporarily “replacing” the default repository. Setting it
causes the command to ignore the default repository (it also does not affect,
i.e. overwrite the default repository). On the other hand, if any other
repositories are supplied as command line arguments, this flag will be ignored
(and the default repository may be overwritten).--patch
, --match
, --tag
, and variants
on these, which for --patch
are --patches
,
--from-patch
, and --to-patch
. The --patch
and
--tag
forms simply take (POSIX extended, aka egrep
) regular
expressions and match them against tag and patch names. --match
,
described below, allows more powerful patterns.darcs pull --patches bugfix
means “pull all the patches with `bugfix' in their name, along with any
patches they require.” If you really only want patches with `bugfix' in
their name, you should use the --no-deps
option, which makes darcs
exclude any matched patches from the selection which have dependencies that
are themselves not explicitly matched by the selection.unrecord
, unpull
and obliterate
, patches that
depend on the selected patches are silently included, or if
--no-deps
is used selected patches with dependencies on not selected
patches are excluded from the selection.--match
accepts six primitive match types, although
there are plans to expand it to match more patterns. Also, note that the
syntax is still preliminary and subject to change.darcs annotate --summary --match 'exact foo+bar'This is useful for situations where a patch name contains characters that could be considered special for regular expressions.
darcs annotate --summary --match 'name foo'Note that to match regexp metacharacters, such as
(
, literally, they
must be escaped with backslash along with any embedded double quotes. To
match a literal backslash it must be written quadrupled in general, but often
it need not be escaped, since backslash is only special in regexps when
followed by a metacharacter. In the following example pairs, the first
literal is matched by the second sequence in the match name:
“"
”:“\"
”, “\
”:“\\\\
”,
“\x
”:“\x
”, “(
”:“\(
”.darcs annotate --summary --match \ 'hash 20040403105958-53a90-c719567e92c3b0ab9eddd5290b705712b8b918ef'Note you need to provide the full hash string as above. This is intended to be used, for example, by programs allowing you to view darcs repositories (e.g. CGI scripts like viewCVS).
darcs annotate --summary --match 'author foo'There is also support for matching by date. This is done using commands such as
darcs annotate --summary --match 'date "last week"' darcs annotate --summary --match 'date yesterday' darcs annotate --summary --match 'date "today 14:00"' darcs annotate --summary --match 'date "tea time yesterday"' darcs annotate --summary --match 'date "3 days before last year at 17:00"' darcs changes --from-match 'date "Sat Jun 30 11:31:30 EDT 2004"'Notes: when matching on the ISO format, a partial date is treated as a range. English dates can either refer to a specific day (“6 months ago',“day before yesterday”), or to an interval from some past date (“last month”) to the present. Putting this all together, if today is “2004-07-24” then the following matches should work:
date | patches selected |
2004 | from 2004-01-01 up to and including 2004-12-31 |
2004-01 | from 2004-01-01 up to and including 2004-01-31 |
2004-01-01 | during 2004-01-01 |
today | during 2004-07-24 (starting midnight in your timezone) |
yesterday | during 2004-07-23 |
6 months ago | during 2004-01-23 |
last 6 months | since 2004-01-23 |
last month | since 2004-06-23 (not 2004-06-01!) |
last week | since 2004-07-16 |
darcs annotate --summary --match 'date "between 2004-03-12 and last week"' darcs annotate --summary --match 'date "after 2005"' darcs annotate --summary --match 'date "in the last 3 weeks"' darcs annotate --summary --match 'date "P3M/2006-03-17"' darcs annotate --summary --match 'date "2004-01-02/2006-03-17"' darcs annotate --summary --match 'date "P2M6D"'You may also prefer to combine date matching with a more specific pattern.
darcs annotate --summary --match 'date "last week" && name foo'The sixth match type accepts a regular expression which is checked against file paths that the patch touches. The syntax is
darcs annotate --summary --match 'touch foo/bar.c'The
--match
pattern can include the logical operators &&
,
||
and not
, as well as grouping of patterns with parentheses.
For example
darcs annotate --summary --match 'name record && not name overrode'
|
whatsnew
and record
which would otherwise require reading
every file in the repository and comparing it with a reference version. However,
there are times when this can cause problems, such as when running a series
of darcs commands from a script, in which case often a file will be
modified twice in the same second, which can lead to the second
modification going unnoticed. The solution to such predicaments is the
--ignore-times
option, which instructs darcs not to trust the file
modification times, but instead to check each file's contents explicitly.
|
David Roundy <droundy@abridgegame.org>
. The easiest way to do
this is
to define an environment variable EMAIL
or DARCS_EMAIL
(with
the latter overriding the former). You can also override this using the
--author
flag to any command. Alternatively, you could set your
email address on a per-repository basis using the “defaults” mechanism
for “ALL” commands, as described in Appendix ??.
Or, you could specify the author on a per-repository basis using the
_darcs/prefs/author
file as described in section ??..darcs/author
. This file overrides the
contents of the environment variables, but a repository-specific author
file overrides the global author file.
|
--dont-compress
option, which causes darcs not to compress the patch
file.
|
--dry-run
option will cause darcs not to actually take the specified
action, but only print what would have happened. Not all commands accept
--dry-run
, but those that do should accept the --summary
option.
|
--summary
option shows a summary of the patches that would have been
pulled/pushed/whatever. The format is similar to the output format of
cvs update
and looks like this:
A ./added_but_not_recorded.c A! ./added_but_not_recorded_conflicts.c a ./would_be_added_if_look_for_adds_option_was_used.h M ./modified.t -1 +1 M! ./modified_conflicts.t -1 +1 R ./removed_but_not_recorded.c R! ./removed_but_not_recorded_conflicts.cYou can probably guess what the flags mean from the clever file names.
--look-for-adds
option available for
whatsnew
and record
. They have not been added yet, but would be
added automatically if --look-for-adds
were used with the next
record
command.--external-merge 'opendiff %1 %2 -ancestor %a -merge %o'The
%1
and %2
are replaced with the two versions to be
merged, %a
is replaced with the common ancestor of the two versions.
Most importantly, %o
is replaced with the name of the output file
that darcs will require to be created holding the merged version. The
above example works with the FileMerge.app tool that comes with Apple's
developer tools. To use xxdiff, you would use
--external-merge 'xxdiff -m -O -M %o %1 %a %2'To use
kdiff3
, you can use
--external-merge 'kdiff3 --output %o %a %1 %2'To use
tortoiseMerge
, you can use
--external-merge 'tortoiseMerge /base:"%a" /mine:"%1" /theirs:"%2" /merged:"%o"'(
tortoiseMerge
is a nice merge tool that comes with TortoiseSVN and works well
on Windows.)exec
ed with the rest as arguments—it is not a shell command. In particular,
on Windows this means that the first command path should not contain spaces and
you should make sure the command is in your PATH
. %
escapes is done everywhere. If you need to prevent
substitution you can use a double percentage sign, i.e. %%a
is substituted with
%a
. Here is an example script to use the Emacs' Ediff package for merging.
#! /bin/sh # External merge command for darcs, using Emacs Ediff, via server if possible. # It needs args %1 %2 %a %o, i.e. the external merge command is, say, # `emerge3 %1 %2 %a %o'. test $# -eq 4 || exit 1 form="(ediff-merge-files-with-ancestor" while test $# -gt 0; do count=$count. if [ $count = .... ]; then form=$form\ nil # Lisp STARTUP-HOOKS arg fi case $1 in # Worry about quoting -- escape " and \ *[\"\\]* ) form=$form\ \"$(echo $1 | sed -e's/["\\]/\\\0/g')\" ;; *) form=$form\ \"$1\" ;; esac shift done form=$form')' ( emacsclient --eval "$form" || # Emacs 22 server gnudoit "$form" || # XEmacs/Emacs 21 server emacs --eval "$form" || # Relatively slow to start up xemacs -eval "$form" # Horribly slow to start up ) 2>/dev/nullIt would be invoked like:
--external-merge 'emerge3 %1 %2 %a %o'If you figure out how to use darcs with another merge tool, please let me know what flags you used so I can mention it here.
_darcs/prefs/defaults
or ~/.darcs/prefs
, see ??)
a line such as
ALL external-merge kdiff3 --output %o %a %1 %2or
ALL external-merge tortoiseMerge /base:"%a" /mine:"%1" /theirs:"%2" /merged:"%o"Note that the defaults file does not want quotes around the command.
|
--posthook
to specify the command. This is useful
for people who want to have a command run whenever a patch is applied. Using
--no-posthook
will disable running the command.
|
--prompt-posthook
to force prompting before running the
posthook command. For security reasons, this is the default. When
defining a posthook for apply, you will need to use
--run-posthook
or else you will get an error, because the
subprocess which runs the apply command cannot prompt the user.DARCS_PATCHES
contains a human-readable summary of the patches being
acted upon. The format is the same as "darcs changes". DARCS_PATCHES_XML
Contains the same details, in the same XML format as "darcs changes". Finally,
DARCS_FILES
contains a list of the files affected, one file per line.
If your repository has filenames including newlines, you'll just have to
cope. Note, however, that none of these environment variables are
defined when running under windows. Note also that we refuse to pass
environment variables greater in size than 10k, in order to avoid triggering
E2BIG
errors.
|
--prehook
to specify the command. An example use is
for people who want to have a command run whenever a patch is to be recorded, such as
translating line endings before recording patches. Using
--no-prehook
will disable running the command.
|
--prompt-prehook
to force prompting before running the
prehook command. For security reasons, this is the default.
|
|
|
|
--umask
will cause Darcs to switch to a different umask before
writing to the repository.
|
ALL dont-restrict-paths
in _darcs/prefs/defaults
. This turns
off all sanity checking for file paths in patches.--restrict-paths
on
the command line, when pulling or applying unknown patches.
|
|
--help
as an argument gives a brief
summary of what commands are available.
The --overview
option gives a more technical summary of
what the commands actually do.
|
--version
tells you the version of
darcs you are using. Calling darcs with the flag --exact-version
gives the precise version of darcs, even if that version doesn't correspond
to a released version number. This is helpful with bug reports, especially
when running with a “latest” version of darcs.
|
--commands
gives a simple list
of available commands. This latter arrangement is primarily intended for
the use of command-line autocompletion facilities, as are available in
bash.help
as a command. This is equivalent to calling
darcs –help.
the --help
to that command. For example, darcs help query manifest
is equivalent to darcs query manifest --help
.Usage: darcs help [OPTION]... [<DARCS_COMMAND> [DARCS_SUBCOMMAND]]
--match |
shows a summary of how to use patch matching rules |
Usage: darcs initialize [OPTION]...
--plain-pristine-tree |
use a plain pristine tree [DEFAULT] |
|
--no-pristine-tree |
use no pristine tree |
|
--hashed |
Some new features. Compatible with older repos |
|
--darcs-2 |
All features. Related repos must use same format [DEFAULT] |
|
--old-fashioned-inventory |
Minimal features. What older repos use. |
|
--repodir DIRECTORY |
specify the repository directory in which to run |
initialize
once for each project you work on. Run it from the top
level directory of the project, with the project files already there.
initialize
will set up all the directories and files darcs needs in order to
start keeping track of revisions for your project.initialize
creates a single directory named _darcs
, with contents
for internal use. The one subdictory of interest to users is
_darcs/prefs
, which will include an empty file _darcs/prefs/motd
(see Section ??), as well as files named boring
and
binaries
, which contain useful defaults as described in Sections
?? et seq.
|
old-fashioned-inventory
is the default. While it has minimal features, it is the best tested and the limitations
it does have are well known.hashed
Offers several features while still being compatible with old-fashioned repositories. The specific features are:
_darcs/pristine
directory no longer holds the pristine
cache. This disallows certain hackish short-cuts, but also dramatically
reduces the danger of third-party programs (e.g. DreamWeaver) recursing
into the pristine cache and corrupting darcs repositories.^C
). Secondly, if the source repository disappears,
or you lose network connectivity, some operations may fail.darcs-2
Enables all available features, and requiring that all repos for a project use the same format. In addition to the features of the hashed
format described above, the darcs-2
format also enables the following:
|
initialize
with the
--no-pristine-tree
flag to create a repository with no pristine
tree. Please see Section ?? for more information.Usage: darcs get [OPTION]... <REPOSITORY> [<DIRECTORY>]
--repo-name DIRECTORY |
path of output directory |
|
--partial |
get partial repository using checkpoint (old-fashioned format only) |
|
--lazy |
get patch files only as needed |
|
--ephemeral |
don't save patch files in the repository |
|
--complete |
get a complete copy of the repository |
|
--to-match PATTERN |
select changes up to a patch matching PATTERN |
|
--to-patch REGEXP |
select changes up to a patch matching REGEXP |
|
-t |
--tag REGEXP |
select tag matching REGEXP |
--context FILENAME |
version specified by the context in FILENAME |
|
--set-default |
set default repository [DEFAULT] |
|
--no-set-default |
don't set default repository |
|
--set-scripts-executable |
make scripts executable |
|
--dont-set-scripts-executable |
don't make scripts executable |
|
--nolinks |
do not link repository or pristine to sibling |
|
--plain-pristine-tree |
use a plain pristine tree [DEFAULT] |
|
--no-pristine-tree |
use no pristine tree |
|
--hashed |
Convert darcs-1 format to hashed format |
|
--old-fashioned-inventory |
Convert from hashed to darcs-1 format |
|
--repodir DIRECTORY |
specify the repository directory in which to run |
--ssh-cm |
use SSH ControlMaster feature |
|
--no-ssh-cm |
don't use SSH ControlMaster feature [DEFAULT] |
|
--http-pipelining |
enable HTTP pipelining |
|
--no-http-pipelining |
disable HTTP pipelining [DEFAULT] |
|
--no-cache |
don't use patch caches |
darcs get
to get yourself one copy, and then
running darcs get
on that copy to make any more you like. The only
catch is that the first time you run darcs push
or darcs pull
from any of these second copies, by default they will access your first
copy—which may not be what you want.
|
--tag
, --to-patch
or
--to-match
options, or you can use the --context=FILENAME
option, which specifies a file containing a context generated with
darcs changes --context
. This allows you (for example) to include in
your compiled program an option to output the precise version of the
repository from which it was generated, and then perhaps ask users to
include this information in bug reports.--to-patch
or --to-match
, you may
get a version of your code that has never before been seen, if the patches
have gotten themselves reordered. If you ever want to be able to precisely
reproduce a given version, you need either to tag it or create a context
file.
|
|
--no-pristine-tree
flag to create a repository with no pristine
tree. Please see Section ?? for more information.Usage: darcs put [OPTION]... <NEW REPOSITORY>
--to-match PATTERN |
select changes up to a patch matching PATTERN |
|
--to-patch REGEXP |
select changes up to a patch matching REGEXP |
|
-t |
--tag REGEXP |
select tag matching REGEXP |
--context FILENAME |
version specified by the context in FILENAME |
|
--set-scripts-executable |
make scripts executable |
|
--dont-set-scripts-executable |
don't make scripts executable |
|
--hashed |
Convert darcs-1 format to hashed format |
|
--old-fashioned-inventory |
Convert from hashed to darcs-1 format |
|
--set-default |
set default repository [DEFAULT] |
|
--no-set-default |
don't set default repository |
|
--repodir DIRECTORY |
specify the repository directory in which to run |
--apply-as USERNAME |
apply patch as another user using sudo |
|
--apply-as-myself |
don't use sudo to apply as another user [DEFAULT] |
|
--ssh-cm |
use SSH ControlMaster feature |
|
--no-ssh-cm |
don't use SSH ControlMaster feature [DEFAULT] |
|
--http-pipelining |
enable HTTP pipelining |
|
--no-http-pipelining |
disable HTTP pipelining [DEFAULT] |
|
--no-cache |
don't use patch caches |
darcs init
there. After the new repository is created
all selected patches will be pushed just as with the command
push
.
|
--apply-as
flag, darcs will use sudo to apply the
changes 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.
|
--tag
, --to-patch
or
--to-match
options, or you can use the --context=FILENAME
option, which specifies a file containing a context generated with
darcs changes --context
. This allows you (for example) to include in
your compiled program an option to output the precise version of the
repository from which it was generated, and then perhaps ask users to
include this information in bug reports.--to-patch
or --to-match
, you may
get a version of your code that has never before been seen, if the patches
have gotten themselves reordered. If you ever want to be able to precisely
reproduce a given version, you need either to tag it or create a context
file.Usage: darcs add [OPTION]... <FILE or DIRECTORY> ...
--boring |
don't skip boring files |
|
--case-ok |
don't refuse to add files differing only in case |
|
--reserved-ok |
don't refuse to add files with Windows-reserved names |
|
-r |
--recursive |
add contents of subdirectories |
--not-recursive |
don't add contents of subdirectories |
|
--date-trick |
add files with date appended to avoid conflict [EXPERIMENTAL] |
|
--no-date-trick |
don't use experimental date appending trick [DEFAULT] |
|
--repodir DIRECTORY |
specify the repository directory in which to run |
|
--dry-run |
don't actually take the action |
--umask UMASK |
specify umask to use when writing |
|
--boring
option.
|
--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.Usage: darcs remove [OPTION]... <FILE or DIRECTORY> ...
--repodir DIRECTORY |
specify the repository directory in which to run |
--umask UMASK |
specify umask to use when writing |
Usage: darcs mv [OPTION]... [FILE or DIRECTORY]...
--case-ok |
don't refuse to add files differing only in case |
|
--reserved-ok |
don't refuse to add files with Windows-reserved names |
|
--repodir DIRECTORY |
specify the repository directory in which to run |
--umask UMASK |
specify umask to use when writing |
|
--case-ok
.Usage: darcs replace [OPTION]... <OLD> <NEW> <FILE> ...
--token-chars "[CHARS]" |
define token to contain these characters |
|
-f |
--force |
proceed with replace even if 'new' token already exists |
--no-force |
don't force the replace if it looks scary |
|
--repodir DIRECTORY |
specify the repository directory in which to run |
--ignore-times |
don't trust the file modification times |
|
--umask UMASK |
specify umask to use when writing |
[A-Za-z_0-9]
), and if one of your tokens
contains a `-
' or `.
', you will then (by default) get the “filename”
regexp, which is [A-Za-z_0-9\-\.]
.
|
--token-chars
option. You may prefer to define tokens in terms
of delimiting characters instead of allowed characters using a flag such as
--token-chars '[^ \n\t]'
, which would define a token as being
white-space delimited._darcs/prefs/defaults
to always specify the same
--token-chars
, since your replace patches will be better behaved (in
terms of commutation and merges) if they have tokens defined in the same
way.% darcs replace newtoken aaack ./foo.c % darcs replace oldtoken newtoken ./foo.c % darcs recordwill be valid, even if
newtoken
and oldtoken
are both present
in the recorded version of foo.c, while the sequence
% [manually edit foo.c replacing newtoken with aaack] % darcs replace oldtoken newtoken ./foo.cwill fail because “newtoken” still exists in the recorded version of
foo.c
. The reason for the difference is that when recording, a
“replace” patch always is recorded before any manual changes,
which is usually what you want, since often you will introduce new
occurrences of the “newtoken” in your manual changes. In contrast,
multiple “replace” changes are recorded in the order in which
they were made.Usage: darcs record [OPTION]... [FILE or DIRECTORY]...
-m |
--patch-name PATCHNAME |
name of patch |
-A |
--author EMAIL |
specify author id |
--no-test |
don't run the test script |
|
--test |
run the test script |
|
--leave-test-directory |
don't remove the test directory |
|
--remove-test-directory |
remove the test directory |
|
-a |
--all |
answer yes to all patches |
--pipe |
ask user interactively for the patch metadata |
|
-i |
--interactive |
prompt user interactively |
--ask-deps |
ask for extra dependencies |
|
--no-ask-deps |
don't ask for extra dependencies |
|
--edit-long-comment |
edit the long comment by default |
|
--skip-long-comment |
don't give a long comment |
|
--prompt-long-comment |
prompt for whether to edit the long comment |
|
-l |
--look-for-adds |
look for (non-boring) files that could be added |
--dont-look-for-adds |
don't look for any files that could be added [DEFAULT] |
|
--repodir DIRECTORY |
specify the repository directory in which to run |
--logfile FILE |
give patch name and comment in file |
|
--delete-logfile |
delete the logfile when done |
|
--compress |
create compressed patches |
|
--dont-compress |
don't create compressed patches |
|
--ignore-times |
don't trust the file modification times |
|
--umask UMASK |
specify umask to use when writing |
|
--set-scripts-executable |
make scripts executable |
|
--dont-set-scripts-executable |
don't make scripts executable |
DARCS_EMAIL
environment variable, and if that doesn't
exist, from the EMAIL
environment variable. The date on which the
patch was recorded is also included. Currently there is no provision for
keeping track of when a patch enters a given repository.
Finally, each changeset should have a full log (which may be empty). This
log is for detailed notes which are too lengthy to fit in the name. If you
answer that you do want to create a comment file, darcs will open an editor
so that you can enter the comment in. The choice of editor proceeds as
follows. If one of the $DARCS_EDITOR
, $VISUAL
or
$EDITOR
environment variables is defined, its value is used (with
precedence proceeding in the order listed). If not, “vi”, “emacs”,
“emacs -nw” and “nano” are tried in that order.
|
--logfile
flag. If you do so, the first line of the specified file
will be taken to be the patch name, and the remainder will be the “long
comment”. This feature can be especially handy if you have a test that
fails several times on the record (thus aborting the record), so you don't
have to type in the long comment multiple times. The file's contents will
override the --patch-name
option.
|
--ask-deps
flag, and darcs will ask you for the patch's
dependencies.darcs tag
command will record a patch
with no actual changes but which depends on the entire current
inventory of the repository. The darcs record --ask-deps
with
no selected changes will record a patch that depends on only those
patches selected via the --ask-deps
operation, resulting in a
patch which describes a set of patches; the presence of this primary
patch in a repository implies the presence of (at least) the
depended-upon patches.
|
--no-test
) to skip the test.
|
--set-scripts-executable
to darcs record
, darcs will set scripts
executable in the test directory before running the test.
|
--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 (ctrl-D on Unixy systems, ctrl-Z
on systems running a Microsoft OS).--pipe
prompts look like:
What is the date? Mon Nov 15 13:38:01 EST 2004 Who is the author? David Roundy What is the log? One or more comment lines
|
record
works interactively. Probably the only thing you need
to know about using this is that you can press ?
at the prompt to be
shown a list of the rest of the options and what they do. The rest should be
clear from there. Here's a
“screenshot” to demonstrate:
hunk ./hello.pl +2 +#!/usr/bin/perl +print "Hello World!\n"; Shall I record this patch? (2/2) [ynWsfqadjk], or ? for help: ? How to use record... y: record this patch n: don't record it w: wait and decide later, defaulting to no s: don't record the rest of the changes to this file f: record the rest of the changes to this file d: record selected patches a: record all the remaining patches q: cancel record j: skip to next patch k: back up to previous patch h or ?: show this help <Space>: accept the current default (which is capitalized)What you can't see in that “screenshot” is that
darcs
will also try to use
color in your terminal to make the output even easier to read.Usage: darcs pull [OPTION]... [REPOSITORY]...
--matches PATTERN |
select patches matching PATTERN |
|
-p |
--patches REGEXP |
select patches matching REGEXP |
-t |
--tags REGEXP |
select tags matching REGEXP |
-a |
--all |
answer yes to all patches |
-i |
--interactive |
prompt user interactively |
--mark-conflicts |
mark conflicts [DEFAULT] |
|
--allow-conflicts |
allow conflicts, but don't mark them |
|
--dont-allow-conflicts |
fail on patches that create conflicts |
|
--external-merge COMMAND |
use external tool to merge conflicts |
|
--test |
run the test script |
|
--no-test |
don't run the test script |
|
--dry-run |
don't actually take the action |
|
--xml-output |
generate XML formatted output |
|
-s |
--summary |
summarize changes |
--no-summary |
don't summarize changes |
|
--no-deps |
don't automatically fulfill dependencies |
|
--set-default |
set default repository [DEFAULT] |
|
--no-set-default |
don't set default repository |
|
--repodir DIRECTORY |
specify the repository directory in which to run |
|
--ignore-unrelated-repos |
do not check if repositories are unrelated |
--intersection |
take intersection of all repositories |
|
--union |
take union of all repositories [DEFAULT] |
|
--complement |
take complement of repositories (in order listed) |
|
--compress |
create compressed patches |
|
--dont-compress |
don't create compressed patches |
|
--nolinks |
do not link repository or pristine to sibling |
|
--ignore-times |
don't trust the file modification times |
|
--remote-repo URL |
specify the remote repository URL to work with |
|
--set-scripts-executable |
make scripts executable |
|
--dont-set-scripts-executable |
don't make scripts executable |
|
--umask UMASK |
specify umask to use when writing |
|
--ssh-cm |
use SSH ControlMaster feature |
|
--no-ssh-cm |
don't use SSH ControlMaster feature [DEFAULT] |
|
--http-pipelining |
enable HTTP pipelining |
|
--no-http-pipelining |
disable HTTP pipelining [DEFAULT] |
|
--no-cache |
don't use patch caches |
|
--complement
,
--intersection
, and --union
flags.
--union
) behavior is to pull any patches
that are in any of the specified repositories (R1 ∪R2
∪R3 …).--intersection
flag, darcs
will only pull those patches which are present in all source
repositories (R1 ∩R2 ∩R3 …).--complement
flag, darcs will only
pull elements in the first repository that do not exist in any of the
remaining repositories4 (R1
\ (R2 ∪R3 ∪…)).
|
--external-merge
. For more details see
subsection ??.
|
--patches
, --matches
, --tags
, and --no-deps
options can be used to select which patches to pull, as described in
subsection ??.
|
--test
option, pull will run the test (if a test
exists) on a scratch copy of the repository contents prior to actually performing
the pull. If the test fails, the pull will be aborted.
|
--verbose
option causes another section to appear in the
output which also displays a summary of patches that you have and the remote
repository lacks. Thus, the following syntax can be used to show you all the patch
differences between two repositories:
darcs pull --dry-run --verbose
Usage: darcs push [OPTION]... [REPOSITORY]
--matches PATTERN |
select patches matching PATTERN |
|
-p |
--patches REGEXP |
select patches matching REGEXP |
-t |
--tags REGEXP |
select tags matching REGEXP |
--no-deps |
don't automatically fulfill dependencies |
|
-a |
--all |
answer yes to all patches |
-i |
--interactive |
prompt user interactively |
--sign |
sign the patch with your gpg key |
|
--sign-as KEYID |
sign the patch with a given keyid |
|
--sign-ssl IDFILE |
sign the patch using openssl with a given private key |
|
--dont-sign |
don't sign the patch |
|
--dry-run |
don't actually take the action |
|
--xml-output |
generate XML formatted output |
|
-s |
--summary |
summarize changes |
--no-summary |
don't summarize changes |
|
--repodir DIRECTORY |
specify the repository directory in which to run |
|
--set-default |
set default repository [DEFAULT] |
|
--no-set-default |
don't set default repository |
|
--ignore-unrelated-repos |
do not check if repositories are unrelated |
--apply-as USERNAME |
apply patch as another user using sudo |
|
--apply-as-myself |
don't use sudo to apply as another user [DEFAULT] |
|
--nolinks |
do not link repository or pristine to sibling |
|
--remote-repo URL |
specify the remote repository URL to work with |
|
--ssh-cm |
use SSH ControlMaster feature |
|
--no-ssh-cm |
don't use SSH ControlMaster feature [DEFAULT] |
|
--http-pipelining |
enable HTTP pipelining |
|
--no-http-pipelining |
disable HTTP pipelining [DEFAULT] |
|
--no-cache |
don't use patch caches |
DARCS_SSH
environment variable
(see subsection ??). The command invoked via ssh is always
darcs
, i.e. the darcs executable must be in the default path on
the remote machine.--test
) will affect the behavior of push. This also means
that push is somewhat less efficient than pull.bash: darcs: command not foundthen this means that the darcs on the remote machine could not be started. Make sure that the darcs executable is called
darcs
and is found in the default path. The default path can
be different in interactive and in non-interactive shells. Say
ssh login@remote.machine darcsto try whether the remote darcs can be found, or
ssh login@remote.machine 'echo $PATH'(note the single quotes) to check the default path.
|
--apply-as
flag, darcs will use sudo to apply the
changes 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.
|
--patches
, --matches
, --tags
, and --no-deps
options can be used to select which patches to push, as described in
subsection ??.apply
in the target repository. Most commonly, for
pushed-to repositories, you'd like to have --dont-allow-conflicts
as
a default option to apply (by default, it is already the default...). If
this is the case, when there are conflicts on push, darcs will fail with an
error message. You can then resolve by pulling the conflicting patch,
recording a resolution and then pushing the resolution together with the
conflicting patch.--allow-conflicts
.
In this case conflicting patches will be applied, but the conflicts will
not be marked in the working directory.--mark-conflicts
specified as a
default flag for apply in the target repository, when there is a conflict,
it will be marked in the working directory of the target repository. In
this case, you should resolve the conflict in the target repository itself.Usage: darcs send [OPTION]... [REPOSITORY]
--matches PATTERN |
select patches matching PATTERN |
|
-p |
--patches REGEXP |
select patches matching REGEXP |
-t |
--tags REGEXP |
select tags matching REGEXP |
--no-deps |
don't automatically fulfill dependencies |
|
-a |
--all |
answer yes to all patches |
-i |
--interactive |
prompt user interactively |
--from EMAIL |
specify email address |
|
-A |
--author EMAIL |
specify author id |
--to EMAIL |
specify destination email |
|
--cc EMAIL |
mail results to additional EMAIL(s). Requires –reply |
|
--subject SUBJECT |
specify mail subject |
|
-o |
--output FILE |
specify output filename |
-O |
--output-auto-name[=DIRECTORY] |
output to automatically named file in DIRECTORY, default: current directory |
--sign |
sign the patch with your gpg key |
|
--sign-as KEYID |
sign the patch with a given keyid |
|
--sign-ssl IDFILE |
sign the patch using openssl with a given private key |
|
--dont-sign |
don't sign the patch |
|
--dry-run |
don't actually take the action |
|
--xml-output |
generate XML formatted output |
|
-s |
--summary |
summarize changes |
--no-summary |
don't summarize changes |
|
--edit-description |
edit the patch bundle description |
|
--dont-edit-description |
don't edit the patch bundle description |
|
--set-default |
set default repository [DEFAULT] |
|
--no-set-default |
don't set default repository |
|
--repodir DIRECTORY |
specify the repository directory in which to run |
|
--sendmail-command COMMAND |
specify sendmail command |
|
--ignore-unrelated-repos |
do not check if repositories are unrelated |
--logfile FILE |
give patch name and comment in file |
|
--delete-logfile |
delete the logfile when done |
|
--remote-repo URL |
specify the remote repository URL to work with |
|
--context FILENAME |
send to context stored in FILENAME |
|
--ssh-cm |
use SSH ControlMaster feature |
|
--no-ssh-cm |
don't use SSH ControlMaster feature [DEFAULT] |
|
--http-pipelining |
enable HTTP pipelining |
|
--no-http-pipelining |
disable HTTP pipelining [DEFAULT] |
|
--no-cache |
don't use patch caches |
--author
options with the return address
that darcs send
will set for your patch bundle.--author A
but your machine is configured to send mail from
address B by default, then the return address on your message will be B.--from A
and your mail client supports setting the
From: address arbitrarily (some non-Unix-like mail clients, especially,
may not support this), then the return address will be A; if it does
not support this, then the return address will be B.--from
nor --author
, then the return
address will be B.
--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.
|
--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._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.
|
--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.
|
--patches
, --matches
, --tags
, and --no-deps
options can be used to select which patches to send, as described in
subsection ??.
|
--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.
|
--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:
evolution "mailto:%T?subject=%S&attach=%A&cc=%C&body=%B" msmtp -t %<
Usage: darcs apply [OPTION]... <PATCHFILE>
--verify PUBRING |
verify that the patch was signed by a key in PUBRING |
|
--verify-ssl KEYS |
verify using openSSL with authorized keys from file KEYS |
|
--no-verify |
don't verify patch signature |
|
-a |
--all |
answer yes to all patches |
-i |
--interactive |
prompt user interactively |
--dry-run |
don't actually take the action |
|
--xml-output |
generate XML formatted output |
|
--mark-conflicts |
mark conflicts |
|
--allow-conflicts |
allow conflicts, but don't mark them |
|
--no-resolve-conflicts |
equivalent to –dont-allow-conflicts, for backwards compatibility |
|
--dont-allow-conflicts |
fail on patches that create conflicts [DEFAULT] |
|
--external-merge COMMAND |
use external tool to merge conflicts |
|
--no-test |
don't run the test script |
|
--test |
run the test script |
|
--leave-test-directory |
don't remove the test directory |
|
--remove-test-directory |
remove the test directory |
|
--repodir DIRECTORY |
specify the repository directory in which to run |
--reply FROM |
reply to email-based patch using FROM address |
|
--cc EMAIL |
mail results to additional EMAIL(s). Requires –reply |
|
--happy-forwarding |
forward unsigned messages without extra header |
|
--sendmail-command COMMAND |
specify sendmail command |
|
--ignore-times |
don't trust the file modification times |
|
--compress |
create compressed patches |
|
--dont-compress |
don't create compressed patches |
|
--set-scripts-executable |
make scripts executable |
|
--dont-set-scripts-executable |
don't make scripts executable |
|
--umask UMASK |
specify umask to use when writing |
|
--verify PUBRING
option, darcs will check that
the patch was GPG-signed by a key which is in PUBRING
and will
refuse to apply the patch otherwise.
|
--reply FROM
option to darcs apply
, it will send the
results of the application to the sender of the patch. This only works if
the patch is in the form of email with its headers intact, so that darcs
can actually know the origin of the patch. The reply email will indicate
whether or not the patch was successfully applied. The FROM
flag is
the email address that will be used as the “from” address when replying.
If the darcs apply is being done automatically, it is important that this
address not be the same as the address at which the patch was received, in
order to avoid automatic email loops.--cc
option to specify additional recipients. Note that the
--cc
option requires the --reply
option, which
provides the “From” address.--reply
feature of apply is intended primarily for two uses.
When used by itself, it is handy for when you want to apply patches sent to
you by other developers so that they will know when their patch has been
applied. For example, in my .muttrc
(the config file for my mailer)
I have:
macro pager A "<pipe-entry>darcs apply --verbose \ --reply droundy@abridgegame.org --repodir ~/darcswhich allows me to apply a patch to darcs directly from my mailer, with the originator of that patch being sent a confirmation when the patch is successfully applied. NOTE: In an attempt to make sure no one else can read your email, mutt seems to set the umask such that patches created with the above macro are not world-readable, so use it with care.
--verify
option, the
--reply
option allows for a nice pushable repository. When these
two options are used together, any patches that don't pass the verify will
be forwarded to the FROM
address of the --reply
option. This
allows you to set up a repository so that anyone who is authorized can push
to it and have it automatically applied, but if a stranger pushes to it,
the patch will be forwarded to you. Please (for your own sake!) be certain
that the --reply FROM
address is different from the one used to send
patches to a pushable repository, since otherwise an unsigned patch will be
forwarded to the repository in an infinite loop.darcs apply --verify PUBRING --reply
to create a
pushable repository by applying patches automatically as they are received by
email, you will also want to use the --dont-allow-conflicts
option.
|
--dont-allow-conflicts
flag causes apply to fail when applying a
patch would cause conflicts. This flag is recommended on repositories
which will be pushed to or sent to.
|
--allow-conflicts
will allow conflicts, but will keep the local and
recorded versions in sync on the repository. This means the conflict will exist
in both locations until it is resolved.
|
--mark-conflicts
will add conflict markers to illustrate the the
conflict.
|
--external-merge
. For more details see
subsection ??.
|
--interactive
flag, darcs will
ask you for each change in the patch bundle whether or not you wish to
apply that change. The opposite is the --all
flag, which can be
used to override an interactive
which might be set in your
“defaults” file.
|
--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:
msmtp -t %<
|
--test
option, apply will run the test (if a test
exists) prior to applying the patch. If the test fails, the patch is not
applied. In this case, if the --reply
option was used, the results
of the test are sent in the reply email. You can also specify the
--no-test
option, which will override the --test
option, and
prevent the test from being run. This is helpful when setting up a
pushable repository, to keep users from running code.Usage: darcs whatsnew [OPTION]... [FILE or DIRECTORY]...
-s |
--summary |
summarize changes |
--no-summary |
don't summarize changes |
|
-u |
--unified |
output patch in a darcs-specific format similar to diff -u |
-l |
--look-for-adds |
look for (non-boring) files that could be added |
--dont-look-for-adds |
don't look for any files that could be added [DEFAULT] |
|
--repodir DIRECTORY |
specify the repository directory in which to run |
--ignore-times |
don't trust the file modification times |
|
--boring |
don't skip boring files |
darcs whatsnew
will return a non-zero value if
there are no changes, which can be useful if you just want to see in a
script if anything has been modified. If you want to see some context
around your changes, you can use the -u
option, to get output
similar to the unidiff format.whatsnew
, darcs will output only changes to those files or to files in
those directories.Usage: darcs changes [OPTION]... [FILE or DIRECTORY]...
--to-match PATTERN |
select changes up to a patch matching PATTERN |
|
--to-patch REGEXP |
select changes up to a patch matching REGEXP |
|
--to-tag REGEXP |
select changes up to a tag matching REGEXP |
|
--from-match PATTERN |
select changes starting with a patch matching PATTERN |
|
--from-patch REGEXP |
select changes starting with a patch matching REGEXP |
|
--from-tag REGEXP |
select changes starting with a tag matching REGEXP |
|
--last NUMBER |
select the last NUMBER patches |
|
-n |
--index N-M |
select a range of patches |
--matches PATTERN |
select patches matching PATTERN |
|
-p |
--patches REGEXP |
select patches matching REGEXP |
-t |
--tags REGEXP |
select tags matching REGEXP |
--only-to-files |
show only changes to specified files |
|
--context |
give output suitable for get –context |
|
--xml-output |
generate XML formatted output |
|
--human-readable |
give human-readable output |
|
--number |
number the changes |
|
--count |
output count of changes |
|
-s |
--summary |
summarize changes |
--no-summary |
don't summarize changes |
|
--reverse |
show changes in reverse order |
|
--repo URL |
specify the repository URL |
|
--repodir DIRECTORY |
specify the repository directory in which to run |
|
-a |
--all |
answer yes to all patches |
-i |
--interactive |
prompt user interactively |
--ssh-cm |
use SSH ControlMaster feature |
|
--no-ssh-cm |
don't use SSH ControlMaster feature [DEFAULT] |
|
--http-pipelining |
enable HTTP pipelining |
|
--no-http-pipelining |
disable HTTP pipelining [DEFAULT] |
|
--no-cache |
don't use patch caches |
|
--from-patch
, --from-match
, or
--from-tag
option, it outputs only those changes since that tag or
patch.
|
--context
flag, darcs changes outputs sufficient
information to allow the current state of the repository to be
recreated at a later date. This information should generally be piped to a
file, and then can be used later in conjunction with
darcs get --context
to recreate the current version. Note that
while the --context
flag may be used in conjunction with
--xml-output
or --human-readable
, in neither case will darcs
get be able to read the output. On the other hand, sufficient information
will be output for a knowledgeable human to recreate the current
state of the repository.Usage: darcs show authors [OPTION]...
--repodir DIRECTORY |
specify the repository directory in which to run |
Usage: darcs show contents [OPTION]... [FILE]...
--match PATTERN |
select a single patch matching PATTERN |
|
-p |
--patch REGEXP |
select a single patch matching REGEXP |
-t |
--tag REGEXP |
select tag matching REGEXP |
-n |
--index N-M |
select a range of patches |
--repodir DIRECTORY |
specify the repository directory in which to run |
Usage: darcs show files [OPTION]...
--files |
include files in output [DEFAULT] |
|
--no-files |
don't include files in output |
|
--directories |
include directories in output [DEFAULT] |
|
--no-directories |
don't include directories in output |
|
--pending |
reflect pending patches in output [DEFAULT] |
|
--no-pending |
only included recorded patches in output |
|
-0 |
--null |
separate file names by NUL characters |
--repodir DIRECTORY |
specify the repository directory in which to run |
--pending
option is specified),
the effect of pending patches on the repository is taken into account.
In other words, if you add a file using darcs add, it
immediately appears in the output of query manifest, even if it
is not yet recorded. If you specify the --no-pending
option,
query manifest will only list recorded files (and directories).--files
and --directories
options control whether
files and directories are included in the output. The
--no-files
and --no-directories
options have the
reverse effect. The default is to include files, but not directories.--null
option, the file names are written to
standard output in unescaped form, and separated by ASCII NUL bytes.
This format is suitable for further automatic processing (for example,
using xargs -0
).Usage: darcs show tags [OPTION]...
--repodir DIRECTORY |
specify the repository directory in which to run |
Usage: darcs show repo [OPTION]...
--repodir DIRECTORY |
specify the repository directory in which to run |
|
--files |
include files in output [DEFAULT] |
|
--no-files |
don't include files in output |
|
--xml-output |
generate XML formatted output |
show repo
displays information about
the current repository: the location, the type, etc.darcs show repo | grep Root: | awk {print $2}
can be used to locate the
top-level _darcs
directory from anyplace within a darcs repository
working directory.
|
--files
option is specified (the default), then the
show repo
operation will read patch information from the
repository and display the number of patches in the repository. The
--no-files
option can be used to suppress this operation (and
improve performance).
|
show repo
displays output in human readable
form, but the --xml-output
option can be used to obtain
XML-formatted to facilitate regular parsing by external tools.Usage: darcs tag [OPTION]... [TAGNAME]
-m |
--patch-name PATCHNAME |
name of patch |
-A |
--author EMAIL |
specify author id |
--checkpoint |
create a checkpoint file (see get –partial) |
|
--pipe |
ask user interactively for the patch metadata |
|
-i |
--interactive |
prompt user interactively |
--repodir DIRECTORY |
specify the repository directory in which to run |
--compress |
create compressed patches |
|
--dont-compress |
don't create compressed patches |
|
--umask UMASK |
specify umask to use when writing |
% darcs get --tag "darcs 3.14" REPOLOCATIONEach tagged version has a version name. The version is also flagged with the person who tagged it (taken by default from the `DARCS_EMAIL' or `EMAIL' environment variable). The date is also included in the version information.
|
--checkpoint
option allows the tag be used later with the
--partial
flag to get
or check
.
|
--pipe
option, you will be prompted for the
tag date and author. This interface is intended for scripting darcs, in
particular for writing repository conversion scripts. The prompts are
intended mostly as useful guide (since scripts won't need them), to help
you understand the format in which to provide the input. Here's an example
of what the --pipe
prompts looks like:
What is the date? Mon Nov 15 13:38:01 EST 2004 Who is the author? David Roundy What is the version name? 3.0 Finished tagging patch 'TAG 3.0'Using
tag
creates an entry in the repository history just like record
.
It will show up with darcs changes
appearing in the format:
tagged My Tag NameTo display all tags in the repository, use the “
darcs query tags
”
command.Usage: darcs setpref [OPTION]... <PREF> <VALUE>
--repodir DIRECTORY |
specify the repository directory in which to run |
--umask UMASK |
specify umask to use when writing |
% darcs setpref test "echo I am not really testing anything."Setpref allows you to set a preference value in a way that will propagate to other repositories.
_darcs/prefs/prefs
”. Changes
you make in that file will be preserved._darcs/prefs/prefs
” holds the only preferences information
that can propagate between repositories by pushes and pulls, and the only
way this happens is when the setprefs command is used. Note that although
prefs settings are included in patches, they are not fully version
controlled. In particular, depending on the order in which a series of
merges is performed, you may end up with a different final prefs
configuration. In practice I don't expect this to be a problem, as the
prefs usually won't be changed very often.Usage: darcs check [OPTION]...
--complete |
get a complete copy of the repository |
|
--partial |
get partial repository using checkpoint (old-fashioned format only) |
|
--no-test |
don't run the test script |
|
--test |
run the test script |
|
--leave-test-directory |
don't remove the test directory |
|
--remove-test-directory |
remove the test directory |
|
--repodir DIRECTORY |
specify the repository directory in which to run |
|
darcs get --partial
), by default
darcs check
will only verify the contents since the most recent checkpoint. You can
change this behavior using the --complete
flag.% darcs setpref test "sh configure && make && make test"Or, if you want to define a test specific to one copy of the repository, you could do this by editing the file
_darcs/prefs/prefs
.
|
--leave-test-directory
flag. Alas, there is no
way to make darcs leave the test directory only if the test fails. The
opposite of --leave-test-directory
is
--remove-test-directory
, which could come in handy if you choose to
make --leave-test-directory
the default (see
section ??).
|
--no-test
option.Usage: darcs optimize [OPTION]...
--checkpoint |
create a checkpoint file (see get –partial) |
|
-t |
--tag TAGNAME |
name of version to checkpoint |
--repodir DIRECTORY |
specify the repository directory in which to run |
|
--reorder-patches |
reorder the patches in the repository |
|
--sibling URL |
specify a sibling directory |
|
--relink |
relink random internal data to a sibling |
|
--relink-pristine |
relink pristine tree (not recommended) |
--compress |
create compressed patches |
|
--dont-compress |
don't create compressed patches |
|
--uncompress |
uncompress patches |
|
--umask UMASK |
specify umask to use when writing |
|
--checkpoint
option, optimize creates a checkpoint patch
for a tag. You can specify the tag with the --tag
option, or
just let darcs choose the most recent tag. Note that optimize
--checkpoint
will fail when used on a “partial” repository. Also,
the tag that is to be checkpointed must not be preceded by any patches
that are not included in that tag. If that is the case, no checkpointing
is done.--partial
flag to
get
and check
. This allows for users to retrieve
a working repository with limited history with a savings of disk
space and bandwidth.
|
--checkpoint
option.--compress
option, optimize will compress all the
patches in the repository. Similarly, if you give the --uncompress
,
optimize will decompress all the patches in the repository.
--dont-compress
means “don't compress, but don't uncompress
either”. It would be useful if one of the compression options was provided
as a default and you wanted to override it.
|
--relink
and --relink-pristine
options cause Darcs
to relink files from a sibling. See Section ??.
|
--reorder-patches
option causes Darcs to create an optimal
ordering of its internal patch inventory. This may help to produce shorter
`context' lists when sending patches, and may improve performance for some
other operations as well. You should not run --reorder-patches
on a
repository from which someone may be simultaneously pulling or getting, as
this could lead to repository corruption.Usage: darcs amend-record [OPTION]... [FILE or DIRECTORY]...
--match PATTERN |
select a single patch matching PATTERN |
|
-p |
--patch REGEXP |
select a single patch matching REGEXP |
-n |
--index N-M |
select a range of patches |
--no-test |
don't run the test script |
|
--test |
run the test script |
|
--leave-test-directory |
don't remove the test directory |
|
--remove-test-directory |
remove the test directory |
|
-a |
--all |
answer yes to all patches |
-i |
--interactive |
prompt user interactively |
-A |
--author EMAIL |
specify author id |
-m |
--patch-name PATCHNAME |
name of patch |
--edit-long-comment |
edit the long comment by default |
|
--skip-long-comment |
don't give a long comment |
|
--prompt-long-comment |
prompt for whether to edit the long comment |
|
-l |
--look-for-adds |
look for (non-boring) files that could be added |
--dont-look-for-adds |
don't look for any files that could be added [DEFAULT] |
|
--repodir DIRECTORY |
specify the repository directory in which to run |
--compress |
create compressed patches |
|
--dont-compress |
don't create compressed patches |
|
--ignore-times |
don't trust the file modification times |
|
--umask UMASK |
specify umask to use when writing |
|
--set-scripts-executable |
make scripts executable |
|
--dont-set-scripts-executable |
don't make scripts executable |
amend-record
will modify the date of the recorded patch. --set-scripts-executable
flag is passed to amend-record, darcs will set
scripts executable in the temporary test directory before running the test. Usage: darcs rollback [OPTION]... [FILE or DIRECTORY]...
--from-match PATTERN |
select changes starting with a patch matching PATTERN |
|
--from-patch REGEXP |
select changes starting with a patch matching REGEXP |
|
--from-tag REGEXP |
select changes starting with a tag matching REGEXP |
|
--last NUMBER |
select the last NUMBER patches |
|
--matches PATTERN |
select patches matching PATTERN |
|
-p |
--patches REGEXP |
select patches matching REGEXP |
-t |
--tags REGEXP |
select tags matching REGEXP |
-a |
--all |
answer yes to all patches |
-i |
--interactive |
prompt user interactively |
-A |
--author EMAIL |
specify author id |
-m |
--patch-name PATCHNAME |
name of patch |
--edit-long-comment |
edit the long comment by default |
|
--skip-long-comment |
don't give a long comment |
|
--prompt-long-comment |
prompt for whether to edit the long comment |
|
--no-test |
don't run the test script |
|
--test |
run the test script |
|
--leave-test-directory |
don't remove the test directory |
|
--remove-test-directory |
remove the test directory |
|
--repodir DIRECTORY |
specify the repository directory in which to run |
--compress |
create compressed patches |
|
--dont-compress |
don't create compressed patches |
|
--umask UMASK |
specify umask to use when writing |
Usage: darcs unrecord [OPTION]...
--from-match PATTERN |
select changes starting with a patch matching PATTERN |
|
--from-patch REGEXP |
select changes starting with a patch matching REGEXP |
|
--from-tag REGEXP |
select changes starting with a tag matching REGEXP |
|
--last NUMBER |
select the last NUMBER patches |
|
--matches PATTERN |
select patches matching PATTERN |
|
-p |
--patches REGEXP |
select patches matching REGEXP |
-t |
--tags REGEXP |
select tags matching REGEXP |
--no-deps |
don't automatically fulfill dependencies |
|
-a |
--all |
answer yes to all patches |
-i |
--interactive |
prompt user interactively |
--repodir DIRECTORY |
specify the repository directory in which to run |
--compress |
create compressed patches |
|
--dont-compress |
don't create compressed patches |
|
--umask UMASK |
specify umask to use when writing |
darcs revert
.
To do unrecord and revert in one go, you can use darcs obliterate
.
|
--from
and --last
options
to set the earliest patch selectable to unrecord.
|
--patches
, --matches
, --tags
, and --no-deps
options can be used to select which patches to unrecord, as described in
subsection ??.--no-deps
you won't be asked about patches that can't be
unrecorded due to depending patches.--from
or --last
options to search
more or fewer patches.Usage: darcs obliterate [OPTION]...
--from-match PATTERN |
select changes starting with a patch matching PATTERN |
|
--from-patch REGEXP |
select changes starting with a patch matching REGEXP |
|
--from-tag REGEXP |
select changes starting with a tag matching REGEXP |
|
--last NUMBER |
select the last NUMBER patches |
|
--matches PATTERN |
select patches matching PATTERN |
|
-p |
--patches REGEXP |
select patches matching REGEXP |
-t |
--tags REGEXP |
select tags matching REGEXP |
--no-deps |
don't automatically fulfill dependencies |
|
-a |
--all |
answer yes to all patches |
-i |
--interactive |
prompt user interactively |
--repodir DIRECTORY |
specify the repository directory in which to run |
--compress |
create compressed patches |
|
--dont-compress |
don't create compressed patches |
|
--ignore-times |
don't trust the file modification times |
|
--umask UMASK |
specify umask to use when writing |
|
--from
and --last
options to set the earliest patch
selectable to obliterate.
|
--patches
, --matches
, --tags
, and --no-deps
options can be used to select which patches to obliterate, as described in
subsection ??.--no-deps
you won't be asked
about patches that can't be obliterated due to depending patches.--from
or --last
options to search
more or fewer patches.Usage: darcs revert [OPTION]... [FILE or DIRECTORY]...
-a |
--all |
answer yes to all patches |
-i |
--interactive |
prompt user interactively |
--repodir DIRECTORY |
specify the repository directory in which to run |
--ignore-times |
don't trust the file modification times |
|
--umask UMASK |
specify umask to use when writing |
Usage: darcs unrevert [OPTION]...
--ignore-times |
don't trust the file modification times |
|
-a |
--all |
answer yes to all patches |
-i |
--interactive |
prompt user interactively |
--repodir DIRECTORY |
specify the repository directory in which to run |
--umask UMASK |
specify umask to use when writing |
Usage: darcs diff [OPTION]... [FILE or DIRECTORY]...
--to-match PATTERN |
select changes up to a patch matching PATTERN |
|
--to-patch REGEXP |
select changes up to a patch matching REGEXP |
|
--to-tag REGEXP |
select changes up to a tag matching REGEXP |
|
--from-match PATTERN |
select changes starting with a patch matching PATTERN |
|
--from-patch REGEXP |
select changes starting with a patch matching REGEXP |
|
--from-tag REGEXP |
select changes starting with a tag matching REGEXP |
|
--match PATTERN |
select a single patch matching PATTERN |
|
-p |
--patch REGEXP |
select a single patch matching REGEXP |
--last NUMBER |
select the last NUMBER patches |
|
-n |
--index N-M |
select a range of patches |
--diff-command COMMAND |
specify diff command (ignores –diff-opts) |
|
--diff-opts OPTIONS |
options to pass to diff |
|
-u |
--unified |
pass -u option to diff |
--repodir DIRECTORY |
specify the repository directory in which to run |
|
--store-in-memory |
do patch application in memory rather than on disk |
|
% darcs diff -t 0.9.8 -t 0.9.10 -- -uto get a diff in the unified format. Actually, thanks to the wonders of getopt you need the “
--
” shown above before any arguments to diff.
You can also specify additional arguments to diff using the
--diff-opts
flag. The above command would look like this:
% darcs diff --diff-opts -u -t 0.9.8 -t 0.9.10This may not seem like an improvement, but it really pays off when you want to always give diff the same options. You can do this by adding
% diff diff-opts -udpto your
_darcs/prefs/defaults
file.% darcs diff foo.c bar.c baz/
|
--diff-command
, e.g.
--diff-command 'opendiff %1 %2'.The
%1
and %2
are replaced with the two versions to be
merged. The above example works with the FileMerge.app tool that comes with
Apple's developer tools. To use xxdiff, you would use
--diff-command 'xxdiff %1 %2'To use
kdiff3
, you can use
--diff-command 'kdiff3 %1 %2'Note that the command is split into space-separated words and the first one is
exec
ed with the rest as arguments—it is not a shell command. Also
the substitution of the %
escapes is only done on complete words.
See ?? for how you might work around this fact, for example,
with Emacs' Ediff package.--diff-opts
flag is ignored if you use this option.Usage: darcs annotate [OPTION]... [FILE or DIRECTORY]...
-s |
--summary |
summarize changes |
--no-summary |
don't summarize changes |
|
-u |
--unified |
output patch in a darcs-specific format similar to diff -u |
--human-readable |
give human-readable output |
|
--xml-output |
generate XML formatted output |
|
--match PATTERN |
select a single patch matching PATTERN |
|
-p |
--patch REGEXP |
select a single patch matching REGEXP |
-t |
--tag REGEXP |
select tag matching REGEXP |
-n |
--index N-M |
select a range of patches |
--creator-hash HASH |
specify hash of creator patch (see docs) |
|
--repodir DIRECTORY |
specify the repository directory in which to run |
|
--human-readable
.--xml-output
is the alternative to --human-readable
.--summary
can be used with either the --xml-output
or the
--human-readable
options to alter the results. It is documented
fully in the `common options' portion of the manual. --unified
flag implies --human-readable
, and causes
the output to remain in a darcs-specific format that is similar to that produced
by diff --unified
.# Created by [bounce handling patch # mark**20040526202216] as ./test/m7/bounce_handling.pl bounce_handling.plIf a patch name and a directory are given, these details are output for the time after that patch was applied. If a directory and a tag name are given, the details of the patches involved in the specified tagged version will be output.
|
--creator-hash
option should only be used in combination with a
file or directory to be annotated. In this case, the name of that file or
directory is interpreted to be its name at the time it was created,
and the hash given along with --creator-hash
indicates the patch
that created the file or directory. This allows you to (relatively) easily
examine a file even if it has been renamed multiple times.Usage: darcs show authors [OPTION]...
--repodir DIRECTORY |
specify the repository directory in which to run |
Usage: darcs show contents [OPTION]... [FILE]...
--match PATTERN |
select a single patch matching PATTERN |
|
-p |
--patch REGEXP |
select a single patch matching REGEXP |
-t |
--tag REGEXP |
select tag matching REGEXP |
-n |
--index N-M |
select a range of patches |
--repodir DIRECTORY |
specify the repository directory in which to run |
Usage: darcs show files [OPTION]...
--files |
include files in output [DEFAULT] |
|
--no-files |
don't include files in output |
|
--directories |
include directories in output [DEFAULT] |
|
--no-directories |
don't include directories in output |
|
--pending |
reflect pending patches in output [DEFAULT] |
|
--no-pending |
only included recorded patches in output |
|
-0 |
--null |
separate file names by NUL characters |
--repodir DIRECTORY |
specify the repository directory in which to run |
--pending
option is specified),
the effect of pending patches on the repository is taken into account.
In other words, if you add a file using darcs add, it
immediately appears in the output of query manifest, even if it
is not yet recorded. If you specify the --no-pending
option,
query manifest will only list recorded files (and directories).--files
and --directories
options control whether
files and directories are included in the output. The
--no-files
and --no-directories
options have the
reverse effect. The default is to include files, but not directories.--null
option, the file names are written to
standard output in unescaped form, and separated by ASCII NUL bytes.
This format is suitable for further automatic processing (for example,
using xargs -0
).Usage: darcs show tags [OPTION]...
--repodir DIRECTORY |
specify the repository directory in which to run |
Usage: darcs show repo [OPTION]...
--repodir DIRECTORY |
specify the repository directory in which to run |
|
--files |
include files in output [DEFAULT] |
|
--no-files |
don't include files in output |
|
--xml-output |
generate XML formatted output |
show repo
displays information about
the current repository: the location, the type, etc.darcs show repo | grep Root: | awk {print $2}
can be used to locate the
top-level _darcs
directory from anyplace within a darcs repository
working directory.
|
--files
option is specified (the default), then the
show repo
operation will read patch information from the
repository and display the number of patches in the repository. The
--no-files
option can be used to suppress this operation (and
improve performance).
|
show repo
displays output in human readable
form, but the --xml-output
option can be used to obtain
XML-formatted to facilitate regular parsing by external tools.Usage: darcs convert [OPTION]... <REPOSITORY> [<DIRECTORY>]
--repo-name DIRECTORY |
path of output directory |
|
--set-scripts-executable |
make scripts executable |
|
--dont-set-scripts-executable |
don't make scripts executable |
--ssh-cm |
use SSH ControlMaster feature |
|
--no-ssh-cm |
don't use SSH ControlMaster feature [DEFAULT] |
|
--http-pipelining |
enable HTTP pipelining |
|
--no-http-pipelining |
disable HTTP pipelining [DEFAULT] |
|
--no-cache |
don't use patch caches |
Usage: darcs mark-conflicts [OPTION]...
--ignore-times |
don't trust the file modification times |
|
--repodir DIRECTORY |
specify the repository directory in which to run |
--umask UMASK |
specify umask to use when writing |
Usage: darcs dist [OPTION]...
-d |
--dist-name DISTNAME |
name of version |
--repodir DIRECTORY |
specify the repository directory in which to run |
dist: darcs dist --dist-name darcs-`./darcs --version`
darcs dist
then simply creates a clean copy of the source tree,
which it then tars and gzips. If you use programs such as autoconf or
automake, you really should run them on the clean tree before tarring it up
and distributing it. You can do this using the pref value “predist”,
which is a shell command that is run prior to tarring up the distribution:
% darcs setpref predist "autoconf && automake"
Usage: darcs trackdown [OPTION]... [[INITIALIZATION] COMMAND]
--repodir DIRECTORY |
specify the repository directory in which to run |
--set-scripts-executable |
make scripts executable |
|
--dont-set-scripts-executable |
don't make scripts executable |
'autoconf; ./configure >/dev/null'Then it runs the test command, for example
'make && cd tests && sh /tmp/test.sh'While the test command exits with an error return code, darcs “unapplies” one patch from the version controlled files to retrieve an earlier version, and repeats the test command. If the test command finally succeeds, the name of the hunted down patch is found in the output before the last test run.
% darcs trackdown 'make && false'would result in compiling every version in the repository–which is a rather tedious prospect.
% darcs trackdown 'grep FIXME Record.lhs'To find the latest version that compiles, you can run
% darcs trackdown 'autoconf' './configure && make'Trackdown can also be used to see how other features of the code changed with time. For example
% darcs trackdown 'autoconf; ./configure' \ "make darcs > /dev/null && cd ~/darcs && time darcs check && false"would let you see how long `darcs check' takes to run on each previous version of darcs that will actually compile. The “
&& false
”
ensures that trackdown keeps going.Usage: darcs repair [OPTION]...
--repodir DIRECTORY |
specify the repository directory in which to run |
--umask UMASK |
specify umask to use when writing |
[A-Za-z_0-9]
.M( M(A,B), M(A,M(C,D)))From which it recreates a merge history:
C A M(A,B) M( M(A,B), M(A,M(C,D)))(For the curious, yes I can easily unwind this merger in my head [and on paper can unwind insanely more complex mergers]—that's what comes of working for a few months on an algorithm.) Let's start with a simple unwinding. The merger
M(A,B)
simply means that two patches
(A
and B
) conflicted, and of the two of them A
is
first in the history. The last two patches in the unwinding of any merger
are always just this easy. So this unwinds to:
A M(A,B)What about a merger of mergers? How about
M(A,M(C,D))
. In this case
we know the two most recent patches are:
A M(A,M(C,D))But obviously the unwinding isn't complete, since we don't yet see where
C
and D
came from. In this case we take the unwinding of
M(C,D)
and drop its latest patch (which is M(C,D)
itself) and
place that at the beginning of our patch train:
C A M(A,M(C,D))As we look at
M( M(A,B), M(A,M(C,D)))
, we consider the unwindings of
each of its subpatches:
C A A M(A,B) M(A,M(C,D))As we did with
M(A,M(C,D))
, we'll drop the first patch on the
right and insert the first patch on the left. That moves us up to the two
A
's. Since these agree, we can use just one of them (they
“should” agree). That leaves us with the C
which goes first.A
's would come out at the same time, and if
they didn't, we'd have to rearrange things until they did. Or if there was
no way to rearrange things so that they would agree, we have to go on to
plan B, which I will explain now.M( M(A,B), M(C,D))
. We can easily unwind the
two subpatches
A C M(A,B) M(C,D)Now we need to reconcile the
A
and C
. How do we do this?
Well, as usual, the solution is to use the most wonderful
Theorem ??. In this case we have to use it in the reverse of
how we used it when merging, since we know that A
and C
could
either one be the last patch applied before M(A,B)
or
M(C,D)
. So we can find C'
using
C' A M(A,B) M( M(A,B), M(C,D) )There is a bit more complexity to the unwinding process (mostly having to do with cases where you have deeper nesting), but I think the general principles that are followed are pretty much included in the above discussion.
merger MERGERVERSION <first patch> <second patch>
_darcs
. There must also be a subdirectory within
_darcs
named patches
. The patches
directory contains
the actual patches which are in the repository. There must also be a
pristine tree, which may either be a directory containing a cache of
the version of the tree which has been recorded, or a stub, and may be
named either “current” or “pristine”._darcs/pristine/
or _darcs/current/
), which will temporarily
cause your repository to be inconsistent. So don't record any
patches while viewing files in _darcs/current with an editor! A better
plan would be to restrict yourself to viewing these files with a pager such
as more or less._darcs
is the inventory
file, which lists all the
patches that are in the repository. Moreover, it also gives the order of the
representation of the patches as they are stored. Given a source of patches,
i.e. any other set of repositories which have between them all the patches
contained in a given repository, that repository can be reproduced based on only the
information in the inventory
file. Under those circumstances, the
order of the patches specified in the inventory
file would be
unimportant, as this order is only needed to provide context for the
interpretation of the stored patches in this repository.patches
which
is called `pending'. This patch describes any changes which have not yet
been recorded, and cannot be determined by a simple diff. For example, file
additions or renames are placed in pending until they are recorded.
Similarly, token replaces are stored in pending until they are recorded._darcs
directory also contains a directory called
“prefs
”, which is described in Chapter ??.The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software—to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too.
When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.
To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.
For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.
We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.
Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.
Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.
The precise terms and conditions for copying, distribution and modification follow.
<one line to give the program's name and a brief idea of what it does.>Also add information on how to contact you by electronic and paper mail.
Copyright (C) <year> <name of author>
This program 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 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
Gnomovision version 69, Copyright (C) <year> <name of author>The hypothetical commands show w and show c should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than show w and show c; they could even be mouse-clicks or menu items—whatever suits your program.
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it under certain conditions; type `show c' for details.
Yoyodyne, Inc., hereby disclaims all copyright interest in the programThis General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Library General Public License instead of this License.
`Gnomovision' (which makes passes at compilers) written by James Hacker.
<signature of Ty Coon>, 1 April 1989
Ty Coon, President of Vice
This document was translated from LATEX by HEVEA.