Fossil SCM
Extracted the glossary to a new document from the old "why use Fossil" doc, expanded it considerably, converted it from Wiki to Markdown, and updated the links to point to its new location.
Commit
a58d952fa68c1955fbf5f49cbfa406aa043fd4adee94aa6e0f2fc18d7480de8b
Parent
28a60efcf99db20…
8 files changed
+2
-2
+1
-47
+229
+2
-1
+1
+1
-1
+1
-1
+1
-97
+2
-2
| --- www/concepts.wiki | ||
| +++ www/concepts.wiki | ||
| @@ -15,12 +15,12 @@ | ||
| 15 | 15 | This document is intended as a quick introduction to the concepts |
| 16 | 16 | behind Fossil. |
| 17 | 17 | |
| 18 | 18 | See also: |
| 19 | 19 | |
| 20 | - * [./whyusefossil.wiki#definitions|Definitions] | |
| 21 | - * [./quickstart.wiki|Quick start guide] | |
| 20 | + * [./glossary.md | Glossary] | |
| 21 | + * [./quickstart.wiki | Quick start guide] | |
| 22 | 22 | |
| 23 | 23 | <h2>2.0 Composition Of A Project</h2> |
| 24 | 24 | |
| 25 | 25 | <verbatim type="pikchr float-right"> |
| 26 | 26 | R1: cylinder "Remote" "Repository" fill 0xadd8e6 rad 70% |
| 27 | 27 |
| --- www/concepts.wiki | |
| +++ www/concepts.wiki | |
| @@ -15,12 +15,12 @@ | |
| 15 | This document is intended as a quick introduction to the concepts |
| 16 | behind Fossil. |
| 17 | |
| 18 | See also: |
| 19 | |
| 20 | * [./whyusefossil.wiki#definitions|Definitions] |
| 21 | * [./quickstart.wiki|Quick start guide] |
| 22 | |
| 23 | <h2>2.0 Composition Of A Project</h2> |
| 24 | |
| 25 | <verbatim type="pikchr float-right"> |
| 26 | R1: cylinder "Remote" "Repository" fill 0xadd8e6 rad 70% |
| 27 |
| --- www/concepts.wiki | |
| +++ www/concepts.wiki | |
| @@ -15,12 +15,12 @@ | |
| 15 | This document is intended as a quick introduction to the concepts |
| 16 | behind Fossil. |
| 17 | |
| 18 | See also: |
| 19 | |
| 20 | * [./glossary.md | Glossary] |
| 21 | * [./quickstart.wiki | Quick start guide] |
| 22 | |
| 23 | <h2>2.0 Composition Of A Project</h2> |
| 24 | |
| 25 | <verbatim type="pikchr float-right"> |
| 26 | R1: cylinder "Remote" "Repository" fill 0xadd8e6 rad 70% |
| 27 |
+1
-47
| --- www/gitusers.md | ||
| +++ www/gitusers.md | ||
| @@ -130,56 +130,10 @@ | ||
| 130 | 130 | |
| 131 | 131 | [fpull]: /help?cmd=pull |
| 132 | 132 | [gpull]: https://git-scm.com/docs/git-pull |
| 133 | 133 | [gcokoan]: https://stevelosh.com/blog/2013/04/git-koans/#s2-one-thing-well |
| 134 | 134 | |
| 135 | - | |
| 136 | -#### <a id="rname"></a> Naming Repositories | |
| 137 | - | |
| 138 | -The Fossil repository database file can be named anything | |
| 139 | -you want, with a single exception: if you’re going to use the | |
| 140 | -[`fossil server DIRECTORY`][server] feature, the repositories you wish | |
| 141 | -to serve need to be stored together in a flat directory and have | |
| 142 | -"`.fossil`" suffixes. That aside, you can follow any other convention that | |
| 143 | -makes sense to you. | |
| 144 | - | |
| 145 | -This author uses a scheme like the following on mobile machines that | |
| 146 | -shuttle between home and the office: | |
| 147 | - | |
| 148 | -``` pikchr toggle indent | |
| 149 | -scale=0.8 | |
| 150 | -box "~/museum/" fit | |
| 151 | -move right 0.1 | |
| 152 | -line right dotted | |
| 153 | -move right 0.05 | |
| 154 | -box invis "where one stores valuable fossils" ljust | |
| 155 | - | |
| 156 | -arrow down 50% from first box.s then right 50% | |
| 157 | -box "work/" fit | |
| 158 | -move right 0.1 | |
| 159 | -line dotted | |
| 160 | -move right 0.05 | |
| 161 | -box invis "projects from $dayjob" ljust | |
| 162 | - | |
| 163 | -arrow down 50% from 2nd vertex of previous arrow then right 50% | |
| 164 | -box "home/" fit | |
| 165 | -move right 0.1 | |
| 166 | -line dotted right until even with previous line.end | |
| 167 | -move right 0.05 | |
| 168 | -box invis "personal at-home projects" ljust | |
| 169 | - | |
| 170 | -arrow down 50% from 2nd vertex of previous arrow then right 50% | |
| 171 | -box "other/" fit | |
| 172 | -move right 0.1 | |
| 173 | -line dotted right until even with previous line.end | |
| 174 | -move right 0.05 | |
| 175 | -box invis "clones of Fossil itself, SQLite, etc." ljust | |
| 176 | -``` | |
| 177 | - | |
| 178 | -On a Windows box, you might instead choose "`C:\Fossils`" | |
| 179 | -and do without the subdirectory scheme, for example. | |
| 180 | - | |
| 181 | 135 | |
| 182 | 136 | #### <a id="close" name="dotfile"></a> Closing a Check-Out |
| 183 | 137 | |
| 184 | 138 | The [`fossil close`][close] command dissociates a check-out directory from the |
| 185 | 139 | Fossil repository database, nondestructively inverting [`fossil open`][open]. |
| @@ -324,11 +278,11 @@ | ||
| 324 | 278 | repo DB file or what you name it. |
| 325 | 279 | |
| 326 | 280 | |
| 327 | 281 | [clone]: /help?cmd=clone |
| 328 | 282 | [close]: /help?cmd=close |
| 329 | -[gloss]: ./whyusefossil.wiki#definitions | |
| 283 | +[gloss]: ./glossary.md | |
| 330 | 284 | [open]: /help?cmd=open |
| 331 | 285 | [set]: /help?cmd=setting |
| 332 | 286 | [server]: /help?cmd=server |
| 333 | 287 | [stash]: /help?cmd=stash |
| 334 | 288 | [undo]: /help?cmd=undo |
| 335 | 289 | |
| 336 | 290 | ADDED www/glossary.md |
| --- www/gitusers.md | |
| +++ www/gitusers.md | |
| @@ -130,56 +130,10 @@ | |
| 130 | |
| 131 | [fpull]: /help?cmd=pull |
| 132 | [gpull]: https://git-scm.com/docs/git-pull |
| 133 | [gcokoan]: https://stevelosh.com/blog/2013/04/git-koans/#s2-one-thing-well |
| 134 | |
| 135 | |
| 136 | #### <a id="rname"></a> Naming Repositories |
| 137 | |
| 138 | The Fossil repository database file can be named anything |
| 139 | you want, with a single exception: if you’re going to use the |
| 140 | [`fossil server DIRECTORY`][server] feature, the repositories you wish |
| 141 | to serve need to be stored together in a flat directory and have |
| 142 | "`.fossil`" suffixes. That aside, you can follow any other convention that |
| 143 | makes sense to you. |
| 144 | |
| 145 | This author uses a scheme like the following on mobile machines that |
| 146 | shuttle between home and the office: |
| 147 | |
| 148 | ``` pikchr toggle indent |
| 149 | scale=0.8 |
| 150 | box "~/museum/" fit |
| 151 | move right 0.1 |
| 152 | line right dotted |
| 153 | move right 0.05 |
| 154 | box invis "where one stores valuable fossils" ljust |
| 155 | |
| 156 | arrow down 50% from first box.s then right 50% |
| 157 | box "work/" fit |
| 158 | move right 0.1 |
| 159 | line dotted |
| 160 | move right 0.05 |
| 161 | box invis "projects from $dayjob" ljust |
| 162 | |
| 163 | arrow down 50% from 2nd vertex of previous arrow then right 50% |
| 164 | box "home/" fit |
| 165 | move right 0.1 |
| 166 | line dotted right until even with previous line.end |
| 167 | move right 0.05 |
| 168 | box invis "personal at-home projects" ljust |
| 169 | |
| 170 | arrow down 50% from 2nd vertex of previous arrow then right 50% |
| 171 | box "other/" fit |
| 172 | move right 0.1 |
| 173 | line dotted right until even with previous line.end |
| 174 | move right 0.05 |
| 175 | box invis "clones of Fossil itself, SQLite, etc." ljust |
| 176 | ``` |
| 177 | |
| 178 | On a Windows box, you might instead choose "`C:\Fossils`" |
| 179 | and do without the subdirectory scheme, for example. |
| 180 | |
| 181 | |
| 182 | #### <a id="close" name="dotfile"></a> Closing a Check-Out |
| 183 | |
| 184 | The [`fossil close`][close] command dissociates a check-out directory from the |
| 185 | Fossil repository database, nondestructively inverting [`fossil open`][open]. |
| @@ -324,11 +278,11 @@ | |
| 324 | repo DB file or what you name it. |
| 325 | |
| 326 | |
| 327 | [clone]: /help?cmd=clone |
| 328 | [close]: /help?cmd=close |
| 329 | [gloss]: ./whyusefossil.wiki#definitions |
| 330 | [open]: /help?cmd=open |
| 331 | [set]: /help?cmd=setting |
| 332 | [server]: /help?cmd=server |
| 333 | [stash]: /help?cmd=stash |
| 334 | [undo]: /help?cmd=undo |
| 335 | |
| 336 | DDED www/glossary.md |
| --- www/gitusers.md | |
| +++ www/gitusers.md | |
| @@ -130,56 +130,10 @@ | |
| 130 | |
| 131 | [fpull]: /help?cmd=pull |
| 132 | [gpull]: https://git-scm.com/docs/git-pull |
| 133 | [gcokoan]: https://stevelosh.com/blog/2013/04/git-koans/#s2-one-thing-well |
| 134 | |
| 135 | |
| 136 | #### <a id="close" name="dotfile"></a> Closing a Check-Out |
| 137 | |
| 138 | The [`fossil close`][close] command dissociates a check-out directory from the |
| 139 | Fossil repository database, nondestructively inverting [`fossil open`][open]. |
| @@ -324,11 +278,11 @@ | |
| 278 | repo DB file or what you name it. |
| 279 | |
| 280 | |
| 281 | [clone]: /help?cmd=clone |
| 282 | [close]: /help?cmd=close |
| 283 | [gloss]: ./glossary.md |
| 284 | [open]: /help?cmd=open |
| 285 | [set]: /help?cmd=setting |
| 286 | [server]: /help?cmd=server |
| 287 | [stash]: /help?cmd=stash |
| 288 | [undo]: /help?cmd=undo |
| 289 | |
| 290 | DDED www/glossary.md |
+229
| --- a/www/glossary.md | ||
| +++ b/www/glossary.md | ||
| @@ -0,0 +1,229 @@ | ||
| 1 | +# Glossary | |
| 2 | + | |
| 3 | +There are several terms-of-art in Fossil that have specific meanings | |
| 4 | +which are either not immediately obvious to an outsider or which have | |
| 5 | +technical associations that can lead someone to either use the terms | |
| 6 | +incorrectly or to get the wrong idea from someone using those terms | |
| 7 | +correctly. We hope to teach users how to properly “speak FossEach definition is followed by a bullet-point list of clarifying | |
| 8 | +details. These are not part of the definition itself.project"></a>Project | |
| 9 | + | |
| 10 | +A collection of one or more computer files that serve some conceptually | |
| 11 | +unified purpose, which purpose changes and evolves over time, with the | |
| 12 | +history of that project being a valuable record. | |
| 13 | + | |
| 14 | +* We qualify the Fossil definition of this common word like this to | |
| 15 | + set aside cases where a zip file or tarball would suffice. If you | |
| 16 | + can pack your project up into such an archive once and be done with | |
| 17 | + it, Fossil is overkill. | |
| 18 | + | |
| 19 | + And yet that is often just the beginning, since there is often a | |
| 20 | + need for something to be changed, so now you have “version 2” of the | |
| 21 | + archive file. If you can foresee yourself creating versioned archive | |
| 22 | + files for your project, then you probably should be using Fossil for | |
| 23 | + it instead, then using Fossil’s [zip] or [tarball] command to | |
| 24 | + automatically produce archives of the latest version rather than | |
| 25 | + manually produce and track versions of the archive. The web version | |
| 26 | + of these commands ([`/zip`][zw] and [`/tarball`][tw]) are | |
| 27 | + particularly useful for public distribution of the latest version of | |
| 28 | + a project’s files. | |
| 29 | + | |
| 30 | +* Fossil was designed to host the SQLite software project, which is | |
| 31 | + comprised of source code, makefiles, scripts, documentation files, | |
| 32 | + and so forth. Fossil is also useful for many other purposes, such as | |
| 33 | + a fiction book project where each chapter is held in a separate file | |
| 34 | + and assembled into a finished whole deliverable. | |
| 35 | + | |
| 36 | +* We speak of projects being more than one file because even though | |
| 37 | + Fossil can be made to track the history of a single file, it is far | |
| 38 | + more often the case that when you get to something of a scale | |
| 39 | + sufficient to be called a “project,” there is more than one | |
| 40 | + version-tracked file involved, if not at the start, then certainly | |
| 41 | + by thWe usedose changeswith one chapter per | |
| 42 | + file. That implies scripts for combining those chapters into the | |
| 43 | + finished book and converting that into PDF and ePub outputs, each of | |
| 44 | + which benefit from being version-tracked. | |
| 45 | + | |
| 46 | + You could instead use a Word DOCX file for common word like this t, | |
| 47 | + with these implicit scripts replaced by Word menu commands. Fossil | |
| 48 | + will happily track that single file’s evolution for you, though | |
| 49 | + ./image-format-vs-re?cmd=tarba) to *not* do | |
| 50 | + that. | |
| 51 | + | |
| 52 | + Let us say you choose to solve the primary problems brought up in | |
| 53 | + that document by using a format like AsciiDoc instead. You could | |
| 54 | + still use a single file for the entire book’s proseoresee yourself creating versioned archive | |
| 55 | + files for your project, then you probably should be using Fossil for | |
| 56 | + it instead, then using Fossil’s [zip] or [tarball] command to | |
| 57 | + automatically produce archives of the latest version rather than | |
| 58 | + manually produce and track versions of the archive. The web version | |
| 59 | + of these commands ([`/zip`][zw] and [`/tarball`][tw]) are | |
| 60 | + particularly useful for public distribution of the latest version of | |
| 61 | + a project’s files. | |
| 62 | + | |
| 63 | +* Fossil was designed to host the SQLite software project, which is | |
| 64 | + comprised of source code, makefiles, scripts, documentation files, | |
| 65 | + and so forth. Fossil is also useful for many other purposes, such as | |
| 66 | + a fiction book project where each chapter is held in a separate file | |
| 67 | + and assembled into a finished whole deliverable. | |
| 68 | + | |
| 69 | +* We speak of projects being more than one file because even though | |
| 70 | + Fossil can be made to track the history of a single file, it is far | |
| 71 | + more often the case that when you get to something of a scale | |
| 72 | + sufficient to be called a “project,” there is more than one | |
| 73 | + version-tracked file involved, if not at the start, then certainly | |
| 74 | + by the end of the project. | |
| 75 | + | |
| 76 | + To take the example of a fiction book above, instead of putting each | |
| 77 | + chapter in a separate file, you could use a single AsciiDoc file for | |
| 78 | + the entire book project rather than make use of its [include | |
| 79 | + facility][AIF] to assemble it from chapter files, since that does at | |
| 80 | + least solve the [key problemsrting the | |
| 81 | + source document to HTML, scripts to convert that intermediate output | |
| 82 | + to PDF and ePub in a reliably repeatable fashion, a `README` file | |
| 83 | + containing instructions to the printing house, and so forth. | |
| 84 | + | |
| 85 | +* Fossil requires that all the files for a project be collected into a | |
| 86 | + single directory hierarchy, owned by a single user with full rights | |
| 87 | + to modify those files. Fossil is not a good choice for managing a | |
| 88 | + project that has files scattered hither and yon all over the file | |
| 89 | + system, nor of collections of files with complicated ownership and | |
| 90 | + access rights. | |
| 91 | + | |
| 92 | + A project made of an operating system | |
| 93 | + ins zip archivsystem | |
| 94 | + installation’s configuration file set is not a good use of Fossil, | |
| 95 | + because you’ll have all of your OS’s *other* files intermixejust as with a zip archive,so even if you were to | |
| 96 | + try to use Fossil as a system deployment tool by archiving versions | |
| 97 | + of the OS configuration files and then unpacking them on a neappending “`.fossil`would have read/write access by | |
| 98 | + the user who did the extraction, which’s required, being the “directory | |
| 99 | + name” form of [the `fossil server l clean --verily` on such a system? | |
| 100 | + You can constrain that with [the `ignore-glob` setting][IGS], but | |
| 101 | + are you prepared to write and maintain all the rules needed to keep | |
| 102 | + Fossil from blowing away the untracked portions of the file system? | |
| 103 | + We believe Fossil is a poor choice for a whole-system configuration | |
| 104 | + backup utility. | |
| 105 | + | |
| 106 | + As a counterexample, a project tracking your [Vim] configuration | |
| 107 | + history is a much better use of Fossil, because it’s all held within | |
| 108 | + `~/.vim`, and your user has full rights to that subdirectory. | |
| 109 | + | |
| 110 | +[AIF]: https://docs.asciidoctor.org/asciidoc/latest/directive?cmd=/include/ | |
| 111 | +[IGS]: /help/ignore-glob | |
| 112 | +[IFRS]: ./image-format-vs-re?cmd=tarball | |
| 113 | +[tw]: /help?cmd=/tarball | |
| 114 | +[Vim]: https://ww?cmd=zip | |
| 115 | +[zw]: /help?cmd= | |
| 116 | +which are either not immediately obvious to an outsider or which have | |
| 117 | +technical associations that can lead someone to either use the terms | |
| 118 | +incorrectly or to get the wrong idea from someone using those terms | |
| 119 | +correctly. We hope to teach users how to properly “speak Fossil” with | |
| 120 | +this glossary. | |
| 121 | + | |
| 122 | +The bullet-point lists following each definition are meant to be | |
| 123 | +clarifying and illustrative. They are not part of the definitions | |
| 124 | +themselves. | |
| 125 | + | |
| 126 | + | |
| 127 | +## <a id="project"></a>Project | |
| 128 | + | |
| 129 | +A collection of one or more computer files that serve some conceptually | |
| 130 | +unified purpose, which purpose changes and evolves over time, with the | |
| 131 | +history of that project being a valuable record. | |
| 132 | + | |
| 133 | +* We qualify the Fossil definition of this common word like this to | |
| 134 | + set aside cases where a zip file or tarball would suffice. If you | |
| 135 | + can pack your project up into such an archive once and be done with | |
| 136 | + it, Fossil is overkill. | |
| 137 | + | |
| 138 | + And yet that is often just the beginning, since there is often a | |
| 139 | + need for something to be changed, so now you have “version 2” of the | |
| 140 | + archive file. If you can foresee yourself creating versioned archive | |
| 141 | + files for your project, then you probably should be using Fossil for | |
| 142 | + it instead, then using Fossil’s [zip] or [tarball] command to | |
| 143 | + automatically produce archives of the latest version rather than | |
| 144 | + manually produce and track versions of the archive. The web version | |
| 145 | + of these commands ([`/zip`][zw] and [`/tarball`][tw]) are | |
| 146 | + particularly useful for public distribution of the latest version of | |
| 147 | + a project’s files. | |
| 148 | + | |
| 149 | +* Fossil was designed to host the SQLite software project, which is | |
| 150 | + comprised of source code, makefiles, scripts, documentation files, | |
| 151 | + and so forth. Fossil is also useful for many other purposes, such as | |
| 152 | + a fiction book project where each chapter is held in a separate file | |
| 153 | + and assembled into a finished whole deliverable. | |
| 154 | + | |
| 155 | +* We speak of projects being more than one file because even though | |
| 156 | + Fossil can be made to track the history of a single file, it is far | |
| 157 | + more often the case that when you get to something of a scale | |
| 158 | + sufficient to be called a “project,” there is more than one | |
| 159 | + version-tracked file involved, if not at the start, then certainly | |
| 160 | + by the end of the project. | |
| 161 | + | |
| 162 | + To take the example of a fiction book above, instead of putting each | |
| 163 | + chapter in a separate file, you could use a single AsciiDoc file for | |
| 164 | + the entire book project rather than make use of its [include | |
| 165 | + facility][AIF] to assemble it from chapter files, since that does at | |
| 166 | + least solve the [key problems][IFRS] inherent in./backup.md | |
| 167 | +[CAP]:rent in version-tracking | |
| 168 | + soormat with Fossil instead./help?cmd=pull | |
| 169 | +[push]:ad. | |
| 170 | + | |
| 171 | + While Fossil will h containing the prose | |
| 172 | + o/help?cmd=sync��re s yorepositoryobleversion e the terms | |
| 173 | +incorrectly o of the | |
| 174 | + man. It which Fossil follows, not e | |
| 175 | +seen from ) format, the tySynonyms: version, | |
| 176 | +snapshot, revision, commit. Sometimes styled HA1 synonyms for | |
| 177 | + people ex | |
| 178 | + vice | |
| 179 | + bits reserved in the UU | |
| 180 | + bits reserved in the UUID format | |
| 181 | +used. | |
| 182 | + | |
| 183 | +* Theliterated from use since there are columns in the Fossil | |
| 184 | + repository format that use the obsolete term; we cannot change this | |
| 185 | + without breaking backwards compatibility.) | |
| 186 | + | |
| 187 | +You will find all of these synonyms used in the Fossil documentation. | |
| 188 | +Some day we may settle on a single term, but it doesn’t seem likely. | |
| 189 | + | |
| 190 | +[CVS] | |
| 191 | + e the terms | |
| 192 | +incorrectly or to# Glossary | |
| 193 | + | |
| 194 | +There are several terms-of-art in Fossil that have spgher doesn’t help with this confusion, making a Fossil version | |
| 195 | + hash twice as large as a proper UUID. Alas, the term will never be | |
| 196 | + fully obliterated from use since there are columns in the Fossil | |
| 197 | + repository format that use the obsolete term; we cannot change this | |
| 198 | + without breaking backwards compatibility.) | |
| 199 | + | |
| 200 | +You will find all of these synonyms used in the Fossil documentation. | |
| 201 | +Some day we may settle on a single term, but it doesn’t seem likely. | |
| 202 | + | |
| 203 | +[CVS]: https://en.wikipedia.org/wiki/ SHA | |
| 204 | + hashd the extraction, which probably isn’t what yorepositoryoblem | |
| 205 | + with using this as a synonym for a Fossil-managed versio of the | |
| 206 | + managed files is that there are [standards][UUID] defining the | |
| 207 | + format of a “UUID,” none of which Fossil follows, not even the | |
| 208 | + [version 4][ruuid] (random) format, the type of UUID closeso a Fossil hash.(^Ail 2.0 style SHA1 synonyms for | |
| 209 | + people expect for a proper | |
| 210 | + UU and vice | |
| 211 | + bits reserved in the UUID format for | |
| 212 | + the variant code cannot make a correct declaration except by a | |
| 213 | + random 1:64 chance. The SHA3-256 option allowed in Fossil 2.0 and | |
| 214 | + higher doesn’t help with this confusion, making a Fossil version | |
| 215 | + hash twice as large as a proper UUID. Alas, the term will never be | |
| 216 | + fully obliterated from use since there are columns in the Fossil | |
| 217 | + repository format that use the obsolete term; we cannot change this | |
| 218 | + without breaking backwards compatibility.) | |
| 219 | + | |
| 220 | +You will find all of these synonyms used in the Fossil documentation. | |
| 221 | +Some day we may settle on a single term, but it doesn’t seem likely. | |
| 222 | + | |
| 223 | +[CVS] | |
| 224 | + e the terms | |
| 225 | +incorrectly or to# Glossary | |
| 226 | + | |
| 227 | +There are several terms-of-art in Fossil that have spgher doesn’t help with this confusion, help with this confusion, making a Fossil version | |
| 228 | + hash twice as large as a proper UUID. Alas, the term will never be | |
| 229 | + fully obliterated from use since there are columns in |
| --- a/www/glossary.md | |
| +++ b/www/glossary.md | |
| @@ -0,0 +1,229 @@ | |
| --- a/www/glossary.md | |
| +++ b/www/glossary.md | |
| @@ -0,0 +1,229 @@ | |
| 1 | # Glossary |
| 2 | |
| 3 | There are several terms-of-art in Fossil that have specific meanings |
| 4 | which are either not immediately obvious to an outsider or which have |
| 5 | technical associations that can lead someone to either use the terms |
| 6 | incorrectly or to get the wrong idea from someone using those terms |
| 7 | correctly. We hope to teach users how to properly “speak FossEach definition is followed by a bullet-point list of clarifying |
| 8 | details. These are not part of the definition itself.project"></a>Project |
| 9 | |
| 10 | A collection of one or more computer files that serve some conceptually |
| 11 | unified purpose, which purpose changes and evolves over time, with the |
| 12 | history of that project being a valuable record. |
| 13 | |
| 14 | * We qualify the Fossil definition of this common word like this to |
| 15 | set aside cases where a zip file or tarball would suffice. If you |
| 16 | can pack your project up into such an archive once and be done with |
| 17 | it, Fossil is overkill. |
| 18 | |
| 19 | And yet that is often just the beginning, since there is often a |
| 20 | need for something to be changed, so now you have “version 2” of the |
| 21 | archive file. If you can foresee yourself creating versioned archive |
| 22 | files for your project, then you probably should be using Fossil for |
| 23 | it instead, then using Fossil’s [zip] or [tarball] command to |
| 24 | automatically produce archives of the latest version rather than |
| 25 | manually produce and track versions of the archive. The web version |
| 26 | of these commands ([`/zip`][zw] and [`/tarball`][tw]) are |
| 27 | particularly useful for public distribution of the latest version of |
| 28 | a project’s files. |
| 29 | |
| 30 | * Fossil was designed to host the SQLite software project, which is |
| 31 | comprised of source code, makefiles, scripts, documentation files, |
| 32 | and so forth. Fossil is also useful for many other purposes, such as |
| 33 | a fiction book project where each chapter is held in a separate file |
| 34 | and assembled into a finished whole deliverable. |
| 35 | |
| 36 | * We speak of projects being more than one file because even though |
| 37 | Fossil can be made to track the history of a single file, it is far |
| 38 | more often the case that when you get to something of a scale |
| 39 | sufficient to be called a “project,” there is more than one |
| 40 | version-tracked file involved, if not at the start, then certainly |
| 41 | by thWe usedose changeswith one chapter per |
| 42 | file. That implies scripts for combining those chapters into the |
| 43 | finished book and converting that into PDF and ePub outputs, each of |
| 44 | which benefit from being version-tracked. |
| 45 | |
| 46 | You could instead use a Word DOCX file for common word like this t, |
| 47 | with these implicit scripts replaced by Word menu commands. Fossil |
| 48 | will happily track that single file’s evolution for you, though |
| 49 | ./image-format-vs-re?cmd=tarba) to *not* do |
| 50 | that. |
| 51 | |
| 52 | Let us say you choose to solve the primary problems brought up in |
| 53 | that document by using a format like AsciiDoc instead. You could |
| 54 | still use a single file for the entire book’s proseoresee yourself creating versioned archive |
| 55 | files for your project, then you probably should be using Fossil for |
| 56 | it instead, then using Fossil’s [zip] or [tarball] command to |
| 57 | automatically produce archives of the latest version rather than |
| 58 | manually produce and track versions of the archive. The web version |
| 59 | of these commands ([`/zip`][zw] and [`/tarball`][tw]) are |
| 60 | particularly useful for public distribution of the latest version of |
| 61 | a project’s files. |
| 62 | |
| 63 | * Fossil was designed to host the SQLite software project, which is |
| 64 | comprised of source code, makefiles, scripts, documentation files, |
| 65 | and so forth. Fossil is also useful for many other purposes, such as |
| 66 | a fiction book project where each chapter is held in a separate file |
| 67 | and assembled into a finished whole deliverable. |
| 68 | |
| 69 | * We speak of projects being more than one file because even though |
| 70 | Fossil can be made to track the history of a single file, it is far |
| 71 | more often the case that when you get to something of a scale |
| 72 | sufficient to be called a “project,” there is more than one |
| 73 | version-tracked file involved, if not at the start, then certainly |
| 74 | by the end of the project. |
| 75 | |
| 76 | To take the example of a fiction book above, instead of putting each |
| 77 | chapter in a separate file, you could use a single AsciiDoc file for |
| 78 | the entire book project rather than make use of its [include |
| 79 | facility][AIF] to assemble it from chapter files, since that does at |
| 80 | least solve the [key problemsrting the |
| 81 | source document to HTML, scripts to convert that intermediate output |
| 82 | to PDF and ePub in a reliably repeatable fashion, a `README` file |
| 83 | containing instructions to the printing house, and so forth. |
| 84 | |
| 85 | * Fossil requires that all the files for a project be collected into a |
| 86 | single directory hierarchy, owned by a single user with full rights |
| 87 | to modify those files. Fossil is not a good choice for managing a |
| 88 | project that has files scattered hither and yon all over the file |
| 89 | system, nor of collections of files with complicated ownership and |
| 90 | access rights. |
| 91 | |
| 92 | A project made of an operating system |
| 93 | ins zip archivsystem |
| 94 | installation’s configuration file set is not a good use of Fossil, |
| 95 | because you’ll have all of your OS’s *other* files intermixejust as with a zip archive,so even if you were to |
| 96 | try to use Fossil as a system deployment tool by archiving versions |
| 97 | of the OS configuration files and then unpacking them on a neappending “`.fossil`would have read/write access by |
| 98 | the user who did the extraction, which’s required, being the “directory |
| 99 | name” form of [the `fossil server l clean --verily` on such a system? |
| 100 | You can constrain that with [the `ignore-glob` setting][IGS], but |
| 101 | are you prepared to write and maintain all the rules needed to keep |
| 102 | Fossil from blowing away the untracked portions of the file system? |
| 103 | We believe Fossil is a poor choice for a whole-system configuration |
| 104 | backup utility. |
| 105 | |
| 106 | As a counterexample, a project tracking your [Vim] configuration |
| 107 | history is a much better use of Fossil, because it’s all held within |
| 108 | `~/.vim`, and your user has full rights to that subdirectory. |
| 109 | |
| 110 | [AIF]: https://docs.asciidoctor.org/asciidoc/latest/directive?cmd=/include/ |
| 111 | [IGS]: /help/ignore-glob |
| 112 | [IFRS]: ./image-format-vs-re?cmd=tarball |
| 113 | [tw]: /help?cmd=/tarball |
| 114 | [Vim]: https://ww?cmd=zip |
| 115 | [zw]: /help?cmd= |
| 116 | which are either not immediately obvious to an outsider or which have |
| 117 | technical associations that can lead someone to either use the terms |
| 118 | incorrectly or to get the wrong idea from someone using those terms |
| 119 | correctly. We hope to teach users how to properly “speak Fossil” with |
| 120 | this glossary. |
| 121 | |
| 122 | The bullet-point lists following each definition are meant to be |
| 123 | clarifying and illustrative. They are not part of the definitions |
| 124 | themselves. |
| 125 | |
| 126 | |
| 127 | ## <a id="project"></a>Project |
| 128 | |
| 129 | A collection of one or more computer files that serve some conceptually |
| 130 | unified purpose, which purpose changes and evolves over time, with the |
| 131 | history of that project being a valuable record. |
| 132 | |
| 133 | * We qualify the Fossil definition of this common word like this to |
| 134 | set aside cases where a zip file or tarball would suffice. If you |
| 135 | can pack your project up into such an archive once and be done with |
| 136 | it, Fossil is overkill. |
| 137 | |
| 138 | And yet that is often just the beginning, since there is often a |
| 139 | need for something to be changed, so now you have “version 2” of the |
| 140 | archive file. If you can foresee yourself creating versioned archive |
| 141 | files for your project, then you probably should be using Fossil for |
| 142 | it instead, then using Fossil’s [zip] or [tarball] command to |
| 143 | automatically produce archives of the latest version rather than |
| 144 | manually produce and track versions of the archive. The web version |
| 145 | of these commands ([`/zip`][zw] and [`/tarball`][tw]) are |
| 146 | particularly useful for public distribution of the latest version of |
| 147 | a project’s files. |
| 148 | |
| 149 | * Fossil was designed to host the SQLite software project, which is |
| 150 | comprised of source code, makefiles, scripts, documentation files, |
| 151 | and so forth. Fossil is also useful for many other purposes, such as |
| 152 | a fiction book project where each chapter is held in a separate file |
| 153 | and assembled into a finished whole deliverable. |
| 154 | |
| 155 | * We speak of projects being more than one file because even though |
| 156 | Fossil can be made to track the history of a single file, it is far |
| 157 | more often the case that when you get to something of a scale |
| 158 | sufficient to be called a “project,” there is more than one |
| 159 | version-tracked file involved, if not at the start, then certainly |
| 160 | by the end of the project. |
| 161 | |
| 162 | To take the example of a fiction book above, instead of putting each |
| 163 | chapter in a separate file, you could use a single AsciiDoc file for |
| 164 | the entire book project rather than make use of its [include |
| 165 | facility][AIF] to assemble it from chapter files, since that does at |
| 166 | least solve the [key problems][IFRS] inherent in./backup.md |
| 167 | [CAP]:rent in version-tracking |
| 168 | soormat with Fossil instead./help?cmd=pull |
| 169 | [push]:ad. |
| 170 | |
| 171 | While Fossil will h containing the prose |
| 172 | o/help?cmd=sync��re s yorepositoryobleversion e the terms |
| 173 | incorrectly o of the |
| 174 | man. It which Fossil follows, not e |
| 175 | seen from ) format, the tySynonyms: version, |
| 176 | snapshot, revision, commit. Sometimes styled HA1 synonyms for |
| 177 | people ex |
| 178 | vice |
| 179 | bits reserved in the UU |
| 180 | bits reserved in the UUID format |
| 181 | used. |
| 182 | |
| 183 | * Theliterated from use since there are columns in the Fossil |
| 184 | repository format that use the obsolete term; we cannot change this |
| 185 | without breaking backwards compatibility.) |
| 186 | |
| 187 | You will find all of these synonyms used in the Fossil documentation. |
| 188 | Some day we may settle on a single term, but it doesn’t seem likely. |
| 189 | |
| 190 | [CVS] |
| 191 | e the terms |
| 192 | incorrectly or to# Glossary |
| 193 | |
| 194 | There are several terms-of-art in Fossil that have spgher doesn’t help with this confusion, making a Fossil version |
| 195 | hash twice as large as a proper UUID. Alas, the term will never be |
| 196 | fully obliterated from use since there are columns in the Fossil |
| 197 | repository format that use the obsolete term; we cannot change this |
| 198 | without breaking backwards compatibility.) |
| 199 | |
| 200 | You will find all of these synonyms used in the Fossil documentation. |
| 201 | Some day we may settle on a single term, but it doesn’t seem likely. |
| 202 | |
| 203 | [CVS]: https://en.wikipedia.org/wiki/ SHA |
| 204 | hashd the extraction, which probably isn’t what yorepositoryoblem |
| 205 | with using this as a synonym for a Fossil-managed versio of the |
| 206 | managed files is that there are [standards][UUID] defining the |
| 207 | format of a “UUID,” none of which Fossil follows, not even the |
| 208 | [version 4][ruuid] (random) format, the type of UUID closeso a Fossil hash.(^Ail 2.0 style SHA1 synonyms for |
| 209 | people expect for a proper |
| 210 | UU and vice |
| 211 | bits reserved in the UUID format for |
| 212 | the variant code cannot make a correct declaration except by a |
| 213 | random 1:64 chance. The SHA3-256 option allowed in Fossil 2.0 and |
| 214 | higher doesn’t help with this confusion, making a Fossil version |
| 215 | hash twice as large as a proper UUID. Alas, the term will never be |
| 216 | fully obliterated from use since there are columns in the Fossil |
| 217 | repository format that use the obsolete term; we cannot change this |
| 218 | without breaking backwards compatibility.) |
| 219 | |
| 220 | You will find all of these synonyms used in the Fossil documentation. |
| 221 | Some day we may settle on a single term, but it doesn’t seem likely. |
| 222 | |
| 223 | [CVS] |
| 224 | e the terms |
| 225 | incorrectly or to# Glossary |
| 226 | |
| 227 | There are several terms-of-art in Fossil that have spgher doesn’t help with this confusion, help with this confusion, making a Fossil version |
| 228 | hash twice as large as a proper UUID. Alas, the term will never be |
| 229 | fully obliterated from use since there are columns in |
+2
-1
| --- www/mkindex.tcl | ||
| +++ www/mkindex.tcl | ||
| @@ -62,12 +62,13 @@ | ||
| 62 | 62 | foss-cklist.wiki {Checklist For Successful Open-Source Projects} |
| 63 | 63 | fossil-from-msvc.wiki {Integrating Fossil in the Microsoft Express 2010 IDE} |
| 64 | 64 | fossil-is-not-relational.md {Introduction to the (Non-relational) Fossil Data Model} |
| 65 | 65 | fossil_prompt.wiki {Fossilized Bash Prompt} |
| 66 | 66 | fossil-v-git.wiki {Fossil Versus Git} |
| 67 | - globs.md {File Name Glob Patterns} | |
| 68 | 67 | gitusers.md {Git to Fossil Translation Guide} |
| 68 | + globs.md {File Name Glob Patterns} | |
| 69 | + glossary.md {Glossary} | |
| 69 | 70 | grep.md {Fossil grep vs POSIX grep} |
| 70 | 71 | hacker-howto.wiki {Hacker How-To} |
| 71 | 72 | hacker-howto.wiki {Fossil Developers Guide} |
| 72 | 73 | hashes.md {Hashes: Fossil Artifact Identification} |
| 73 | 74 | hashpolicy.wiki {Hash Policy: Choosing Between SHA1 and SHA3-256} |
| 74 | 75 |
| --- www/mkindex.tcl | |
| +++ www/mkindex.tcl | |
| @@ -62,12 +62,13 @@ | |
| 62 | foss-cklist.wiki {Checklist For Successful Open-Source Projects} |
| 63 | fossil-from-msvc.wiki {Integrating Fossil in the Microsoft Express 2010 IDE} |
| 64 | fossil-is-not-relational.md {Introduction to the (Non-relational) Fossil Data Model} |
| 65 | fossil_prompt.wiki {Fossilized Bash Prompt} |
| 66 | fossil-v-git.wiki {Fossil Versus Git} |
| 67 | globs.md {File Name Glob Patterns} |
| 68 | gitusers.md {Git to Fossil Translation Guide} |
| 69 | grep.md {Fossil grep vs POSIX grep} |
| 70 | hacker-howto.wiki {Hacker How-To} |
| 71 | hacker-howto.wiki {Fossil Developers Guide} |
| 72 | hashes.md {Hashes: Fossil Artifact Identification} |
| 73 | hashpolicy.wiki {Hash Policy: Choosing Between SHA1 and SHA3-256} |
| 74 |
| --- www/mkindex.tcl | |
| +++ www/mkindex.tcl | |
| @@ -62,12 +62,13 @@ | |
| 62 | foss-cklist.wiki {Checklist For Successful Open-Source Projects} |
| 63 | fossil-from-msvc.wiki {Integrating Fossil in the Microsoft Express 2010 IDE} |
| 64 | fossil-is-not-relational.md {Introduction to the (Non-relational) Fossil Data Model} |
| 65 | fossil_prompt.wiki {Fossilized Bash Prompt} |
| 66 | fossil-v-git.wiki {Fossil Versus Git} |
| 67 | gitusers.md {Git to Fossil Translation Guide} |
| 68 | globs.md {File Name Glob Patterns} |
| 69 | glossary.md {Glossary} |
| 70 | grep.md {Fossil grep vs POSIX grep} |
| 71 | hacker-howto.wiki {Hacker How-To} |
| 72 | hacker-howto.wiki {Fossil Developers Guide} |
| 73 | hashes.md {Hashes: Fossil Artifact Identification} |
| 74 | hashpolicy.wiki {Hash Policy: Choosing Between SHA1 and SHA3-256} |
| 75 |
| --- www/permutedindex.html | ||
| +++ www/permutedindex.html | ||
| @@ -69,10 +69,11 @@ | ||
| 69 | 69 | <li><a href="hints.wiki">Fossil Tips And Usage Hints</a></li> |
| 70 | 70 | <li><a href="fossil-v-git.wiki">Fossil Versus Git</a></li> |
| 71 | 71 | <li><a href="fossil_prompt.wiki">Fossilized Bash Prompt</a></li> |
| 72 | 72 | <li><a href="faq.wiki">Frequently Asked Questions</a></li> |
| 73 | 73 | <li><a href="gitusers.md">Git to Fossil Translation Guide</a></li> |
| 74 | +<li><a href="glossary.md">Glossary</a></li> | |
| 74 | 75 | <li><a href="hacker-howto.wiki">Hacker How-To</a></li> |
| 75 | 76 | <li><a href="adding_code.wiki">Hacking Fossil</a></li> |
| 76 | 77 | <li><a href="hashpolicy.wiki">Hash Policy: Choosing Between SHA1 and SHA3-256</a></li> |
| 77 | 78 | <li><a href="hashes.md">Hashes: Fossil Artifact Identification</a></li> |
| 78 | 79 | <li><a href="index.wiki">Home Page</a></li> |
| 79 | 80 |
| --- www/permutedindex.html | |
| +++ www/permutedindex.html | |
| @@ -69,10 +69,11 @@ | |
| 69 | <li><a href="hints.wiki">Fossil Tips And Usage Hints</a></li> |
| 70 | <li><a href="fossil-v-git.wiki">Fossil Versus Git</a></li> |
| 71 | <li><a href="fossil_prompt.wiki">Fossilized Bash Prompt</a></li> |
| 72 | <li><a href="faq.wiki">Frequently Asked Questions</a></li> |
| 73 | <li><a href="gitusers.md">Git to Fossil Translation Guide</a></li> |
| 74 | <li><a href="hacker-howto.wiki">Hacker How-To</a></li> |
| 75 | <li><a href="adding_code.wiki">Hacking Fossil</a></li> |
| 76 | <li><a href="hashpolicy.wiki">Hash Policy: Choosing Between SHA1 and SHA3-256</a></li> |
| 77 | <li><a href="hashes.md">Hashes: Fossil Artifact Identification</a></li> |
| 78 | <li><a href="index.wiki">Home Page</a></li> |
| 79 |
| --- www/permutedindex.html | |
| +++ www/permutedindex.html | |
| @@ -69,10 +69,11 @@ | |
| 69 | <li><a href="hints.wiki">Fossil Tips And Usage Hints</a></li> |
| 70 | <li><a href="fossil-v-git.wiki">Fossil Versus Git</a></li> |
| 71 | <li><a href="fossil_prompt.wiki">Fossilized Bash Prompt</a></li> |
| 72 | <li><a href="faq.wiki">Frequently Asked Questions</a></li> |
| 73 | <li><a href="gitusers.md">Git to Fossil Translation Guide</a></li> |
| 74 | <li><a href="glossary.md">Glossary</a></li> |
| 75 | <li><a href="hacker-howto.wiki">Hacker How-To</a></li> |
| 76 | <li><a href="adding_code.wiki">Hacking Fossil</a></li> |
| 77 | <li><a href="hashpolicy.wiki">Hash Policy: Choosing Between SHA1 and SHA3-256</a></li> |
| 78 | <li><a href="hashes.md">Hashes: Fossil Artifact Identification</a></li> |
| 79 | <li><a href="index.wiki">Home Page</a></li> |
| 80 |
+1
-1
| --- www/quickstart.wiki | ||
| +++ www/quickstart.wiki | ||
| @@ -25,11 +25,11 @@ | ||
| 25 | 25 | <h2 id="workflow" name="fslclone">General Work Flow</h2> |
| 26 | 26 | |
| 27 | 27 | <p>Fossil works with repository files (a database in a single file with the project's |
| 28 | 28 | complete history) and with checked-out local trees (the working directory |
| 29 | 29 | you use to do your work). |
| 30 | -(See [./whyusefossil.wiki#definitions | definitions] for more background.) | |
| 30 | +(See [./glossary.md | the glossary] for more background.) | |
| 31 | 31 | The workflow looks like this:</p> |
| 32 | 32 | |
| 33 | 33 | <ul> |
| 34 | 34 | <li>Create or clone a repository file. ([/help/init|fossil init] or |
| 35 | 35 | [/help/clone | fossil clone]) |
| 36 | 36 |
| --- www/quickstart.wiki | |
| +++ www/quickstart.wiki | |
| @@ -25,11 +25,11 @@ | |
| 25 | <h2 id="workflow" name="fslclone">General Work Flow</h2> |
| 26 | |
| 27 | <p>Fossil works with repository files (a database in a single file with the project's |
| 28 | complete history) and with checked-out local trees (the working directory |
| 29 | you use to do your work). |
| 30 | (See [./whyusefossil.wiki#definitions | definitions] for more background.) |
| 31 | The workflow looks like this:</p> |
| 32 | |
| 33 | <ul> |
| 34 | <li>Create or clone a repository file. ([/help/init|fossil init] or |
| 35 | [/help/clone | fossil clone]) |
| 36 |
| --- www/quickstart.wiki | |
| +++ www/quickstart.wiki | |
| @@ -25,11 +25,11 @@ | |
| 25 | <h2 id="workflow" name="fslclone">General Work Flow</h2> |
| 26 | |
| 27 | <p>Fossil works with repository files (a database in a single file with the project's |
| 28 | complete history) and with checked-out local trees (the working directory |
| 29 | you use to do your work). |
| 30 | (See [./glossary.md | the glossary] for more background.) |
| 31 | The workflow looks like this:</p> |
| 32 | |
| 33 | <ul> |
| 34 | <li>Create or clone a repository file. ([/help/init|fossil init] or |
| 35 | [/help/clone | fossil clone]) |
| 36 |
+1
-1
| --- www/userlinks.wiki | ||
| +++ www/userlinks.wiki | ||
| @@ -3,11 +3,11 @@ | ||
| 3 | 3 | * [./permutedindex.html | Documentation index] with [/search?c=d | full text search]. |
| 4 | 4 | * [./reviews.wiki | Testimonials] from satisfied Fossil users and |
| 5 | 5 | [./quotes.wiki | Quotes] about Fossil and other DVCSes. |
| 6 | 6 | * [./faq.wiki | Frequently Asked Questions] |
| 7 | 7 | * The [./concepts.wiki | concepts] behind Fossil. |
| 8 | - [./whyusefossil.wiki#definitions | Another viewpoint]. | |
| 8 | + [./glossary.md | Another viewpoint]. | |
| 9 | 9 | * [./quickstart.wiki | Quick Start] guide to using Fossil. |
| 10 | 10 | * [./qandc.wiki | Questions & Criticisms] directed at Fossil. |
| 11 | 11 | * [./build.wiki | Compiling and Installing] |
| 12 | 12 | * Fossil supports [./embeddeddoc.wiki | embedded documentation] |
| 13 | 13 | that is versioned along with project source code. |
| 14 | 14 |
| --- www/userlinks.wiki | |
| +++ www/userlinks.wiki | |
| @@ -3,11 +3,11 @@ | |
| 3 | * [./permutedindex.html | Documentation index] with [/search?c=d | full text search]. |
| 4 | * [./reviews.wiki | Testimonials] from satisfied Fossil users and |
| 5 | [./quotes.wiki | Quotes] about Fossil and other DVCSes. |
| 6 | * [./faq.wiki | Frequently Asked Questions] |
| 7 | * The [./concepts.wiki | concepts] behind Fossil. |
| 8 | [./whyusefossil.wiki#definitions | Another viewpoint]. |
| 9 | * [./quickstart.wiki | Quick Start] guide to using Fossil. |
| 10 | * [./qandc.wiki | Questions & Criticisms] directed at Fossil. |
| 11 | * [./build.wiki | Compiling and Installing] |
| 12 | * Fossil supports [./embeddeddoc.wiki | embedded documentation] |
| 13 | that is versioned along with project source code. |
| 14 |
| --- www/userlinks.wiki | |
| +++ www/userlinks.wiki | |
| @@ -3,11 +3,11 @@ | |
| 3 | * [./permutedindex.html | Documentation index] with [/search?c=d | full text search]. |
| 4 | * [./reviews.wiki | Testimonials] from satisfied Fossil users and |
| 5 | [./quotes.wiki | Quotes] about Fossil and other DVCSes. |
| 6 | * [./faq.wiki | Frequently Asked Questions] |
| 7 | * The [./concepts.wiki | concepts] behind Fossil. |
| 8 | [./glossary.md | Another viewpoint]. |
| 9 | * [./quickstart.wiki | Quick Start] guide to using Fossil. |
| 10 | * [./qandc.wiki | Questions & Criticisms] directed at Fossil. |
| 11 | * [./build.wiki | Compiling and Installing] |
| 12 | * Fossil supports [./embeddeddoc.wiki | embedded documentation] |
| 13 | that is versioned along with project source code. |
| 14 |
+1
-97
| --- www/whyusefossil.wiki | ||
| +++ www/whyusefossil.wiki | ||
| @@ -39,107 +39,11 @@ | ||
| 39 | 39 | </ol> |
| 40 | 40 | </ol> |
| 41 | 41 | |
| 42 | 42 | <p id="definitions"><b>II. Definitions</b></p> |
| 43 | 43 | |
| 44 | -<ul> | |
| 45 | -<li><p><b>Project</b> → | |
| 46 | - a collection of computer files that serve some common | |
| 47 | - purpose. Often the project is a software application and the | |
| 48 | - individual files are source code together with makefiles, scripts, and | |
| 49 | - "README.txt" files. Other examples of projects include books or | |
| 50 | - manuals in which each chapter or section is held in a separate file. | |
| 51 | - <ul> | |
| 52 | - <li><p>Projects change and evolve. The whole purpose of version | |
| 53 | - control is to track and manage that evolution. | |
| 54 | - <li><p>Most projects contain many files, but it is possible | |
| 55 | - to have a project consisting of just a single file. | |
| 56 | - <li><p>Fossil requires that | |
| 57 | - all the files for a project must be collected into a single | |
| 58 | - directory hierarchy - a single folder possibly with layers | |
| 59 | - of subfolders. Fossil is not a good choice for managing a | |
| 60 | - project that has files scattered hither and yon all over | |
| 61 | - the disk. In other words, Fossil only works for projects | |
| 62 | - where the files are laid out such that they can be archived | |
| 63 | - into a ZIP file or tarball. | |
| 64 | - </ul> | |
| 65 | -<li><p><b>Repository</b> → | |
| 66 | - (also called "repo") a single file that contains | |
| 67 | - all historical versions of all files in a project. A repo is similar | |
| 68 | - to a ZIP archive in that it is a single file that stores compressed | |
| 69 | - versions of many other files. Files can be extracted from the | |
| 70 | - repo and new files can be added to the repo, just as with a ZIP | |
| 71 | - archive. But a repo has other capabilities above and beyond | |
| 72 | - what a ZIP archive can do. | |
| 73 | - <ul> | |
| 74 | - <li><p>Fossil does not care what you name your repository files, | |
| 75 | - though names ending with ".fossil" are recommended. | |
| 76 | - <li><p>A single project typically has multiple, redundant repositories on | |
| 77 | - separate machines. | |
| 78 | - <li><p>All repositories stay synchronized with one another by exchanging | |
| 79 | - information via HTTPS or SSH. | |
| 80 | - <li><p>All repos for a single project redundantly store all information | |
| 81 | - about that project. So if any one repo is lost due to a disk | |
| 82 | - crash, all content is preserved in the surviving repos. | |
| 83 | - <li><p>The usual arrangement is one repository per user. And since | |
| 84 | - most users these days have their own computer, that means one | |
| 85 | - repository per computer. But this is not a requirement. It is | |
| 86 | - ok to have multiple copies of the same repository on the same | |
| 87 | - computer. | |
| 88 | - <li><p>Fossil works fine with just a single copy of the repository. | |
| 89 | - But in that case there is no redundancy. If that one repository | |
| 90 | - file is lost due to a hardware malfunction, then there is no way | |
| 91 | - to recover the project. | |
| 92 | - <li><p>Best practice is to keep all repositories for a user in a single | |
| 93 | - folder. Folders such as "~/Fossils" or "%USERPROFILE%\Fossils" | |
| 94 | - are recommended. Fossil itself does not care where the repositories | |
| 95 | - are stored. Nor does Fossil require repositories to be | |
| 96 | - kept in the same folder. But it is easier to organize your work | |
| 97 | - if all repositories are kept in the same place. | |
| 98 | - </ul> | |
| 99 | -<li><p><b>Check-out</b> → | |
| 100 | - a set of files that have been extracted from a | |
| 101 | - repository and that represent a particular version or snapshot of | |
| 102 | - the project. | |
| 103 | - <ul> | |
| 104 | - <li><p>Check-outs must be on the same computer as the repository from | |
| 105 | - which they are extracted. This is just like with a ZIP archive: | |
| 106 | - one must have the ZIP archive file on the local machine before | |
| 107 | - extracting files from ZIP archive. | |
| 108 | - <li><p>There can be multiple check-outs (in different folders) from | |
| 109 | - the same repository. | |
| 110 | - <li><p>The repository must be on the same computer as the check-out, but | |
| 111 | - the relative locations of the repo and the check-out are arbitrary. | |
| 112 | - The repository may be located inside the folder holding the | |
| 113 | - check-out, but it certainly does not have to be and usually is | |
| 114 | - not. | |
| 115 | - <li><p>A special file exists in every check-out that tells Fossil from | |
| 116 | - which repository the check-out was extracted, and which version of | |
| 117 | - the project the check-out represents. This is the ".fslckout" file | |
| 118 | - on unix systems or the "_FOSSIL_" file on Windows. | |
| 119 | - </ul> | |
| 120 | -<li><p><b>Check-in</b> → | |
| 121 | - another name for a particular version of the project. | |
| 122 | - A check-in is a collection of files inside of a repository that | |
| 123 | - represent a snapshot of the project for an instant in time. | |
| 124 | - Check-ins exist only inside of the repository. This contrasts with | |
| 125 | - a check-out which is a collection of files outside of the repository. | |
| 126 | - <ul> | |
| 127 | - <li><p>Every check-out knows the check-in from which it was derived. | |
| 128 | - But check-outs might have been edited and so might not exactly | |
| 129 | - match their associated check-in. | |
| 130 | - <li><p>Check-ins are immutable. They can never be changed. But | |
| 131 | - check-outs are collections of ordinary files on disk. The | |
| 132 | - files of a check-out can be edited just like any other file. | |
| 133 | - <li><p>A check-in can be thought of as an historical snapshot of a | |
| 134 | - check-out. | |
| 135 | - <li><p>"Check-in", "version", "snapshot", and "revision" are synonyms. | |
| 136 | - <li><p> When used as a noun, the word "commit" is another synonym | |
| 137 | - for "check-in". When used as a verb, the word "commit" | |
| 138 | - means to create a new check-in. | |
| 139 | - </ul> | |
| 140 | -</ul> | |
| 44 | +Moved to [./glossary.md | a separate document]. | |
| 141 | 45 | |
| 142 | 46 | <p><b>III. Basic Fossil commands</b> |
| 143 | 47 | |
| 144 | 48 | <ul> |
| 145 | 49 | <li><p><b>clone</b> → |
| 146 | 50 |
| --- www/whyusefossil.wiki | |
| +++ www/whyusefossil.wiki | |
| @@ -39,107 +39,11 @@ | |
| 39 | </ol> |
| 40 | </ol> |
| 41 | |
| 42 | <p id="definitions"><b>II. Definitions</b></p> |
| 43 | |
| 44 | <ul> |
| 45 | <li><p><b>Project</b> → |
| 46 | a collection of computer files that serve some common |
| 47 | purpose. Often the project is a software application and the |
| 48 | individual files are source code together with makefiles, scripts, and |
| 49 | "README.txt" files. Other examples of projects include books or |
| 50 | manuals in which each chapter or section is held in a separate file. |
| 51 | <ul> |
| 52 | <li><p>Projects change and evolve. The whole purpose of version |
| 53 | control is to track and manage that evolution. |
| 54 | <li><p>Most projects contain many files, but it is possible |
| 55 | to have a project consisting of just a single file. |
| 56 | <li><p>Fossil requires that |
| 57 | all the files for a project must be collected into a single |
| 58 | directory hierarchy - a single folder possibly with layers |
| 59 | of subfolders. Fossil is not a good choice for managing a |
| 60 | project that has files scattered hither and yon all over |
| 61 | the disk. In other words, Fossil only works for projects |
| 62 | where the files are laid out such that they can be archived |
| 63 | into a ZIP file or tarball. |
| 64 | </ul> |
| 65 | <li><p><b>Repository</b> → |
| 66 | (also called "repo") a single file that contains |
| 67 | all historical versions of all files in a project. A repo is similar |
| 68 | to a ZIP archive in that it is a single file that stores compressed |
| 69 | versions of many other files. Files can be extracted from the |
| 70 | repo and new files can be added to the repo, just as with a ZIP |
| 71 | archive. But a repo has other capabilities above and beyond |
| 72 | what a ZIP archive can do. |
| 73 | <ul> |
| 74 | <li><p>Fossil does not care what you name your repository files, |
| 75 | though names ending with ".fossil" are recommended. |
| 76 | <li><p>A single project typically has multiple, redundant repositories on |
| 77 | separate machines. |
| 78 | <li><p>All repositories stay synchronized with one another by exchanging |
| 79 | information via HTTPS or SSH. |
| 80 | <li><p>All repos for a single project redundantly store all information |
| 81 | about that project. So if any one repo is lost due to a disk |
| 82 | crash, all content is preserved in the surviving repos. |
| 83 | <li><p>The usual arrangement is one repository per user. And since |
| 84 | most users these days have their own computer, that means one |
| 85 | repository per computer. But this is not a requirement. It is |
| 86 | ok to have multiple copies of the same repository on the same |
| 87 | computer. |
| 88 | <li><p>Fossil works fine with just a single copy of the repository. |
| 89 | But in that case there is no redundancy. If that one repository |
| 90 | file is lost due to a hardware malfunction, then there is no way |
| 91 | to recover the project. |
| 92 | <li><p>Best practice is to keep all repositories for a user in a single |
| 93 | folder. Folders such as "~/Fossils" or "%USERPROFILE%\Fossils" |
| 94 | are recommended. Fossil itself does not care where the repositories |
| 95 | are stored. Nor does Fossil require repositories to be |
| 96 | kept in the same folder. But it is easier to organize your work |
| 97 | if all repositories are kept in the same place. |
| 98 | </ul> |
| 99 | <li><p><b>Check-out</b> → |
| 100 | a set of files that have been extracted from a |
| 101 | repository and that represent a particular version or snapshot of |
| 102 | the project. |
| 103 | <ul> |
| 104 | <li><p>Check-outs must be on the same computer as the repository from |
| 105 | which they are extracted. This is just like with a ZIP archive: |
| 106 | one must have the ZIP archive file on the local machine before |
| 107 | extracting files from ZIP archive. |
| 108 | <li><p>There can be multiple check-outs (in different folders) from |
| 109 | the same repository. |
| 110 | <li><p>The repository must be on the same computer as the check-out, but |
| 111 | the relative locations of the repo and the check-out are arbitrary. |
| 112 | The repository may be located inside the folder holding the |
| 113 | check-out, but it certainly does not have to be and usually is |
| 114 | not. |
| 115 | <li><p>A special file exists in every check-out that tells Fossil from |
| 116 | which repository the check-out was extracted, and which version of |
| 117 | the project the check-out represents. This is the ".fslckout" file |
| 118 | on unix systems or the "_FOSSIL_" file on Windows. |
| 119 | </ul> |
| 120 | <li><p><b>Check-in</b> → |
| 121 | another name for a particular version of the project. |
| 122 | A check-in is a collection of files inside of a repository that |
| 123 | represent a snapshot of the project for an instant in time. |
| 124 | Check-ins exist only inside of the repository. This contrasts with |
| 125 | a check-out which is a collection of files outside of the repository. |
| 126 | <ul> |
| 127 | <li><p>Every check-out knows the check-in from which it was derived. |
| 128 | But check-outs might have been edited and so might not exactly |
| 129 | match their associated check-in. |
| 130 | <li><p>Check-ins are immutable. They can never be changed. But |
| 131 | check-outs are collections of ordinary files on disk. The |
| 132 | files of a check-out can be edited just like any other file. |
| 133 | <li><p>A check-in can be thought of as an historical snapshot of a |
| 134 | check-out. |
| 135 | <li><p>"Check-in", "version", "snapshot", and "revision" are synonyms. |
| 136 | <li><p> When used as a noun, the word "commit" is another synonym |
| 137 | for "check-in". When used as a verb, the word "commit" |
| 138 | means to create a new check-in. |
| 139 | </ul> |
| 140 | </ul> |
| 141 | |
| 142 | <p><b>III. Basic Fossil commands</b> |
| 143 | |
| 144 | <ul> |
| 145 | <li><p><b>clone</b> → |
| 146 |
| --- www/whyusefossil.wiki | |
| +++ www/whyusefossil.wiki | |
| @@ -39,107 +39,11 @@ | |
| 39 | </ol> |
| 40 | </ol> |
| 41 | |
| 42 | <p id="definitions"><b>II. Definitions</b></p> |
| 43 | |
| 44 | Moved to [./glossary.md | a separate document]. |
| 45 | |
| 46 | <p><b>III. Basic Fossil commands</b> |
| 47 | |
| 48 | <ul> |
| 49 | <li><p><b>clone</b> → |
| 50 |