• FrequentlyAskedQuestions

Performance

Darcs is so slow when I try to push/pull/send (and seems to hang?)... why?

There are several possibilities.

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,

1. Check to see if the same darcs operation is significantly faster when dealing with a repository that is on the same machine.
2. If you are using ssh, check to see how long a single ssh connection makes

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:

• http://article.gmane.org/gmane.comp.version-control.darcs.user/7082

• http://thread.gmane.org/gmane.comp.version-control.darcs.user/7295

Basic usage

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 do I add an entire tree of files to Darcs?

$ darcs add -r .

How can I find out what files darcs is managing?

(similar to the tla inventory command).

With darcs 1.0.4pre2 or later, you can do this with a simple

darcs query manifest

With older versions, you can use the fact that Darcs keeps a copy of all the managed files under _darcs/pristine, by using something like

find _darcs/pristine -type f

or

(cd _darcs/pristine && find * .[!.]* ..?* -type f)

or with GNU find

find _darcs/pristine -type f -printf "%P\n"

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.

How can I compare patches which result in a conflict? I also want to see their full log entries.

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 changes --tags="."

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

A: 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?

Four possible answers:

1. Use ssh-agent (if you have or are willing to generate an ssh keypair). This is explained elsewhere on the internet

2. Get a recent version of darcs and ssh. Darcs 1.0.7 to darcs 1.0.8 should fix this problem, but only if you have a recent version of OpenSSH (with the ControlMaster feature). Unfortunately, the feature had to be withdrawn in 1.0.9 (by default) because it causes mysterious hanging in some cases. You can reenable it with the --ssh-cm switch (which can also go in your defaults)

   • Unfortunately, for Mac OS X 10.4 (Tiger), the default ssh is not recent enough. You will have to install a newer version using Fink or DarwinPorts and either put your fink/dp paths in front or set the DARCS_SSH environment variable to /opt/local/bin/ssh (along with DARCS_SCP and DARCS_FTP, replacing ssh with scp and sftp respectively)

3. Use password-less ssh keys, which is likewise explained elsewhere on the internet

4. Use fsh: it creates a persistent secure tunnel between two machines using ssh, asking password just once

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).

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 have support for RCS style keyword expansion?

No, see DifferencesFromCVS.

Can darcs handle symlinks?

No. Symbolic links are unsupported by darcs as of version 1.0.3.

Does Darcs support Unicode?

Not fully, although UTF-8 does work a bit.

UTF-8 partially 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).

Other

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 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, you may have better luck petitioning an alternative such as Berlios.de, which already supports both CVS and Subversion. Further along the lines of abandoning Sourceforge, you could also set up a TracOnDarcs installation at your site.

What's the best way for a user to work on Darcs itself, as far as local versions of David's darcs repo, pulling and sending goes?

See DeveloperFAQ and DeveloperTips

Why doesn't darcs use a hidden directory like .darcs for metadata, rather than the visible _darcs?

See the corresponding issue on the bug tracker for a discussion of this question.

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 too slow!

See Performance, above.

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.