Darcs performance is improving, but still bad in many areas. There are some things you can do to help it, though, and some specific issues with workarounds. Have a look in the performance FAQ for more help.

Short answer: darcs get --tag or darcs get --to-match, being aware that get will create a copy of the repository.

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 patterns (or for darcs < 2.3 darcs help --match) for patch-matching details) to pick which patch we should match up to.

Note that darcs get will get a new copy of the repo, at the specified patch. If you already have a copy of the repository, and want to modify it in place, use darcs obliterate with either the ’–from-match’ or ’–from-tag’ options (Note the inversion of from/to, since we want to obliterate a suffix of our patch-history, not get a prefix). N.B. darcs obliterate will obliterate the patches you select - if they are not present in another repository, they will be irrecoverable!

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)

At present, the best way to identify a patch’s hash is by running darcs changes --xml.

A minor UI bug is that the hash attribute currently includes an “.gz” suffix (issue1558) which you can omit.

Note: see Hashes for a description of how these hashes are generated (they come from the metadata, not the patch contents). This is because a patch can have different contents depending on its context.

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

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.

darcs diff -p : performs a diff; you could even use –diff-command to view the differences in a graphical viewer

darcs changes -v -p | less : shows you multiple patches. Use this if you’re not sure exactly what patch you’re looking for, but you have a some search criteria in mind. One technique would be to omit the -p and just use the search feature in your pager

A file is considered “boring” if its path matches a set of regular expressions defined in the _darcs/prefs/boring file. Darcs add will ignore such files by default. See the manual page for more details.

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.

Making use of ssh-agent will allow you to enter your passphrase just once, regardless of your darcs version; however, additionally upgrading the server and the client to darcs 2 will keep the cryptography negotiation to a minimum.

Since version 2.4, darcs has a --remote-darcs flag to set the path to the remote darcs executable.

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

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 Conflicts FAQ for more help.

To compute a diff between two different repositories, at present, you’ll need to just get a copy of the remote repository and perform the diff by hand. See issue1869 for a feature request that would add cross-repository diffing.

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.

You may find that commands like darcs pull --match X offers you patches that do not appear to match the criterion you specified.

What is really going on here is that darcs is offering you the patches that you would need to pull in order to pull patches that do match X.

There are three cases: either you don’t want to pull any patch that does not match X, or you want to pull them implicitely as needed, or you want to review them.

In the first case, you can tell Darcs not to only offer patches you can pull without any dependencies not matching X with the --no-deps flag. Of course, this implies that some matches will not be offered to you at all, since pulling them requires pulling some non-X patch. This makes sense for instance if you only want to pull patches touching a given file, but not necessarily all of them.

In the second case, you can tell Darcs not to ask you about patches not matching X, but pull them silently as needed. For this, you have to use the --dont-prompt-for-dependencies flag. Of course, this implies that some patches will be pulled without you having seen them in the interactive selection. If that bothers you, you may want to first do a darcs pull --dry-run --interactive --match X --dont-prompt-for-dependencies first, to see what dependencies will be pulled. This makes sense if you want to pull patches implementing a given feature, along with their dependencies.

In the last case, what you’re seeing is actually what you want to see, though the UI does not make it explicit that you’re seeing these patches because of dependencies.

Note that issue337 on the Darcs bugtracker has a proposed refinement to make Darcs matching more intuitive. You may want to make yourself nosy on that ticket if you’re interested in this topic.

Try selecting the patch and all its dependencies with darcs rollback, and then just selecting the changes you actually want to rollback.

Tips:

You can select patches more easily by using –match to identify the patch you’re looking for. Note that people are sometimes confused by when Darcs seems to offer unrelated matches; see the corresponding FAQ entry for more details.

Keep in mind that when selecting changes in interactive mode, you can just short cuts like ’s’ and ‘f’ to skip over or select all the changes in a file, respectively).

You’ll want to get the dependencies. Do you know which repository was the patch sent against?

Patch bundles sent with newer versions of Darcs should advertise it with a line like

1 patch for repository http://example.com/repo

If you don’t see such a line, and if the bundle was sent by email, you can look at the Darcs-URL header of that email to find out.

Now try the following:

# get the version of master the patch was sent against
# and apply the patch to it
darcs get --context p.dpatch http://example.com/master /tmp/master-lite
cd /tmp/master-lite
darcs apply /tmp/p.dpatch
# pull the patch from the copy of master
cd local-copy
darcs pull /tmp/master-lite

Using the original repo gives you the context. Using get –context makes sure you get only the context. And using darcs apply on master-lite and then pulling in the patch you really want to apply lets you pick out only the bare minimum of dependencies.

If you know the names of the patches you want to apply, you can use darcs pull -p to make cherry picking more convenient.

Darcs needs to obtain a representation of the patch before it can use patch theory to determine if it can skip it. Obtaining dependencies happens behind the scenes in the case of `darcs pull`, but in the case of `darcs apply`, Darcs does not know where to get the missing patches from. First, patch bundles only contain the patches being sent. Dependencies are refered to by a patch identifier since the idea is that you are applying a patch made against a particular repository, and can always retrieve the patches yourself from that repository. Second, Darcs (unfortunately) does not store any metadata in patch bundles that would let it know where to fetch missing dependencies from.

