Using Fossil — Version Control System

How Fossil can be used

João Duarte Pinto
6 min readMay 5, 2021

Remote Repository Set-up

A Raspberry Pi was used to host the remote repository, being accessed through the local network.

The operating system running on the Raspberry Pi is Ubuntu Server 20.04 LTS, previously configured to access the local network and with openssh-server installed so that it can be accessed by another machine.

ssh into server

To access the server, the personal computer must be in same network as the server.

My personal computer is a Macbook, so, just need to open the terminal without having to install third-party software and ssh into server:

$ ssh <user>@<ip_address_of_server>

On the ubuntu server, to know the IP address just enter the following command:

$ hostname -i

Fossil installation

After logging into the server, it is necessary to install Fossil. The chosen way of installation was through the following command:

$ sudo apt install fossil

To confirm that the installation was successful we can see the version of the fossil that is being used.

$ fossil versionThis is fossil version 2.12.1

Creating new project

A new folder was created in the user’s home directory with the name “fossil-vs-git”, to house the repository. The current directory was moved to this new folder to start the repository.

$ mkdir fossil-vs-git
$ cd fossil-vs-git/

So let’s start the Fossil repository!

$ fossil init <repository_name>

The name of the repository used was: fossil-vs-git.fossil.

So command used was:

$ fossil init fossil-vs-git.fossil

The repository can have any name, but the extension .fossil is used traditionally. As we are going to use this repository as a remote server, the .fossil extension is mandatory.

After the comand, project-id, server-id, admin user and initial password will be displayed.

Then, we must checkout a Local Tree:

$ fossil open <repository_name>

If the directory isn’t empty, force flag must be used:

$ fossil open <repository_name> --force

Keep in mind in what’s displayed in terminal, we will need the repository path.

To serve this repository, we need to make some configuration on the UI, to init the web server:

$ fossil serve <repository_path>Listening for HTTP requests on TCP port 8080

Then, on web browser we go to server ip address plus port, in this case 8080, like:

  • <ip_address>:8080

Log with credentials showed before and set Project Name to: Fossil-vs-Git, then hit Apply Changes.

As Fossil uses a cathedral-style development method, we have to create a user for each employee. We will create a user so that we can later clone the repository to the personal computer.

Go to the “Admin” tab, select “Users”, then hit “Add”. We must then fill in the requested fields and, for this purpose, make the new user Admin.

To finish what we need to do on the server, we go back to the terminal and put the job to run in the background:

Press: ctrl + z to stop and then make it run on background.

$ bg

To avoid doing this step, when starting the server, you can add the “&” at the end to put it running in the background.

$ fossil serve <repository_path> &

Now, it’s time to work on the personal computer!

Install Fossil and clone repository to local machine

Fossil Installation

The Homebrew package manager was used to install Fossil on the MacOs operating system.

$ brew install fossil

A folder was created to house the project on the local machine. The repository was then cloned into that folder.

The HTTP protocol was used to access the remote repository, using the following command:

$ fossil clone http://<username>@<ip_address>:<port> <repository-filename>

In this case:

$ fossil clone http://<username>@<ip_address>:8080 fossil-vs-git.fossil

Enter the password setted before, and the clone will succeed.

Now, we have to put a copy of the initial project inside the repository folder to do the implementation using Fossil.

Push the base project into remote

Open local tree:

$ fossil open fossil-vs-git.fossil -f

Now, add all files to be commited:

$ fossil add .

Reset added files

$ fossil add --reset

Ignoring files — ignore-glob

At the root of the project a directory with name: .fossil-settings

$ mkdir .fossil-settings
$ cd .fossil-settings

Inside the new folder create a file named ignore-glob, and per line put the glob that we want to ignore:

$ nano ignore-glob

Insert the globs like:

*/target/*

Now, ignored files will not be added

Commiting

To commit type the following comand to commit:

$ fossil commit

Default text editor will open to introduce commit message.

Here we can see demonstrated one of Fossil’s capabilities, as autosync by default is active, when a commit is made, the remote repository is automatically pulled (to download possible changes in remote), also automatically pushes to the remote with the contents of the commit.

Autosync, pull, push, sync and update

Autosync can be turned off:

$ fossil settings autosync off

If so, to put the changes in the remote repository, it is necessary to pull and push:

$ fossil pull <URL>
$ fossil push <URL>

OR: both at same time with:

$ fossil sync <URL>

If you omit the URL argument, fossil will use whatever server you most recently synced with.

When you pull in changes from others, they go into your repository, not into your checked-out local tree. To get the changes into your local tree, use update:

$ fossil update <branch_name_OR_tag_OR_abbreviation_of_check-in>

Fossil pull automatically when you run update and a push automatically after you commit.

Offline mode

When trying to make a commit without an internet connection/server, Fossil will notice that there is no connection and ask if you want to continue. If you decide to continue the changes will be saved locally. Later, when the connection is restored, just run the following command to synchronize with the server:

$ fossil sync

Offline support exists too for the web interface, using the fossil server command on the personal computer lets open and edit what is needed (like adding tickets), even offline, and then later sync with remote.

Tickets

Fossil allows you to use the ticketing system, provided by the Web Interface. There is no need to use third-party applications.

Go to Tickets section and add tickets.

Tags

You can tag in various ways, for example through the commit, with the — tag flag, and each check-in can have several tags, just by repeating the flag:

$ fossil commit --tag <tag_name>

You can also add tags to existing check-ins:

$ fossil tag add <tag_name> <check-in>

Creating a new branch

In fossil we can create branches by:

$ fossil branch new <branch_name> <check-in_that_the_branch_splits_off_from>

Current branch is preceded by *

To change between branches:

$ fossil update <branch_name>

Merging branches

To merge two branches we must switch to the branch we want to merge into:

$ fossil update <branch_name>

Then, merge:

$ fossil merge <branch_to_be_incorporated>

And finally, commit the merge:

$ fossil commit

Access to repository

You can find a copy of the repository here!

If you have fossil on your local machine, just copy the repository, and, inside the directory that have the copy use this command:

$ fossil open <repository_name>

In this case:

$ fossil open devops.fossil

Final thoughts

As has been shown, Fossil is a distributed version control system capable of being a competitor against Git, and offering a lot of features that Git alone does not.

Of the large drawbacks found, the lack of use on the part of the developer community means that not much information is found, although the information found is of quality. The number of services capable of hosting a Fossil repository is also small, only http://chiselapp.com and http://fossilrepos.sourceforge.net have this capability.

--

--