Fossil SCM
c/--force/--allow-fork/. Since fossil 1.29, not every repository has an initial commit and the initial commit no longer needs to be empty. Change the wording to account for that.
Commit
aafcf6c57b982e188fa0b8bb5623b19123bb32fa
Parent
45f5184e2a9734a…
1 file changed
+26
-27
+26
-27
| --- www/branching.wiki | ||
| +++ www/branching.wiki | ||
| @@ -19,19 +19,19 @@ | ||
| 19 | 19 | |
| 20 | 20 | The arrows in figure 1 show the evolution of a project. The initial |
| 21 | 21 | check-in is 1. Check-in 2 is derived from 1. In other words, check-in 2 |
| 22 | 22 | was created by making edits to check-in 1 and then committing those edits. |
| 23 | 23 | We say that 2 is a <i>child</i> of 1 |
| 24 | -and that 1 is a <i>parent</i> of 2. | |
| 24 | +and that 1 is a <i>parent</i> of 2. | |
| 25 | 25 | Check-in 3 is derived from check-in 2, making |
| 26 | 26 | 3 a child of 2. We say that 3 is a <i>descendant</i> of both 1 and 2 and that 1 |
| 27 | -and 2 are both <i>ancestors</i> of 3. | |
| 27 | +and 2 are both <i>ancestors</i> of 3. | |
| 28 | 28 | |
| 29 | 29 | <a name="dag"></a> |
| 30 | 30 | <h2>DAGs</h2> |
| 31 | 31 | |
| 32 | -The graph of check-ins is a | |
| 32 | +The graph of check-ins is a | |
| 33 | 33 | [http://en.wikipedia.org/wiki/Directed_acyclic_graph | directed acyclic graph] |
| 34 | 34 | commonly shortened to <i>DAG</i>. Check-in 1 is the <i>root</i> of the DAG |
| 35 | 35 | since it has no ancestors. Check-in 4 is a <i>leaf</i> of the DAG since |
| 36 | 36 | it has no descendants. (We will give a more precise definition later of |
| 37 | 37 | "leaf.") |
| @@ -47,21 +47,21 @@ | ||
| 47 | 47 | </td></tr></table></center> |
| 48 | 48 | |
| 49 | 49 | The graph in figure 2 has two leaves: check-ins 3 and 4. Check-in 2 has |
| 50 | 50 | two children, check-ins 3 and 4. We call this state a <i>fork</i>. |
| 51 | 51 | |
| 52 | -Fossil tries to prevent forks. Suppose two programmers named Alice and | |
| 53 | -Bob are each editing check-in 2 separately. Alice finishes her edits | |
| 54 | -first and commits her changes, resulting in check-in 3. Later, when Bob | |
| 55 | -attempts to commit his changes, fossil verifies that check-in 2 is still | |
| 56 | -a leaf. Fossil sees that check-in 3 has occurred and aborts Bob's commit | |
| 57 | -attempt with a message "would fork." This allows Bob to do a "fossil | |
| 58 | -update" which pulls in Alice's changes, merging them into his own | |
| 59 | -changes. After merging, Bob commits check-in 4 as a child of check-in 3. | |
| 60 | -The result is a linear graph as shown in figure 1. This is how CVS | |
| 61 | -works. This is also how fossil works in [./concepts.wiki#workflow | | |
| 62 | -"autosync"] mode. | |
| 52 | +Fossil tries to prevent forks. Suppose two programmers named Alice and | |
| 53 | +Bob are each editing check-in 2 separately. Alice finishes her edits | |
| 54 | +first and commits her changes, resulting in check-in 3. Later, when Bob | |
| 55 | +attempts to commit his changes, fossil verifies that check-in 2 is still | |
| 56 | +a leaf. Fossil sees that check-in 3 has occurred and aborts Bob's commit | |
| 57 | +attempt with a message "would fork." This allows Bob to do a "fossil | |
| 58 | +update" which pulls in Alice's changes, merging them into his own | |
| 59 | +changes. After merging, Bob commits check-in 4 as a child of check-in 3. | |
| 60 | +The result is a linear graph as shown in figure 1. This is how CVS | |
| 61 | +works. This is also how fossil works in [./concepts.wiki#workflow | | |
| 62 | +"autosync"] mode. | |
| 63 | 63 | |
| 64 | 64 | But perhaps Bob is off-network when he does his commit, so he |
| 65 | 65 | has no way of knowing that Alice has already committed her changes. |
| 66 | 66 | Or, it could be that Bob has turned off "autosync" mode in Fossil. Or, |
| 67 | 67 | maybe Bob just doesn't want to merge in Alice's changes before he has |
| @@ -86,11 +86,11 @@ | ||
| 86 | 86 | </td></tr></table></center> |
| 87 | 87 | |
| 88 | 88 | Check-in 5 is a child of check-in 3 because it was created by editing |
| 89 | 89 | check-in 3. But check-in 5 also inherits the changes from check-in 4 by |
| 90 | 90 | virtue of the merge. So we say that check-in 5 is a <i>merge child</i> |
| 91 | -of check-in 4 and that it is a <i>direct child</i> of check-in 3. | |
| 91 | +of check-in 4 and that it is a <i>direct child</i> of check-in 3. | |
| 92 | 92 | The graph is now back to a single leaf (check-in 5). |
| 93 | 93 | |
| 94 | 94 | We have already seen that if fossil is in autosync mode then Bob would |
| 95 | 95 | have been warned about the potential fork the first time he tried to |
| 96 | 96 | commit check-in 4. If Bob had updated his local check-out to merge in |
| @@ -112,11 +112,11 @@ | ||
| 112 | 112 | instead of as a separate manual step. We will not take sides in that |
| 113 | 113 | debate. We will simply point out that fossil enables you to do it either way. |
| 114 | 114 | |
| 115 | 115 | <h2>Forking Versus Branching</h2> |
| 116 | 116 | |
| 117 | -Having more than one leaf in the check-in DAG is called a "fork." This | |
| 117 | +Having more than one leaf in the check-in DAG is called a "fork." This | |
| 118 | 118 | is usually undesirable and either avoided entirely, |
| 119 | 119 | as in figure 1, or else quickly resolved as shown in figure 3. |
| 120 | 120 | But sometimes, one does want to have multiple leaves. For example, a project |
| 121 | 121 | might have one leaf that is the latest version of the project under |
| 122 | 122 | development and another leaf that is the latest version that has been |
| @@ -131,19 +131,19 @@ | ||
| 131 | 131 | <img src="branch04.gif" width=426 height=123><br> |
| 132 | 132 | Figure 4 |
| 133 | 133 | </td></tr></table></center> |
| 134 | 134 | |
| 135 | 135 | The hypothetical scenario of figure 4 is this: The project starts and |
| 136 | -progresses to a point where (at check-in 2) | |
| 136 | +progresses to a point where (at check-in 2) | |
| 137 | 137 | it is ready to enter testing for its first release. |
| 138 | 138 | In a real project, of course, there might be hundreds or thousands of |
| 139 | 139 | check-ins before a project reaches this point, but for simplicity of |
| 140 | 140 | presentation we will say that the project is ready after check-in 2. |
| 141 | 141 | The project then splits into two branches that are used by separate |
| 142 | 142 | teams. The testing team, using the blue branch, finds and fixes a few |
| 143 | 143 | bugs. This is shown by check-ins 6 and 9. Meanwhile the development |
| 144 | -team, working on the top uncolored branch, | |
| 144 | +team, working on the top uncolored branch, | |
| 145 | 145 | is busy adding features for the second |
| 146 | 146 | release. Of course, the development team would like to take advantage of |
| 147 | 147 | the bug fixes implemented by the testing team. So periodically, the |
| 148 | 148 | changes in the test branch are merged into the dev branch. This is |
| 149 | 149 | shown by the dashed merge arrows between check-ins 6 and 7 and between |
| @@ -174,13 +174,13 @@ | ||
| 174 | 174 | |
| 175 | 175 | A <i>tag</i> is a name that is attached to a check-in. A |
| 176 | 176 | <i>property</i> is a name/value pair. Internally, fossil implements |
| 177 | 177 | tags as properties with a NULL value. So, tags and properties really |
| 178 | 178 | are much the same thing, and henceforth we will use the word "tag" |
| 179 | -to mean either a tag or a property. | |
| 179 | +to mean either a tag or a property. | |
| 180 | 180 | |
| 181 | -A tag can be a one-time tag, a propagating tag or a cancellation tag. | |
| 181 | +A tag can be a one-time tag, a propagating tag or a cancellation tag. | |
| 182 | 182 | A one-time tag only applies to the check-in to which it is attached. A |
| 183 | 183 | propagating tag applies to the check-in to which it is attached and also |
| 184 | 184 | to all direct descendants of that check-in. A <i>direct descendant</i> |
| 185 | 185 | is a descendant through direct children. Tags propagation does not |
| 186 | 186 | cross merges. Tag propagation also stops as soon |
| @@ -187,14 +187,13 @@ | ||
| 187 | 187 | as it encounters another check-in with the same tag. A cancellation tag |
| 188 | 188 | is attached to a single check-in in order to either override a one-time |
| 189 | 189 | tag that was previously placed on that same check-in, or to block |
| 190 | 190 | tag propagation from an ancestor. |
| 191 | 191 | |
| 192 | -Every repository is created with a single empty check-in that has two | |
| 193 | -propagating tags. In figure 5, that initial empty check-in is check-in 1. | |
| 194 | -The <b>branch</b> tag tells (by its value) | |
| 195 | -what branch the check-in is a member of. | |
| 192 | +The initial checkin of every repository has two propagating tags. In | |
| 193 | +figure 5, that initial check-in is check-in 1. The <b>branch</b> tag | |
| 194 | +tells (by its value) what branch the check-in is a member of. | |
| 196 | 195 | The default branch is called "trunk." All tags that begin with "<b>sym-</b>" |
| 197 | 196 | are symbolic name tags. When a symbolic name tag is attached to a |
| 198 | 197 | check-in, that allows you to refer to that check-in by its symbolic |
| 199 | 198 | name rather than by its 40-character SHA1 hash name. When a symbolic name |
| 200 | 199 | tag propagates (as does the <b>sym-trunk</b> tag) then referring to that |
| @@ -212,12 +211,12 @@ | ||
| 212 | 211 | |
| 213 | 212 | Check-in 4 also has a <b>sym-test</b> tag, which gives the symbolic name |
| 214 | 213 | "test" to check-ins 4, 6, and 9. Because tags do not propagate across |
| 215 | 214 | merges, check-ins 7, 8, and 10 do not inherit the <b>sym-test</b> tag and |
| 216 | 215 | are hence not known by the name "test." |
| 217 | -To prevent the <b>sym-trunk</b> tag from propagating from check-in 1 | |
| 218 | -into check-ins 4, 6, and 9, there is a cancellation tag for | |
| 216 | +To prevent the <b>sym-trunk</b> tag from propagating from check-in 1 | |
| 217 | +into check-ins 4, 6, and 9, there is a cancellation tag for | |
| 219 | 218 | <b>sym-trunk</b> on check-in 4. The net effect is that |
| 220 | 219 | check-ins on the trunk go by the symbolic name of "trunk" and check-ins |
| 221 | 220 | on the test branch go by the symbolic name "test." |
| 222 | 221 | |
| 223 | 222 | The <b>bgcolor=blue</b> tag on check-in 4 causes the background color |
| @@ -225,11 +224,11 @@ | ||
| 225 | 224 | |
| 226 | 225 | Figure 5 also shows two one-time tags on check-in 9. (The diagram does |
| 227 | 226 | not make a graphical distinction between one-time and propagating tags.) |
| 228 | 227 | The <b>sym-release-1.0</b> tag means that check-in 9 can be referred to |
| 229 | 228 | using the more meaningful name "release-1.0." The <b>closed</b> tag means |
| 230 | -that check-in 9 is a "closed leaf." A closed leaf is a leaf that should | |
| 229 | +that check-in 9 is a "closed leaf." A closed leaf is a leaf that should | |
| 231 | 230 | never have direct children. |
| 232 | 231 | |
| 233 | 232 | <h2>Review Of Terminology</h2> |
| 234 | 233 | |
| 235 | 234 | <blockquote><dl> |
| 236 | 235 |
| --- www/branching.wiki | |
| +++ www/branching.wiki | |
| @@ -19,19 +19,19 @@ | |
| 19 | |
| 20 | The arrows in figure 1 show the evolution of a project. The initial |
| 21 | check-in is 1. Check-in 2 is derived from 1. In other words, check-in 2 |
| 22 | was created by making edits to check-in 1 and then committing those edits. |
| 23 | We say that 2 is a <i>child</i> of 1 |
| 24 | and that 1 is a <i>parent</i> of 2. |
| 25 | Check-in 3 is derived from check-in 2, making |
| 26 | 3 a child of 2. We say that 3 is a <i>descendant</i> of both 1 and 2 and that 1 |
| 27 | and 2 are both <i>ancestors</i> of 3. |
| 28 | |
| 29 | <a name="dag"></a> |
| 30 | <h2>DAGs</h2> |
| 31 | |
| 32 | The graph of check-ins is a |
| 33 | [http://en.wikipedia.org/wiki/Directed_acyclic_graph | directed acyclic graph] |
| 34 | commonly shortened to <i>DAG</i>. Check-in 1 is the <i>root</i> of the DAG |
| 35 | since it has no ancestors. Check-in 4 is a <i>leaf</i> of the DAG since |
| 36 | it has no descendants. (We will give a more precise definition later of |
| 37 | "leaf.") |
| @@ -47,21 +47,21 @@ | |
| 47 | </td></tr></table></center> |
| 48 | |
| 49 | The graph in figure 2 has two leaves: check-ins 3 and 4. Check-in 2 has |
| 50 | two children, check-ins 3 and 4. We call this state a <i>fork</i>. |
| 51 | |
| 52 | Fossil tries to prevent forks. Suppose two programmers named Alice and |
| 53 | Bob are each editing check-in 2 separately. Alice finishes her edits |
| 54 | first and commits her changes, resulting in check-in 3. Later, when Bob |
| 55 | attempts to commit his changes, fossil verifies that check-in 2 is still |
| 56 | a leaf. Fossil sees that check-in 3 has occurred and aborts Bob's commit |
| 57 | attempt with a message "would fork." This allows Bob to do a "fossil |
| 58 | update" which pulls in Alice's changes, merging them into his own |
| 59 | changes. After merging, Bob commits check-in 4 as a child of check-in 3. |
| 60 | The result is a linear graph as shown in figure 1. This is how CVS |
| 61 | works. This is also how fossil works in [./concepts.wiki#workflow | |
| 62 | "autosync"] mode. |
| 63 | |
| 64 | But perhaps Bob is off-network when he does his commit, so he |
| 65 | has no way of knowing that Alice has already committed her changes. |
| 66 | Or, it could be that Bob has turned off "autosync" mode in Fossil. Or, |
| 67 | maybe Bob just doesn't want to merge in Alice's changes before he has |
| @@ -86,11 +86,11 @@ | |
| 86 | </td></tr></table></center> |
| 87 | |
| 88 | Check-in 5 is a child of check-in 3 because it was created by editing |
| 89 | check-in 3. But check-in 5 also inherits the changes from check-in 4 by |
| 90 | virtue of the merge. So we say that check-in 5 is a <i>merge child</i> |
| 91 | of check-in 4 and that it is a <i>direct child</i> of check-in 3. |
| 92 | The graph is now back to a single leaf (check-in 5). |
| 93 | |
| 94 | We have already seen that if fossil is in autosync mode then Bob would |
| 95 | have been warned about the potential fork the first time he tried to |
| 96 | commit check-in 4. If Bob had updated his local check-out to merge in |
| @@ -112,11 +112,11 @@ | |
| 112 | instead of as a separate manual step. We will not take sides in that |
| 113 | debate. We will simply point out that fossil enables you to do it either way. |
| 114 | |
| 115 | <h2>Forking Versus Branching</h2> |
| 116 | |
| 117 | Having more than one leaf in the check-in DAG is called a "fork." This |
| 118 | is usually undesirable and either avoided entirely, |
| 119 | as in figure 1, or else quickly resolved as shown in figure 3. |
| 120 | But sometimes, one does want to have multiple leaves. For example, a project |
| 121 | might have one leaf that is the latest version of the project under |
| 122 | development and another leaf that is the latest version that has been |
| @@ -131,19 +131,19 @@ | |
| 131 | <img src="branch04.gif" width=426 height=123><br> |
| 132 | Figure 4 |
| 133 | </td></tr></table></center> |
| 134 | |
| 135 | The hypothetical scenario of figure 4 is this: The project starts and |
| 136 | progresses to a point where (at check-in 2) |
| 137 | it is ready to enter testing for its first release. |
| 138 | In a real project, of course, there might be hundreds or thousands of |
| 139 | check-ins before a project reaches this point, but for simplicity of |
| 140 | presentation we will say that the project is ready after check-in 2. |
| 141 | The project then splits into two branches that are used by separate |
| 142 | teams. The testing team, using the blue branch, finds and fixes a few |
| 143 | bugs. This is shown by check-ins 6 and 9. Meanwhile the development |
| 144 | team, working on the top uncolored branch, |
| 145 | is busy adding features for the second |
| 146 | release. Of course, the development team would like to take advantage of |
| 147 | the bug fixes implemented by the testing team. So periodically, the |
| 148 | changes in the test branch are merged into the dev branch. This is |
| 149 | shown by the dashed merge arrows between check-ins 6 and 7 and between |
| @@ -174,13 +174,13 @@ | |
| 174 | |
| 175 | A <i>tag</i> is a name that is attached to a check-in. A |
| 176 | <i>property</i> is a name/value pair. Internally, fossil implements |
| 177 | tags as properties with a NULL value. So, tags and properties really |
| 178 | are much the same thing, and henceforth we will use the word "tag" |
| 179 | to mean either a tag or a property. |
| 180 | |
| 181 | A tag can be a one-time tag, a propagating tag or a cancellation tag. |
| 182 | A one-time tag only applies to the check-in to which it is attached. A |
| 183 | propagating tag applies to the check-in to which it is attached and also |
| 184 | to all direct descendants of that check-in. A <i>direct descendant</i> |
| 185 | is a descendant through direct children. Tags propagation does not |
| 186 | cross merges. Tag propagation also stops as soon |
| @@ -187,14 +187,13 @@ | |
| 187 | as it encounters another check-in with the same tag. A cancellation tag |
| 188 | is attached to a single check-in in order to either override a one-time |
| 189 | tag that was previously placed on that same check-in, or to block |
| 190 | tag propagation from an ancestor. |
| 191 | |
| 192 | Every repository is created with a single empty check-in that has two |
| 193 | propagating tags. In figure 5, that initial empty check-in is check-in 1. |
| 194 | The <b>branch</b> tag tells (by its value) |
| 195 | what branch the check-in is a member of. |
| 196 | The default branch is called "trunk." All tags that begin with "<b>sym-</b>" |
| 197 | are symbolic name tags. When a symbolic name tag is attached to a |
| 198 | check-in, that allows you to refer to that check-in by its symbolic |
| 199 | name rather than by its 40-character SHA1 hash name. When a symbolic name |
| 200 | tag propagates (as does the <b>sym-trunk</b> tag) then referring to that |
| @@ -212,12 +211,12 @@ | |
| 212 | |
| 213 | Check-in 4 also has a <b>sym-test</b> tag, which gives the symbolic name |
| 214 | "test" to check-ins 4, 6, and 9. Because tags do not propagate across |
| 215 | merges, check-ins 7, 8, and 10 do not inherit the <b>sym-test</b> tag and |
| 216 | are hence not known by the name "test." |
| 217 | To prevent the <b>sym-trunk</b> tag from propagating from check-in 1 |
| 218 | into check-ins 4, 6, and 9, there is a cancellation tag for |
| 219 | <b>sym-trunk</b> on check-in 4. The net effect is that |
| 220 | check-ins on the trunk go by the symbolic name of "trunk" and check-ins |
| 221 | on the test branch go by the symbolic name "test." |
| 222 | |
| 223 | The <b>bgcolor=blue</b> tag on check-in 4 causes the background color |
| @@ -225,11 +224,11 @@ | |
| 225 | |
| 226 | Figure 5 also shows two one-time tags on check-in 9. (The diagram does |
| 227 | not make a graphical distinction between one-time and propagating tags.) |
| 228 | The <b>sym-release-1.0</b> tag means that check-in 9 can be referred to |
| 229 | using the more meaningful name "release-1.0." The <b>closed</b> tag means |
| 230 | that check-in 9 is a "closed leaf." A closed leaf is a leaf that should |
| 231 | never have direct children. |
| 232 | |
| 233 | <h2>Review Of Terminology</h2> |
| 234 | |
| 235 | <blockquote><dl> |
| 236 |
| --- www/branching.wiki | |
| +++ www/branching.wiki | |
| @@ -19,19 +19,19 @@ | |
| 19 | |
| 20 | The arrows in figure 1 show the evolution of a project. The initial |
| 21 | check-in is 1. Check-in 2 is derived from 1. In other words, check-in 2 |
| 22 | was created by making edits to check-in 1 and then committing those edits. |
| 23 | We say that 2 is a <i>child</i> of 1 |
| 24 | and that 1 is a <i>parent</i> of 2. |
| 25 | Check-in 3 is derived from check-in 2, making |
| 26 | 3 a child of 2. We say that 3 is a <i>descendant</i> of both 1 and 2 and that 1 |
| 27 | and 2 are both <i>ancestors</i> of 3. |
| 28 | |
| 29 | <a name="dag"></a> |
| 30 | <h2>DAGs</h2> |
| 31 | |
| 32 | The graph of check-ins is a |
| 33 | [http://en.wikipedia.org/wiki/Directed_acyclic_graph | directed acyclic graph] |
| 34 | commonly shortened to <i>DAG</i>. Check-in 1 is the <i>root</i> of the DAG |
| 35 | since it has no ancestors. Check-in 4 is a <i>leaf</i> of the DAG since |
| 36 | it has no descendants. (We will give a more precise definition later of |
| 37 | "leaf.") |
| @@ -47,21 +47,21 @@ | |
| 47 | </td></tr></table></center> |
| 48 | |
| 49 | The graph in figure 2 has two leaves: check-ins 3 and 4. Check-in 2 has |
| 50 | two children, check-ins 3 and 4. We call this state a <i>fork</i>. |
| 51 | |
| 52 | Fossil tries to prevent forks. Suppose two programmers named Alice and |
| 53 | Bob are each editing check-in 2 separately. Alice finishes her edits |
| 54 | first and commits her changes, resulting in check-in 3. Later, when Bob |
| 55 | attempts to commit his changes, fossil verifies that check-in 2 is still |
| 56 | a leaf. Fossil sees that check-in 3 has occurred and aborts Bob's commit |
| 57 | attempt with a message "would fork." This allows Bob to do a "fossil |
| 58 | update" which pulls in Alice's changes, merging them into his own |
| 59 | changes. After merging, Bob commits check-in 4 as a child of check-in 3. |
| 60 | The result is a linear graph as shown in figure 1. This is how CVS |
| 61 | works. This is also how fossil works in [./concepts.wiki#workflow | |
| 62 | "autosync"] mode. |
| 63 | |
| 64 | But perhaps Bob is off-network when he does his commit, so he |
| 65 | has no way of knowing that Alice has already committed her changes. |
| 66 | Or, it could be that Bob has turned off "autosync" mode in Fossil. Or, |
| 67 | maybe Bob just doesn't want to merge in Alice's changes before he has |
| @@ -86,11 +86,11 @@ | |
| 86 | </td></tr></table></center> |
| 87 | |
| 88 | Check-in 5 is a child of check-in 3 because it was created by editing |
| 89 | check-in 3. But check-in 5 also inherits the changes from check-in 4 by |
| 90 | virtue of the merge. So we say that check-in 5 is a <i>merge child</i> |
| 91 | of check-in 4 and that it is a <i>direct child</i> of check-in 3. |
| 92 | The graph is now back to a single leaf (check-in 5). |
| 93 | |
| 94 | We have already seen that if fossil is in autosync mode then Bob would |
| 95 | have been warned about the potential fork the first time he tried to |
| 96 | commit check-in 4. If Bob had updated his local check-out to merge in |
| @@ -112,11 +112,11 @@ | |
| 112 | instead of as a separate manual step. We will not take sides in that |
| 113 | debate. We will simply point out that fossil enables you to do it either way. |
| 114 | |
| 115 | <h2>Forking Versus Branching</h2> |
| 116 | |
| 117 | Having more than one leaf in the check-in DAG is called a "fork." This |
| 118 | is usually undesirable and either avoided entirely, |
| 119 | as in figure 1, or else quickly resolved as shown in figure 3. |
| 120 | But sometimes, one does want to have multiple leaves. For example, a project |
| 121 | might have one leaf that is the latest version of the project under |
| 122 | development and another leaf that is the latest version that has been |
| @@ -131,19 +131,19 @@ | |
| 131 | <img src="branch04.gif" width=426 height=123><br> |
| 132 | Figure 4 |
| 133 | </td></tr></table></center> |
| 134 | |
| 135 | The hypothetical scenario of figure 4 is this: The project starts and |
| 136 | progresses to a point where (at check-in 2) |
| 137 | it is ready to enter testing for its first release. |
| 138 | In a real project, of course, there might be hundreds or thousands of |
| 139 | check-ins before a project reaches this point, but for simplicity of |
| 140 | presentation we will say that the project is ready after check-in 2. |
| 141 | The project then splits into two branches that are used by separate |
| 142 | teams. The testing team, using the blue branch, finds and fixes a few |
| 143 | bugs. This is shown by check-ins 6 and 9. Meanwhile the development |
| 144 | team, working on the top uncolored branch, |
| 145 | is busy adding features for the second |
| 146 | release. Of course, the development team would like to take advantage of |
| 147 | the bug fixes implemented by the testing team. So periodically, the |
| 148 | changes in the test branch are merged into the dev branch. This is |
| 149 | shown by the dashed merge arrows between check-ins 6 and 7 and between |
| @@ -174,13 +174,13 @@ | |
| 174 | |
| 175 | A <i>tag</i> is a name that is attached to a check-in. A |
| 176 | <i>property</i> is a name/value pair. Internally, fossil implements |
| 177 | tags as properties with a NULL value. So, tags and properties really |
| 178 | are much the same thing, and henceforth we will use the word "tag" |
| 179 | to mean either a tag or a property. |
| 180 | |
| 181 | A tag can be a one-time tag, a propagating tag or a cancellation tag. |
| 182 | A one-time tag only applies to the check-in to which it is attached. A |
| 183 | propagating tag applies to the check-in to which it is attached and also |
| 184 | to all direct descendants of that check-in. A <i>direct descendant</i> |
| 185 | is a descendant through direct children. Tags propagation does not |
| 186 | cross merges. Tag propagation also stops as soon |
| @@ -187,14 +187,13 @@ | |
| 187 | as it encounters another check-in with the same tag. A cancellation tag |
| 188 | is attached to a single check-in in order to either override a one-time |
| 189 | tag that was previously placed on that same check-in, or to block |
| 190 | tag propagation from an ancestor. |
| 191 | |
| 192 | The initial checkin of every repository has two propagating tags. In |
| 193 | figure 5, that initial check-in is check-in 1. The <b>branch</b> tag |
| 194 | tells (by its value) what branch the check-in is a member of. |
| 195 | The default branch is called "trunk." All tags that begin with "<b>sym-</b>" |
| 196 | are symbolic name tags. When a symbolic name tag is attached to a |
| 197 | check-in, that allows you to refer to that check-in by its symbolic |
| 198 | name rather than by its 40-character SHA1 hash name. When a symbolic name |
| 199 | tag propagates (as does the <b>sym-trunk</b> tag) then referring to that |
| @@ -212,12 +211,12 @@ | |
| 211 | |
| 212 | Check-in 4 also has a <b>sym-test</b> tag, which gives the symbolic name |
| 213 | "test" to check-ins 4, 6, and 9. Because tags do not propagate across |
| 214 | merges, check-ins 7, 8, and 10 do not inherit the <b>sym-test</b> tag and |
| 215 | are hence not known by the name "test." |
| 216 | To prevent the <b>sym-trunk</b> tag from propagating from check-in 1 |
| 217 | into check-ins 4, 6, and 9, there is a cancellation tag for |
| 218 | <b>sym-trunk</b> on check-in 4. The net effect is that |
| 219 | check-ins on the trunk go by the symbolic name of "trunk" and check-ins |
| 220 | on the test branch go by the symbolic name "test." |
| 221 | |
| 222 | The <b>bgcolor=blue</b> tag on check-in 4 causes the background color |
| @@ -225,11 +224,11 @@ | |
| 224 | |
| 225 | Figure 5 also shows two one-time tags on check-in 9. (The diagram does |
| 226 | not make a graphical distinction between one-time and propagating tags.) |
| 227 | The <b>sym-release-1.0</b> tag means that check-in 9 can be referred to |
| 228 | using the more meaningful name "release-1.0." The <b>closed</b> tag means |
| 229 | that check-in 9 is a "closed leaf." A closed leaf is a leaf that should |
| 230 | never have direct children. |
| 231 | |
| 232 | <h2>Review Of Terminology</h2> |
| 233 | |
| 234 | <blockquote><dl> |
| 235 |