[[`TableOfContents `_([maxdepth])]] 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: - `http://article.gmane.org/gmane.comp.version-control.darcs.user/7082 `_ - `http://thread.gmane.org/gmane.comp.version-control.darcs.user/7295 `_ [[Anchor(start-prod)]] 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 --to-match`` Long answer: What exactly do you mean by go back to an older version? *TODO* 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). :: 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. How can I compare patches which result in a conflict? I also want to see their full log entries. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ *TODO* 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? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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. 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? ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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. Other ----- Where can I find hosting for my darcs project? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ See Self:Hosting for some options 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. 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 `_ 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 `_ 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 initial import of hello.txt $ 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 --------------- 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* 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 $ 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.