d87ca60c58 2008-05-15 stephan: <h1 align="center"> d87ca60c58 2008-05-15 stephan: Fossil Concepts d87ca60c58 2008-05-15 stephan: </h1> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <h2>1.0 Introduction</h2> d87ca60c58 2008-05-15 stephan: <p> d87ca60c58 2008-05-15 stephan: <a href="index.html">Fossil</a> is a d87ca60c58 2008-05-15 stephan: <a href="http://en.wikipedia.org/wiki/Software_configuration_management"> d87ca60c58 2008-05-15 stephan: software configuration management</a> system. d87ca60c58 2008-05-15 stephan: Fossil is software that is designed to control and track the d87ca60c58 2008-05-15 stephan: development of a software project and to record the history d87ca60c58 2008-05-15 stephan: of the project. d87ca60c58 2008-05-15 stephan: There are many such systems in use today. Fossil strives to d87ca60c58 2008-05-15 stephan: distinguish itself from the others by being extremely simple d87ca60c58 2008-05-15 stephan: to setup and operate.</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>This document is intended as a quick introduction to the concepts d87ca60c58 2008-05-15 stephan: behind fossil.</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <h2>2.0 Composition Of A Project</h2> d87ca60c58 2008-05-15 stephan: <img src="concept1.gif" align="right" hspace="10"> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>A software project normally consists of a "source tree". d87ca60c58 2008-05-15 stephan: A source tree is a hierarchy of files that are used to generate d87ca60c58 2008-05-15 stephan: the end product. The source tree changes over time as the d87ca60c58 2008-05-15 stephan: software grows and expands and as features are added and bugs d87ca60c58 2008-05-15 stephan: are fixed. A snapshot of the source tree at any point in time d87ca60c58 2008-05-15 stephan: is called a "version" or "revision" or a "baseline" of the product. d87ca60c58 2008-05-15 stephan: In fossil, we use the name "baseline".</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>A "repository" is a database that contains copies of all historical d87ca60c58 2008-05-15 stephan: versions or baselines for a project. Baselines are normally stored in the d87ca60c58 2008-05-15 stephan: repository in a highly space-efficient compressed format (delta encoding). d87ca60c58 2008-05-15 stephan: But that is an implementation detail that you the user need not worry over. d87ca60c58 2008-05-15 stephan: Think of the repository as a safe place where all your old baselines are d87ca60c58 2008-05-15 stephan: securely stored away and available for retrieval whenever you need d87ca60c58 2008-05-15 stephan: them.</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>A repository in fossil is a single file on your disk. This file d87ca60c58 2008-05-15 stephan: might be rather large (dozens or hundreds of megabytes for a large d87ca60c58 2008-05-15 stephan: or long running project) but it is nevertheless just a file. You d87ca60c58 2008-05-15 stephan: can move it around, rename it, write it out to a memory stick, or d87ca60c58 2008-05-15 stephan: do anything else you normally do with files.</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>Each source tree that is controlled by fossil is associated with d87ca60c58 2008-05-15 stephan: a single repository on the local disk drive. You can tie two or more d87ca60c58 2008-05-15 stephan: source trees to a single repository if you want (though one d87ca60c58 2008-05-15 stephan: tree per repository is the most common configuration.) So a d87ca60c58 2008-05-15 stephan: single repository can be associated with many source trees, but d87ca60c58 2008-05-15 stephan: each source tree is associated with only one repository.</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>Fossil source trees may not overlap. A fossil source tree is identified d87ca60c58 2008-05-15 stephan: by a file named "_FOSSIL_" in the root directory of the source tree. Every d87ca60c58 2008-05-15 stephan: file that is a sibling of _FOSSIL_ and every file in every subfolder is d87ca60c58 2008-05-15 stephan: considered potentially a part of the source tree. The _FOSSIL_ file d87ca60c58 2008-05-15 stephan: contains (among other things) the pathname of the repository with which d87ca60c58 2008-05-15 stephan: the source tree is associated. On the other hand, the repository has d87ca60c58 2008-05-15 stephan: no record of its source trees. So you are free to delete a source tree d87ca60c58 2008-05-15 stephan: or move it around without consequence. But if you move or rename or d87ca60c58 2008-05-15 stephan: delete a repository, then any source trees associated with that repository d87ca60c58 2008-05-15 stephan: will no longer be able to locate their repository and will stop working.</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>When multiple developers are working on the same project, each d87ca60c58 2008-05-15 stephan: developer typically has his or her own local repository and an associated d87ca60c58 2008-05-15 stephan: source tree in which to work. Developers share their work by d87ca60c58 2008-05-15 stephan: "syncing" the content of their local repositories either directly d87ca60c58 2008-05-15 stephan: or through a central server. Changes can "push" from the local d87ca60c58 2008-05-15 stephan: repository into a remote repository. Or changes can "pull" from a d87ca60c58 2008-05-15 stephan: remote repository into a local repository. Or one can do a "sync" d87ca60c58 2008-05-15 stephan: which is a shortcut for doing both a push and a pull at the same time. d87ca60c58 2008-05-15 stephan: Fossil also has the concept of "cloning". A "clone" is like a "pull", d87ca60c58 2008-05-15 stephan: except that instead of beginning with an existing local repository, d87ca60c58 2008-05-15 stephan: a clone begins with nothing and creates a new local repository that d87ca60c58 2008-05-15 stephan: is a duplicate of a remote repository.</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>Communication between repositories is via HTTP. Remote d87ca60c58 2008-05-15 stephan: repositories are identified by URL. You can also point a webbrowser d87ca60c58 2008-05-15 stephan: at a repository and get human-readable status, history, and tracking d87ca60c58 2008-05-15 stephan: information about the project.</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <h3>2.1 Identification Of Artifacts</h3> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>A particular version of a particular file is called an "artifact". d87ca60c58 2008-05-15 stephan: Each artifact has a universally unique name which is the d87ca60c58 2008-05-15 stephan: <a href="http://en.wikipedia.org/wiki/SHA">SHA1</a> hash of the content d87ca60c58 2008-05-15 stephan: of that file expressed as 40 characters of lower-case hexadecimal. Such d87ca60c58 2008-05-15 stephan: a hash is referred to as the Universally Unique Identifier or UUID d87ca60c58 2008-05-15 stephan: for the artifact. The SHA1 algorithm is created with the purpose of d87ca60c58 2008-05-15 stephan: providing a highly forgery-resistent identifier for a file. Given any d87ca60c58 2008-05-15 stephan: file it is simple to find the UUID for that file. But given a d87ca60c58 2008-05-15 stephan: UUID it is computationally intractable to generate a file that will d87ca60c58 2008-05-15 stephan: have that UUID.</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>UUIDs look something like this:</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <blockquote><b> d87ca60c58 2008-05-15 stephan: 6089f0b563a9db0a6d90682fe47fd7161ff867c8<br> d87ca60c58 2008-05-15 stephan: 59712614a1b3ccfd84078a37fa5b606e28434326<br> d87ca60c58 2008-05-15 stephan: 19dbf73078be9779edd6a0156195e610f81c94f9<br> d87ca60c58 2008-05-15 stephan: b4104959a67175f02d6b415480be22a239f1f077<br> d87ca60c58 2008-05-15 stephan: 997c9d6ae03ad114b2b57f04e9eeef17dcb82788 d87ca60c58 2008-05-15 stephan: </b></blockquote> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>When referring to an artifact using fossil, you can use a unique d87ca60c58 2008-05-15 stephan: prefix of the UUID that is four characters or longer. This saves d87ca60c58 2008-05-15 stephan: a lot of typing. When displaying UUIDs, fossil will usually only d87ca60c58 2008-05-15 stephan: show the first 10 digits since that is normally enough to uniquely d87ca60c58 2008-05-15 stephan: identify a file.</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>Changing (or adding or removing) a single byte in a file results d87ca60c58 2008-05-15 stephan: in a completely different UUID. And since the UUID is the name of d87ca60c58 2008-05-15 stephan: the artifact, making any change to a file results in a new artifact. d87ca60c58 2008-05-15 stephan: In this way, artifacts are immutable.</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>A repository is really just an unordered collection of d87ca60c58 2008-05-15 stephan: artifacts. New artifacts can be added to the repository, but d87ca60c58 2008-05-15 stephan: existing artifacts can never be removed. Fossil is designed in d87ca60c58 2008-05-15 stephan: such a way that it can be handed a set of artifacts in any d87ca60c58 2008-05-15 stephan: order and it can figure out the relationship between those d87ca60c58 2008-05-15 stephan: artifacts and reconstruct the complete development history of d87ca60c58 2008-05-15 stephan: a software project.</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <h3>2.2 Manifests</h3> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>At the root of a source tree is a special file called the d87ca60c58 2008-05-15 stephan: "manifest". The manifest is a listing of all other files in d87ca60c58 2008-05-15 stephan: that source tree. The manifest contains the (complete) UUID d87ca60c58 2008-05-15 stephan: of the file and the name of the file as it appears on disk, d87ca60c58 2008-05-15 stephan: and thus serves as a mapping from UUID to disk name. The UUID d87ca60c58 2008-05-15 stephan: of the manifest is the UUID that identifies a baseline. When d87ca60c58 2008-05-15 stephan: you look at a "timeline" of changes in fossil, the UUID associated d87ca60c58 2008-05-15 stephan: with each check-in or commit is really just the UUID of the d87ca60c58 2008-05-15 stephan: manifest for that baseline.</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>Fossil automatically generates a manifest whenever you "commit" d87ca60c58 2008-05-15 stephan: a new baseline. So this is not something that you, the developer, d87ca60c58 2008-05-15 stephan: need to worry with. The format of a manifest is intentionally d87ca60c58 2008-05-15 stephan: designed to be simple to parse, so that if d87ca60c58 2008-05-15 stephan: you want to read and interpret a manifest, either by hand or d87ca60c58 2008-05-15 stephan: with a script, that is easy to do. But you will probably never d87ca60c58 2008-05-15 stephan: need to do so.</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>In addition to identifying all files in the baseline, a d87ca60c58 2008-05-15 stephan: manifest also contains a check-in comment, the date and time d87ca60c58 2008-05-15 stephan: when the baseline was established, who created the baseline, d87ca60c58 2008-05-15 stephan: and links to other baselines from which the current baseline d87ca60c58 2008-05-15 stephan: is derived. There is also a couple of checksums used to verify d87ca60c58 2008-05-15 stephan: the integrity of the baseline. And the whole manifest might d87ca60c58 2008-05-15 stephan: be PGP clearsigned.</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <h3>2.3 Key concepts</h3> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <ul> d87ca60c58 2008-05-15 stephan: <li>A <b>baseline</b> is a set of files arranged d87ca60c58 2008-05-15 stephan: in a hierarchy.</li> d87ca60c58 2008-05-15 stephan: <li>A <b>repository</b> keeps a record of historical baselines.</li> d87ca60c58 2008-05-15 stephan: <li>Repositories share their changes using <b>push</b>, <b>pull</b>, d87ca60c58 2008-05-15 stephan: <b>sync</b>, and <b>clone</b>.</li> d87ca60c58 2008-05-15 stephan: <li>A particular version of a particular file is an <b>artifact</b> d87ca60c58 2008-05-15 stephan: that is identified by a <b>UUID</b>.</li> d87ca60c58 2008-05-15 stephan: <li>Artifacts tracked by fossil are inherently immutable.</li> d87ca60c58 2008-05-15 stephan: <li>Fossil automatically generates a <b>manifest</b> file that identifies d87ca60c58 2008-05-15 stephan: every artifact in a baseline.</li> d87ca60c58 2008-05-15 stephan: <li>The UUID of the manifest is the UUID of the baseline.</li> d87ca60c58 2008-05-15 stephan: </ul> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <h2>3.0 Fossil - The Program</h2> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>Fossil is software. The implementation of fossil is in the form d87ca60c58 2008-05-15 stephan: of a single executable named "fossil". To install fossil on your system, d87ca60c58 2008-05-15 stephan: all you have to do is obtain a copy of this one executable file (either d87ca60c58 2008-05-15 stephan: by downloading a precompiled version or compiling it yourself) and then d87ca60c58 2008-05-15 stephan: putting that file somewhere on your PATH.</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>Fossil is completely self-contained. It is not necessary to d87ca60c58 2008-05-15 stephan: install any other software in order to use fossil. You do <u>not</u> need d87ca60c58 2008-05-15 stephan: CVS, gzip, diff, rsync, Python, Perl, Tcl, Java, apache, PostgreSQL, MySQL, d87ca60c58 2008-05-15 stephan: SQLite, patch, or any similar software on your system in order to use d87ca60c58 2008-05-15 stephan: fossil effectively. You will want to have some kind of text editor d87ca60c58 2008-05-15 stephan: for entering check-in comments. Fossil will use whatever text editor d87ca60c58 2008-05-15 stephan: is identified by your VISUAL environment variable. Fossil will also d87ca60c58 2008-05-15 stephan: use GPG to clearsign your manifests if you happen to have it installed, d87ca60c58 2008-05-15 stephan: but fossil will skip that step if GPG missing from your system. d87ca60c58 2008-05-15 stephan: You can optionally set up fossil to use external "diff" programs, d87ca60c58 2008-05-15 stephan: though a perfectly functional "diff" algorithm is built it and works e5aac82dd5 2008-05-16 drh: fine for most people.</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>To uninstall fossil, simply delete the executable.</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>To upgrade an older version of fossil to a newer version, just d87ca60c58 2008-05-15 stephan: replace the old executable with the new one. You might need to d87ca60c58 2008-05-15 stephan: run a one-time command to restructure your repositories after d87ca60c58 2008-05-15 stephan: an upgrade. Check the instructions that come with the upgrade d87ca60c58 2008-05-15 stephan: for details.</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>To use fossil, simply type the name of executable in your d87ca60c58 2008-05-15 stephan: shell, followed by one of the various built-in commands and d87ca60c58 2008-05-15 stephan: arguments appropriate for that command. For example:</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <blockquote><b> d87ca60c58 2008-05-15 stephan: fossil help d87ca60c58 2008-05-15 stephan: </b></blockquote> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>In the next section, when we say things like "use the <b>help</b> d87ca60c58 2008-05-15 stephan: command" we mean to use the command name "help" as the first d87ca60c58 2008-05-15 stephan: token after the name of the fossil executable, as shown above.</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <h2>4.0 Workflow</h2> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <img src="concept2.gif" align="right" hspace="10"> 16094f7ebc 2008-05-16 drh: d87ca60c58 2008-05-15 stephan: <ol> d87ca60c58 2008-05-15 stephan: <li><p> d87ca60c58 2008-05-15 stephan: Establish a local repository using either the <b>new</b> command d87ca60c58 2008-05-15 stephan: to start a new project, or the <b>clone</b> command to make a clone d87ca60c58 2008-05-15 stephan: of a repository for an existing project. d87ca60c58 2008-05-15 stephan: </p></li> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <li><p> d87ca60c58 2008-05-15 stephan: Establish one or more source trees by changing your working directory d87ca60c58 2008-05-15 stephan: to where you want the root of the source tree to be, then issuing d87ca60c58 2008-05-15 stephan: the <b>open</b> command with the name of the repository file as its d87ca60c58 2008-05-15 stephan: argument. d87ca60c58 2008-05-15 stephan: </p></li> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <li><p> d87ca60c58 2008-05-15 stephan: Use the <b>update</b> command followed by a UUID to cause your d87ca60c58 2008-05-15 stephan: source tree to change to the baseline identified by that UUID. d87ca60c58 2008-05-15 stephan: The <b>timeline</b> or <b>leaves</b> commands might help you to d87ca60c58 2008-05-15 stephan: identify an appropriate baseline. d87ca60c58 2008-05-15 stephan: </p></li> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <li><p> d87ca60c58 2008-05-15 stephan: Edit the code. Add new files to the source tree using the <b>add</b> d87ca60c58 2008-05-15 stephan: command. Omit files from future baselines using the <b>rm</b> command. d87ca60c58 2008-05-15 stephan: (Even when you remove files from future baselines, those files continue d87ca60c58 2008-05-15 stephan: to exist in historical baselines.) Test your changes. d87ca60c58 2008-05-15 stephan: </p></li> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <li><p> d87ca60c58 2008-05-15 stephan: Create a new baseline using the <b>commit</b> command. You will be prompted d87ca60c58 2008-05-15 stephan: for a check-in comment and also for your GPG key if you have GPG installed. d87ca60c58 2008-05-15 stephan: The commit copies the edits you have made in your local source d87ca60c58 2008-05-15 stephan: tree into your local repository. d87ca60c58 2008-05-15 stephan: </p></li> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <li><p> d87ca60c58 2008-05-15 stephan: Share your changes with others using the <b>push</b> command. d87ca60c58 2008-05-15 stephan: Push causes the edits you committed into your local repository to be d87ca60c58 2008-05-15 stephan: pushed out into other repositories. d87ca60c58 2008-05-15 stephan: </p></li> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <li><p> d87ca60c58 2008-05-15 stephan: When your coworkers make their own changes, you can pull those changes d87ca60c58 2008-05-15 stephan: into your local repository using the <b>pull</b> command. Note that d87ca60c58 2008-05-15 stephan: the pull command only pulls the changes into your local repository, d87ca60c58 2008-05-15 stephan: not into your local source tree. d87ca60c58 2008-05-15 stephan: </p></li> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <li><p> d87ca60c58 2008-05-15 stephan: After the changes of others are in your local repository, you d87ca60c58 2008-05-15 stephan: can move them into your local source tree using <b>update</b>. If d87ca60c58 2008-05-15 stephan: you have made parallel d87ca60c58 2008-05-15 stephan: changes, you can merge your changes together with your coworkers changes d87ca60c58 2008-05-15 stephan: by do an <b>update</b> to your latest baseline, then doing a d87ca60c58 2008-05-15 stephan: <b>merge</b> with your coworkers latest baseline. After your d87ca60c58 2008-05-15 stephan: verify that the merged code is still functional, you can <b>commit</b> d87ca60c58 2008-05-15 stephan: a new baseline that contains both yours and your coworkers changes d87ca60c58 2008-05-15 stephan: and then push the new baseline back to your coworker. d87ca60c58 2008-05-15 stephan: </p></li> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <li><p> d87ca60c58 2008-05-15 stephan: Repeat all of the above until you have generated great software. d87ca60c58 2008-05-15 stephan: </p></li> d87ca60c58 2008-05-15 stephan: </ol> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <h3>4.1 Variations</h3> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>The <b>settings</b> lets you view and modify various operating d87ca60c58 2008-05-15 stephan: properties of fossil. Among the available settings is "autosync" d87ca60c58 2008-05-15 stephan: mode. When autosync is enabled, the push and pull of content from d87ca60c58 2008-05-15 stephan: your local server is largely automated. Whenever you use the <b>update</b> d87ca60c58 2008-05-15 stephan: command, fossil first does a <b>pull</b> to see if other users have d87ca60c58 2008-05-15 stephan: perhaps added new baselines to the central repository. When you d87ca60c58 2008-05-15 stephan: <b>commit</b>, fossil also does a <b>pull</b> and issues a warning d87ca60c58 2008-05-15 stephan: if your check-in would cause a fork. After a <b>commit</b>, fossil d87ca60c58 2008-05-15 stephan: automatically does a <b>push</b> to send your changes up to the d87ca60c58 2008-05-15 stephan: central server.</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>With autosync enabled, fossil works like d87ca60c58 2008-05-15 stephan: <a href="http://www.nongnu.org/cvs/">CVS</a> or d87ca60c58 2008-05-15 stephan: <a href="http://subversion.tigris.org/">Subversion</a>. d87ca60c58 2008-05-15 stephan: When autosync disabled, fossil works more like d87ca60c58 2008-05-15 stephan: <a href="http://monotone.ca/">Monotone</a>, d87ca60c58 2008-05-15 stephan: <a href="http://git.or.cz">GIT</a>, or d87ca60c58 2008-05-15 stephan: <a href="http://www.selenic.com/mercurial/wiki/">Mercurial</a>. d87ca60c58 2008-05-15 stephan: The fun thing about fossil is that it will work either d87ca60c58 2008-05-15 stephan: way, depending on your needs of the moment. You can freely switch d87ca60c58 2008-05-15 stephan: between these operating modes using commands like:</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <blockquote> d87ca60c58 2008-05-15 stephan: <b>fossil setting autosync off<br /> d87ca60c58 2008-05-15 stephan: fossil setting autosync on</b> d87ca60c58 2008-05-15 stephan: </blockquote> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>For additional information about autosync and other settings d87ca60c58 2008-05-15 stephan: using the <b>help</b> command.</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <h2>5.0 Setting Up A Fossil Server</h2> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>With other configuration management software, setting up a server is d87ca60c58 2008-05-15 stephan: a lot of work and normally takes time, patience, and a lot of system d87ca60c58 2008-05-15 stephan: knowledge. Fossil is designed to avoid this frustration. Setting up d87ca60c58 2008-05-15 stephan: a server with fossil is ridiculously easy. You have three options:</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <ol> d87ca60c58 2008-05-15 stephan: <li><p><b>Setting up a stand-alone server</b></p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>From within your source tree just use the <b>server</b> command and d87ca60c58 2008-05-15 stephan: fossil will start listening for incoming requests on TCP port 8080. d87ca60c58 2008-05-15 stephan: You can point your webbrowser at <a href="http://localhost:8080/"> d87ca60c58 2008-05-15 stephan: http://localhost:8080/</a> and begin exploring. Or your coworkers d87ca60c58 2008-05-15 stephan: can do pushes or pulls against your server. Use the <b>--port</b> d87ca60c58 2008-05-15 stephan: option to the server command to specify a different TCP port. If d87ca60c58 2008-05-15 stephan: you do not have a local source tree, use the <b>-R</b> command-line d87ca60c58 2008-05-15 stephan: option to specify the repository file.</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>A stand-alone server is a great way to set of transient connections d87ca60c58 2008-05-15 stephan: between coworkers for doing quick pushes or pulls. But you can also d87ca60c58 2008-05-15 stephan: set up a permanent stand-alone server if you prefer. Just make d87ca60c58 2008-05-15 stephan: arrangements for fossil to be launched with appropriate arguments d87ca60c58 2008-05-15 stephan: after every reboot.</p> d87ca60c58 2008-05-15 stephan: </li> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <li><p><b>Setting up a CGI server</b></p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>If you have a webserver running on your machine already, you can d87ca60c58 2008-05-15 stephan: set up fossil to be run from CGI. Simply create an executable script d87ca60c58 2008-05-15 stephan: that looks something like this:</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <blockquote><pre> d87ca60c58 2008-05-15 stephan: #!/usr/local/bin/fossil d87ca60c58 2008-05-15 stephan: repository: /home/me/bigproject.fossil d87ca60c58 2008-05-15 stephan: </pre></blockquote> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>Edit this script to use whatever pathnames are appropriate for d87ca60c58 2008-05-15 stephan: your project. Then point your webbrowser at the script and off you d87ca60c58 2008-05-15 stephan: go.</p></li> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <li><p><b>Setting up an inetd server</b></p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>If you have inetd or xinetd running on your system, you can set d87ca60c58 2008-05-15 stephan: those services up to launch fossil to deal with inbound TCP/IP connections d87ca60c58 2008-05-15 stephan: on whatever port you want. Set up inetd or xinetd to launch fossil d87ca60c58 2008-05-15 stephan: like this:</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <blockquote><pre> d87ca60c58 2008-05-15 stephan: /usr/local/bin/fossil http /home/me/bigproject.fossil d87ca60c58 2008-05-15 stephan: </pre></blockquote> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>As before, change the filenames to whatever is appropriate for d87ca60c58 2008-05-15 stephan: your system. You can have fossil run as any user that has write d87ca60c58 2008-05-15 stephan: permission on the repository and on the directory that contains the d87ca60c58 2008-05-15 stephan: repository. But it is safer to run fossil as root. When fossil d87ca60c58 2008-05-15 stephan: sees that it is running as root, it automatically puts itself into d87ca60c58 2008-05-15 stephan: a <a href="http://en.wikipedia.org/wiki/Chroot">chroot jail</a> and d87ca60c58 2008-05-15 stephan: drops all privileges prior to reading any information from the client. d87ca60c58 2008-05-15 stephan: Since fossil is a stand-alone program, you do not need to put anything d87ca60c58 2008-05-15 stephan: in the chroot jail with fossil in order for it to do its job.</p> d87ca60c58 2008-05-15 stephan: </li> d87ca60c58 2008-05-15 stephan: </ol>
File Annotation