Fossil

Check-in [2686bad1]
Login

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

Overview
Comment:Added the section "Fixing Forks" to www/branching.wiki, and added an explanatory paragraph about the intentionality of forking.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 2686bad19a267fc0ddcefe0a5fdc718865aaf56427babc83c1f91fd9f78561f7
User & Date: wyoung 2019-06-20 11:10:13
Context
2019-06-20
11:30
Markdownism fix in a Wiki-formatted doc check-in: cbca374c user: wyoung tags: trunk
11:10
Added the section "Fixing Forks" to www/branching.wiki, and added an explanatory paragraph about the intentionality of forking. check-in: 2686bad1 user: wyoung tags: trunk
2019-06-19
18:45
Added a new section, "Branch Names Need Not Be Unique" to www/branching.wiki. check-in: 42bfe936 user: wyoung tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to www/branching.wiki.

85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
...
145
146
147
148
149
150
151


152
153
154
155
156
157
158
...
272
273
274
275
276
277
278














279
280
281
282
283
284
285
Fossil also uses a forked branch's leaf check-in timestamps when
checking out that branch: it gives you the fork with the latest
check-in, which in turn selects which parent your next check-in will be
a child of.  This situation means development on that branch can fork
into two independent lines of development, based solely on which branch
tip is newer at the time the next user starts his work on it.  Because
of this, we strongly recommend that you do not intentionally create
forks on branches with "--allow-fork" if that branch is used by many
people over a long period of time. (Prime example: trunk.)

Let us return to Figure 2. To resolve such situations before they can
become a real problem, Alice can use the <b>fossil merge</b> command to
merge Bob's changes into her local copy of check-in 3.  Then she can
commit the results as check-in 5.  This results in a DAG as shown in
Figure 3.

................................................................................
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>
................................................................................
temporarily fork the branch's development. It avoids cluttering the
global branch namespace with short-lived temporary named branches.

There's a common generalization of that case: you're a solo developer,
so that the problems with branching vs forking simply don't matter. In
that case, feel free to use "--allow-fork" as much as you like.
















<h2 id="tags">Tags And Properties</h2>

Tags and properties are used in Fossil to help express the intent, and
thus to distinguish between forks and branches.  Figure 5 shows the
same scenario as Figure 4 but with tags and properties added:








|
|







 







>
>







 







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







85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
...
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
...
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
Fossil also uses a forked branch's leaf check-in timestamps when
checking out that branch: it gives you the fork with the latest
check-in, which in turn selects which parent your next check-in will be
a child of.  This situation means development on that branch can fork
into two independent lines of development, based solely on which branch
tip is newer at the time the next user starts his work on it.  Because
of this, we strongly recommend that you do not intentionally create
forks on long-lived shared working branches with "--allow-fork".  (Prime
example: trunk.)

Let us return to Figure 2. To resolve such situations before they can
become a real problem, Alice can use the <b>fossil merge</b> command to
merge Bob's changes into her local copy of check-in 3.  Then she can
commit the results as check-in 5.  This results in a DAG as shown in
Figure 3.

................................................................................
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>

Forks *may* be intentional, but most of the time, they're accidental.

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>
................................................................................
temporarily fork the branch's development. It avoids cluttering the
global branch namespace with short-lived temporary named branches.

There's a common generalization of that case: you're a solo developer,
so that the problems with branching vs forking simply don't matter. In
that case, feel free to use "--allow-fork" as much as you like.


<h2 id="fix">Fixing Forks</h2>

If your local checkout is on a forked branch, you can usually fix a fork
automatically with:

<pre>
    $ fossil merge
</pre>

Normally you need to pass arguments to <b>fossil merge</b> to tell it
what you want to merge into the current basis view of the repository,
but without arguments, the command seeks out and fixes forks.


<h2 id="tags">Tags And Properties</h2>

Tags and properties are used in Fossil to help express the intent, and
thus to distinguish between forks and branches.  Figure 5 shows the
same scenario as Figure 4 but with tags and properties added: