Fossil SCM

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

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button