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. 8Fossil is software that is designed to control and track the 9development of a software project and to record the history 10of the project. 11There are many such systems in use today. Fossil strives to 12distinguish itself from the others by being extremely simple 13to setup and operate. 14 15This document is intended as a quick introduction to the concepts 16behind Fossil. 17 18See also: 19 20 * [./whyusefossil.wiki#definitions|Definitions] 21 * [./quickstart.wiki|Quick start guide] 22 23<h2>2.0 Composition Of A Project</h2> 24 25<verbatim type="pikchr float-right"> 26R1: cylinder "Remote" "Repository" fill 0xadd8e6 rad 70% 27R2: cylinder same "Remote" "Repository" at 2.5*R1.wid right of R1 28 spline <-> from R1.e to 0.6<R1.se,R2.sw> then to 0.4<R1.ne,R2.nw> then to R2.w 29 text "HTTP" at .5<R1.ne,R2.nw> 30R3: cylinder same "Local" "Repository" fill 0x90ee90 \ 31 at dist(R1.e,R2.w) below .5<R1,R2> 32 spline <-> from .5<R1.s,R1.se> to 0.6<R1.s,R3.w> to 0.5<R1.se,R3.n> to .5<R3.nw,R3.n> "HTTP" \ 33 behind R1 34 spline <-> from R2.sw to .6<R2.sw,R3.n> to .5<R2.s,R3.e> to R3.ne "HTTP" ljust 35T1: line from 1.0cm heading 200 from R3.sw go 2.2cm heading 150 then 2.2cm west close \ 36 fill 0xffff00 "Local" below "Source Tree" below 37T2: line from 1.0cm heading 160 from R3.se same "Local" below "Source Tree" below 38 line <-> from R3.sw to T1.start 39 line <-> from R3.se to T2.start 40</verbatim> 41 42A software project normally consists of a "source tree". 43A source tree is a hierarchy of files that are used to generate 44the end product. The source tree changes over time as the 45software grows and expands and as features are added and bugs 46are fixed. A snapshot of the source tree at any point in time 47is called a "version" or "revision" or a "baseline" of the product. 48In Fossil, we use the name "check-in". 49 50A "repository" is a database that contains copies of all historical 51check-ins for a project. Check-ins are normally stored in the 52repository in a highly space-efficient compressed format (delta encoding). 53But that is an implementation detail that you the user need not worry over. 54Think of the repository as a safe place where all your old check-ins are 55securely stored away and available for retrieval whenever you need 56them. 57 58A repository in Fossil is a single file on your disk. This file 59might be rather large (dozens or hundreds of megabytes for a large 60or long running project) but it is nevertheless just a file. You 61can move it around, rename it, write it out to a memory stick, or 62do anything else you normally do with files. 63 64Each source tree that is controlled by Fossil is associated with 65a single repository on the local disk drive. You can tie two or more 66source trees to a single repository if you want (though one 67tree per repository is the most common configuration.) So a 68single repository can be associated with many source trees, but 69each source tree is associated with only one repository. 70 71Fossil source trees may not overlap. A Fossil source tree is identified 72by a file named "_FOSSIL_" (or ".fslckout", but this article will always 73use the name "_FOSSIL_") in the root directory of the source tree. Every 74file that is a sibling of _FOSSIL_ and every file in every subfolder is 75considered potentially a part of the source tree. The _FOSSIL_ file 76contains (among other things) the pathname of the repository with which 77the source tree is associated. On the other hand, the repository has 78no record of its source trees. So you are free to delete a source tree 79or move it around without consequence. But if you move or rename or 80delete a repository, then any source trees associated with that repository 81will no longer be able to locate their repository and will stop working. 82 83When multiple developers are working on the same project, each 84developer typically has his or her own local repository and an associated 85source tree in which to work. Developers share their work by 86"syncing" the content of their local repositories either directly 87or through a central server. Changes can "push" from the local 88repository into a remote repository. Or changes can "pull" from a 89remote repository into a local repository. Or one can do a "sync" 90which is a shortcut for doing both a push and a pull at the same time. 91Fossil also has the concept of "cloning". A "clone" is like a "pull", 92except that instead of beginning with an existing local repository, 93a clone begins with nothing and creates a new local repository that 94is a duplicate of a remote repository. 95 96Communication between repositories is via HTTP. Remote 97repositories are identified by URL. You can also point a web browser 98at a repository and get human-readable status, history, and tracking 99information about the project. 100 101<h3 id="artifacts">2.1 Identification Of Artifacts</h3> 102 103A particular version of a particular file is called an "artifact". Each 104artifact has a universally unique name which is the <a 105href="http://en.wikipedia.org/wiki/SHA1">SHA1</a> or <a 106href="http://en.wikipedia.org/wiki/SHA3">SHA3-256</a> hash of the 107content of that file expressed as either 40 or 64 characters of 108lower-case hexadecimal. (See the [./hashpolicy.wiki|hash policy 109document] for information on which algorithm is used, when.) Such a hash 110is referred to as the Artifact ID. These hash algorithms were created 111with Fossil's purpose in mind: to provide a highly forgery-resistant 112identifier for a blob of data, such as a file. Given any file, it is 113simple to find the artifact ID for that file. But given an artifact ID, 114it is computationally intractable to generate a file that will have that 115same artifact ID. 116 117Artifact IDs look something like this: 118 119<blockquote><b> 1206089f0b563a9db0a6d90682fe47fd7161ff867c8<br> 12159712614a1b3ccfd84078a37fa5b606e28434326<br> 12219dbf73078be9779edd6a0156195e610f81c94f9<br> 123b4104959a67175f02d6b415480be22a239f1f077<br> 124997c9d6ae03ad114b2b57f04e9eeef17dcb82788 125</b></blockquote> 126 127When referring to an artifact using Fossil, you can use a unique 128prefix of the artifact ID that is four characters or longer. This saves 129a lot of typing. When displaying artifact IDs, Fossil will usually only 130show the first 10 digits since that is normally enough to uniquely 131identify a file. 132 133Changing (or adding or removing) a single byte in a file results 134in a completely different artifact ID. And since the artifact ID is the name of 135the artifact, making any change to a file results in a new artifact. 136In this way, artifacts are immutable. 137 138A repository is really just an unordered collection of 139artifacts. New artifacts can be added to the repository, but 140existing artifacts can never be removed. (Well, almost never. There 141is a [./shunning.wiki | "shunning"] mechanism that allows spam or other 142inappropriate content to be removed if absolutely necessary, but such 143removal is discouraged.) 144Fossil is designed in 145such a way that it can be handed a set of artifacts in any 146order and it can figure out the relationship between those 147artifacts and reconstruct the complete development history of 148a software project. 149 150<h3>2.2 Manifests</h3> 151 152Associated with every check-in is a special file called the 153[./fileformat.wiki#manifest| "manifest"]. The manifest is a 154listing of all other files in 155that source tree. The manifest contains the (complete) artifact ID 156of the file and the name of the file as it appears on disk, 157and thus serves as a mapping from artifact ID to disk name. The artifact ID 158of the manifest is the identifier for the entire check-in. When 159you look at a "timeline" of changes in Fossil, the ID associated 160with each check-in or commit is really just the artifact ID of the 161manifest for that check-in. 162 163<p>The manifest file is not normally a real file on disk. Instead, 164the manifest is computed in memory by Fossil whenever it needs it. 165However, the "fossil setting manifest on" command will cause the 166manifest file to be materialized to disk, if desired. Both Fossil 167itself, and SQLite cause the manifest file to be materialized to disk 168so that the makefiles for these project can read the manifest and 169embed version information in generated binaries. 170 171<p>Fossil automatically generates a manifest whenever you "commit" 172a new check-in. So this is not something that you, the developer, 173need to worry with. The format of a manifest is intentionally 174designed to be simple to parse, so that if 175you want to read and interpret a manifest, either by hand or 176with a script, that is easy to do. But you will probably never 177need to do so.</p> 178 179<p>In addition to identifying all files in the check-in, a 180manifest also contains a check-in comment, the date and time 181when the check-in was established, who created the check-in, 182and links to other check-ins from which the current check-in 183is derived. There is also a couple of checksums used to verify 184the integrity of the check-in. And the whole manifest might 185be PGP clearsigned.</p> 186 187<h3 id="keyconc">2.3 Key concepts</h3> 188 189<ul> 190<li>A <b>check-in</b> is a set of files arranged 191 in a hierarchy.</li> 192<li>A <b>repository</b> keeps a record of historical check-ins.</li> 193<li>Repositories share their changes using <b>push</b>, <b>pull</b>, 194 <b>sync</b>, and <b>clone</b>.</li> 195<li>A particular <u>version</u> of a particular file is an <b>artifact</b> 196 that is identified by an <b>artifact ID</b>.</li> 197<li>Artifacts tracked by Fossil are inherently immutable.</li> 198<li>Fossil automatically generates a <b>manifest</b> file that identifies 199 every artifact in a check-in.</li> 200<li>The artifact ID of the manifest is the identifier of the check-in.</li> 201</ul> 202 203<h2>3.0 Fossil - The Program</h2> 204 205Fossil is software. The implementation of Fossil is in the form 206of a single executable named "fossil" (or "fossil.exe" on Windows). 207To install Fossil on your system, 208all you have to do is obtain a copy of this one executable file (either 209by downloading a 210<a href="https://fossil-scm.org/home/uv/download.html">pre-compiled version</a> 211or [./build.wiki | compiling it yourself]) and then 212putting that file somewhere on your PATH. 213 214Fossil is completely self-contained. It is not necessary to 215install any other software in order to use Fossil. You do <u>not</u> need 216CVS, gzip, diff, rsync, Python, Perl, Tcl, Java, Apache, PostgreSQL, MySQL, 217SQLite, patch, or any similar software on your system in order to use 218Fossil effectively. You will want to have some kind of text editor 219for entering check-in comments. Fossil will use whatever text editor 220is identified by your VISUAL environment variable. Fossil will also 221use GPG to clearsign your manifests if you happen to have it installed, 222but Fossil will skip that step if GPG missing from your system. 223You can optionally set up Fossil to use external "diff" programs, 224though Fossil has an excellent built-in "diff" algorithm that works 225fine for most people. If you happen to have Tcl/Tk installed on your 226system, Fossil will use it to generate a graphical "diff" display when 227you use the --tk option to the "diff" command, but this too is entirely 228optional. 229 230 231To uninstall Fossil, simply delete the executable. 232 233To upgrade an older version of Fossil to a newer version, just 234replace the old executable with the new one. You might need to 235run "<b>fossil all rebuild</b>" to restructure your repositories after 236an upgrade. Running "all rebuild" never hurts, so when upgrading it 237is a good policy to run it even if it is not strictly necessary. 238 239To use Fossil, simply type the name of the executable in your 240shell, followed by one of the various built-in commands and 241arguments appropriate for that command. For example: 242 243<blockquote><b> 244fossil help 245</b></blockquote> 246 247In the next section, when we say things like "use the <b>help</b> 248command" we mean to use the command name "help" as the first 249token after the name of the Fossil executable, as shown above. 250 251<h2 id="workflow">4.0 Workflow</h2> 252 253<verbatim type="pikchr float-right"> 254 down 255R1: cylinder "Remote" "Repository" fill 0xadd8e6 rad 70% 256 move 150% 257R2: cylinder same "Local" "Repository" fill 0x90ee90 258 move 120% 259T1: line go 2.2cm heading 150 then 2.2cm west close \ 260 fill 0xffff00 "Local" below "Source Tree" below 261 arrow from R2.n+(-0.25cm,+0.25cm) to R1.s+(-0.25cm,-0.25cm) \ 262 "push " rjust 263 arrow from R1.s+(+0.25cm,-0.25cm) to R2.n+(+0.25cm,+0.25cm) \ 264 " pull" ljust " clone" ljust 265 arrow from T1.start+(-0.25cm,+0cm) to R2.s+(-0.25cm,-0.25cm) \ 266 "commit " rjust 267 arrow from R2.s+(+0.25cm,-0.25cm) to T1.start+(+0.25cm,+0cm) \ 268 " open" ljust " update" ljust " merge" ljust 269</verbatim> 270 271 272Fossil has two modes of operation: <i>"autosync"</i> and 273<i>"manual-merge"</i> 274Autosync mode is reminiscent of CVS or SVN in that it automatically 275keeps your changes in synchronization with your co-workers through 276the use of a central server. The manual-merge mode is the standard workflow 277for GIT or Mercurial in that your local repository develops 278independently of your coworkers and you share and merge your changes manually. 279An interesting feature of Fossil is that it supports both autosync 280and manual-merge work flows. 281 282The default setting for Fossil is to be in autosync mode. You 283can change the autosync setting or check the current autosync 284setting using commands like: 285 286<blockquote> 287<b>fossil setting autosync on<br> 288fossil setting autosync off<br> 289<b>fossil settings</b> 290</blockquote> 291 292By default, Fossil runs with autosync mode turned on. The 293authors finds that projects run more smoothly in autosync mode since 294autosync helps to prevent pointless forking and merging and helps keeps 295all collaborators working on exactly the same code rather than on their 296own personal forks of the code. In the author's view, manual-merge mode 297should be reserved for disconnected operation. 298 299<h3>4.1 Autosync Workflow</h3> 300 301<ol> 302<li> 303Establish a local repository using either the <b>new</b> command 304to start a new project, or the <b>clone</b> command to make a clone 305of a repository for an existing project. 306</li> 307 308<li> 309Establish one or more source trees using 310the <b>open</b> command with the name of the repository file as its 311argument. 312</li> 313 314<li> 315The <b>open</b> command in the previous step populates your local source 316tree with a copy of the latest check-in. Usually this is what you want. 317In the rare cases where it is not, use the <b>update</b> command to 318switch to a different check-in. 319Use the <b>timeline</b> or <b>leaves</b> commands 320to identify alternative check-ins to switch to. 321</li> 322 323<li> 324Edit the code. Add new files to the source tree using the <b>add</b> 325command. Omit files from future check-ins using the <b>rm</b> command. 326(Even when you remove files from future check-ins, those files continue 327to exist in historical check-ins.) Test your changes. 328</li> 329 330<li> 331Create a new check-in using the <b>commit</b> command. You will be prompted 332for a check-in comment and also for your GPG key if you have GPG installed. 333The commit copies the edits you have made in your local source 334tree into your local repository. After your commit completes, Fossil will 335automatically <b>push</b> your changes back to the server 336you cloned from or whatever server you most recently synced with. 337</li> 338 339<li> 340When your coworkers make their own changes, you can merge those changes 341into your local local source tree using the <b>update</b> command. 342In autosync mode, <b>update</b> will first go back to the server you 343cloned from or with which you most recently synced, and pull down all 344recent changes into your local repository. Then it will merge recent 345changes into your local source tree. If you do an <b>update</b> and 346find that it messes something up in your source tree (perhaps a co-worker 347checked in incompatible changes) you can use the <b>undo</b> command 348to back out the changes. 349</li> 350 351<li> 352Repeat all of the above until you have generated great software. 353</li> 354</ol> 355 356<h3>4.2 Manual-Merge Workflow</h3> 357 358When autosync is disabled, the <b>commit</b> command is decoupled from 359<b>push</b> and the <b>update</b> command is decoupled from <b>pull</b>. 360That means you have to do a few extra steps in order to accomplish the 361<b>push</b> and <b>pull</b> tasks manually. 362 363<ol> 364<li> 365Establish a local repository using either the <b>new</b> command 366to start a new project, or the <b>clone</b> command to make a clone 367of a repository for an existing project. The default setting for 368a new repository is with autosync on, so you will need to turn it off 369using the <b>setting autosync off</b> command with a <b>-R</b> option 370to specify the repository. 371</li> 372 373<li> 374Establish one or more source trees by changing your working directory 375to where you want the root of the source tree to be, then issuing 376the <b>open</b> command with the name of the repository file as its 377argument. 378</li> 379 380<li> 381The <b>open</b> command in the previous step populates your local source 382tree with a copy of the latest check-in. Usually this is what you want. 383In the rare cases where it is not, use the <b>update</b> command to 384switch to a different check-in. 385Use the <b>timeline</b> or <b>leaves</b> commands 386to identify alternative check-ins to switch to. 387</li> 388 389<li> 390Edit the code. Add new files to the source tree using the <b>add</b> 391command. Omit files from future check-ins using the <b>rm</b> command. 392(Even when you remove files from future check-ins, those files continue 393to exist in historical check-ins.) Test your changes. 394</li> 395 396<li> 397Create a new check-in using the <b>commit</b> command. You will be prompted 398for a check-in comment and also for your GPG key if you have GPG installed. 399The commit copies the edits you have made in your local source 400tree into your local repository. 401</li> 402 403<li> 404Use the <b>push</b> command to push your changes out to a server 405where your co-workers can access them. 406</li> 407 408<li> 409When co-workers make their own changes, use the <b>pull</b> command 410to pull those changes into your local repository. Note that <b>pull</b> 411does not move the changes into your local source tree, only into your 412local repository. 413</li> 414 415<li> 416Once changes are in your local repository, use 417the <b>update</b> command to merge them to your local source tree. 418If you merge in some changes and find that the changes do not work out 419or are not to your liking, you can back out the changes using the 420<b>undo</b> command. 421</li> 422 423<li> 424If two or more people ran "commit" against the same check-in, this will 425result in a [./branching.wiki | fork] which you may want to resolve by 426running <b>merge</b> followed by another <b>commit</b>. 427</li> 428 429<li> 430Repeat all of the above until you have generated great software. 431</li> 432</ol> 433 434<h2>5.0 Setting Up A Fossil Server</h2> 435 436With other configuration management software, setting up a server is 437a lot of work and normally takes time, patience, and a lot of system 438knowledge. Fossil is designed to avoid this frustration. Setting up 439a server with Fossil is ridiculously easy. You have four options:</p> 440 441<ol> 442<li><p><b>Stand-alone server.</b> 443Simply run the [/help?cmd=server|fossil server] or 444[/help?cmd=ui|fossil ui] command from the command-line. 445 446<li><p><b>CGI.</b> 447Install a 2-line CGI script on a CGI-enabled web-server like Apache. 448 449<li><p><b>SCGI.</b> 450Start an SCGI server using the 451[/help?cmd=server| fossil server --scgi] command for handling 452SCGI requests from web-servers like Nginx. 453 454<li><p><b>Inetd or Stunnel.</b> 455Configure programs like inetd, xinetd, or stunnel to hand off HTTP requests 456directly to the [/help?cmd=http|fossil http] command. 457</ol> 458 459See the [./server/ | How To Configure A Fossil Server] document 460for details. 461 462<h2>6.0 Review Of Key Concepts</h2> 463 464<ul> 465<li>The <b>fossil</b> program is a self-contained stand-alone executable. 466 Just put it somewhere on your PATH to install it.</li> 467<li>Use the <b>clone</b> or <b>new</b> commands to create a new repository.</li> 468<li>Use the <b>open</b> command to create a new source tree.</li> 469<li>Use the <b>add</b> and <b>rm</b> or <b>delete</b> commands to add and 470 remove files from the local source tree.</li> 471<li>Use the <b>commit</b> command to create a new check-in.</li> 472<li>Use the <b>update</b> command to merge in changes from others.</li> 473<li>The <b>push</b> and <b>pull</b> commands can be used to share changes 474 manually, but these things happen automatically in the default 475 autosync mode.</li> 476</ul> 477