Fossil SCM
Documentation updates, including a big rework of the homepage.
Commit
522824b26a27a5985f77be163368fc75d2ff06eb
Parent
8e3b7fab9f76ffc…
7 files changed
+1
-2
+127
-112
+1
+1
+68
-43
+39
-28
+1
+1
-2
| --- www/build.wiki | ||
| +++ www/build.wiki | ||
| @@ -1,8 +1,7 @@ | ||
| 1 | -<title>Fossil Documentation</title> | |
| 1 | +<title>Building and Installing Fossil</title> | |
| 2 | 2 | <nowiki> |
| 3 | -<h1>Installing Fossil</h1> | |
| 4 | 3 | |
| 5 | 4 | <p>This page describes how to build and install Fossil. The |
| 6 | 5 | whole process is designed to be very easy.</p> |
| 7 | 6 | |
| 8 | 7 | <h2>0.0 Using A Pre-compiled Binary</h2> |
| 9 | 8 |
| --- www/build.wiki | |
| +++ www/build.wiki | |
| @@ -1,8 +1,7 @@ | |
| 1 | <title>Fossil Documentation</title> |
| 2 | <nowiki> |
| 3 | <h1>Installing Fossil</h1> |
| 4 | |
| 5 | <p>This page describes how to build and install Fossil. The |
| 6 | whole process is designed to be very easy.</p> |
| 7 | |
| 8 | <h2>0.0 Using A Pre-compiled Binary</h2> |
| 9 |
| --- www/build.wiki | |
| +++ www/build.wiki | |
| @@ -1,8 +1,7 @@ | |
| 1 | <title>Building and Installing Fossil</title> |
| 2 | <nowiki> |
| 3 | |
| 4 | <p>This page describes how to build and install Fossil. The |
| 5 | whole process is designed to be very easy.</p> |
| 6 | |
| 7 | <h2>0.0 Using A Pre-compiled Binary</h2> |
| 8 |
+127
-112
| --- www/concepts.wiki | ||
| +++ www/concepts.wiki | ||
| @@ -1,68 +1,66 @@ | ||
| 1 | 1 | <title>Fossil Concepts</title> |
| 2 | -<nowiki> | |
| 3 | 2 | <h1 align="center">Fossil Concepts</h1> |
| 4 | 3 | |
| 5 | 4 | <h2>1.0 Introduction</h2> |
| 6 | -<p> | |
| 7 | -<a href="index.html">Fossil</a> is a | |
| 8 | -<a href="http://en.wikipedia.org/wiki/Software_configuration_management"> | |
| 9 | -software configuration management</a> system. | |
| 5 | + | |
| 6 | +[./index.wiki | Fossil] is a | |
| 7 | +[http://en.wikipedia.org/wiki/Software_configuration_management | software configuration management] system. | |
| 10 | 8 | Fossil is software that is designed to control and track the |
| 11 | 9 | development of a software project and to record the history |
| 12 | 10 | of the project. |
| 13 | 11 | There are many such systems in use today. Fossil strives to |
| 14 | 12 | distinguish itself from the others by being extremely simple |
| 15 | -to setup and operate.</p> | |
| 13 | +to setup and operate. | |
| 16 | 14 | |
| 17 | -<p>This document is intended as a quick introduction to the concepts | |
| 18 | -behind fossil.</p> | |
| 15 | +This document is intended as a quick introduction to the concepts | |
| 16 | +behind fossil. | |
| 19 | 17 | |
| 20 | 18 | <h2>2.0 Composition Of A Project</h2> |
| 21 | 19 | <img src="concept1.gif" align="right" hspace="10"> |
| 22 | 20 | |
| 23 | -<p>A software project normally consists of a "source tree". | |
| 21 | +A software project normally consists of a "source tree". | |
| 24 | 22 | A source tree is a hierarchy of files that are used to generate |
| 25 | 23 | the end product. The source tree changes over time as the |
| 26 | 24 | software grows and expands and as features are added and bugs |
| 27 | 25 | are fixed. A snapshot of the source tree at any point in time |
| 28 | 26 | is called a "version" or "revision" or a "baseline" of the product. |
| 29 | -In fossil, we use the name "check-in".</p> | |
| 27 | +In fossil, we use the name "check-in". | |
| 30 | 28 | |
| 31 | -<p>A "repository" is a database that contains copies of all historical | |
| 29 | +A "repository" is a database that contains copies of all historical | |
| 32 | 30 | check-ins for a project. Check-ins are normally stored in the |
| 33 | 31 | repository in a highly space-efficient compressed format (delta encoding). |
| 34 | 32 | But that is an implementation detail that you the user need not worry over. |
| 35 | 33 | Think of the repository as a safe place where all your old check-ins are |
| 36 | 34 | securely stored away and available for retrieval whenever you need |
| 37 | -them.</p> | |
| 35 | +them. | |
| 38 | 36 | |
| 39 | -<p>A repository in fossil is a single file on your disk. This file | |
| 37 | +A repository in fossil is a single file on your disk. This file | |
| 40 | 38 | might be rather large (dozens or hundreds of megabytes for a large |
| 41 | 39 | or long running project) but it is nevertheless just a file. You |
| 42 | 40 | can move it around, rename it, write it out to a memory stick, or |
| 43 | -do anything else you normally do with files.</p> | |
| 41 | +do anything else you normally do with files. | |
| 44 | 42 | |
| 45 | -<p>Each source tree that is controlled by fossil is associated with | |
| 43 | +Each source tree that is controlled by fossil is associated with | |
| 46 | 44 | a single repository on the local disk drive. You can tie two or more |
| 47 | 45 | source trees to a single repository if you want (though one |
| 48 | 46 | tree per repository is the most common configuration.) So a |
| 49 | 47 | single repository can be associated with many source trees, but |
| 50 | -each source tree is associated with only one repository.</p> | |
| 48 | +each source tree is associated with only one repository. | |
| 51 | 49 | |
| 52 | -<p>Fossil source trees may not overlap. A fossil source tree is identified | |
| 50 | +Fossil source trees may not overlap. A fossil source tree is identified | |
| 53 | 51 | by a file named "_FOSSIL_" in the root directory of the source tree. Every |
| 54 | 52 | file that is a sibling of _FOSSIL_ and every file in every subfolder is |
| 55 | 53 | considered potentially a part of the source tree. The _FOSSIL_ file |
| 56 | 54 | contains (among other things) the pathname of the repository with which |
| 57 | 55 | the source tree is associated. On the other hand, the repository has |
| 58 | 56 | no record of its source trees. So you are free to delete a source tree |
| 59 | 57 | or move it around without consequence. But if you move or rename or |
| 60 | 58 | delete a repository, then any source trees associated with that repository |
| 61 | -will no longer be able to locate their repository and will stop working.</p> | |
| 59 | +will no longer be able to locate their repository and will stop working. | |
| 62 | 60 | |
| 63 | -<p>When multiple developers are working on the same project, each | |
| 61 | +When multiple developers are working on the same project, each | |
| 64 | 62 | developer typically has his or her own local repository and an associated |
| 65 | 63 | source tree in which to work. Developers share their work by |
| 66 | 64 | "syncing" the content of their local repositories either directly |
| 67 | 65 | or through a central server. Changes can "push" from the local |
| 68 | 66 | repository into a remote repository. Or changes can "pull" from a |
| @@ -69,71 +67,74 @@ | ||
| 69 | 67 | remote repository into a local repository. Or one can do a "sync" |
| 70 | 68 | which is a shortcut for doing both a push and a pull at the same time. |
| 71 | 69 | Fossil also has the concept of "cloning". A "clone" is like a "pull", |
| 72 | 70 | except that instead of beginning with an existing local repository, |
| 73 | 71 | a clone begins with nothing and creates a new local repository that |
| 74 | -is a duplicate of a remote repository.</p> | |
| 72 | +is a duplicate of a remote repository. | |
| 75 | 73 | |
| 76 | -<p>Communication between repositories is via HTTP. Remote | |
| 74 | +Communication between repositories is via HTTP. Remote | |
| 77 | 75 | repositories are identified by URL. You can also point a web browser |
| 78 | 76 | at a repository and get human-readable status, history, and tracking |
| 79 | -information about the project.</p> | |
| 77 | +information about the project. | |
| 80 | 78 | |
| 81 | 79 | <h3>2.1 Identification Of Artifacts</h3> |
| 82 | 80 | |
| 83 | -<p>A particular version of a particular file is called an "artifact". | |
| 81 | +A particular version of a particular file is called an "artifact". | |
| 84 | 82 | Each artifact has a universally unique name which is the |
| 85 | 83 | <a href="http://en.wikipedia.org/wiki/SHA">SHA1</a> hash of the content |
| 86 | 84 | of that file expressed as 40 characters of lower-case hexadecimal. Such |
| 87 | 85 | a hash is referred to as the Artifact Identifier or Artifact ID |
| 88 | 86 | for the artifact. The SHA1 algorithm is created with the purpose of |
| 89 | 87 | providing a highly forgery-resistant identifier for a file. Given any |
| 90 | 88 | file it is simple to find the artifact ID for that file. But given a |
| 91 | 89 | artifact ID it is computationally intractable to generate a file that will |
| 92 | -have that Artifact ID.</p> | |
| 90 | +have that Artifact ID. | |
| 93 | 91 | |
| 94 | - | |
| 95 | -<p>Artifact IDs look something like this:</p> | |
| 92 | +Artifact IDs look something like this: | |
| 96 | 93 | |
| 97 | 94 | <blockquote><b> |
| 98 | 95 | 6089f0b563a9db0a6d90682fe47fd7161ff867c8<br> |
| 99 | 96 | 59712614a1b3ccfd84078a37fa5b606e28434326<br> |
| 100 | 97 | 19dbf73078be9779edd6a0156195e610f81c94f9<br> |
| 101 | 98 | b4104959a67175f02d6b415480be22a239f1f077<br> |
| 102 | 99 | 997c9d6ae03ad114b2b57f04e9eeef17dcb82788 |
| 103 | 100 | </b></blockquote> |
| 104 | 101 | |
| 105 | -<p>When referring to an artifact using fossil, you can use a unique | |
| 102 | +When referring to an artifact using fossil, you can use a unique | |
| 106 | 103 | prefix of the artifact ID that is four characters or longer. This saves |
| 107 | 104 | a lot of typing. When displaying artifact IDs, fossil will usually only |
| 108 | 105 | show the first 10 digits since that is normally enough to uniquely |
| 109 | -identify a file.</p> | |
| 106 | +identify a file. | |
| 110 | 107 | |
| 111 | -<p>Changing (or adding or removing) a single byte in a file results | |
| 108 | +Changing (or adding or removing) a single byte in a file results | |
| 112 | 109 | in a completely different artifact ID. And since the artifact ID is the name of |
| 113 | 110 | the artifact, making any change to a file results in a new artifact. |
| 114 | -In this way, artifacts are immutable.</p> | |
| 111 | +In this way, artifacts are immutable. | |
| 115 | 112 | |
| 116 | -<p>A repository is really just an unordered collection of | |
| 113 | +A repository is really just an unordered collection of | |
| 117 | 114 | artifacts. New artifacts can be added to the repository, but |
| 118 | -existing artifacts can never be removed. Fossil is designed in | |
| 115 | +existing artifacts can never be removed. (Well, almost never. There | |
| 116 | +is a [./shunning.wiki | "shunning"] mechanism that allows spam or other | |
| 117 | +inappropriate content to be removed if absolutely necessary, but such | |
| 118 | +removal is discouraged.) | |
| 119 | +Fossil is designed in | |
| 119 | 120 | such a way that it can be handed a set of artifacts in any |
| 120 | 121 | order and it can figure out the relationship between those |
| 121 | 122 | artifacts and reconstruct the complete development history of |
| 122 | -a software project.</p> | |
| 123 | +a software project. | |
| 123 | 124 | |
| 124 | 125 | <h3>2.2 Manifests</h3> |
| 125 | 126 | |
| 126 | -<p>At the root of a source tree is a special file called the | |
| 127 | +At the root of a source tree is a special file called the | |
| 127 | 128 | "manifest". The manifest is a listing of all other files in |
| 128 | 129 | that source tree. The manifest contains the (complete) artifact ID |
| 129 | 130 | of the file and the name of the file as it appears on disk, |
| 130 | 131 | and thus serves as a mapping from artifact ID to disk name. The artifact ID |
| 131 | 132 | of the manifest is the identifier for the entire check-in. When |
| 132 | 133 | you look at a "timeline" of changes in fossil, the ID associated |
| 133 | 134 | with each check-in or commit is really just the artifact ID of the |
| 134 | -manifest for that check-in.</p> | |
| 135 | +manifest for that check-in. | |
| 135 | 136 | |
| 136 | 137 | <p>Fossil automatically generates a manifest whenever you "commit" |
| 137 | 138 | a new check-in. So this is not something that you, the developer, |
| 138 | 139 | need to worry with. The format of a manifest is intentionally |
| 139 | 140 | designed to be simple to parse, so that if |
| @@ -165,17 +166,17 @@ | ||
| 165 | 166 | <li>The artifact ID of the manifest is the identifier of the check-in.</li> |
| 166 | 167 | </ul> |
| 167 | 168 | |
| 168 | 169 | <h2>3.0 Fossil - The Program</h2> |
| 169 | 170 | |
| 170 | -<p>Fossil is software. The implementation of fossil is in the form | |
| 171 | +Fossil is software. The implementation of fossil is in the form | |
| 171 | 172 | of a single executable named "fossil". To install fossil on your system, |
| 172 | 173 | all you have to do is obtain a copy of this one executable file (either |
| 173 | 174 | by downloading a pre-compiled version or compiling it yourself) and then |
| 174 | -putting that file somewhere on your PATH.</p> | |
| 175 | +putting that file somewhere on your PATH. | |
| 175 | 176 | |
| 176 | -<p>Fossil is completely self-contained. It is not necessary to | |
| 177 | +Fossil is completely self-contained. It is not necessary to | |
| 177 | 178 | install any other software in order to use fossil. You do <u>not</u> need |
| 178 | 179 | CVS, gzip, diff, rsync, Python, Perl, Tcl, Java, apache, PostgreSQL, MySQL, |
| 179 | 180 | SQLite, patch, or any similar software on your system in order to use |
| 180 | 181 | fossil effectively. You will want to have some kind of text editor |
| 181 | 182 | for entering check-in comments. Fossil will use whatever text editor |
| @@ -182,252 +183,266 @@ | ||
| 182 | 183 | is identified by your VISUAL environment variable. Fossil will also |
| 183 | 184 | use GPG to clearsign your manifests if you happen to have it installed, |
| 184 | 185 | but fossil will skip that step if GPG missing from your system. |
| 185 | 186 | You can optionally set up fossil to use external "diff" programs, |
| 186 | 187 | though fossil has an excellent built-in "diff" algorithm that works |
| 187 | -fine for most people.</p> | |
| 188 | +fine for most people. | |
| 188 | 189 | |
| 189 | -<p>To uninstall fossil, simply delete the executable.</p> | |
| 190 | +To uninstall fossil, simply delete the executable. | |
| 190 | 191 | |
| 191 | -<p>To upgrade an older version of fossil to a newer version, just | |
| 192 | +To upgrade an older version of fossil to a newer version, just | |
| 192 | 193 | replace the old executable with the new one. You might need to |
| 193 | -run a one-time command to restructure your repositories after | |
| 194 | -an upgrade. Check the instructions that come with the upgrade | |
| 195 | -for details.</p> | |
| 194 | +run "<b>fossil all rebuild</b>" to restructure your repositories after | |
| 195 | +an upgrade. Running "all rebuild" never hurts, so when upgrading it | |
| 196 | +is a good policy to run it even if it is not strictly necessary. | |
| 196 | 197 | |
| 197 | -<p>To use fossil, simply type the name of the executable in your | |
| 198 | +To use fossil, simply type the name of the executable in your | |
| 198 | 199 | shell, followed by one of the various built-in commands and |
| 199 | -arguments appropriate for that command. For example:</p> | |
| 200 | +arguments appropriate for that command. For example: | |
| 200 | 201 | |
| 201 | 202 | <blockquote><b> |
| 202 | 203 | fossil help |
| 203 | 204 | </b></blockquote> |
| 204 | 205 | |
| 205 | -<p>In the next section, when we say things like "use the <b>help</b> | |
| 206 | +In the next section, when we say things like "use the <b>help</b> | |
| 206 | 207 | command" we mean to use the command name "help" as the first |
| 207 | -token after the name of the fossil executable, as shown above.</p> | |
| 208 | +token after the name of the fossil executable, as shown above. | |
| 208 | 209 | |
| 210 | +<a name="workflow"> | |
| 209 | 211 | <h2>4.0 Workflow</h2> |
| 210 | 212 | |
| 211 | 213 | <img src="concept2.gif" align="right" hspace="10"> |
| 212 | 214 | |
| 213 | -<p>Fossil has two modes of operation: "autosync" and "non-autosync". | |
| 214 | -Autosync mode works something like CVS or SVN in that it automatically | |
| 215 | -keeps your work in sync with the central server. Non-autosync is | |
| 216 | -more like GIT or Bitkeeper in that your local repository develops | |
| 217 | -independently of your coworkers and you share your changes manually. | |
| 215 | +Fossil has two modes of operation: <i>"autosync"</i> and | |
| 216 | +<i>"manual-merge"</i> | |
| 217 | +Autosync mode is reminiscent of CVS or SVN in that it automatically | |
| 218 | +keeps your changes in synchronization with your co-workers through | |
| 219 | +the use of a central server. The manual-merge mode is the standard workflow | |
| 220 | +for GIT or Mercurial in that your local repository develops | |
| 221 | +independently of your coworkers and you share and merge your changes manually. | |
| 218 | 222 | An interesting feature of fossil is that it supports both autosync |
| 219 | -and non-autosync work flows.</p> | |
| 223 | +and manual-merge work flows. | |
| 220 | 224 | |
| 221 | -<p>The default setting for fossil is to be in autosync mode. You | |
| 225 | +The default setting for fossil is to be in autosync mode. You | |
| 222 | 226 | can change the autosync setting or check the current autosync |
| 223 | -setting using commands like:</p> | |
| 227 | +setting using commands like: | |
| 224 | 228 | |
| 225 | 229 | <blockquote> |
| 226 | 230 | <b>fossil setting autosync on<br> |
| 227 | 231 | fossil setting autosync off<br> |
| 228 | 232 | <b>fossil settings</b> |
| 229 | 233 | </blockquote> |
| 230 | 234 | |
| 231 | -<p>By default, fossil runs with autosync mode turned on. The | |
| 232 | -authors find that projects run more smoothly when autosync is only | |
| 233 | -disabled when off-network.</p> | |
| 235 | +By default, fossil runs with autosync mode turned on. The | |
| 236 | +authors finds that projects run more smoothly in autosync mode since | |
| 237 | +autosync helps to prevent pointless forking and merge and helps keeps | |
| 238 | +all collaborators working on exactly the same code rather than on their | |
| 239 | +own personal forks of the code. In the author's view, manual-merge mode | |
| 240 | +should be reserved for disconnected operation. | |
| 234 | 241 | |
| 235 | 242 | <h3>4.1 Autosync Workflow</h3> |
| 236 | 243 | |
| 237 | 244 | <ol> |
| 238 | -<li><p> | |
| 245 | +<li> | |
| 239 | 246 | Establish a local repository using either the <b>new</b> command |
| 240 | 247 | to start a new project, or the <b>clone</b> command to make a clone |
| 241 | 248 | of a repository for an existing project. |
| 242 | -</p></li> | |
| 249 | +</li> | |
| 243 | 250 | |
| 244 | -<li><p> | |
| 251 | +<li> | |
| 245 | 252 | Establish one or more source trees by changing your working directory |
| 246 | 253 | to where you want the root of the source tree to be, then issuing |
| 247 | 254 | the <b>open</b> command with the name of the repository file as its |
| 248 | 255 | argument. |
| 249 | -</p></li> | |
| 256 | +</li> | |
| 250 | 257 | |
| 251 | -<li><p> | |
| 258 | +<li> | |
| 252 | 259 | The <b>open</b> command in the previous step populates your local source |
| 253 | 260 | tree with a copy of the latest check-in. Usually this is what you want. |
| 254 | 261 | In the rare cases where it is not, use the <b>update</b> command to |
| 255 | 262 | switch to a new check-in. Use the <b>timeline</b> or <b>leaves</b> commands |
| 256 | 263 | to identify alternative check-ins to switch to. |
| 257 | -</p></li> | |
| 264 | +</li> | |
| 258 | 265 | |
| 259 | -<li><p> | |
| 266 | +<li> | |
| 260 | 267 | Edit the code. Add new files to the source tree using the <b>add</b> |
| 261 | 268 | command. Omit files from future check-ins using the <b>rm</b> command. |
| 262 | 269 | (Even when you remove files from future check-ins, those files continue |
| 263 | 270 | to exist in historical check-ins.) Test your changes. |
| 264 | -</p></li> | |
| 271 | +</li> | |
| 265 | 272 | |
| 266 | -<li><p> | |
| 273 | +<li> | |
| 267 | 274 | Create a new check-in using the <b>commit</b> command. You will be prompted |
| 268 | 275 | for a check-in comment and also for your GPG key if you have GPG installed. |
| 269 | 276 | The commit copies the edits you have made in your local source |
| 270 | 277 | tree into your local repository. After your commit completes, fossil will |
| 271 | 278 | automatically <b>push</b> your changes back to the server |
| 272 | 279 | you cloned from or whatever server you most recently synced with. |
| 273 | -</p></li> | |
| 280 | +</li> | |
| 274 | 281 | |
| 275 | -<li><p> | |
| 282 | +<li> | |
| 276 | 283 | When your coworkers make their own changes, you can merge those changes |
| 277 | 284 | into your local local source tree using the <b>update</b> command. |
| 278 | 285 | In autosync mode, <b>update</b> will first go back to the server you |
| 279 | 286 | cloned from or with which you most recently synced, and pull down all |
| 280 | 287 | recent changes into your local repository. Then it will merge recent |
| 281 | 288 | changes into your local source tree. If you do an <b>update</b> and |
| 282 | 289 | find that it messes something up in your source tree (perhaps a co-worker |
| 283 | 290 | checked in incompatible changes) you can use the <b>undo</b> command |
| 284 | 291 | to back out the changes. |
| 285 | -</p></li> | |
| 292 | +</li> | |
| 286 | 293 | |
| 287 | -<li><p> | |
| 294 | +<li> | |
| 288 | 295 | Repeat all of the above until you have generated great software. |
| 289 | -</p></li> | |
| 296 | +</li> | |
| 290 | 297 | </ol> |
| 291 | 298 | |
| 292 | -<h3>4.2 Non-Autosync Workflow</h3> | |
| 299 | +<h3>4.2 Manual-Merge Workflow</h3> | |
| 293 | 300 | |
| 294 | -<p>When autosync is disabled, the <b>commit</b> command is decoupled from | |
| 301 | +When autosync is disabled, the <b>commit</b> command is decoupled from | |
| 295 | 302 | <b>push</b> and the <b>update</b> command is decoupled from <b>pull</b>. |
| 296 | 303 | That means you have to do a few extra steps in order to accomplish the |
| 297 | -<b>push</b> and <b>pull</b> tasks manually.</p> | |
| 304 | +<b>push</b> and <b>pull</b> tasks manually. | |
| 298 | 305 | |
| 299 | 306 | <ol> |
| 300 | -<li><p> | |
| 307 | +<li> | |
| 301 | 308 | Establish a local repository using either the <b>new</b> command |
| 302 | 309 | to start a new project, or the <b>clone</b> command to make a clone |
| 303 | 310 | of a repository for an existing project. The default setting for |
| 304 | 311 | a new repository is with autosync on, so you will need to turn it off |
| 305 | 312 | using the <b>setting autosync off</b> command with a <b>-R</b> option |
| 306 | 313 | to specify the repository. |
| 307 | -</p></li> | |
| 314 | +</li> | |
| 308 | 315 | |
| 309 | -<li><p> | |
| 316 | +<li> | |
| 310 | 317 | Establish one or more source trees by changing your working directory |
| 311 | 318 | to where you want the root of the source tree to be, then issuing |
| 312 | 319 | the <b>open</b> command with the name of the repository file as its |
| 313 | 320 | argument. |
| 314 | -</p></li> | |
| 321 | +</li> | |
| 315 | 322 | |
| 316 | -<li><p> | |
| 323 | +<li> | |
| 317 | 324 | The <b>open</b> command in the previous step populates your local source |
| 318 | 325 | tree with a copy of the latest check-in. Usually this is what you want. |
| 319 | 326 | In the rare cases where it is not, use the <b>update</b> command to |
| 320 | 327 | switch to a new check-in. Use the <b>timeline</b> or <b>leaves</b> commands |
| 321 | 328 | to identify alternative check-ins to switch to. |
| 322 | -</p></li> | |
| 329 | +</li> | |
| 323 | 330 | |
| 324 | -<li><p> | |
| 331 | +<li> | |
| 325 | 332 | Edit the code. Add new files to the source tree using the <b>add</b> |
| 326 | 333 | command. Omit files from future check-ins using the <b>rm</b> command. |
| 327 | 334 | (Even when you remove files from future check-ins, those files continue |
| 328 | 335 | to exist in historical check-ins.) Test your changes. |
| 329 | -</p></li> | |
| 336 | +</li> | |
| 330 | 337 | |
| 331 | -<li><p> | |
| 338 | +<li> | |
| 332 | 339 | Create a new check-in using the <b>commit</b> command. You will be prompted |
| 333 | 340 | for a check-in comment and also for your GPG key if you have GPG installed. |
| 334 | 341 | The commit copies the edits you have made in your local source |
| 335 | 342 | tree into your local repository. |
| 336 | -</p></li> | |
| 343 | +</li> | |
| 337 | 344 | |
| 338 | -<li><p>Use the <b>push</b> command to push your changes out to a server | |
| 345 | +<li> | |
| 346 | +Use the <b>push</b> command to push your changes out to a server | |
| 339 | 347 | where your co-workers can access them. |
| 340 | -</p></li> | |
| 348 | +</li> | |
| 341 | 349 | |
| 342 | -<li><p> | |
| 350 | +<li> | |
| 343 | 351 | When co-workers make their own changes, use the <b>pull</b> command |
| 344 | 352 | to pull those changes into your local repository. Note that <b>pull</b> |
| 345 | 353 | does not move the changes into your local source tree, only into your |
| 346 | 354 | local repository. |
| 347 | -</p></li> | |
| 355 | +</li> | |
| 348 | 356 | |
| 349 | -<li><p> | |
| 357 | +<li> | |
| 350 | 358 | Once changes are in your local repository, use |
| 351 | 359 | use the <b>update</b> command to merge them to your local source tree. |
| 352 | 360 | If you merge in some changes and find that the changes do not work out |
| 353 | 361 | or are not to your liking, you can back out the changes using the |
| 354 | 362 | <b>undo</b> command. |
| 355 | -</p></li> | |
| 363 | +</li> | |
| 364 | + | |
| 365 | +<li> | |
| 366 | +If two or more people ran "commit" against the same baseline, this will | |
| 367 | +result in a [./branching.wiki | fork] which you may want to resolve by | |
| 368 | +running <b>merge</b> followed by another <b>commit</b>. | |
| 369 | +</li> | |
| 356 | 370 | |
| 357 | -<li><p> | |
| 371 | +<li> | |
| 358 | 372 | Repeat all of the above until you have generated great software. |
| 359 | -</p></li> | |
| 373 | +</li> | |
| 360 | 374 | </ol> |
| 361 | 375 | |
| 362 | 376 | <h2>5.0 Setting Up A Fossil Server</h2> |
| 363 | 377 | |
| 364 | -<p>With other configuration management software, setting up a server is | |
| 378 | +With other configuration management software, setting up a server is | |
| 365 | 379 | a lot of work and normally takes time, patience, and a lot of system |
| 366 | 380 | knowledge. Fossil is designed to avoid this frustration. Setting up |
| 367 | 381 | a server with fossil is ridiculously easy. You have three options:</p> |
| 368 | 382 | |
| 369 | 383 | <ol> |
| 370 | -<li><p><b><a name="saserv">S</a>etting up a stand-alone server</b></p> | |
| 384 | +<li><b><a name="saserv">S</a>etting up a stand-alone server</b> | |
| 371 | 385 | |
| 372 | -<p>From within your source tree just use the <b>server</b> command and | |
| 386 | +From within your source tree just use the <b>server</b> command and | |
| 373 | 387 | fossil will start listening for incoming requests on TCP port 8080. |
| 374 | 388 | You can point your web browser at <a href="http://localhost:8080/"> |
| 375 | 389 | http://localhost:8080/</a> and begin exploring. Or your coworkers |
| 376 | 390 | can do pushes or pulls against your server. Use the <b>--port</b> |
| 377 | 391 | option to the server command to specify a different TCP port. If |
| 378 | 392 | you do not have a local source tree, use the <b>-R</b> command-line |
| 379 | -option to specify the repository file.</p> | |
| 393 | +option to specify the repository file. | |
| 380 | 394 | |
| 381 | -<p>A stand-alone server is a great way to set of transient connections | |
| 395 | +A stand-alone server is a great way to set of transient connections | |
| 382 | 396 | between coworkers for doing quick pushes or pulls. But you can also |
| 383 | 397 | set up a permanent stand-alone server if you prefer. Just make |
| 384 | 398 | arrangements for fossil to be launched with appropriate arguments |
| 385 | -after every reboot.</p> | |
| 399 | +after every reboot. | |
| 386 | 400 | |
| 387 | -<p>If you just want a server to browse the built-in fossil website | |
| 401 | +If you just want a server to browse the built-in fossil website | |
| 388 | 402 | locally, use the <b>ui</b> command in place of <b>server</b>. The |
| 389 | 403 | <b>ui</b> command starts up a local server too, but it also takes |
| 390 | 404 | the additional step of automatically launching your webbrowser and |
| 391 | -pointing at the new server.</p> | |
| 405 | +pointing at the new server. | |
| 392 | 406 | </li> |
| 393 | 407 | |
| 394 | -<li><p><b>Setting up a CGI server</b></p> | |
| 408 | +<li><b>Setting up a CGI server</b> | |
| 395 | 409 | |
| 396 | -<p>If you have a webserver running on your machine already, you can | |
| 410 | +If you have a web-server running on your machine already, you can | |
| 397 | 411 | set up fossil to be run from CGI. Simply create an executable script |
| 398 | -that looks something like this:</p> | |
| 412 | +that looks something like this: | |
| 399 | 413 | |
| 400 | 414 | <blockquote><pre> |
| 401 | 415 | #!/usr/local/bin/fossil |
| 402 | 416 | repository: /home/me/bigproject.fossil |
| 403 | 417 | </pre></blockquote> |
| 404 | 418 | |
| 405 | -<p>Edit this script to use whatever pathnames are appropriate for | |
| 419 | +Edit this script to use whatever pathnames are appropriate for | |
| 406 | 420 | your project. Then point your web browser at the script and off you |
| 407 | -go.</p></li> | |
| 421 | +go. The [./selfhost.wiki | self-hosting fossil repositories] are | |
| 422 | +all set up this way.</li> | |
| 408 | 423 | |
| 409 | -<li><p><b>Setting up an inetd server</b></p> | |
| 424 | +<li><b>Setting up an inetd server</b> | |
| 410 | 425 | |
| 411 | -<p>If you have inetd or xinetd running on your system, you can set | |
| 426 | +If you have inetd or xinetd running on your system, you can set | |
| 412 | 427 | those services up to launch fossil to deal with inbound TCP/IP connections |
| 413 | 428 | on whatever port you want. Set up inetd or xinetd to launch fossil |
| 414 | -like this:</p> | |
| 429 | +like this: | |
| 415 | 430 | |
| 416 | 431 | <blockquote><pre> |
| 417 | 432 | /usr/local/bin/fossil http /home/me/bigproject.fossil |
| 418 | 433 | </pre></blockquote> |
| 419 | 434 | |
| 420 | -<p>As before, change the filenames to whatever is appropriate for | |
| 435 | +As before, change the filenames to whatever is appropriate for | |
| 421 | 436 | your system. You can have fossil run as any user that has write |
| 422 | 437 | permission on the repository and on the directory that contains the |
| 423 | 438 | repository. But it is safer to run fossil as root. When fossil |
| 424 | 439 | sees that it is running as root, it automatically puts itself into |
| 425 | 440 | a <a href="http://en.wikipedia.org/wiki/Chroot">chroot jail</a> and |
| 426 | 441 | drops all privileges prior to reading any information from the client. |
| 427 | 442 | Since fossil is a stand-alone program, you do not need to put anything |
| 428 | -in the chroot jail with fossil in order for it to do its job.</p> | |
| 443 | +in the chroot jail with fossil in order for it to do its job. | |
| 429 | 444 | </li> |
| 430 | 445 | </ol> |
| 431 | 446 | |
| 432 | 447 | <h2>6.0 Review Of Key Concepts</h2> |
| 433 | 448 | |
| 434 | 449 |
| --- www/concepts.wiki | |
| +++ www/concepts.wiki | |
| @@ -1,68 +1,66 @@ | |
| 1 | <title>Fossil Concepts</title> |
| 2 | <nowiki> |
| 3 | <h1 align="center">Fossil Concepts</h1> |
| 4 | |
| 5 | <h2>1.0 Introduction</h2> |
| 6 | <p> |
| 7 | <a href="index.html">Fossil</a> is a |
| 8 | <a href="http://en.wikipedia.org/wiki/Software_configuration_management"> |
| 9 | software configuration management</a> system. |
| 10 | Fossil is software that is designed to control and track the |
| 11 | development of a software project and to record the history |
| 12 | of the project. |
| 13 | There are many such systems in use today. Fossil strives to |
| 14 | distinguish itself from the others by being extremely simple |
| 15 | to setup and operate.</p> |
| 16 | |
| 17 | <p>This document is intended as a quick introduction to the concepts |
| 18 | behind fossil.</p> |
| 19 | |
| 20 | <h2>2.0 Composition Of A Project</h2> |
| 21 | <img src="concept1.gif" align="right" hspace="10"> |
| 22 | |
| 23 | <p>A software project normally consists of a "source tree". |
| 24 | A source tree is a hierarchy of files that are used to generate |
| 25 | the end product. The source tree changes over time as the |
| 26 | software grows and expands and as features are added and bugs |
| 27 | are fixed. A snapshot of the source tree at any point in time |
| 28 | is called a "version" or "revision" or a "baseline" of the product. |
| 29 | In fossil, we use the name "check-in".</p> |
| 30 | |
| 31 | <p>A "repository" is a database that contains copies of all historical |
| 32 | check-ins for a project. Check-ins are normally stored in the |
| 33 | repository in a highly space-efficient compressed format (delta encoding). |
| 34 | But that is an implementation detail that you the user need not worry over. |
| 35 | Think of the repository as a safe place where all your old check-ins are |
| 36 | securely stored away and available for retrieval whenever you need |
| 37 | them.</p> |
| 38 | |
| 39 | <p>A repository in fossil is a single file on your disk. This file |
| 40 | might be rather large (dozens or hundreds of megabytes for a large |
| 41 | or long running project) but it is nevertheless just a file. You |
| 42 | can move it around, rename it, write it out to a memory stick, or |
| 43 | do anything else you normally do with files.</p> |
| 44 | |
| 45 | <p>Each source tree that is controlled by fossil is associated with |
| 46 | a single repository on the local disk drive. You can tie two or more |
| 47 | source trees to a single repository if you want (though one |
| 48 | tree per repository is the most common configuration.) So a |
| 49 | single repository can be associated with many source trees, but |
| 50 | each source tree is associated with only one repository.</p> |
| 51 | |
| 52 | <p>Fossil source trees may not overlap. A fossil source tree is identified |
| 53 | by a file named "_FOSSIL_" in the root directory of the source tree. Every |
| 54 | file that is a sibling of _FOSSIL_ and every file in every subfolder is |
| 55 | considered potentially a part of the source tree. The _FOSSIL_ file |
| 56 | contains (among other things) the pathname of the repository with which |
| 57 | the source tree is associated. On the other hand, the repository has |
| 58 | no record of its source trees. So you are free to delete a source tree |
| 59 | or move it around without consequence. But if you move or rename or |
| 60 | delete a repository, then any source trees associated with that repository |
| 61 | will no longer be able to locate their repository and will stop working.</p> |
| 62 | |
| 63 | <p>When multiple developers are working on the same project, each |
| 64 | developer typically has his or her own local repository and an associated |
| 65 | source tree in which to work. Developers share their work by |
| 66 | "syncing" the content of their local repositories either directly |
| 67 | or through a central server. Changes can "push" from the local |
| 68 | repository into a remote repository. Or changes can "pull" from a |
| @@ -69,71 +67,74 @@ | |
| 69 | remote repository into a local repository. Or one can do a "sync" |
| 70 | which is a shortcut for doing both a push and a pull at the same time. |
| 71 | Fossil also has the concept of "cloning". A "clone" is like a "pull", |
| 72 | except that instead of beginning with an existing local repository, |
| 73 | a clone begins with nothing and creates a new local repository that |
| 74 | is a duplicate of a remote repository.</p> |
| 75 | |
| 76 | <p>Communication between repositories is via HTTP. Remote |
| 77 | repositories are identified by URL. You can also point a web browser |
| 78 | at a repository and get human-readable status, history, and tracking |
| 79 | information about the project.</p> |
| 80 | |
| 81 | <h3>2.1 Identification Of Artifacts</h3> |
| 82 | |
| 83 | <p>A particular version of a particular file is called an "artifact". |
| 84 | Each artifact has a universally unique name which is the |
| 85 | <a href="http://en.wikipedia.org/wiki/SHA">SHA1</a> hash of the content |
| 86 | of that file expressed as 40 characters of lower-case hexadecimal. Such |
| 87 | a hash is referred to as the Artifact Identifier or Artifact ID |
| 88 | for the artifact. The SHA1 algorithm is created with the purpose of |
| 89 | providing a highly forgery-resistant identifier for a file. Given any |
| 90 | file it is simple to find the artifact ID for that file. But given a |
| 91 | artifact ID it is computationally intractable to generate a file that will |
| 92 | have that Artifact ID.</p> |
| 93 | |
| 94 | |
| 95 | <p>Artifact IDs look something like this:</p> |
| 96 | |
| 97 | <blockquote><b> |
| 98 | 6089f0b563a9db0a6d90682fe47fd7161ff867c8<br> |
| 99 | 59712614a1b3ccfd84078a37fa5b606e28434326<br> |
| 100 | 19dbf73078be9779edd6a0156195e610f81c94f9<br> |
| 101 | b4104959a67175f02d6b415480be22a239f1f077<br> |
| 102 | 997c9d6ae03ad114b2b57f04e9eeef17dcb82788 |
| 103 | </b></blockquote> |
| 104 | |
| 105 | <p>When referring to an artifact using fossil, you can use a unique |
| 106 | prefix of the artifact ID that is four characters or longer. This saves |
| 107 | a lot of typing. When displaying artifact IDs, fossil will usually only |
| 108 | show the first 10 digits since that is normally enough to uniquely |
| 109 | identify a file.</p> |
| 110 | |
| 111 | <p>Changing (or adding or removing) a single byte in a file results |
| 112 | in a completely different artifact ID. And since the artifact ID is the name of |
| 113 | the artifact, making any change to a file results in a new artifact. |
| 114 | In this way, artifacts are immutable.</p> |
| 115 | |
| 116 | <p>A repository is really just an unordered collection of |
| 117 | artifacts. New artifacts can be added to the repository, but |
| 118 | existing artifacts can never be removed. Fossil is designed in |
| 119 | such a way that it can be handed a set of artifacts in any |
| 120 | order and it can figure out the relationship between those |
| 121 | artifacts and reconstruct the complete development history of |
| 122 | a software project.</p> |
| 123 | |
| 124 | <h3>2.2 Manifests</h3> |
| 125 | |
| 126 | <p>At the root of a source tree is a special file called the |
| 127 | "manifest". The manifest is a listing of all other files in |
| 128 | that source tree. The manifest contains the (complete) artifact ID |
| 129 | of the file and the name of the file as it appears on disk, |
| 130 | and thus serves as a mapping from artifact ID to disk name. The artifact ID |
| 131 | of the manifest is the identifier for the entire check-in. When |
| 132 | you look at a "timeline" of changes in fossil, the ID associated |
| 133 | with each check-in or commit is really just the artifact ID of the |
| 134 | manifest for that check-in.</p> |
| 135 | |
| 136 | <p>Fossil automatically generates a manifest whenever you "commit" |
| 137 | a new check-in. So this is not something that you, the developer, |
| 138 | need to worry with. The format of a manifest is intentionally |
| 139 | designed to be simple to parse, so that if |
| @@ -165,17 +166,17 @@ | |
| 165 | <li>The artifact ID of the manifest is the identifier of the check-in.</li> |
| 166 | </ul> |
| 167 | |
| 168 | <h2>3.0 Fossil - The Program</h2> |
| 169 | |
| 170 | <p>Fossil is software. The implementation of fossil is in the form |
| 171 | of a single executable named "fossil". To install fossil on your system, |
| 172 | all you have to do is obtain a copy of this one executable file (either |
| 173 | by downloading a pre-compiled version or compiling it yourself) and then |
| 174 | putting that file somewhere on your PATH.</p> |
| 175 | |
| 176 | <p>Fossil is completely self-contained. It is not necessary to |
| 177 | install any other software in order to use fossil. You do <u>not</u> need |
| 178 | CVS, gzip, diff, rsync, Python, Perl, Tcl, Java, apache, PostgreSQL, MySQL, |
| 179 | SQLite, patch, or any similar software on your system in order to use |
| 180 | fossil effectively. You will want to have some kind of text editor |
| 181 | for entering check-in comments. Fossil will use whatever text editor |
| @@ -182,252 +183,266 @@ | |
| 182 | is identified by your VISUAL environment variable. Fossil will also |
| 183 | use GPG to clearsign your manifests if you happen to have it installed, |
| 184 | but fossil will skip that step if GPG missing from your system. |
| 185 | You can optionally set up fossil to use external "diff" programs, |
| 186 | though fossil has an excellent built-in "diff" algorithm that works |
| 187 | fine for most people.</p> |
| 188 | |
| 189 | <p>To uninstall fossil, simply delete the executable.</p> |
| 190 | |
| 191 | <p>To upgrade an older version of fossil to a newer version, just |
| 192 | replace the old executable with the new one. You might need to |
| 193 | run a one-time command to restructure your repositories after |
| 194 | an upgrade. Check the instructions that come with the upgrade |
| 195 | for details.</p> |
| 196 | |
| 197 | <p>To use fossil, simply type the name of the executable in your |
| 198 | shell, followed by one of the various built-in commands and |
| 199 | arguments appropriate for that command. For example:</p> |
| 200 | |
| 201 | <blockquote><b> |
| 202 | fossil help |
| 203 | </b></blockquote> |
| 204 | |
| 205 | <p>In the next section, when we say things like "use the <b>help</b> |
| 206 | command" we mean to use the command name "help" as the first |
| 207 | token after the name of the fossil executable, as shown above.</p> |
| 208 | |
| 209 | <h2>4.0 Workflow</h2> |
| 210 | |
| 211 | <img src="concept2.gif" align="right" hspace="10"> |
| 212 | |
| 213 | <p>Fossil has two modes of operation: "autosync" and "non-autosync". |
| 214 | Autosync mode works something like CVS or SVN in that it automatically |
| 215 | keeps your work in sync with the central server. Non-autosync is |
| 216 | more like GIT or Bitkeeper in that your local repository develops |
| 217 | independently of your coworkers and you share your changes manually. |
| 218 | An interesting feature of fossil is that it supports both autosync |
| 219 | and non-autosync work flows.</p> |
| 220 | |
| 221 | <p>The default setting for fossil is to be in autosync mode. You |
| 222 | can change the autosync setting or check the current autosync |
| 223 | setting using commands like:</p> |
| 224 | |
| 225 | <blockquote> |
| 226 | <b>fossil setting autosync on<br> |
| 227 | fossil setting autosync off<br> |
| 228 | <b>fossil settings</b> |
| 229 | </blockquote> |
| 230 | |
| 231 | <p>By default, fossil runs with autosync mode turned on. The |
| 232 | authors find that projects run more smoothly when autosync is only |
| 233 | disabled when off-network.</p> |
| 234 | |
| 235 | <h3>4.1 Autosync Workflow</h3> |
| 236 | |
| 237 | <ol> |
| 238 | <li><p> |
| 239 | Establish a local repository using either the <b>new</b> command |
| 240 | to start a new project, or the <b>clone</b> command to make a clone |
| 241 | of a repository for an existing project. |
| 242 | </p></li> |
| 243 | |
| 244 | <li><p> |
| 245 | Establish one or more source trees by changing your working directory |
| 246 | to where you want the root of the source tree to be, then issuing |
| 247 | the <b>open</b> command with the name of the repository file as its |
| 248 | argument. |
| 249 | </p></li> |
| 250 | |
| 251 | <li><p> |
| 252 | The <b>open</b> command in the previous step populates your local source |
| 253 | tree with a copy of the latest check-in. Usually this is what you want. |
| 254 | In the rare cases where it is not, use the <b>update</b> command to |
| 255 | switch to a new check-in. Use the <b>timeline</b> or <b>leaves</b> commands |
| 256 | to identify alternative check-ins to switch to. |
| 257 | </p></li> |
| 258 | |
| 259 | <li><p> |
| 260 | Edit the code. Add new files to the source tree using the <b>add</b> |
| 261 | command. Omit files from future check-ins using the <b>rm</b> command. |
| 262 | (Even when you remove files from future check-ins, those files continue |
| 263 | to exist in historical check-ins.) Test your changes. |
| 264 | </p></li> |
| 265 | |
| 266 | <li><p> |
| 267 | Create a new check-in using the <b>commit</b> command. You will be prompted |
| 268 | for a check-in comment and also for your GPG key if you have GPG installed. |
| 269 | The commit copies the edits you have made in your local source |
| 270 | tree into your local repository. After your commit completes, fossil will |
| 271 | automatically <b>push</b> your changes back to the server |
| 272 | you cloned from or whatever server you most recently synced with. |
| 273 | </p></li> |
| 274 | |
| 275 | <li><p> |
| 276 | When your coworkers make their own changes, you can merge those changes |
| 277 | into your local local source tree using the <b>update</b> command. |
| 278 | In autosync mode, <b>update</b> will first go back to the server you |
| 279 | cloned from or with which you most recently synced, and pull down all |
| 280 | recent changes into your local repository. Then it will merge recent |
| 281 | changes into your local source tree. If you do an <b>update</b> and |
| 282 | find that it messes something up in your source tree (perhaps a co-worker |
| 283 | checked in incompatible changes) you can use the <b>undo</b> command |
| 284 | to back out the changes. |
| 285 | </p></li> |
| 286 | |
| 287 | <li><p> |
| 288 | Repeat all of the above until you have generated great software. |
| 289 | </p></li> |
| 290 | </ol> |
| 291 | |
| 292 | <h3>4.2 Non-Autosync Workflow</h3> |
| 293 | |
| 294 | <p>When autosync is disabled, the <b>commit</b> command is decoupled from |
| 295 | <b>push</b> and the <b>update</b> command is decoupled from <b>pull</b>. |
| 296 | That means you have to do a few extra steps in order to accomplish the |
| 297 | <b>push</b> and <b>pull</b> tasks manually.</p> |
| 298 | |
| 299 | <ol> |
| 300 | <li><p> |
| 301 | Establish a local repository using either the <b>new</b> command |
| 302 | to start a new project, or the <b>clone</b> command to make a clone |
| 303 | of a repository for an existing project. The default setting for |
| 304 | a new repository is with autosync on, so you will need to turn it off |
| 305 | using the <b>setting autosync off</b> command with a <b>-R</b> option |
| 306 | to specify the repository. |
| 307 | </p></li> |
| 308 | |
| 309 | <li><p> |
| 310 | Establish one or more source trees by changing your working directory |
| 311 | to where you want the root of the source tree to be, then issuing |
| 312 | the <b>open</b> command with the name of the repository file as its |
| 313 | argument. |
| 314 | </p></li> |
| 315 | |
| 316 | <li><p> |
| 317 | The <b>open</b> command in the previous step populates your local source |
| 318 | tree with a copy of the latest check-in. Usually this is what you want. |
| 319 | In the rare cases where it is not, use the <b>update</b> command to |
| 320 | switch to a new check-in. Use the <b>timeline</b> or <b>leaves</b> commands |
| 321 | to identify alternative check-ins to switch to. |
| 322 | </p></li> |
| 323 | |
| 324 | <li><p> |
| 325 | Edit the code. Add new files to the source tree using the <b>add</b> |
| 326 | command. Omit files from future check-ins using the <b>rm</b> command. |
| 327 | (Even when you remove files from future check-ins, those files continue |
| 328 | to exist in historical check-ins.) Test your changes. |
| 329 | </p></li> |
| 330 | |
| 331 | <li><p> |
| 332 | Create a new check-in using the <b>commit</b> command. You will be prompted |
| 333 | for a check-in comment and also for your GPG key if you have GPG installed. |
| 334 | The commit copies the edits you have made in your local source |
| 335 | tree into your local repository. |
| 336 | </p></li> |
| 337 | |
| 338 | <li><p>Use the <b>push</b> command to push your changes out to a server |
| 339 | where your co-workers can access them. |
| 340 | </p></li> |
| 341 | |
| 342 | <li><p> |
| 343 | When co-workers make their own changes, use the <b>pull</b> command |
| 344 | to pull those changes into your local repository. Note that <b>pull</b> |
| 345 | does not move the changes into your local source tree, only into your |
| 346 | local repository. |
| 347 | </p></li> |
| 348 | |
| 349 | <li><p> |
| 350 | Once changes are in your local repository, use |
| 351 | use the <b>update</b> command to merge them to your local source tree. |
| 352 | If you merge in some changes and find that the changes do not work out |
| 353 | or are not to your liking, you can back out the changes using the |
| 354 | <b>undo</b> command. |
| 355 | </p></li> |
| 356 | |
| 357 | <li><p> |
| 358 | Repeat all of the above until you have generated great software. |
| 359 | </p></li> |
| 360 | </ol> |
| 361 | |
| 362 | <h2>5.0 Setting Up A Fossil Server</h2> |
| 363 | |
| 364 | <p>With other configuration management software, setting up a server is |
| 365 | a lot of work and normally takes time, patience, and a lot of system |
| 366 | knowledge. Fossil is designed to avoid this frustration. Setting up |
| 367 | a server with fossil is ridiculously easy. You have three options:</p> |
| 368 | |
| 369 | <ol> |
| 370 | <li><p><b><a name="saserv">S</a>etting up a stand-alone server</b></p> |
| 371 | |
| 372 | <p>From within your source tree just use the <b>server</b> command and |
| 373 | fossil will start listening for incoming requests on TCP port 8080. |
| 374 | You can point your web browser at <a href="http://localhost:8080/"> |
| 375 | http://localhost:8080/</a> and begin exploring. Or your coworkers |
| 376 | can do pushes or pulls against your server. Use the <b>--port</b> |
| 377 | option to the server command to specify a different TCP port. If |
| 378 | you do not have a local source tree, use the <b>-R</b> command-line |
| 379 | option to specify the repository file.</p> |
| 380 | |
| 381 | <p>A stand-alone server is a great way to set of transient connections |
| 382 | between coworkers for doing quick pushes or pulls. But you can also |
| 383 | set up a permanent stand-alone server if you prefer. Just make |
| 384 | arrangements for fossil to be launched with appropriate arguments |
| 385 | after every reboot.</p> |
| 386 | |
| 387 | <p>If you just want a server to browse the built-in fossil website |
| 388 | locally, use the <b>ui</b> command in place of <b>server</b>. The |
| 389 | <b>ui</b> command starts up a local server too, but it also takes |
| 390 | the additional step of automatically launching your webbrowser and |
| 391 | pointing at the new server.</p> |
| 392 | </li> |
| 393 | |
| 394 | <li><p><b>Setting up a CGI server</b></p> |
| 395 | |
| 396 | <p>If you have a webserver running on your machine already, you can |
| 397 | set up fossil to be run from CGI. Simply create an executable script |
| 398 | that looks something like this:</p> |
| 399 | |
| 400 | <blockquote><pre> |
| 401 | #!/usr/local/bin/fossil |
| 402 | repository: /home/me/bigproject.fossil |
| 403 | </pre></blockquote> |
| 404 | |
| 405 | <p>Edit this script to use whatever pathnames are appropriate for |
| 406 | your project. Then point your web browser at the script and off you |
| 407 | go.</p></li> |
| 408 | |
| 409 | <li><p><b>Setting up an inetd server</b></p> |
| 410 | |
| 411 | <p>If you have inetd or xinetd running on your system, you can set |
| 412 | those services up to launch fossil to deal with inbound TCP/IP connections |
| 413 | on whatever port you want. Set up inetd or xinetd to launch fossil |
| 414 | like this:</p> |
| 415 | |
| 416 | <blockquote><pre> |
| 417 | /usr/local/bin/fossil http /home/me/bigproject.fossil |
| 418 | </pre></blockquote> |
| 419 | |
| 420 | <p>As before, change the filenames to whatever is appropriate for |
| 421 | your system. You can have fossil run as any user that has write |
| 422 | permission on the repository and on the directory that contains the |
| 423 | repository. But it is safer to run fossil as root. When fossil |
| 424 | sees that it is running as root, it automatically puts itself into |
| 425 | a <a href="http://en.wikipedia.org/wiki/Chroot">chroot jail</a> and |
| 426 | drops all privileges prior to reading any information from the client. |
| 427 | Since fossil is a stand-alone program, you do not need to put anything |
| 428 | in the chroot jail with fossil in order for it to do its job.</p> |
| 429 | </li> |
| 430 | </ol> |
| 431 | |
| 432 | <h2>6.0 Review Of Key Concepts</h2> |
| 433 | |
| 434 |
| --- www/concepts.wiki | |
| +++ www/concepts.wiki | |
| @@ -1,68 +1,66 @@ | |
| 1 | <title>Fossil Concepts</title> |
| 2 | <h1 align="center">Fossil Concepts</h1> |
| 3 | |
| 4 | <h2>1.0 Introduction</h2> |
| 5 | |
| 6 | [./index.wiki | Fossil] is a |
| 7 | [http://en.wikipedia.org/wiki/Software_configuration_management | software configuration management] system. |
| 8 | Fossil is software that is designed to control and track the |
| 9 | development of a software project and to record the history |
| 10 | of the project. |
| 11 | There are many such systems in use today. Fossil strives to |
| 12 | distinguish itself from the others by being extremely simple |
| 13 | to setup and operate. |
| 14 | |
| 15 | This document is intended as a quick introduction to the concepts |
| 16 | behind fossil. |
| 17 | |
| 18 | <h2>2.0 Composition Of A Project</h2> |
| 19 | <img src="concept1.gif" align="right" hspace="10"> |
| 20 | |
| 21 | A software project normally consists of a "source tree". |
| 22 | A source tree is a hierarchy of files that are used to generate |
| 23 | the end product. The source tree changes over time as the |
| 24 | software grows and expands and as features are added and bugs |
| 25 | are fixed. A snapshot of the source tree at any point in time |
| 26 | is called a "version" or "revision" or a "baseline" of the product. |
| 27 | In fossil, we use the name "check-in". |
| 28 | |
| 29 | A "repository" is a database that contains copies of all historical |
| 30 | check-ins for a project. Check-ins are normally stored in the |
| 31 | repository in a highly space-efficient compressed format (delta encoding). |
| 32 | But that is an implementation detail that you the user need not worry over. |
| 33 | Think of the repository as a safe place where all your old check-ins are |
| 34 | securely stored away and available for retrieval whenever you need |
| 35 | them. |
| 36 | |
| 37 | A repository in fossil is a single file on your disk. This file |
| 38 | might be rather large (dozens or hundreds of megabytes for a large |
| 39 | or long running project) but it is nevertheless just a file. You |
| 40 | can move it around, rename it, write it out to a memory stick, or |
| 41 | do anything else you normally do with files. |
| 42 | |
| 43 | Each source tree that is controlled by fossil is associated with |
| 44 | a single repository on the local disk drive. You can tie two or more |
| 45 | source trees to a single repository if you want (though one |
| 46 | tree per repository is the most common configuration.) So a |
| 47 | single repository can be associated with many source trees, but |
| 48 | each source tree is associated with only one repository. |
| 49 | |
| 50 | Fossil source trees may not overlap. A fossil source tree is identified |
| 51 | by a file named "_FOSSIL_" in the root directory of the source tree. Every |
| 52 | file that is a sibling of _FOSSIL_ and every file in every subfolder is |
| 53 | considered potentially a part of the source tree. The _FOSSIL_ file |
| 54 | contains (among other things) the pathname of the repository with which |
| 55 | the source tree is associated. On the other hand, the repository has |
| 56 | no record of its source trees. So you are free to delete a source tree |
| 57 | or move it around without consequence. But if you move or rename or |
| 58 | delete a repository, then any source trees associated with that repository |
| 59 | will no longer be able to locate their repository and will stop working. |
| 60 | |
| 61 | When multiple developers are working on the same project, each |
| 62 | developer typically has his or her own local repository and an associated |
| 63 | source tree in which to work. Developers share their work by |
| 64 | "syncing" the content of their local repositories either directly |
| 65 | or through a central server. Changes can "push" from the local |
| 66 | repository into a remote repository. Or changes can "pull" from a |
| @@ -69,71 +67,74 @@ | |
| 67 | remote repository into a local repository. Or one can do a "sync" |
| 68 | which is a shortcut for doing both a push and a pull at the same time. |
| 69 | Fossil also has the concept of "cloning". A "clone" is like a "pull", |
| 70 | except that instead of beginning with an existing local repository, |
| 71 | a clone begins with nothing and creates a new local repository that |
| 72 | is a duplicate of a remote repository. |
| 73 | |
| 74 | Communication between repositories is via HTTP. Remote |
| 75 | repositories are identified by URL. You can also point a web browser |
| 76 | at a repository and get human-readable status, history, and tracking |
| 77 | information about the project. |
| 78 | |
| 79 | <h3>2.1 Identification Of Artifacts</h3> |
| 80 | |
| 81 | A particular version of a particular file is called an "artifact". |
| 82 | Each artifact has a universally unique name which is the |
| 83 | <a href="http://en.wikipedia.org/wiki/SHA">SHA1</a> hash of the content |
| 84 | of that file expressed as 40 characters of lower-case hexadecimal. Such |
| 85 | a hash is referred to as the Artifact Identifier or Artifact ID |
| 86 | for the artifact. The SHA1 algorithm is created with the purpose of |
| 87 | providing a highly forgery-resistant identifier for a file. Given any |
| 88 | file it is simple to find the artifact ID for that file. But given a |
| 89 | artifact ID it is computationally intractable to generate a file that will |
| 90 | have that Artifact ID. |
| 91 | |
| 92 | Artifact IDs look something like this: |
| 93 | |
| 94 | <blockquote><b> |
| 95 | 6089f0b563a9db0a6d90682fe47fd7161ff867c8<br> |
| 96 | 59712614a1b3ccfd84078a37fa5b606e28434326<br> |
| 97 | 19dbf73078be9779edd6a0156195e610f81c94f9<br> |
| 98 | b4104959a67175f02d6b415480be22a239f1f077<br> |
| 99 | 997c9d6ae03ad114b2b57f04e9eeef17dcb82788 |
| 100 | </b></blockquote> |
| 101 | |
| 102 | When referring to an artifact using fossil, you can use a unique |
| 103 | prefix of the artifact ID that is four characters or longer. This saves |
| 104 | a lot of typing. When displaying artifact IDs, fossil will usually only |
| 105 | show the first 10 digits since that is normally enough to uniquely |
| 106 | identify a file. |
| 107 | |
| 108 | Changing (or adding or removing) a single byte in a file results |
| 109 | in a completely different artifact ID. And since the artifact ID is the name of |
| 110 | the artifact, making any change to a file results in a new artifact. |
| 111 | In this way, artifacts are immutable. |
| 112 | |
| 113 | A repository is really just an unordered collection of |
| 114 | artifacts. New artifacts can be added to the repository, but |
| 115 | existing artifacts can never be removed. (Well, almost never. There |
| 116 | is a [./shunning.wiki | "shunning"] mechanism that allows spam or other |
| 117 | inappropriate content to be removed if absolutely necessary, but such |
| 118 | removal is discouraged.) |
| 119 | Fossil is designed in |
| 120 | such a way that it can be handed a set of artifacts in any |
| 121 | order and it can figure out the relationship between those |
| 122 | artifacts and reconstruct the complete development history of |
| 123 | a software project. |
| 124 | |
| 125 | <h3>2.2 Manifests</h3> |
| 126 | |
| 127 | At the root of a source tree is a special file called the |
| 128 | "manifest". The manifest is a listing of all other files in |
| 129 | that source tree. The manifest contains the (complete) artifact ID |
| 130 | of the file and the name of the file as it appears on disk, |
| 131 | and thus serves as a mapping from artifact ID to disk name. The artifact ID |
| 132 | of the manifest is the identifier for the entire check-in. When |
| 133 | you look at a "timeline" of changes in fossil, the ID associated |
| 134 | with each check-in or commit is really just the artifact ID of the |
| 135 | manifest for that check-in. |
| 136 | |
| 137 | <p>Fossil automatically generates a manifest whenever you "commit" |
| 138 | a new check-in. So this is not something that you, the developer, |
| 139 | need to worry with. The format of a manifest is intentionally |
| 140 | designed to be simple to parse, so that if |
| @@ -165,17 +166,17 @@ | |
| 166 | <li>The artifact ID of the manifest is the identifier of the check-in.</li> |
| 167 | </ul> |
| 168 | |
| 169 | <h2>3.0 Fossil - The Program</h2> |
| 170 | |
| 171 | Fossil is software. The implementation of fossil is in the form |
| 172 | of a single executable named "fossil". To install fossil on your system, |
| 173 | all you have to do is obtain a copy of this one executable file (either |
| 174 | by downloading a pre-compiled version or compiling it yourself) and then |
| 175 | putting that file somewhere on your PATH. |
| 176 | |
| 177 | Fossil is completely self-contained. It is not necessary to |
| 178 | install any other software in order to use fossil. You do <u>not</u> need |
| 179 | CVS, gzip, diff, rsync, Python, Perl, Tcl, Java, apache, PostgreSQL, MySQL, |
| 180 | SQLite, patch, or any similar software on your system in order to use |
| 181 | fossil effectively. You will want to have some kind of text editor |
| 182 | for entering check-in comments. Fossil will use whatever text editor |
| @@ -182,252 +183,266 @@ | |
| 183 | is identified by your VISUAL environment variable. Fossil will also |
| 184 | use GPG to clearsign your manifests if you happen to have it installed, |
| 185 | but fossil will skip that step if GPG missing from your system. |
| 186 | You can optionally set up fossil to use external "diff" programs, |
| 187 | though fossil has an excellent built-in "diff" algorithm that works |
| 188 | fine for most people. |
| 189 | |
| 190 | To uninstall fossil, simply delete the executable. |
| 191 | |
| 192 | To upgrade an older version of fossil to a newer version, just |
| 193 | replace the old executable with the new one. You might need to |
| 194 | run "<b>fossil all rebuild</b>" to restructure your repositories after |
| 195 | an upgrade. Running "all rebuild" never hurts, so when upgrading it |
| 196 | is a good policy to run it even if it is not strictly necessary. |
| 197 | |
| 198 | To use fossil, simply type the name of the executable in your |
| 199 | shell, followed by one of the various built-in commands and |
| 200 | arguments appropriate for that command. For example: |
| 201 | |
| 202 | <blockquote><b> |
| 203 | fossil help |
| 204 | </b></blockquote> |
| 205 | |
| 206 | In the next section, when we say things like "use the <b>help</b> |
| 207 | command" we mean to use the command name "help" as the first |
| 208 | token after the name of the fossil executable, as shown above. |
| 209 | |
| 210 | <a name="workflow"> |
| 211 | <h2>4.0 Workflow</h2> |
| 212 | |
| 213 | <img src="concept2.gif" align="right" hspace="10"> |
| 214 | |
| 215 | Fossil has two modes of operation: <i>"autosync"</i> and |
| 216 | <i>"manual-merge"</i> |
| 217 | Autosync mode is reminiscent of CVS or SVN in that it automatically |
| 218 | keeps your changes in synchronization with your co-workers through |
| 219 | the use of a central server. The manual-merge mode is the standard workflow |
| 220 | for GIT or Mercurial in that your local repository develops |
| 221 | independently of your coworkers and you share and merge your changes manually. |
| 222 | An interesting feature of fossil is that it supports both autosync |
| 223 | and manual-merge work flows. |
| 224 | |
| 225 | The default setting for fossil is to be in autosync mode. You |
| 226 | can change the autosync setting or check the current autosync |
| 227 | setting using commands like: |
| 228 | |
| 229 | <blockquote> |
| 230 | <b>fossil setting autosync on<br> |
| 231 | fossil setting autosync off<br> |
| 232 | <b>fossil settings</b> |
| 233 | </blockquote> |
| 234 | |
| 235 | By default, fossil runs with autosync mode turned on. The |
| 236 | authors finds that projects run more smoothly in autosync mode since |
| 237 | autosync helps to prevent pointless forking and merge and helps keeps |
| 238 | all collaborators working on exactly the same code rather than on their |
| 239 | own personal forks of the code. In the author's view, manual-merge mode |
| 240 | should be reserved for disconnected operation. |
| 241 | |
| 242 | <h3>4.1 Autosync Workflow</h3> |
| 243 | |
| 244 | <ol> |
| 245 | <li> |
| 246 | Establish a local repository using either the <b>new</b> command |
| 247 | to start a new project, or the <b>clone</b> command to make a clone |
| 248 | of a repository for an existing project. |
| 249 | </li> |
| 250 | |
| 251 | <li> |
| 252 | Establish one or more source trees by changing your working directory |
| 253 | to where you want the root of the source tree to be, then issuing |
| 254 | the <b>open</b> command with the name of the repository file as its |
| 255 | argument. |
| 256 | </li> |
| 257 | |
| 258 | <li> |
| 259 | The <b>open</b> command in the previous step populates your local source |
| 260 | tree with a copy of the latest check-in. Usually this is what you want. |
| 261 | In the rare cases where it is not, use the <b>update</b> command to |
| 262 | switch to a new check-in. Use the <b>timeline</b> or <b>leaves</b> commands |
| 263 | to identify alternative check-ins to switch to. |
| 264 | </li> |
| 265 | |
| 266 | <li> |
| 267 | Edit the code. Add new files to the source tree using the <b>add</b> |
| 268 | command. Omit files from future check-ins using the <b>rm</b> command. |
| 269 | (Even when you remove files from future check-ins, those files continue |
| 270 | to exist in historical check-ins.) Test your changes. |
| 271 | </li> |
| 272 | |
| 273 | <li> |
| 274 | Create a new check-in using the <b>commit</b> command. You will be prompted |
| 275 | for a check-in comment and also for your GPG key if you have GPG installed. |
| 276 | The commit copies the edits you have made in your local source |
| 277 | tree into your local repository. After your commit completes, fossil will |
| 278 | automatically <b>push</b> your changes back to the server |
| 279 | you cloned from or whatever server you most recently synced with. |
| 280 | </li> |
| 281 | |
| 282 | <li> |
| 283 | When your coworkers make their own changes, you can merge those changes |
| 284 | into your local local source tree using the <b>update</b> command. |
| 285 | In autosync mode, <b>update</b> will first go back to the server you |
| 286 | cloned from or with which you most recently synced, and pull down all |
| 287 | recent changes into your local repository. Then it will merge recent |
| 288 | changes into your local source tree. If you do an <b>update</b> and |
| 289 | find that it messes something up in your source tree (perhaps a co-worker |
| 290 | checked in incompatible changes) you can use the <b>undo</b> command |
| 291 | to back out the changes. |
| 292 | </li> |
| 293 | |
| 294 | <li> |
| 295 | Repeat all of the above until you have generated great software. |
| 296 | </li> |
| 297 | </ol> |
| 298 | |
| 299 | <h3>4.2 Manual-Merge Workflow</h3> |
| 300 | |
| 301 | When autosync is disabled, the <b>commit</b> command is decoupled from |
| 302 | <b>push</b> and the <b>update</b> command is decoupled from <b>pull</b>. |
| 303 | That means you have to do a few extra steps in order to accomplish the |
| 304 | <b>push</b> and <b>pull</b> tasks manually. |
| 305 | |
| 306 | <ol> |
| 307 | <li> |
| 308 | Establish a local repository using either the <b>new</b> command |
| 309 | to start a new project, or the <b>clone</b> command to make a clone |
| 310 | of a repository for an existing project. The default setting for |
| 311 | a new repository is with autosync on, so you will need to turn it off |
| 312 | using the <b>setting autosync off</b> command with a <b>-R</b> option |
| 313 | to specify the repository. |
| 314 | </li> |
| 315 | |
| 316 | <li> |
| 317 | Establish one or more source trees by changing your working directory |
| 318 | to where you want the root of the source tree to be, then issuing |
| 319 | the <b>open</b> command with the name of the repository file as its |
| 320 | argument. |
| 321 | </li> |
| 322 | |
| 323 | <li> |
| 324 | The <b>open</b> command in the previous step populates your local source |
| 325 | tree with a copy of the latest check-in. Usually this is what you want. |
| 326 | In the rare cases where it is not, use the <b>update</b> command to |
| 327 | switch to a new check-in. Use the <b>timeline</b> or <b>leaves</b> commands |
| 328 | to identify alternative check-ins to switch to. |
| 329 | </li> |
| 330 | |
| 331 | <li> |
| 332 | Edit the code. Add new files to the source tree using the <b>add</b> |
| 333 | command. Omit files from future check-ins using the <b>rm</b> command. |
| 334 | (Even when you remove files from future check-ins, those files continue |
| 335 | to exist in historical check-ins.) Test your changes. |
| 336 | </li> |
| 337 | |
| 338 | <li> |
| 339 | Create a new check-in using the <b>commit</b> command. You will be prompted |
| 340 | for a check-in comment and also for your GPG key if you have GPG installed. |
| 341 | The commit copies the edits you have made in your local source |
| 342 | tree into your local repository. |
| 343 | </li> |
| 344 | |
| 345 | <li> |
| 346 | Use the <b>push</b> command to push your changes out to a server |
| 347 | where your co-workers can access them. |
| 348 | </li> |
| 349 | |
| 350 | <li> |
| 351 | When co-workers make their own changes, use the <b>pull</b> command |
| 352 | to pull those changes into your local repository. Note that <b>pull</b> |
| 353 | does not move the changes into your local source tree, only into your |
| 354 | local repository. |
| 355 | </li> |
| 356 | |
| 357 | <li> |
| 358 | Once changes are in your local repository, use |
| 359 | use the <b>update</b> command to merge them to your local source tree. |
| 360 | If you merge in some changes and find that the changes do not work out |
| 361 | or are not to your liking, you can back out the changes using the |
| 362 | <b>undo</b> command. |
| 363 | </li> |
| 364 | |
| 365 | <li> |
| 366 | If two or more people ran "commit" against the same baseline, this will |
| 367 | result in a [./branching.wiki | fork] which you may want to resolve by |
| 368 | running <b>merge</b> followed by another <b>commit</b>. |
| 369 | </li> |
| 370 | |
| 371 | <li> |
| 372 | Repeat all of the above until you have generated great software. |
| 373 | </li> |
| 374 | </ol> |
| 375 | |
| 376 | <h2>5.0 Setting Up A Fossil Server</h2> |
| 377 | |
| 378 | With other configuration management software, setting up a server is |
| 379 | a lot of work and normally takes time, patience, and a lot of system |
| 380 | knowledge. Fossil is designed to avoid this frustration. Setting up |
| 381 | a server with fossil is ridiculously easy. You have three options:</p> |
| 382 | |
| 383 | <ol> |
| 384 | <li><b><a name="saserv">S</a>etting up a stand-alone server</b> |
| 385 | |
| 386 | From within your source tree just use the <b>server</b> command and |
| 387 | fossil will start listening for incoming requests on TCP port 8080. |
| 388 | You can point your web browser at <a href="http://localhost:8080/"> |
| 389 | http://localhost:8080/</a> and begin exploring. Or your coworkers |
| 390 | can do pushes or pulls against your server. Use the <b>--port</b> |
| 391 | option to the server command to specify a different TCP port. If |
| 392 | you do not have a local source tree, use the <b>-R</b> command-line |
| 393 | option to specify the repository file. |
| 394 | |
| 395 | A stand-alone server is a great way to set of transient connections |
| 396 | between coworkers for doing quick pushes or pulls. But you can also |
| 397 | set up a permanent stand-alone server if you prefer. Just make |
| 398 | arrangements for fossil to be launched with appropriate arguments |
| 399 | after every reboot. |
| 400 | |
| 401 | If you just want a server to browse the built-in fossil website |
| 402 | locally, use the <b>ui</b> command in place of <b>server</b>. The |
| 403 | <b>ui</b> command starts up a local server too, but it also takes |
| 404 | the additional step of automatically launching your webbrowser and |
| 405 | pointing at the new server. |
| 406 | </li> |
| 407 | |
| 408 | <li><b>Setting up a CGI server</b> |
| 409 | |
| 410 | If you have a web-server running on your machine already, you can |
| 411 | set up fossil to be run from CGI. Simply create an executable script |
| 412 | that looks something like this: |
| 413 | |
| 414 | <blockquote><pre> |
| 415 | #!/usr/local/bin/fossil |
| 416 | repository: /home/me/bigproject.fossil |
| 417 | </pre></blockquote> |
| 418 | |
| 419 | Edit this script to use whatever pathnames are appropriate for |
| 420 | your project. Then point your web browser at the script and off you |
| 421 | go. The [./selfhost.wiki | self-hosting fossil repositories] are |
| 422 | all set up this way.</li> |
| 423 | |
| 424 | <li><b>Setting up an inetd server</b> |
| 425 | |
| 426 | If you have inetd or xinetd running on your system, you can set |
| 427 | those services up to launch fossil to deal with inbound TCP/IP connections |
| 428 | on whatever port you want. Set up inetd or xinetd to launch fossil |
| 429 | like this: |
| 430 | |
| 431 | <blockquote><pre> |
| 432 | /usr/local/bin/fossil http /home/me/bigproject.fossil |
| 433 | </pre></blockquote> |
| 434 | |
| 435 | As before, change the filenames to whatever is appropriate for |
| 436 | your system. You can have fossil run as any user that has write |
| 437 | permission on the repository and on the directory that contains the |
| 438 | repository. But it is safer to run fossil as root. When fossil |
| 439 | sees that it is running as root, it automatically puts itself into |
| 440 | a <a href="http://en.wikipedia.org/wiki/Chroot">chroot jail</a> and |
| 441 | drops all privileges prior to reading any information from the client. |
| 442 | Since fossil is a stand-alone program, you do not need to put anything |
| 443 | in the chroot jail with fossil in order for it to do its job. |
| 444 | </li> |
| 445 | </ol> |
| 446 | |
| 447 | <h2>6.0 Review Of Key Concepts</h2> |
| 448 | |
| 449 |
+1
| --- www/faq.tcl | ||
| +++ www/faq.tcl | ||
| @@ -97,10 +97,11 @@ | ||
| 97 | 97 | |
| 98 | 98 | |
| 99 | 99 | ############################################################################# |
| 100 | 100 | # Code to actually generate the FAQ |
| 101 | 101 | # |
| 102 | +puts "<title>Fossil FAQ</title>" | |
| 102 | 103 | puts "<h1 align=\"center\">Frequently Asked Questions</h1>\n" |
| 103 | 104 | puts "<p>Note: See also <a href=\"qandc.wiki\">Questions and Criticisms</a>.\n" |
| 104 | 105 | |
| 105 | 106 | puts {<ol>} |
| 106 | 107 | for {set i 1} {$i<$cnt} {incr i} { |
| 107 | 108 |
| --- www/faq.tcl | |
| +++ www/faq.tcl | |
| @@ -97,10 +97,11 @@ | |
| 97 | |
| 98 | |
| 99 | ############################################################################# |
| 100 | # Code to actually generate the FAQ |
| 101 | # |
| 102 | puts "<h1 align=\"center\">Frequently Asked Questions</h1>\n" |
| 103 | puts "<p>Note: See also <a href=\"qandc.wiki\">Questions and Criticisms</a>.\n" |
| 104 | |
| 105 | puts {<ol>} |
| 106 | for {set i 1} {$i<$cnt} {incr i} { |
| 107 |
| --- www/faq.tcl | |
| +++ www/faq.tcl | |
| @@ -97,10 +97,11 @@ | |
| 97 | |
| 98 | |
| 99 | ############################################################################# |
| 100 | # Code to actually generate the FAQ |
| 101 | # |
| 102 | puts "<title>Fossil FAQ</title>" |
| 103 | puts "<h1 align=\"center\">Frequently Asked Questions</h1>\n" |
| 104 | puts "<p>Note: See also <a href=\"qandc.wiki\">Questions and Criticisms</a>.\n" |
| 105 | |
| 106 | puts {<ol>} |
| 107 | for {set i 1} {$i<$cnt} {incr i} { |
| 108 |
+1
| --- www/faq.wiki | ||
| +++ www/faq.wiki | ||
| @@ -1,5 +1,6 @@ | ||
| 1 | +<title>Fossil FAQ</title> | |
| 1 | 2 | <h1 align="center">Frequently Asked Questions</h1> |
| 2 | 3 | |
| 3 | 4 | <p>Note: See also <a href="qandc.wiki">Questions and Criticisms</a>. |
| 4 | 5 | |
| 5 | 6 | <ol> |
| 6 | 7 |
| --- www/faq.wiki | |
| +++ www/faq.wiki | |
| @@ -1,5 +1,6 @@ | |
| 1 | <h1 align="center">Frequently Asked Questions</h1> |
| 2 | |
| 3 | <p>Note: See also <a href="qandc.wiki">Questions and Criticisms</a>. |
| 4 | |
| 5 | <ol> |
| 6 |
| --- www/faq.wiki | |
| +++ www/faq.wiki | |
| @@ -1,5 +1,6 @@ | |
| 1 | <title>Fossil FAQ</title> |
| 2 | <h1 align="center">Frequently Asked Questions</h1> |
| 3 | |
| 4 | <p>Note: See also <a href="qandc.wiki">Questions and Criticisms</a>. |
| 5 | |
| 6 | <ol> |
| 7 |
+68
-43
| --- www/index.wiki | ||
| +++ www/index.wiki | ||
| @@ -5,10 +5,11 @@ | ||
| 5 | 5 | <h2>Quick Links</h2> |
| 6 | 6 | <ul> |
| 7 | 7 | <li> [./quickstart.wiki | Quick Start] |
| 8 | 8 | <li> [http://www.fossil-scm.org/download.html | Download] |
| 9 | 9 | <li> [./build.wiki | Install] |
| 10 | +<li> [../COPYRIGHT-GPL2.txt | License] | |
| 10 | 11 | <li> [/timeline | Recent changes] |
| 11 | 12 | <li> [./faq.wiki | FAQ] |
| 12 | 13 | </ul> |
| 13 | 14 | <center><img src="fossil.gif"></center> |
| 14 | 15 | </td></tr> |
| @@ -19,59 +20,83 @@ | ||
| 19 | 20 | <font size=5><b>Fossil:</b><i> |
| 20 | 21 | Simple, high-reliability, distributed software configuration management |
| 21 | 22 | </i></font> |
| 22 | 23 | </center> |
| 23 | 24 | |
| 24 | -<h3>Feature Summary:</h3> | |
| 25 | - * [./concepts.wiki | Distributed version control] | |
| 26 | - * Integrated, [./bugtheory.wiki | distributed bug tracking] and | |
| 27 | - [./wikitheory.wiki | distributed wiki]. | |
| 28 | - * Built-in [./webui.wiki | web interface] that supports deep | |
| 29 | - archaeological digs through the project history. | |
| 30 | - * All network communication via HTTP with | |
| 31 | - [./quickstart.wiki#proxy | proxy support] | |
| 32 | - so that everything works from behind restrictive firewalls. | |
| 33 | - Communication is [./stats.wiki | bandwidth-efficient]. | |
| 34 | - * Everything (client, server, and utilities) is included in a | |
| 35 | - single self-contained executable - [./build.wiki | trivial to install]. | |
| 36 | - * Server runs as [./quickstart.wiki#cgiserver | CGI], using | |
| 37 | - [./quickstart.wiki#inetdserver | inetd/xinetd] | |
| 38 | - or using its own | |
| 39 | - [./quickstart.wiki#serversetup | built-in, stand alone web server]. | |
| 40 | - * Flexible workflow:<ul> | |
| 41 | - <li>Disconnected, distributed development like | |
| 42 | - <a href="http://kerneltrap.org/node/4982">git</a>, | |
| 43 | - <a href="http://www.monotone.ca/">monotone</a>, | |
| 44 | - <a href="http://www.selenic.com/mercurial/wiki/index.cgi">mercurial</a>, | |
| 45 | - and <a href="http://www.bitkeeper.com/">bitkeeper</a> | |
| 46 | - <li>Or, client/server operation like | |
| 47 | - <a href="http://www.nongnu.org/cvs/">CVS</a> and | |
| 48 | - <a href="http://subversion.tigris.org/">subversion</a>, | |
| 49 | - <li>Or, operations on local repositories, | |
| 50 | - <li>Or, all of the above at the same time</ul> | |
| 51 | - * [./selfhost.wiki | Self-hosting] since 2007-07-21. | |
| 52 | - * An entire project contained in single | |
| 53 | - [./stats.wiki | compact] disk file | |
| 54 | - (an [http://www.sqlite.org/ | SQLite] database.) | |
| 55 | - * Uses an [./fileformat.wiki | enduring file format] that is | |
| 56 | - designed to be readable, searchable, and extensible by people | |
| 57 | - not yet born. | |
| 58 | - * Automatic [./selfcheck.wiki | self-check] | |
| 59 | - on repository changes makes it exceedingly | |
| 60 | - unlikely that data will ever be lost because of a software bug. | |
| 61 | - * License: [../COPYRIGHT-GPL2.txt | GPL] | |
| 62 | - | |
| 63 | -<h3>User Links:</h3> | |
| 64 | - | |
| 25 | +<h3>Why Use Fossil?</h3> | |
| 26 | + | |
| 27 | +There are plenty of open-source version control systems available on the | |
| 28 | +internet these days. What makes Fossil worthy of attention? | |
| 29 | + | |
| 30 | + 1. <b>Bug Tracking And Wiki</b> - | |
| 31 | + In addition to doing [./concepts.wiki | distributed version control] | |
| 32 | + like Git and Mercurial, | |
| 33 | + Fossil also supports [./bugtheory.wiki | distributed bug tracking] and | |
| 34 | + [./wikitheory.wiki | distributed wiki] all in a single | |
| 35 | + integrated package. | |
| 36 | + | |
| 37 | + 2. <b>Web Interface</b> - | |
| 38 | + Fossil has a built-in and easy-to-use [./webui.wiki | web interface] | |
| 39 | + that simplifies project tracking and promotes situational awareness. | |
| 40 | + Simply type "fossil ui" from within any check-out and Fossil | |
| 41 | + automatically opens your web browser in a page that gives detailed | |
| 42 | + history and status information on that project. | |
| 43 | + | |
| 44 | + 3. <b>Autosync</b> - | |
| 45 | + Fossil supports [./concepts.wiki#workflow | "autosync" mode] | |
| 46 | + which helps to keep projects moving | |
| 47 | + forward by reducing the amount of needless | |
| 48 | + [./branching.wiki | forking and merging] often | |
| 49 | + associated distributed projects. | |
| 50 | + | |
| 51 | + 4. <b>Self-Contained</b> - | |
| 52 | + Fossil is a single stand-alone executable that contains everything | |
| 53 | + needed to do configuration management. | |
| 54 | + Installation is trivial: simply download a | |
| 55 | + <a href="http://www.fossil-scm.org/download.html">precompiled binary</a> | |
| 56 | + for Linux, Mac, or Windows and put it on your $PATH. | |
| 57 | + [./build.wiki | Easy-to-compile source code] is available for | |
| 58 | + users on other platforms. Fossil sources are also mostly self-contained, | |
| 59 | + requiring only the "zlib" library and the standard C library to build. | |
| 60 | + | |
| 61 | + 5. <b>Simple Networking</b> - | |
| 62 | + Fossil uses plain old HTTP (with | |
| 63 | + [./quickstart.wiki#proxy | proxy support]) | |
| 64 | + for all network communications, meaning that it works fine from behind | |
| 65 | + restrictive firewalls. The protocol is | |
| 66 | + [./stats.wiki | bandwidth efficient] to the point that Fossil can be | |
| 67 | + used comfortably over a dial-up internet connection. | |
| 68 | + | |
| 69 | + 6. <b>CGI Enabled</b> - | |
| 70 | + No server is required to use fossil. But a | |
| 71 | + server does make collaboration easier. Fossil supports three different | |
| 72 | + yet simple [./quickstart.wiki#serversetup | server configurations]. | |
| 73 | + The most popular is a 2-line CGI script. This is the approach | |
| 74 | + used by the [./selfhost.wiki | self-hosting fossil repositories]. | |
| 75 | + | |
| 76 | + 7. <b>Robust & Reliable</b> - | |
| 77 | + Fossil stores content in an SQLite database so that transactions are | |
| 78 | + atomic even if interrupted by a power loss or system crash. Furthermore, | |
| 79 | + automatic [./selfcheck.wiki | self-checks] verify that all aspects of | |
| 80 | + the repository are consistent prior to each commit. In over two years | |
| 81 | + of operation, no work has ever been lost after having been committed to | |
| 82 | + a Fossil repository. | |
| 83 | + | |
| 84 | +<hr> | |
| 85 | +<h3>Links For Fossil Users:</h3> | |
| 86 | + | |
| 87 | + * [./reviews.wiki | Testimonials] from satisfied fossil users. | |
| 65 | 88 | * [./faq.wiki | FAQ] |
| 66 | 89 | * The [./concepts.wiki | concepts] behind fossil |
| 67 | 90 | * [./quickstart.wiki | Quick Start] guide to using fossil |
| 68 | - * [./reviews.wiki | Testimonials] from fossil users. | |
| 69 | 91 | * [./qandc.wiki | Questions & Criticisms] directed at fossil. |
| 70 | 92 | * [./build.wiki | Building And Installing] |
| 71 | 93 | * Fossil supports [./embeddeddoc.wiki | embedded documentation] |
| 72 | 94 | that is versioned along with project source code. |
| 95 | + * Fossil uses an [./fileformat.wiki | enduring file format] that is | |
| 96 | + designed to be readable, searchable, and extensible by people | |
| 97 | + not yet born. | |
| 73 | 98 | * A tutorial on [./branching.wiki | branching], what it means and how |
| 74 | 99 | to do it using fossil. |
| 75 | 100 | * The [./selfcheck.wiki | automatic self-check] mechanism |
| 76 | 101 | helps insure project integrity. |
| 77 | 102 | * Fossil contains a [./wikitheory.wiki | built-in wiki]. |
| @@ -82,15 +107,15 @@ | ||
| 82 | 107 | hosted on fossil. |
| 83 | 108 | * How to [./shunning.wiki | delete content] from a fossil repository. |
| 84 | 109 | * Some (unfinished but expanding) extended |
| 85 | 110 | [./reference.wiki | reference documentation] for the fossil command line. |
| 86 | 111 | |
| 87 | -<h3>Developer Links:</h3> | |
| 112 | +<h3>Links For Fossil Developer:</h3> | |
| 88 | 113 | |
| 89 | 114 | * [./pop.wiki | Principles Of Operation] |
| 90 | 115 | * The [./fileformat.wiki | file format] used by every content |
| 91 | 116 | file stored in the repository. |
| 92 | 117 | * The [./delta_format.wiki | format of deltas] used to |
| 93 | 118 | efficiently store changes between file revisions. |
| 94 | 119 | * The [./delta_encoder_algorithm.wiki | encoder algorithm] used to |
| 95 | 120 | efficiently generate deltas. |
| 96 | 121 | * The [./sync.wiki | synchronization protocol]. |
| 97 | 122 |
| --- www/index.wiki | |
| +++ www/index.wiki | |
| @@ -5,10 +5,11 @@ | |
| 5 | <h2>Quick Links</h2> |
| 6 | <ul> |
| 7 | <li> [./quickstart.wiki | Quick Start] |
| 8 | <li> [http://www.fossil-scm.org/download.html | Download] |
| 9 | <li> [./build.wiki | Install] |
| 10 | <li> [/timeline | Recent changes] |
| 11 | <li> [./faq.wiki | FAQ] |
| 12 | </ul> |
| 13 | <center><img src="fossil.gif"></center> |
| 14 | </td></tr> |
| @@ -19,59 +20,83 @@ | |
| 19 | <font size=5><b>Fossil:</b><i> |
| 20 | Simple, high-reliability, distributed software configuration management |
| 21 | </i></font> |
| 22 | </center> |
| 23 | |
| 24 | <h3>Feature Summary:</h3> |
| 25 | * [./concepts.wiki | Distributed version control] |
| 26 | * Integrated, [./bugtheory.wiki | distributed bug tracking] and |
| 27 | [./wikitheory.wiki | distributed wiki]. |
| 28 | * Built-in [./webui.wiki | web interface] that supports deep |
| 29 | archaeological digs through the project history. |
| 30 | * All network communication via HTTP with |
| 31 | [./quickstart.wiki#proxy | proxy support] |
| 32 | so that everything works from behind restrictive firewalls. |
| 33 | Communication is [./stats.wiki | bandwidth-efficient]. |
| 34 | * Everything (client, server, and utilities) is included in a |
| 35 | single self-contained executable - [./build.wiki | trivial to install]. |
| 36 | * Server runs as [./quickstart.wiki#cgiserver | CGI], using |
| 37 | [./quickstart.wiki#inetdserver | inetd/xinetd] |
| 38 | or using its own |
| 39 | [./quickstart.wiki#serversetup | built-in, stand alone web server]. |
| 40 | * Flexible workflow:<ul> |
| 41 | <li>Disconnected, distributed development like |
| 42 | <a href="http://kerneltrap.org/node/4982">git</a>, |
| 43 | <a href="http://www.monotone.ca/">monotone</a>, |
| 44 | <a href="http://www.selenic.com/mercurial/wiki/index.cgi">mercurial</a>, |
| 45 | and <a href="http://www.bitkeeper.com/">bitkeeper</a> |
| 46 | <li>Or, client/server operation like |
| 47 | <a href="http://www.nongnu.org/cvs/">CVS</a> and |
| 48 | <a href="http://subversion.tigris.org/">subversion</a>, |
| 49 | <li>Or, operations on local repositories, |
| 50 | <li>Or, all of the above at the same time</ul> |
| 51 | * [./selfhost.wiki | Self-hosting] since 2007-07-21. |
| 52 | * An entire project contained in single |
| 53 | [./stats.wiki | compact] disk file |
| 54 | (an [http://www.sqlite.org/ | SQLite] database.) |
| 55 | * Uses an [./fileformat.wiki | enduring file format] that is |
| 56 | designed to be readable, searchable, and extensible by people |
| 57 | not yet born. |
| 58 | * Automatic [./selfcheck.wiki | self-check] |
| 59 | on repository changes makes it exceedingly |
| 60 | unlikely that data will ever be lost because of a software bug. |
| 61 | * License: [../COPYRIGHT-GPL2.txt | GPL] |
| 62 | |
| 63 | <h3>User Links:</h3> |
| 64 | |
| 65 | * [./faq.wiki | FAQ] |
| 66 | * The [./concepts.wiki | concepts] behind fossil |
| 67 | * [./quickstart.wiki | Quick Start] guide to using fossil |
| 68 | * [./reviews.wiki | Testimonials] from fossil users. |
| 69 | * [./qandc.wiki | Questions & Criticisms] directed at fossil. |
| 70 | * [./build.wiki | Building And Installing] |
| 71 | * Fossil supports [./embeddeddoc.wiki | embedded documentation] |
| 72 | that is versioned along with project source code. |
| 73 | * A tutorial on [./branching.wiki | branching], what it means and how |
| 74 | to do it using fossil. |
| 75 | * The [./selfcheck.wiki | automatic self-check] mechanism |
| 76 | helps insure project integrity. |
| 77 | * Fossil contains a [./wikitheory.wiki | built-in wiki]. |
| @@ -82,15 +107,15 @@ | |
| 82 | hosted on fossil. |
| 83 | * How to [./shunning.wiki | delete content] from a fossil repository. |
| 84 | * Some (unfinished but expanding) extended |
| 85 | [./reference.wiki | reference documentation] for the fossil command line. |
| 86 | |
| 87 | <h3>Developer Links:</h3> |
| 88 | |
| 89 | * [./pop.wiki | Principles Of Operation] |
| 90 | * The [./fileformat.wiki | file format] used by every content |
| 91 | file stored in the repository. |
| 92 | * The [./delta_format.wiki | format of deltas] used to |
| 93 | efficiently store changes between file revisions. |
| 94 | * The [./delta_encoder_algorithm.wiki | encoder algorithm] used to |
| 95 | efficiently generate deltas. |
| 96 | * The [./sync.wiki | synchronization protocol]. |
| 97 |
| --- www/index.wiki | |
| +++ www/index.wiki | |
| @@ -5,10 +5,11 @@ | |
| 5 | <h2>Quick Links</h2> |
| 6 | <ul> |
| 7 | <li> [./quickstart.wiki | Quick Start] |
| 8 | <li> [http://www.fossil-scm.org/download.html | Download] |
| 9 | <li> [./build.wiki | Install] |
| 10 | <li> [../COPYRIGHT-GPL2.txt | License] |
| 11 | <li> [/timeline | Recent changes] |
| 12 | <li> [./faq.wiki | FAQ] |
| 13 | </ul> |
| 14 | <center><img src="fossil.gif"></center> |
| 15 | </td></tr> |
| @@ -19,59 +20,83 @@ | |
| 20 | <font size=5><b>Fossil:</b><i> |
| 21 | Simple, high-reliability, distributed software configuration management |
| 22 | </i></font> |
| 23 | </center> |
| 24 | |
| 25 | <h3>Why Use Fossil?</h3> |
| 26 | |
| 27 | There are plenty of open-source version control systems available on the |
| 28 | internet these days. What makes Fossil worthy of attention? |
| 29 | |
| 30 | 1. <b>Bug Tracking And Wiki</b> - |
| 31 | In addition to doing [./concepts.wiki | distributed version control] |
| 32 | like Git and Mercurial, |
| 33 | Fossil also supports [./bugtheory.wiki | distributed bug tracking] and |
| 34 | [./wikitheory.wiki | distributed wiki] all in a single |
| 35 | integrated package. |
| 36 | |
| 37 | 2. <b>Web Interface</b> - |
| 38 | Fossil has a built-in and easy-to-use [./webui.wiki | web interface] |
| 39 | that simplifies project tracking and promotes situational awareness. |
| 40 | Simply type "fossil ui" from within any check-out and Fossil |
| 41 | automatically opens your web browser in a page that gives detailed |
| 42 | history and status information on that project. |
| 43 | |
| 44 | 3. <b>Autosync</b> - |
| 45 | Fossil supports [./concepts.wiki#workflow | "autosync" mode] |
| 46 | which helps to keep projects moving |
| 47 | forward by reducing the amount of needless |
| 48 | [./branching.wiki | forking and merging] often |
| 49 | associated distributed projects. |
| 50 | |
| 51 | 4. <b>Self-Contained</b> - |
| 52 | Fossil is a single stand-alone executable that contains everything |
| 53 | needed to do configuration management. |
| 54 | Installation is trivial: simply download a |
| 55 | <a href="http://www.fossil-scm.org/download.html">precompiled binary</a> |
| 56 | for Linux, Mac, or Windows and put it on your $PATH. |
| 57 | [./build.wiki | Easy-to-compile source code] is available for |
| 58 | users on other platforms. Fossil sources are also mostly self-contained, |
| 59 | requiring only the "zlib" library and the standard C library to build. |
| 60 | |
| 61 | 5. <b>Simple Networking</b> - |
| 62 | Fossil uses plain old HTTP (with |
| 63 | [./quickstart.wiki#proxy | proxy support]) |
| 64 | for all network communications, meaning that it works fine from behind |
| 65 | restrictive firewalls. The protocol is |
| 66 | [./stats.wiki | bandwidth efficient] to the point that Fossil can be |
| 67 | used comfortably over a dial-up internet connection. |
| 68 | |
| 69 | 6. <b>CGI Enabled</b> - |
| 70 | No server is required to use fossil. But a |
| 71 | server does make collaboration easier. Fossil supports three different |
| 72 | yet simple [./quickstart.wiki#serversetup | server configurations]. |
| 73 | The most popular is a 2-line CGI script. This is the approach |
| 74 | used by the [./selfhost.wiki | self-hosting fossil repositories]. |
| 75 | |
| 76 | 7. <b>Robust & Reliable</b> - |
| 77 | Fossil stores content in an SQLite database so that transactions are |
| 78 | atomic even if interrupted by a power loss or system crash. Furthermore, |
| 79 | automatic [./selfcheck.wiki | self-checks] verify that all aspects of |
| 80 | the repository are consistent prior to each commit. In over two years |
| 81 | of operation, no work has ever been lost after having been committed to |
| 82 | a Fossil repository. |
| 83 | |
| 84 | <hr> |
| 85 | <h3>Links For Fossil Users:</h3> |
| 86 | |
| 87 | * [./reviews.wiki | Testimonials] from satisfied fossil users. |
| 88 | * [./faq.wiki | FAQ] |
| 89 | * The [./concepts.wiki | concepts] behind fossil |
| 90 | * [./quickstart.wiki | Quick Start] guide to using fossil |
| 91 | * [./qandc.wiki | Questions & Criticisms] directed at fossil. |
| 92 | * [./build.wiki | Building And Installing] |
| 93 | * Fossil supports [./embeddeddoc.wiki | embedded documentation] |
| 94 | that is versioned along with project source code. |
| 95 | * Fossil uses an [./fileformat.wiki | enduring file format] that is |
| 96 | designed to be readable, searchable, and extensible by people |
| 97 | not yet born. |
| 98 | * A tutorial on [./branching.wiki | branching], what it means and how |
| 99 | to do it using fossil. |
| 100 | * The [./selfcheck.wiki | automatic self-check] mechanism |
| 101 | helps insure project integrity. |
| 102 | * Fossil contains a [./wikitheory.wiki | built-in wiki]. |
| @@ -82,15 +107,15 @@ | |
| 107 | hosted on fossil. |
| 108 | * How to [./shunning.wiki | delete content] from a fossil repository. |
| 109 | * Some (unfinished but expanding) extended |
| 110 | [./reference.wiki | reference documentation] for the fossil command line. |
| 111 | |
| 112 | <h3>Links For Fossil Developer:</h3> |
| 113 | |
| 114 | * [./pop.wiki | Principles Of Operation] |
| 115 | * The [./fileformat.wiki | file format] used by every content |
| 116 | file stored in the repository. |
| 117 | * The [./delta_format.wiki | format of deltas] used to |
| 118 | efficiently store changes between file revisions. |
| 119 | * The [./delta_encoder_algorithm.wiki | encoder algorithm] used to |
| 120 | efficiently generate deltas. |
| 121 | * The [./sync.wiki | synchronization protocol]. |
| 122 |
+39
-28
| --- www/selfcheck.wiki | ||
| +++ www/selfcheck.wiki | ||
| @@ -1,61 +1,49 @@ | ||
| 1 | -<nowiki> | |
| 2 | -<h1 align="center"> | |
| 3 | -Fossil Repository Integrity Self-Checks | |
| 4 | -</h1> | |
| 5 | - | |
| 6 | -<p> | |
| 7 | -Even though fossil is a relatively new project and still contains | |
| 8 | -many bugs, it is designed with features to give it a high level | |
| 9 | -of integrity so that you can have confidence that you will not | |
| 10 | -lose your files. This note describes the defensive measures that | |
| 11 | -fossil uses to help prevent file loss due to bugs. | |
| 12 | -</p> | |
| 13 | - | |
| 14 | -<p><i>Follow-up as of 2007-11-24:</i> | |
| 15 | -<i>Reiterated on 2008-05-16 and again on 2008-10-04:</i> | |
| 1 | +<title>Fossil Repository Integrity Self-Checks</title> | |
| 2 | + | |
| 3 | +<h1 align="center">Fossil Repository Integrity Self-Checks</h1> | |
| 4 | + | |
| 5 | +Fossil is designed with features to give it a high level | |
| 6 | +of integrity so that users can have confidence that content will | |
| 7 | +never be mangled or lost by Fossil. | |
| 8 | +This note describes the defensive measures that | |
| 9 | +Fossil uses to help prevent information loss due to bugs. | |
| 10 | + | |
| 16 | 11 | Fossil has been hosting itself and many other projects for |
| 17 | -months now. Many bugs have been encountered. But, thanks in large | |
| 12 | +years now. Many bugs have been encountered. But, thanks in large | |
| 18 | 13 | part to the defensive measures described here, no data has been |
| 19 | 14 | lost. The integrity checks are doing their job well.</p> |
| 20 | 15 | |
| 21 | 16 | <h2>Atomic Check-ins With Rollback</h2> |
| 22 | 17 | |
| 23 | -<p> | |
| 24 | 18 | The fossil repository is an |
| 25 | 19 | <a href="http://www.sqlite.org/">SQLite version 3</a> database file. |
| 26 | 20 | SQLite is very mature and stable and has been in wide-spread use for many |
| 27 | 21 | years, so we are confident it will not cause repository |
| 28 | 22 | corruption. SQLite |
| 29 | 23 | databases do not corrupt even if a program or system crash or power |
| 30 | 24 | failure occurs in the middle of the update. If some kind of crash |
| 31 | 25 | does occur in the middle of a change, then all the changes are rolled |
| 32 | 26 | back the next time that the database is accessed. |
| 33 | -</p> | |
| 34 | 27 | |
| 35 | -<p> | |
| 36 | 28 | A check-in operation in fossil makes many changes to the repository |
| 37 | 29 | database. But all these changes happen within a single transaction. |
| 38 | 30 | If something goes wrong in the middle of the commit, then the transaction |
| 39 | 31 | is rolled back and the database is unchanged. |
| 40 | -</p> | |
| 41 | 32 | |
| 42 | 33 | <h2>Verification Of Delta Encodings Prior To Transaction Commit</h2> |
| 43 | 34 | |
| 44 | -<p> | |
| 45 | 35 | The content files that comprise the global state of a fossil respository |
| 46 | 36 | are stored in the repository as a tree. The leaves of the tree are |
| 47 | 37 | stored as zlib-compressed BLOBs. Interior nodes are deltas from their |
| 48 | 38 | decendants. A lot of encoding is going on. There is |
| 49 | 39 | zlib-compression which is relatively well-tested but still might |
| 50 | 40 | cause corruption if used improperly. And there is the relatively |
| 51 | 41 | new delta-encoding mechanism designed expressly for fossil. We want |
| 52 | 42 | to make sure that bugs in these encoding mechanisms do not lead to |
| 53 | 43 | loss of data. |
| 54 | -</p> | |
| 55 | 44 | |
| 56 | -<p> | |
| 57 | 45 | To increase our confidence that everything in the repository is |
| 58 | 46 | recoverable, fossil makes sure it can extract an exact replicate |
| 59 | 47 | of every content file that it changes just prior to transaction |
| 60 | 48 | commit. So during the course of check-in (or other repository |
| 61 | 49 | operation) many different files |
| @@ -66,23 +54,19 @@ | ||
| 66 | 54 | file. Then just before transaction commit, fossil re-extracts |
| 67 | 55 | the original content of all files that were written, computes |
| 68 | 56 | the SHA1 checksum again, and verifies that the checksums match. |
| 69 | 57 | If anything does not match up, an error |
| 70 | 58 | message is printed and the transaction rolls back. |
| 71 | -</p> | |
| 72 | 59 | |
| 73 | -<p> | |
| 74 | 60 | So, in other words, fossil always checks to make sure it can |
| 75 | 61 | re-extract a file before it commits a change to that file. |
| 76 | 62 | Hence bugs in fossil are unlikely to corrupt the repository in |
| 77 | 63 | a way that prevents us from extracting historical versions of |
| 78 | 64 | files. |
| 79 | -</p> | |
| 80 | 65 | |
| 81 | 66 | <h2>Checksum Over All Files In A Check-in</h2> |
| 82 | 67 | |
| 83 | -<p> | |
| 84 | 68 | Manifest artifacts that define a check-in have two fields (the |
| 85 | 69 | R-card and Z-card) that record MD5 hashs of the manifest itself |
| 86 | 70 | and of all other files in the manifest. Prior to any check-in |
| 87 | 71 | commit, these checksums are verified to ensure that the check-in |
| 88 | 72 | checked in agrees exactly with what is on disk. Similarly, |
| @@ -89,6 +73,33 @@ | ||
| 89 | 73 | the repository checksum is verified after a checkout to make |
| 90 | 74 | sure that the entire repository was checked out correctly. |
| 91 | 75 | Note that these added checks use a different hash (MD5 instead |
| 92 | 76 | of SHA1) in order to avoid common-mode failures in the hash |
| 93 | 77 | algorithm implementation. |
| 94 | -</p> | |
| 78 | + | |
| 79 | + | |
| 80 | +<h2>Checksums On Control Artifacts And Deltas</h2> | |
| 81 | + | |
| 82 | +Every [./fileformat.wiki | control artifact] in a fossil repository | |
| 83 | +contains a "Z-card" bearing an MD5 checksum over the rest of the | |
| 84 | +artifact. Any mismatch causes the control artifact to be ignored. | |
| 85 | + | |
| 86 | +The [./delta_format.wiki | file delta format] includes a 32-bit | |
| 87 | +checksum of the target file. Whenever a file is reconstructed from | |
| 88 | +a delta, that checksum is verified to make sure the reconstruction | |
| 89 | +was done correctly. | |
| 90 | + | |
| 91 | +<h2>Reliability Versus Performance</h2> | |
| 92 | + | |
| 93 | +Some version control systems make a big deal out of being "high performance" | |
| 94 | +or the "fastest version control system". Fossil makes no such claims and has | |
| 95 | +no such ambition. Indeed, profiling indicates that fossil bears a | |
| 96 | +substantial performance cost for | |
| 97 | +doing all of the checksumming and verification outlined above. | |
| 98 | +Fossil takes the philosophy of the | |
| 99 | +<a href="http://en.wikipedia.org/wiki/The_Tortoise_and_the_Hare">tortoise</a>: | |
| 100 | +reliability is more important than raw speed. The developers of | |
| 101 | +fossil see no merit in getting the wrong answer quickly. | |
| 102 | + | |
| 103 | +Fossil may not be the fastest versioning system, but it is "fast enough". | |
| 104 | +Fossil runs quickly enough to stay out of the developers way. | |
| 105 | +Most operations complete in under a second. | |
| 95 | 106 |
| --- www/selfcheck.wiki | |
| +++ www/selfcheck.wiki | |
| @@ -1,61 +1,49 @@ | |
| 1 | <nowiki> |
| 2 | <h1 align="center"> |
| 3 | Fossil Repository Integrity Self-Checks |
| 4 | </h1> |
| 5 | |
| 6 | <p> |
| 7 | Even though fossil is a relatively new project and still contains |
| 8 | many bugs, it is designed with features to give it a high level |
| 9 | of integrity so that you can have confidence that you will not |
| 10 | lose your files. This note describes the defensive measures that |
| 11 | fossil uses to help prevent file loss due to bugs. |
| 12 | </p> |
| 13 | |
| 14 | <p><i>Follow-up as of 2007-11-24:</i> |
| 15 | <i>Reiterated on 2008-05-16 and again on 2008-10-04:</i> |
| 16 | Fossil has been hosting itself and many other projects for |
| 17 | months now. Many bugs have been encountered. But, thanks in large |
| 18 | part to the defensive measures described here, no data has been |
| 19 | lost. The integrity checks are doing their job well.</p> |
| 20 | |
| 21 | <h2>Atomic Check-ins With Rollback</h2> |
| 22 | |
| 23 | <p> |
| 24 | The fossil repository is an |
| 25 | <a href="http://www.sqlite.org/">SQLite version 3</a> database file. |
| 26 | SQLite is very mature and stable and has been in wide-spread use for many |
| 27 | years, so we are confident it will not cause repository |
| 28 | corruption. SQLite |
| 29 | databases do not corrupt even if a program or system crash or power |
| 30 | failure occurs in the middle of the update. If some kind of crash |
| 31 | does occur in the middle of a change, then all the changes are rolled |
| 32 | back the next time that the database is accessed. |
| 33 | </p> |
| 34 | |
| 35 | <p> |
| 36 | A check-in operation in fossil makes many changes to the repository |
| 37 | database. But all these changes happen within a single transaction. |
| 38 | If something goes wrong in the middle of the commit, then the transaction |
| 39 | is rolled back and the database is unchanged. |
| 40 | </p> |
| 41 | |
| 42 | <h2>Verification Of Delta Encodings Prior To Transaction Commit</h2> |
| 43 | |
| 44 | <p> |
| 45 | The content files that comprise the global state of a fossil respository |
| 46 | are stored in the repository as a tree. The leaves of the tree are |
| 47 | stored as zlib-compressed BLOBs. Interior nodes are deltas from their |
| 48 | decendants. A lot of encoding is going on. There is |
| 49 | zlib-compression which is relatively well-tested but still might |
| 50 | cause corruption if used improperly. And there is the relatively |
| 51 | new delta-encoding mechanism designed expressly for fossil. We want |
| 52 | to make sure that bugs in these encoding mechanisms do not lead to |
| 53 | loss of data. |
| 54 | </p> |
| 55 | |
| 56 | <p> |
| 57 | To increase our confidence that everything in the repository is |
| 58 | recoverable, fossil makes sure it can extract an exact replicate |
| 59 | of every content file that it changes just prior to transaction |
| 60 | commit. So during the course of check-in (or other repository |
| 61 | operation) many different files |
| @@ -66,23 +54,19 @@ | |
| 66 | file. Then just before transaction commit, fossil re-extracts |
| 67 | the original content of all files that were written, computes |
| 68 | the SHA1 checksum again, and verifies that the checksums match. |
| 69 | If anything does not match up, an error |
| 70 | message is printed and the transaction rolls back. |
| 71 | </p> |
| 72 | |
| 73 | <p> |
| 74 | So, in other words, fossil always checks to make sure it can |
| 75 | re-extract a file before it commits a change to that file. |
| 76 | Hence bugs in fossil are unlikely to corrupt the repository in |
| 77 | a way that prevents us from extracting historical versions of |
| 78 | files. |
| 79 | </p> |
| 80 | |
| 81 | <h2>Checksum Over All Files In A Check-in</h2> |
| 82 | |
| 83 | <p> |
| 84 | Manifest artifacts that define a check-in have two fields (the |
| 85 | R-card and Z-card) that record MD5 hashs of the manifest itself |
| 86 | and of all other files in the manifest. Prior to any check-in |
| 87 | commit, these checksums are verified to ensure that the check-in |
| 88 | checked in agrees exactly with what is on disk. Similarly, |
| @@ -89,6 +73,33 @@ | |
| 89 | the repository checksum is verified after a checkout to make |
| 90 | sure that the entire repository was checked out correctly. |
| 91 | Note that these added checks use a different hash (MD5 instead |
| 92 | of SHA1) in order to avoid common-mode failures in the hash |
| 93 | algorithm implementation. |
| 94 | </p> |
| 95 |
| --- www/selfcheck.wiki | |
| +++ www/selfcheck.wiki | |
| @@ -1,61 +1,49 @@ | |
| 1 | <title>Fossil Repository Integrity Self-Checks</title> |
| 2 | |
| 3 | <h1 align="center">Fossil Repository Integrity Self-Checks</h1> |
| 4 | |
| 5 | Fossil is designed with features to give it a high level |
| 6 | of integrity so that users can have confidence that content will |
| 7 | never be mangled or lost by Fossil. |
| 8 | This note describes the defensive measures that |
| 9 | Fossil uses to help prevent information loss due to bugs. |
| 10 | |
| 11 | Fossil has been hosting itself and many other projects for |
| 12 | years now. Many bugs have been encountered. But, thanks in large |
| 13 | part to the defensive measures described here, no data has been |
| 14 | lost. The integrity checks are doing their job well.</p> |
| 15 | |
| 16 | <h2>Atomic Check-ins With Rollback</h2> |
| 17 | |
| 18 | The fossil repository is an |
| 19 | <a href="http://www.sqlite.org/">SQLite version 3</a> database file. |
| 20 | SQLite is very mature and stable and has been in wide-spread use for many |
| 21 | years, so we are confident it will not cause repository |
| 22 | corruption. SQLite |
| 23 | databases do not corrupt even if a program or system crash or power |
| 24 | failure occurs in the middle of the update. If some kind of crash |
| 25 | does occur in the middle of a change, then all the changes are rolled |
| 26 | back the next time that the database is accessed. |
| 27 | |
| 28 | A check-in operation in fossil makes many changes to the repository |
| 29 | database. But all these changes happen within a single transaction. |
| 30 | If something goes wrong in the middle of the commit, then the transaction |
| 31 | is rolled back and the database is unchanged. |
| 32 | |
| 33 | <h2>Verification Of Delta Encodings Prior To Transaction Commit</h2> |
| 34 | |
| 35 | The content files that comprise the global state of a fossil respository |
| 36 | are stored in the repository as a tree. The leaves of the tree are |
| 37 | stored as zlib-compressed BLOBs. Interior nodes are deltas from their |
| 38 | decendants. A lot of encoding is going on. There is |
| 39 | zlib-compression which is relatively well-tested but still might |
| 40 | cause corruption if used improperly. And there is the relatively |
| 41 | new delta-encoding mechanism designed expressly for fossil. We want |
| 42 | to make sure that bugs in these encoding mechanisms do not lead to |
| 43 | loss of data. |
| 44 | |
| 45 | To increase our confidence that everything in the repository is |
| 46 | recoverable, fossil makes sure it can extract an exact replicate |
| 47 | of every content file that it changes just prior to transaction |
| 48 | commit. So during the course of check-in (or other repository |
| 49 | operation) many different files |
| @@ -66,23 +54,19 @@ | |
| 54 | file. Then just before transaction commit, fossil re-extracts |
| 55 | the original content of all files that were written, computes |
| 56 | the SHA1 checksum again, and verifies that the checksums match. |
| 57 | If anything does not match up, an error |
| 58 | message is printed and the transaction rolls back. |
| 59 | |
| 60 | So, in other words, fossil always checks to make sure it can |
| 61 | re-extract a file before it commits a change to that file. |
| 62 | Hence bugs in fossil are unlikely to corrupt the repository in |
| 63 | a way that prevents us from extracting historical versions of |
| 64 | files. |
| 65 | |
| 66 | <h2>Checksum Over All Files In A Check-in</h2> |
| 67 | |
| 68 | Manifest artifacts that define a check-in have two fields (the |
| 69 | R-card and Z-card) that record MD5 hashs of the manifest itself |
| 70 | and of all other files in the manifest. Prior to any check-in |
| 71 | commit, these checksums are verified to ensure that the check-in |
| 72 | checked in agrees exactly with what is on disk. Similarly, |
| @@ -89,6 +73,33 @@ | |
| 73 | the repository checksum is verified after a checkout to make |
| 74 | sure that the entire repository was checked out correctly. |
| 75 | Note that these added checks use a different hash (MD5 instead |
| 76 | of SHA1) in order to avoid common-mode failures in the hash |
| 77 | algorithm implementation. |
| 78 | |
| 79 | |
| 80 | <h2>Checksums On Control Artifacts And Deltas</h2> |
| 81 | |
| 82 | Every [./fileformat.wiki | control artifact] in a fossil repository |
| 83 | contains a "Z-card" bearing an MD5 checksum over the rest of the |
| 84 | artifact. Any mismatch causes the control artifact to be ignored. |
| 85 | |
| 86 | The [./delta_format.wiki | file delta format] includes a 32-bit |
| 87 | checksum of the target file. Whenever a file is reconstructed from |
| 88 | a delta, that checksum is verified to make sure the reconstruction |
| 89 | was done correctly. |
| 90 | |
| 91 | <h2>Reliability Versus Performance</h2> |
| 92 | |
| 93 | Some version control systems make a big deal out of being "high performance" |
| 94 | or the "fastest version control system". Fossil makes no such claims and has |
| 95 | no such ambition. Indeed, profiling indicates that fossil bears a |
| 96 | substantial performance cost for |
| 97 | doing all of the checksumming and verification outlined above. |
| 98 | Fossil takes the philosophy of the |
| 99 | <a href="http://en.wikipedia.org/wiki/The_Tortoise_and_the_Hare">tortoise</a>: |
| 100 | reliability is more important than raw speed. The developers of |
| 101 | fossil see no merit in getting the wrong answer quickly. |
| 102 | |
| 103 | Fossil may not be the fastest versioning system, but it is "fast enough". |
| 104 | Fossil runs quickly enough to stay out of the developers way. |
| 105 | Most operations complete in under a second. |
| 106 |
+1
| --- www/stats.wiki | ||
| +++ www/stats.wiki | ||
| @@ -1,5 +1,6 @@ | ||
| 1 | +<title>Fossil Performance</title> | |
| 1 | 2 | <h1 align="center">Performance Statistics</h1> |
| 2 | 3 | |
| 3 | 4 | The questions will inevitably arise: How does Fossil perform? |
| 4 | 5 | Does it use a lot of disk space or bandwidth? Is it scalable? |
| 5 | 6 | |
| 6 | 7 |
| --- www/stats.wiki | |
| +++ www/stats.wiki | |
| @@ -1,5 +1,6 @@ | |
| 1 | <h1 align="center">Performance Statistics</h1> |
| 2 | |
| 3 | The questions will inevitably arise: How does Fossil perform? |
| 4 | Does it use a lot of disk space or bandwidth? Is it scalable? |
| 5 | |
| 6 |
| --- www/stats.wiki | |
| +++ www/stats.wiki | |
| @@ -1,5 +1,6 @@ | |
| 1 | <title>Fossil Performance</title> |
| 2 | <h1 align="center">Performance Statistics</h1> |
| 3 | |
| 4 | The questions will inevitably arise: How does Fossil perform? |
| 5 | Does it use a lot of disk space or bandwidth? Is it scalable? |
| 6 | |
| 7 |