Darcs User Manual

Contents

• Introduction
  • Features
  
  
• Getting started
  • Creating your repository
  • Making changes
  • Making your repository visible to others
  • Getting changes made to another repository
  • Moving patches from one repository to another
    • Push
    • All pulls
    • Send and apply manually
  
  
• Configuring darcs
  • prefs
  • Environment variables
  • General-purpose variables
  • Remote repositories
  • Highlighted output
  • Character escaping and non-ASCII character encodings
  
  
• Best practices
  • Creating patches
    • Changes
    • Keeping or discarding changes
    • Unrecording changes
    • Special patches and pending
  • Using patches
    • Dependencies
    • Branches: just normal repositories
    • Moving patches around--no versions
    • Tags--versions
    • Conflicts
    • Resolving conflicts
  • Global and per-repository caches
  • Distributed development with one primary developer
  • Sending signed patches by email
  
  
• Darcs commands
  • Common options to darcs commands
    • Match
    • Posthooks
    • Prehooks
  • Options apart from darcs commands
  • Getting help
    • darcs help
  • Creating repositories
    • darcs initialize
    • darcs get
  • Modifying the contents of a repository
    • darcs add
    • darcs remove
    • darcs move
    • darcs replace
  • Working with changes
    • darcs record
    • darcs pull
    • darcs push
    • darcs send
    • darcs apply
  • Seeing what you've done
    • darcs whatsnew
    • darcs changes
  • More advanced commands
    • darcs tag
    • darcs setpref
    • darcs test
    • darcs repair
    • darcs optimize
  • Undoing, redoing and running in circles
    • darcs amend-record
    • darcs rollback
    • darcs unrecord
    • darcs obliterate
    • darcs revert
    • darcs unrevert
  • Advanced examination of the repository
    • darcs diff
    • darcs annotate
    • darcs show
  • Rarely needed and obscure commands
    • darcs mark-conflicts
    • darcs trackdown
    • darcs dist
    • darcs put
    • darcs fetch
    • darcs convert
  
  
• Building darcs
• License

Introduction

This manual provides a stable documentation for using darcs. To find more up-to-date and complementary information, please consult the darcs wiki.

Darcs is a revision control system, along the lines of Subversion, Git or Mercurial. That means that it keeps track of various revisions and branches of your project, allows for changes to propagate from one branch to another. Darcs has two particularly distinctive features which differ from other revision control systems:

Every source tree a branch

Darcs keeps track of changes rather than versions

In the world of darcs, the source tree is not the fundamental object, but rather the patch is the fundamental object. Rather than a patch being defined in terms of the difference between two trees, a tree is defined as the result of applying a given set of patches to an empty tree. Moreover, these patches may be reordered without changing the tree. This makes many operations, like cherry-picking or merging, much more natural.

Features

Record changes locally

Interactive records

Unrecord local changes

Interactive everything else

Test suites

Any old server

You decide write permissions

File and directory moves

Token replace

Configurable defaults

Getting started

This chapter will lead you through an example use of darcs, which hopefully will allow you to get started using darcs with your project.

Creating your repository

Creating your repository in the first place just involves telling darcs to create the special directory (called _darcs) in your project tree, which will hold the revision information. This is done by simply calling from the root directory of your project:

$ cd my_project/
$ darcs initialize

$ darcs add *.c Makefile.am configure.ac

$ darcs record --all
What is the patch name? Initial revision.

Making changes

Now that we have created our repository, make a change to one or more of your files. After making the modification run:

$ darcs whatsnew

Let's say you have now made a change to your project. The next thing to do is to record a patch. Recording a patch consists of grouping together a set of related changes, and giving them a name. It also tags the patch with the date it was recorded and your email address.

To record a patch simply type:

$ darcs record

You can now rerun whatsnew, and see that indeed the changes you have recorded are no longer marked as new.

Making your repository visible to others

You can also self-host your repositories by using any web server. The recommended way to do this (using apache in a UNIX environment) is to create a directory called /var/www/repos, and then put a symlink to your repository there:

$ cd /var/www/repos
$ ln -s /home/username/myproject .

Getting changes made to another repository

$ darcs pull your.server.org/repos/yourproject

Of course, maybe people don't even have a copy of your repository. In that case they'd want to do a

$ darcs get your.server.org/repos/yourproject

Get, pull and push also work over ssh. Ssh-paths are of the same form accepted by scp, namely [username@]host:/path/to/repository.

Moving patches from one repository to another

Darcs is flexible as to how you move patches from one repository to another. This section will introduce all the ways you can get patches from one place to another, starting with the simplest and moving to the most complicated.

Push

If you use ssh, you can use the push method to transfer changes. Push can also be used when the target repository is local, in which case ssh isn't needed.

Note that you can use push to administer a multiple-user repository. You just need to create a user for the repository (or repositories), and give everyone with write access ssh access, perhaps using .ssh/authorized_keys. Then they run

$ darcs push repouser@repo.server:repo/directory

If you like this idea about creating a repository user to own a repository which is writable by a number of users, you have one other option.

Push --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*

All pulls

This method involves making each repository readable (by http, ftp, nfs-mounted disk, or a public web hosting), and you run 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.

Send and apply manually

Sometimes the push method is impossible because the owner of the main repository does not want or cannot create a user to write into it, and you cannot use the all-pull method because you cannot set up a web server on your machine, perhaps because it's behind a firewall or perhaps for security reasons, or because it is often turned off. In this case you can use darcs send from that computer to generate a patch bundle for the remote 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 the owner of that repository runs 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 the owner of the remote repository has to keep track of the patch bundle (in the email, or whatever).

To use the send and apply method with email, the best is probably to create a _darcs/prefs/email file in the target repository containing the email address of the maintainer. This way anyone who sends to this repository will automatically send the patch bundle to that email address.

If you receive many patches by email, you probably will benefit by running darcs apply directly from your mail program. You can place in your .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"

text/x-patch;                           cat; copiousoutput
text/x-darcs-patch;                     cat; copiousoutput

Configuring darcs

There are several ways you can adjust darcs' behavior to suit your needs. The first is to edit files in the _darcs/prefs/ directory of a repository. Such configuration only applies when working with that repository. To configure darcs on a per-user rather than per-repository basis (but with essentially the same methods), you can edit (or create) files in the ~/.darcs/ directory. Finally, the behavior of some darcs commands can be modified by setting appropriate environment variables.

Microsoft Windows

The global darcs directory is %APPDATA%\darcs\. This typically expands to C:\Documents And Settings\user\Application Data\darcs\. This folder contains the cache, as well as all the per-user settings files: preferences, boring etc... These will became the new defaults that can be overridden on per-repository basis.

prefs

The _darcs directory contains a prefs directory. This directory exists simply to hold user configuration settings specific to this repository. The contents of this directory are intended to be modifiable by the user, although in some cases a mistake in such a modification may cause darcs to behave strangely.

defaults

Default values for darcs commands can be configured on a per-repository basis by editing (and possibly creating) the _darcs/prefs/defaults file. Each line of this file has the following form:

COMMAND FLAG VALUE

Note that the use of 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 (for MS Windows, see  )
repo/_darcs/prefs/defaults	provides defaults for one project,
	overrules changes per user

For example, if your system clock is bizarre, you could instruct darcs to always ignore the file modification times by adding the following line to your _darcs/prefs/defaults file. (Note that this would have to be done for each repository!)

ALL ignore-times

If you never want to run a test when recording to a particular repository (but still want to do so when running check on that repository), and like to name all your patches ``Stupid patch'', you could use the following:

record no-test
record patch-name Stupid patch

If you would like a command to be run every time patches are recorded in a particular repository (for example if you have one central repository, that all developers contribute to), then you can set apply to always run a command when apply is successful. For example, if you need to make sure that the files in the repository have the correct access rights you might use the following. There are two things to note about using darcs this way:

• Without the second line you will get errors, because the sub process that runs apply cannot prompt interactively.
• Whatever script is run by the post apply command should not be added to the repository with darcs add; doing so would allow people to modify that file and then run arbitrary scripts on your main repository, possibly damaging or violating security.

apply posthook chmod -R a+r *
apply run-posthook

Similarly, if you need a command to run automatically before darcs performs an action you can use a prehook. Using prehooks it could be possible to canonicalize line endings before recording patches.

There are some options which are meant specifically for use in _darcs/prefs/defaults. One of them is --disable. As the name suggests, this option will disable every command that got it as argument. So, if you are afraid that you could damage your repositories by inadvertent use of a command like amend-record, add the following line to _darcs/prefs/defaults:

amend-record disable

Also, a global preferences file can be created with the name .darcs/defaults in your home directory, on MS Windows  . Options present there will be added to the repository-specific preferences. If they conflict with repository-specific options, the repository-specific ones will take precedence.

repos

author

boring

\.hi$
\.o$
^\.[^/]
^_
~$
(^|/)CVS($|/)

You may want to have the boring file under version control. To do this you can use darcs setpref to set the value ``boringfile'' to the name of your desired boring file (e.g. darcs setpref boringfile .boring, where .boring is the repository path of a file that has been darcs added to your repository). The boringfile preference overrides _darcs/prefs/boring, so be sure to copy that file to the boringfile.

You can also set up a ``boring'' regexps file in your home directory, named ~/.darcs/boring, (see on MS Windows), which will be used with all of your darcs repositories.

Any file not already managed by darcs and whose repository path (such as manual/index.html) matches any of the boring regular expressions is considered boring. The boring file is used to filter the files provided to darcs add, to allow you to use a simple darcs add newdir newdir/* without accidentally adding a bunch of object files. It is also used when the --look-for-adds flag is given to whatsnew or record. Note that once a file has been added to darcs, it is not considered boring, even if it matches the boring file filter.

binaries

email

sources

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

A global cache is enabled by default in your home directory. The cache allows darcs to avoid re-downloading patches (for example, when doing a second darcs get of the same repository), and also allows darcs to use hard links to reduce disk usage.

Note that the cache directory should reside on the same filesystem as your repositories, so you may need to vary this. You can also use multiple cache directories on different filesystems, if you have several filesystems on which you use darcs.

motd

Environment variables

There are a few environment variables whose contents affect darcs' behavior. Here is a quick list of all the variables and their documentation in the rest of the manual:

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_CONNECTION_TIMEOUT
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

General-purpose variables

DARCS_EDITOR, DARCSEDITOR, VISUAL and EDITOR

DARCS_PAGER and PAGER

DARCS_TMPDIR and TMPDIR

DARCS_KEEP_TMPDIR

HOME and APPDATA

Remote repositories

DARCS_CONNECTION_TIMEOUT

DARCS_SSH

The environment variable $DARCS_SSH can be used to specify an alternative SSH client. Arguments may be included, separated by whitespace. The value is not interpreted by a shell, so shell constructs cannot be used; in particular, it is not possible for the program name to contain whitespace by using quoting or escaping.

DARCS_SCP and DARCS_SFTP

If transfer-mode fails, Darcs will fall back on scp(1) and sftp(1). The commands invoked can be customized with the environment variables $DARCS_SCP and $DARCS_SFTP respectively, which behave like $DARCS_SSH. If the remote end allows only sftp, try setting DARCS_SCP=sftp.

SSH_PORT

HTTP_PROXY, HTTPS_PROXY, FTP_PROXY, ALL_PROXY and NO_PROXY

[protocol://]<host>[:port]

In which case libcurl will use the proxy for the associated protocol (HTTP, HTTPS and FTP). The environment variable ALL_PROXY can be used to set a single proxy for all libcurl requests.

If the environment variable NO_PROXY is a comma-separated list of host names, access to those hosts will bypass proxies defined by the above variables. For example, it is quite common to avoid proxying requests to machines on the local network with

NO_PROXY=localhost,*.localdomain

For compatibility with lynx et al, lowercase equivalents of these environment variables (e.g. $http_proxy) are also understood and are used in preference to the uppercase versions.

If Darcs was not built with libcurl, all these environment variables are silently ignored, and there is no way to use a web proxy.

DARCS_PROXYUSERPWD

DARCS_GET_FOO, DARCS_MGET_FOO and DARCS_APPLY_FOO

This method overrides all other ways of getting foo://xxx URLs.

Note that each command should be constructed so that it sends the downloaded content to STDOUT, and the next argument to it should be the URL. Here are some examples that should work for DARCS_GET_HTTP:

fetch -q -o -  
curl -s -f
lynx -source 
wget -q -O -

Apart from such toy examples, it is likely that you will need to manipulate the argument before passing it to the actual fetcher program. For example, consider the problem of getting read access to a repository on a CIFS (SMB) share without mount privileges:

export DARCS_GET_SMB="smbclient -c get"
darcs get smb://fs/twb/Desktop/hello-world

The above command will not work for several reasons. Firstly, Darcs will pass it an argument beginning with `smb:', which smbclient does not understand. Secondly, the host and share `//fs/twb' must be presented as a separate argument to the path `Desktop/hello-world'. Thirdly, smbclient requires that `get' and the path be a single argument (including a space), rather than two separate arguments. Finally, smbclient's `get' command writes the file to disk, while Darcs expects it to be printed to standard output.

In principle, we could get around such problems by making the variable contain a shell script, e.g.

export DARCS_GET_SMB='sh -c "...; smbclient $x -c \"get $y\""'

Unfortunately, Darcs splits the command on whitespace and does not understand that quotation or escaping, so there is no way to make Darcs pass the text after `-c' to sh as a single argument. Therefore, we instead need to put such one-liners in separate, executable scripts.

Continuing our smbclient example, we create an executable script ~/.darcs/libexec/get_smb with the following contents:

#!/bin/bash -e
IFS=/ read host share file <<<"${1#smb://}"
smbclient //$host/$share -c "get $file -"

And at last we can say

export DARCS_GET_SMB=~/.darcs/libexec/get_smb
darcs get smb://fs/twb/Desktop/hello-world

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 she

SEARCH:

Related searches:
command record directory boring variable

gipoco.com is neither affiliated with the authors of this page or responsible
for its contents. This is a safe-cache copy of the original web site.

gipoco.com is neither affiliated with the authors of this page nor responsible for its contents. This is a safe-cache copy of the original web site.