Fossil SCM
Added the "Git Worktrees" section to the gitusers doc, which acts as a complement to the "multiple check-out directories" section of the new ckout-workflow.md doc. It gives us a place to talk about git-worktree and git clone --separate-git-dir.
Commit
31f8a835dafbe8a867ed80646557b6d2c25d742d899af7d774e2ed004dddf019
Parent
f2c5ab91a96551b…
1 file changed
+62
-3
+62
-3
| --- www/gitusers.md | ||
| +++ www/gitusers.md | ||
| @@ -50,11 +50,11 @@ | ||
| 50 | 50 | on, extracted for you from the repository database file by the `fossil` |
| 51 | 51 | program. |
| 52 | 52 | |
| 53 | 53 | Git commingles these two by default, with the repository stored in a |
| 54 | 54 | `.git` subdirectory underneath your working directory. There are ways to |
| 55 | -emulate the Fossil working style in Git, but because they’re not | |
| 55 | +[emulate the Fossil working style in Git](#worktree), but because they’re not | |
| 56 | 56 | designed into the core concept of the tool, Git tutorials usually |
| 57 | 57 | advocate a switch-in-place working mode instead, so that is how most |
| 58 | 58 | users end up working with Git. Contrast [Fossil’s check-out workflow |
| 59 | 59 | document][ckwf] to see the practical differences. |
| 60 | 60 | |
| @@ -156,14 +156,73 @@ | ||
| 156 | 156 | is that you’re about to delete the directory, so you want Fossil to forget about it |
| 157 | 157 | for the purposes of commands like [`fossil all`][all]. Even that isn’t |
| 158 | 158 | necessary, because Fossil will detect that this has happened and forget |
| 159 | 159 | the working directory for you. |
| 160 | 160 | |
| 161 | -The closest equivalent in Git is `git worktree remove`. | |
| 162 | - | |
| 163 | 161 | [all]: /help?cmd=all |
| 164 | 162 | |
| 163 | + | |
| 164 | +#### <a id="worktree"></a> Git Worktrees | |
| 165 | + | |
| 166 | +There are at least three different ways to get [Fossil-style multiple | |
| 167 | +check-out directories][mcw] with Git. | |
| 168 | + | |
| 169 | +The old way is to simply symlink the `.git` directory between working | |
| 170 | +trees: | |
| 171 | + | |
| 172 | + mkdir ../foo-branch | |
| 173 | + ln -s ../actual-clone-dir/.git . | |
| 174 | + git checkout foo-branch | |
| 175 | + | |
| 176 | +The symlink trick has a number of problems, the largest being that | |
| 177 | +symlinks weren’t available on Windows until Vista, and until the Windows | |
| 178 | +10 Creators Update was released in spring of 2017, you had to be an | |
| 179 | +Administrator to use the feature besides. ([Source][wsyml]) Git solved | |
| 180 | +this problem two years earlier with the `git-worktree` command in Git | |
| 181 | +2.5: | |
| 182 | + | |
| 183 | + git worktree add ../foo-branch foo-branch | |
| 184 | + cd ../foo-branch | |
| 185 | + | |
| 186 | +That is approximately equivalent to this in Fossil: | |
| 187 | + | |
| 188 | + mkdir ../foo-branch | |
| 189 | + fossil open /path/to/repo.fossil foo-branch | |
| 190 | + | |
| 191 | +That then leads us to the closest equivalent in Git to [closing a Fossil | |
| 192 | +check-out](#close): | |
| 193 | + | |
| 194 | + git worktree remove . | |
| 195 | + | |
| 196 | +Note, however, that unlike `fossil close`, once the Git command | |
| 197 | +determines that there are no uncommitted changes, it blows away all of | |
| 198 | +the checked-out files! Fossil’s alternative is shorter, easier to | |
| 199 | +remember, and safer. | |
| 200 | + | |
| 201 | +There’s another way to get Fossil-like separate worktrees in Git: | |
| 202 | + | |
| 203 | + git clone --separate-git-dir repo.git https://example.com/repo | |
| 204 | + | |
| 205 | +This allows you to have your Git repository directory entirely separate | |
| 206 | +from your working tree, with `.git` in the check-out directory being a | |
| 207 | +file that points to `../repo.git`, in this example. | |
| 208 | + | |
| 209 | +As of Fossil 2.14, there is a direct equivalent: | |
| 210 | + | |
| 211 | + fossil clone https://example.com/repo | |
| 212 | + | |
| 213 | +It’s a shorter command because we deduce `repo.fossil` and the `repo/` | |
| 214 | +working directory from the last element of the path in the URI. If you | |
| 215 | +wanted to override both inferences, you’d say: | |
| 216 | + | |
| 217 | + fossil clone --workdir foo https://example.com/repo/bar | |
| 218 | + | |
| 219 | +That gets you `bar.fossil` with a `foo/` working directory. | |
| 220 | + | |
| 221 | +[mcw]: ./ckout-workflows.md#mcw | |
| 222 | +[wsyml]: https://blogs.windows.com/windowsdeveloper/2016/12/02/symlinks-windows-10/ | |
| 223 | + | |
| 165 | 224 | |
| 166 | 225 | #### <a id="iip"></a> Init In Place |
| 167 | 226 | |
| 168 | 227 | To illustrate the differences that Fossil’s separation of repository |
| 169 | 228 | from working directory creates in practice, consider this common Git “init in place” |
| 170 | 229 |
| --- www/gitusers.md | |
| +++ www/gitusers.md | |
| @@ -50,11 +50,11 @@ | |
| 50 | on, extracted for you from the repository database file by the `fossil` |
| 51 | program. |
| 52 | |
| 53 | Git commingles these two by default, with the repository stored in a |
| 54 | `.git` subdirectory underneath your working directory. There are ways to |
| 55 | emulate the Fossil working style in Git, but because they’re not |
| 56 | designed into the core concept of the tool, Git tutorials usually |
| 57 | advocate a switch-in-place working mode instead, so that is how most |
| 58 | users end up working with Git. Contrast [Fossil’s check-out workflow |
| 59 | document][ckwf] to see the practical differences. |
| 60 | |
| @@ -156,14 +156,73 @@ | |
| 156 | is that you’re about to delete the directory, so you want Fossil to forget about it |
| 157 | for the purposes of commands like [`fossil all`][all]. Even that isn’t |
| 158 | necessary, because Fossil will detect that this has happened and forget |
| 159 | the working directory for you. |
| 160 | |
| 161 | The closest equivalent in Git is `git worktree remove`. |
| 162 | |
| 163 | [all]: /help?cmd=all |
| 164 | |
| 165 | |
| 166 | #### <a id="iip"></a> Init In Place |
| 167 | |
| 168 | To illustrate the differences that Fossil’s separation of repository |
| 169 | from working directory creates in practice, consider this common Git “init in place” |
| 170 |
| --- www/gitusers.md | |
| +++ www/gitusers.md | |
| @@ -50,11 +50,11 @@ | |
| 50 | on, extracted for you from the repository database file by the `fossil` |
| 51 | program. |
| 52 | |
| 53 | Git commingles these two by default, with the repository stored in a |
| 54 | `.git` subdirectory underneath your working directory. There are ways to |
| 55 | [emulate the Fossil working style in Git](#worktree), but because they’re not |
| 56 | designed into the core concept of the tool, Git tutorials usually |
| 57 | advocate a switch-in-place working mode instead, so that is how most |
| 58 | users end up working with Git. Contrast [Fossil’s check-out workflow |
| 59 | document][ckwf] to see the practical differences. |
| 60 | |
| @@ -156,14 +156,73 @@ | |
| 156 | is that you’re about to delete the directory, so you want Fossil to forget about it |
| 157 | for the purposes of commands like [`fossil all`][all]. Even that isn’t |
| 158 | necessary, because Fossil will detect that this has happened and forget |
| 159 | the working directory for you. |
| 160 | |
| 161 | [all]: /help?cmd=all |
| 162 | |
| 163 | |
| 164 | #### <a id="worktree"></a> Git Worktrees |
| 165 | |
| 166 | There are at least three different ways to get [Fossil-style multiple |
| 167 | check-out directories][mcw] with Git. |
| 168 | |
| 169 | The old way is to simply symlink the `.git` directory between working |
| 170 | trees: |
| 171 | |
| 172 | mkdir ../foo-branch |
| 173 | ln -s ../actual-clone-dir/.git . |
| 174 | git checkout foo-branch |
| 175 | |
| 176 | The symlink trick has a number of problems, the largest being that |
| 177 | symlinks weren’t available on Windows until Vista, and until the Windows |
| 178 | 10 Creators Update was released in spring of 2017, you had to be an |
| 179 | Administrator to use the feature besides. ([Source][wsyml]) Git solved |
| 180 | this problem two years earlier with the `git-worktree` command in Git |
| 181 | 2.5: |
| 182 | |
| 183 | git worktree add ../foo-branch foo-branch |
| 184 | cd ../foo-branch |
| 185 | |
| 186 | That is approximately equivalent to this in Fossil: |
| 187 | |
| 188 | mkdir ../foo-branch |
| 189 | fossil open /path/to/repo.fossil foo-branch |
| 190 | |
| 191 | That then leads us to the closest equivalent in Git to [closing a Fossil |
| 192 | check-out](#close): |
| 193 | |
| 194 | git worktree remove . |
| 195 | |
| 196 | Note, however, that unlike `fossil close`, once the Git command |
| 197 | determines that there are no uncommitted changes, it blows away all of |
| 198 | the checked-out files! Fossil’s alternative is shorter, easier to |
| 199 | remember, and safer. |
| 200 | |
| 201 | There’s another way to get Fossil-like separate worktrees in Git: |
| 202 | |
| 203 | git clone --separate-git-dir repo.git https://example.com/repo |
| 204 | |
| 205 | This allows you to have your Git repository directory entirely separate |
| 206 | from your working tree, with `.git` in the check-out directory being a |
| 207 | file that points to `../repo.git`, in this example. |
| 208 | |
| 209 | As of Fossil 2.14, there is a direct equivalent: |
| 210 | |
| 211 | fossil clone https://example.com/repo |
| 212 | |
| 213 | It’s a shorter command because we deduce `repo.fossil` and the `repo/` |
| 214 | working directory from the last element of the path in the URI. If you |
| 215 | wanted to override both inferences, you’d say: |
| 216 | |
| 217 | fossil clone --workdir foo https://example.com/repo/bar |
| 218 | |
| 219 | That gets you `bar.fossil` with a `foo/` working directory. |
| 220 | |
| 221 | [mcw]: ./ckout-workflows.md#mcw |
| 222 | [wsyml]: https://blogs.windows.com/windowsdeveloper/2016/12/02/symlinks-windows-10/ |
| 223 | |
| 224 | |
| 225 | #### <a id="iip"></a> Init In Place |
| 226 | |
| 227 | To illustrate the differences that Fossil’s separation of repository |
| 228 | from working directory creates in practice, consider this common Git “init in place” |
| 229 |