initial commitHEADmaster

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>