Getting started

I see that you are still here, cool! Before we can really get our hands dirty let’s get familiar with some of the terminology you will encounter when you are using darcs.

Terminology

It’s somewhat important to speak the same language when we are talking about a topic like version control so we need to establish a common vocabulary first. Don’t worry, it won’t be much and I’ll be introducing new terms as we are going along, but here are the basic terms you need to know. Some of these definitions might suffer a bit from being mutually recursive so if you don’t get it right away, don’t worry it’ll all become a lot clearer once you start using darcs.

• Working Tree

  This is the directory tree where our project files reside, all work is done here.

• Repository

  We already talked a bit about this but let’s keep our most basic terms in one place. A repository is a place where darcs stores information about a project’s history. As our working tree changes through time we can record patches that represent those changes and store them in our repository together with additional information like, what changed, who did the changes and when.

• Change

  A change is a modification that we have done to our working tree. It can be something like adding or removing a file, changing the content of a file, moving a file from one place to another etc. To find out if something has changed in our working tree, darcs checks its contents against the state of the repository.

• Patch

  A patch is how we represent changes. Whenever we want to remember changes we do this by recording a patch. A patch is made up out of one or more changes and takes a repository from one state to another.

Knowing this we can now formulate the statement:

The state of a repository is defined by a set of changes.

Whoa, hold on a second! That sounds pretty mathematical, and that’s because it is. But don’t worry, the ideas we are dealing with here can be expressed in simple ways. In mathematics we have the notion of a set. Something like {1,2,3} denotes a set containing those three numbers, 1, 2 and 3. When we are talking about sets the order of their elements do not matter. So we can think of {1,2,3} and {3,1,2} as being different denotations of the same set. In darcs the order of the changes do not matter, when you have the same set of changes as someone else you will both arrive at the same repository state, it doesn’t matter in which order you acquired them.

darcs stores changes as a sequence of patches. Let’s look at a simple example.

Let A be a change that adds a file foo to our project and let B be a change that adds a file bar to our project. These two changes are independent of each other, meaning each of them can exist without the other, so we can pull them into our repository in any order. So adding A and then B to our repository gets us to the same place as adding B and then A. Maybe you remember this from school where you have learn that 1 + 2 is the same thing as 2 + 1. darcs applies this concept to patches and it’s called commutation and it is vital to the way darcs works. In our example we say that “A and B commute” which basically means that the patch sequence AB (first apply A than B) gets us to the same place as the sequence BA.

Installing darcs

If you are running a Unix or a Unix-like operating system. You should be able to install darcs via your package manager. Since darcs is written in Haskell, you can also install it using stack or cabal by doing one of the following.

$ stack install darcs

or

$ cabal install darcs

I would only recommend this when your package manager does not offer a recent version of darcs or if it is not available.

Please consult your operating system or package manager manual to find out how to install either darcs, stack and/or cabal.

Once you have darcs installed you can use darcs --version to find out what version you are currently using.

Using the darcs command line interface

darcs is used via a command line interface, that means you are interacting with it by issuing commands on the shell. If you already have used other version control systems where you mostly interact with them using fancy graphical user interfaces this might worry you a bit, but don’t be afraid. darcs has a very friendly user interface that leaves little room for unpleasant surprises. One major feature is that most of the commands offer an interactive mode, and most of the time it’s even the commands default to do things interactively. Let me give you an example.

Let’s say I want to rollback (it’s not important to understand what that means exactly, we’ll get to that later) a change, to do that I would simply issue the darcs rollback command and darcs would present me with a prompt similar to this:

$ darcs rollback
patch eec36aaa61a4fad924657cd86624ba162991860d
Author: raichoo@example.com
Date:   Mon Jun 18 12:32:34 CEST 2018
  * fish: add move color to darcs prompt
Shall I rollback this patch? (1/253)  [ynW...], or ? for more options:

I can answer with y for “yes” and n for “no” and darcs will proceed to the next patch. If I want to know what options are available to me I can simply hit ? and in the case of rollback I will be presented with the following set of options.

How to use rollback:
y: rollback this patch
n: don't rollback it
w: wait and decide later, defaulting to no


s: don't rollback the rest of the changes to this file
f: rollback the rest of the changes to this file

v: view this patch in full
p: view this patch in full with pager
l: list all selected patches
x: view a summary of this patch

d: rollback selected patches, skipping all the remaining patches
a: rollback all the remaining patches
q: cancel rollback

j: skip to next patch
k: back up to previous patch
g: start over from the first patch

?: show this help

<Space>: accept the current default (which is capitalized)

darcs also comes with a built-in help system. So if you want to know what rollback does you can simply issue darcs help rollback or darcs rollback --help and there you go, you get the manual for the rollback command.

If you just want to have a list of all available commands with a short description of their functionality darcs help is your friend.

Great! Everything you need, right at your fingertips! You don’t need to reach for a reference or deep dive into the documentation to get the job done.