Fossil Quick Start

This is a guide to help you get started using the Fossil Distributed Version Control System quickly and painlessly.

Installing

Fossil is a single self-contained C program. You need to either download a precompiled binary or compile it yourself from sources. Install Fossil by putting the fossil binary someplace on your $PATH.

You can test that Fossil is present and working like this:

fossil version
This is fossil version 2.13 [309af345ab] 2020-09-28 04:02:55 UTC

General Work Flow

Fossil works with repository files (a database in a single file with the project's complete history) and with checked-out local trees (the working directory you use to do your work). (See definitions for more background.) The workflow looks like this:

Create or clone a repository file. (fossil init or fossil clone)
Check out a local tree. (fossil open)
Perform operations on the repository (including repository configuration).

Fossil can be entirely driven from the command line. Many features can also be conveniently accessed from the built-in web user interface.

The following sections give a brief overview of these operations.

Starting A New Project

To start a new project with fossil create a new empty repository this way: (more info)

fossil init repository-filename

You can name the database anything you like, and you can place it anywhere in the filesystem. The .fossil extension is traditional but only required if you are going to use the fossil server DIRECTORY feature.”

Cloning An Existing Repository

Most fossil operations interact with a repository that is on the local disk drive, not on a remote system. Hence, before accessing a remote repository it is necessary to make a local copy of that repository. Making a local copy of a remote repository is called "cloning".

Clone a remote repository as follows: (more info)

fossil clone URL repository-filename

The URL specifies the fossil repository you want to clone. The repository-filename is the new local filename into which the cloned repository will be written. For example, to clone the source code of Fossil itself:

fossil clone https://fossil-scm.org/ myclone.fossil

If your logged-in username is 'exampleuser', you should see output something like this:

Round-trips: 8 Artifacts sent: 0 received: 39421 Clone done, sent: 2424 received: 42965725 ip: 10.10.10.0 Rebuilding repository meta-data... 100% complete... Extra delta compression... Vacuuming the database... project-id: 94259BB9F186226D80E49D1FA2DB29F935CCA0333 server-id: 016595e9043054038a9ea9bc526d7f33f7ac0e42 admin-user: exampleuser (password is "yoWgDR42iv")>

If the remote repository requires a login, include a userid in the URL like this:

fossil clone https://remoteuserid@www.example.org/ myclone.fossil

You will be prompted separately for the password. Use "%HH" escapes for special characters in the userid. For example "/" would be replaced by "%2F" meaning that a userid of "Projects/Budget" would become "Projects%2FBudget")

If you are behind a restrictive firewall, you might need to specify an HTTP proxy.

A Fossil repository is a single disk file. Instead of cloning, you can just make a copy of the repository file (for example, using "scp"). Note, however, that the repository file contains auxiliary information above and beyond the versioned files, including some sensitive information such as password hashes and email addresses. If you want to share Fossil repositories directly by copying, consider running the fossil scrub command to remove sensitive information before transmitting the file.

Importing From Another Version Control System

Rather than start a new project, or clone an existing Fossil project, you might prefer to import an existing Git project into Fossil using the fossil import command.

You can even decide to export your project back into git using the fossil git command, which is how the Fossil project maintains its public GitHub mirror. There is no limit to the number of times a tree can be imported and exported between Fossil and git.

The Git fast-export format has become a popular way to move files between version management systems, including from Mercurial. Fossil can also import Subversion projects directly.

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 do this: (more info)

fossil open repository-filename

for example:

fossil open ../myclone.fossil BUILD.txt COPYRIGHT-BSD2.txt README.md ︙

(or "fossil open ..\myclone.fossil" on Windows).

This leaves you with the newest version of the tree checked out. 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 diff
fossil timeline
fossil ls
fossil branch

If you created a new repository using "fossil init" some commands will not produce much output.

Note that Fossil allows you to make multiple check-outs in separate directories from the same repository. This enables you, for example, to do builds from multiple branches or versions at the same time without having to generate extra clones.

To switch a checkout between different versions and branches, use:

fossil update
fossil checkout

