Fossil Quick Start

This is a guide to get you started using fossil quickly and painlessly.

Installing

Fossil is a single self-contained C program that you need to install before using. Build the binary and put it someplace on your PATH environment variable.

Cloning A Existing Repository

Use this command:

fossil clone URL repository-filename

The URL above is the http URL for the fossil repository you want to clone. You can call the new repository anything you want - there are no naming restrictions. As an example, you can clone the fossil repository this way:

fossil clone http://fossil-scm.hwaci.com/fossil myclone.fsl

Starting A New Project

To start a new project with fossil, create a new empty repository this way:

fossil new repository-filename

Configuring Your Local Repository

When you create a new repository, either by cloning an existing project or create a new project of your own, you usually want to do some local configuration. This is accomplished using a webbrowser. First start a fossil webserver like this:

fossil server repository-filename

This creates a mini-webserver listening on port 8080. You can specify a different port using the -port option on the command-line. After the server is running, point your webbrowser at http://localhost:8080/ and start configuring.

By default, fossil does not require a login for HTTP connections coming in from the IP loopback address 127.0.0.1. You can, and perhaps should, change this after you create a few users.

When you are finished configuring, just press Control-C or use the kill command to shut down the mini-server.

Checking Out A Local Tree

To work on a project in fossil, you need to check out a local copy of the source tree. Create the directory you want to be the root of your tree and cd into that directory. Then to this:

fossil open repository-filename

This leaves you with the original (empty) version of the tree checked out. To get to the latest version, also do this:

fossil update

From anywhere underneath the root of your local tree, you can type commands like the following to find out the status of your local tree:

fossil info
fossil status
fossil changes
fossil timeline
fossil leaves
fossil ls
fossil branches

Making Changes

To add new files to your project, or remove old files, use these commands:

fossil add file...
fossil rm file...

You can also edit files freely. Once you are ready to commit your changes, type:

fossil commit

You will be prompted for check-in comments using whatever editor is specified by your VISUAL or EDITOR environment variable. If you have GPG installed, you may be prompted for your GPG passphrase so that the check-in can be signed with your GPG signature. After this your changes will be checked in.

Sharing Changes

The changes you commit are only on your local repository. To share those changes with other repositories, do:

fossil push URL

Where URL is the http: URL of the server repository you want to share your changes with. If you omit the URL argument, fossil will use whatever server you most recently synced with.

The push command only sends your changes to others. To Receive changes from others, use pull. Or go both ways at once using sync:

fossil pull URL
fossil sync URL

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 UUID

The UUID is some unique abbreviation to the 40-character version ID. If you omit the UUID fossil moves you to the leaf version of the branch your are currently on. If your branch has multiple leaves, you get an error - you'll have to specify the leaf you want using a UUID argument.

Branching And Merging

You can create branches by doing multiple commits off of the same base version. To merge to branches back together, first update to the leaf of one branch. Then do a merge of the leaf of the other branch:

fossil merge UUID

Test to make sure your merge didn't mess up the code, then commit and possibly also push your changes. Remember that nobody else can see your changes until you commit and if other are using a different repository you will also need to push.

Setting Up A Server

The easiest way to set up a server is:

fossil server repository-filename

You can omit the repository-filename if you are within a checked-out local tree. This server uses port 8080 by default but you can specify a different port using the -port command.

Command-line servers like this are useful when two people want to share a repository on temporary or ad-hoc basis. For a more permanent installation, you should use either the CGI server or the inetd server. To use the CGI server, create a CGI script that looks something like this:

#!/usr/local/bin/fossil
repository: /home/proj1/repos1.fsl

Adjust the paths in this CGI script to match your installation. Now point clients at the CGI script. That's all there is to it!

You can also run fossil off of inetd or xinetd. For an inetd installation, make an entry in /etc/inetd.conf that looks something like this:

80 stream tcp nowait.1000 root /usr/bin/fossil \
/usr/bin/fossil http /home/proj1/repos1.fsl

Adjust the paths to suit your installation, of course. Notice that fossil runs as root. This is not required - you can run it as an unprivileged user. But it is more secure to run fossil as root. When you do run fossil as root, it automatically puts itself in a chroot jail in the same directory as the repository, then drops root privileges prior to reading any information from the request.

More Hints

Try these commands:

fossil command
fossil test-command

Explore and have fun!