Fossil

Check-in [2da10998]
Login

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

Overview
Comment:Added new section, "The Authors' Voice" to www/branching.wiki. Other assorted improvements as well.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 2da109981a198bf89b00218f510dc6942c98142fef2e00b1188425880e9c57bd
User & Date: wyoung 2019-06-20 13:32:19
Context
2019-06-20
16:40
Removed "The Author's Voice" from www/branching.wiki due to multiple complaints. check-in: 1926d1d5 user: wyoung tags: trunk
13:32
Added new section, "The Authors' Voice" to www/branching.wiki. Other assorted improvements as well. check-in: 2da10998 user: wyoung tags: trunk
11:30
Markdownism fix in a Wiki-formatted doc check-in: cbca374c user: wyoung tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to www/branching.wiki.

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
217
218
219
220
221
222
...
236
237
238
239
240
241
242
243
244

245
246
247
248
249
250
251
252
...
428
429
430
431
432
433
434

435












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 named, intentional forks
a.k.a. branches. First:

<pre>
    $ fossil commit --branch my-new-branch-name
</pre>

This is the method we recommend for most cases: it creates a branch as
part of a checkin using the current branch as its basis. After the



checkin, your local working directory is switched to that branch, so
that further checkins occur on that branch as well, as children of the
last checkin on that branch.

The second, more complicated option is:

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


Not only is the first command longer, you must give the second command
before creating any checkins, because until you do, your local working
directory remains on the same branch it was on at the time you issued
the command.



In addition to those problems, the second method is 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.

(Keep in mind that trunk is just another branch in Fossil. It is simply
................................................................................
    autosync is disabled on one or both of the repositories or because
    the user doing the check-in has no network connection at the moment
    of the commit, Fossil has no way of knowing that it is creating a
    fork until the two repositories are later sync'd.</p></li>

    <li><p>By Fossil when the cloning hierarchy is more than 2 levels
    deep. If your master repository is cloned by user A and then user B
    clones from user A's repository, check-ins to user B's repo do not
    check the master repo before allowing the check-in even with

    autosync enabled. It isn't until user A syncs her repo with the
    master repo that an inadvertent fork can be detected.
    <br><br>
    Because of this, we recommend that if you're using Fossil in a
    distributed way like this, that check-ins be made only to the master
    or its immediate child repos, and that those further down the chain
    be read-only clones. This is not to say that we repudiate Fossil's
    use as a Distributed Version Control System, just that such use is
................................................................................
Because some VCSes can't cope with duplicate branch names, Fossil
collapses such names down on export using the same timestamp based
arbitration logic, so that only the branch with the newest checkin gets
the branch name in the export.

All of the above is true of tags in general, not just branches.






















|







|
>
>
>


|









>
|


<
>
>







 







|
|
>
|







 







>

>
>
>
>
>
>
>
>
>
>
>
>
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
217
218

219
220
221
222
223
224
225
226
227
...
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
...
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
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 named, intentional forks,
a.k.a. branches. First:

<pre>
    $ fossil commit --branch my-new-branch-name
</pre>

This is the method we recommend for most cases: it creates a branch as
part of a checkin using the version in the current checkout directory
as its basis. (This is normally the tip of the current branch, though
it doesn't have to be. You can create a branch from an ancestor checkin
on a branch as well.) After making this branch-creating
checkin, your local working directory is switched to that branch, so
that further checkins occur on that branch as well, as children of the
tip checkin on that branch.

The second, more complicated option is:

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

Not only is this three commands instead of one, the first of which is
longer than the entire simpler command above, you must give the second command
before creating any checkins, because until you do, your local working
directory remains on the same branch it was on at the time you issued

the command, so that the commit would otherwise put the new material on
the original branch instead of the new one.

In addition to those problems, the second method is 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.

(Keep in mind that trunk is just another branch in Fossil. It is simply
................................................................................
    autosync is disabled on one or both of the repositories or because
    the user doing the check-in has no network connection at the moment
    of the commit, Fossil has no way of knowing that it is creating a
    fork until the two repositories are later sync'd.</p></li>

    <li><p>By Fossil when the cloning hierarchy is more than 2 levels
    deep. If your master repository is cloned by user A and then user B
    clones from user A's repository, a check-in by user B will cause
    that repo to attempt an autosync with user A's repo before allowing
    the checkin, but it will <i>not</i> check with the master repo as
    well. It isn't until user A syncs her repo with the
    master repo that an inadvertent fork can be detected.
    <br><br>
    Because of this, we recommend that if you're using Fossil in a
    distributed way like this, that check-ins be made only to the master
    or its immediate child repos, and that those further down the chain
    be read-only clones. This is not to say that we repudiate Fossil's
    use as a Distributed Version Control System, just that such use is
................................................................................
Because some VCSes can't cope with duplicate branch names, Fossil
collapses such names down on export using the same timestamp based
arbitration logic, so that only the branch with the newest checkin gets
the branch name in the export.

All of the above is true of tags in general, not just branches.

<h2 id="voice">The Authors' Voice</h2>

Above, "we" refers to
[/blame?udc=1&w=on&checkin=trunk&filename=www%2Fbranching.wiki|the
historical authors of this file]. It is our collective voice and
opinions above. As in all walks of life, this is not the only possible
philosophy, but it is our duty and pleasure in this document to present
our philosophy to you. You are of course free to adopt or reject as much
of it as you like. Fossil supports many styles, not just those this
document's authors prefer. This should go without saying, but we get
push-back from people who apparently believe all documents on all web
pages should either support their beliefs, or they are factually wrong.
Someone is [https://www.xkcd.com/386/|always wrong on the Internet],
somewhere.  Please don't hold that against us.