A beginner’s guide to Darcs

This document is intended as a quick guide to using darcs. It also also gives some example usage patterns.

This tutorial is available as

• PDF
• HTML

What is darcs?

darcs is a version control system, based on patches. A patch represents some change in the files, and the total collection of changes constitutes the repository.

When working on the files, one has a local copy of the repository. One can work on the files in the local copy as one normally would. After doing some changes, one records them to make a patch. After the patches are made they can shared with others, who can incorporate the changes into their repositories.

Why use darcs?

The motivation for using darcs is that it makes it easier for more than one person to work on a set of files simultaneously. One does not need to manually stitch together the changes made. It also gives a backup of everything, and records the history of the development.

Darcs works best with text files, such as source code, markup (such as HTML, or markdown), or plain text files.

Common commands

The following are the basic commands needed in order to use darcs.

darcs init

Create a new, empty repository in the current directory.

darcs get

Creates a copy of a repository. This is only done once to set up the local copy on your machine.

darcs add [FILE]

Tell darcs to add the [FILE] to the repository.

darcs record

Create a patch from the changes made to the local copy. This is done every time you have done some change which could be considered a logical unit.

darcs pull

Get patches from another repository.

darcs push

Push your patches to another repository.

Example of using darcs

Say I would like to work on my Agda computation library. The task at hand is to add a todo file with my current goals. At the moment there is no todo list, so when the file is created we need to alert darcs attension to it by use of darcs add.

$ darcs get ichor@hub.darcs.net:computation
Copying patches, to get lazy repository hit ctrl-C...
Finished getting.
$ cd computation
$ ls
Computation.agda    Predicate.agda      _darcs/             old/
mkfile
$ cat todo
# TODO
 - Fill out list of things todo
[EOF]
$ darcs add todo
$ darcs record
addfile ./todo
Shall I record this change? (1/2)  [ynW...], or ? for more options: y
hunk ./todo 1
+# TODO
+ - Fill out list of things todo
Shall I record this change? (2/2)  [ynW...], or ? for more options: y
What is the patch name? Added todo file.
Do you want to add a long comment? [yn]n
Finished recording patch 'Added todo file.'
$ darcs push
Pushing to "ichor@hub.darcs.net:computation"...
Thu May  7 08:39:34 CEST 2015  Ichor <ichor@Xishan>
  * Added todo file.
Shall I push this patch? (1/1)  [ynW...], or ? for more options: y
Finished applying.
Push successful.

More about the basic commands

To find out more about how each of these commands work, run

darcs help [COMMAND]

Or read the relevant sections of the manual.

Using darcs

We will now review typical uses of darcs.

File manipulation

Files managed by darcs can be edited in any editor. Darcs will automatically detect changes in the files which are under its supervision when you do darcs record. Some file manipulations can be done by darcs, which means that it can gracefully apply these changes in different contexts. For example moving a file can be done by darcs so that if another patch changes the same file, before it was moved, the changes will be applied to the file where it was moved.

Another useful file operation is replacing a string with another. This can for example be used to change the name of a function across an entire project, so that even parallel developments using the old name will be gracefully changed to the new name when the patch is applied.

A good practise is to use replace to change the occurences of a file name in other files when moving the file.

File manipulation commands

darcs move [FILE] [DEST]`

Move file to destination

darcs replace [OLD] [NEW] [FILE]

Replace the [OLD] with [NEW] in [FILE]

Patch dependencies

When creating a patch darcs determins which other patches needed to be in place for the changes to make sense. These patches are the implicit dependencies of a patch. There are also explicit dependencies, which you can specify using the flag --ask-deps when running darcs record.

When pulling or pushing a patch, darcs will pull/push all its dependencies.

Example: Using explicit dependencies.

Tags

A tag is a special kind of patch which names the current state of the repository. The way it does so is by depending on all previous patches. Since a tag has a lot of dependencies it allows darcs to optimise the merging of two repositories when they have shared tags.

Good practise is therefore to tag the state of the repository quite often. Giving the tag an informative description helps referring to it later.

Tag commands

darcs tag

Create a tag.

darcs list tags

List the tags in the current repository

Branches

Repositories which share some patches (but not all) are called branches. It is often practical to have several branches for each project — each with a different purpose.

Examples of branches

Some different use cases for branches:

• The trunk. A centrally located repository, representing the current state of development. In coding projects it is good practise to keep the code in the trunk compiling at all times.
• Working copy. A copy where one is performing current work.
• Feature branch. A branch dedicated to devoping a specific feature. Once the feature is done and tested, it is pushed to other branches and can be deleted.
• Version branch. A branch dedicated to a specific version of the files, for example targetting a public release.
• Fork. A branch of a project intended to be an independent development.

These are all fairly long-lived branches. It is also useful to create one-off branches for various tasks.

Going back in time

Darcs allow you to create branches which contain any subset of patches, as long as they are closed under dependencies. This means that you can go back to an earlier state of the repository. For example when programming, this allows new work patterns and there are obvious benefits when trying to locate the source of a regression.

You can also roll back previous patches by constructing an inverse patch. An inverse of a patch is a patch which has the effect of undoing the changes made by the patch. This is useful of if you have revised some parts of your files, and later find out that the old version was better. The newer version is still kept in the history of the repository, so you can continuing your experimentation later, by rolling back the rolling back.

Finally, you can obliterate a patch. Obliterating a patch completely removes it from the current repository. It is recommended to exercise caution when obliterating patches, as you can loose important work. Obliterating can for the most part be avoided by using other techniques.

Commands for time traveling

darcs get --tag [TAG] [REPOSITORY]

This branches [REPOSITORY] and fetches the patches up to [TAG].

darcs pull [REPOSITORY]

When pulling [REPOSITORY], darcs will ask you which patches you want to pull, allowing you to choose the subset you are after.

darcs rollback

Lets you specified a set of patches, and constructs an inverse patch for them.

Example of cloning a repository up to a tag.

We can get version 1.0.0 of darcs.

 $ darcs get --lazy --tag 1.0.0 darcs.net
   (…)

Example of pulling only the desired patches

Say I would like to get a copy of my Agda computation project and check that it will compile without the old files.

 $ mkdir computation.no-old
 $ cd computation.no-old/
 $ darcs init
 $ darcs pull ichor@hub.darcs.net:ichor/computation
Tue Apr 28 09:26:29 CEST 2015  Ichor <ichor@Xishan>
  * Added computation module.
Shall I pull this patch? (1/4)  [ynW...], or ? for more options: y
Tue Apr 28 09:27:19 CEST 2015  Ichor <ichor@Xishan>
  * Added old computation things.
Shall I pull this patch? (2/4)  [ynW...], or ? for more options: n
Tue Apr 28 09:28:05 CEST 2015  Ichor <ichor@Xishan>
  * Added minimal mkfile
Shall I pull this patch? (3/4)  [ynW...], or ? for more options: y
Thu May  7 08:39:34 CEST 2015  Ichor <ichor@Xishan>
  * Added predicate logic lib.
Shall I pull this patch? (4/4)  [ynW...], or ? for more options: y
Finished pulling and applying.
 $ ls
Computation.agda  _darcs  mkfile  Predicate.agda
 $ mk all
(…)
Finished Computation.

Example of rolling back a patch

Example of locating a regression

Amending

Conflicts

Testing

Signing