SHA1 Hash:	dc1a5cf739b0b1e83c273d5f68805a5c86d935af
Date:	2009-01-23 22:05:37
User:	drh
Comment:	Updates to the branching document.
Timelines:	ancestors | descendants | both | trunk
Other Links:	files | ZIP archive | manifest

• branch=trunk inherited from [a28c83647d]
• sym-trunk inherited from [a28c83647d]

Modified www/branching.wiki from [55dd24e8cf] to [867e5fd1b3].

@@ -5,11 +5,11 @@
 In a simple and perfect world, the development of a project would proceed
 linearly, as shown in figure 1.
 
 <center><table border=1 cellpadding=10 hspace=10 vspace=10>
 <tr><td align="center">
-<img src="branch01.gif"><br>
+<img src="branch01.gif" width=280 height=68><br>
 Figure 1
 </td></tr></table></center>
 
 Each circle represents a check-in.  For the sake of clarity, the check-ins
 are given small consecutive numbers.  In a real system, of course, the
@@ -27,20 +27,21 @@
 3 a child of 2.  We say that 3 is a <i>descendant</i> of both 1 and 2 and that 1
 and 2 are both <i>ancestors</i> of 3.
 
 We call the graph of check-ins a <i>tree</i>.  Check-in 1 is the <i>root</i>
 since it has no ancestors.  Check-in 4 is a <i>leaf</i> of the tree since
-it has no descendants.
+it has no descendants.  (We will give a more precise in the definition of
+"leaf" later.)
 
 Alas, reality often interferes with the simple linear development of a
 project.  Suppose two programmers make independent modifications to check-in 2.
 After both changes are checked in, we have a check-in graph that looks
 like figure 2:
 
 <center><table border=1 cellpadding=10 hspace=10 vspace=10>
 <tr><td align="center">
-<img src="branch02.gif"><br>
+<img src="branch02.gif" width=210 height=140><br>
 Figure 2
 </td></tr></table></center>
 
 The graph in figure 2 has two leaves: check-ins 3 and 4.  Check-in 2 has
 two children, check-ins 3 and 4.  We call this stituation a <i>fork</i>.
@@ -57,11 +58,11 @@
 as shown in figure 1.  This is how CVS works.  This is also how fossil
 works in "autosync" mode.
 
 But it might be that Bob is off-network when he does his commit, so he
 has no way of knowing that Alice has already committed her changes.
-Or, it could be that Bob has turned of "autosync" mode in SQLite.  Or,
+Or, it could be that Bob has turned off "autosync" mode in SQLite.  Or,
 maybe Bob just doesn't want to merge in Alices changes before he has
 saved his own, so he forces the commit to occur using the "--force" option
 to the fossil <b>commit</b> command.  For whatever reason, two commits against
 check-in 2 have occurred and now the tree has two leaves.
 
@@ -69,17 +70,17 @@
 the most features and the most bug fixes?  When there is more than
 one leaf in the graph, you don't really know.  So we like to have
 graphs with a single leaf.
 
 To resolve this situation, Alice can use the fossil <b>merge</b> command
-to me merge in Bob's changes in here local copy of check-in 3.  Then she
+to merge in Bob's changes in her local copy of check-in 3.  Then she
 can commit the results as check-in 5.  This results in a tree as shown
 in figure 3.
 
 <center><table border=1 cellpadding=10 hspace=10 vspace=10>
 <tr><td align="center">
-<img src="branch03.gif"><br>
+<img src="branch03.gif" width=282 height=152><br>
 Figure 3
 </td></tr></table></center>
 
 Check-in 5 is a direct child of check-in 3 because it was created by editing
 check-in 3.  But check-in 5 also inherits the changes from check-in 4 by
@@ -96,18 +97,18 @@
 Hold your hand over the check-in 4 circle of figure 3 and then figure
 3 looks exactly like figure 1 (except that the leaf has a different check-in
 number, but that is just a notational difference - the two check-ins have
 exactly the same content).  In other words, figure 3 is really a superset
 of figure 1.  The check-in 4 of figure 3 captures addition state which
