Fossil SCM
Recast the section on dotfiles in the gitusers doc to cover "fossil close" and its implications more broadly.
Commit
526446c23ce70a96e96dd20e0315baf6e8657984411f09c9b2f2b04d3f6c2c57
Parent
30894085f42dc5c…
1 file changed
+23
-7
+23
-7
| --- www/gitusers.md | ||
| +++ www/gitusers.md | ||
| @@ -161,25 +161,40 @@ | ||
| 161 | 161 | a [Heisenbug][hb], forcing it to show itself. While that runs, you can |
| 162 | 162 | open a new terminal tab, “`cd ../trunk`”, and get back |
| 163 | 163 | to work. |
| 164 | 164 | |
| 165 | 165 | |
| 166 | -#### <a id="dotfile"></a> `.git` vs. `.fslckout` | |
| 166 | +#### <a id="close" name="dotfile"></a> Closing A Check-Out | |
| 167 | 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 | |
| 168 | +The `fossil close` command dissaociates a check-out directory from the | |
| 169 | +Fossil repository database, nondestructively inverting `fossil open`. It | |
| 170 | +won’t remove the managed files, and unless you give the `--force` | |
| 171 | +option, it won’t let you close the check-out with uncommitted changes to | |
| 172 | +those managed files. | |
| 173 | + | |
| 174 | +The `close` command also refuses to run without `--force` when you have | |
| 175 | +certain precious per-checkout data, which Fossil stores in the | |
| 176 | +`.fslckout` file at the root of a check-out directory. This is a SQLite | |
| 171 | 177 | database that keeps track of local state such as what version you have |
| 172 | 178 | 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. | |
| 179 | +[undo] buffers, per-checkout [settings][set], and so forth. The stash | |
| 180 | +and undo buffers are considered precious, being “uncommitted changes,” | |
| 181 | +so you have to force Fossil to discard these as part of closing the | |
| 182 | +check-out. | |
| 183 | + | |
| 184 | +Thus, `.fslckout` is not the same thing as `.git`! | |
| 176 | 185 | |
| 177 | 186 | In native Windows builds of Fossil — that is, excluding Cygwin and WSL |
| 178 | 187 | builds, which follow POSIX conventions — this file is called `_FOSSIL_` |
| 179 | 188 | instead to get around the historical 3-character extension limit with |
| 180 | 189 | certain legacy filesystems. |
| 190 | + | |
| 191 | +Closing a check-out directory is a rare operation. One common use case | |
| 192 | +is that you’re about to delete it, so you want Fossil to forget about it | |
| 193 | +for the purposes of commands like [`fossil all`][all]. | |
| 194 | + | |
| 195 | +[all]: /help?cmd=all | |
| 181 | 196 | |
| 182 | 197 | |
| 183 | 198 | #### <a id="iip"></a> Init In Place |
| 184 | 199 | |
| 185 | 200 | To illustrate these differences, consider this common Git “init in place” |
| @@ -216,10 +231,11 @@ | ||
| 216 | 231 | Git, not to commend this `.fsl`-at-project-root trick to you. A better |
| 217 | 232 | choice would be `~/museum/home/long-established-project.fossil`, if |
| 218 | 233 | you’re following the directory scheme exemplified above. That said, it |
| 219 | 234 | does emphasize an earlier point: Fossil doesn’t care where you put the |
| 220 | 235 | repo DB file or what you name it. |
| 236 | + | |
| 221 | 237 | |
| 222 | 238 | [clone]: /help?cmd=clone |
| 223 | 239 | [close]: /help?cmd=close |
| 224 | 240 | [gloss]: ./whyusefossil.wiki#definitions |
| 225 | 241 | [hb]: https://en.wikipedia.org/wiki/Heisenbug |
| 226 | 242 |
| --- www/gitusers.md | |
| +++ www/gitusers.md | |
| @@ -161,25 +161,40 @@ | |
| 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 | |
| 183 | #### <a id="iip"></a> Init In Place |
| 184 | |
| 185 | To illustrate these differences, consider this common Git “init in place” |
| @@ -216,10 +231,11 @@ | |
| 216 | Git, not to commend this `.fsl`-at-project-root trick to you. A better |
| 217 | choice would be `~/museum/home/long-established-project.fossil`, if |
| 218 | you’re following the directory scheme exemplified above. That said, it |
| 219 | does emphasize an earlier point: Fossil doesn’t care where you put the |
| 220 | repo DB file or what you name it. |
| 221 | |
| 222 | [clone]: /help?cmd=clone |
| 223 | [close]: /help?cmd=close |
| 224 | [gloss]: ./whyusefossil.wiki#definitions |
| 225 | [hb]: https://en.wikipedia.org/wiki/Heisenbug |
| 226 |
| --- www/gitusers.md | |
| +++ www/gitusers.md | |
| @@ -161,25 +161,40 @@ | |
| 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="close" name="dotfile"></a> Closing A Check-Out |
| 167 | |
| 168 | The `fossil close` command dissaociates a check-out directory from the |
| 169 | Fossil repository database, nondestructively inverting `fossil open`. It |
| 170 | won’t remove the managed files, and unless you give the `--force` |
| 171 | option, it won’t let you close the check-out with uncommitted changes to |
| 172 | those managed files. |
| 173 | |
| 174 | The `close` command also refuses to run without `--force` when you have |
| 175 | certain precious per-checkout data, which Fossil stores in the |
| 176 | `.fslckout` file at the root of a check-out directory. This is a SQLite |
| 177 | database that keeps track of local state such as what version you have |
| 178 | checked out, the contents of the [stash] for that working directory, the |
| 179 | [undo] buffers, per-checkout [settings][set], and so forth. The stash |
| 180 | and undo buffers are considered precious, being “uncommitted changes,” |
| 181 | so you have to force Fossil to discard these as part of closing the |
| 182 | check-out. |
| 183 | |
| 184 | Thus, `.fslckout` is not the same thing as `.git`! |
| 185 | |
| 186 | In native Windows builds of Fossil — that is, excluding Cygwin and WSL |
| 187 | builds, which follow POSIX conventions — this file is called `_FOSSIL_` |
| 188 | instead to get around the historical 3-character extension limit with |
| 189 | certain legacy filesystems. |
| 190 | |
| 191 | Closing a check-out directory is a rare operation. One common use case |
| 192 | is that you’re about to delete it, so you want Fossil to forget about it |
| 193 | for the purposes of commands like [`fossil all`][all]. |
| 194 | |
| 195 | [all]: /help?cmd=all |
| 196 | |
| 197 | |
| 198 | #### <a id="iip"></a> Init In Place |
| 199 | |
| 200 | To illustrate these differences, consider this common Git “init in place” |
| @@ -216,10 +231,11 @@ | |
| 231 | Git, not to commend this `.fsl`-at-project-root trick to you. A better |
| 232 | choice would be `~/museum/home/long-established-project.fossil`, if |
| 233 | you’re following the directory scheme exemplified above. That said, it |
| 234 | does emphasize an earlier point: Fossil doesn’t care where you put the |
| 235 | repo DB file or what you name it. |
| 236 | |
| 237 | |
| 238 | [clone]: /help?cmd=clone |
| 239 | [close]: /help?cmd=close |
| 240 | [gloss]: ./whyusefossil.wiki#definitions |
| 241 | [hb]: https://en.wikipedia.org/wiki/Heisenbug |
| 242 |