update honors the "autosync" option and does a "soft" switch, merging any local changes into the target version, whereas checkout does not automatically sync and does a "hard" switch, overwriting local changes if told to do so.

Making and Committing Changes

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

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

The command:

fossil changes

lists files that have changed since the last commit to the repository. For example, if you edit the file "README.md":

fossil changes
EDITED README.md

To see exactly what change was made you can use the command

fossil diff:

fossil diff
Index: README.md ============================================================ --- README.md +++ README.md @@ -1,5 +1,6 @@ +Made some changes to the project # Original text

"fossil diff" is the difference between your tree on disk now and as the tree was when you did "fossil open". An open is the first checkout from a repository into a new directory.

To see the most recent changes made to the repository by other users, use "fossil timeline" to find out the most recent commit, and then "fossil diff" between that commit and the current tree:

fossil timeline
=== 2021-03-28 === 03:18:54 [ad75dfa4a0] *CURRENT* Added details to frobnicate command (user: user-one tags: trunk) === 2021-03-27 === 23:58:05 [ab975c6632] Update README.md. (user: user-two tags: trunk) ⋮
fossil diff --from current --to ab975c6632
Index: frobnicate.c ============================================================ --- frobnicate.c +++ frobnicate.c @@ -1,10 +1,11 @@ +/* made a change to the source file */ # Original text

"current" is an alias for the checkout version, so the command "fossil diff --from ad75dfa4a0 --to ab975c6632" gives identical results.

To commit your changes to a local-only repository:

fossil commit (... Fossil will start your editor, if defined)
# Enter a commit message for this check-in. Lines beginning with # are ignored. # # user: exampleuser # tags: trunk # # EDITED README.md Edited file to add description of code changes New_Version: 7b9a416ced4a69a60589dde1aedd1a30fde8eec3528d265dbeed5135530440ab

You will be prompted for check-in comments using whatever editor is specified by your VISUAL or EDITOR environment variable. If none is specified Fossil uses line-editing in the terminal.

To commit your changes to a repository that was cloned from remote you perform the same actions but the results are different. Fossil defaults to 'autosync' mode, a single-stage commit that sends all changes committed to the local repository immediately on to the remote parent repository. This only works if you have write permission to the remote respository.

Naming of Files, Checkins, and Branches

Fossil deals with information artifacts. This Quickstart document only deals with files and collections of files, but be aware there are also tickets, wiki pages and more. Every artifact in Fossil has a universally-unique hash id, and may also have a human-readable name.

The following are all equivalent ways of identifying a Fossil file, checkin or branch artifact:

the full unique SHA-256 hash, such as be836de35a821523beac2e53168e135d5ebd725d7af421e5f736a28e8034673a
an abbreviated hash prefix, such as the first ten characters: be836de35a . This won't be universally unique, but it is usually unique within any one repository. As an example, the Fossil project hash collisions showed at the time of writing that there are no artifacts with identical first 8 characters
a branch name, such as "special-features" or "juliet-testing". Each branch also has a unique SHA-256 hash

A special convenience branch is "trunk", which is Fossil's default branch name for the first checkin, and the default for any time a branch name is needed but not specified.

This will get you started on identifying checkins. The Checkin Names document is a complete reference, including how timestamps can also be used.

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 easily accomplished using the web-server that is built into fossil. Start the fossil web server like this: (more info)

fossil ui repository-filename

You can omit the repository-filename from the command above if you are inside a checked-out local tree.

This starts a web server then automatically launches your web browser and makes it point to this web server. If your system has an unusual configuration, fossil might not be able to figure out how to start your web browser. In that case, first tell fossil where to find your web browser using a command like this:

fossil setting web-browser path-to-web-browser

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.

Making Changes

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

fossil add file...
fossil rm file...
fossil addremove 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.

In the default configuration, the commit command will also automatically push your changes, but that feature can be disabled. (More information about autosync and how to disable it.) Remember that your coworkers can not see your changes until you commit and push them.

When autosync is turned off, 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 VERSION

