Overview
| SHA1 Hash: | e319e8e870b1bba78aec44bd732b5e8daf84a8ad |
|---|---|
| Date: | 2007-08-25 03:30:15 |
| User: | drh |
| Comment: | Improvements to timeline formatting. Added the "concepts.html" document. |
| Timelines: | ancestors | descendants | both | trunk |
| Other Links: | files | ZIP archive | manifest |
Tags And Properties
- branch=trunk inherited from [a28c83647d]
- sym-trunk inherited from [a28c83647d]
Changes
[hide diffs]Added art/concept1.dia version [84f4b61b5f]
cannot compute difference between binary files
Added art/concept2.dia version [45f4612209]
cannot compute difference between binary files
Modified src/timeline.c from [4792000fa7] to [f946387177].
@@ -111,12 +111,12 @@
style_header("Timeline");
if( !g.okHistory &&
db_exists("SELECT 1 FROM user"
" WHERE login='anonymous'"
" AND cap LIKE '%%h%%'") ){
- @ <p><b>Note:</b> You will be able to see much more timeline
- @ information if <a href="%s(g.zBaseURL)/login">login</a>.</p>
+ @ <p><b>Note:</b> You will be able to access <u>much</u> more
+ @ historical information if <a href="%s(g.zBaseURL)/login">login</a>.</p>
}
zSQL = mprintf(
"SELECT uuid, datetime(event.mtime,'localtime'), comment, user"
" FROM event, blob"
" WHERE event.type='ci' AND blob.rid=event.objid"
Added www/concept1.gif version [6bb98f69a2]
cannot compute difference between binary files
Added www/concept2.gif version [ff6165d1e9]
cannot compute difference between binary files
Added www/concepts.html version [c70816f44a]
@@ -1,1 +1,340 @@ +<html> +<head> +<title>Fossil Concepts</title> +</head> +<body bgcolor="white"> +<h1 align="center"> +Fossil Concepts +</h1> + +<h2>1.0 Introduction</h2> +<p> +<a href="index.html">Fossil</a> is a +<a href="http://en.wikipedia.org/wiki/Software_configuration_management"> +software configuration management</a> system. +Fossil is software that is design to control and track the +development of a software project and to record the history +of the project. +There are many such systems in use today. Fossil strives to +distinguish itself from the others by being extremely simple +to setup and operate.</p> + +<p>This document is intended as a quick introduction to the concepts +behind fossil.</p> + +<h2>2.0 Composition Of A Project</h2> +<img src="concept1.gif" align="right" hspace="10"> + +<p>A software project normally consists of a "source tree". +A source tree is a hierarchy of files that are used to generate +the end product. The source tree changes over time as the +software grows and expands and as features are added and bugs +are fixed. A snapshot of the source tree at any point in time +is called a "version" or a "baseline" of the product.</p> + +<p>A "repository" is a database that contains copies of all historical +versions or baselines for a project. Baselines are normally stored in the +repository in a highly space-efficient compressed format (delta encoding). +But that is an implementation detail that you the user need not worry over. +Think of the repository as a safe place where all your old baselines +securely stored away and available for retrieval whenever you need +them.</p> + +<p>A repository in fossil is a single file on your disk. This file +might be rather larger (dozens or hundreds of megabytes for a large +or long running project) but it is nevertheless just a file. You +can move it around, rename it, write it out to a memory stick, or +do anything else you normally do with files.</p> + +<p>Each source tree that is controlled by fossil is associated with +a single repository on the local disk drive. You can two or more +source trees tied to a single repository if you want (though one +tree per repository is the most common configuration.) So a +single repository can be associated with many source trees, but +each source tree is associated with only one repository.</p> + +<p>Fossil source tree may not overlap. A fossil source tree is identified +by a file named "_FOSSIL_" in the root directory of the source tree. Every +file that is a sibling of _FOSSIL_ and every file in every subfolder is +considered potentially a part of the source tree. The _FOSSIL_ file +contains (among other things) the pathname of the repository with which +the source tree is associated. On the other hand, the repository has +no record of its source trees. So you are free to delete a source tree +or move it around without consequence. But if you move or rename or +delete a repository, then any source trees associated with that repository +will no longer be able to locate their repository and will stop working.</p> + +<p>When multiple developers are working on the same project, each +developer typically has his or her own local repository and an associated +source tree in which to work. Developers share their work by +"syncing" the content of their local repositories either directly +or through a central server. Changes can "push" from the local +repository into a remote repository. Or changes can "pull" from a +remote repository into a local repository. Or one can do a "sync" +which is shortcut for doing both a push and a pull at the same time. +Fossil also has the concept of "cloning". A "clone" is like a "pull" +except that instead of beginning with an existing local repository, +a clone begins with nothing and creates a new local repository that +is a replicate of a remote repository.</p> + +<p>Communication between repositories is via HTTP. Remote +repositories are identified by URL. You can also point a webbrowser +at a repository and get human-readable status, history, and tracking +information about the project.</p> + +<h3>2.1 Identification Of Artifacts</h3> + +<p>A particular version of a particular file is called an "artifact". +Each artifact has a universally unique name which is the +<a href="http://en.wikipedia.org/wiki/SHA">SHA1</a> hash of the content +of that file expressed as 40 characters of lower-case hexadecimal. Such +such has is referred to as the Universally Unique Identifier or UUID +for the artifact. The SHA1 algorithm is created with the purpose of +provide a highly forgery-resistent identifier for a file. Given any +file it is simple to find the UUID for that file. But given a +UUID it is computationally intractable to generate a file that will +generate that UUID.</p> + + +<p>UUIDs look something like this:</p> + +<blockquote><b> +6089f0b563a9db0a6d90682fe47fd7161ff867c8<br> +59712614a1b3ccfd84078a37fa5b606e28434326<br> +19dbf73078be9779edd6a0156195e610f81c94f9<br> +b4104959a67175f02d6b415480be22a239f1f077<br> +997c9d6ae03ad114b2b57f04e9eeef17dcb82788 +</b></blockquote> + +<p>When referring to an artifact using fossil, you can use a unique +prefix of the UUID that is four characters or longer. This saves +a lot of typing. When displaying UUIDs, fossil will usually only +show the first 10 digits since that is normally enough to uniquely +identify a file.</p> + +<p>Changing (or adding or removing) a single byte in a file results +in a completely different UUID. And since the UUID is the name of +the artifact, making any change to a file results in a new artifact. +In this way, artifacts are immutable.</p> + +<p>A repository is really just an unordered collection of +artifacts. New artifacts can be added to the repository, but +existing artifacts can never be removed. Fossil is designed in +such a way that it can be handed a set of artifacts in any +order and it can figure out the relationship between those +artifacts and reconstruct the complete development history of +a software project.</p> + +<h3>2.2 Manifests</h3> + +<p>At the root of a source tree is a special file called the +"manifest". The manifest is a listing of all other files in +that source tree. The manifest contains the (complete) UUID +of the file and the name of the file as it appears on disk, +and thus serves as a mapping from UUID to disk name. The UUID +of the manifest is the UUID that identifies a baseline. When +you look at a "timeline" of changes in fossil, the UUID associated +with each check-in or commit is really just the UUID of the +manifest for that baseline.</p> + +<p>Fossil automatically generates a manifest whenever you "commit" +a new baseline. So this is not something that you, the developer, +need to worry with. The format of a manifest is intentially +designed to be simple to parse, however, so that if +you want to read and interpret a manifest, either by hand or +with a script, that is easy to do.</p> + +<p>In addition to identifying all files in the baseline, a +manifest also contains a check-in comment, the date and time +when the baseline was established, who created the baseline, +and links to other baselines from which the current baseline +is derived. There is also a couple of checksums used to verify +the integrity of the baseline. And the whole manifest might +be PGP clearsigned.</p> + +<h3>2.3 Key concepts</h3> + +<ul> +<li>A <b>baseline</b> or <b>version</b> is a set of files arranged + in a hierarchy.</li> +<li>A <b>repository</b> keeps a record of historical baselines.</li> +<li>Repositories share their changes using <b>push</b>, <b>pull</b>, + <b>sync</b>, and <b>clone</b>.</li> +<li>A particular version of a particular file is an <b>artifact</b> + that is identified by a <b>UUID</b>.</li> +<li>Artifacts tracked by fossil are inheriently immutable.</li> +<li>Fossil automatically generates a <b>manifest</b> file that identifies + every artifact in a baseline.</li> +<li>The UUID of the manifest is the UUID of the baseline.</li> +</ul> + +<h2>3.0 Fossil - The Program</h2> + +<p>Fossil is software. The implementation of fossil is in the form +of a single executable name "fossil". To install fossil on your system, +all you have to do is obtain a copy of this one executable file (either +by downloading a precompiled version or compiling it yourself) and then +putting that file somewhere on your PATH.</p> + +<p>Fossil is completely self-contained. It is not necessary to +install any other software in order to use fossil. You do <u>not</u> need +CVS, gzip, diff, rsync, Python, Perl, Tcl, Java, apache, PostgreSQL, MySQL, +SQLite, Tcl, patch, or any similar software on your system in order to use +fossil effectively. You will want to have some kind of text editor +for entering check-in comments. Fossil will use whatever text editor +is identified by your VISUAL environment variable. Fossil will also +use GPG to clearsign your manifests if you happen to have it installed, +but fossil will skip that step if you do not have GPG so it is not +essential.</p> + +<p>To uninstall fossil, simply delete the executable.</p> + +<p>To upgrade an older version of fossil to a newer version, just +replace the old executable with the new one. You might need to +run a one-time command to restructure your repositories after +an upgrade. Check the instructions that come with the upgrade +for details.</p> + +<p>To use fossil, simply type the name of executable in your +shell, followed by one of the various built-in commands and +arguments appropriate for that command. For example:</p> + +<blockquote><b> +fossil help +</b></blockquote> + +<p>In the next section, when we say things like "use the <b>help</b> +command" we mean to use the command name "help" as the first +token after the name of the fossil executable, as shown above.</p> + +<h2>4.0 Workflow</h2> + +<img src="concept2.gif" align="right" hspace="10"> +<ol> +<li><p> +Establish a local repository using either the <b>new</b> command +to start a new project, or the <b>clone</b> command to make a clone +of a repository for an existing project. +</p></li> + +<li><p> +Establish one or more source trees by changing your working directory +to where you want the root of the source tree to be, then issuing +the <b>open</b> command with the name of the repository file as its +argument. +</p></li> + +<li><p> +Use the <b>update</b> command followed by a UUID to cause your +source tree to change to the baseline identified by that UUID. +The <b>timeline</b> or <b>leaves</b> commands might help you to +identify an appropriate baseline. +</p></li> + +<li><p> +Edit the code. Add new files to the source tree using the <b>add</b> +command. Omit files from future baselines using the <b>rm</b> command. +(Even when you remove files from future baselines, those files continue +to exist in historical baselines.) Test your changes. +</p></li> + +<li><p> +Create a new baseline using the <b>commit</b> command. You will be prompted +for a check-in comment and also for your GPG key if you have GPG installed. +The commit copies the edits you have made in your local source +tree into your local repository. +</p></li> + +<li><p> +Share your changes with others using the <b>push</b> command. +Push causes the edits you committed into your local repository to be +pushed out into other repositories. +</p></li> + +<li><p> +When your coworkers make their own changes, you can pull those changes +into your local repository using the <b>pull</b> command. Note that +the pull command only pulls the changes into your local repository, +not into your local source tree. +</p></li> + +<li><p> +After the changes of others are in your local repository, you +can move them into your local source tree using <b>update</b>. If +you have made parallel +changes, you can merge your changes together with your coworkers changes +by do an <b>update</b> to your latest baseline, then doing a +<b>merge</b> with your coworkers latest baseline. After your +verify that the merged code is still functional, you can <b>commit</b> +a new baseline that contains both yours and your coworkers changes +and then push the new baseline back to your coworker. +</p></li> + +<li><p> +Repeat all of the above until you have generated great software. +</p></li> +</ol> + +<h2>5.0 Setting Up A Fossil Server</h2> + +<p>With other configuration management software, setting up a server is +a lot of work and normally takes time, patience, and a lot of system +knowledge. Fossil is designed to avoid this frustration. Setting up +a server with fossil is ridiculously easy. You have three options:</p> + +<ol> +<li><p><b>Setting up a stand-alone server</b></p> + +<p>From within your source tree just use the <b>server</b> command and +fossil will start listening for incoming requests on TCP port 8080. +You can point your webbrowser at <a href="http://localhost:8080/"> +http://localhost:8080/</a> and begin exploring. Or your coworkers +can do pushes or pulls against your server. Use the <b>--port</b> +option to the server command to specify a different TCP port. If +you do not have a local source tree, use the <b>-R</b> command-line +option to specify the repository file.</p> + +<p>A stand-alone server is a great way to set of transient connections +between coworkers for doing quick pushes or pulls. But you can also +set up a permanent stand-alone server if you prefer. Just make +arrangements for fossil to be launched with appropriate arguments +after every reboot.</p> +</li> + +<li><p><b>Setting up a CGI server</b></p> + +<p>If you have a webserver running on your machine already, you can +set up fossil to be run from CGI. Simply create an executable script +that looks something like this:</p> + +<blockquote><pre> +#!/usr/local/bin/fossil +repository: /home/me/bigproject.fossil +</pre></blockquote> + +<p>Edit this script to use whatever pathnames are appropriate for +your project. Then point your webbrowser at the script and off you +go.</p></li> + +<li><p><b>Setting up an inetd server</b></p> + +<p>If you have inetd or xinetd running on your system, you can set +those services up to launch fossil to deal with inbound TCP/IP connections +on whatever port you want. Set up inetd or xinetd to launch fossil +like this:</p> + +<blockquote><pre> +/usr/local/bin/fossil http /home/me/bigproject.fossil +</pre></blockquote> +<p>As before, change the filenames to whatever is appropriate for +your system. You can have fossil run as any user that has write +permission on the repository and on the directory that contains the +repository. But it is safer to run fossil as root. When fossil +sees that it is running as root, it automatically puts itself into +a <a href="http://en.wikipedia.org/wiki/Chroot">chroot jail</a> and +drops all privileges prior to reading any information from the client. +Since fossil is a stand-alone program, you do not need to put anything +in the chroot jail with fossil in order for it to do its job.</p> +</li> +</ol>
Modified www/index.html from [d3b58fe572] to [62a56c4597].
@@ -7,13 +7,14 @@ <p> This is a preliminary homepage for a new software configuration management system called "Fossil". The system is -<a href="http://fossil-scm.hwaci.com/fossil/index">self-hosting</a>. +<a href="http://fossil-scm.hwaci.com/fossil/timeline">self-hosting</a> on +<a href="http://www.hwaci.com/cgi-bin/fossil/timeline">two separate servers</a>. You can download the lastest sources -compile it your self using the instructions below. +compile it yourself using the instructions below. </p> <p>Design Goals For Fossil:</p> <ul> @@ -77,10 +78,11 @@ </ul> <p>Other Links:</p> <ul> +<li>The <a href="concepts.html">concepts</b> behind fossil</li> <li><a href="build.html">Building And Installing</a></li> <li><a href="quickstart.html">Quick Start</a> guide to using fossil <li><a href="pop.html">Principals Of Operation</a></li> <li>The <a href="selfcheck.html">automatic self-check</a> mechanism helps insure project integrity.</li>