-is omitted from figure 1.  In check-in 4 of figure 3 is a copy
-of Bob's local checkout before he merged in Alices changes.  That snapshot
+is omitted from figure 1.  Check-in 4 of figure 3 holds a copy
+of Bob's local checkout before he merged in Alice's changes.  That snapshot
 of Bob's changes independent of Alice's changes is omitted from figure 1.
 Some people say that the approach taken in figure 3 is better because it
 preserves this extra intermediate state.  Others say that the approach
 taken in figure 1 is better because it is much easier to visualize a
 linear line of development and because the the merging happens automatically
-instead of as a separate manual step.  We will not take sides in this
+instead of as a separate manual step.  We will not take sides in that
 debate.  We will simply point out that fossil enables you to do it either way.
 
 <h2>Forking Versus Branching</h2>
 
 Forking and having more than one leaf in the check-in tree is usually
@@ -122,11 +123,11 @@
 Figure 4 shows an example of a project where there are two branches, one
 for development work and another for testing.
 
 <center><table border=1 cellpadding=10 hspace=10 vspace=10>
 <tr><td align="center">
-<img src="branch04.gif"><br>
+<img src="branch04.gif" width=426 height=123><br>
 Figure 4
 </td></tr></table></center>
 
 The hypothetical scenario of figure 4 is this:  The project starts and
 progresses to a point where (at check-in 2)
@@ -135,11 +136,12 @@
 check-ins before a project reaches this point, but for simplicity of
 presentation we will say that the project is ready after check-in 2.
 The project then splits into two branches that are used by separate
 teams.  The testing team, using the blue branch, finds and fixes a few
 bugs.  This is shown by check-ins 6 and 9.  Meanwhile the development
-team, working on the red branch, is busy adding features for the second
+team, working on the top uncolored branch,
+is busy adding features for the second
 release.  Of course, the development team would like to take advantage of
 the bug fixes implemented by the testing team.  So periodically, the
 changes in the test branch are merged into the dev branch.  This is
 shown by the dashed merge arrows between check-ins 6 and 7 and between
 check-ins 9 and 10.
@@ -149,11 +151,11 @@
 the difference?  As far as the internal fossil data structure are
 concerned, there is no difference.  The distinction is in the intent.
 In figure 2, the fact that check-in 2 has multiple children is an
 accident that stems from concurrent development.  In figure 4, giving
 check-in 2 multiple children is a deliberate act.  So, to a good
-approximating, we define forking to be by accident and branching to
+approximation, we define forking to be by accident and branching to
 be by intent.  Apart from that, they are the same.
 
 <h2>Tags And Properties</h2>
 
 Tags and properties are used in fossil to help express the intent, and
@@ -160,11 +162,11 @@
 thus to distinguish between forks and branches.  Figure 5 shows the
 same scenario as figure 4 but with tags and properties added:
 
 <center><table border=1 cellpadding=10 hspace=10 vspace=10>
 <tr><td align="center">
-<img src="branch05.gif"><br>
+<img src="branch05.gif" width=485 height=177><br>
 Figure 5
 </td></tr></table></center>
 
 A <i>tag</i> is a name that is attached to a check-in.  A
 <i>property</i> is a name/value pair.  Internally, fossil implements
@@ -171,11 +173,11 @@
 tags as properties with a NULL value.  So, tags and properties really
 are much the same thing, and henceforth we will use the word "tag"
 to mean either a tag or a property.
 
 A tag can be either a one-time tag or an propagating tag or a cancellation.
-A one-time tag only applies to the check-in to which it is attached.  An
+A one-time tag only applies to the check-in to which it is attached.  A
 propagating tag applies to the check-in to which it is attached and also
 to all direct descendants of that check-in.  A <i>direct descendant</i>
 is a descendant through direct children.  Tags propagation does not
 cross merges.  Tag propagation also stops as soon
 as it encounters another check-in with the same tag.  A cancellation tag
@@ -219,11 +221,11 @@
 Figure 5 also shows two one-time tags on check-in 9.  (The diagram does
 not make a graphical distinction between one-time and propagating tags.)
 The <b>sym-release-1.0</b> tag means that check-in 9 can be referred to
 using the more meaningful name "release-1.0".  The <b>closed</b> tag means
 that check-in 9 is a "closed leaf".  A closed leaf is a leaf that intended
-to never have any childred.
+to never have any direct children.
 
 <h2>Review Of Terminology</h2>
 
 Here is a list of definitions of key terms: