5523218023 2009-08-24 drh: <title>Fossil Quick Start Guide</title> 16094f7ebc 2008-05-16 drh: <nowiki> 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 16094f7ebc 2008-05-16 drh: either download a 16094f7ebc 2008-05-16 drh: <a href="http://www.fossil-scm.org/download.html">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: 3c1234c0f2 2009-09-12 drh: </blockquote> 3c1234c0f2 2009-09-12 drh: <a name="fslclone"></a> 3c1234c0f2 2009-09-12 drh: <h2>Cloning An Existing Repository</h2><blockquote> 70dcb9fc8b 2008-05-19 drh: 70dcb9fc8b 2008-05-19 drh: <p>Most fossil operations interact with a repository that is on the 70dcb9fc8b 2008-05-19 drh: local disk drive, not on a remote system. Hence, before accessing 70dcb9fc8b 2008-05-19 drh: a remote repository it is necessary to make a local copy of that 70dcb9fc8b 2008-05-19 drh: repository. Making a local copy of a remote repository is called 70dcb9fc8b 2008-05-19 drh: "cloning".</p> 70dcb9fc8b 2008-05-19 drh: 70dcb9fc8b 2008-05-19 drh: <p>Clone a remote repository as follows:</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 d1477108b0 2008-05-20 stephan: you want to clone, and it may include a "user:password" part, e.g. d1477108b0 2008-05-20 stephan: <tt>http://drh:secret@www.fossil-scm.org/fossil</tt>. You can d1477108b0 2008-05-20 stephan: call the new repository anything you want - there are no naming d1477108b0 2008-05-20 stephan: restrictions. As an example, you can clone the fossil repository d1477108b0 2008-05-20 stephan: this way:</p> d1477108b0 2008-05-20 stephan: d1477108b0 2008-05-20 stephan: <blockquote> 42ed55e82f 2008-06-02 drh: <b>fossil clone http://www.fossil-scm.org/ myclone.fossil</b> 70dcb9fc8b 2008-05-19 drh: </blockquote> 70dcb9fc8b 2008-05-19 drh: 70dcb9fc8b 2008-05-19 drh: <p>The new local copy of the respository is stored in a single file, 70dcb9fc8b 2008-05-19 drh: which in the example above is named "myclone.fossil". 70dcb9fc8b 2008-05-19 drh: You can name your repositories anything you want. The ".fossil" suffix 70dcb9fc8b 2008-05-19 drh: is not required.</p> 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 42ed55e82f 2008-06-02 drh: local configuration. This is easily accomplished using the webserver 42ed55e82f 2008-06-02 drh: that is built into fossil. Start the fossil webserver like this:</p> 06689854ae 2008-05-17 drh: 06689854ae 2008-05-17 drh: <blockquote> 06689854ae 2008-05-17 drh: <b>fossil ui </b><i> repository-filename</i> 06689854ae 2008-05-17 drh: </blockquote> 06689854ae 2008-05-17 drh: 924554d78b 2008-07-18 drh: <p>This starts a 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. 06689854ae 2008-05-17 drh: After the server is running, fossil will then attempt to launch your 06689854ae 2008-05-17 drh: web browser and make it point to this web server. If your system 06689854ae 2008-05-17 drh: has an unusual configuration, fossil might not be able to figure out 06689854ae 2008-05-17 drh: how to start your web browser. In that case, start the web browser 06689854ae 2008-05-17 drh: yourself and point it at http://localhost:8080/. Click on the 766bec08ce 2009-01-25 drh: "Admin" link on the menu bar to start configuring your repository.</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 924554d78b 2008-07-18 drh: do 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: 06689854ae 2008-05-17 drh: <p>This leaves you with the newest version of the tree 06689854ae 2008-05-17 drh: checked out. 06689854ae 2008-05-17 drh: 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> da4363308c 2009-09-12 rwilson: <b>fossil branch list</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> e8c4f69c50 2008-10-24 drh: <b>fossil update</b> <i>AID</i> d87ca60c58 2008-05-15 stephan: </blockquote> d87ca60c58 2008-05-15 stephan: e8c4f69c50 2008-10-24 drh: <p>The <i>AID</i> is some unique abbreviation to the 40-character 904ee40b93 2009-01-23 drh: artifact identifier (AID) for a particular check-in. If you omit e8c4f69c50 2008-10-24 drh: the <i>AID</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 e8c4f69c50 2008-10-24 drh: leaf you want using a <i>AID</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> e8c4f69c50 2008-10-24 drh: <b>fossil merge</b> <i>AID</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: 70dcb9fc8b 2008-05-19 drh: <a name="serversetup"></a> 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: 06689854ae 2008-05-17 drh: <p>Or</b> 06689854ae 2008-05-17 drh: 06689854ae 2008-05-17 drh: <blockquote> 06689854ae 2008-05-17 drh: <b>fossil ui</b> <i>repository-filename</i> 06689854ae 2008-05-17 drh: </blockquote> 06689854ae 2008-05-17 drh: 06689854ae 2008-05-17 drh: <p>The difference between these two command is that <b>ui</b> e65e669148 2008-05-24 drh: attempts to automatically start your web browser pointing at the 06689854ae 2008-05-17 drh: server whereas <b>server</b> does not. 06689854ae 2008-05-17 drh: 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 c8893c69ac 2008-10-05 drh: inetd server. c8893c69ac 2008-10-05 drh: <a name="cgiserver"></a> c8893c69ac 2008-10-05 drh: 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> 70dcb9fc8b 2008-05-19 drh: repository: /home/proj1/repos1.fossil d87ca60c58 2008-05-15 stephan: </b></blockquote> d87ca60c58 2008-05-15 stephan: e65e669148 2008-05-24 drh: <p>Adjust the paths in this CGI script to match your installation e2431b17df 2009-11-09 drh: and make sure both repository file and the directory that contains it e2431b17df 2009-11-09 drh: are readable and writable by the user that CGI scripts run as. e65e669148 2008-05-24 drh: Then point clients at the CGI script. That's all there is to it!</p> e65e669148 2008-05-24 drh: c8893c69ac 2008-10-05 drh: <a name="inetdserver"></a> e2431b17df 2009-11-09 drh: <p>You can also run fossil from 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> 70dcb9fc8b 2008-05-19 drh: /usr/bin/fossil http /home/proj1/repos1.fossil 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> d1477108b0 2008-05-20 stephan: </nowiki>
File Annotation