<title>Fossil Quick Start Guide</title>
<h1 align="center">Fossil Quick Start</h1>
<p>This is a guide to get you started using fossil quickly
and painlessly.</p>
<h2>Installing</h2>
<p>Fossil is a single self-contained C program. You need to
either download a
<a href="http://www.fossil-scm.org/download.html">precompiled binary</a>
or <a href="build.wiki">compile it yourself</a> from sources.
Install fossil by putting the fossil binary
someplace on your $PATH.</p>
<a name="fslclone"></a>
<h2>General Work Flow</h2>
<p>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:</p>
<ul>
<li>Create or clone a repository file. ([/help/init|fossil init] or
[/help/clone | fossil clone])
<li>Check out a local tree. ([/help/open | fossil open])
<li>Perform operations on the repository (including repository
configuration).
</ul>
<p>The following sections will give you a brief overview of these
operations.</p>
<h2>Starting A New Project</h2>
<p>To start a new project with fossil, create a new empty repository
this way: ([/help/init | more info]) </p>
<blockquote>
<b>fossil init </b><i> repository-filename</i>
</blockquote>
<h2>Cloning An Existing Repository</h2>
<p>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".</p>
<p>Clone a remote repository as follows: ([/help/clone | more info])</p>
<blockquote>
<b>fossil clone</b> <i>URL repository-filename</i>
</blockquote>
<p>The <i>URL</i> above is the http URL for the fossil repository
you want to clone, and it may include a "user:password" part, e.g.
<tt>http://user:password@www.fossil-scm.org/fossil</tt>. 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:</p>
<blockquote>
<b>fossil clone http://www.fossil-scm.org/ myclone.fossil</b>
</blockquote>
<p>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.</p>
<p>Note: If you are behind a restrictive firewall, you might need
to <a href="#proxy">specify an HTTP proxy</a>.</p>
<p>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, consider running the
[/help/scrub|fossil scrub] command to remove sensitive information
before transmitting the file.
<h2>Importing From Another Version Control System</h2>
<p>Rather than start a new project, or clone an existing Fossil project,
you might prefer to
<a href="./inout.wiki">import an existing Git project</a>
into Fossil using the [/help/import | fossil import] command.
<h2>Checking Out A Local Tree</h2>
<p>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])</p>
<blockquote>
<b>fossil open </b><i> repository-filename</i>
</blockquote>
<p>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:</p>
<blockquote>
<b>[/help/info | fossil info]</b><br>
<b>[/help/status | fossil status]</b><br>
<b>[/help/changes | fossil changes]</b><br>
<b>[/help/diff | fossil diff]</b><br>
<b>[/help/timeline | fossil timeline]</b><br>
<b>[/help/ls | fossil ls]</b><br>
<b>[/help/branch | fossil branch]</b><br>
</blockquote>
<p>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.</p>
<p>To switch a checkout between different versions and branches,
use:</p>
<blockquote>
<b>[/help/update | fossil update]</b><br>
<b>[/help/checkout | fossil checkout]</b><br>
</blockquote>
<p>[/help/update | update] honors the "autosync" option and
does a "soft" switch, merging any local changes into the target
version, whereas [/help/checkout | checkout] does not
automatically sync and does a "hard" switch, overwriting local
changes if told to do so.</p>
<h2>Configuring Your Local Repository</h2>
<p>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])</p>
<blockquote>
<b>fossil ui </b><i> repository-filename</i>
</blockquote>
<p>You can omit the <i>repository-filename</i> from the command above
if you are inside a checked-out local tree.</p>
<p>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:</p>
<blockquote>
<b>fossil setting web-browser </b><i> path-to-web-browser</i>
</blockquote>
<p>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.</p>
<p>When you are finished configuring, just press Control-C or use
the <b>kill</b> command to shut down the mini-server.</p>
<h2>Making Changes</h2>
<p>To add new files to your project, or remove old files, use these
commands:</p>
<blockquote>
<b>[/help/add | fossil add]</b> <i>file...</i><br>
<b>[/help/rm | fossil rm]</b> <i>file...</i><br>
<b>[/help/addremove | fossil addremove]</b> <i>file...</i><br>
</blockquote>
<p>You can also edit files freely. Once you are ready to commit
your changes, type:</p>
<blockquote>
<b>[/help/commit | fossil commit]</b>
</blockquote>
<p>You will be prompted for check-in comments using whatever editor
is specified by your VISUAL or EDITOR environment variable.</p>
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.</p>
<h2>Sharing Changes</h2>
<p>When [./concepts.wiki#workflow|autosync] is turned off,
the changes you [/help/commit | commit] are only
on your local repository.
To share those changes with other repositories, do:</p>
<blockquote>
<b>[/help/push | fossil push]</b> <i>URL</i>
</blockquote>
<p>Where <i>URL</i> is the http: URL of the server repository you
want to share your changes with. If you omit the <i>URL</i> argument,
fossil will use whatever server you most recently synced with.</p>
<p>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]:</p>
<blockquote>
<b>[/help/pull | fossil pull]</b> <i>URL</i><br>
<b>[/help/sync | fossil sync]</b> <i>URL</i>
</blockquote>
<p>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]:</p>
<blockquote>
<b>[/help/update | fossil update]</b> <i>VERSION</i>
</blockquote>
<p>The <i>VERSION</i> 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 <i>VERSION</i>, then fossil moves you to the
latest version of the branch your are currently on.</p>
<p>The default behavior is for [./concepts.wiki#workflow|autosync] to
be turned on. That means that a [/help/pull|pull] automatically occurs
when you run [/help/update|update] and a [/help/push|push] happens
automatically after you [/help/commit|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.</p>
<blockquote>
<b>[/help/checkout | fossil checkout]</b> <i>VERSION</i>
</blockquote>
<p>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 <tt>--force</tt>
flag is used.</p>
<h2>Branching And Merging</h2>
<p>Use the --branch option to the [/help/commit | 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 [/help/branch | 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
[/help/update | update] to the branch you want to merge into.
Then do a [/help/merge|merge] another branch that you want to incorporate
the changes from. For example, to merge "featureX" changes into "trunk"
do this:</p>
<blockquote>
<b>fossil [/help/update|update] trunk</b><br>
<b>fossil [/help/merge|merge] featureX</b><br>
<i># make sure the merge didn't break anything...</i><br>
<b>fossil [/help/commit|commit]
</blockquote>
<p>The argument to the [/help/merge|merge] command can be any of the
version identifier forms that work for [/help/update|update].
([./checkin_names.wiki|more info].)
The merge command has options to cherrypick individual
changes, or to back out individual changes, if you don't want to
do a full merge.</p>
The merge command puts all changes in your working check-out.
No changes are made to the repository.
You must run [/help/commit|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.
<p>If a merge or update doesn't work out (perhaps something breaks or
there are many merge conflicts) then you back up using:</p>
<blockquote>
<b>[/help/undo | fossil undo]</b>
</blockquote>
<p>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.</p>
<h2>Setting Up A Server</h2>
<p>Fossil can act as a stand-alone web server using one of these
commands:</p>
<blockquote>
<b>[/help/server | fossil server]</b> <i>repository-filename</i><br>
<b>[/help/ui | fossil ui]</b> <i>repository-filename</i>
</blockquote>
<p>The <i>repository-filename</i> can be omitted when these commands
are run from within an open check-out, which a particularly useful
shortcut for the <b>fossil ui</b> command.
<p>The <b>ui</b> command is intended for accessing the web interface
from a local desktop. The <b>ui</b> command binds to the loopback IP
address only (and 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 <b>server</b> command,
which binds on all IP addresses and does not try to start a web browser.</p>
<p>Servers are also easily configured as:
<ul>
<li>[./server.wiki#inetd|inetd/xinetd]
<li>[./server.wiki#cgi|CGI]
<li>[./server.wiki#scgi|SCGI]
</ul>
<p>The [./selfhost.wiki | self-hosting fossil repositories] use
CGI.
<a name="proxy"></a>
<h2>HTTP Proxies</h2>
<p>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,
<b>sync</b>, <b>clone</b>, <b>push</b>, and <b>pull</b>.</p>
<blockquote>
<b>fossil clone </b><i>URL</i> <b>--proxy</b> <i>Proxy-URL</i>
</blockquote>
<p>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:</p>
<blockquote>
<b>fossil setting proxy </b><i>Proxy-URL</i>
</blockquote>
<p>Or, you can set the "<b>http_proxy</b>" environment variable:</p>
<blockquote>
<b>export http_proxy=</b><i>Proxy-URL</i>
</blockquote>
<p>To stop using the proxy, do:</p>
<blockquote>
<b>fossil setting proxy off</b>
</blockquote>
<p>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:</p>
<blockquote>
<b>fossil sync http://192.168.1.36:8080/ --proxy off</b>
</blockquote>
<h2>More Hints</h2>
<p>A [/help | complete list of commands] is available, as is the
[./hints.wiki|helpful hints] document. See the
[./permutedindex.html#pindex|permuted index] for additional
documentation.
<p>Explore and have fun!</p>