Fossil SCM
Broke the long "Repositories And Checkouts Are Distinct" section in the gitusers doc up into sections, reordered some things, and added a Pikchr showing my ~museum directory structure as an example.
Commit
88a833075839d87bfa83869875262b207ad3cca2607112a596dff9918db81d11
Parent
a8d7878789da6e3…
1 file changed
+40
-14
+40
-14
| --- www/gitusers.md | ||
| +++ www/gitusers.md | ||
| @@ -49,11 +49,42 @@ | ||
| 49 | 49 | pointing at that same Git repository, but because it’s not designed into |
| 50 | 50 | the core concept of the tool, Git tutorials usually advocate a |
| 51 | 51 | switch-in-place working mode instead, so that is how most users end up |
| 52 | 52 | working with it. |
| 53 | 53 | |
| 54 | -You can use Fossil the same way, switching between versions in a | |
| 54 | + | |
| 55 | +#### <a id="rname"></a> Naming Repositories | |
| 56 | + | |
| 57 | +The Fossil repository database file can be named anything | |
| 58 | +you want, with a single exception: if you’re going to use the | |
| 59 | +[`fossil server DIRECTORY`][server] feature, the repositories you wish | |
| 60 | +to serve need to be stored together in a flat directory and have a | |
| 61 | +"`.fossil`" suffix. That aside, you can follow any other convention that | |
| 62 | +makes sense to you. | |
| 63 | + | |
| 64 | +This author uses a scheme like the following on mobile machines that | |
| 65 | +shuttle between home and the office: | |
| 66 | + | |
| 67 | +``` pikchr toggle indent | |
| 68 | +box "~/museum/" fit ; right ; "where one stores valuable fossils" | |
| 69 | + | |
| 70 | +arrow down 50% from previous box.s then right 50% | |
| 71 | +box "work/" fit ; line dashed right ; "projects from $dayjob" | |
| 72 | + | |
| 73 | +arrow down 50% from 2nd vertex of previous arrow then right 50% | |
| 74 | +box "home/" fit ; line dashed right until even with previous text.w ; "personal at-home projects" | |
| 75 | + | |
| 76 | +arrow down 50% from 2nd vertex of previous arrow then right 50% | |
| 77 | +box "other/" fit ; line dashed right until even with previous text.w ; "clones of Fossil itself, SQLite, etc." | |
| 78 | +``` | |
| 79 | + | |
| 80 | +On a Windows box, you might choose "`C:\Fossils`" instead, for example. | |
| 81 | + | |
| 82 | + | |
| 83 | +#### <a id="scw"></a> Single-Checkout Workflows | |
| 84 | + | |
| 85 | +You can use Fossil in the typical Git way, switching between versions in a | |
| 55 | 86 | single check-out directory: |
| 56 | 87 | |
| 57 | 88 | fossil clone https://example.com/repo /path/to/repo.fossil |
| 58 | 89 | mkdir work-dir |
| 59 | 90 | cd work-dir |
| @@ -85,20 +116,12 @@ | ||
| 85 | 116 | before opening it. If `fossil open URI` worked like `git clone`, that |
| 86 | 117 | would mean `fossil open` has two different ways of working depending on |
| 87 | 118 | the argument, which is a non-Fossil sort of thing to do. We strive for |
| 88 | 119 | consistent behavior across commands and modes. |
| 89 | 120 | |
| 90 | -The Fossil repository file can be named anything you want, with a single | |
| 91 | -exception: if you’re going to use the [`fossil server DIRECTORY`][server] | |
| 92 | -feature, the repositories need to have a "`.fossil`" suffix. That aside, | |
| 93 | -you can follow any other convention that makes sense to you. | |
| 94 | - | |
| 95 | -Many Fossil users gather all of their Fossil repositories | |
| 96 | -in a single directory on their machine, such as "`~/museum`" or | |
| 97 | -"`C:\Fossils`". This can help humans to keep their repositories | |
| 98 | -organized, but Fossil itself doesn't really care. (Why “museum”? | |
| 99 | -Because that is where one stores valuable fossils.) | |
| 121 | + | |
| 122 | +#### <a id="mcw"></a> Multiple-Checkout Workflows | |
| 100 | 123 | |
| 101 | 124 | Because Fossil cleanly separates the repository from the check-out, it |
| 102 | 125 | is routine to have multiple check-outs from the same repository: |
| 103 | 126 | |
| 104 | 127 | mkdir -p ~/src/my-project/trunk |
| @@ -137,23 +160,26 @@ | ||
| 137 | 160 | might need to run an hours-long brute-force replication script to tickle |
| 138 | 161 | a [Heisenbug][hb], forcing it to show itself. While that runs, you can |
| 139 | 162 | open a new terminal tab, “`cd ../trunk`”, and get back |
| 140 | 163 | to work. |
| 141 | 164 | |
| 165 | + | |
| 166 | +#### <a id="dotfile"></a> `.git` vs. `.fslckout` | |
| 167 | + | |
| 142 | 168 | Git users may be initially confused by the `.fslckout` file at the root |
| 143 | 169 | of a check-out directory. |
| 144 | 170 | This is not the same thing as `.git`. It’s a per-checkout SQLite |
| 145 | 171 | database that keeps track of local state such as what version you have |
| 146 | 172 | checked out, the contents of the [stash] for that working directory, the |
| 147 | 173 | [undo] buffers, per-checkout [settings][set], and so forth. Largely what Fossil |
| 148 | 174 | does when you ask it to [close] a check-out is to remove this file after |
| 149 | 175 | making certain safety checks. |
| 150 | 176 | |
| 151 | -(In native Windows builds of Fossil, this file is called `_FOSSIL_` | |
| 177 | +In native Windows builds of Fossil — that is, excluding Cygwin and WSL | |
| 178 | +builds, which follow POSIX conventions — this file is called `_FOSSIL_` | |
| 152 | 179 | instead to get around the historical 3-character extension limit with |
| 153 | -certain legacy filesystems. “Native” here is a distinction to exclude | |
| 154 | -Cygwin and WSL builds, which use `.fslckout`.) | |
| 180 | +certain legacy filesystems. | |
| 155 | 181 | |
| 156 | 182 | [clone]: /help?cmd=clone |
| 157 | 183 | [close]: /help?cmd=close |
| 158 | 184 | [gloss]: ./whyusefossil.wiki#definitions |
| 159 | 185 | [hb]: https://en.wikipedia.org/wiki/Heisenbug |
| 160 | 186 |
| --- www/gitusers.md | |
| +++ www/gitusers.md | |
| @@ -49,11 +49,42 @@ | |
| 49 | pointing at that same Git repository, but because it’s not designed into |
| 50 | the core concept of the tool, Git tutorials usually advocate a |
| 51 | switch-in-place working mode instead, so that is how most users end up |
| 52 | working with it. |
| 53 | |
| 54 | You can use Fossil the same way, switching between versions in a |
| 55 | single check-out directory: |
| 56 | |
| 57 | fossil clone https://example.com/repo /path/to/repo.fossil |
| 58 | mkdir work-dir |
| 59 | cd work-dir |
| @@ -85,20 +116,12 @@ | |
| 85 | before opening it. If `fossil open URI` worked like `git clone`, that |
| 86 | would mean `fossil open` has two different ways of working depending on |
| 87 | the argument, which is a non-Fossil sort of thing to do. We strive for |
| 88 | consistent behavior across commands and modes. |
| 89 | |
| 90 | The Fossil repository file can be named anything you want, with a single |
| 91 | exception: if you’re going to use the [`fossil server DIRECTORY`][server] |
| 92 | feature, the repositories need to have a "`.fossil`" suffix. That aside, |
| 93 | you can follow any other convention that makes sense to you. |
| 94 | |
| 95 | Many Fossil users gather all of their Fossil repositories |
| 96 | in a single directory on their machine, such as "`~/museum`" or |
| 97 | "`C:\Fossils`". This can help humans to keep their repositories |
| 98 | organized, but Fossil itself doesn't really care. (Why “museum”? |
| 99 | Because that is where one stores valuable fossils.) |
| 100 | |
| 101 | Because Fossil cleanly separates the repository from the check-out, it |
| 102 | is routine to have multiple check-outs from the same repository: |
| 103 | |
| 104 | mkdir -p ~/src/my-project/trunk |
| @@ -137,23 +160,26 @@ | |
| 137 | might need to run an hours-long brute-force replication script to tickle |
| 138 | a [Heisenbug][hb], forcing it to show itself. While that runs, you can |
| 139 | open a new terminal tab, “`cd ../trunk`”, and get back |
| 140 | to work. |
| 141 | |
| 142 | Git users may be initially confused by the `.fslckout` file at the root |
| 143 | of a check-out directory. |
| 144 | This is not the same thing as `.git`. It’s a per-checkout SQLite |
| 145 | database that keeps track of local state such as what version you have |
| 146 | checked out, the contents of the [stash] for that working directory, the |
| 147 | [undo] buffers, per-checkout [settings][set], and so forth. Largely what Fossil |
| 148 | does when you ask it to [close] a check-out is to remove this file after |
| 149 | making certain safety checks. |
| 150 | |
| 151 | (In native Windows builds of Fossil, this file is called `_FOSSIL_` |
| 152 | instead to get around the historical 3-character extension limit with |
| 153 | certain legacy filesystems. “Native” here is a distinction to exclude |
| 154 | Cygwin and WSL builds, which use `.fslckout`.) |
| 155 | |
| 156 | [clone]: /help?cmd=clone |
| 157 | [close]: /help?cmd=close |
| 158 | [gloss]: ./whyusefossil.wiki#definitions |
| 159 | [hb]: https://en.wikipedia.org/wiki/Heisenbug |
| 160 |
| --- www/gitusers.md | |
| +++ www/gitusers.md | |
| @@ -49,11 +49,42 @@ | |
| 49 | pointing at that same Git repository, but because it’s not designed into |
| 50 | the core concept of the tool, Git tutorials usually advocate a |
| 51 | switch-in-place working mode instead, so that is how most users end up |
| 52 | working with it. |
| 53 | |
| 54 | |
| 55 | #### <a id="rname"></a> Naming Repositories |
| 56 | |
| 57 | The Fossil repository database file can be named anything |
| 58 | you want, with a single exception: if you’re going to use the |
| 59 | [`fossil server DIRECTORY`][server] feature, the repositories you wish |
| 60 | to serve need to be stored together in a flat directory and have a |
| 61 | "`.fossil`" suffix. That aside, you can follow any other convention that |
| 62 | makes sense to you. |
| 63 | |
| 64 | This author uses a scheme like the following on mobile machines that |
| 65 | shuttle between home and the office: |
| 66 | |
| 67 | ``` pikchr toggle indent |
| 68 | box "~/museum/" fit ; right ; "where one stores valuable fossils" |
| 69 | |
| 70 | arrow down 50% from previous box.s then right 50% |
| 71 | box "work/" fit ; line dashed right ; "projects from $dayjob" |
| 72 | |
| 73 | arrow down 50% from 2nd vertex of previous arrow then right 50% |
| 74 | box "home/" fit ; line dashed right until even with previous text.w ; "personal at-home projects" |
| 75 | |
| 76 | arrow down 50% from 2nd vertex of previous arrow then right 50% |
| 77 | box "other/" fit ; line dashed right until even with previous text.w ; "clones of Fossil itself, SQLite, etc." |
| 78 | ``` |
| 79 | |
| 80 | On a Windows box, you might choose "`C:\Fossils`" instead, for example. |
| 81 | |
| 82 | |
| 83 | #### <a id="scw"></a> Single-Checkout Workflows |
| 84 | |
| 85 | You can use Fossil in the typical Git way, switching between versions in a |
| 86 | single check-out directory: |
| 87 | |
| 88 | fossil clone https://example.com/repo /path/to/repo.fossil |
| 89 | mkdir work-dir |
| 90 | cd work-dir |
| @@ -85,20 +116,12 @@ | |
| 116 | before opening it. If `fossil open URI` worked like `git clone`, that |
| 117 | would mean `fossil open` has two different ways of working depending on |
| 118 | the argument, which is a non-Fossil sort of thing to do. We strive for |
| 119 | consistent behavior across commands and modes. |
| 120 | |
| 121 | |
| 122 | #### <a id="mcw"></a> Multiple-Checkout Workflows |
| 123 | |
| 124 | Because Fossil cleanly separates the repository from the check-out, it |
| 125 | is routine to have multiple check-outs from the same repository: |
| 126 | |
| 127 | mkdir -p ~/src/my-project/trunk |
| @@ -137,23 +160,26 @@ | |
| 160 | might need to run an hours-long brute-force replication script to tickle |
| 161 | a [Heisenbug][hb], forcing it to show itself. While that runs, you can |
| 162 | open a new terminal tab, “`cd ../trunk`”, and get back |
| 163 | to work. |
| 164 | |
| 165 | |
| 166 | #### <a id="dotfile"></a> `.git` vs. `.fslckout` |
| 167 | |
| 168 | Git users may be initially confused by the `.fslckout` file at the root |
| 169 | of a check-out directory. |
| 170 | This is not the same thing as `.git`. It’s a per-checkout SQLite |
| 171 | database that keeps track of local state such as what version you have |
| 172 | checked out, the contents of the [stash] for that working directory, the |
| 173 | [undo] buffers, per-checkout [settings][set], and so forth. Largely what Fossil |
| 174 | does when you ask it to [close] a check-out is to remove this file after |
| 175 | making certain safety checks. |
| 176 | |
| 177 | In native Windows builds of Fossil — that is, excluding Cygwin and WSL |
| 178 | builds, which follow POSIX conventions — this file is called `_FOSSIL_` |
| 179 | instead to get around the historical 3-character extension limit with |
| 180 | certain legacy filesystems. |
| 181 | |
| 182 | [clone]: /help?cmd=clone |
| 183 | [close]: /help?cmd=close |
| 184 | [gloss]: ./whyusefossil.wiki#definitions |
| 185 | [hb]: https://en.wikipedia.org/wiki/Heisenbug |
| 186 |