Git and GitHub are by far the most popular choices when it comes to writing and managing code. Because of their popularity, however, it's easy to overlook other software configuration management (SCM) systems that may prove to be a better fit for your next coding project. Case in point: Fossil [1], a lightweight SCM that is easy to master and offers a range of genuinely useful features and functionality.

Fossil's most important advantages compared with other SCMs are the integrated bug tracker, wiki, and so-called technotes. Better still, Fossil features a built-in web interface that gives you instant web access to the repository and all its tools. In other words, Fossil offers everything you need to document your code, track bugs, and collaborate right out of the box.

Fossil offers plenty of features and creature comforts that make it particularly suited for individual developers and casual coders who need a straightforward way to keep track of their small-scale coding projects. If you are one of them, then Fossil is right up your alley.

First Steps with Fossil

The Fossil application is a self-contained, standalone executable, and it's available for all major platforms. If you run a mainstream Linux distribution, chances are Fossil is available in the official software repositories. Alternatively, you can compile the latest version of Fossil yourself using the following commands (replace x.xx with the latest version number)

wget https://www.fossil-scm.org/download/fossil-src-x.xx.tar.gz
tar xzvf fossil-src-x.xx.tar.gz
cd fossil-src-x.xx
./configure --with-openssl=none
make

The --with-openssl=none parameter in the ./configure command omits HTTPS functionality (which you probably don't need when using Fossil on your local Linux machine). Before compiling Fossil on Ubuntu, you need to install the zlib library manually:

sudo apt-get install zlib1g-dev

Once the make process is finished, move the resulting fossil binary to the directory in your PATH (e.g., /usr/bin).

The first step after you've installed Fossil is to initialize a repository in the directory that contains files for the coding project (i.e., the source tree) that you want Fossil to manage. Switch to the directory and run the fossil init command followed by the desired repository name, for example:

fossil init foo.fossil

The created repository database contains all check-ins (snapshots of the source tree at any point in time). In other words, unlike other SCM systems that store repository data across multiple files in a dedicated directory, Fossil keeps a source tree and version control data in a single database that acts like a regular file. You can rename, copy, and move it at will.

Next, open the repository to the working directory and add the project files to the repository:

fossil open foo.fossil
fossil add .

The last command adds all files in the current directory and subdirectories recursively. If you want to exclude certain files from being tracked, you can use the fossil settings ignore-glob command:

fossil settings ignore-glob "*.tasks,*.log,.directory"

This operation will ignore files matching the specified criteria for the current repository only, but you can add the --global parameter to apply the defined rule globally:

fossil settings ignore-glob "*.md,*.log,.directory" --global

If the repository contains images, fonts, and compiled executables, you can use the fossil settings binary-glob command to configure Fossil to treat them as binary files for committing and merging:

fossil settings binary-glob "*.jpg, *.png" --global

Finally, you can create the initial commit using fossil commit:

fossil commit -m "Initial commit"

As you would expect, Fossil also allows you to clone existing repositories using the dedicated fossil clone command. In addition to local repositories, Fossil supports cloning of remote repositories via HTTP and SSH. All you have to do is to point the fossil clone command to a repository file on a remote machine and specify the desired name for the cloned repository file:

fossil clone ssh://user@remotehost/path/to/foo.fossil foo.fossil

The clever part is that, when you commit modifications in a cloned Fossil repository, the system automatically pushes changes to the remote original repository. This feature is called Auto-Sync, and it provides an easy and hands-free way of keeping the original repository and its clones in sync. (See the "From Git to Fossil" box for more information.)

git fast-export --all | fossil import --git foo.fossil

To pull recent changes from the remote repository, use the fossil pull command followed by the fossil update command.

Once you've created or cloned a repository, your typical Fossil workflow may look something like this:

• Add, edit, and delete some files in the source tree.
• Run the fossil extra command to list new files. This step is optional.
• Run fossil status to list modified files. This step is optional.
• Run fossil addremove to add the new files to the repository and remove the deleted files.
• Run the fossil commit -m "Commit message" command to commit the changes.

For a quick view of the differences between the current and previous versions of a file, run fossil diff:

fossil diff foo.php

When you need to cancel changes made to a file, use the fossil revert command

fossil revert foo.php

to go back to the previous version.

Working with the Web Interface

The built-in interface provides an easy way to configure and work with the current repository from the convenience of your preferred browser (Figure 1). Fossil has two commands for launching the web interface. The fossil ui command launches the web interface with the default user logged in. This command also binds to the loopback IP address (127.0.0.1), so it can't be used to serve content to a different machine.

Figure 1: Fossil's web interface.

The fossil server command doesn't bind to the loopback IP address, and you need to log in with credentials automatically generated when you initialized the repository using the fossil init command. By default, Fossil's web interface runs on port 8080, but you can change that using the -port parameter. Here are examples of using both commands:

fossil ui foo.fossil
fossil server foo.fossil
fossil ui foo.fossil -port 8381

When you run one of these commands, the web interface automatically opens in the default browser. Before you familiarize yourself with the interface and its functionality, it's a good idea to configure the repository's few basic settings (Figure 2). You can switch to the Admin area to access the list of configurable items. To begin, you might want to give the project a name and provide a short description, which can be done in the Configuration section. It also makes sense to change the automatically generated password for the default admin user. To do this, switch to the Users section, select the default user, specify the desired password, and press Apply Changes.

Figure 2: Configuring the repository's basic settings.

Speaking of users, Fossil comes with several default user accounts: anonymous, nobody, developer, and reader. All users, whether they are logged in or not, inherit the privileges of the nobody account. Anyone can log in to the repository as an anonymous user with the password shown on the homepage. Logged in users inherit all anonymous and nobody privileges. Knowing this can help you configure access rights for visitors, users, and contributors alike.

Fossil's web interface provides access to several modules, including Timeline, Tickets, and Wiki. Fossil's wiki engine powers practically all pages in the repository, and the Wiki section lists all existing pages and lets you easily add new ones. If you've ever tried to work with a wiki, you shouldn't have problems figuring out how to use Fossil's wiki functionality. Note that the wiki supports both native Fossil Wiki markup as well as Markdown.

In addition to regular wiki pages, Fossil lets you create so-called technotes (Figure 3). These are special wiki pages that – instead of page names – are associated with specific points in time. Each technote appears as an item on the Timeline (more about the Timeline later), and clicking on the timeline link will display the text of the technote. A technote features editable content, timeline entry text, and a timestamp. It's also possible to assign a color label and multiple tags to a technote.

Figure 3: In addition to regular wiki pages, Fossil supports technotes.

As the name suggests, the Timeline section displays repository events, such as check-ins and wiki page edits, in chronological order. Each check-in entry (Figure 4) has a hyperlinked label consisting of the first 10 digits of the check-in's hash value. Click on the label to see detailed info about changes in this check-in. The two buttons on the page – Show Unified Diffs and Show Side-by-Side Diffs – can be useful for viewing differences between the current file and its previous version. The Show Unified Diffs button displays and highlights the modification inside the file, whereas the Show Side-by-Side Diffs button displays two versions of the file with highlighted changes side by side.

Figure 4: Check-in page offers detailed info and lets you compare files side by side.

The Tickets section (Figure 5) provides tools for filing and tracking issues. Creating and submitting a ticket is rather easy, because you only have to provide a few simple bits of information in the default ticket form. Fossil also allows you to customize the default ticket form to your specific needs. For example, if you want to add a new item to the Type drop-down list, you can easily do this by navigating to Admin | Tickets | Common and inserting the desired item in the set type_choices list.

Figure 5: Customizing ticket options.

In a similar manner, you can modify the default priority, severity, resolution, and status choices and tweak the default New Ticket and Edit Ticket pages using the appropriate links in the Admin | Tickets section. The All Tickets item runs an SQL query and presents the result as a nicely formatted table of all tickets. If you have a working knowledge of SQL, you can customize the report by clicking on the edit link and modifying the default SQL query. And, you can create additional reports using the New report format link.

Fossil Hosting with Chisel

You don't need to set up a dedicated server for serving Fossil repositories via HTTP or SSH: Any machine or virtual private server accessible via the Internet will do just fine. But, if you are not keen on hosting Fossil repositories on your own server, Chisel [2] has you covered. This free service lets you to host an unlimited number of repositories and will back them up every week to keep them safe. The application that powers Chisel is open source and the service is available free of charge.