5523218023 2009-08-24 drh: <title>Fossil Concepts</title> 5523218023 2009-08-24 drh: <h1 align="center">Fossil Concepts</h1> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <h2>1.0 Introduction</h2> 522824b26a 2009-08-28 drh: 522824b26a 2009-08-28 drh: [./index.wiki | Fossil] is a 522824b26a 2009-08-28 drh: [http://en.wikipedia.org/wiki/Software_configuration_management | software configuration management] system. d87ca60c58 2008-05-15 stephan: Fossil is software that is designed to control and track the d87ca60c58 2008-05-15 stephan: development of a software project and to record the history d87ca60c58 2008-05-15 stephan: of the project. d87ca60c58 2008-05-15 stephan: There are many such systems in use today. Fossil strives to d87ca60c58 2008-05-15 stephan: distinguish itself from the others by being extremely simple 522824b26a 2009-08-28 drh: to setup and operate. 522824b26a 2009-08-28 drh: 522824b26a 2009-08-28 drh: This document is intended as a quick introduction to the concepts 522824b26a 2009-08-28 drh: behind fossil. d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <h2>2.0 Composition Of A Project</h2> d87ca60c58 2008-05-15 stephan: <img src="concept1.gif" align="right" hspace="10"> d87ca60c58 2008-05-15 stephan: 522824b26a 2009-08-28 drh: A software project normally consists of a "source tree". d87ca60c58 2008-05-15 stephan: A source tree is a hierarchy of files that are used to generate d87ca60c58 2008-05-15 stephan: the end product. The source tree changes over time as the d87ca60c58 2008-05-15 stephan: software grows and expands and as features are added and bugs d87ca60c58 2008-05-15 stephan: are fixed. A snapshot of the source tree at any point in time d87ca60c58 2008-05-15 stephan: is called a "version" or "revision" or a "baseline" of the product. 522824b26a 2009-08-28 drh: In fossil, we use the name "check-in". 522824b26a 2009-08-28 drh: 522824b26a 2009-08-28 drh: A "repository" is a database that contains copies of all historical 904ee40b93 2009-01-23 drh: check-ins for a project. Check-ins are normally stored in the d87ca60c58 2008-05-15 stephan: repository in a highly space-efficient compressed format (delta encoding). d87ca60c58 2008-05-15 stephan: But that is an implementation detail that you the user need not worry over. 904ee40b93 2009-01-23 drh: Think of the repository as a safe place where all your old check-ins are d87ca60c58 2008-05-15 stephan: securely stored away and available for retrieval whenever you need 522824b26a 2009-08-28 drh: them. 522824b26a 2009-08-28 drh: 522824b26a 2009-08-28 drh: A repository in fossil is a single file on your disk. This file d87ca60c58 2008-05-15 stephan: might be rather large (dozens or hundreds of megabytes for a large d87ca60c58 2008-05-15 stephan: or long running project) but it is nevertheless just a file. You d87ca60c58 2008-05-15 stephan: can move it around, rename it, write it out to a memory stick, or 522824b26a 2009-08-28 drh: do anything else you normally do with files. 522824b26a 2009-08-28 drh: 522824b26a 2009-08-28 drh: Each source tree that is controlled by fossil is associated with d87ca60c58 2008-05-15 stephan: a single repository on the local disk drive. You can tie two or more d87ca60c58 2008-05-15 stephan: source trees to a single repository if you want (though one d87ca60c58 2008-05-15 stephan: tree per repository is the most common configuration.) So a d87ca60c58 2008-05-15 stephan: single repository can be associated with many source trees, but 522824b26a 2009-08-28 drh: each source tree is associated with only one repository. 522824b26a 2009-08-28 drh: 522824b26a 2009-08-28 drh: Fossil source trees may not overlap. A fossil source tree is identified d87ca60c58 2008-05-15 stephan: by a file named "_FOSSIL_" in the root directory of the source tree. Every d87ca60c58 2008-05-15 stephan: file that is a sibling of _FOSSIL_ and every file in every subfolder is d87ca60c58 2008-05-15 stephan: considered potentially a part of the source tree. The _FOSSIL_ file d87ca60c58 2008-05-15 stephan: contains (among other things) the pathname of the repository with which d87ca60c58 2008-05-15 stephan: the source tree is associated. On the other hand, the repository has d87ca60c58 2008-05-15 stephan: no record of its source trees. So you are free to delete a source tree d87ca60c58 2008-05-15 stephan: or move it around without consequence. But if you move or rename or d87ca60c58 2008-05-15 stephan: delete a repository, then any source trees associated with that repository 522824b26a 2009-08-28 drh: will no longer be able to locate their repository and will stop working. 522824b26a 2009-08-28 drh: 522824b26a 2009-08-28 drh: When multiple developers are working on the same project, each d87ca60c58 2008-05-15 stephan: developer typically has his or her own local repository and an associated d87ca60c58 2008-05-15 stephan: source tree in which to work. Developers share their work by d87ca60c58 2008-05-15 stephan: "syncing" the content of their local repositories either directly d87ca60c58 2008-05-15 stephan: or through a central server. Changes can "push" from the local d87ca60c58 2008-05-15 stephan: repository into a remote repository. Or changes can "pull" from a d87ca60c58 2008-05-15 stephan: remote repository into a local repository. Or one can do a "sync" d87ca60c58 2008-05-15 stephan: which is a shortcut for doing both a push and a pull at the same time. d87ca60c58 2008-05-15 stephan: Fossil also has the concept of "cloning". A "clone" is like a "pull", d87ca60c58 2008-05-15 stephan: except that instead of beginning with an existing local repository, d87ca60c58 2008-05-15 stephan: a clone begins with nothing and creates a new local repository that 522824b26a 2009-08-28 drh: is a duplicate of a remote repository. 522824b26a 2009-08-28 drh: 522824b26a 2009-08-28 drh: Communication between repositories is via HTTP. Remote 9eb6ea75c1 2008-11-11 kejoki: repositories are identified by URL. You can also point a web browser d87ca60c58 2008-05-15 stephan: at a repository and get human-readable status, history, and tracking 522824b26a 2009-08-28 drh: information about the project. d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <h3>2.1 Identification Of Artifacts</h3> d87ca60c58 2008-05-15 stephan: 522824b26a 2009-08-28 drh: A particular version of a particular file is called an "artifact". d87ca60c58 2008-05-15 stephan: Each artifact has a universally unique name which is the d87ca60c58 2008-05-15 stephan: <a href="http://en.wikipedia.org/wiki/SHA">SHA1</a> hash of the content d87ca60c58 2008-05-15 stephan: of that file expressed as 40 characters of lower-case hexadecimal. Such e8c4f69c50 2008-10-24 drh: a hash is referred to as the Artifact Identifier or Artifact ID d87ca60c58 2008-05-15 stephan: for the artifact. The SHA1 algorithm is created with the purpose of 9eb6ea75c1 2008-11-11 kejoki: providing a highly forgery-resistant identifier for a file. Given any e8c4f69c50 2008-10-24 drh: file it is simple to find the artifact ID for that file. But given a e8c4f69c50 2008-10-24 drh: artifact ID it is computationally intractable to generate a file that will 522824b26a 2009-08-28 drh: have that Artifact ID. 522824b26a 2009-08-28 drh: 522824b26a 2009-08-28 drh: Artifact IDs look something like this: d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <blockquote><b> d87ca60c58 2008-05-15 stephan: 6089f0b563a9db0a6d90682fe47fd7161ff867c8<br> d87ca60c58 2008-05-15 stephan: 59712614a1b3ccfd84078a37fa5b606e28434326<br> d87ca60c58 2008-05-15 stephan: 19dbf73078be9779edd6a0156195e610f81c94f9<br> d87ca60c58 2008-05-15 stephan: b4104959a67175f02d6b415480be22a239f1f077<br> d87ca60c58 2008-05-15 stephan: 997c9d6ae03ad114b2b57f04e9eeef17dcb82788 d87ca60c58 2008-05-15 stephan: </b></blockquote> d87ca60c58 2008-05-15 stephan: 522824b26a 2009-08-28 drh: When referring to an artifact using fossil, you can use a unique e8c4f69c50 2008-10-24 drh: prefix of the artifact ID that is four characters or longer. This saves e8c4f69c50 2008-10-24 drh: a lot of typing. When displaying artifact IDs, fossil will usually only d87ca60c58 2008-05-15 stephan: show the first 10 digits since that is normally enough to uniquely 522824b26a 2009-08-28 drh: identify a file. 522824b26a 2009-08-28 drh: 522824b26a 2009-08-28 drh: Changing (or adding or removing) a single byte in a file results e8c4f69c50 2008-10-24 drh: in a completely different artifact ID. And since the artifact ID is the name of d87ca60c58 2008-05-15 stephan: the artifact, making any change to a file results in a new artifact. 522824b26a 2009-08-28 drh: In this way, artifacts are immutable. 522824b26a 2009-08-28 drh: 522824b26a 2009-08-28 drh: A repository is really just an unordered collection of d87ca60c58 2008-05-15 stephan: artifacts. New artifacts can be added to the repository, but 522824b26a 2009-08-28 drh: existing artifacts can never be removed. (Well, almost never. There 522824b26a 2009-08-28 drh: is a [./shunning.wiki | "shunning"] mechanism that allows spam or other 522824b26a 2009-08-28 drh: inappropriate content to be removed if absolutely necessary, but such 522824b26a 2009-08-28 drh: removal is discouraged.) 522824b26a 2009-08-28 drh: Fossil is designed in d87ca60c58 2008-05-15 stephan: such a way that it can be handed a set of artifacts in any d87ca60c58 2008-05-15 stephan: order and it can figure out the relationship between those d87ca60c58 2008-05-15 stephan: artifacts and reconstruct the complete development history of 522824b26a 2009-08-28 drh: a software project. d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <h3>2.2 Manifests</h3> d87ca60c58 2008-05-15 stephan: 522824b26a 2009-08-28 drh: At the root of a source tree is a special file called the d87ca60c58 2008-05-15 stephan: "manifest". The manifest is a listing of all other files in e8c4f69c50 2008-10-24 drh: that source tree. The manifest contains the (complete) artifact ID d87ca60c58 2008-05-15 stephan: of the file and the name of the file as it appears on disk, e8c4f69c50 2008-10-24 drh: and thus serves as a mapping from artifact ID to disk name. The artifact ID 904ee40b93 2009-01-23 drh: of the manifest is the identifier for the entire check-in. When e8c4f69c50 2008-10-24 drh: you look at a "timeline" of changes in fossil, the ID associated e8c4f69c50 2008-10-24 drh: with each check-in or commit is really just the artifact ID of the 522824b26a 2009-08-28 drh: manifest for that check-in. d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <p>Fossil automatically generates a manifest whenever you "commit" 904ee40b93 2009-01-23 drh: a new check-in. So this is not something that you, the developer, d87ca60c58 2008-05-15 stephan: need to worry with. The format of a manifest is intentionally d87ca60c58 2008-05-15 stephan: designed to be simple to parse, so that if d87ca60c58 2008-05-15 stephan: you want to read and interpret a manifest, either by hand or d87ca60c58 2008-05-15 stephan: with a script, that is easy to do. But you will probably never d87ca60c58 2008-05-15 stephan: need to do so.</p> d87ca60c58 2008-05-15 stephan: 904ee40b93 2009-01-23 drh: <p>In addition to identifying all files in the check-in, a d87ca60c58 2008-05-15 stephan: manifest also contains a check-in comment, the date and time 904ee40b93 2009-01-23 drh: when the check-in was established, who created the check-in, 904ee40b93 2009-01-23 drh: and links to other check-ins from which the current check-in d87ca60c58 2008-05-15 stephan: is derived. There is also a couple of checksums used to verify 904ee40b93 2009-01-23 drh: the integrity of the check-in. And the whole manifest might d87ca60c58 2008-05-15 stephan: be PGP clearsigned.</p> d87ca60c58 2008-05-15 stephan: 3c1234c0f2 2009-09-12 drh: <a name="keyconc"></a> d87ca60c58 2008-05-15 stephan: <h3>2.3 Key concepts</h3> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <ul> 904ee40b93 2009-01-23 drh: <li>A <b>check-in</b> is a set of files arranged d87ca60c58 2008-05-15 stephan: in a hierarchy.</li> 904ee40b93 2009-01-23 drh: <li>A <b>repository</b> keeps a record of historical check-ins.</li> d87ca60c58 2008-05-15 stephan: <li>Repositories share their changes using <b>push</b>, <b>pull</b>, d87ca60c58 2008-05-15 stephan: <b>sync</b>, and <b>clone</b>.</li> bc857ecd92 2009-02-13 kejoki: <li>A particular <u>version</u> of a particular file is an <b>artifact</b> e8c4f69c50 2008-10-24 drh: that is identified by an <b>artifact ID</b>.</li> d87ca60c58 2008-05-15 stephan: <li>Artifacts tracked by fossil are inherently immutable.</li> d87ca60c58 2008-05-15 stephan: <li>Fossil automatically generates a <b>manifest</b> file that identifies 904ee40b93 2009-01-23 drh: every artifact in a check-in.</li> 904ee40b93 2009-01-23 drh: <li>The artifact ID of the manifest is the identifier of the check-in.</li> d87ca60c58 2008-05-15 stephan: </ul> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <h2>3.0 Fossil - The Program</h2> d87ca60c58 2008-05-15 stephan: 522824b26a 2009-08-28 drh: Fossil is software. The implementation of fossil is in the form 3c1234c0f2 2009-09-12 drh: of a single executable named "fossil" (or "fossil.exe" on windows). 3c1234c0f2 2009-09-12 drh: To install fossil on your system, d87ca60c58 2008-05-15 stephan: all you have to do is obtain a copy of this one executable file (either 3c1234c0f2 2009-09-12 drh: by downloading a 3c1234c0f2 2009-09-12 drh: <a href="http://www.fossil-scm.org/download.html">pre-compiled version</a> 3c1234c0f2 2009-09-12 drh: or [./build.wiki | compiling it yourself]) and then 522824b26a 2009-08-28 drh: putting that file somewhere on your PATH. 522824b26a 2009-08-28 drh: 522824b26a 2009-08-28 drh: Fossil is completely self-contained. It is not necessary to d87ca60c58 2008-05-15 stephan: install any other software in order to use fossil. You do <u>not</u> need d87ca60c58 2008-05-15 stephan: CVS, gzip, diff, rsync, Python, Perl, Tcl, Java, apache, PostgreSQL, MySQL, d87ca60c58 2008-05-15 stephan: SQLite, patch, or any similar software on your system in order to use d87ca60c58 2008-05-15 stephan: fossil effectively. You will want to have some kind of text editor d87ca60c58 2008-05-15 stephan: for entering check-in comments. Fossil will use whatever text editor d87ca60c58 2008-05-15 stephan: is identified by your VISUAL environment variable. Fossil will also d87ca60c58 2008-05-15 stephan: use GPG to clearsign your manifests if you happen to have it installed, d87ca60c58 2008-05-15 stephan: but fossil will skip that step if GPG missing from your system. d87ca60c58 2008-05-15 stephan: You can optionally set up fossil to use external "diff" programs, bad9999d7d 2008-07-21 drh: though fossil has an excellent built-in "diff" algorithm that works 522824b26a 2009-08-28 drh: fine for most people. 522824b26a 2009-08-28 drh: 522824b26a 2009-08-28 drh: To uninstall fossil, simply delete the executable. 522824b26a 2009-08-28 drh: 522824b26a 2009-08-28 drh: To upgrade an older version of fossil to a newer version, just d87ca60c58 2008-05-15 stephan: replace the old executable with the new one. You might need to 522824b26a 2009-08-28 drh: run "<b>fossil all rebuild</b>" to restructure your repositories after 522824b26a 2009-08-28 drh: an upgrade. Running "all rebuild" never hurts, so when upgrading it 522824b26a 2009-08-28 drh: is a good policy to run it even if it is not strictly necessary. 522824b26a 2009-08-28 drh: 522824b26a 2009-08-28 drh: To use fossil, simply type the name of the executable in your d87ca60c58 2008-05-15 stephan: shell, followed by one of the various built-in commands and 522824b26a 2009-08-28 drh: arguments appropriate for that command. For example: d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <blockquote><b> d87ca60c58 2008-05-15 stephan: fossil help d87ca60c58 2008-05-15 stephan: </b></blockquote> d87ca60c58 2008-05-15 stephan: 522824b26a 2009-08-28 drh: In the next section, when we say things like "use the <b>help</b> d87ca60c58 2008-05-15 stephan: command" we mean to use the command name "help" as the first 522824b26a 2009-08-28 drh: token after the name of the fossil executable, as shown above. 522824b26a 2009-08-28 drh: 3c1234c0f2 2009-09-12 drh: <a name="workflow"></a> d87ca60c58 2008-05-15 stephan: <h2>4.0 Workflow</h2> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <img src="concept2.gif" align="right" hspace="10"> 16094f7ebc 2008-05-16 drh: 522824b26a 2009-08-28 drh: Fossil has two modes of operation: <i>"autosync"</i> and 522824b26a 2009-08-28 drh: <i>"manual-merge"</i> 522824b26a 2009-08-28 drh: Autosync mode is reminiscent of CVS or SVN in that it automatically 522824b26a 2009-08-28 drh: keeps your changes in synchronization with your co-workers through 522824b26a 2009-08-28 drh: the use of a central server. The manual-merge mode is the standard workflow 522824b26a 2009-08-28 drh: for GIT or Mercurial in that your local repository develops 522824b26a 2009-08-28 drh: independently of your coworkers and you share and merge your changes manually. 2e275c1420 2009-01-23 drh: An interesting feature of fossil is that it supports both autosync 522824b26a 2009-08-28 drh: and manual-merge work flows. 522824b26a 2009-08-28 drh: 522824b26a 2009-08-28 drh: The default setting for fossil is to be in autosync mode. You 26a2b61dbd 2008-05-29 drh: can change the autosync setting or check the current autosync 522824b26a 2009-08-28 drh: setting using commands like: 26a2b61dbd 2008-05-29 drh: 26a2b61dbd 2008-05-29 drh: <blockquote> 26a2b61dbd 2008-05-29 drh: <b>fossil setting autosync on<br> 26a2b61dbd 2008-05-29 drh: fossil setting autosync off<br> 26a2b61dbd 2008-05-29 drh: <b>fossil settings</b> 26a2b61dbd 2008-05-29 drh: </blockquote> 26a2b61dbd 2008-05-29 drh: 522824b26a 2009-08-28 drh: By default, fossil runs with autosync mode turned on. The 522824b26a 2009-08-28 drh: authors finds that projects run more smoothly in autosync mode since 522824b26a 2009-08-28 drh: autosync helps to prevent pointless forking and merge and helps keeps 522824b26a 2009-08-28 drh: all collaborators working on exactly the same code rather than on their 522824b26a 2009-08-28 drh: own personal forks of the code. In the author's view, manual-merge mode 522824b26a 2009-08-28 drh: should be reserved for disconnected operation. 26a2b61dbd 2008-05-29 drh: 26a2b61dbd 2008-05-29 drh: <h3>4.1 Autosync Workflow</h3> 26a2b61dbd 2008-05-29 drh: d87ca60c58 2008-05-15 stephan: <ol> 522824b26a 2009-08-28 drh: <li> d87ca60c58 2008-05-15 stephan: Establish a local repository using either the <b>new</b> command d87ca60c58 2008-05-15 stephan: to start a new project, or the <b>clone</b> command to make a clone d87ca60c58 2008-05-15 stephan: of a repository for an existing project. 522824b26a 2009-08-28 drh: </li> 522824b26a 2009-08-28 drh: 522824b26a 2009-08-28 drh: <li> d87ca60c58 2008-05-15 stephan: Establish one or more source trees by changing your working directory d87ca60c58 2008-05-15 stephan: to where you want the root of the source tree to be, then issuing d87ca60c58 2008-05-15 stephan: the <b>open</b> command with the name of the repository file as its d87ca60c58 2008-05-15 stephan: argument. 522824b26a 2009-08-28 drh: </li> 522824b26a 2009-08-28 drh: 522824b26a 2009-08-28 drh: <li> 26a2b61dbd 2008-05-29 drh: The <b>open</b> command in the previous step populates your local source 904ee40b93 2009-01-23 drh: tree with a copy of the latest check-in. Usually this is what you want. 26a2b61dbd 2008-05-29 drh: In the rare cases where it is not, use the <b>update</b> command to 904ee40b93 2009-01-23 drh: switch to a new check-in. Use the <b>timeline</b> or <b>leaves</b> commands 904ee40b93 2009-01-23 drh: to identify alternative check-ins to switch to. 522824b26a 2009-08-28 drh: </li> 522824b26a 2009-08-28 drh: 522824b26a 2009-08-28 drh: <li> d87ca60c58 2008-05-15 stephan: Edit the code. Add new files to the source tree using the <b>add</b> 904ee40b93 2009-01-23 drh: command. Omit files from future check-ins using the <b>rm</b> command. 904ee40b93 2009-01-23 drh: (Even when you remove files from future check-ins, those files continue 904ee40b93 2009-01-23 drh: to exist in historical check-ins.) Test your changes. 522824b26a 2009-08-28 drh: </li> 522824b26a 2009-08-28 drh: 522824b26a 2009-08-28 drh: <li> 904ee40b93 2009-01-23 drh: Create a new check-in using the <b>commit</b> command. You will be prompted d87ca60c58 2008-05-15 stephan: for a check-in comment and also for your GPG key if you have GPG installed. d87ca60c58 2008-05-15 stephan: The commit copies the edits you have made in your local source 26a2b61dbd 2008-05-29 drh: tree into your local repository. After your commit completes, fossil will 26a2b61dbd 2008-05-29 drh: automatically <b>push</b> your changes back to the server 26a2b61dbd 2008-05-29 drh: you cloned from or whatever server you most recently synced with. 522824b26a 2009-08-28 drh: </li> 522824b26a 2009-08-28 drh: 522824b26a 2009-08-28 drh: <li> 26a2b61dbd 2008-05-29 drh: When your coworkers make their own changes, you can merge those changes 26a2b61dbd 2008-05-29 drh: into your local local source tree using the <b>update</b> command. 26a2b61dbd 2008-05-29 drh: In autosync mode, <b>update</b> will first go back to the server you 26a2b61dbd 2008-05-29 drh: cloned from or with which you most recently synced, and pull down all 26a2b61dbd 2008-05-29 drh: recent changes into your local repository. Then it will merge recent 26a2b61dbd 2008-05-29 drh: changes into your local source tree. If you do an <b>update</b> and 26a2b61dbd 2008-05-29 drh: find that it messes something up in your source tree (perhaps a co-worker 26a2b61dbd 2008-05-29 drh: checked in incompatible changes) you can use the <b>undo</b> command 26a2b61dbd 2008-05-29 drh: to back out the changes. 522824b26a 2009-08-28 drh: </li> 522824b26a 2009-08-28 drh: 522824b26a 2009-08-28 drh: <li> 522824b26a 2009-08-28 drh: Repeat all of the above until you have generated great software. 522824b26a 2009-08-28 drh: </li> d87ca60c58 2008-05-15 stephan: </ol> d87ca60c58 2008-05-15 stephan: 522824b26a 2009-08-28 drh: <h3>4.2 Manual-Merge Workflow</h3> 522824b26a 2009-08-28 drh: 522824b26a 2009-08-28 drh: When autosync is disabled, the <b>commit</b> command is decoupled from 26a2b61dbd 2008-05-29 drh: <b>push</b> and the <b>update</b> command is decoupled from <b>pull</b>. 26a2b61dbd 2008-05-29 drh: That means you have to do a few extra steps in order to accomplish the 522824b26a 2009-08-28 drh: <b>push</b> and <b>pull</b> tasks manually. 26a2b61dbd 2008-05-29 drh: 26a2b61dbd 2008-05-29 drh: <ol> 522824b26a 2009-08-28 drh: <li> 26a2b61dbd 2008-05-29 drh: Establish a local repository using either the <b>new</b> command 26a2b61dbd 2008-05-29 drh: to start a new project, or the <b>clone</b> command to make a clone 26a2b61dbd 2008-05-29 drh: of a repository for an existing project. The default setting for 26a2b61dbd 2008-05-29 drh: a new repository is with autosync on, so you will need to turn it off 26a2b61dbd 2008-05-29 drh: using the <b>setting autosync off</b> command with a <b>-R</b> option 26a2b61dbd 2008-05-29 drh: to specify the repository. 522824b26a 2009-08-28 drh: </li> 522824b26a 2009-08-28 drh: 522824b26a 2009-08-28 drh: <li> 26a2b61dbd 2008-05-29 drh: Establish one or more source trees by changing your working directory 26a2b61dbd 2008-05-29 drh: to where you want the root of the source tree to be, then issuing 26a2b61dbd 2008-05-29 drh: the <b>open</b> command with the name of the repository file as its 26a2b61dbd 2008-05-29 drh: argument. 522824b26a 2009-08-28 drh: </li> 522824b26a 2009-08-28 drh: 522824b26a 2009-08-28 drh: <li> 26a2b61dbd 2008-05-29 drh: The <b>open</b> command in the previous step populates your local source 904ee40b93 2009-01-23 drh: tree with a copy of the latest check-in. Usually this is what you want. 26a2b61dbd 2008-05-29 drh: In the rare cases where it is not, use the <b>update</b> command to 904ee40b93 2009-01-23 drh: switch to a new check-in. Use the <b>timeline</b> or <b>leaves</b> commands 904ee40b93 2009-01-23 drh: to identify alternative check-ins to switch to. 522824b26a 2009-08-28 drh: </li> 522824b26a 2009-08-28 drh: 522824b26a 2009-08-28 drh: <li> 26a2b61dbd 2008-05-29 drh: Edit the code. Add new files to the source tree using the <b>add</b> 904ee40b93 2009-01-23 drh: command. Omit files from future check-ins using the <b>rm</b> command. 904ee40b93 2009-01-23 drh: (Even when you remove files from future check-ins, those files continue 904ee40b93 2009-01-23 drh: to exist in historical check-ins.) Test your changes. 522824b26a 2009-08-28 drh: </li> 522824b26a 2009-08-28 drh: 522824b26a 2009-08-28 drh: <li> 904ee40b93 2009-01-23 drh: Create a new check-in using the <b>commit</b> command. You will be prompted 26a2b61dbd 2008-05-29 drh: for a check-in comment and also for your GPG key if you have GPG installed. 26a2b61dbd 2008-05-29 drh: The commit copies the edits you have made in your local source 26a2b61dbd 2008-05-29 drh: tree into your local repository. 522824b26a 2009-08-28 drh: </li> 522824b26a 2009-08-28 drh: 522824b26a 2009-08-28 drh: <li> 522824b26a 2009-08-28 drh: Use the <b>push</b> command to push your changes out to a server 26a2b61dbd 2008-05-29 drh: where your co-workers can access them. 522824b26a 2009-08-28 drh: </li> 522824b26a 2009-08-28 drh: 522824b26a 2009-08-28 drh: <li> 26a2b61dbd 2008-05-29 drh: When co-workers make their own changes, use the <b>pull</b> command 26a2b61dbd 2008-05-29 drh: to pull those changes into your local repository. Note that <b>pull</b> 26a2b61dbd 2008-05-29 drh: does not move the changes into your local source tree, only into your 26a2b61dbd 2008-05-29 drh: local repository. 522824b26a 2009-08-28 drh: </li> 522824b26a 2009-08-28 drh: 522824b26a 2009-08-28 drh: <li> 26a2b61dbd 2008-05-29 drh: Once changes are in your local repository, use 26a2b61dbd 2008-05-29 drh: use the <b>update</b> command to merge them to your local source tree. 26a2b61dbd 2008-05-29 drh: If you merge in some changes and find that the changes do not work out 26a2b61dbd 2008-05-29 drh: or are not to your liking, you can back out the changes using the 26a2b61dbd 2008-05-29 drh: <b>undo</b> command. 522824b26a 2009-08-28 drh: </li> 522824b26a 2009-08-28 drh: 522824b26a 2009-08-28 drh: <li> 522824b26a 2009-08-28 drh: If two or more people ran "commit" against the same baseline, this will 522824b26a 2009-08-28 drh: result in a [./branching.wiki | fork] which you may want to resolve by 522824b26a 2009-08-28 drh: running <b>merge</b> followed by another <b>commit</b>. 522824b26a 2009-08-28 drh: </li> 522824b26a 2009-08-28 drh: 522824b26a 2009-08-28 drh: <li> 26a2b61dbd 2008-05-29 drh: Repeat all of the above until you have generated great software. 522824b26a 2009-08-28 drh: </li> 26a2b61dbd 2008-05-29 drh: </ol> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <h2>5.0 Setting Up A Fossil Server</h2> d87ca60c58 2008-05-15 stephan: 522824b26a 2009-08-28 drh: With other configuration management software, setting up a server is d87ca60c58 2008-05-15 stephan: a lot of work and normally takes time, patience, and a lot of system d87ca60c58 2008-05-15 stephan: knowledge. Fossil is designed to avoid this frustration. Setting up d87ca60c58 2008-05-15 stephan: a server with fossil is ridiculously easy. You have three options:</p> d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <ol> 3c1234c0f2 2009-09-12 drh: <li><b><a name="saserv"></a>Setting up a stand-alone server</b> 522824b26a 2009-08-28 drh: 522824b26a 2009-08-28 drh: From within your source tree just use the <b>server</b> command and d87ca60c58 2008-05-15 stephan: fossil will start listening for incoming requests on TCP port 8080. 9eb6ea75c1 2008-11-11 kejoki: You can point your web browser at <a href="http://localhost:8080/"> d87ca60c58 2008-05-15 stephan: http://localhost:8080/</a> and begin exploring. Or your coworkers d87ca60c58 2008-05-15 stephan: can do pushes or pulls against your server. Use the <b>--port</b> d87ca60c58 2008-05-15 stephan: option to the server command to specify a different TCP port. If d87ca60c58 2008-05-15 stephan: you do not have a local source tree, use the <b>-R</b> command-line 522824b26a 2009-08-28 drh: option to specify the repository file. d87ca60c58 2008-05-15 stephan: 522824b26a 2009-08-28 drh: A stand-alone server is a great way to set of transient connections d87ca60c58 2008-05-15 stephan: between coworkers for doing quick pushes or pulls. But you can also d87ca60c58 2008-05-15 stephan: set up a permanent stand-alone server if you prefer. Just make d87ca60c58 2008-05-15 stephan: arrangements for fossil to be launched with appropriate arguments 522824b26a 2009-08-28 drh: after every reboot. 2e275c1420 2009-01-23 drh: 522824b26a 2009-08-28 drh: If you just want a server to browse the built-in fossil website 2e275c1420 2009-01-23 drh: locally, use the <b>ui</b> command in place of <b>server</b>. The 2e275c1420 2009-01-23 drh: <b>ui</b> command starts up a local server too, but it also takes 2e275c1420 2009-01-23 drh: the additional step of automatically launching your webbrowser and 522824b26a 2009-08-28 drh: pointing at the new server. d87ca60c58 2008-05-15 stephan: </li> d87ca60c58 2008-05-15 stephan: 522824b26a 2009-08-28 drh: <li><b>Setting up a CGI server</b> d87ca60c58 2008-05-15 stephan: 522824b26a 2009-08-28 drh: If you have a web-server running on your machine already, you can d87ca60c58 2008-05-15 stephan: set up fossil to be run from CGI. Simply create an executable script 522824b26a 2009-08-28 drh: that looks something like this: d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <blockquote><pre> d87ca60c58 2008-05-15 stephan: #!/usr/local/bin/fossil d87ca60c58 2008-05-15 stephan: repository: /home/me/bigproject.fossil d87ca60c58 2008-05-15 stephan: </pre></blockquote> d87ca60c58 2008-05-15 stephan: 522824b26a 2009-08-28 drh: Edit this script to use whatever pathnames are appropriate for 9eb6ea75c1 2008-11-11 kejoki: your project. Then point your web browser at the script and off you 522824b26a 2009-08-28 drh: go. The [./selfhost.wiki | self-hosting fossil repositories] are 522824b26a 2009-08-28 drh: all set up this way.</li> 9eb6ea75c1 2008-11-11 kejoki: 522824b26a 2009-08-28 drh: <li><b>Setting up an inetd server</b> d87ca60c58 2008-05-15 stephan: 522824b26a 2009-08-28 drh: If you have inetd or xinetd running on your system, you can set d87ca60c58 2008-05-15 stephan: those services up to launch fossil to deal with inbound TCP/IP connections d87ca60c58 2008-05-15 stephan: on whatever port you want. Set up inetd or xinetd to launch fossil 522824b26a 2009-08-28 drh: like this: d87ca60c58 2008-05-15 stephan: d87ca60c58 2008-05-15 stephan: <blockquote><pre> d87ca60c58 2008-05-15 stephan: /usr/local/bin/fossil http /home/me/bigproject.fossil d87ca60c58 2008-05-15 stephan: </pre></blockquote> d87ca60c58 2008-05-15 stephan: 522824b26a 2009-08-28 drh: As before, change the filenames to whatever is appropriate for d87ca60c58 2008-05-15 stephan: your system. You can have fossil run as any user that has write d87ca60c58 2008-05-15 stephan: permission on the repository and on the directory that contains the d87ca60c58 2008-05-15 stephan: repository. But it is safer to run fossil as root. When fossil d87ca60c58 2008-05-15 stephan: sees that it is running as root, it automatically puts itself into d87ca60c58 2008-05-15 stephan: a <a href="http://en.wikipedia.org/wiki/Chroot">chroot jail</a> and d87ca60c58 2008-05-15 stephan: drops all privileges prior to reading any information from the client. d87ca60c58 2008-05-15 stephan: Since fossil is a stand-alone program, you do not need to put anything 522824b26a 2009-08-28 drh: in the chroot jail with fossil in order for it to do its job. d87ca60c58 2008-05-15 stephan: </li> d87ca60c58 2008-05-15 stephan: </ol> 26a2b61dbd 2008-05-29 drh: 26a2b61dbd 2008-05-29 drh: <h2>6.0 Review Of Key Concepts</h2> 26a2b61dbd 2008-05-29 drh: 26a2b61dbd 2008-05-29 drh: <ul> 26a2b61dbd 2008-05-29 drh: <li>The <b>fossil</b> program is a self-contained stand-alone executable. 26a2b61dbd 2008-05-29 drh: Just put it somewhere on your PATH to install it.</li> 26a2b61dbd 2008-05-29 drh: <li>Use the <b>clone</b> or <b>new</b> commands to create a new repository.</li> 26a2b61dbd 2008-05-29 drh: <li>Use the <b>open</b> command to create a new source tree.</li> 26a2b61dbd 2008-05-29 drh: <li>Use the <b>add</b> and <b>rm</b> or <b>delete</b> commands to add and 26a2b61dbd 2008-05-29 drh: remove files from the local source tree.</li> 904ee40b93 2009-01-23 drh: <li>Use the <b>commit</b> command to create a new check-in.</li> 26a2b61dbd 2008-05-29 drh: <li>Use the <b>update</b> command to merge in changes from others.</li> 26a2b61dbd 2008-05-29 drh: <li>The <b>push</b> and <b>pull</b> commands can be used to share changes 26a2b61dbd 2008-05-29 drh: manually, but these things happen automatically in the default 26a2b61dbd 2008-05-29 drh: autosync mode.</li> 26a2b61dbd 2008-05-29 drh: </ul>
File Annotation