Fossil SCM
Edit pass for clarity on the ckout-workflows doc
Commit
ea594514cc98ac7d83c3510eed121811c9135d0f44e750647c3784397e49a1e9
Parent
3f6f7deaf6d434d…
1 file changed
+26
-38
+26
-38
| --- www/ckout-workflows.md | ||
| +++ www/ckout-workflows.md | ||
| @@ -2,12 +2,11 @@ | ||
| 2 | 2 | |
| 3 | 3 | Because Fossil separates the concept of “check-out directory” from |
| 4 | 4 | “repository DB file,” it gives you the freedom to choose from several |
| 5 | 5 | working styles. Contrast Git, where the two concepts are normally |
| 6 | 6 | intermingled in a single working directory, which strongly encourages |
| 7 | -the “update in place” working style, leaving its `git-worktree` feature | |
| 8 | -underutilized. | |
| 7 | +the “update in place” working style. | |
| 9 | 8 | |
| 10 | 9 | |
| 11 | 10 | ## <a id="mcw"></a> Multiple-Checkout Workflow |
| 12 | 11 | |
| 13 | 12 | With Fossil, it is routine to have multiple check-outs from the same |
| @@ -48,13 +47,13 @@ | ||
| 48 | 47 | |
| 49 | 48 | Each check-out operates independently of the others. |
| 50 | 49 | |
| 51 | 50 | This multiple-checkouts working style is especially useful when Fossil stores source code in programming languages |
| 52 | 51 | where there is a “build” step that transforms source files into files |
| 53 | -you actually run or distribute. With Git’s typical switch-in-place workflow, | |
| 54 | -you have to rebuild all outputs from the source files | |
| 55 | -that differ between those versions whenever you switch versions. In the above Fossil working model, | |
| 52 | +you actually run or distribute. Contrast a switch-in-place workflow, | |
| 53 | +where you have to rebuild all outputs from the source files | |
| 54 | +that differ between those versions whenever you switch versions. In the above model, | |
| 56 | 55 | you switch versions with a “`cd`” command instead, so that you only have |
| 57 | 56 | to rebuild outputs from files you yourself change. |
| 58 | 57 | |
| 59 | 58 | This style is also useful when a check-out directory may be tied up with |
| 60 | 59 | some long-running process, as with the “test” example above, where you |
| @@ -72,13 +71,13 @@ | ||
| 72 | 71 | Nevertheless, it is possible to work in a more typical Git sort of |
| 73 | 72 | style, switching between versions in a single check-out directory. |
| 74 | 73 | |
| 75 | 74 | #### <a id="idiomatic"></a> The Idiomatic Fossil Way |
| 76 | 75 | |
| 77 | -With the clone done as in [the prior section](#mdw), the most idiomatic | |
| 78 | -way is as follows: | |
| 76 | +The most idiomatic way is as follows: | |
| 79 | 77 | |
| 78 | + fossil clone https://example.com/repo /path/to/repo.fossil | |
| 80 | 79 | mkdir work-dir |
| 81 | 80 | cd work-dir |
| 82 | 81 | fossil open /path/to/repo.fossil |
| 83 | 82 | ...work on trunk... |
| 84 | 83 | |
| @@ -87,56 +86,44 @@ | ||
| 87 | 86 | |
| 88 | 87 | Basically, you replace the `cd` commands in the multiple checkouts |
| 89 | 88 | workflow above with `fossil up` commands. |
| 90 | 89 | |
| 91 | 90 | |
| 92 | -#### <a id="open"></a> The Clone-and-Open Way | |
| 91 | +#### <a id="open"></a> Opening a Repository by URI | |
| 93 | 92 | |
| 94 | -In Fossil 2.12, we added a feature that allows you to get closer to | |
| 95 | -Git’s single-step clone-and-open behavior: | |
| 93 | +In Fossil 2.12, we added a feature to simplify the single-worktree use | |
| 94 | +case: | |
| 96 | 95 | |
| 97 | 96 | mkdir work-dir |
| 98 | 97 | cd work-dir |
| 99 | 98 | fossil open https://example.com/repo |
| 100 | 99 | |
| 101 | 100 | Now you have “trunk” open in `work-dir`, with the repo file stored as |
| 102 | 101 | `repo.fossil` in that same directory. |
| 103 | 102 | |
| 104 | -The use of [`fossil open`][open] here instead of [`fossil clone`][clone] | |
| 105 | -is likely to surprise a Git user. When we were [discussing][caod] | |
| 106 | -this, we considered following the Git command style, but we decided | |
| 107 | -against it because it goes against this core Fossil design principle: | |
| 108 | -given that the Fossil repo is separate from the check-out, why would you | |
| 109 | -expect asking for a repo clone to also create a check-out directory for | |
| 110 | -you? We view commingled repository + check-out as a design error in | |
| 111 | -Git, so why would we repeat the error? | |
| 112 | - | |
| 113 | -To see why we see this behavior is error-prone, consider that | |
| 114 | -`git clean` must have an exception to avoid nuking the `.git` directory. | |
| 115 | -We had to add that complication to `fossil clean` when we added the | |
| 116 | -`fossil open URI` feature: it won’t nuke the repo DB file. | |
| 117 | - | |
| 118 | -[clone]: /help?cmd=clone | |
| 119 | -[open]: /help?cmd=open | |
| 120 | - | |
| 121 | - | |
| 122 | -#### <a id="clone"></a> The Git Clone Way | |
| 123 | - | |
| 124 | -This feature didn’t placate many Git fans, though, so with Fossil 2.14 — | |
| 125 | -currently unreleased — we now allow this: | |
| 103 | +Users of Git may be surprised that it doesn’t create a directory for you | |
| 104 | +and that you `cd` into it *before* the clone-and-open step, not after. | |
| 105 | +This is because we’re overloading the “open” command, which already had | |
| 106 | +the behavior of opening into the current working directory. Changing it | |
| 107 | +to behave like `git clone` would therefore make the behavior surprising | |
| 108 | +to Fossil users. (See [our discussions][caod] if you want the full | |
| 109 | +details.) | |
| 110 | + | |
| 111 | + | |
| 112 | +#### <a id="clone"></a> Git-Like Clone-and-Open | |
| 113 | + | |
| 114 | +With Fossil 2.14 — currently unreleased — we added a more Git-like | |
| 115 | +alternative: | |
| 126 | 116 | |
| 127 | 117 | fossil clone https://fossil-scm.org/fossil |
| 118 | + cd fossil | |
| 128 | 119 | |
| 129 | 120 | This results in a `fossil.fossil` repo DB file and a `fossil/` working |
| 130 | 121 | directory. |
| 131 | 122 | |
| 132 | 123 | Note that our `clone URI` behavior does not commingle the repo and |
| 133 | -check-out, solving our major problem with the Git design, though we | |
| 134 | -still believe it to be confusing to have “clone” be part of “open,” and | |
| 135 | -still more confusing to have “open” part of “clone.” We prefer keeping | |
| 136 | -these operations entirely separate, either as at the [top of this | |
| 137 | -section](#scw) or [as in the prior one](#mcw). Still, please yourself. | |
| 124 | +check-out, solving our major problem with the Git design. | |
| 138 | 125 | |
| 139 | 126 | If you want the repo to be named something else, adjust the URL: |
| 140 | 127 | |
| 141 | 128 | fossil clone https://fossil-scm.org/fossil/fsl |
| 142 | 129 | |
| @@ -149,8 +136,9 @@ | ||
| 149 | 136 | fossil clone https://dev.example.com/repo/my-project |
| 150 | 137 | |
| 151 | 138 | The `/repo` addition is the key: whatever comes after is used as the |
| 152 | 139 | repository name. [See the docs][clone] for more details. |
| 153 | 140 | |
| 154 | -[caod]: https://fossil-scm.org/forum/forumpost/3f143cec74 | |
| 141 | +[caod]: https://fossil-scm.org/forum/forumpost/3f143cec74 | |
| 142 | +[clone]: /help?cmd=clone | |
| 155 | 143 | |
| 156 | 144 | <div style="height:50em" id="this-space-intentionally-left-blank"></div> |
| 157 | 145 |
| --- www/ckout-workflows.md | |
| +++ www/ckout-workflows.md | |
| @@ -2,12 +2,11 @@ | |
| 2 | |
| 3 | Because Fossil separates the concept of “check-out directory” from |
| 4 | “repository DB file,” it gives you the freedom to choose from several |
| 5 | working styles. Contrast Git, where the two concepts are normally |
| 6 | intermingled in a single working directory, which strongly encourages |
| 7 | the “update in place” working style, leaving its `git-worktree` feature |
| 8 | underutilized. |
| 9 | |
| 10 | |
| 11 | ## <a id="mcw"></a> Multiple-Checkout Workflow |
| 12 | |
| 13 | With Fossil, it is routine to have multiple check-outs from the same |
| @@ -48,13 +47,13 @@ | |
| 48 | |
| 49 | Each check-out operates independently of the others. |
| 50 | |
| 51 | This multiple-checkouts working style is especially useful when Fossil stores source code in programming languages |
| 52 | where there is a “build” step that transforms source files into files |
| 53 | you actually run or distribute. With Git’s typical switch-in-place workflow, |
| 54 | you have to rebuild all outputs from the source files |
| 55 | that differ between those versions whenever you switch versions. In the above Fossil working model, |
| 56 | you switch versions with a “`cd`” command instead, so that you only have |
| 57 | to rebuild outputs from files you yourself change. |
| 58 | |
| 59 | This style is also useful when a check-out directory may be tied up with |
| 60 | some long-running process, as with the “test” example above, where you |
| @@ -72,13 +71,13 @@ | |
| 72 | Nevertheless, it is possible to work in a more typical Git sort of |
| 73 | style, switching between versions in a single check-out directory. |
| 74 | |
| 75 | #### <a id="idiomatic"></a> The Idiomatic Fossil Way |
| 76 | |
| 77 | With the clone done as in [the prior section](#mdw), the most idiomatic |
| 78 | way is as follows: |
| 79 | |
| 80 | mkdir work-dir |
| 81 | cd work-dir |
| 82 | fossil open /path/to/repo.fossil |
| 83 | ...work on trunk... |
| 84 | |
| @@ -87,56 +86,44 @@ | |
| 87 | |
| 88 | Basically, you replace the `cd` commands in the multiple checkouts |
| 89 | workflow above with `fossil up` commands. |
| 90 | |
| 91 | |
| 92 | #### <a id="open"></a> The Clone-and-Open Way |
| 93 | |
| 94 | In Fossil 2.12, we added a feature that allows you to get closer to |
| 95 | Git’s single-step clone-and-open behavior: |
| 96 | |
| 97 | mkdir work-dir |
| 98 | cd work-dir |
| 99 | fossil open https://example.com/repo |
| 100 | |
| 101 | Now you have “trunk” open in `work-dir`, with the repo file stored as |
| 102 | `repo.fossil` in that same directory. |
| 103 | |
| 104 | The use of [`fossil open`][open] here instead of [`fossil clone`][clone] |
| 105 | is likely to surprise a Git user. When we were [discussing][caod] |
| 106 | this, we considered following the Git command style, but we decided |
| 107 | against it because it goes against this core Fossil design principle: |
| 108 | given that the Fossil repo is separate from the check-out, why would you |
| 109 | expect asking for a repo clone to also create a check-out directory for |
| 110 | you? We view commingled repository + check-out as a design error in |
| 111 | Git, so why would we repeat the error? |
| 112 | |
| 113 | To see why we see this behavior is error-prone, consider that |
| 114 | `git clean` must have an exception to avoid nuking the `.git` directory. |
| 115 | We had to add that complication to `fossil clean` when we added the |
| 116 | `fossil open URI` feature: it won’t nuke the repo DB file. |
| 117 | |
| 118 | [clone]: /help?cmd=clone |
| 119 | [open]: /help?cmd=open |
| 120 | |
| 121 | |
| 122 | #### <a id="clone"></a> The Git Clone Way |
| 123 | |
| 124 | This feature didn’t placate many Git fans, though, so with Fossil 2.14 — |
| 125 | currently unreleased — we now allow this: |
| 126 | |
| 127 | fossil clone https://fossil-scm.org/fossil |
| 128 | |
| 129 | This results in a `fossil.fossil` repo DB file and a `fossil/` working |
| 130 | directory. |
| 131 | |
| 132 | Note that our `clone URI` behavior does not commingle the repo and |
| 133 | check-out, solving our major problem with the Git design, though we |
| 134 | still believe it to be confusing to have “clone” be part of “open,” and |
| 135 | still more confusing to have “open” part of “clone.” We prefer keeping |
| 136 | these operations entirely separate, either as at the [top of this |
| 137 | section](#scw) or [as in the prior one](#mcw). Still, please yourself. |
| 138 | |
| 139 | If you want the repo to be named something else, adjust the URL: |
| 140 | |
| 141 | fossil clone https://fossil-scm.org/fossil/fsl |
| 142 | |
| @@ -149,8 +136,9 @@ | |
| 149 | fossil clone https://dev.example.com/repo/my-project |
| 150 | |
| 151 | The `/repo` addition is the key: whatever comes after is used as the |
| 152 | repository name. [See the docs][clone] for more details. |
| 153 | |
| 154 | [caod]: https://fossil-scm.org/forum/forumpost/3f143cec74 |
| 155 | |
| 156 | <div style="height:50em" id="this-space-intentionally-left-blank"></div> |
| 157 |
| --- www/ckout-workflows.md | |
| +++ www/ckout-workflows.md | |
| @@ -2,12 +2,11 @@ | |
| 2 | |
| 3 | Because Fossil separates the concept of “check-out directory” from |
| 4 | “repository DB file,” it gives you the freedom to choose from several |
| 5 | working styles. Contrast Git, where the two concepts are normally |
| 6 | intermingled in a single working directory, which strongly encourages |
| 7 | the “update in place” working style. |
| 8 | |
| 9 | |
| 10 | ## <a id="mcw"></a> Multiple-Checkout Workflow |
| 11 | |
| 12 | With Fossil, it is routine to have multiple check-outs from the same |
| @@ -48,13 +47,13 @@ | |
| 47 | |
| 48 | Each check-out operates independently of the others. |
| 49 | |
| 50 | This multiple-checkouts working style is especially useful when Fossil stores source code in programming languages |
| 51 | where there is a “build” step that transforms source files into files |
| 52 | you actually run or distribute. Contrast a switch-in-place workflow, |
| 53 | where you have to rebuild all outputs from the source files |
| 54 | that differ between those versions whenever you switch versions. In the above model, |
| 55 | you switch versions with a “`cd`” command instead, so that you only have |
| 56 | to rebuild outputs from files you yourself change. |
| 57 | |
| 58 | This style is also useful when a check-out directory may be tied up with |
| 59 | some long-running process, as with the “test” example above, where you |
| @@ -72,13 +71,13 @@ | |
| 71 | Nevertheless, it is possible to work in a more typical Git sort of |
| 72 | style, switching between versions in a single check-out directory. |
| 73 | |
| 74 | #### <a id="idiomatic"></a> The Idiomatic Fossil Way |
| 75 | |
| 76 | The most idiomatic way is as follows: |
| 77 | |
| 78 | fossil clone https://example.com/repo /path/to/repo.fossil |
| 79 | mkdir work-dir |
| 80 | cd work-dir |
| 81 | fossil open /path/to/repo.fossil |
| 82 | ...work on trunk... |
| 83 | |
| @@ -87,56 +86,44 @@ | |
| 86 | |
| 87 | Basically, you replace the `cd` commands in the multiple checkouts |
| 88 | workflow above with `fossil up` commands. |
| 89 | |
| 90 | |
| 91 | #### <a id="open"></a> Opening a Repository by URI |
| 92 | |
| 93 | In Fossil 2.12, we added a feature to simplify the single-worktree use |
| 94 | case: |
| 95 | |
| 96 | mkdir work-dir |
| 97 | cd work-dir |
| 98 | fossil open https://example.com/repo |
| 99 | |
| 100 | Now you have “trunk” open in `work-dir`, with the repo file stored as |
| 101 | `repo.fossil` in that same directory. |
| 102 | |
| 103 | Users of Git may be surprised that it doesn’t create a directory for you |
| 104 | and that you `cd` into it *before* the clone-and-open step, not after. |
| 105 | This is because we’re overloading the “open” command, which already had |
| 106 | the behavior of opening into the current working directory. Changing it |
| 107 | to behave like `git clone` would therefore make the behavior surprising |
| 108 | to Fossil users. (See [our discussions][caod] if you want the full |
| 109 | details.) |
| 110 | |
| 111 | |
| 112 | #### <a id="clone"></a> Git-Like Clone-and-Open |
| 113 | |
| 114 | With Fossil 2.14 — currently unreleased — we added a more Git-like |
| 115 | alternative: |
| 116 | |
| 117 | fossil clone https://fossil-scm.org/fossil |
| 118 | cd fossil |
| 119 | |
| 120 | This results in a `fossil.fossil` repo DB file and a `fossil/` working |
| 121 | directory. |
| 122 | |
| 123 | Note that our `clone URI` behavior does not commingle the repo and |
| 124 | check-out, solving our major problem with the Git design. |
| 125 | |
| 126 | If you want the repo to be named something else, adjust the URL: |
| 127 | |
| 128 | fossil clone https://fossil-scm.org/fossil/fsl |
| 129 | |
| @@ -149,8 +136,9 @@ | |
| 136 | fossil clone https://dev.example.com/repo/my-project |
| 137 | |
| 138 | The `/repo` addition is the key: whatever comes after is used as the |
| 139 | repository name. [See the docs][clone] for more details. |
| 140 | |
| 141 | [caod]: https://fossil-scm.org/forum/forumpost/3f143cec74 |
| 142 | [clone]: /help?cmd=clone |
| 143 | |
| 144 | <div style="height:50em" id="this-space-intentionally-left-blank"></div> |
| 145 |