Fossil SCM
Several expansions on the new points in www/branching.wiki
Commit
bf048cd576fc265fc852c6011302b11c07369c5151ef0ed7348eaa418dcc94fb
Parent
184cf2087affd59…
1 file changed
+24
-16
+24
-16
| --- www/branching.wiki | ||
| +++ www/branching.wiki | ||
| @@ -223,19 +223,20 @@ | ||
| 223 | 223 | default when it has no better idea of which branch you mean.) |
| 224 | 224 | |
| 225 | 225 | |
| 226 | 226 | <h2 id="forking">Justifications For Forking</h2> |
| 227 | 227 | |
| 228 | -The primary cases where forking is justified are all when it is done purely | |
| 229 | -in software in order to avoid losing information: | |
| 228 | +The primary cases where forking is justified over branching are all when | |
| 229 | +it is done purely in software in order to avoid losing information: | |
| 230 | 230 | |
| 231 | 231 | <ol> |
| 232 | 232 | <li><p>By Fossil itself when two users check in children to the same |
| 233 | - leaf of a branch, as in Figure 2. If they're doing it because | |
| 234 | - autosync is disabled on one or both of the repositories, Fossil has | |
| 235 | - no way of knowing that it is creating a fork until the two | |
| 236 | - repositories are later sync'd manually.</p></li> | |
| 233 | + leaf of a branch, as in Figure 2. If the fork occurs because | |
| 234 | + autosync is disabled on one or both of the repositories or because | |
| 235 | + the user doing the check-in has no network connection at the moment | |
| 236 | + of the commit, Fossil has no way of knowing that it is creating a | |
| 237 | + fork until the two repositories are later sync'd.</p></li> | |
| 237 | 238 | |
| 238 | 239 | <li><p>By Fossil when the cloning hierarchy is more than 2 levels |
| 239 | 240 | deep. If your master repository is cloned by user A and then user B |
| 240 | 241 | clones from user A's repository, check-ins to user B's repo do not |
| 241 | 242 | check the master repo before allowing the check-in even with |
| @@ -243,28 +244,35 @@ | ||
| 243 | 244 | master repo that an inadvertent fork can be detected. |
| 244 | 245 | <br><br> |
| 245 | 246 | Because of this, we recommend that if you're using Fossil in a |
| 246 | 247 | distributed way like this, that check-ins be made only to the master |
| 247 | 248 | or its immediate child repos, and that those further down the chain |
| 248 | - be read-only clones.</p></li> | |
| 249 | + be read-only clones. This is not to say that we repudiate Fossil's | |
| 250 | + use as a Distributed Version Control System, just that such use is | |
| 251 | + prone to creating forks, by the nature of distributed development. | |
| 252 | + We hope we've made it clear in this document why forks on long-lived | |
| 253 | + shared working branches are a problem.</p></li> | |
| 249 | 254 | |
| 250 | 255 | <li><p>You've automated Fossil (e.g. with a shell script) and |
| 251 | - forking is a possibility, so you add "--allow-fork" to your | |
| 252 | - "checkin" commands to prevent Fossil from refusing the check-in due | |
| 253 | - to the fork. It's better to write such a script to detect this | |
| 254 | - condition and cope with it (e.g. "fossil update") but if the | |
| 255 | - alternative is losing information, you may feel justified in | |
| 256 | - creating forks that an interactive user must later clean up with | |
| 257 | - "fossil merge" commands.</p></li> | |
| 256 | + forking is a possibility, so you write <b>fossil commit | |
| 257 | + --allow-fork</b> commands to prevent Fossil from refusing the | |
| 258 | + check-in because it would create a fork. It's better to write such | |
| 259 | + a script to detect this condition and cope with it (e.g. <b>fossil | |
| 260 | + update</b>) but if the alternative is losing information, you may | |
| 261 | + feel justified in creating forks that an interactive user must later | |
| 262 | + clean up with <b>fossil merge</b> commands.</p></li> | |
| 258 | 263 | </ol> |
| 259 | 264 | |
| 260 | 265 | That leaves only one case where we can recommend use of "--allow-fork" |
| 261 | -by interactive users, while autosync is enabled: when you're working on | |
| 266 | +by interactive users: when you're working on | |
| 262 | 267 | a personal branch so that creating a dual-tipped branch isn't going to |
| 263 | 268 | cause any other user an inconvenience or risk forking the development. |
| 269 | +Only one developer is involved, and the fork may be short-lived, so | |
| 270 | +there is no risk of inadvertently forking the overall development effort. | |
| 264 | 271 | This is a good alternative to branching when you just need to |
| 265 | -temporarily fork the branch's development. | |
| 272 | +temporarily fork the branch's development. It avoids cluttering the | |
| 273 | +global branch namespace with short-lived temporary named branches. | |
| 266 | 274 | |
| 267 | 275 | There's a common generalization of that case: you're a solo developer, |
| 268 | 276 | so that the problems with branching vs forking simply don't matter. In |
| 269 | 277 | that case, feel free to use "--allow-fork" as much as you like. |
| 270 | 278 | |
| 271 | 279 |
| --- www/branching.wiki | |
| +++ www/branching.wiki | |
| @@ -223,19 +223,20 @@ | |
| 223 | default when it has no better idea of which branch you mean.) |
| 224 | |
| 225 | |
| 226 | <h2 id="forking">Justifications For Forking</h2> |
| 227 | |
| 228 | The primary cases where forking is justified are all when it is done purely |
| 229 | in software in order to avoid losing information: |
| 230 | |
| 231 | <ol> |
| 232 | <li><p>By Fossil itself when two users check in children to the same |
| 233 | leaf of a branch, as in Figure 2. If they're doing it because |
| 234 | autosync is disabled on one or both of the repositories, Fossil has |
| 235 | no way of knowing that it is creating a fork until the two |
| 236 | repositories are later sync'd manually.</p></li> |
| 237 | |
| 238 | <li><p>By Fossil when the cloning hierarchy is more than 2 levels |
| 239 | deep. If your master repository is cloned by user A and then user B |
| 240 | clones from user A's repository, check-ins to user B's repo do not |
| 241 | check the master repo before allowing the check-in even with |
| @@ -243,28 +244,35 @@ | |
| 243 | master repo that an inadvertent fork can be detected. |
| 244 | <br><br> |
| 245 | Because of this, we recommend that if you're using Fossil in a |
| 246 | distributed way like this, that check-ins be made only to the master |
| 247 | or its immediate child repos, and that those further down the chain |
| 248 | be read-only clones.</p></li> |
| 249 | |
| 250 | <li><p>You've automated Fossil (e.g. with a shell script) and |
| 251 | forking is a possibility, so you add "--allow-fork" to your |
| 252 | "checkin" commands to prevent Fossil from refusing the check-in due |
| 253 | to the fork. It's better to write such a script to detect this |
| 254 | condition and cope with it (e.g. "fossil update") but if the |
| 255 | alternative is losing information, you may feel justified in |
| 256 | creating forks that an interactive user must later clean up with |
| 257 | "fossil merge" commands.</p></li> |
| 258 | </ol> |
| 259 | |
| 260 | That leaves only one case where we can recommend use of "--allow-fork" |
| 261 | by interactive users, while autosync is enabled: when you're working on |
| 262 | a personal branch so that creating a dual-tipped branch isn't going to |
| 263 | cause any other user an inconvenience or risk forking the development. |
| 264 | This is a good alternative to branching when you just need to |
| 265 | temporarily fork the branch's development. |
| 266 | |
| 267 | There's a common generalization of that case: you're a solo developer, |
| 268 | so that the problems with branching vs forking simply don't matter. In |
| 269 | that case, feel free to use "--allow-fork" as much as you like. |
| 270 | |
| 271 |
| --- www/branching.wiki | |
| +++ www/branching.wiki | |
| @@ -223,19 +223,20 @@ | |
| 223 | default when it has no better idea of which branch you mean.) |
| 224 | |
| 225 | |
| 226 | <h2 id="forking">Justifications For Forking</h2> |
| 227 | |
| 228 | The primary cases where forking is justified over branching are all when |
| 229 | it is done purely in software in order to avoid losing information: |
| 230 | |
| 231 | <ol> |
| 232 | <li><p>By Fossil itself when two users check in children to the same |
| 233 | leaf of a branch, as in Figure 2. If the fork occurs because |
| 234 | autosync is disabled on one or both of the repositories or because |
| 235 | the user doing the check-in has no network connection at the moment |
| 236 | of the commit, Fossil has no way of knowing that it is creating a |
| 237 | fork until the two repositories are later sync'd.</p></li> |
| 238 | |
| 239 | <li><p>By Fossil when the cloning hierarchy is more than 2 levels |
| 240 | deep. If your master repository is cloned by user A and then user B |
| 241 | clones from user A's repository, check-ins to user B's repo do not |
| 242 | check the master repo before allowing the check-in even with |
| @@ -243,28 +244,35 @@ | |
| 244 | master repo that an inadvertent fork can be detected. |
| 245 | <br><br> |
| 246 | Because of this, we recommend that if you're using Fossil in a |
| 247 | distributed way like this, that check-ins be made only to the master |
| 248 | or its immediate child repos, and that those further down the chain |
| 249 | be read-only clones. This is not to say that we repudiate Fossil's |
| 250 | use as a Distributed Version Control System, just that such use is |
| 251 | prone to creating forks, by the nature of distributed development. |
| 252 | We hope we've made it clear in this document why forks on long-lived |
| 253 | shared working branches are a problem.</p></li> |
| 254 | |
| 255 | <li><p>You've automated Fossil (e.g. with a shell script) and |
| 256 | forking is a possibility, so you write <b>fossil commit |
| 257 | --allow-fork</b> commands to prevent Fossil from refusing the |
| 258 | check-in because it would create a fork. It's better to write such |
| 259 | a script to detect this condition and cope with it (e.g. <b>fossil |
| 260 | update</b>) but if the alternative is losing information, you may |
| 261 | feel justified in creating forks that an interactive user must later |
| 262 | clean up with <b>fossil merge</b> commands.</p></li> |
| 263 | </ol> |
| 264 | |
| 265 | That leaves only one case where we can recommend use of "--allow-fork" |
| 266 | by interactive users: when you're working on |
| 267 | a personal branch so that creating a dual-tipped branch isn't going to |
| 268 | cause any other user an inconvenience or risk forking the development. |
| 269 | Only one developer is involved, and the fork may be short-lived, so |
| 270 | there is no risk of inadvertently forking the overall development effort. |
| 271 | This is a good alternative to branching when you just need to |
| 272 | temporarily fork the branch's development. It avoids cluttering the |
| 273 | global branch namespace with short-lived temporary named branches. |
| 274 | |
| 275 | There's a common generalization of that case: you're a solo developer, |
| 276 | so that the problems with branching vs forking simply don't matter. In |
| 277 | that case, feel free to use "--allow-fork" as much as you like. |
| 278 | |
| 279 |