It helps to compare the two commands. Suppose we have a repository called “trunk” and a local copy called “laggard“. When you pull a set of patches from “trunk” to “laggard“, any patches they depend on will be automatically fetched from the same place (“trunk”). Now suppose on the other hand that somebody sends you a patch based on trunk, but your repository “laggard” is not quite up to date. If the bundle depends on some “trunk” patches that “laggard” does not have yet, Darcs gets stuck and just lets you know that it can’t apply patches due to missing dependencies.

`pull`

`apply`

patches

trunk

bundle.dpatch

dependencies

trunk

???

destination

laggard

laggard

See issue2150 for some discussion on how Darcs can improve this for the future.

Are you just trying to “clean up” the patch context? (You’ll want the upcoming darcs rebase feature)

If you’re still absolutely sure you want to do this and you know why you want to do it, then you’ll have to perform a “manual rebase”. A manual rebase consists in hand-editing the patch bundle, removing the patch bundle hash at the end, and removing the context lines. Keep in mind that patch bundles are newline-sensitive. Use at your own risk!

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 (see issue1009). This requires a change of repository format and thus is not planned for soon.

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:

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.

If you’re interested in further developments on this issue, see issue54 for a permissions tracking feature request.

No, you can only duplicate and modify entire 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 Subversion.

These two files will make darcs recreate and update symbolic links at each darcs operation. Posthooks are local to a repository, so you would have to tell people fetching your repository to put the same entry into their _darcs/prefs/defaults. If do you so this, then you can simulate versioned symlinks by version controlling the update-symlinks.sh file.

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

Darcs agnosticism w/r/t 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.

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.

Yes, just set the environment variable “DARCS_CONNECTION_TIMEOUT” with the number of second that you will wait for a connection to happen. This feature only works with HTTP repositories (and via curl, which is most likely what you’re using). The default timeout is 30 seconds.

Darcs branches and repositories are the same thing. So to create a branch, you have to use darcs get (darcs get –lazy in particular). This creates create a new directory. If you have a lot of branches, it could be a good idea to have a single container directory and subdirectories underneath it for all the branches you use, eg

foo-project
|-- trunk
|-- release-2.4
`-- hacking-on-bar

Support for in-repository branches is a frequently requested Darcs feature. We agree that having some kind of branch mechanism that does not require you to create a new directory could be very useful and we are currently thinking of how to get it right. One issue we are trying to wrap our heads around is introducing such a feature while preserving the core simplicity of Darcs.

The revert commands actually systematically backs up reverted changes in a special internal patch called “the unrevert patch”. Then, with the command darcs unrevert you can apply back the contents of this patch to the working copy.

Be careful that the unrevert patch is overwritten each time you run darcs revert. That is, if you want to use the unrevert patch as a stash branch, you have to do a single revert command. Therefore you want to use revert with the -a flag.

A manual hack you can do for a more fine-grained stashing is the following:

darcs revert ; mv _darcs/patches/unrevert xxx.dpatch

You can later apply the xxx.dpatch file to the working copy with darcs apply.

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

If you never experience bugs such as exponential merge times or [1], you are better not upgrading the patch semantics, then no. This is because the Darcs 2 format does a better job at merging some common conflicts, but it also has some important bugs dealing with duplicate patches and nested conflicts. [2]

It’s important to know that you can keep Darcs 1 semantics but still get a lot of the same benefits of the Darcs 2 format by invoking darcs optimize --upgrade (from Darcs 2.4 and up).

It is also important to know that the Darcs team will probably support old patch semantics indefinitely, so you do not need to worry about your repositories becoming obsolete.

Not officially (sorry!). The Darcs binary on Windows is a normal Windows executable that does not understand Cygwin paths. You could try, at your own risk, a wrapper script (which does the job of converting Cygwin paths like /home/foo to Windows paths) provided by the darcs user community; see WindowsConfiguration for more details.

Note that we would be happy to reconsider Cygwin support if somebody is willing to add Cygwin support for GHC.

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.

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:

add the line “apply umask 0002” to _darcs/prefs/defaults

add the line “apply umask 0002” to ~/.darcs/defaults I’ve created an issue for a system-wide solution for this: issue1185

If someone who wants to contribute to your project has a problem installing or building darcs on their OS, you may want to make it easy for them to at least get the latest recorded version of the repository.

The simplest way to provide that is to set a posthook in your repository. Add the following two lines in the file _darcs/prefs/defaults of your repository:

apply posthook darcs dist
apply run-posthook

Now, each time you push or record in that repository, the command darcs dist will be called, and a tarball myrepo.tar.gz will be created, always containing the latest recorded version of the repository files.

Now, in addition to telling people to do darcs get --lazy http://www.site.org/myrepo/ you can also point them to http://www.site.org/myrepo/myrepo.tar.gz.