This is a guide to get you started using fossil quickly and painlessly.
Fossil is a single self-contained C program. You need to either download a precompiled binary or build it yourself from sources. Install fossil by putting the fossil binary someplace on your $PATH.
Fossil works with repository files (a database with the project's complete history) and with checked-out local trees (the working directory you use to do your work). The workflow looks like this:
The following sections will give you a brief overview of these operations.
To start a new project with fossil, create a new empty repository this way: ([/help/init | more info])
fossil init repository-filename
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: ([/help/clone | more info])
fossil clone URL repository-filename
The URL above is the http URL for the fossil repository you want to clone, and it may include a "user:password" part, e.g. http://drh:secret@www.fossil-scm.org/fossil. 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://www.fossil-scm.org/ myclone.fossil
The new local copy of the repository is stored in a single file, which in the example above is named "myclone.fossil". You can name your repositories anything you want. The ".fossil" suffix is not required.
Note: If you are behind a restrictive firewall, you might need to specify an HTTP proxy to use.
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 passwords and email addresses. If you want to share Fossil repositories directly, consider running the [/help/scrub|fossil scrub] command to remove sensitive information before transmitting the file.
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 [/help/import | fossil import] command.
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: ([/help/open | more info])
fossil open repository-filename
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:
[/help/info | fossil info]
[/help/status | fossil status]
[/help/changes | fossil changes]
[/help/diff | fossil diff]
[/help/timeline | fossil timeline]
[/help/ls | fossil ls]
[/help/branch | fossil branch]
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 webserver like this: ([/help/ui | 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.
To add new files to your project, or remove old files, use these commands:
[/help/add | fossil add] file...
[/help/rm | fossil rm] file...
[/help/addremove | fossil addremove] file...
You can also edit files freely. Once you are ready to commit your changes, type:
[/help/commit | fossil commit]
You will be prompted for check-in comments using whatever editor is specified by your VISUAL or EDITOR environment variable.
The changes you [/help/commit | commit] are only on your local repository. To share those changes with other repositories, do:
[/help/push | 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 [/help/push | push] command only sends your changes to others. To Receive changes from others, use [/help/pull | pull]. Or go both ways at once using [/help/sync | sync]:
[/help/pull | fossil pull] URL
[/help/sync | 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 [/help/update | update]:
[/help/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. ([./checkin_names.wiki | more info]) If you omit the VERSION, then fossil moves you to the latest version of the branch your are currently on.
You can create branches by doing multiple commits off of the same base version. To merge two branches back together, first [/help/update | update] to the leaf of one branch. Then do a [/help/merge | merge] of the leaf of the other branch:
[/help/merge | fossil merge] VERSION
The VERSION can be any of the forms allowed for [/help/update | update]. After performing the merge, you will normally want to test it to make sure it does not break anything, then [/help/commit | commit] your changes. In the default configuration, the [/help/commit|commit] command will also automatically [/help/push|push] your changes, but that feature can be disabled. (More information about [./concepts.wiki#workflow|autosync] and how to disable it.) Remember that your coworkers can not see your changes until you commit and push them.
The merge command has options to cherrypick individual changes, or to back out individual changes.
If a merge or update doesn't work out (perhaps something breaks or there are many merge conflicts) then you back up using:
[/help/undo | fossil undo]
This will back out the changes that the merge or update made to the working checkout. There is also a [/help/redo|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.
The easiest way to set up a server is:
[/help/server | fossil server] repository-filename
Or
[/help/ui | fossil ui] repository-filename
The ui command is intended for accessing the web interface from a local desktop. The ui command binds to the loopback IP address only (and is thus makes the web interface visible only on the local machine) and it automatically start your web browser pointing at the server. For cross-machine collaboration, use the server command, which binds on all IP addresses and does not try to start a web browser. You can omit the repository-filename if you are within a checked-out local tree. The server uses port 8080 by default but you can specify a different port using the -port option.
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.fossil
Adjust the paths in this CGI script to match your installation and make sure both repository file and the directory that contains it are readable and writable by the user that CGI scripts run as. Then point clients at the CGI script. That's all there is to it!
You can also run fossil from 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.fossil
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.
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 [/help/setting | 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 an 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-workers repository on your LAN, you might type:
fossil sync http://192.168.1.36:8080/ --proxy off
A [/help | complete list of commands] is available.
Explore and have fun!