The VERSION can be the name of a branch or tag or any abbreviation to the 40-character artifact identifier for a particular check-in, or it can be a date/time stamp. (more info) If you omit the VERSION, then fossil moves you to the latest version of the branch your are currently on.

The default behavior is for autosync to be turned on. That means that a pull automatically occurs when you run update and a push happens automatically after you commit. So in normal practice, the push, pull, and sync commands are rarely used. But it is important to know about them, all the same.

fossil checkout VERSION

Is similar to update except that it does not honor the autosync setting, nor does it merge in local changes - it prefers to overwrite them and fails if local changes exist unless the --force flag is used.

Branching And Merging

Use the --branch option to the commit command to start a new branch. Note that in Fossil, branches are normally created when you commit, not before you start editing. You can use the branch new command to create a new branch before you start editing, if you want, but most people just wait until they are ready to commit.

To merge two branches back together, first update to the branch you want to merge into. Then do a merge of the other branch that you want to incorporate the changes from. For example, to merge "featureX" changes into "trunk" do this:

fossil update trunk
fossil merge featureX
# make sure the merge didn't break anything...
fossil commit

The argument to the merge command can be any of the version identifier forms that work for update. (more info.) The merge command has options to cherry-pick individual changes, or to back out individual changes, if you don't want to do a full merge.

The merge command puts all changes in your working check-out. No changes are made to the repository. You must run commit separately to add the merge changes into your repository to make them persistent and so that your coworkers can see them. But before you do that, you will normally want to run a few tests to verify that the merge didn't cause logic breaks in your code.

The same branch can be merged multiple times without trouble. Fossil automatically keeps up with things and avoids conflicts when doing multiple merges. So even if you have merged the featureX branch into trunk previously, you can do so again and Fossil will automatically know to pull in only those changes that have occurred since the previous merge.

If a merge or update doesn't work out (perhaps something breaks or there are many merge conflicts) then you back up using:

fossil undo

This will back out the changes that the merge or update made to the working checkout. There is also a redo command if you undo by mistake. Undo and redo only work for changes that have not yet been checked in using commit and there is only a single level of undo/redo.

Setting Up A Server

Fossil can act as a stand-alone web server using one of these commands:

fossil server repository-filename
fossil ui repository-filename

The repository-filename can be omitted when these commands are run from within an open check-out, which is a particularly useful shortcut with the fossil ui command.

The ui command is intended for accessing the web user interface from a local desktop. (We sometimes call this mode "Fossil UI.") The ui command differs from the server command by binding to the loopback IP address only (thus making the web UI visible only on the local machine) and by automatically starting your default web browser, pointing it at the running UI server. The localhost restriction exists because it also gives anyone who can access the resulting web UI full control over the repository. (This is the all-powerful Setup capabliity.)

For cross-machine collaboration, use the server command instead, which binds on all IP addresses, does not try to start a web browser, and enforces Fossil's role-based access control system.

Servers are also easily configured as:

…along with several other options.

The self-hosting fossil repositories use CGI.

You might need to set up a server, whether you know it yet or not. See the Benefits of a Fossil Server article for details.

HTTP Proxies

If you are behind a restrictive firewall that requires you to use an HTTP proxy to reach the internet, then you can configure the proxy in three different ways. You can tell fossil about your proxy using a command-line option on commands that use the network, sync, clone, push, and pull.

fossil clone URL --proxy Proxy-URL

It is annoying to have to type in the proxy URL every time you sync your project, though, so you can make the proxy configuration persistent using the setting command:

fossil setting proxy Proxy-URL

Or, you can set the "http_proxy" environment variable:

export http_proxy=Proxy-URL

To stop using the proxy, do:

fossil setting proxy off

Or unset the environment variable. The fossil setting for the HTTP proxy takes precedence over the environment variable and the command-line option overrides both. If you have a persistent proxy setting that you want to override for a one-time sync, that is easily done on the command-line. For example, to sync with a co-worker's repository on your LAN, you might type:

fossil sync http://192.168.1.36:8080/ --proxy off

Fossil