Fossil SCM
Updates to the branching document.
Commit
dc1a5cf739b0b1e83c273d5f68805a5c86d935af
Parent
2e275c14202446f…
1 file changed
+17
-15
+17
-15
| --- www/branching.wiki | ||
| +++ www/branching.wiki | ||
| @@ -5,11 +5,11 @@ | ||
| 5 | 5 | In a simple and perfect world, the development of a project would proceed |
| 6 | 6 | linearly, as shown in figure 1. |
| 7 | 7 | |
| 8 | 8 | <center><table border=1 cellpadding=10 hspace=10 vspace=10> |
| 9 | 9 | <tr><td align="center"> |
| 10 | -<img src="branch01.gif"><br> | |
| 10 | +<img src="branch01.gif" width=280 height=68><br> | |
| 11 | 11 | Figure 1 |
| 12 | 12 | </td></tr></table></center> |
| 13 | 13 | |
| 14 | 14 | Each circle represents a check-in. For the sake of clarity, the check-ins |
| 15 | 15 | are given small consecutive numbers. In a real system, of course, the |
| @@ -27,20 +27,21 @@ | ||
| 27 | 27 | 3 a child of 2. We say that 3 is a <i>descendant</i> of both 1 and 2 and that 1 |
| 28 | 28 | and 2 are both <i>ancestors</i> of 3. |
| 29 | 29 | |
| 30 | 30 | We call the graph of check-ins a <i>tree</i>. Check-in 1 is the <i>root</i> |
| 31 | 31 | since it has no ancestors. Check-in 4 is a <i>leaf</i> of the tree since |
| 32 | -it has no descendants. | |
| 32 | +it has no descendants. (We will give a more precise in the definition of | |
| 33 | +"leaf" later.) | |
| 33 | 34 | |
| 34 | 35 | Alas, reality often interferes with the simple linear development of a |
| 35 | 36 | project. Suppose two programmers make independent modifications to check-in 2. |
| 36 | 37 | After both changes are checked in, we have a check-in graph that looks |
| 37 | 38 | like figure 2: |
| 38 | 39 | |
| 39 | 40 | <center><table border=1 cellpadding=10 hspace=10 vspace=10> |
| 40 | 41 | <tr><td align="center"> |
| 41 | -<img src="branch02.gif"><br> | |
| 42 | +<img src="branch02.gif" width=210 height=140><br> | |
| 42 | 43 | Figure 2 |
| 43 | 44 | </td></tr></table></center> |
| 44 | 45 | |
| 45 | 46 | The graph in figure 2 has two leaves: check-ins 3 and 4. Check-in 2 has |
| 46 | 47 | two children, check-ins 3 and 4. We call this stituation a <i>fork</i>. |
| @@ -57,11 +58,11 @@ | ||
| 57 | 58 | as shown in figure 1. This is how CVS works. This is also how fossil |
| 58 | 59 | works in "autosync" mode. |
| 59 | 60 | |
| 60 | 61 | But it might be that Bob is off-network when he does his commit, so he |
| 61 | 62 | has no way of knowing that Alice has already committed her changes. |
| 62 | -Or, it could be that Bob has turned of "autosync" mode in SQLite. Or, | |
| 63 | +Or, it could be that Bob has turned off "autosync" mode in SQLite. Or, | |
| 63 | 64 | maybe Bob just doesn't want to merge in Alices changes before he has |
| 64 | 65 | saved his own, so he forces the commit to occur using the "--force" option |
| 65 | 66 | to the fossil <b>commit</b> command. For whatever reason, two commits against |
| 66 | 67 | check-in 2 have occurred and now the tree has two leaves. |
| 67 | 68 | |
| @@ -69,17 +70,17 @@ | ||
| 69 | 70 | the most features and the most bug fixes? When there is more than |
| 70 | 71 | one leaf in the graph, you don't really know. So we like to have |
| 71 | 72 | graphs with a single leaf. |
| 72 | 73 | |
| 73 | 74 | To resolve this situation, Alice can use the fossil <b>merge</b> command |
| 74 | -to me merge in Bob's changes in here local copy of check-in 3. Then she | |
| 75 | +to merge in Bob's changes in her local copy of check-in 3. Then she | |
| 75 | 76 | can commit the results as check-in 5. This results in a tree as shown |
| 76 | 77 | in figure 3. |
| 77 | 78 | |
| 78 | 79 | <center><table border=1 cellpadding=10 hspace=10 vspace=10> |
| 79 | 80 | <tr><td align="center"> |
| 80 | -<img src="branch03.gif"><br> | |
| 81 | +<img src="branch03.gif" width=282 height=152><br> | |
| 81 | 82 | Figure 3 |
| 82 | 83 | </td></tr></table></center> |
| 83 | 84 | |
| 84 | 85 | Check-in 5 is a direct child of check-in 3 because it was created by editing |
| 85 | 86 | check-in 3. But check-in 5 also inherits the changes from check-in 4 by |
| @@ -96,18 +97,18 @@ | ||
| 96 | 97 | Hold your hand over the check-in 4 circle of figure 3 and then figure |
| 97 | 98 | 3 looks exactly like figure 1 (except that the leaf has a different check-in |
| 98 | 99 | number, but that is just a notational difference - the two check-ins have |
| 99 | 100 | exactly the same content). In other words, figure 3 is really a superset |
| 100 | 101 | of figure 1. The check-in 4 of figure 3 captures addition state which |
| 101 | -is omitted from figure 1. In check-in 4 of figure 3 is a copy | |
| 102 | -of Bob's local checkout before he merged in Alices changes. That snapshot | |
| 102 | +is omitted from figure 1. Check-in 4 of figure 3 holds a copy | |
| 103 | +of Bob's local checkout before he merged in Alice's changes. That snapshot | |
| 103 | 104 | of Bob's changes independent of Alice's changes is omitted from figure 1. |
| 104 | 105 | Some people say that the approach taken in figure 3 is better because it |
| 105 | 106 | preserves this extra intermediate state. Others say that the approach |
| 106 | 107 | taken in figure 1 is better because it is much easier to visualize a |
| 107 | 108 | linear line of development and because the the merging happens automatically |
| 108 | -instead of as a separate manual step. We will not take sides in this | |
| 109 | +instead of as a separate manual step. We will not take sides in that | |
| 109 | 110 | debate. We will simply point out that fossil enables you to do it either way. |
| 110 | 111 | |
| 111 | 112 | <h2>Forking Versus Branching</h2> |
| 112 | 113 | |
| 113 | 114 | Forking and having more than one leaf in the check-in tree is usually |
| @@ -122,11 +123,11 @@ | ||
| 122 | 123 | Figure 4 shows an example of a project where there are two branches, one |
| 123 | 124 | for development work and another for testing. |
| 124 | 125 | |
| 125 | 126 | <center><table border=1 cellpadding=10 hspace=10 vspace=10> |
| 126 | 127 | <tr><td align="center"> |
| 127 | -<img src="branch04.gif"><br> | |
| 128 | +<img src="branch04.gif" width=426 height=123><br> | |
| 128 | 129 | Figure 4 |
| 129 | 130 | </td></tr></table></center> |
| 130 | 131 | |
| 131 | 132 | The hypothetical scenario of figure 4 is this: The project starts and |
| 132 | 133 | progresses to a point where (at check-in 2) |
| @@ -135,11 +136,12 @@ | ||
| 135 | 136 | check-ins before a project reaches this point, but for simplicity of |
| 136 | 137 | presentation we will say that the project is ready after check-in 2. |
| 137 | 138 | The project then splits into two branches that are used by separate |
| 138 | 139 | teams. The testing team, using the blue branch, finds and fixes a few |
| 139 | 140 | bugs. This is shown by check-ins 6 and 9. Meanwhile the development |
| 140 | -team, working on the red branch, is busy adding features for the second | |
| 141 | +team, working on the top uncolored branch, | |
| 142 | +is busy adding features for the second | |
| 141 | 143 | release. Of course, the development team would like to take advantage of |
| 142 | 144 | the bug fixes implemented by the testing team. So periodically, the |
| 143 | 145 | changes in the test branch are merged into the dev branch. This is |
| 144 | 146 | shown by the dashed merge arrows between check-ins 6 and 7 and between |
| 145 | 147 | check-ins 9 and 10. |
| @@ -149,11 +151,11 @@ | ||
| 149 | 151 | the difference? As far as the internal fossil data structure are |
| 150 | 152 | concerned, there is no difference. The distinction is in the intent. |
| 151 | 153 | In figure 2, the fact that check-in 2 has multiple children is an |
| 152 | 154 | accident that stems from concurrent development. In figure 4, giving |
| 153 | 155 | check-in 2 multiple children is a deliberate act. So, to a good |
| 154 | -approximating, we define forking to be by accident and branching to | |
| 156 | +approximation, we define forking to be by accident and branching to | |
| 155 | 157 | be by intent. Apart from that, they are the same. |
| 156 | 158 | |
| 157 | 159 | <h2>Tags And Properties</h2> |
| 158 | 160 | |
| 159 | 161 | Tags and properties are used in fossil to help express the intent, and |
| @@ -160,11 +162,11 @@ | ||
| 160 | 162 | thus to distinguish between forks and branches. Figure 5 shows the |
| 161 | 163 | same scenario as figure 4 but with tags and properties added: |
| 162 | 164 | |
| 163 | 165 | <center><table border=1 cellpadding=10 hspace=10 vspace=10> |
| 164 | 166 | <tr><td align="center"> |
| 165 | -<img src="branch05.gif"><br> | |
| 167 | +<img src="branch05.gif" width=485 height=177><br> | |
| 166 | 168 | Figure 5 |
| 167 | 169 | </td></tr></table></center> |
| 168 | 170 | |
| 169 | 171 | A <i>tag</i> is a name that is attached to a check-in. A |
| 170 | 172 | <i>property</i> is a name/value pair. Internally, fossil implements |
| @@ -171,11 +173,11 @@ | ||
| 171 | 173 | tags as properties with a NULL value. So, tags and properties really |
| 172 | 174 | are much the same thing, and henceforth we will use the word "tag" |
| 173 | 175 | to mean either a tag or a property. |
| 174 | 176 | |
| 175 | 177 | A tag can be either a one-time tag or an propagating tag or a cancellation. |
| 176 | -A one-time tag only applies to the check-in to which it is attached. An | |
| 178 | +A one-time tag only applies to the check-in to which it is attached. A | |
| 177 | 179 | propagating tag applies to the check-in to which it is attached and also |
| 178 | 180 | to all direct descendants of that check-in. A <i>direct descendant</i> |
| 179 | 181 | is a descendant through direct children. Tags propagation does not |
| 180 | 182 | cross merges. Tag propagation also stops as soon |
| 181 | 183 | as it encounters another check-in with the same tag. A cancellation tag |
| @@ -219,11 +221,11 @@ | ||
| 219 | 221 | Figure 5 also shows two one-time tags on check-in 9. (The diagram does |
| 220 | 222 | not make a graphical distinction between one-time and propagating tags.) |
| 221 | 223 | The <b>sym-release-1.0</b> tag means that check-in 9 can be referred to |
| 222 | 224 | using the more meaningful name "release-1.0". The <b>closed</b> tag means |
| 223 | 225 | that check-in 9 is a "closed leaf". A closed leaf is a leaf that intended |
| 224 | -to never have any childred. | |
| 226 | +to never have any direct children. | |
| 225 | 227 | |
| 226 | 228 | <h2>Review Of Terminology</h2> |
| 227 | 229 | |
| 228 | 230 | Here is a list of definitions of key terms: |
| 229 | 231 | |
| 230 | 232 |
| --- www/branching.wiki | |
| +++ www/branching.wiki | |
| @@ -5,11 +5,11 @@ | |
| 5 | In a simple and perfect world, the development of a project would proceed |
| 6 | linearly, as shown in figure 1. |
| 7 | |
| 8 | <center><table border=1 cellpadding=10 hspace=10 vspace=10> |
| 9 | <tr><td align="center"> |
| 10 | <img src="branch01.gif"><br> |
| 11 | Figure 1 |
| 12 | </td></tr></table></center> |
| 13 | |
| 14 | Each circle represents a check-in. For the sake of clarity, the check-ins |
| 15 | are given small consecutive numbers. In a real system, of course, the |
| @@ -27,20 +27,21 @@ | |
| 27 | 3 a child of 2. We say that 3 is a <i>descendant</i> of both 1 and 2 and that 1 |
| 28 | and 2 are both <i>ancestors</i> of 3. |
| 29 | |
| 30 | We call the graph of check-ins a <i>tree</i>. Check-in 1 is the <i>root</i> |
| 31 | since it has no ancestors. Check-in 4 is a <i>leaf</i> of the tree since |
| 32 | it has no descendants. |
| 33 | |
| 34 | Alas, reality often interferes with the simple linear development of a |
| 35 | project. Suppose two programmers make independent modifications to check-in 2. |
| 36 | After both changes are checked in, we have a check-in graph that looks |
| 37 | like figure 2: |
| 38 | |
| 39 | <center><table border=1 cellpadding=10 hspace=10 vspace=10> |
| 40 | <tr><td align="center"> |
| 41 | <img src="branch02.gif"><br> |
| 42 | Figure 2 |
| 43 | </td></tr></table></center> |
| 44 | |
| 45 | The graph in figure 2 has two leaves: check-ins 3 and 4. Check-in 2 has |
| 46 | two children, check-ins 3 and 4. We call this stituation a <i>fork</i>. |
| @@ -57,11 +58,11 @@ | |
| 57 | as shown in figure 1. This is how CVS works. This is also how fossil |
| 58 | works in "autosync" mode. |
| 59 | |
| 60 | But it might be that Bob is off-network when he does his commit, so he |
| 61 | has no way of knowing that Alice has already committed her changes. |
| 62 | Or, it could be that Bob has turned of "autosync" mode in SQLite. Or, |
| 63 | maybe Bob just doesn't want to merge in Alices changes before he has |
| 64 | saved his own, so he forces the commit to occur using the "--force" option |
| 65 | to the fossil <b>commit</b> command. For whatever reason, two commits against |
| 66 | check-in 2 have occurred and now the tree has two leaves. |
| 67 | |
| @@ -69,17 +70,17 @@ | |
| 69 | the most features and the most bug fixes? When there is more than |
| 70 | one leaf in the graph, you don't really know. So we like to have |
| 71 | graphs with a single leaf. |
| 72 | |
| 73 | To resolve this situation, Alice can use the fossil <b>merge</b> command |
| 74 | to me merge in Bob's changes in here local copy of check-in 3. Then she |
| 75 | can commit the results as check-in 5. This results in a tree as shown |
| 76 | in figure 3. |
| 77 | |
| 78 | <center><table border=1 cellpadding=10 hspace=10 vspace=10> |
| 79 | <tr><td align="center"> |
| 80 | <img src="branch03.gif"><br> |
| 81 | Figure 3 |
| 82 | </td></tr></table></center> |
| 83 | |
| 84 | Check-in 5 is a direct child of check-in 3 because it was created by editing |
| 85 | check-in 3. But check-in 5 also inherits the changes from check-in 4 by |
| @@ -96,18 +97,18 @@ | |
| 96 | Hold your hand over the check-in 4 circle of figure 3 and then figure |
| 97 | 3 looks exactly like figure 1 (except that the leaf has a different check-in |
| 98 | number, but that is just a notational difference - the two check-ins have |
| 99 | exactly the same content). In other words, figure 3 is really a superset |
| 100 | of figure 1. The check-in 4 of figure 3 captures addition state which |
| 101 | is omitted from figure 1. In check-in 4 of figure 3 is a copy |
| 102 | of Bob's local checkout before he merged in Alices changes. That snapshot |
| 103 | of Bob's changes independent of Alice's changes is omitted from figure 1. |
| 104 | Some people say that the approach taken in figure 3 is better because it |
| 105 | preserves this extra intermediate state. Others say that the approach |
| 106 | taken in figure 1 is better because it is much easier to visualize a |
| 107 | linear line of development and because the the merging happens automatically |
| 108 | instead of as a separate manual step. We will not take sides in this |
| 109 | debate. We will simply point out that fossil enables you to do it either way. |
| 110 | |
| 111 | <h2>Forking Versus Branching</h2> |
| 112 | |
| 113 | Forking and having more than one leaf in the check-in tree is usually |
| @@ -122,11 +123,11 @@ | |
| 122 | Figure 4 shows an example of a project where there are two branches, one |
| 123 | for development work and another for testing. |
| 124 | |
| 125 | <center><table border=1 cellpadding=10 hspace=10 vspace=10> |
| 126 | <tr><td align="center"> |
| 127 | <img src="branch04.gif"><br> |
| 128 | Figure 4 |
| 129 | </td></tr></table></center> |
| 130 | |
| 131 | The hypothetical scenario of figure 4 is this: The project starts and |
| 132 | progresses to a point where (at check-in 2) |
| @@ -135,11 +136,12 @@ | |
| 135 | check-ins before a project reaches this point, but for simplicity of |
| 136 | presentation we will say that the project is ready after check-in 2. |
| 137 | The project then splits into two branches that are used by separate |
| 138 | teams. The testing team, using the blue branch, finds and fixes a few |
| 139 | bugs. This is shown by check-ins 6 and 9. Meanwhile the development |
| 140 | team, working on the red branch, is busy adding features for the second |
| 141 | release. Of course, the development team would like to take advantage of |
| 142 | the bug fixes implemented by the testing team. So periodically, the |
| 143 | changes in the test branch are merged into the dev branch. This is |
| 144 | shown by the dashed merge arrows between check-ins 6 and 7 and between |
| 145 | check-ins 9 and 10. |
| @@ -149,11 +151,11 @@ | |
| 149 | the difference? As far as the internal fossil data structure are |
| 150 | concerned, there is no difference. The distinction is in the intent. |
| 151 | In figure 2, the fact that check-in 2 has multiple children is an |
| 152 | accident that stems from concurrent development. In figure 4, giving |
| 153 | check-in 2 multiple children is a deliberate act. So, to a good |
| 154 | approximating, we define forking to be by accident and branching to |
| 155 | be by intent. Apart from that, they are the same. |
| 156 | |
| 157 | <h2>Tags And Properties</h2> |
| 158 | |
| 159 | Tags and properties are used in fossil to help express the intent, and |
| @@ -160,11 +162,11 @@ | |
| 160 | thus to distinguish between forks and branches. Figure 5 shows the |
| 161 | same scenario as figure 4 but with tags and properties added: |
| 162 | |
| 163 | <center><table border=1 cellpadding=10 hspace=10 vspace=10> |
| 164 | <tr><td align="center"> |
| 165 | <img src="branch05.gif"><br> |
| 166 | Figure 5 |
| 167 | </td></tr></table></center> |
| 168 | |
| 169 | A <i>tag</i> is a name that is attached to a check-in. A |
| 170 | <i>property</i> is a name/value pair. Internally, fossil implements |
| @@ -171,11 +173,11 @@ | |
| 171 | tags as properties with a NULL value. So, tags and properties really |
| 172 | are much the same thing, and henceforth we will use the word "tag" |
| 173 | to mean either a tag or a property. |
| 174 | |
| 175 | A tag can be either a one-time tag or an propagating tag or a cancellation. |
| 176 | A one-time tag only applies to the check-in to which it is attached. An |
| 177 | propagating tag applies to the check-in to which it is attached and also |
| 178 | to all direct descendants of that check-in. A <i>direct descendant</i> |
| 179 | is a descendant through direct children. Tags propagation does not |
| 180 | cross merges. Tag propagation also stops as soon |
| 181 | as it encounters another check-in with the same tag. A cancellation tag |
| @@ -219,11 +221,11 @@ | |
| 219 | Figure 5 also shows two one-time tags on check-in 9. (The diagram does |
| 220 | not make a graphical distinction between one-time and propagating tags.) |
| 221 | The <b>sym-release-1.0</b> tag means that check-in 9 can be referred to |
| 222 | using the more meaningful name "release-1.0". The <b>closed</b> tag means |
| 223 | that check-in 9 is a "closed leaf". A closed leaf is a leaf that intended |
| 224 | to never have any childred. |
| 225 | |
| 226 | <h2>Review Of Terminology</h2> |
| 227 | |
| 228 | Here is a list of definitions of key terms: |
| 229 | |
| 230 |
| --- www/branching.wiki | |
| +++ www/branching.wiki | |
| @@ -5,11 +5,11 @@ | |
| 5 | In a simple and perfect world, the development of a project would proceed |
| 6 | linearly, as shown in figure 1. |
| 7 | |
| 8 | <center><table border=1 cellpadding=10 hspace=10 vspace=10> |
| 9 | <tr><td align="center"> |
| 10 | <img src="branch01.gif" width=280 height=68><br> |
| 11 | Figure 1 |
| 12 | </td></tr></table></center> |
| 13 | |
| 14 | Each circle represents a check-in. For the sake of clarity, the check-ins |
| 15 | are given small consecutive numbers. In a real system, of course, the |
| @@ -27,20 +27,21 @@ | |
| 27 | 3 a child of 2. We say that 3 is a <i>descendant</i> of both 1 and 2 and that 1 |
| 28 | and 2 are both <i>ancestors</i> of 3. |
| 29 | |
| 30 | We call the graph of check-ins a <i>tree</i>. Check-in 1 is the <i>root</i> |
| 31 | since it has no ancestors. Check-in 4 is a <i>leaf</i> of the tree since |
| 32 | it has no descendants. (We will give a more precise in the definition of |
| 33 | "leaf" later.) |
| 34 | |
| 35 | Alas, reality often interferes with the simple linear development of a |
| 36 | project. Suppose two programmers make independent modifications to check-in 2. |
| 37 | After both changes are checked in, we have a check-in graph that looks |
| 38 | like figure 2: |
| 39 | |
| 40 | <center><table border=1 cellpadding=10 hspace=10 vspace=10> |
| 41 | <tr><td align="center"> |
| 42 | <img src="branch02.gif" width=210 height=140><br> |
| 43 | Figure 2 |
| 44 | </td></tr></table></center> |
| 45 | |
| 46 | The graph in figure 2 has two leaves: check-ins 3 and 4. Check-in 2 has |
| 47 | two children, check-ins 3 and 4. We call this stituation a <i>fork</i>. |
| @@ -57,11 +58,11 @@ | |
| 58 | as shown in figure 1. This is how CVS works. This is also how fossil |
| 59 | works in "autosync" mode. |
| 60 | |
| 61 | But it might be that Bob is off-network when he does his commit, so he |
| 62 | has no way of knowing that Alice has already committed her changes. |
| 63 | Or, it could be that Bob has turned off "autosync" mode in SQLite. Or, |
| 64 | maybe Bob just doesn't want to merge in Alices changes before he has |
| 65 | saved his own, so he forces the commit to occur using the "--force" option |
| 66 | to the fossil <b>commit</b> command. For whatever reason, two commits against |
| 67 | check-in 2 have occurred and now the tree has two leaves. |
| 68 | |
| @@ -69,17 +70,17 @@ | |
| 70 | the most features and the most bug fixes? When there is more than |
| 71 | one leaf in the graph, you don't really know. So we like to have |
| 72 | graphs with a single leaf. |
| 73 | |
| 74 | To resolve this situation, Alice can use the fossil <b>merge</b> command |
| 75 | to merge in Bob's changes in her local copy of check-in 3. Then she |
| 76 | can commit the results as check-in 5. This results in a tree as shown |
| 77 | in figure 3. |
| 78 | |
| 79 | <center><table border=1 cellpadding=10 hspace=10 vspace=10> |
| 80 | <tr><td align="center"> |
| 81 | <img src="branch03.gif" width=282 height=152><br> |
| 82 | Figure 3 |
| 83 | </td></tr></table></center> |
| 84 | |
| 85 | Check-in 5 is a direct child of check-in 3 because it was created by editing |
| 86 | check-in 3. But check-in 5 also inherits the changes from check-in 4 by |
| @@ -96,18 +97,18 @@ | |
| 97 | Hold your hand over the check-in 4 circle of figure 3 and then figure |
| 98 | 3 looks exactly like figure 1 (except that the leaf has a different check-in |
| 99 | number, but that is just a notational difference - the two check-ins have |
| 100 | exactly the same content). In other words, figure 3 is really a superset |
| 101 | of figure 1. The check-in 4 of figure 3 captures addition state which |
| 102 | is omitted from figure 1. Check-in 4 of figure 3 holds a copy |
| 103 | of Bob's local checkout before he merged in Alice's changes. That snapshot |
| 104 | of Bob's changes independent of Alice's changes is omitted from figure 1. |
| 105 | Some people say that the approach taken in figure 3 is better because it |
| 106 | preserves this extra intermediate state. Others say that the approach |
| 107 | taken in figure 1 is better because it is much easier to visualize a |
| 108 | linear line of development and because the the merging happens automatically |
| 109 | instead of as a separate manual step. We will not take sides in that |
| 110 | debate. We will simply point out that fossil enables you to do it either way. |
| 111 | |
| 112 | <h2>Forking Versus Branching</h2> |
| 113 | |
| 114 | Forking and having more than one leaf in the check-in tree is usually |
| @@ -122,11 +123,11 @@ | |
| 123 | Figure 4 shows an example of a project where there are two branches, one |
| 124 | for development work and another for testing. |
| 125 | |
| 126 | <center><table border=1 cellpadding=10 hspace=10 vspace=10> |
| 127 | <tr><td align="center"> |
| 128 | <img src="branch04.gif" width=426 height=123><br> |
| 129 | Figure 4 |
| 130 | </td></tr></table></center> |
| 131 | |
| 132 | The hypothetical scenario of figure 4 is this: The project starts and |
| 133 | progresses to a point where (at check-in 2) |
| @@ -135,11 +136,12 @@ | |
| 136 | check-ins before a project reaches this point, but for simplicity of |
| 137 | presentation we will say that the project is ready after check-in 2. |
| 138 | The project then splits into two branches that are used by separate |
| 139 | teams. The testing team, using the blue branch, finds and fixes a few |
| 140 | bugs. This is shown by check-ins 6 and 9. Meanwhile the development |
| 141 | team, working on the top uncolored branch, |
| 142 | is busy adding features for the second |
| 143 | release. Of course, the development team would like to take advantage of |
| 144 | the bug fixes implemented by the testing team. So periodically, the |
| 145 | changes in the test branch are merged into the dev branch. This is |
| 146 | shown by the dashed merge arrows between check-ins 6 and 7 and between |
| 147 | check-ins 9 and 10. |
| @@ -149,11 +151,11 @@ | |
| 151 | the difference? As far as the internal fossil data structure are |
| 152 | concerned, there is no difference. The distinction is in the intent. |
| 153 | In figure 2, the fact that check-in 2 has multiple children is an |
| 154 | accident that stems from concurrent development. In figure 4, giving |
| 155 | check-in 2 multiple children is a deliberate act. So, to a good |
| 156 | approximation, we define forking to be by accident and branching to |
| 157 | be by intent. Apart from that, they are the same. |
| 158 | |
| 159 | <h2>Tags And Properties</h2> |
| 160 | |
| 161 | Tags and properties are used in fossil to help express the intent, and |
| @@ -160,11 +162,11 @@ | |
| 162 | thus to distinguish between forks and branches. Figure 5 shows the |
| 163 | same scenario as figure 4 but with tags and properties added: |
| 164 | |
| 165 | <center><table border=1 cellpadding=10 hspace=10 vspace=10> |
| 166 | <tr><td align="center"> |
| 167 | <img src="branch05.gif" width=485 height=177><br> |
| 168 | Figure 5 |
| 169 | </td></tr></table></center> |
| 170 | |
| 171 | A <i>tag</i> is a name that is attached to a check-in. A |
| 172 | <i>property</i> is a name/value pair. Internally, fossil implements |
| @@ -171,11 +173,11 @@ | |
| 173 | tags as properties with a NULL value. So, tags and properties really |
| 174 | are much the same thing, and henceforth we will use the word "tag" |
| 175 | to mean either a tag or a property. |
| 176 | |
| 177 | A tag can be either a one-time tag or an propagating tag or a cancellation. |
| 178 | A one-time tag only applies to the check-in to which it is attached. A |
| 179 | propagating tag applies to the check-in to which it is attached and also |
| 180 | to all direct descendants of that check-in. A <i>direct descendant</i> |
| 181 | is a descendant through direct children. Tags propagation does not |
| 182 | cross merges. Tag propagation also stops as soon |
| 183 | as it encounters another check-in with the same tag. A cancellation tag |
| @@ -219,11 +221,11 @@ | |
| 221 | Figure 5 also shows two one-time tags on check-in 9. (The diagram does |
| 222 | not make a graphical distinction between one-time and propagating tags.) |
| 223 | The <b>sym-release-1.0</b> tag means that check-in 9 can be referred to |
| 224 | using the more meaningful name "release-1.0". The <b>closed</b> tag means |
| 225 | that check-in 9 is a "closed leaf". A closed leaf is a leaf that intended |
| 226 | to never have any direct children. |
| 227 | |
| 228 | <h2>Review Of Terminology</h2> |
| 229 | |
| 230 | Here is a list of definitions of key terms: |
| 231 | |
| 232 |