File Annotation
Not logged in
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
9eb6ea75c1 2008-11-11    kejoki: repositories are identified by URL.  You can also point a web browser
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
e8c4f69c50 2008-10-24       drh: a hash is referred to as the Artifact Identifier or Artifact ID
d87ca60c58 2008-05-15   stephan: for the artifact.  The SHA1 algorithm is created with the purpose of
9eb6ea75c1 2008-11-11    kejoki: providing a highly forgery-resistant identifier for a file.  Given any
e8c4f69c50 2008-10-24       drh: file it is simple to find the artifact ID for that file.  But given a
e8c4f69c50 2008-10-24       drh: artifact ID it is computationally intractable to generate a file that will
e8c4f69c50 2008-10-24       drh: have that Artifact ID.</p>
e8c4f69c50 2008-10-24       drh: 
e8c4f69c50 2008-10-24       drh: 
e8c4f69c50 2008-10-24       drh: <p>Artifact IDs 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
e8c4f69c50 2008-10-24       drh: prefix of the artifact ID that is four characters or longer.  This saves
e8c4f69c50 2008-10-24       drh: a lot of typing.  When displaying artifact IDs, 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
e8c4f69c50 2008-10-24       drh: in a completely different artifact ID.  And since the artifact ID 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
e8c4f69c50 2008-10-24       drh: that source tree.  The manifest contains the (complete) artifact ID
d87ca60c58 2008-05-15   stephan: of the file and the name of the file as it appears on disk,
e8c4f69c50 2008-10-24       drh: and thus serves as a mapping from artifact ID to disk name.  The artifact ID
e8c4f69c50 2008-10-24       drh: of the manifest is the identifier for the entire baseline.  When
e8c4f69c50 2008-10-24       drh: you look at a "timeline" of changes in fossil, the ID associated
e8c4f69c50 2008-10-24       drh: with each check-in or commit is really just the artifact ID 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>
e8c4f69c50 2008-10-24       drh:     that is identified by an <b>artifact ID</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>
e8c4f69c50 2008-10-24       drh: <li>The artifact ID of the manifest is the identifier 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
9eb6ea75c1 2008-11-11    kejoki: by downloading a pre-compiled 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,
bad9999d7d 2008-07-21       drh: though fossil 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.
9eb6ea75c1 2008-11-11    kejoki: You can point your web browser 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
9eb6ea75c1 2008-11-11    kejoki: your project.  Then point your web browser 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>