d87ca60c58 2008-05-15 stephan: <h1 align="center">Fossil Quick Start</h1> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>This is a guide to get you started using fossil quickly d87ca60c58 2008-05-15 stephan: and painlessly.</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <h2>Installing</h2><blockquote> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>Fossil is a single self-contained C program. You need to d87ca60c58 2008-05-15 stephan: either download a <a href="download.wiki">FIXME precompiled binary</a> d87ca60c58 2008-05-15 stephan: or <a href="build.wiki">build it yourself</a> from sources. d87ca60c58 2008-05-15 stephan: Install fossil by putting the fossil binary d87ca60c58 2008-05-15 stephan: someplace on your PATH environment variable.</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: </blockquote> d87ca60c58 2008-05-15 stephan: <h2>Cloning A Existing Repository</h2> d87ca60c58 2008-05-15 stephan: <blockquote> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>Use this command:</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <blockquote> d87ca60c58 2008-05-15 stephan: <b>fossil clone</b> <i>URL repository-filename</i> d87ca60c58 2008-05-15 stephan: </blockquote> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>The <i>URL</i> above is the http URL for the fossil repository d87ca60c58 2008-05-15 stephan: you want to clone. You can call the new repository anything you d87ca60c58 2008-05-15 stephan: want - there are no naming restrictions. As an example, you can d87ca60c58 2008-05-15 stephan: clone the fossil repository this way:</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <blockquote> d87ca60c58 2008-05-15 stephan: <b>fossil clone http://www.fossil-scm.org/fossil myclone.fsl</b> d87ca60c58 2008-05-15 stephan: </blockquote> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>Note: If you are behind a restrictive firewall, you might need d87ca60c58 2008-05-15 stephan: to <a href="#proxy">specify an HTTP proxy</a> to use.</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: </blockquote><h2>Starting A New Project</h2><blockquote> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>To start a new project with fossil, create a new empty repository d87ca60c58 2008-05-15 stephan: this way:</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <blockquote> d87ca60c58 2008-05-15 stephan: <b>fossil new </b><i> repository-filename</i> d87ca60c58 2008-05-15 stephan: </blockquote> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: </blockquote><h2>Configuring Your Local Repository</h2><blockquote> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>When you create a new repository, either by cloning an existing d87ca60c58 2008-05-15 stephan: project or create a new project of your own, you usually want to do some d87ca60c58 2008-05-15 stephan: local configuration. This is accomplished using a webbrowser. First d87ca60c58 2008-05-15 stephan: start a fossil webserver like this:</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <blockquote> d87ca60c58 2008-05-15 stephan: <b>fossil server </b><i> repository-filename</i> d87ca60c58 2008-05-15 stephan: </blockquote> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>This creates a mini-webserver listening on port 8080. You can d87ca60c58 2008-05-15 stephan: specify a different port using the <b>-port</b> option on the command-line. d87ca60c58 2008-05-15 stephan: After the server is running, point your webbrowser at d87ca60c58 2008-05-15 stephan: http://localhost:8080/ and start configuring.</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>By default, fossil does not require a login for HTTP connections d87ca60c58 2008-05-15 stephan: coming in from the IP loopback address 127.0.0.1. You can, and perhaps d87ca60c58 2008-05-15 stephan: should, change this after you create a few users.</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>When you are finished configuring, just press Control-C or use d87ca60c58 2008-05-15 stephan: the <b>kill</b> command to shut down the mini-server.</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: </blockquote><h2>Checking Out A Local Tree</h2><blockquote> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>To work on a project in fossil, you need to check out a local d87ca60c58 2008-05-15 stephan: copy of the source tree. Create the directory you want to be d87ca60c58 2008-05-15 stephan: the root of your tree and cd into that directory. Then d87ca60c58 2008-05-15 stephan: to this:</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <blockquote> d87ca60c58 2008-05-15 stephan: <b>fossil open </b><i> repository-filename</i> d87ca60c58 2008-05-15 stephan: </blockquote> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>This leaves you with the original (empty) version of the tree d87ca60c58 2008-05-15 stephan: checked out. To get to the latest version, also do this:</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <blockquote> d87ca60c58 2008-05-15 stephan: <b>fossil update</b> d87ca60c58 2008-05-15 stephan: </blockquote> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>From anywhere underneath the root of your local tree, you d87ca60c58 2008-05-15 stephan: can type commands like the following to find out the status of d87ca60c58 2008-05-15 stephan: your local tree:</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <blockquote> d87ca60c58 2008-05-15 stephan: <b>fossil info</b><br> d87ca60c58 2008-05-15 stephan: <b>fossil status</b><br> d87ca60c58 2008-05-15 stephan: <b>fossil changes</b><br> d87ca60c58 2008-05-15 stephan: <b>fossil timeline</b><br> d87ca60c58 2008-05-15 stephan: <b>fossil leaves</b><br> d87ca60c58 2008-05-15 stephan: <b>fossil ls</b><br> d87ca60c58 2008-05-15 stephan: <b>fossil branches</b><br> d87ca60c58 2008-05-15 stephan: </blockquote> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: </blockquote><h2>Making Changes</h2><blockquote> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>To add new files to your project, or remove old files, use these d87ca60c58 2008-05-15 stephan: commands:</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <blockquote> d87ca60c58 2008-05-15 stephan: <b>fossil add</b> <i>file...</i><br> d87ca60c58 2008-05-15 stephan: <b>fossil rm</b> <i>file...</i> d87ca60c58 2008-05-15 stephan: </blockquote> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>You can also edit files freely. Once you are ready to commit d87ca60c58 2008-05-15 stephan: your changes, type:</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <blockquote> d87ca60c58 2008-05-15 stephan: <b>fossil commit</b> d87ca60c58 2008-05-15 stephan: </blockquote> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>You will be prompted for check-in comments using whatever editor d87ca60c58 2008-05-15 stephan: is specified by your VISUAL or EDITOR environment variable. If you d87ca60c58 2008-05-15 stephan: have GPG installed, you may be prompted for your GPG passphrase so d87ca60c58 2008-05-15 stephan: that the check-in can be signed with your GPG signature. After d87ca60c58 2008-05-15 stephan: this your changes will be checked in.</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: </blockquote><h2>Sharing Changes</h2><blockquote> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>The changes you <b>commit</b> are only on your local repository. d87ca60c58 2008-05-15 stephan: To share those changes with other repositories, do:</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <blockquote> d87ca60c58 2008-05-15 stephan: <b>fossil push</b> <i>URL</i> d87ca60c58 2008-05-15 stephan: </blockquote> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>Where <i>URL</i> is the http: URL of the server repository you d87ca60c58 2008-05-15 stephan: want to share your changes with. If you omit the <i>URL</i> argument, d87ca60c58 2008-05-15 stephan: fossil will use whatever server you most recently synced with.</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>The <b>push</b> command only sends your changes to others. To d87ca60c58 2008-05-15 stephan: Receive changes from others, use <b>pull</b>. Or go both ways at d87ca60c58 2008-05-15 stephan: once using <b>sync</b>:</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <blockquote> d87ca60c58 2008-05-15 stephan: <b>fossil pull</b> <i>URL</i><br> d87ca60c58 2008-05-15 stephan: <b>fossil sync</b> <i>URL</i> d87ca60c58 2008-05-15 stephan: </blockquote> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>When you pull in changes from others, they go into your repository, d87ca60c58 2008-05-15 stephan: not into your checked-out local tree. To get the changes into your d87ca60c58 2008-05-15 stephan: local tree, use <b>update</b>:</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <blockquote> d87ca60c58 2008-05-15 stephan: <b>fossil update</b> <i>UUID</i> d87ca60c58 2008-05-15 stephan: </blockquote> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>The <i>UUID</i> is some unique abbreviation to the 40-character d87ca60c58 2008-05-15 stephan: version ID. If you omit the <i>UUID</i> fossil moves you to the d87ca60c58 2008-05-15 stephan: leaf version of the branch your are currently on. If your branch d87ca60c58 2008-05-15 stephan: has multiple leaves, you get an error - you'll have to specify the d87ca60c58 2008-05-15 stephan: leaf you want using a <i>UUID</i> argument.</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: </blockquote><h2>Branching And Merging</h2><blockquote> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>You can create branches by doing multiple commits off of the d87ca60c58 2008-05-15 stephan: same base version. To merge to branches back together, first d87ca60c58 2008-05-15 stephan: <b>update</b> to the leaf of one branch. Then do a <b>merge</b> d87ca60c58 2008-05-15 stephan: of the leaf of the other branch:</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <blockquote> d87ca60c58 2008-05-15 stephan: <b>fossil merge</b> <i>UUID</i> d87ca60c58 2008-05-15 stephan: </blockquote> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>Test to make sure your merge didn't mess up the code, then d87ca60c58 2008-05-15 stephan: <b>commit</b> and possibly also <b>push</b> your changes. Remember d87ca60c58 2008-05-15 stephan: that nobody else can see your changes until you <b>commit</b> and d87ca60c58 2008-05-15 stephan: if other are using a different repository you will also need to d87ca60c58 2008-05-15 stephan: <b>push</b>.</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <a name="serversetup"> d87ca60c58 2008-05-15 stephan: </blockquote><h2>Setting Up A Server</h2><blockquote> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>The easiest way to set up a server is:</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <blockquote> d87ca60c58 2008-05-15 stephan: <b>fossil server</b> <i>repository-filename</i> d87ca60c58 2008-05-15 stephan: </blockquote> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>You can omit the <i>repository-filename</i> if you are within d87ca60c58 2008-05-15 stephan: a checked-out local tree. This server uses port 8080 by default d87ca60c58 2008-05-15 stephan: but you can specify a different port using the <b>-port</b> command.</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>Command-line servers like this are useful when two people want d87ca60c58 2008-05-15 stephan: to share a repository on temporary or ad-hoc basis. For a more d87ca60c58 2008-05-15 stephan: permanent installation, you should use either the CGI server or the d87ca60c58 2008-05-15 stephan: inetd server. To use the CGI server, create a CGI script that d87ca60c58 2008-05-15 stephan: looks something like this:</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <blockquote><b> d87ca60c58 2008-05-15 stephan: #!/usr/local/bin/fossil<br> d87ca60c58 2008-05-15 stephan: repository: /home/proj1/repos1.fsl d87ca60c58 2008-05-15 stephan: </b></blockquote> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>Adjust the paths in this CGI script to match your installation. d87ca60c58 2008-05-15 stephan: Now point clients at the CGI script. That's all there is to it!</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>You can also run fossil off of inetd or xinetd. For an inetd d87ca60c58 2008-05-15 stephan: installation, make an entry in /etc/inetd.conf that looks something d87ca60c58 2008-05-15 stephan: like this:</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <blockquote><b> d87ca60c58 2008-05-15 stephan: 80 stream tcp nowait.1000 root /usr/bin/fossil \<br> d87ca60c58 2008-05-15 stephan: /usr/bin/fossil http /home/proj1/repos1.fsl d87ca60c58 2008-05-15 stephan: </b></blockquote> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>Adjust the paths to suit your installation, of course. Notice that d87ca60c58 2008-05-15 stephan: fossil runs as root. This is not required - you can run it as an d87ca60c58 2008-05-15 stephan: unprivileged user. But it is more secure to run fossil as root. d87ca60c58 2008-05-15 stephan: When you do run fossil as root, it automatically puts itself in a d87ca60c58 2008-05-15 stephan: chroot jail in the same directory as the repository, then drops d87ca60c58 2008-05-15 stephan: root privileges prior to reading any information from the request.</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: </blockquote><a name="proxy"></a><h2>HTTP Proxies</h2><blockquote> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>If you are behind a restrictive firewall that requires you to use d87ca60c58 2008-05-15 stephan: an HTTP proxy to reach the internet, then you can configure the proxy d87ca60c58 2008-05-15 stephan: in three different ways. You can tell fossil about your proxy using d87ca60c58 2008-05-15 stephan: a command-line option on commands that use the network, d87ca60c58 2008-05-15 stephan: <b>sync</b>, <b>clone</b>, <b>push</b>, and <b>pull</b>.</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <blockquote> d87ca60c58 2008-05-15 stephan: <b>fossil clone </b><i>URL</i> <b>--proxy</b> <i>Proxy-URL</i> d87ca60c58 2008-05-15 stephan: </blockquote> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>It is annoying to have to type in the proxy URL every time you d87ca60c58 2008-05-15 stephan: sync your project, though, so you can make the proxy configuration d87ca60c58 2008-05-15 stephan: persistent using the <b>setting</b> command:</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <blockquote> d87ca60c58 2008-05-15 stephan: <b>fossil setting proxy </b><i>Proxy-URL</i> d87ca60c58 2008-05-15 stephan: </blockquote> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>Or, you can set the "<b>http_proxy</b>" environment variable:</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <blockquote> d87ca60c58 2008-05-15 stephan: <b>export http_proxy=</b><i>Proxy-URL</i> d87ca60c58 2008-05-15 stephan: </blockquote> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>To stop using the proxy, do:</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <blockquote> d87ca60c58 2008-05-15 stephan: <b>fossil setting proxy off</b> d87ca60c58 2008-05-15 stephan: </blockquote> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>Or unset the environment variable. The fossil setting for the d87ca60c58 2008-05-15 stephan: HTTP proxy takes precedence over the environment variable and the d87ca60c58 2008-05-15 stephan: command-line option overrides both. If you have an persistent d87ca60c58 2008-05-15 stephan: proxy setting that you want to override for a one-time sync, that d87ca60c58 2008-05-15 stephan: is easily done on the command-line. For example, to sync with d87ca60c58 2008-05-15 stephan: a co-workers repository on your LAN, you might type:</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <blockquote> d87ca60c58 2008-05-15 stephan: <b>fossil sync http://192.168.1.36:8080/ --proxy off</b> d87ca60c58 2008-05-15 stephan: </blockquote> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: </blockquote><h2>More Hints</h2><blockquote> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>Try these commands:</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <blockquote><b> d87ca60c58 2008-05-15 stephan: fossil help<br> d87ca60c58 2008-05-15 stephan: fossil test-commands d87ca60c58 2008-05-15 stephan: </b></blockquote> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>Explore and have fun!</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: </blockquote> d87ca60c58 2008-05-15 stephan:
File Annotation