26a2b61dbd 2008-05-29 drh: <nowiki> 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, 26a2b61dbd 2008-05-29 drh: though SQLite has an excellent built-in "diff" algorithm that 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: 26a2b61dbd 2008-05-29 drh: <p>To use fossil, simply type the name of the 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"> 26a2b61dbd 2008-05-29 drh: 26a2b61dbd 2008-05-29 drh: <p>Fossil has two modes of operation: "autosync" and "non-autosync". 26a2b61dbd 2008-05-29 drh: Autosync mode works something like CVS or SVN in that it automatically 26a2b61dbd 2008-05-29 drh: keeps your work in sync with the central server. Non-autosync is 26a2b61dbd 2008-05-29 drh: more like GIT, or Bitkeeper in that your local repository develops 26a2b61dbd 2008-05-29 drh: independently of your coworkers and you share your changes manually. 26a2b61dbd 2008-05-29 drh: The interesting thing about fossil is that it supports both autosync 26a2b61dbd 2008-05-29 drh: and non-autosync work flows.</p> 26a2b61dbd 2008-05-29 drh: 26a2b61dbd 2008-05-29 drh: <p>The default setting for fossil is to be in autosync mode. You 26a2b61dbd 2008-05-29 drh: can change the autosync setting or check the current autosync 26a2b61dbd 2008-05-29 drh: setting using commands like:</p> 26a2b61dbd 2008-05-29 drh: 26a2b61dbd 2008-05-29 drh: <blockquote> 26a2b61dbd 2008-05-29 drh: <b>fossil setting autosync on<br> 26a2b61dbd 2008-05-29 drh: fossil setting autosync off<br> 26a2b61dbd 2008-05-29 drh: <b>fossil settings</b> 26a2b61dbd 2008-05-29 drh: </blockquote> 26a2b61dbd 2008-05-29 drh: 26a2b61dbd 2008-05-29 drh: <p>By default, fossil runs with autosync mode turned on. The 26a2b61dbd 2008-05-29 drh: authors find that projects run more smoothly when autosync is only 26a2b61dbd 2008-05-29 drh: disabled when off-network.</p> 26a2b61dbd 2008-05-29 drh: 26a2b61dbd 2008-05-29 drh: <h3>4.1 Autosync Workflow</h3> 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> 26a2b61dbd 2008-05-29 drh: The <b>open</b> command in the previous step populates your local source 26a2b61dbd 2008-05-29 drh: tree with a copy of the latest baseline. Usually this is what you want. 26a2b61dbd 2008-05-29 drh: In the rare cases where it is not, use the <b>update</b> command to 26a2b61dbd 2008-05-29 drh: switch to a new baseline. Use the <b>timeline</b> or <b>leaves</b> commands 26a2b61dbd 2008-05-29 drh: to identify alternative baselines to switch to. 26a2b61dbd 2008-05-29 drh: </p></li> 26a2b61dbd 2008-05-29 drh: 26a2b61dbd 2008-05-29 drh: <li><p> 26a2b61dbd 2008-05-29 drh: Edit the code. Add new files to the source tree using the <b>add</b> 26a2b61dbd 2008-05-29 drh: command. Omit files from future baselines using the <b>rm</b> command. 26a2b61dbd 2008-05-29 drh: (Even when you remove files from future baselines, those files continue 26a2b61dbd 2008-05-29 drh: to exist in historical baselines.) Test your changes. 26a2b61dbd 2008-05-29 drh: </p></li> 26a2b61dbd 2008-05-29 drh: 26a2b61dbd 2008-05-29 drh: <li><p> 26a2b61dbd 2008-05-29 drh: Create a new baseline using the <b>commit</b> command. You will be prompted 26a2b61dbd 2008-05-29 drh: for a check-in comment and also for your GPG key if you have GPG installed. 26a2b61dbd 2008-05-29 drh: The commit copies the edits you have made in your local source 26a2b61dbd 2008-05-29 drh: tree into your local repository. After your commit completes, fossil will 26a2b61dbd 2008-05-29 drh: automatically <b>push</b> your changes back to the server 26a2b61dbd 2008-05-29 drh: you cloned from or whatever server you most recently synced with. 26a2b61dbd 2008-05-29 drh: </p></li> 26a2b61dbd 2008-05-29 drh: 26a2b61dbd 2008-05-29 drh: <li><p> 26a2b61dbd 2008-05-29 drh: When your coworkers make their own changes, you can merge those changes 26a2b61dbd 2008-05-29 drh: into your local local source tree using the <b>update</b> command. 26a2b61dbd 2008-05-29 drh: In autosync mode, <b>update</b> will first go back to the server you 26a2b61dbd 2008-05-29 drh: cloned from or with which you most recently synced, and pull down all 26a2b61dbd 2008-05-29 drh: recent changes into your local repository. Then it will merge recent 26a2b61dbd 2008-05-29 drh: changes into your local source tree. If you do an <b>update</b> and 26a2b61dbd 2008-05-29 drh: find that it messes something up in your source tree (perhaps a co-worker 26a2b61dbd 2008-05-29 drh: checked in incompatible changes) you can use the <b>undo</b> command 26a2b61dbd 2008-05-29 drh: to back out the changes. 26a2b61dbd 2008-05-29 drh: </p></li> 26a2b61dbd 2008-05-29 drh: 26a2b61dbd 2008-05-29 drh: <li><p> 26a2b61dbd 2008-05-29 drh: Repeat all of the above until you have generated great software. 26a2b61dbd 2008-05-29 drh: </p></li> 26a2b61dbd 2008-05-29 drh: </ol> 26a2b61dbd 2008-05-29 drh: 26a2b61dbd 2008-05-29 drh: <h3>4.2 Non-Autosync Workflow</h3> 26a2b61dbd 2008-05-29 drh: 26a2b61dbd 2008-05-29 drh: <p>When autosync is disabled, the <b>commit</b> command is decoupled from 26a2b61dbd 2008-05-29 drh: <b>push</b> and the <b>update</b> command is decoupled from <b>pull</b>. 26a2b61dbd 2008-05-29 drh: That means you have to do a few extra steps in order to accomplish the 26a2b61dbd 2008-05-29 drh: <b>push</b> and <b>pull</b> tasks manually.</p> 26a2b61dbd 2008-05-29 drh: 26a2b61dbd 2008-05-29 drh: <ol> 26a2b61dbd 2008-05-29 drh: <li><p> 26a2b61dbd 2008-05-29 drh: Establish a local repository using either the <b>new</b> command 26a2b61dbd 2008-05-29 drh: to start a new project, or the <b>clone</b> command to make a clone 26a2b61dbd 2008-05-29 drh: of a repository for an existing project. The default setting for 26a2b61dbd 2008-05-29 drh: a new repository is with autosync on, so you will need to turn it off 26a2b61dbd 2008-05-29 drh: using the <b>setting autosync off</b> command with a <b>-R</b> option 26a2b61dbd 2008-05-29 drh: to specify the repository. 26a2b61dbd 2008-05-29 drh: </p></li> 26a2b61dbd 2008-05-29 drh: 26a2b61dbd 2008-05-29 drh: <li><p> 26a2b61dbd 2008-05-29 drh: Establish one or more source trees by changing your working directory 26a2b61dbd 2008-05-29 drh: to where you want the root of the source tree to be, then issuing 26a2b61dbd 2008-05-29 drh: the <b>open</b> command with the name of the repository file as its 26a2b61dbd 2008-05-29 drh: argument. 26a2b61dbd 2008-05-29 drh: </p></li> 26a2b61dbd 2008-05-29 drh: 26a2b61dbd 2008-05-29 drh: <li><p> 26a2b61dbd 2008-05-29 drh: The <b>open</b> command in the previous step populates your local source 26a2b61dbd 2008-05-29 drh: tree with a copy of the latest baseline. Usually this is what you want. 26a2b61dbd 2008-05-29 drh: In the rare cases where it is not, use the <b>update</b> command to 26a2b61dbd 2008-05-29 drh: switch to a new baseline. Use the <b>timeline</b> or <b>leaves</b> commands 26a2b61dbd 2008-05-29 drh: to identify alternative baselines to switch to. 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: 26a2b61dbd 2008-05-29 drh: <li><p>Use the <b>push</b> command to push your changes out to a server 26a2b61dbd 2008-05-29 drh: where your co-workers can access them. d87ca60c58 2008-05-15 stephan: </p></li> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <li><p> 26a2b61dbd 2008-05-29 drh: When co-workers make their own changes, use the <b>pull</b> command 26a2b61dbd 2008-05-29 drh: to pull those changes into your local repository. Note that <b>pull</b> 26a2b61dbd 2008-05-29 drh: does not move the changes into your local source tree, only into your 26a2b61dbd 2008-05-29 drh: local repository. d87ca60c58 2008-05-15 stephan: </p></li> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <li><p> 26a2b61dbd 2008-05-29 drh: Once changes are in your local repository, use 26a2b61dbd 2008-05-29 drh: use the <b>update</b> command to merge them to your local source tree. 26a2b61dbd 2008-05-29 drh: If you merge in some changes and find that the changes do not work out 26a2b61dbd 2008-05-29 drh: or are not to your liking, you can back out the changes using the 26a2b61dbd 2008-05-29 drh: <b>undo</b> command. 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: <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> 26a2b61dbd 2008-05-29 drh: 26a2b61dbd 2008-05-29 drh: <h2>6.0 Review Of Key Concepts</h2> 26a2b61dbd 2008-05-29 drh: 26a2b61dbd 2008-05-29 drh: <ul> 26a2b61dbd 2008-05-29 drh: <li>The <b>fossil</b> program is a self-contained stand-alone executable. 26a2b61dbd 2008-05-29 drh: Just put it somewhere on your PATH to install it.</li> 26a2b61dbd 2008-05-29 drh: <li>Use the <b>clone</b> or <b>new</b> commands to create a new repository.</li> 26a2b61dbd 2008-05-29 drh: <li>Use the <b>open</b> command to create a new source tree.</li> 26a2b61dbd 2008-05-29 drh: <li>Use the <b>add</b> and <b>rm</b> or <b>delete</b> commands to add and 26a2b61dbd 2008-05-29 drh: remove files from the local source tree.</li> 26a2b61dbd 2008-05-29 drh: <li>Use the <b>commit</b> command to create a new baseline.</li> 26a2b61dbd 2008-05-29 drh: <li>Use the <b>update</b> command to merge in changes from others.</li> 26a2b61dbd 2008-05-29 drh: <li>The <b>push</b> and <b>pull</b> commands can be used to share changes 26a2b61dbd 2008-05-29 drh: manually, but these things happen automatically in the default 26a2b61dbd 2008-05-29 drh: autosync mode.</li> 26a2b61dbd 2008-05-29 drh: </ul>
File Annotation