Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
Comment: | Capitalize "Fossil" in the concepts.wiki document. |
---|---|
Downloads: | Tarball | ZIP archive |
Timelines: | family | ancestors | descendants | both | trunk |
Files: | files | file ages | folders |
SHA1: |
b63c4300028643768ad1a1fc60e8834d |
User & Date: | drh 2015-12-02 09:55:09.383 |
Context
2015-12-02
| ||
20:18 | Fix harmless compiler warning. ... (check-in: a3691d76 user: mistachkin tags: trunk) | |
09:55 | Capitalize "Fossil" in the concepts.wiki document. ... (check-in: b63c4300 user: drh tags: trunk) | |
09:50 | Improved command-line help for push, pull, sync, and clone commands. ... (check-in: 26d0c20a user: drh tags: trunk) | |
Changes
Changes to www/concepts.wiki.
︙ | ︙ | |||
9 10 11 12 13 14 15 | development of a software project and to record the history of the project. There are many such systems in use today. Fossil strives to distinguish itself from the others by being extremely simple to setup and operate. This document is intended as a quick introduction to the concepts | | | | | | | 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 | development of a software project and to record the history of the project. There are many such systems in use today. Fossil strives to distinguish itself from the others by being extremely simple to setup and operate. This document is intended as a quick introduction to the concepts behind Fossil. <h2>2.0 Composition Of A Project</h2> <img src="concept1.gif" align="right" hspace="10"> A software project normally consists of a "source tree". A source tree is a hierarchy of files that are used to generate the end product. The source tree changes over time as the software grows and expands and as features are added and bugs are fixed. A snapshot of the source tree at any point in time is called a "version" or "revision" or a "baseline" of the product. In Fossil, we use the name "check-in". A "repository" is a database that contains copies of all historical check-ins for a project. Check-ins are normally stored in the repository in a highly space-efficient compressed format (delta encoding). But that is an implementation detail that you the user need not worry over. Think of the repository as a safe place where all your old check-ins are securely stored away and available for retrieval whenever you need them. A repository in Fossil is a single file on your disk. This file might be rather large (dozens or hundreds of megabytes for a large or long running project) but it is nevertheless just a file. You can move it around, rename it, write it out to a memory stick, or do anything else you normally do with files. Each source tree that is controlled by Fossil is associated with a single repository on the local disk drive. You can tie two or more source trees to a single repository if you want (though one tree per repository is the most common configuration.) So a single repository can be associated with many source trees, but each source tree is associated with only one repository. Fossil source trees may not overlap. A Fossil source tree is identified by a file named "_FOSSIL_" (or ".fslckout", but this article will always use the name "_FOSSIL_") in the root directory of the source tree. Every file that is a sibling of _FOSSIL_ and every file in every subfolder is considered potentially a part of the source tree. The _FOSSIL_ file contains (among other things) the pathname of the repository with which the source tree is associated. On the other hand, the repository has no record of its source trees. So you are free to delete a source tree |
︙ | ︙ | |||
96 97 98 99 100 101 102 | 6089f0b563a9db0a6d90682fe47fd7161ff867c8<br> 59712614a1b3ccfd84078a37fa5b606e28434326<br> 19dbf73078be9779edd6a0156195e610f81c94f9<br> b4104959a67175f02d6b415480be22a239f1f077<br> 997c9d6ae03ad114b2b57f04e9eeef17dcb82788 </b></blockquote> | | | | 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 | 6089f0b563a9db0a6d90682fe47fd7161ff867c8<br> 59712614a1b3ccfd84078a37fa5b606e28434326<br> 19dbf73078be9779edd6a0156195e610f81c94f9<br> b4104959a67175f02d6b415480be22a239f1f077<br> 997c9d6ae03ad114b2b57f04e9eeef17dcb82788 </b></blockquote> When referring to an artifact using Fossil, you can use a unique prefix of the artifact ID that is four characters or longer. This saves a lot of typing. When displaying artifact IDs, Fossil will usually only show the first 10 digits since that is normally enough to uniquely identify a file. Changing (or adding or removing) a single byte in a file results in a completely different artifact ID. And since the artifact ID is the name of the artifact, making any change to a file results in a new artifact. In this way, artifacts are immutable. |
︙ | ︙ | |||
128 129 130 131 132 133 134 | Associated with every check-in is a special file called the [./fileformat.wiki#manifest| "manifest"]. The manifest is a listing of all other files in that source tree. The manifest contains the (complete) artifact ID of the file and the name of the file as it appears on disk, and thus serves as a mapping from artifact ID to disk name. The artifact ID of the manifest is the identifier for the entire check-in. When | | | 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 | Associated with every check-in is a special file called the [./fileformat.wiki#manifest| "manifest"]. The manifest is a listing of all other files in that source tree. The manifest contains the (complete) artifact ID of the file and the name of the file as it appears on disk, and thus serves as a mapping from artifact ID to disk name. The artifact ID of the manifest is the identifier for the entire check-in. When you look at a "timeline" of changes in Fossil, the ID associated with each check-in or commit is really just the artifact ID of the manifest for that check-in. <p>The manifest file is not normally a real file on disk. Instead, the manifest is computed in memory by Fossil whenever it needs it. However, the "fossil setting manifest on" command will cause the manifest file to be materialized to disk, if desired. Both Fossil |
︙ | ︙ | |||
167 168 169 170 171 172 173 | <li>A <b>check-in</b> is a set of files arranged in a hierarchy.</li> <li>A <b>repository</b> keeps a record of historical check-ins.</li> <li>Repositories share their changes using <b>push</b>, <b>pull</b>, <b>sync</b>, and <b>clone</b>.</li> <li>A particular <u>version</u> of a particular file is an <b>artifact</b> that is identified by an <b>artifact ID</b>.</li> | | | | | | | | | | | | | | | | | 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 | <li>A <b>check-in</b> is a set of files arranged in a hierarchy.</li> <li>A <b>repository</b> keeps a record of historical check-ins.</li> <li>Repositories share their changes using <b>push</b>, <b>pull</b>, <b>sync</b>, and <b>clone</b>.</li> <li>A particular <u>version</u> of a particular file is an <b>artifact</b> that is identified by an <b>artifact ID</b>.</li> <li>Artifacts tracked by Fossil are inherently immutable.</li> <li>Fossil automatically generates a <b>manifest</b> file that identifies every artifact in a check-in.</li> <li>The artifact ID of the manifest is the identifier of the check-in.</li> </ul> <h2>3.0 Fossil - The Program</h2> Fossil is software. The implementation of Fossil is in the form of a single executable named "fossil" (or "fossil.exe" on Windows). To install Fossil on your system, all you have to do is obtain a copy of this one executable file (either by downloading a <a href="http://www.fossil-scm.org/download.html">pre-compiled version</a> or [./build.wiki | compiling it yourself]) and then putting that file somewhere on your PATH. Fossil is completely self-contained. It is not necessary to install any other software in order to use Fossil. You do <u>not</u> need CVS, gzip, diff, rsync, Python, Perl, Tcl, Java, apache, PostgreSQL, MySQL, SQLite, patch, or any similar software on your system in order to use Fossil effectively. You will want to have some kind of text editor for entering check-in comments. Fossil will use whatever text editor is identified by your VISUAL environment variable. Fossil will also use GPG to clearsign your manifests if you happen to have it installed, but Fossil will skip that step if GPG missing from your system. You can optionally set up Fossil to use external "diff" programs, though Fossil has an excellent built-in "diff" algorithm that works fine for most people. If you happen to have Tcl/Tk installed on your system, Fossil will use it to generate a graphical "diff" display when you use the --tk option to the "diff" command, but this too is entirely optional. To uninstall Fossil, simply delete the executable. To upgrade an older version of Fossil to a newer version, just replace the old executable with the new one. You might need to run "<b>fossil all rebuild</b>" to restructure your repositories after an upgrade. Running "all rebuild" never hurts, so when upgrading it is a good policy to run it even if it is not strictly necessary. To use Fossil, simply type the name of the executable in your shell, followed by one of the various built-in commands and arguments appropriate for that command. For example: <blockquote><b> fossil help </b></blockquote> In the next section, when we say things like "use the <b>help</b> command" we mean to use the command name "help" as the first token after the name of the Fossil executable, as shown above. <a name="workflow"></a> <h2>4.0 Workflow</h2> <img src="concept2.gif" align="right" hspace="10"> Fossil has two modes of operation: <i>"autosync"</i> and <i>"manual-merge"</i> Autosync mode is reminiscent of CVS or SVN in that it automatically keeps your changes in synchronization with your co-workers through the use of a central server. The manual-merge mode is the standard workflow for GIT or Mercurial in that your local repository develops independently of your coworkers and you share and merge your changes manually. An interesting feature of Fossil is that it supports both autosync and manual-merge work flows. The default setting for Fossil is to be in autosync mode. You can change the autosync setting or check the current autosync setting using commands like: <blockquote> <b>fossil setting autosync on<br> fossil setting autosync off<br> <b>fossil settings</b> </blockquote> By default, Fossil runs with autosync mode turned on. The authors finds that projects run more smoothly in autosync mode since autosync helps to prevent pointless forking and merge and helps keeps all collaborators working on exactly the same code rather than on their own personal forks of the code. In the author's view, manual-merge mode should be reserved for disconnected operation. <h3>4.1 Autosync Workflow</h3> |
︙ | ︙ | |||
288 289 290 291 292 293 294 | to exist in historical check-ins.) Test your changes. </li> <li> Create a new check-in using the <b>commit</b> command. You will be prompted for a check-in comment and also for your GPG key if you have GPG installed. The commit copies the edits you have made in your local source | | | 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 | to exist in historical check-ins.) Test your changes. </li> <li> Create a new check-in using the <b>commit</b> command. You will be prompted for a check-in comment and also for your GPG key if you have GPG installed. The commit copies the edits you have made in your local source tree into your local repository. After your commit completes, Fossil will automatically <b>push</b> your changes back to the server you cloned from or whatever server you most recently synced with. </li> <li> When your coworkers make their own changes, you can merge those changes into your local local source tree using the <b>update</b> command. |
︙ | ︙ | |||
393 394 395 396 397 398 399 | </ol> <h2>5.0 Setting Up A Fossil Server</h2> With other configuration management software, setting up a server is a lot of work and normally takes time, patience, and a lot of system knowledge. Fossil is designed to avoid this frustration. Setting up | | | 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 | </ol> <h2>5.0 Setting Up A Fossil Server</h2> With other configuration management software, setting up a server is a lot of work and normally takes time, patience, and a lot of system knowledge. Fossil is designed to avoid this frustration. Setting up a server with Fossil is ridiculously easy. You have four options:</p> <ol> <li><p><b>Stand-alone server.</b> Simply run the [/help?cmd=server|fossil server] or [/help?cmd=ui|fossil ui] command from the command-line. <li><p><b>CGI.</b> |
︙ | ︙ |