Fossil SCM
Added new section, "The Authors' Voice" to www/branching.wiki. Other assorted improvements as well.
Commit
2da109981a198bf89b00218f510dc6942c98142fef2e00b1188425880e9c57bd
Parent
cbca374c37eb1a5…
1 file changed
+27
-8
+27
-8
| --- www/branching.wiki | ||
| +++ www/branching.wiki | ||
| @@ -186,35 +186,40 @@ | ||
| 186 | 186 | accident that stems from concurrent development. In Figure 4, giving |
| 187 | 187 | check-in 2 multiple children is a deliberate act. So, to a good |
| 188 | 188 | approximation, we define forking to be by accident and branching to |
| 189 | 189 | be by intent. Apart from that, they are the same. |
| 190 | 190 | |
| 191 | -Fossil offers two primary ways to create named, intentional forks | |
| 191 | +Fossil offers two primary ways to create named, intentional forks, | |
| 192 | 192 | a.k.a. branches. First: |
| 193 | 193 | |
| 194 | 194 | <pre> |
| 195 | 195 | $ fossil commit --branch my-new-branch-name |
| 196 | 196 | </pre> |
| 197 | 197 | |
| 198 | 198 | This is the method we recommend for most cases: it creates a branch as |
| 199 | -part of a checkin using the current branch as its basis. After the | |
| 199 | +part of a checkin using the version in the current checkout directory | |
| 200 | +as its basis. (This is normally the tip of the current branch, though | |
| 201 | +it doesn't have to be. You can create a branch from an ancestor checkin | |
| 202 | +on a branch as well.) After making this branch-creating | |
| 200 | 203 | checkin, your local working directory is switched to that branch, so |
| 201 | 204 | that further checkins occur on that branch as well, as children of the |
| 202 | -last checkin on that branch. | |
| 205 | +tip checkin on that branch. | |
| 203 | 206 | |
| 204 | 207 | The second, more complicated option is: |
| 205 | 208 | |
| 206 | 209 | <pre> |
| 207 | 210 | $ fossil branch new my-new-branch-name trunk |
| 208 | 211 | $ fossil update my-new-branch-name |
| 209 | 212 | $ fossil commit |
| 210 | 213 | </pre> |
| 211 | 214 | |
| 212 | -Not only is the first command longer, you must give the second command | |
| 215 | +Not only is this three commands instead of one, the first of which is | |
| 216 | +longer than the entire simpler command above, you must give the second command | |
| 213 | 217 | before creating any checkins, because until you do, your local working |
| 214 | 218 | directory remains on the same branch it was on at the time you issued |
| 215 | -the command. | |
| 219 | +the command, so that the commit would otherwise put the new material on | |
| 220 | +the original branch instead of the new one. | |
| 216 | 221 | |
| 217 | 222 | In addition to those problems, the second method is a violation of the |
| 218 | 223 | [https://en.wikipedia.org/wiki/You_aren%27t_gonna_need_it|YAGNI |
| 219 | 224 | Principle]. We recommend that you wait until you actually need the |
| 220 | 225 | branch and create it using the first command above. |
| @@ -238,13 +243,14 @@ | ||
| 238 | 243 | of the commit, Fossil has no way of knowing that it is creating a |
| 239 | 244 | fork until the two repositories are later sync'd.</p></li> |
| 240 | 245 | |
| 241 | 246 | <li><p>By Fossil when the cloning hierarchy is more than 2 levels |
| 242 | 247 | deep. If your master repository is cloned by user A and then user B |
| 243 | - clones from user A's repository, check-ins to user B's repo do not | |
| 244 | - check the master repo before allowing the check-in even with | |
| 245 | - autosync enabled. It isn't until user A syncs her repo with the | |
| 248 | + clones from user A's repository, a check-in by user B will cause | |
| 249 | + that repo to attempt an autosync with user A's repo before allowing | |
| 250 | + the checkin, but it will <i>not</i> check with the master repo as | |
| 251 | + well. It isn't until user A syncs her repo with the | |
| 246 | 252 | master repo that an inadvertent fork can be detected. |
| 247 | 253 | <br><br> |
| 248 | 254 | Because of this, we recommend that if you're using Fossil in a |
| 249 | 255 | distributed way like this, that check-ins be made only to the master |
| 250 | 256 | or its immediate child repos, and that those further down the chain |
| @@ -430,6 +436,19 @@ | ||
| 430 | 436 | arbitration logic, so that only the branch with the newest checkin gets |
| 431 | 437 | the branch name in the export. |
| 432 | 438 | |
| 433 | 439 | All of the above is true of tags in general, not just branches. |
| 434 | 440 | |
| 441 | +<h2 id="voice">The Authors' Voice</h2> | |
| 435 | 442 | |
| 443 | +Above, "we" refers to | |
| 444 | +[/blame?udc=1&w=on&checkin=trunk&filename=www%2Fbranching.wiki|the | |
| 445 | +historical authors of this file]. It is our collective voice and | |
| 446 | +opinions above. As in all walks of life, this is not the only possible | |
| 447 | +philosophy, but it is our duty and pleasure in this document to present | |
| 448 | +our philosophy to you. You are of course free to adopt or reject as much | |
| 449 | +of it as you like. Fossil supports many styles, not just those this | |
| 450 | +document's authors prefer. This should go without saying, but we get | |
| 451 | +push-back from people who apparently believe all documents on all web | |
| 452 | +pages should either support their beliefs, or they are factually wrong. | |
| 453 | +Someone is [https://www.xkcd.com/386/|always wrong on the Internet], | |
| 454 | +somewhere. Please don't hold that against us. | |
| 436 | 455 |
| --- www/branching.wiki | |
| +++ www/branching.wiki | |
| @@ -186,35 +186,40 @@ | |
| 186 | accident that stems from concurrent development. In Figure 4, giving |
| 187 | check-in 2 multiple children is a deliberate act. So, to a good |
| 188 | approximation, we define forking to be by accident and branching to |
| 189 | be by intent. Apart from that, they are the same. |
| 190 | |
| 191 | Fossil offers two primary ways to create named, intentional forks |
| 192 | a.k.a. branches. First: |
| 193 | |
| 194 | <pre> |
| 195 | $ fossil commit --branch my-new-branch-name |
| 196 | </pre> |
| 197 | |
| 198 | This is the method we recommend for most cases: it creates a branch as |
| 199 | part of a checkin using the current branch as its basis. After the |
| 200 | checkin, your local working directory is switched to that branch, so |
| 201 | that further checkins occur on that branch as well, as children of the |
| 202 | last checkin on that branch. |
| 203 | |
| 204 | The second, more complicated option is: |
| 205 | |
| 206 | <pre> |
| 207 | $ fossil branch new my-new-branch-name trunk |
| 208 | $ fossil update my-new-branch-name |
| 209 | $ fossil commit |
| 210 | </pre> |
| 211 | |
| 212 | Not only is the first command longer, you must give the second command |
| 213 | before creating any checkins, because until you do, your local working |
| 214 | directory remains on the same branch it was on at the time you issued |
| 215 | the command. |
| 216 | |
| 217 | In addition to those problems, the second method is a violation of the |
| 218 | [https://en.wikipedia.org/wiki/You_aren%27t_gonna_need_it|YAGNI |
| 219 | Principle]. We recommend that you wait until you actually need the |
| 220 | branch and create it using the first command above. |
| @@ -238,13 +243,14 @@ | |
| 238 | of the commit, Fossil has no way of knowing that it is creating a |
| 239 | fork until the two repositories are later sync'd.</p></li> |
| 240 | |
| 241 | <li><p>By Fossil when the cloning hierarchy is more than 2 levels |
| 242 | deep. If your master repository is cloned by user A and then user B |
| 243 | clones from user A's repository, check-ins to user B's repo do not |
| 244 | check the master repo before allowing the check-in even with |
| 245 | autosync enabled. It isn't until user A syncs her repo with the |
| 246 | master repo that an inadvertent fork can be detected. |
| 247 | <br><br> |
| 248 | Because of this, we recommend that if you're using Fossil in a |
| 249 | distributed way like this, that check-ins be made only to the master |
| 250 | or its immediate child repos, and that those further down the chain |
| @@ -430,6 +436,19 @@ | |
| 430 | arbitration logic, so that only the branch with the newest checkin gets |
| 431 | the branch name in the export. |
| 432 | |
| 433 | All of the above is true of tags in general, not just branches. |
| 434 | |
| 435 | |
| 436 |
| --- www/branching.wiki | |
| +++ www/branching.wiki | |
| @@ -186,35 +186,40 @@ | |
| 186 | accident that stems from concurrent development. In Figure 4, giving |
| 187 | check-in 2 multiple children is a deliberate act. So, to a good |
| 188 | approximation, we define forking to be by accident and branching to |
| 189 | be by intent. Apart from that, they are the same. |
| 190 | |
| 191 | Fossil offers two primary ways to create named, intentional forks, |
| 192 | a.k.a. branches. First: |
| 193 | |
| 194 | <pre> |
| 195 | $ fossil commit --branch my-new-branch-name |
| 196 | </pre> |
| 197 | |
| 198 | This is the method we recommend for most cases: it creates a branch as |
| 199 | part of a checkin using the version in the current checkout directory |
| 200 | as its basis. (This is normally the tip of the current branch, though |
| 201 | it doesn't have to be. You can create a branch from an ancestor checkin |
| 202 | on a branch as well.) After making this branch-creating |
| 203 | checkin, your local working directory is switched to that branch, so |
| 204 | that further checkins occur on that branch as well, as children of the |
| 205 | tip checkin on that branch. |
| 206 | |
| 207 | The second, more complicated option is: |
| 208 | |
| 209 | <pre> |
| 210 | $ fossil branch new my-new-branch-name trunk |
| 211 | $ fossil update my-new-branch-name |
| 212 | $ fossil commit |
| 213 | </pre> |
| 214 | |
| 215 | Not only is this three commands instead of one, the first of which is |
| 216 | longer than the entire simpler command above, you must give the second command |
| 217 | before creating any checkins, because until you do, your local working |
| 218 | directory remains on the same branch it was on at the time you issued |
| 219 | the command, so that the commit would otherwise put the new material on |
| 220 | the original branch instead of the new one. |
| 221 | |
| 222 | In addition to those problems, the second method is a violation of the |
| 223 | [https://en.wikipedia.org/wiki/You_aren%27t_gonna_need_it|YAGNI |
| 224 | Principle]. We recommend that you wait until you actually need the |
| 225 | branch and create it using the first command above. |
| @@ -238,13 +243,14 @@ | |
| 243 | of the commit, Fossil has no way of knowing that it is creating a |
| 244 | fork until the two repositories are later sync'd.</p></li> |
| 245 | |
| 246 | <li><p>By Fossil when the cloning hierarchy is more than 2 levels |
| 247 | deep. If your master repository is cloned by user A and then user B |
| 248 | clones from user A's repository, a check-in by user B will cause |
| 249 | that repo to attempt an autosync with user A's repo before allowing |
| 250 | the checkin, but it will <i>not</i> check with the master repo as |
| 251 | well. It isn't until user A syncs her repo with the |
| 252 | master repo that an inadvertent fork can be detected. |
| 253 | <br><br> |
| 254 | Because of this, we recommend that if you're using Fossil in a |
| 255 | distributed way like this, that check-ins be made only to the master |
| 256 | or its immediate child repos, and that those further down the chain |
| @@ -430,6 +436,19 @@ | |
| 436 | arbitration logic, so that only the branch with the newest checkin gets |
| 437 | the branch name in the export. |
| 438 | |
| 439 | All of the above is true of tags in general, not just branches. |
| 440 | |
| 441 | <h2 id="voice">The Authors' Voice</h2> |
| 442 | |
| 443 | Above, "we" refers to |
| 444 | [/blame?udc=1&w=on&checkin=trunk&filename=www%2Fbranching.wiki|the |
| 445 | historical authors of this file]. It is our collective voice and |
| 446 | opinions above. As in all walks of life, this is not the only possible |
| 447 | philosophy, but it is our duty and pleasure in this document to present |
| 448 | our philosophy to you. You are of course free to adopt or reject as much |
| 449 | of it as you like. Fossil supports many styles, not just those this |
| 450 | document's authors prefer. This should go without saying, but we get |
| 451 | push-back from people who apparently believe all documents on all web |
| 452 | pages should either support their beliefs, or they are factually wrong. |
| 453 | Someone is [https://www.xkcd.com/386/|always wrong on the Internet], |
| 454 | somewhere. Please don't hold that against us. |
| 455 |