FrequentlyAskedQuestions

If you have a question that is not answered here, please get in touch with us at , or on #darcs on irc.freenode.net. Thanks!

Performance

How can I make darcs go faster?

Upgrade to darcs 2

If you upgrade both your client and your server to a version of darcs 2, darcs will be able to use the darcs transfer-mode ssh connection sharing feature to reduce the number of ssh-connections to at most 2 (this has an added bonus of not making you type your password a lot!)

Alternatively, you can set up connection sharing on the SSH level by adding this to you ~/.ssh/config:

Host *
ControlMaster auto
ControlPath ~/.ssh/master-%r@%h:%p

Use the lazy get feature

For one-off or throwaway branches, you should consider using the darcs get --lazy feature to fetch repositories. This will only fetch the patches which are strictly necessary for darcs to copy the repository, and fetch any future patches only on demand.

Enable a global cache

See DarcsTwo for details. (Enabled by default as of darcs 2.2 (?))

Use a local hard disk

Darcs works with your network drives (e.g. NFS) just fine, but at the time of this writing (2009-01-12) it can make things a little slow. For example, you might find it reading the pristine cache a lot just to do a simple darcs whatsnew. Hopefully this is a problem that can be resolved with some optimisation work. In the meantime, if this makes life uncomfortable, it's worth considering doing the bulk of your work on the local harddisk, perhaps using darcs push or rsync to the network drive if you're concerned about having automated backups. See http://bugs.darcs.net/issue1293 for details.

Note especially that your darcs global cache should live on a local drive. If your home directory is on NFS (for example), it may be a good idea to do something like

mv ~/.darcs /my/local/disk/
ln -s /my/local/disk/.darcs .

Optimise your inventory

The first issue is that darcs may be attempting to retrieve all patches in the remote repository from the last tag. Here are some things to try.

  1. Look in the _darcs/inventory file of the remote repository. How many patches are there in that inventory? These are all patches that darcs is liable to retrieve, even if you already have them.
  2. What happens when you create a tag in the remote repository or push it over? By right, the size of the inventory should drop to zero (starting from the tag you just pushed). If not, your darcs may be slightly buggy wrt tags. darcs optimize should fix it, emptying out your inventory.

  3. After running darcs optimize you should check the _darcs/inventory to see if it matches your expectations. If the most recent tag you know of is not on top, you like have some patches which are not included in that tag. Here darcs optimize --reorder is particularly useful. Try running it a few times, checking the inventory each time to see if you get any changes. Note that doing this on the *remote* repository as well is particularly useful. These simple steps (tag and optimize) should resolve most of your pushing woes. If not,

  4. Check to see if the same darcs operation is significantly faster when dealing with a repository that is on the same machine.

  5. If you are using ssh, check to see how long a single ssh connection makes

Check for conflicts

Finally, do you have any conflicts or merging to do? If so, you may be dealing with the infamous exponential time conflicts bug (for example, if you a series of nested conflicts, or you have two large and identical darcs patches to merge). See the ConflictsFAQ for a possible workaround to this. But note that this should only affect you if you are actually merging patches. If you are just pushing to or pulling from the trunk without any merging, you are not dealing with a conflicts issue.

How well does darcs scale?

A. There are three directions in which a VC system can scale: having long histories, having a large source tree, and having large single commits.

Darcs scales well in the first direction, if you know what you're doing. In other words, Darcs should have no problem dealing with 10 years of history and tens of thousands of commits, although it might require some manual intervention every few months (darcs optimize --checkpoint) and some commands might not be usable in practice without limiting their scope. Making sure to tag regularly also helps with this sort of scaling.

In the other two directions, darcs now scales moderately well, due to recent improvements. Darcs should be able to handle a repository the size of the linux kernel, and should be able to handle patches that make changes of the size of the linux kernel. Some commands may yet not be optimized to scale as they ought, and some are inherently slow (annotate, for example) due to the format in which darcs stores information. Reports of commands that behave poorly on large repositories are welcome.

Here are some data points about people's experiences using darcs on larger projects. Note the date that these were published -- darcs has been improving in scalability with each release:

Upgrading to darcs 2

Is darcs 2 compatible with darcs 1 repositories?

Absolutely! You can use darcs 2 to work with darcs 1 repositories if you want. In fact, using darcs 2 to work with darcs 1 repositories is probably a better idea than using darcs 1 to work with darcs 1 repositories :-)

Why do I get lossy conversion warnings when I convert to the darcs 2 format?

This is because convert "flattens" some conflicts, converting them into ordinary non-conflicting patches, and the result of this flattening depends on the repository state (and the order of patches in a repository).

Basic usage

How do I go back to an older version of my repository?

Short answer: darcs get --tag or darcs get --to-match

Long answer: What exactly do you mean by go back to an older version?

If you're just a casual darcs user, and you want to go back in somebody else's repository, first check to see if they have any tags: darcs show tags. If so, you can darcs get --tag T, where T is the name of the tag you want to go back to.

If they don't have any tags, then you can use darcs get --to-match (see darcs help --match for more details) to pick which patch we should match up to.

Does Darcs even have a notion of versions?

Yes, but it's not what you may expect.

Darcs thinks in terms of patches. The darcs history is just a sequence of patches. As an informal example, one person might have a darcs repository with the patches (A B C), whereas somebody else might have (A C D). What exactly do we mean by version then? Darcs operations are about adding and removing patches to this sequence. If your repository has patches (A B C), and your friend has (A C D), and you pull from his repository, you will have sequence (A B C D) in your repository.

Anyway, suppose we have a repository A B C D, what does it mean to go back to a previous "version?"

One way might be to do something like darcs get --to-match 'name B', which will give you the sequence (A B). But what if instead of going back to B, you just wanted to get rid of B? Darcs is quite happy to do that, dependencies permitting.. You could darcs get a copy of the repository and then do darcs obliterate --match 'name B' to just get rid of patch B.

In the Darcs world, a "version" is simply a set of patches. So if you want to get exactly the same version of a repository as somebody else, you have to get the same set of patches that they do. (Darcs's job is to guarantee that the same set of patches in any order gives the same result)

How do I get exactly same set of patches as somebody else?

By using tags or context files. See the user's manual for more details.

Darcs seems to hang when I pull or apply patches. Why?

If you are pulling patches (as opposed to applying them), you may be dealing with too many untagged patches. See the questions in the Performance section above. Otherwise, you might have run into the exponential time conflicts bug (darcs 1.x). See the ConflictsFAQ for more help.

How can I find out what files darcs is managing?

(similar to the tla inventory command).

darcs show files

This command has been around since darcs 1.0.4 (under the name of query manifest), and was renamed to show files in 2.0.0

How do I find out what files darcs is not managing?

I.e. those files that would be marked with a ? by cvs update.

Use darcs whatsnew -ls. Files which darcs thinks you might want to add marked with a lower case a. To have darcs always ignore certain files (equivalent of .cvsignore), you can use a boringfile (see the manual). To see also what boring files darcs is not managing, use darcs whatsnew -ls --boring.

In the boringfile, if you want to match a directory and its contents, use a regex like:

^foo(/|$)

In particular, be aware that there is no / or ./ at the beginning of the paths that darcs matches against.

I use darcs to record changes made to configuration files in my /etc, is this safe?

No. As mentioned above, darcs does not version file permissions; files pulled will have permission bits set as if they were newly-created files. Many files in /etc need specific permission bits; therefore, it's not currently safe to control their versions with darcs.

How is the syntax of the uri for push/pull using different protocols?

I had a little bit of problems for finding the right syntax

  • ssh:
  • darcs pull username@host.com:path/relative/to/home

    darcs push username@host.com:path/relative/to/home
  • ftp:
  • darcs pull ftp://user:password@host.com/path/relative/to/home
    The password can be omitted, but you'll have to type it several times. darcs push doesn't work via ftp
  • http:
  • darcs pull http://domain.com/path/to/repo
    darcs push doesn't work via http
  • mail:

  • Use darcs send/apply

How do I list all the tags of a repository?

$ darcs show tags

More detailed:

$ darcs changes --tags="."

How can a group share patches without access to each other's repos?

Use context files, and send and apply with patch bundles.

A context file is created with

darcs changes --context > con_A

and contains everything darcs needs to know to "fake" a send to a repo. These context files can be distributed over the group.

Person A:

darcs send --context=con_B -o bundle .
[interactive]
mail B < bundle

Person B:

darcs apply bundle

As B applies new patches, A's (and every one else's) context file for B's repo get more and more out of date, so B should at times send out an updated contextfile.

Person B:

darcs changes --context > con_B
mail A C D < con_B

How does darcs know which files to treat as binary?

You tell it by updating the _darcs/prefs/binaries file.

Since version 0.9.14, there is also support for automatically treating files containing ^Z or '\0' as binary.

How do I avoid typing my ssh password all the time?

Upgrade both your server and your client sides to a version of darcs 2. This implements a form of ssh connection sharing which reduces the number of connections to at most two.

Darcs pull/push over ssh doesn't work when the darcs binary is in a nonstandard location?

Make sure that the darcs binary is located in a directory that is in the PATH even for non-interactive shells. You can test this with:

ssh remotehost echo \$PATH

If the path where darcs is located doesn't show up, you have to modify the PATH variable in a configuration file that is read by the shell even for non-interactive logins (like ~/.zshenv for ZSH or ~/.bashrc for bash).

How can I tell which patches I pushed to a remote repo before?

You can use darcs push --dry-run -p 'PATCHNAME' remoterepo where PATCHNAME is the name of your patch and remoterepo the location of the other repository. If darcs says 'Nothing to push' you have not been pushing that patch yet.

Advanced usage

Why doesn't darcs have a getpref feature to go with setpref?

Try darcs show repo. It will print out the prefs along with other information about the repository.

Features

Does Darcs support binary files?

Yes. You can have multiple versions of a file in a repository, and go back to earlier versions.

Each revision of the binary file is stored in its entirety, not as deltas (as Subversion does). There has been some discussion about using a binary delta patch format such as xdiff3 or bsdiff to improve storing efficiency, but the one person competent to pull such a change (David) doesn't keep binary files in his repos, and hence is not interested.

Thomas Lord describes a work around for Arch that should also work for darcs. It seems that once darcs adds hooks, this process could be automated.

You may also interested to this answer explaining why Arch currently versions binaries without a binary diff (what darcs does).

One notable feature about the way things are is that you cannot have a merge conflict between parts of a binary file; its either all or none.

Does darcs version file meta data, such as permissions?

Not fully. Setting the executable bit based on a shebang (#!) line at the top is possible by using the --set-scripts-executable option.

That would set all scripts that can be executed by unix to be executable. It wouldn't fix binary executables, but those usually shouldn't be managed by darcs anyway.

An alternative to the above is to keep your files non-executable in the repository, and use a predist pref to tweak the permissions. Write a script called fix-perms that does all the tweaking needed, and then do

darcs add fix-perms
darcs setpref predist 'sh ./fix-perms; rm fix-perms'
darcs record

Recall that prefs are versioned if you use setpref.

Note that darcs will not preserve file permissions, even on local pulls between repos owned by the same user. From testing, it appears that the permissions in the target repository are set as if a new file had been added to that directory, regardless of the permissions in the source repository.

Does darcs support nested repositories, or allow you to check out a working copy that is a subtree of another repository?

The short answer is no, you can only duplicate and modify repositories. It is possible to nest repositories, however this is not really recommended, and it is certainly not flexible enough for you to manage things similar to the way you would with inherently hierarchical systems like CVS and SVN.

See NestedRepositories for more information.

Does Darcs support Unicode?

This is actually two separate questions.

Can I version control files with characters in the full Unicode spectrum?

Darcs is almost agnostic to character-encodings, the big exception being that you have to use some sort of 8-bit encoding in order for darcs to treat your files as text.

UTF-8 works, as files would usually contain no embedded ^Z or \0 (encoding of characters outside the ASCII range uses bytes with the high bit set). See the manual section on characters sets: "UTF-8 will work if you set DARCS_DONT_ESCAPE_8BIT to 1", otherwise all non-ASCII characters will be escaped when output.

Apart from output issues, UTF-8 works largely because of its compatibility with ASCII -- common end of line markers (U+000A and U+000D) are identified and files can be treated as text, whilst the rest of the Unicode range is encoded only using specific sets of bytes with the high bit set.

UTF-16 is not well supported as it is (usually) treated as binary due to \0 bytes (basic European alphabet ranges include \0, e.g. 'A' is encoded as 00 41).

Can I write patch comments, or have an author name, with characters in the full Unicode spectrum?

Darcs agnosticism wrt character encodings can be a problem here if you are collaborating with people that use different character encodings. The best practice is to make sure that everybody uses the UTF-8 encoding.

How do I sign and verify darcs patches?

There are actually two questions you could ask: how to sign patches, and how to sign repositories. Darcs gives you a mechanism to sign individual patches (using GPG), but it doesn't yet support the signing of repositories.

See ... TODO

How do I sign and verify darcs repositories?

This isn't possible yet, but it should be possible if we... TODO

Other

How would I go about using darcs for a SourceForge project?

Sourceforge does not currently have darcs installed on their project shell servers, making it impossible to use ssh/scp to perform darcs pushes. However, if a local repository is available you can mirror that repository to your Sourceforge project, using rsync -- this is how http://cloudwiki.sourceforge.net currently maintains their repository on Sourceforge. This works well for projects that have a single maintainer who accepts patches from contributors.

It is possible to upload a darcs binary to your SourceForge shell account, but it may be a breach of your user agreement with Sourceforge. A better strategy would be to request SourceForge install darcs on their shell server. If you or Sourceforge install darcs, you can either use darcs.cgi or darcs-repo on the server, and use Sourceforge's site administration tools to designate individuals who are permitted to modify the repository.

Be aware that SourceForge currently only officially supports CVS and Subversion, and that project shell services are ostensibly only for web site administration and web demonstrations of your project -- even hosting the repository on shell services is somewhat of a grey area.

If you are interested in a having official support for darcs from this kind of service, see the question above about hosting.

How do I start using darcs for a web application (or some other code base) that is already in production?

It is trivial to start using darcs for an existing web application that has two environments; in my case the environments are testing and production. To get started, I did the following:

  • Backup everything; it never hurts to have some backups
  • Do the following in the production environment:
  • darcs initialize
  • [optional] add stuff to ignore to the boring file
  • I had to add a directory var/ to my boring file because I wanted that to be different in all of my repos. Adding the directory to the boring file makes darcs ignore the var/ dir.
  • darcs add --r ./
  • I did this so I could add everything in my production environment to the darcs repository, you might want something different, if so, read the darcs add help.
  • darcs record --all --look-for-adds
  • I named my patch ‚"initial revision from production,"
  • Now the magic: without creating a darcs repository, copy the _darcs directory, in its entirety, from the production environment to the development environment.
  • Issue the following command in the development environment (now with the production environment's _darcs directory):
  • darcs record --look-for-adds
  • For this patch, I named it something like "initial revisions from development‚" That is it; you now have a repository that contains your production code, up to date with your development changes. In my scenario, I had to consolidate a project that had multiple developers working on both the production and the development environments, without keeping the other up-to-date.

How can I control the umask of the files a darcs push operation creates?

It's a typical use-case that a remote unix server is used to share a repo using SSH accounts and a unix group for the project members. By default darcs runs with the server's umask, which usually does not include group write permissions. Currently you have two options to set the umask:

  1. add the line "apply umask 0002" to _darcs/prefs/defaults
  2. add the line "apply umask 0002" to ~/.darcs/defaults I've created an issue for a system-wide solution for this: issue1185

How do I look at a certain file before patch X without using the cgi?

This functionality is sorely missing from darcs. The following hack, based on code in vc-darcs.el, should work:

cp $file /tmp
darcs diff -u --from-patch=$patch $file > /tmp/alamakota.diff
(cd /tmp; patch -R <alamakota.diff)
cat /tmp/$file

This assumes that $file doesn't contain any slashes.

How do I see different patches if their names are not unique?

Use the hash part of the xml output (the gz extention can be omitted):

$ darcs changes --xml-output
<changelog>
<patch author='me@email.com' date='20040605033308' local_date='Sat Jun  5 05:33:08 CEST 2004'
 inverted='False' hash='20040605033308-e14b9-451ae7bc1c4e822940526960e4d8a1faed2f5ed4.gz'>
        <name>initial import of hello.txt</name>
</patch>
</changelog>
$ darcs annotate --match "hash 20040605033308-e14b9-451ae7bc1c4e822940526960e4d8a1faed2f5ed4.gz"
[initial import of hello.txt
me@email.com**20040605033308] {
addfile ./hello.txt
hunk ./hello.txt 1
+Hello darcs!
}

Can I flag a patch so it doesn't get pushed or pulled?

This would typically be for changes that are only for local use; e.g. configuration files.

And the answer is: no.

Troubleshooting

Darcs get cannot fetch my repository! (2.0 to 2.2.x)

Does the following variant of darcs get fix it?

darcs get --hashed <your-repository>

This sort of error can occur if you

  • your darcs 2 is older than 2.3 (which uses --hashed by default)
  • are on a case-insensitive filesystem (e.g. on MacOS X or Windows)
  • and are trying to fetch a repository where Darcs is tracking files whose names only differ in case (e.g. mainWidget.c vs. MainWidget.c)

Prior to Darcs 2, all repositories used what we now call the "old-fashioned" format which is suspectible to case-sensitivity errors. Darcs 2 is more careful about catching these errors than Darcs 1. Unfortunately, this means that it will fail to fetch some old-fashioned repositories. Fortunately, you seamlessly retrieve your repositories using the new, more resiliant, "hashed" format. Moreover, if you are using Darcs 2.3 and up, this will now happen automatically by default.

For more robustness and access to optimisations, we recommend upgrading all your public repositories to the hashed format.

See issue1453 for more details, or let us know on the mailing list if you are having any trouble.

Strange conflicts

Why do my darcs replace patches conflict?

If you have two parallel darcs replace patches that use different token char expressions, they are treated as a conflict because TODO

Too many open files (Mac OS X)

When attempting to pull many patches at once, the following error may be encountered:

darcs: getCurrentDirectory: resource exhausted (Too many open files)

By default, OS X only allows each process to have 256 files open. For performance reasons, darcs keeps a lot of files open when pulling patches and may exceed this limit. In most cases, the solution is to increase the limit. This can be done by using the ulimit bash command.

$ ulimit -a
core file size        (blocks, -c) 0
data seg size         (kbytes, -d) 6144
file size             (blocks, -f) unlimited
max locked memory     (kbytes, -l) unlimited
max memory size       (kbytes, -m) unlimited
open files                    (-n) 256
pipe size          (512 bytes, -p) 1
stack size            (kbytes, -s) 8192
cpu time             (seconds, -t) unlimited
max user processes            (-u) 266
virtual memory        (kbytes, -v) unlimited
$ ulimit -n unlimited
<darcs commands go here>
$ ulimit -n 256

Sometimes, calling ulimit will result in the following error:

-bash: ulimit: open files: cannot modify limit: Operation not permitted

If this happens, start a new shell and try it in the new shell. (There should be a more convenient way to do it but I don't know of one.)

If this doesn't work for some reason, the issue can usually be worked around by pulling fewer patches.

Patches falsely reported as missing

Sometimes darcs will say to you:

darcs: Cannot apply this patch bundle, since we're missing:

And then print the info for a patch that you do have.

In this case, there may be an encoding issue. If the context the patch bundle is encoded in a different way than the context in the repository, and the patch info contains non-ASCII characters, the patches are not recognized as being the same. In this case the sender of the patch must probably make sure that the patch bundle is sent with the right encoding.