~jan0sch/darcs-book

~jan0sch/darcs-book/en/01-introduction.md

title: Introduction prev: index next: chapter02 toclink: yes ---

Introduction

Welcome!

So, you want to learn version control, or more specifically, you want to learn darcs? That's great! I hope this book will give you an interesting perspective on how to manage your projects and enable you to work with other people all around the world. I want to encourage you to follow along with the examples I present in this book and play around with them a bit. Things sometimes happen to make a lot more sense when you type them yourself and see things happening right in front of you. If you haven't used any kind of version control before I hope this book empowers and equips you with new tools that help you to manage your projects and improve your collaborations. If you have been using traditional centralized version control systems as well as other distributed systems I hope this book gives you a new perspective on how things can be done differently since darcs tackles version control in a refreshingly unique way.

In this book I will assume that you are using a Unix or Unix-like operating system.

Most of the examples in this book happen inside of a shell and the issued commands are prefixed with a $ symbol while its output isn't prefixed with anything. Here's an example command that only outputs the word output.

$ echo output
output

What's version control?

Ever had to write an important document over an extended period of time? Then you probably know how this works. You start with important.txt and after a couple of weeks you end up with a folder full of files like this:

-rw-r--r--   1 raichoo  raichoo   19182 Jun  7 23:23 important.txt
-rw-r--r--   1 raichoo  raichoo  121890 Jun  8 15:04 important_final.txt
-rw-r--r--   1 raichoo  raichoo   48245 Jun 11 18:48 important_really_final.txt
-rw-r--r--   1 raichoo  raichoo   35099 Jun 11 21:09 important_final_1.txt
...
-rw-r--r--   1 raichoo  raichoo    6887 Jun 22 18:34 important_final_20487.txt

And if that wasn't confusing enough, you then end up in a situation where you want one part of an older revision in your final version. To make matters even worse, at some point in time a friend of yours volunteered to write some other portion of that document and you start mailing full copies of your document back and forth while you are trying to stitch all of your work together. Needless to say that this isn't much fun but a rather frustrating task that makes working on your project much less enjoyable.

Enter version control! With version control you can keep track of all the changes you have made to your document. You want to revert a portion of your project to a previous revision? No problem, version control takes care of that! It keeps track of the history of your project as time progresses and gives you access to older versions of your project. Deleted something important? Like the older version of a piece of text better than the new one and want it back? No problem! If it's in your version control you have access to it. You can even share your work with others and pull in their changes without doing all the work by hand! Magnificent!

What's a DVCS?

The world of computering is full of acronyms and version control is no exception. darcs is a so called DVCS, which stands for distributed version control system. Now that's a mouthful. But what does it mean? Remember that a version control system keeps track of all the changes you have made to your project? Now here is where the distributed part comes in. Everyone working with you on a project has a complete copy of that projects history on their computer, so you don't even need to be online to have access to all of that information. Your collaborators can make their own changes to the project and share those with you. Nifty huh? We say that every party has their own copy of the project's repository. That's not always the case, there are so called centralized version control systems like svn where you only have the most recent revision of the project on your machine. To access older ones you need to be able to access a server.

Why `darcs`?

In the world of DVCS darcs is a pretty unique animal. Most version control systems take a snapshot of your work and each snapshot depends on one or more previous snapshots. darcs doesn't do that. Instead darcs keeps track of what actually changes. We call that this approach patch based and it has some cool effects when working with multiple people on a single project.

Let's compare that snapshot based approach with the way darcs does it so you can see what I mean.

I'm working with my friends tauli and jeanny on a project. tauli has written some great code (let's call that patch some code) and jeanny has provided some awesome illustrations (let's call that patch graphics). I want to pull their patches into my local copy of the project. gimbar, another friend of mine, wants to do the same to their copy.

First, let's look at the snapshot based approach. We are using a popular tool called git to illustrate this. If you don't fully understand what's happening here, that's fine. It's not necessary to use darcs efficiently.

In the beginning gimbar and I both are on the same snapshot which I have suggestively called "previous work". Both our repositories look like this. git calls its snapshots commits and it uniquely identifies them with a 40-digits long hexadecimal number, in this example our commit previous work would be identified by the hash 85b41da2f0a273c6691ee56b13dfe3590d4d0418.

commit 85b41da2f0a273c6691ee56b13dfe3590d4d0418
Author: raichoo@example.com
Date:   Tue Jun 26 18:58:52 2018 +0200

    previous work

gimbar then pulls in jeanny's and then tauli's patches. gimbar now has the following patches in their repository. It now consists of our previous work snapshot and then adds jeanny's and tauli's changes on top of that. git also adds a Merge due to the fact how snapshot based version control systems work. This is what will cause us problems later.

commit fd9d393916a76bf716d4af6485556182aaaab5a2
Merge: c083eb1 425b39d
Author: gimbar@example.com
Date:   Tue Jun 26 19:00:37 2018 +0200

    Merge

commit 425b39d34417584427ed47218803056974afdfd8
Author: tauli@example.com
Date:   Tue Jun 26 18:59:53 2018 +0200

    some code

commit c083eb19fab5f67694d3dc18e283dcc56798a0aa
Author: jeanny@example.com
Date:   Tue Jun 26 18:59:42 2018 +0200

    graphics

commit 85b41da2f0a273c6691ee56b13dfe3590d4d0418
Author: raichoo@example.com
Date:   Tue Jun 26 18:58:52 2018 +0200

    previous work

Now I come along, sadly I don't know that gimbar already pulled in the other patches and for some reason I happen to pull in tauli's patches first and then jeanny's. I now have the following patches applied to my repository.

commit 48f2fa962e67f7bbb12d1f4d6d3b823e1905b16c
Merge: 425b39d c083eb1
Author: raichoo@example.com
Date:   Tue Jun 26 19:00:14 2018 +0200

    Merge

commit 425b39d34417584427ed47218803056974afdfd8
Author: jeanny@example.com
Date:   Tue Jun 26 18:59:53 2018 +0200

    graphics

commit c083eb19fab5f67694d3dc18e283dcc56798a0aa
Author: tauli@example.com
Date:   Tue Jun 26 18:59:42 2018 +0200

    some code

commit 85b41da2f0a273c6691ee56b13dfe3590d4d0418
Author: raichoo@example.com
Date:   Tue Jun 26 18:58:52 2018 +0200

    previous work

git created those Merge patches for us, but they are quite different for gimbar and me. They have a different author, a different timestamp and most importantly, they have a different commit hash. Now we have to coordinate how we proceed because we are not working on the same snapshot anymore.

In the snapshot based approach we end up with both of our repositories in different states even though both of us pulled in the same patches, we just have pulled them in in a different order.

darcs is different because it's patch based. In darcs a repository consists of a set of changes and these changes are represented by a patch. The order in which we pull them in does not matter. So in the above example gimbar and I end up with our repositories being in the same state even though we have pulled in the changes in a different order. Let's take a look at the same example but this time using darcs.

As before we start with some previous work and we want to base our upcoming work on this. Just like git darcs is using a 40-digit hexadecimal number to uniquely identify patches (for the curious, darcs internally uses SHA-256 to hash the contents of files).

patch 1354819f7c0c26ca865820ad26e184dbcdbde752
Author: raichoo@example.com
Date:   Mon Jul  2 19:35:59 CEST 2018
  * previous work

As before gimbar will first pull in jeanny's and then tauli's changes, bringing our repository into the following state.

patch 90865492c33c9aa5e87ffeb2501095a1772d1248
Author: tauli@example.com
Date:   Mon Jul  2 19:41:15 CEST 2018
  * some code

patch e0d0cfa5cee7882d9a4cb5b6032a22b38114f045
Author: jeanny@example.com
Date:   Mon Jul  2 19:40:10 CEST 2018
  * graphics

patch 1354819f7c0c26ca865820ad26e184dbcdbde752
Author: raichoo@example.com
Date:   Mon Jul  2 19:35:59 CEST 2018
  * previous work

Doesn't look that different, except there is no Merge patch like there would be in git. Even better, when I pull those changes in in reversed order I'm going to end up with a repository state that looks like this.

patch e0d0cfa5cee7882d9a4cb5b6032a22b38114f045
Author: jeanny@example.com
Date:   Mon Jul  2 19:40:10 CEST 2018
  * graphics

patch 90865492c33c9aa5e87ffeb2501095a1772d1248
Author: tauli@example.com
Date:   Mon Jul  2 19:41:15 CEST 2018
  * some code

patch 1354819f7c0c26ca865820ad26e184dbcdbde752
Author: raichoo@example.com
Date:   Mon Jul  2 19:35:59 CEST 2018
  * previous work

"But hey! You might now have the same patches but they are in reverse order? Doesn't that mean that mine and gimbar's repository are different?", I hear you say. That's one of the beautiful things about darcs and what makes it so fundamentally different from other version control systems, even though the patches have been applied in reverse order, for darcs both of our repositories are in the same state.

This approach is great when working together with a couple of people because all of them can mix and match just to their liking and in the end we don't need to do extra work to bring everything back together.