Fossil

Check-in [1e0cf467]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Added the key distinction ("A branch is a named, intentional fork") to www/branching.wiki and added info on actually creating branches.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 1e0cf46762168ab9e311926ebec625952ee383a98057a8c2d1046344dbb3e890
User & Date: wyoung 2019-06-19 17:41:34
Context
2019-06-19
17:58
More expansion on the discussion of creating branches in Fossil, especially in the second-form commands, which were incomplete in the prior version. check-in: 73911668 user: wyoung tags: trunk
17:41
Added the key distinction ("A branch is a named, intentional fork") to www/branching.wiki and added info on actually creating branches. check-in: 1e0cf467 user: wyoung tags: trunk
17:33
Added a generaliation of the prior edit to www/branching.wiki check-in: 3cc437a5 user: wyoung tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to www/branching.wiki.

140
141
142
143
144
145
146
147





148
149
150
151
152
153
154
...
176
177
178
179
180
181
182






















183
184
185
186
187
188
189
is usually undesirable and either avoided entirely,
as in Figure 1, or else quickly resolved as shown in Figure 3.
But sometimes, one does want to have multiple leaves.  For example, a project
might have one leaf that is the latest version of the project under
development and another leaf that is the latest version that has been
tested.
When multiple leaves are desirable, we call this <i>branching</i>
instead of <i>forking</i>.





Figure 4 shows an example of a project where there are two branches, one
for development work and another for testing.

<table border=1 cellpadding=10 hspace=10 vspace=10 align="center">
<tr><td align="center">
<img src="branch04.svg"><br>
Figure 4
................................................................................
the difference?  As far as the internal Fossil data structures 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
approximation, we define forking to be by accident and branching to
be by intent.  Apart from that, they are the same.























<h2 id="forking">Justifications For Forking</h2>

The primary cases where forking is justified are all when it is done purely
in software in order to avoid losing information:

<ol>







|
>
>
>
>
>







 







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
...
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
is usually undesirable and either avoided entirely,
as in Figure 1, or else quickly resolved as shown in Figure 3.
But sometimes, one does want to have multiple leaves.  For example, a project
might have one leaf that is the latest version of the project under
development and another leaf that is the latest version that has been
tested.
When multiple leaves are desirable, we call this <i>branching</i>
instead of <i>forking</i>:

<blockquote>
<b>Key Distinction:</b> A branch is a <i>named, intentional</i> fork.
</blockquote>

Figure 4 shows an example of a project where there are two branches, one
for development work and another for testing.

<table border=1 cellpadding=10 hspace=10 vspace=10 align="center">
<tr><td align="center">
<img src="branch04.svg"><br>
Figure 4
................................................................................
the difference?  As far as the internal Fossil data structures 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
approximation, we define forking to be by accident and branching to
be by intent.  Apart from that, they are the same.

Fossil offers two primary ways to create branches (a.k.a. named,
intentional forks):

<pre>
    $ fossil ci --branch my-new-branch-name
    $ fossil branch new my-new-branch-name trunk
</pre>

The first option is the one we recommend for most cases: it creates a
branch as part of a checkin using the current branch as its basis. 

(Keep in mind that trunk is just another branch in Fossil. It is simply
the default branch name for the first checkin and every checkin made as
one of its direct descendants.)

The second command above is more complicated.  Also, it creates the
branch in advance of actual need, which makes it a violation of the
[https://en.wikipedia.org/wiki/You_aren%27t_gonna_need_it|YAGNI
Principle]. We recommend that you wait until you actually need the
branch and create it using the first command above.


<h2 id="forking">Justifications For Forking</h2>

The primary cases where forking is justified are all when it is done purely
in software in order to avoid losing information:

<ol>