diff options
Diffstat (limited to 'www/glossary.md')
| -rw-r--r-- | www/glossary.md | 466 |
1 files changed, 466 insertions, 0 deletions
diff --git a/www/glossary.md b/www/glossary.md new file mode 100644 index 0000000..8fff002 --- /dev/null +++ b/www/glossary.md @@ -0,0 +1,466 @@ +# Glossary + +There are several terms-of-art in Fossil that have specific meanings +which are either not immediately obvious to an outsider or which have +technical associations that can lead someone to either use the terms +incorrectly or to get the wrong idea from someone using those terms +correctly. We hope to teach users how to properly “speak Fossil” with +this glossary. + +The bullet-point lists following each definition are meant to be +clarifying and illustrative. They are not part of the definitions +themselves. + + +## <a id="project"></a>Project + +A collection of one or more computer files that serve some conceptually +unified purpose, which purpose changes and evolves over time, with the +history of that project being a valuable record. + +* We qualify the Fossil definition of this common word like this to + set aside cases where a zip file or tarball would suffice. If you + can pack your project up into such an archive once and be done with + it, Fossil is overkill. + + And yet that is often just the beginning, since there is often a + need for something to be changed, so now you have “version 2” of the + archive file. If you can foresee yourself creating versioned archive + files for your project, then you probably should be using Fossil for + it instead, then using Fossil’s [zip] or [tarball] command to + automatically produce archives of the latest version rather than + manually produce and track versions of the archive. The web version + of these commands ([`/zip`][zw] and [`/tarball`][tw]) are + particularly useful for public distribution of the latest version of + a project’s files. + +* Fossil was designed to host the SQLite software project, which is + comprised of source code, makefiles, scripts, documentation files, + and so forth. Fossil is also useful for many other purposes, such as + a fiction book project where each chapter is held in a separate file + and assembled into a finished whole deliverable. + +* We speak of projects being more than one file because even though + Fossil can be made to track the history of a single file, it is far + more often the case that when you get to something of a scale + sufficient to be called a “project,” there is more than one + version-tracked file involved, if not at the start, then certainly + by the end of the project. + + To take the example of a fiction book above, instead of putting each + chapter in a separate file, you could use a single AsciiDoc file for + the entire book project rather than make use of its [include + facility][AIF] to assemble it from chapter files, since that does at + least solve the [key problems][IFRS] inherent in version-tracking + something like Word’s DOCX format with Fossil instead. + + While Fossil will happily track the single file containing the prose + of your book project for you, you’re still likely to want separate + files for the cover artwork, a style sheet for use in converting the + source document to HTML, scripts to convert that intermediate output + to PDF and ePub in a reliably repeatable fashion, a `README` file + containing instructions to the printing house, and so forth. + +* Fossil requires that all the files for a project be collected into a + single directory hierarchy, owned by a single user with full rights + to modify those files. Fossil is not a good choice for managing a + project that has files scattered hither and yon all over the file + system, nor of collections of files with complicated ownership and + access rights. + + A project made of an operating system + installation’s configuration file set is not a good use of Fossil, + because you’ll have all of your OS’s *other* files intermixed. + Worse, Fossil doesn’t track OS permissions, so even if you were to + try to use Fossil as a system deployment tool by archiving versions + of the OS configuration files and then unpacking them on a new + system, the extracted project files would have read/write access by + the user who did the extraction, which probably isn’t what you were + wanting. + + Even with these problems aside, do you really want a `.fslckout` + SQLite database at the root of your filesystem? Are you prepared for + the consequences of saying `fossil clean --verily` on such a system? + You can constrain that with [the `ignore-glob` setting][IGS], but + are you prepared to write and maintain all the rules needed to keep + Fossil from blowing away the untracked portions of the file system? + We believe Fossil is a poor choice for a whole-system configuration + backup utility. + + As a counterexample, a project tracking your [Vim] configuration + history is a much better use of Fossil, because it’s all held within + `~/.vim`, and your user has full rights to that subdirectory. + +[AIF]: https://docs.asciidoctor.org/asciidoc/latest/directives/include/ +[IGS]: /help/ignore-glob +[IFRS]: ./image-format-vs-repo-size.md +[tarball]: /help/tarball +[tw]: /help/www/tarball +[Vim]: https://www.vim.org/ +[zip]: /help/zip +[zw]: /help/www/zip + + +## Repository <a id="repository" name="repo"></a> + +A single file that contains all historical versions of all files in a +project, which can be [cloned] to other machines and +[synchronized][sync] with them. Jargon: repo. + +* A Fossil repo is similar to an archive file in that it is a single + file that stores compressed versions of one or more files. Files can be + extracted from the repo, and new files can be added to the repo, + but a Fossil repo has other capabilities + above and beyond what simple archive formats can do. + +* Fossil does not care what you name your repository files, though + we do suggest “`.fossil`” as a standard extension. There is + only one place in Fossil where that convention is required, being the + [`fossil server DIRECTORY`][svrcmd] command, since it serves up + `*.fossil` files from `DIRECTORY`. If you don’t use that feature, + you can name your repo files anything you like. + +* Cloned and synced repos redundantly store all available information + about that project, so if any one repo is lost, all of the cloned + historical content of the project as of the last sync is preserved + in each surviving repo. + + Each user generally clones the project repository down to each + computer they use to participate in that project, and there is + usually at least one central host for the project as well, so there + is usually plenty of redundancy in any given Fossil-based project. + + That said, a Fossil repository clone is a backup only in a limited + sense, because some information can’t be cloned, some doesn’t sync + by default, and some data is neither clonable nor syncable. We cover + these limitations and the workarounds for them in a separate + document, [Backing Up a Remote Fossil Repository][backup]. + +* Rather than be a backup, a Fossil repository clone is a + communication method for coordinating work on the project among + multiple machines and users: local work done against one repository + is communicated up to its parent repository on the next sync, and + work done on other repositories that were previously synced up to + that parent get pulled down into the local repo clone. + + This bidirectional sync is automatic and on by default in Fossil. + You can [disable it][asdis], or you can [push] or [pull] + unidirectionally, if you wish. + + The Fossil philosophy is that all project information resides in + each clone of the repository. In the ideal world, this would occur + instantly and automatically, but in actual use, Fossil falls + somewhat short of that mark. Some limitations are simply + technological: a given clone may be temporarily out of communication + with its parent repository, network delays exist, and so forth. + Fossil is [an AP mode system][CAP]. (This is sometimes called + “eventual consistency.”) Other cases come down to administrative + necessity, as covered in [the backup doc][backup]. + +* Fossil doesn’t require that you have redundant clones. Whether you + do or not is a local decision based on usage needs, communication + requirements, desire for backups, and so forth. + +* Fossil doesn’t care where the repositories are stored, but we + recommend keeping them all in a single subdirectory such as + "`~/fossils`" or "`%USERPROFILE%\Fossils`". A flat set of files + suffices for simple purposes, but you may have use for something + more complicated. This author uses a scheme like the following on + mobile machines that shuttle between home and the office: + +``` pikchr toggle indent +box "~/museum/" fit +move right 0.1 +line right dotted +move right 0.05 +box invis "where one stores valuable fossils" ljust + +arrow down 50% from first box.s then right 50% +box "work/" fit +move right 0.1 +line dotted +move right 0.05 +box invis "projects from $DAYJOB" ljust + +arrow down 50% from 2nd vertex of previous arrow then right 50% +box "home/" fit +move right 0.1 +line dotted right until even with previous line.end +move right 0.05 +box invis "personal at-home projects" ljust + +arrow down 50% from 2nd vertex of previous arrow then right 50% +box "other/" fit +move right 0.1 +line dotted right until even with previous line.end +move right 0.05 +box invis "clones of Fossil itself, SQLite, etc." ljust +``` + +[asdis]: /help/autosync +[backup]: ./backup.md +[CAP]: ./cap-theorem.md +[cloned]: /help/clone +[pull]: /help/pull +[push]: /help/push +[svrcmd]: /help/server +[sync]: /help/sync + +[repository]: #repo +[repositories]: #repo + + +## Version / Revision / Hash / UUID <a id="version" name="hash"></a> + +These terms all mean the same thing: a long hexadecimal +[SHA hash value](./hashes.md) that uniquely identifies a particular +[check-in](#ci). + +We’ve listed the alternatives in decreasing preference order: + +* **Version** and **revision** are near-synonyms in common usage. + Fossil’s code and documentation use both interchangeably because + Fossil was created to manage the development of the SQLite project, + which formerly used [CVS], the Concurrent Versions System. CVS in + turn started out as a front-end to [RCS], the Revision Control + System, but even though CVS uses “version” in its name, it numbers + check-ins using a system derived from RCS’s scheme, which it calls + “Revisions” in user-facing output. Fossil inherits this confusion + honestly. + +* **Hash** refers to the [SHA1 or SHA3-256 hash](./hashes.md) of the + content of the checked-in data, uniquely identifying that version of + the managed files. It is a strictly correct synonym, used more often + in low-level contexts than the term “version.” + +* **UUID** is a deprecated term still found in many parts of the + Fossil internals and (decreasingly) its documentation. The problem + with using this as a synonym for a Fossil-managed version of the + managed files is that there are [standards][UUID] defining the + format of a “UUID,” none of which Fossil follows, not even the + [version 4][ruuid] (random) format, the type of UUID closest in + meaning and usage to a Fossil hash.(^A pre-Fossil 2.0 style SHA1 + hash is 160 bits, not the 128 bits many people expect for a proper + UUID, and even if you truncate it to 128 bits to create a “good + enough” version prefix, the 6 bits reserved in the UUID format for + the variant code cannot make a correct declaration except by a + random 1:64 chance. The SHA3-256 option allowed in Fossil 2.0 and + higher doesn’t help with this confusion, making a Fossil version + hash twice as large as a proper UUID. Alas, the term will never be + fully obliterated from use since there are columns in the Fossil + repository format that use the obsolete term; we cannot change this + without breaking backwards compatibility.) + +You will find all of these synonyms used in the Fossil documentation. +Some day we may settle on a single term, but it doesn’t seem likely. + +[CVS]: https://en.wikipedia.org/wiki/Concurrent_Versions_System +[hash]: #version +[RCS]: https://en.wikipedia.org/wiki/Revision_Control_System +[ruuid]: https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random) +[snfs]: https://en.wikipedia.org/wiki/Snapshot_(computer_storage)#File_systems +[UUID]: https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random) +[version]: #version + + +## Check-in <a id="check-in" name="ci"></a> + +A [version] of the project’s files that have been committed to the +[repository]; as such, it is sometimes called a “commit” instead. A +check-in is a snapshot of the project at an instant in time, as seen from +a single [check-out’s](#co) perspective. It is sometimes styled +“`CHECKIN`”, especially in command documentation where any +[valid check-in name][ciname] can be used. + +* There is a harmless conflation of terms here: any of the various + synonyms for [version] may be used where “check-in” is more accurate, + and vice versa, because there is a 1:1 relation between them. A + check-in *has* a version, but a version suffices to uniquely look up + a particular commit.[^snapshot] + +* Combining both sets of synonyms results in a list of terms that is + confusing to new Fossil users, but it’s easy + enough to internalize the concepts. [Committing][commit] creates a + *commit.* It may also be said to create a checked-in *version* of a + particular *revision* of the project’s files, thus creating an + immutable *snapshot* of the project’s state at the time of the + commit. Fossil users find each of these different words for the + same concept useful for expressive purposes among ourselves, but to + Fossil proper, they all mean the same thing. + +* Check-ins are immutable. + +* Check-ins exist only inside the repository. Contrast a + [check-out](#co). + +* Check-ins may have [one or more names][ciname], but only the + [hash] is globally unique, across all time; we call it the check-in’s + canonical name. The other names are either imprecise, contextual, or + change their meaning over time and across [repositories]. + +[^snapshot]: You may sometimes see the term “snapshot” used as a synonym + for a check-in or the version number identifying said check-in. We + must warn against this usage because there is a potential confusion + here: [the `stash` command][stash] uses the term “snapshot,” as does + [the `undo` system][undo] to make a distinction with check-ins. + Nevertheless, there is a conceptual overlap here between Fossil and + systems that do use the term “snapshot,” the primary distinction being + that Fossil will capture only changes to files you’ve [added][add] to + the [repository], not to everything in [the check-out directory](#co) + at the time of the snapshot. (Thus [the `extras` command][extras].) + Contrast a snapshot taken by a virtual machine system or a + [snapshotting file system][snfs], which captures changes to everything + on the managed storage volume. + +[add]: /help/add +[ciname]: ./checkin_names.wiki +[extras]: /help/extras +[stash]: /help/stash +[undo]: /help/undo + + + +## Check-out <a id="check-out" name="co"></a> + +A set of files extracted from a [repository] that represent a +particular [check-in](#ci) of the [project](#project). + +* Unlike a check-in, a check-out is mutable. It may start out as a + version of a particular check-in extracted from the repository, but + the user is then free to make modifications to the checked-out + files. Once those changes are formally [committed][commit], they + become a new immutable check-in, derived from its parent check-in. + +* You can switch from one check-in to another within a check-out + directory by passing those names to [the `fossil update` + command][update]. + +* Check-outs relate to repositories in a one-to-many fashion: it is + common to have a single repo clone on a machine but to have it + [open] in [multiple working directories][mwd]. Check-out directories + are associated with the repos they were created from by settings + stored in the check-out directory. This is in the `.fslckout` file on + POSIX type systems, but for historical compatibility reasons, it’s + called `_FOSSIL_` by native Windows builds of Fossil. + + (Contrast the Cygwin and WSL Fossil binaries, which use POSIX file + naming rules.) + +* In the same way that one cannot extract files from a zip archive + without having a copy of that zip file, one cannot make check-outs + without access to the repository file or a clone thereof. + +* Because a Fossil repository is an SQLite database file, the same + rules for avoiding data corruption apply to it. In particular, it is + [nearly a hard requirement][h2cflp] that the repository clone be on + the same machine as the one where you make check-outs and the + subsequent check-ins. + + That said, the relative locations of the repo and the check-out + within the local file system are arbitrary. The repository may be + located inside the folder holding the check-out, but it certainly + does not have to be, and it usually is not. As an example, [the + Fossil plugin for Visual Studio Code][fpvsc] defaults to storing the + repo clone within the project directory as a file called `.fsl`, but + this is because VSCode’s version control features assume it’s being + used with Git, where the repository is the `.git` subdirectory + contents. With Fossil, [different check-out workflows][cwork] are + preferred. + +[commit]: /help/commit +[cwork]: ./ckout-workflows.md +[h2cflp]: https://www.sqlite.org/howtocorrupt.html#_file_locking_problems +[fpvsc]: https://marketplace.visualstudio.com/items?itemName=koog1000.fossil +[open]: /help/open +[mwd]: ./ckout-workflows.md#mcw +[update]: /help/update + + +## <a id="docs"></a>Embedded Documentation + +Serving as an alternative to Fossil’s built-in [wiki], the [embedded +documentation feature][edoc] stores the same type of marked-up text +files, but under Fossil’s powerful version control features. + +* The simple rule for determining whether to use the wiki or embedded + docs for any given document is whether the content is considered + “evergreen,” as with a Wikipedia article. + + While Fossil’s wiki feature does store the history of each + document’s changes, Fossil always presents the current version of + the document unless you manually go out of your way to dig back into + the history. Then, having done so, links from that historical + version of the wiki document take you to the current versions of the + target documents, not to the version contemporaneous with the source + document. + + The consequence is that if you say something like… + + $ fossil up 2020-04-01 + $ fossil ui --page wcontent + + …you will **not** see the list of wiki articles as of April Fool’s Day in 2020, but + instead the list of *current* wiki article versions, the same as if you ran it + from a check-out of the tip-of-trunk. + + Contrast embedded docs, which are not only version-controlled as + normal files are in Fossil, they participate in all the tagging, + branching, and other versioning features. There are several + consequences of this, such as that Fossil’s [special check-in + names][ciname] work with embedded doc URLs: + + * <p>If you visit an embedded doc as `/doc/release/file.md` and + then click on a relative link from that document, you will remain on + the release branch. This lets you see not only the release + version of a software project but also the documentation as of + that release.</p> + + * <p>If you visit `/doc/2020-04-01/file.md`, you will not only + pull up the version of `file.md` as of that date, relative links + will take you to contemporaneous versions of those embedded docs + as well.</p> + + * <p>If you say `fossil up 2020-04-01 && fossil ui` and then visit + `/doc/ckout/file.md`, you’ll not only see the checked-out + version of the file as of that date, relative links will show + you other files within that checkout.</p> + +* Fossil’s wiki presents a flat list of articles, while embedded docs + are stored in the repository’s file hierarchy, a powerful + organizational tool well-suited to complicated documentation. + +* Your repository’s Home page is a good candidate for the wiki, as is + documentation meant for use only with the current version of the + repository’s contents. + +* If you are at all uncertain whether to use the wiki or the embedded + documentation feature, prefer the latter, since it is inherently + more powerful, and when you use the [`/fileedit` feature][fef], the + workflow is scarcely different from using the wiki. + + (This very file is embedded documentation: clone + [Fossil’s self-hosting repository][fshr] and you will find it as + `www/glossary.md`.) + +[edoc]: ./embeddeddoc.wiki +[fef]: ./fileedit-page.md +[fshr]: ./selfhost.wiki +[wiki]: ./wikitheory.wiki + + +## <a id="cap"></a>Capability + +Fossil includes a powerful [role-based access control system][rbac] +which affects which users have permission to do certain things within a given +[repository]. You can read more about this complex topic +[here](./caps/). + +Some people — and indeed certain parts of Fossil’s own code — use the +term “permissions” instead, but since [operating system file permissions +also play into this](./caps/#webonly), we prefer the term “capabilities” +(or “caps” for short) when talking about Fossil’s RBAC system to avoid a +confusion here. + +[rbac]: https://en.wikipedia.org/wiki/Role-based_access_control + +<div style="height:50em" id="this-space-intentionally-left-blank"></div> |