<title>Fossil Quick Start Guide</title>
<nowiki>
<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><blockquote>

    <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">build it yourself</a> from sources.
    Install fossil by putting the fossil binary
    someplace on your PATH environment variable.</p>
    
</blockquote>
<a name="fslclone"></a>

<h2>General Work Flow</h2><blockquote>

    <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.  In most operations that require you to work on a
    specific repository you must have a checked out tree in place to work  from.
    The resulting workflow looks like this:</p>

    <ul>
        <li>Create or clone a repository file.  (<b>fossil new</b> or
            <b>fossil clone</b>)
        <li>Check out a local tree.  (<b>fossil open</b>)
        <li>Perform operations on the repository (including repository
            configuration).
        <li><em>Optionally</em> close the local tree.  (<b>fossil
            close</b>, but this is rarely used.)
    </ul>

    <p>The following sections will give you a brief overview of these
    operations.</p>

</blockquote>

<h2>Starting A New Project</h2><blockquote>

    <p>To start a new project with fossil, create a new empty repository
    this way:</p>
    
    <blockquote>
    <b>fossil new </b><i> repository-filename</i>
    </blockquote>

</blockquote>
    
<h2>Cloning An Existing Repository</h2><blockquote>

    <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:</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://drh:secret@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> to use.</p>
    
</blockquote><h2>Importing From Another Version Control System</h2><blockquote>

    <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.

</blockquote><h2>Checking Out A Local Tree</h2><blockquote>

    <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:</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>fossil info</b><br>
    <b>fossil status</b><br>
    <b>fossil changes</b><br>
    <b>fossil diff</b><br>
    <b>fossil timeline</b><br>
    <b>fossil ls</b><br>
    <b>fossil branch list</b><br>
    </blockquote>

</blockquote><h2>Configuring Your Local Repository</h2><blockquote>
    
    <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 webserver
    that is built into fossil.  Start the fossil webserver like this:</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>

</blockquote><h2>Making Changes</h2><blockquote>

    <p>To add new files to your project, or remove old files, use these
    commands:</p>

    <blockquote>
    <b>fossil add</b> <i>file...</i><br>
    <b>fossil rm</b> <i>file...</i>
    </blockquote>

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

    <blockquote>
    <b>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>

</blockquote><h2>Sharing Changes</h2><blockquote>

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

    <blockquote>
    <b>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 <b>push</b> command only sends your changes to others.  To
    Receive changes from others, use <b>pull</b>.  Or go both ways at
    once using <b>sync</b>:</p>

    <blockquote>
    <b>fossil pull</b> <i>URL</i><br>
    <b>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 <b>update</b>:</p>

    <blockquote>
    <b>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.  (<a href="./checkin_names.wiki">More information</a>.)
    If you omit
    the <i>VERSION</i>, then fossil moves you to the
    latest version of the branch your are currently on.</p>

</blockquote><h2>Branching And Merging</h2><blockquote>

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

    <blockquote>
    <b>fossil merge</b> <i>VERSION</i>
    </blockquote>

    <p>The <i>VERSION</i> can be any of the forms allowed for <b>update</b>.
    After performing the merge, you will normally want to test it to
    make sure it does not break anything, then
    <b>commit</b> your chagnes.  In the default configuration, the <b>commit</b>
    command will also automatically <b>push</b> your changes, but that
    feature can be disabled.  (More information about 
    <a href="concepts.wiki#workflow">autosync</a> and how to disable it.)
    Remember that your coworkers can not see your changes until you 
    <b>commit</b> and <b>push</b> them.</p>

    <p>The merge command has options to cherrypick individual
    changes, or to back out individual changes.</p>

    <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>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 <b>redo</b> command if you undo by
    mistake.  Undo and redo only work for changes that have
    not yet been checked in using <b>commit</b> and there is only a single
    level of undo/redo.</p>


<a name="serversetup"></a>
</blockquote><h2>Setting Up A Server</h2><blockquote>

    <p>The easiest way to set up a server is:</p>

    <blockquote>
    <b>fossil server</b> <i>repository-filename</i>
    </blockquote>

    <p>Or</b>

    <blockquote>
    <b>fossil ui</b> <i>repository-filename</i>
    </blockquote>

    <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 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 <b>server</b> command,
    which binds on all IP addresses and does not try to start a web browser.
    You can omit the <i>repository-filename</i> if you are within
    a checked-out local tree.  The <b>server</b> uses port 8080 by default
    but you can specify a different port using the <b>-port</b> option.</p>

    <p>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.
    <a name="cgiserver"></a>
    To use the CGI server, create a CGI script that
    looks something like this:</p>

    <blockquote><b>
    #!/usr/local/bin/fossil<br>
    repository: /home/proj1/repos1.fossil
    </b></blockquote>

    <p>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!</p>

    <a name="inetdserver"></a>
    <p>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:</p>

    <blockquote><b>
    80 stream tcp nowait.1000 root /usr/bin/fossil \<br>
        /usr/bin/fossil http /home/proj1/repos1.fossil
    </b></blockquote>

    <p>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.</p>

</blockquote><a name="proxy"></a><h2>HTTP Proxies</h2><blockquote>

    <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 <b>setting</b> 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>

</blockquote><h2>More Hints</h2><blockquote>

    <p>Try these commands:</p>

    <blockquote><b>
    fossil help<br>
    fossil test-commands
    </b></blockquote>

    <p>Explore and have fun!</p>


</blockquote>
</nowiki>
