Keeping track of changes in code is vital, as any programmer is well aware. There are many reasons for this. Sometimes you just want a history of how your project started, and how it's evolved, as a matter of curiousity or education. Other times, you want to enable other coders to contribute to your project and need a reliable way to merge disparate parts. And still other times, an adjustment you make to fix one problem ends up breaking something else that was formerly working. The Fossil source code management system is an all-in-one version control system, bug tracker, wiki, forum, and documentation solution from the creator of the famous SQLite database.

Install Fossil {#_install_fossil}

Fossil is a single self-contained C program, so you it's very likely that you can just

download Fossil

from its homepage and place it anywhere in your system

PATH

. For example, assuming `/usr/local/bin` is in your path, as it usually is by default:

----[source,bash] $ wget

https://fossil-scm.org/home/uv/fossil-linux-x64-X.Y.tar.gz

$ sudo tar xvf fossil-linux-x64-X.Y.tar.gz \ --directory /usr/local/bin

As you can see, the creation of a Fossil repo returns three items: a unique project ID, a unique server ID, and an admin ID and password. The project and server IDs are version numbers, and the admin credentials establishes your ownership of this repository, and can be used later should you decide to run Fossil as a server for other users to access.

Work in a Fossil repository {#_work_in_a_fossil_repository}

You To start work in a Fossil repo, you must create a working location for its data. You might think of this process as creating a virtual environment in Python, or unzipping a ZIP file that you intend to zip back up again later.

Create a working directory:

----[source,bash] $ mkdir myprojectdir $ cd myprojectdir

You might notice that Fossil has created a hidden file called `.fossil` in your home directory to track your global Fossil preferences. This is not specific to your project, it's just an artifact of this being the first time you've used Fossil.

Adding files {#_adding_files}

To add files to your repository, use the `add` and `commit` subcommands. For the sake of this example, create a simple README file and add it to the repository:

----[source,bash] $ echo "My first Fossil project" > README $ fossil add README ADDED README $ fossil commit -m 'My first commit' New_Version: 2472a43acd11c93d08314e852dedfc6a476403695e44f47061607e4e90ad01aa

You've create a new branch, but your current branch is still `trunk`:

----[source,bash] $ fossil branch current trunk

Merging changes {#_merging_changes}

Suppose you've added an exciting new file to your `dev` branch, and having tested it you're satisfied that it's ready to take its place in trunk. This is called a *merge*.

First, change your branch back to your target branch (in this example, that's `trunk`). Your new file doesn't exist here, or if you modified a file that already existed then the changes to it don't exist here, but that's what the merge is going to take care of.

----[source,bash] $ fossil checkout trunk trunk $ ls README

View the Fossil timeline {#_view_the_fossil_timeline}

To see the history of your repository, use the `timeline` option. This shows you a detailed list of all activity in your repository, including a hash representing the change, the commit message you provided when committing code, and who made the change.

----[source,bash] $ fossil timeline === 2020-11-09 === 06:24:16 [5ef06e668b] added exciting new file (user: klaatu tags: dev) 06:11:19 [cb90e9c6f2] Create new branch named "dev" (user: klaatu tags: dev) 06:08:09 [a2bb73e4a3] **CURRENT** some additions were made (user: klaatu tags: trunk) 06:00:47 [2472a43acd] This is my first commit. (user: klaatu tags: trunk) 04:09:35 [9e6cd96dd6] initial empty check-in (user: klaatu tags: trunk) no more data (5)

image:fossil-ui.jpg

Specifically, you should look at **Users** and **Settings** for security, and **Configuration** for project properties (including a proper title). The web interface isn't just a convenience function. It's intended for actual use, and indeed *is* in use as the host for the Fossil project. There are several surprisingly advance options, from user management (or self management, if you please) to single-signon (SSO) with other Fossil repositories on the same server.

Once you're satisfied with your changes, close the web interface and press **Ctrl+C** to stop the UI engine from running. Commit your web changes just as you would any other update:

----[source,bash] $ fossil commit -m 'web ui updates' New_Version: 11fe7f2855a3246c303df00ec725d0fca526fa0b83fa67c95db92283e8273c60

Make the script executable:

----[source,bash] $ chmod +x repo_myproject.cgi

Working with a local clone requires you to use the `push` subcommand to send local changes back to your remote repository, and the `pull` subcommand to get changes made remotely into your local copy.

----[source,bash] $ fossil push

https://klaatu@example.com/cgi-bin/repo_myproject.cgi

Proxied content from gemini://sdf.org/klaatu/geminifiles/fossil.gmi (external content)

Gemini request details:

Original URL
gemini://sdf.org/klaatu/geminifiles/fossil.gmi
Status code
Success
Meta
text/gemini
Proxied by
kineto

Be advised that no attempt was made to verify the remote SSL certificate.