Fossil SCM
Added the key distinction ("A branch is a named, intentional fork") to www/branching.wiki and added info on actually creating branches.
Commit
1e0cf46762168ab9e311926ebec625952ee383a98057a8c2d1046344dbb3e890
Parent
3cc437a50ffe8c6…
1 file changed
+28
-1
+28
-1
| --- www/branching.wiki | ||
| +++ www/branching.wiki | ||
| @@ -142,11 +142,16 @@ | ||
| 142 | 142 | But sometimes, one does want to have multiple leaves. For example, a project |
| 143 | 143 | might have one leaf that is the latest version of the project under |
| 144 | 144 | development and another leaf that is the latest version that has been |
| 145 | 145 | tested. |
| 146 | 146 | When multiple leaves are desirable, we call this <i>branching</i> |
| 147 | -instead of <i>forking</i>. | |
| 147 | +instead of <i>forking</i>: | |
| 148 | + | |
| 149 | +<blockquote> | |
| 150 | +<b>Key Distinction:</b> A branch is a <i>named, intentional</i> fork. | |
| 151 | +</blockquote> | |
| 152 | + | |
| 148 | 153 | Figure 4 shows an example of a project where there are two branches, one |
| 149 | 154 | for development work and another for testing. |
| 150 | 155 | |
| 151 | 156 | <table border=1 cellpadding=10 hspace=10 vspace=10 align="center"> |
| 152 | 157 | <tr><td align="center"> |
| @@ -178,10 +183,32 @@ | ||
| 178 | 183 | In Figure 2, the fact that check-in 2 has multiple children is an |
| 179 | 184 | accident that stems from concurrent development. In Figure 4, giving |
| 180 | 185 | check-in 2 multiple children is a deliberate act. So, to a good |
| 181 | 186 | approximation, we define forking to be by accident and branching to |
| 182 | 187 | be by intent. Apart from that, they are the same. |
| 188 | + | |
| 189 | +Fossil offers two primary ways to create branches (a.k.a. named, | |
| 190 | +intentional forks): | |
| 191 | + | |
| 192 | +<pre> | |
| 193 | + $ fossil ci --branch my-new-branch-name | |
| 194 | + $ fossil branch new my-new-branch-name trunk | |
| 195 | +</pre> | |
| 196 | + | |
| 197 | +The first option is the one we recommend for most cases: it creates a | |
| 198 | +branch as part of a checkin using the current branch as its basis. | |
| 199 | + | |
| 200 | +(Keep in mind that trunk is just another branch in Fossil. It is simply | |
| 201 | +the default branch name for the first checkin and every checkin made as | |
| 202 | +one of its direct descendants.) | |
| 203 | + | |
| 204 | +The second command above is more complicated. Also, it creates the | |
| 205 | +branch in advance of actual need, which makes it a violation of the | |
| 206 | +[https://en.wikipedia.org/wiki/You_aren%27t_gonna_need_it|YAGNI | |
| 207 | +Principle]. We recommend that you wait until you actually need the | |
| 208 | +branch and create it using the first command above. | |
| 209 | + | |
| 183 | 210 | |
| 184 | 211 | <h2 id="forking">Justifications For Forking</h2> |
| 185 | 212 | |
| 186 | 213 | The primary cases where forking is justified are all when it is done purely |
| 187 | 214 | in software in order to avoid losing information: |
| 188 | 215 |
| --- www/branching.wiki | |
| +++ www/branching.wiki | |
| @@ -142,11 +142,16 @@ | |
| 142 | But sometimes, one does want to have multiple leaves. For example, a project |
| 143 | might have one leaf that is the latest version of the project under |
| 144 | development and another leaf that is the latest version that has been |
| 145 | tested. |
| 146 | When multiple leaves are desirable, we call this <i>branching</i> |
| 147 | instead of <i>forking</i>. |
| 148 | Figure 4 shows an example of a project where there are two branches, one |
| 149 | for development work and another for testing. |
| 150 | |
| 151 | <table border=1 cellpadding=10 hspace=10 vspace=10 align="center"> |
| 152 | <tr><td align="center"> |
| @@ -178,10 +183,32 @@ | |
| 178 | In Figure 2, the fact that check-in 2 has multiple children is an |
| 179 | accident that stems from concurrent development. In Figure 4, giving |
| 180 | check-in 2 multiple children is a deliberate act. So, to a good |
| 181 | approximation, we define forking to be by accident and branching to |
| 182 | be by intent. Apart from that, they are the same. |
| 183 | |
| 184 | <h2 id="forking">Justifications For Forking</h2> |
| 185 | |
| 186 | The primary cases where forking is justified are all when it is done purely |
| 187 | in software in order to avoid losing information: |
| 188 |
| --- www/branching.wiki | |
| +++ www/branching.wiki | |
| @@ -142,11 +142,16 @@ | |
| 142 | But sometimes, one does want to have multiple leaves. For example, a project |
| 143 | might have one leaf that is the latest version of the project under |
| 144 | development and another leaf that is the latest version that has been |
| 145 | tested. |
| 146 | When multiple leaves are desirable, we call this <i>branching</i> |
| 147 | instead of <i>forking</i>: |
| 148 | |
| 149 | <blockquote> |
| 150 | <b>Key Distinction:</b> A branch is a <i>named, intentional</i> fork. |
| 151 | </blockquote> |
| 152 | |
| 153 | Figure 4 shows an example of a project where there are two branches, one |
| 154 | for development work and another for testing. |
| 155 | |
| 156 | <table border=1 cellpadding=10 hspace=10 vspace=10 align="center"> |
| 157 | <tr><td align="center"> |
| @@ -178,10 +183,32 @@ | |
| 183 | In Figure 2, the fact that check-in 2 has multiple children is an |
| 184 | accident that stems from concurrent development. In Figure 4, giving |
| 185 | check-in 2 multiple children is a deliberate act. So, to a good |
| 186 | approximation, we define forking to be by accident and branching to |
| 187 | be by intent. Apart from that, they are the same. |
| 188 | |
| 189 | Fossil offers two primary ways to create branches (a.k.a. named, |
| 190 | intentional forks): |
| 191 | |
| 192 | <pre> |
| 193 | $ fossil ci --branch my-new-branch-name |
| 194 | $ fossil branch new my-new-branch-name trunk |
| 195 | </pre> |
| 196 | |
| 197 | The first option is the one we recommend for most cases: it creates a |
| 198 | branch as part of a checkin using the current branch as its basis. |
| 199 | |
| 200 | (Keep in mind that trunk is just another branch in Fossil. It is simply |
| 201 | the default branch name for the first checkin and every checkin made as |
| 202 | one of its direct descendants.) |
| 203 | |
| 204 | The second command above is more complicated. Also, it creates the |
| 205 | branch in advance of actual need, which makes it a violation of the |
| 206 | [https://en.wikipedia.org/wiki/You_aren%27t_gonna_need_it|YAGNI |
| 207 | Principle]. We recommend that you wait until you actually need the |
| 208 | branch and create it using the first command above. |
| 209 | |
| 210 | |
| 211 | <h2 id="forking">Justifications For Forking</h2> |
| 212 | |
| 213 | The primary cases where forking is justified are all when it is done purely |
| 214 | in software in order to avoid losing information: |
| 215 |