Fossil-SCM: the one-stop versioning and ticket management system

Publicado el sábado, 3 de agosto de 2013

Version control and incident management (tickets) are ubiquitous in development environments. Even for solitary developers who need to keep track of their code. For users who are less technically inclined it often does not even register on their radar that it is among the possibilities. So people who are writing tend to end up with long list of files with dates and other comments appended, without knowing after a while which file was which.

I spend about half my time programming (R and Python) and the other half writing. To manage that I have used the combination of subversion (SVN) and Trac for a long time. They both work perfectly but there is a drawback. They both only work if you have an Internet connection. To work offline, and to collaborate when connections come and go, using a Decentralized Version Control System makes more sense. This allows you to commit versions on your local machine even though there is no Internet connection, and then synchronize it with your central repository later.

As a big fan of version control I also try to encourage participants of workshops I give, and students of classes I teach to start using version control for their own projects. If you have ever written a thesis of any kind, you know what it is like to wake up one day and not remember which one of any of the myriad files you have been creating is the latest version. Usually just before a deadline.

One of the best kept secrets in version control land, it seems, is Fossil-SCM. It was created back in 2006 by Richard Hipp and continues to be enthusiastically developed and supported by the Fossil community. The amazing thing of Fossil is that it gives you a one-stop implementation of version control, a ticketing system and a wiki. It is not only easy to setup but also easy to share. It is available as a single binary that just needs to be copied to be run, and this means in practice that there is no need to contact the IT-Support powers that be. Anyone can set up a fossil repository on one of the computers as being the central repository. Or simply use the repository as your own, and only your own. As a single user your will still reap all the benefits of version control and basic project management tools for your projects.

This does not mean that Fossil is limited in any way. You can go as far as you want in the complexities and flexibilities that a DVCS offers. And one of the main benefits that I find over Subversion is that it is incredibly fast and easy to work with multiple branches. So for instance, for a consultancy report I am writing I will have a trunk, and a branch for the releases (so that I can go back to whatever version it was I delivered on a specific date). The last option is especially useful in data analysis assignments where there is R code to be handed over as part of the project (something that needs to be relatively clean) and R code that is intermediate that I am working.

There is excellent documentation geared toward first time and advanced users on the fossil website. However, if you are one of those non-technical users then the instruction to “put fossil on your $PATH” may seem a bit terse. What it means is the following: to be able for you to issue a fossil command on your command line (be it windows, mac, Linux) the system needs to know where the fossil application resides. And the mechanism to tell that to you system is called the $path variable, sometimes also referred to as the environment variable. You will find how to change that by doing a search online for the system you are working on.

You can check that you have done the correct thing so far by typing fossil version. A little message resembling the following should appear:

This is fossil version 1.26 [c9cb6e7293] 2013-06-18 21:09:23 UTC

If this works then you are ready to set up a fossil to play around in. Using the command line, go to the directory where you want to set up your fossil repository. For example in windows:

cd Documents
mkdir fossilrepos
cd fossil repos

now you can create a new repository by issuing a fossil command

fossil init myrepository.fossil

Note that in the DVCS world, a repository is not a working directory. So there is little you can do with what you have just created. To start working with the repository you need to check out the repository into a so called working directory.

So let’s make a working directory. Go back one level back to the Documents folder, en then create a new folder called MyWorkingDirectory like so:

cd ..
mkdir MyWorkingDirectory
cd MyWorkingDirectory

Inside this directory we will create and change the files that belong to the project, so we need to link the directory to the fossil repository we created earlier. We do that as follows:

fossil open ../fossilrepos/myrepository.fossil

This is just a test, once you start working with fossil you will find out that you can make more than one working directory if you wish, one for each branch inside your project for instance. And of course you can name it anything you like. Also you can verify that even though we have been working with the command line, the folder now exists in your normal way of working, so go to the MyWorkingDirectory folder using the finder (OSX), explorer (Win) or Nautilus (Ubuntu). When you are there, create a small text file (any file will do).

With the new file inside the folder, you are now ready to make a first commit. That is: you are ready to include the current version of the file to your repository.

You do that as follows: back on the command line (I hope you kept you Terminal or CMD window open) you type

fossil commit -m "I am committing my first file"

If you only issue the fossil commit command, then fossil will ask you to add a note describing the changes that you are including in the repository. It is very good practice to put in something descriptive, even if it is the same as the one you issued during the previous commit. You will see why in a second.

Now that you are all set, and you have included your first file, you can start the user interface by typing:

fossil ui &

This will open browser window showing you the content of your current repository. You are by default the administrator of a fossil so you can make changes to the settings and the interface under the admin tab. But first, let’s have a look at what is shown here.

You start on the home page of your Wiki. It makes it easy to keep notes about your project that you can change and edit as you go along. If you are working with more people, then everyone will see this content and will be able to make changes. The basics of using this wiki are described here.

You also have a Time Line, and this is the time line of all the changes that are made, including new tickets that have been created and changes to the wiki. You should see your first commit in your Time Line, with the description that you gave. If you change your file, then commit again with a different message and refresh the page in the browser, you should see the change instantly.

Under Files you will have a list of the files and / or folder that you have created. If the file can be shown in a browser, it will show you the contents. If not (because it is a binary file like a pdf file, powerpoint presentation, etc.) then it will not be able to show you the content.

Under Branches you will see just one branch called Trunk. Exploring the possibilities that branching brings to your work flow is something you should do as soon as you feel a little bit more comfortable using fossil.

Tickets allows you create and view tickets. These are sometimes called incidents, or tasks. When I’m working on a project by myself I like to think about this simply as my todo list, and it is a very powerful way to make sure that you are not forgetting anything, and to assign priorities to whatever you need to finish in a project. In my case, for example, as soon as I get feedback from a customer reading a draft of my report, I will turn those comments into one or more tickets, so that I can resolve them at my own pace, but never forget them.

And “never forget” is the key concept here. In fact my understanding is that Fossil is called after calcified bones just because of that: it never forgets what you did when. And it makes it very easy to ensure that you are sending out the latest version, or helps you to go back to a version where a certain paragraph still existed, but that got deleted somehow.

There are more intricate ways of working with fossil than the basic steps described above. The most important thing is that once you get a feel for making changes to your own fossil set-up, you can help yourself by automating your work flow to a T, or the work flow that you have with your co-workers.

For those who would like to work with fossil in a Spanish language environment, I have made a basic translation available here. You can either clone this Spanish version or download the configuration files.

There never was any excuse not to version your project, and with Fossil there is an immediate answer for anyone who thinks it is either difficult or cumbersome to do so.