Fossil

    ){
      @ <tr><th>Original&nbsp;User&nbsp;&amp;&nbsp;Date:</th><td>
      hyperlink_to_user(zOrigUser,zOrigDate," on ");
      hyperlink_to_date(zOrigDate, "</td></tr>");
    }
    if( g.perm.Admin ){
      db_prepare(&q2,
         "SELECT rcvfrom.ipaddr, user.login, datetime(rcvfrom.mtime)"

         "  FROM blob JOIN rcvfrom USING(rcvid) LEFT JOIN user USING(uid)"
         " WHERE blob.rid=%d",
         rid
      );
      if( db_step(&q2)==SQLITE_ROW ){
        const char *zIpAddr = db_column_text(&q2, 0);
        const char *zUser = db_column_text(&q2, 1);
        const char *zDate = db_column_text(&q2, 2);

        if( zUser==0 || zUser[0]==0 ) zUser = "unknown";
        @ <tr><th>Received&nbsp;From:</th>
        @ <td>%h(zUser) @ %h(zIpAddr) on %s(zDate)</td></tr>

      }
      db_finalize(&q2);
    }

    /* Only show links to read wiki pages if the users can read wiki
    ** and if the wiki pages already exist */
    if( g.perm.RdWiki

    ){
      @ <tr><th>Original&nbsp;User&nbsp;&amp;&nbsp;Date:</th><td>
      hyperlink_to_user(zOrigUser,zOrigDate," on ");
      hyperlink_to_date(zOrigDate, "</td></tr>");
    }
    if( g.perm.Admin ){
      db_prepare(&q2,
         "SELECT rcvfrom.ipaddr, user.login, datetime(rcvfrom.mtime),"
               " blob.rcvid"
         "  FROM blob JOIN rcvfrom USING(rcvid) LEFT JOIN user USING(uid)"
         " WHERE blob.rid=%d",
         rid
      );
      if( db_step(&q2)==SQLITE_ROW ){
        const char *zIpAddr = db_column_text(&q2, 0);
        const char *zUser = db_column_text(&q2, 1);
        const char *zDate = db_column_text(&q2, 2);
        int rcvid = db_column_int(&q2,3);
        if( zUser==0 || zUser[0]==0 ) zUser = "unknown";
        @ <tr><th>Received&nbsp;From:</th>
        @ <td>%h(zUser) @ %h(zIpAddr) on %s(zDate) \
        @ (<a href="%R/rcvfrom?rcvid=%d(rcvid)">Rcvid %d(rcvid)</a>)</td></tr>
      }
      db_finalize(&q2);
    }

    /* Only show links to read wiki pages if the users can read wiki
    ** and if the wiki pages already exist */
    if( g.perm.RdWiki

** If the VERSION argument is omitted, then Fossil attempts to find
** a recent fork on the current branch to merge.
**
** Only file content is merged.  The result continues to use the
** file and directory names from the current checkout even if those
** names might have been changed in the branch being merged in.
**
** Other options:




**
**   --baseline BASELINE     Use BASELINE as the "pivot" of the merge instead
**                           of the nearest common ancestor.  This allows
**                           a sequence of changes in a branch to be merged
**                           without having to merge the entire branch.
**
**   --binary GLOBPATTERN    Treat files that match GLOBPATTERN as binary
**                           and do not try to merge parallel changes.  This
**                           option overrides the "binary-glob" setting.
**
**   --case-sensitive BOOL   Override the case-sensitive setting.  If false,
**                           files whose names differ only in case are taken
**                           to be the same file.





**
**   -f|--force              Force the merge even if it would be a no-op.
**
**   --force-missing         Force the merge even if there is missing content.
**
**   --integrate             Merged branch will be closed when committing.
**

** If the VERSION argument is omitted, then Fossil attempts to find
** a recent fork on the current branch to merge.
**
** Only file content is merged.  The result continues to use the
** file and directory names from the current checkout even if those
** names might have been changed in the branch being merged in.
**
** Options:
**
**   --backout               Do a reverse cherrypick merge against VERSION.
**                           In other words, back out the changes that were
**                           added by VERSION.
**
**   --baseline BASELINE     Use BASELINE as the "pivot" of the merge instead
**                           of the nearest common ancestor.  This allows
**                           a sequence of changes in a branch to be merged
**                           without having to merge the entire branch.
**
**   --binary GLOBPATTERN    Treat files that match GLOBPATTERN as binary
**                           and do not try to merge parallel changes.  This
**                           option overrides the "binary-glob" setting.
**
**   --case-sensitive BOOL   Override the case-sensitive setting.  If false,
**                           files whose names differ only in case are taken
**                           to be the same file.
**
**   --cherrypick            Do a cherrypick merge VERSION into the current
**                           checkout.  A cherrypick merge pulls in the changes
**                           of the single check-in VERSION, rather than all
**                           changes back to the nearest common ancestor.
**
**   -f|--force              Force the merge even if it would be a no-op.
**
**   --force-missing         Force the merge even if there is missing content.
**
**   --integrate             Merged branch will be closed when committing.
**

[/help?cmd=ui|UI],
protected by [./caps/ | a fine-grained role-based
access control system].
These additional capabilities are available for Git as 3rd-party
add-ons, but with Fossil they are integrated into
the design.  One way to describe Fossil is that it is
"[https://github.com/ | GitHub]-in-a-box."






















For developers who choose to self-host projects (rather than using a
3rd-party service such as GitHub) Fossil is much easier to set up, since
the stand-alone Fossil executable together with a [./server/any/cgi.md|2-line CGI script]
suffice to instantiate a full-featured developer website.  To accomplish
the same using Git requires locating, installing, configuring, integrating,
and managing a wide assortment of separate tools.  Standing up a developer
................................................................................
Over half of the C code in Fossil is actually an embedded copy of the
current version of SQLite. Much of what is Fossil-specific after you set
SQLite itself aside is SQL code calling into SQLite. The number of lines
of SQL code in Fossil isn't large by percentage, but since SQL is such
an expressive, declarative language, it has an outsized contribution to
Fossil's user-visible functionality.

Fossil isn't entirely C and SQL code. Its web UI uses JavaScript where

necessary.⁵ The server-side
UI scripting uses a custom minimal
[https://en.wikipedia.org/wiki/Tcl|Tcl] dialect called
[https://www.fossil-scm.org/xfer/doc/trunk/www/th1.md|TH1], which is
embedded into Fossil itself. Fossil's build system and test suite are
largely based on Tcl.⁶ All of this is quite portable.

About half of Git's code is POSIX C, and about a third is POSIX shell
code. This is largely why the so-called "Git for Windows" distributions
(both [https://git-scm.com/download/win|first-party] and
[https://gitforwindows.org/|third-party]) are actually an
[http://mingw.org/wiki/msys|MSYS POSIX portability environment] bundled
with all of the Git stuff, because it would be too painful to port Git
natively to Windows. Git is a foreign citizen on Windows, speaking to it
only through a translator.⁷

While Fossil does lean toward POSIX norms when given a choice — LF-only
line endings are treated as first-class citizens over CR+LF, for example
— the Windows build of Fossil is truly native.

The third-party extensions to Git tend to follow this same pattern.
[http://mingw.org/wiki/msys|GitLab isn't portable to Windows at all],
................................................................................

    <li><p><b>No easy drive-by contributions:</b> Git
    [https://www.git-scm.com/docs/git-request-pull|pull requests] offer
    a low-friction path to accepting
    [https://www.jonobacon.com/2012/07/25/building-strong-community-structural-integrity/|drive-by
    contributions]. Fossil's closest equivalent is its unique
    [/help?cmd=bundle|bundle] feature, which requires higher engagement
    than firing off a PR.⁸ This difference comes directly from the
    initial designed purpose for each tool: the SQLite project doesn't
    accept outside contributions from previously-unknown developers, but
    the Linux kernel does.</p></li>

    <li><p><b>No rebasing:</b> When your local repo clone syncs changes
    up to its parent, those changes are sent exactly as they were
    committed locally. [#history|There is no rebasing mechanism in
................................................................................

<h4 id="branches">2.5.4 Individual Branches vs. The Entire Change History</h4>

Both Fossil and Git store history as a directed acyclic graph (DAG)
of changes, but Git tends to focus more on individual branches of
the DAG, whereas Fossil puts more emphasis on the entire DAG.

For example, the default "sync" behavior in Git is to only sync
a single branch, whereas with Fossil the only sync option it to
sync the entire DAG.  Git commands,
GitHub, and GitLab tend to show only a single branch at
a time, whereas Fossil usually shows all parallel branches at
once.  Git has commands like "rebase" that help keep all relevant
changes on a single branch, whereas Fossil encourages a style of
many concurrent branches constantly springing into existence,
undergoing active development in parallel for a few days or weeks, then
................................................................................
Fossil's implementation of the feature is also simpler to describe. The
brief online help for <tt>[/help?cmd=merge | fossil merge]</tt> is
currently 41 lines long, to which you want to add the 600 lines of
[./branching.wiki | the branching document]. The equivalent
documentation in Git is the aggregation of the man pages for the above
three commands, which is over 1000 lines, much of it mutually redundant.
(e.g.  the <tt>--edit</tt> and <tt>--no-commit</tt> options get
described three different times, each time differently.) Fossil's
documentation is not only more concise, it gives a nice split of brief
online help and full online documentation.


<h3 id="hash">2.9 Hash Algorithm: SHA-3 vs SHA-2 vs SHA-1</h3>

Fossil started out using 160-bit SHA-1 hashes to identify check-ins,
................................................................................
[https://shattered.io/|SHAttered attack] broke, demonstrating that SHA-1
collisions were now practical to create. Two weeks later, the creator of
Fossil delivered a new release allowing a clean migration to
[https://en.wikipedia.org/wiki/SHA-3|256-bit SHA-3] with
[./hashpolicy.wiki|full backwards compatibility] to old SHA-1 based
repositories.

Here in mid-2019, that feature is now in every OS and package repository
known to include Fossil so that the next release
(Fossil 2.10) will begin using SHA-3 hashes even on repos currently
limited to SHA-1 for compatibility with Fossil 1.<i>x</i>,
effectively upgrading them to require Fossil 2.1 or newer. This


not only solves the SHAttered problem, it should prevent a reoccurrence
for the foreseeable future. With the current release (Fossil 2.9) only
repositories created before the
transition to Fossil 2 are still using SHA-1, and then only if the
repository's maintainer chose not to switch them into SHA-3 mode some
time over the past 2 years.

Meanwhile, the Git community took until August 2018 to announce
[https://git-scm.com/docs/hash-function-transition/2.18.0|their plan]
for solving the same problem by moving to SHA-256 (a variant of the
[https://en.wikipedia.org/wiki/SHA-2|older SHA-2 algorithm]) and until
February 2019 to release a version containing the change. It's looking
like this will take years more to percolate through the community.
................................................................................
The practical impact of SHAttered on structured data stores like the one
in Git and Fossil isn't clear, but you want to have your repositories
moved over to a stronger hash algorithm before someone figures out how
to make use of the weaknesses in the old one.  Fossil's developers moved
on this problem quickly and had a widely-deployed solution to it years
ago.


<h2 id="missing">3.0 Missing Features</h2>

Although there is a large overlap in capability between Fossil and Git,
there are many areas where one system has a feature that is simply
missing in the other. We covered most of those above, but there
are a few remaining feature differences we haven't gotten to yet.


<h3 id="missing-in-git">3.1 Features found in Fossil but missing from Git</h3>

  *  <b>The [/help?cmd=all|fossil all] command</b>

   Fossil keeps track of all repositories and check-outs and allows
   operations over all of them with a single command.  For example, in
   Fossil is possible to request a pull of all repositories on a laptop
   from their respective servers, prior to taking the laptop off network.
   Or it is possible to do "fossil all changes" to see if there are any
   uncommitted changes that were overlooked prior to the end of the workday.

  *  <b>The [/help?cmd=undo|fossil undo] command</b>

   Whenever Fossil is told to modify the local checkout in some
   destructive way ([/help?cmd=rm|fossil rm], [/help?cmd=update|fossil
   update], [/help?cmd=revert|fossil revert], etc.) Fossil remembers the
   prior state and is able to return the local check-out directory to
   its prior state with a simple "fossil undo" command. You
   [#history|cannot undo a commit], since writes to the actual
   repository — as opposed to the local check-out directory — are more
   or less permanent, on purpose, but as long as the change is simply
   staged locally, Fossil makes undo
   [https://git-scm.com/book/en/v2/Git-Basics-Undoing-Things|easier than
   in Git].


<h3 id="missing-in-fossil">3.2 Features found in Git but missing from Fossil</h3>

  *  <b>Rebase</b>

   Because of its emphasis on recording history exactly as it happened,
   rather than as we would have liked it to happen, 
   [./rebaseharm.md|Fossil deliberately omits the "rebase" command].
   For those rare
   occasions where something like rebase is actually needed, the same
   topology can be achieved using cherrypick merges.

  *  <b>Push or pull a single branch</b>

   The [/help?cmd=push|fossil push], [/help?cmd=pull|fossil pull], and
   [/help?cmd=sync|fossil sync] commands do not provide the capability to
   push or pull individual branches.  Pushing and pulling in Fossil is
   all or nothing.  This is in keeping with Fossil's emphasis on maintaining
   a complete record and on sharing everything between all developers.

<hr/>

<h3>Asides and Digressions</h3>

<i><small><ol>
    <li><p>[./mirrorlimitations.md|Many
    things are lost] in making a Git mirror of a Fossil repo due to
................................................................................
    requirements among Digital Ocean's offerings currently costs
    $40/month.

    <li><p>This means you can give up waiting for Fossil to be ported to
    the PDP-11, but we remain hopeful that someone may eventually port
    it to [https://en.wikipedia.org/wiki/Z/OS|z/OS].

    <li><p>We try to keep use of Javascript to a minimum in the web UI,
    and we always try to provide sensible fall-backs for those that run
    their browsers with Javascript disabled. Some features of the web UI
    simply won't run without Javascript, but the UI behavior does
    degrade gracefully.

    <li><p>"Why is there all this Tcl in and around Fossil?" you may
    ask. It is because D. Richard Hipp is a long-time Tcl user and
    contributor. SQLite started out as an embedded database for Tcl
    specifically. ([https://sqlite.org/tclsqlite.html | [Reference]])
    When he then created Fossil to manage the development of SQLite, it
    was natural for him to use Tcl-based tools for its scripting, build
    system, test system, etc. It came full circle in 2011 when

[/help?cmd=ui|UI],
protected by [./caps/ | a fine-grained role-based
access control system].
These additional capabilities are available for Git as 3rd-party
add-ons, but with Fossil they are integrated into
the design.  One way to describe Fossil is that it is
"[https://github.com/ | GitHub]-in-a-box."

Fossil can do operations over all local repo clones and check-out
directories with a single command. For example, Fossil lets you say
<tt>fossil all pull</tt> on a laptop prior to taking it off the network
hosting those repos. You can sync up to all of the private repos on your
company network plus those public Internet-hosted repos you use. Whether
going out for a working lunch or on a transoceanic an airplane trip, one
command gets you in sync. This works with several other Fossil
sub-commands, such as <tt>fossil all changes</tt> to get a list of files
that you forgot to commit prior to the end of your working day, across
all repos.

Whenever Fossil is told to modify the local checkout in some destructive
way ([/help?cmd=rm|fossil rm], [/help?cmd=update|fossil update],
[/help?cmd=revert|fossil revert], etc.) Fossil remembers the prior state
and is able to return the check-out directory to that state with a
<tt>fossil undo</tt> command. You cannot undo a commit in Fossil
([#history | on purpose!]) but as long as the change remains confined to
the local check-out directory only, Fossil makes undo
[https://git-scm.com/book/en/v2/Git-Basics-Undoing-Things|easier than in
Git].

For developers who choose to self-host projects (rather than using a
3rd-party service such as GitHub) Fossil is much easier to set up, since
the stand-alone Fossil executable together with a [./server/any/cgi.md|2-line CGI script]
suffice to instantiate a full-featured developer website.  To accomplish
the same using Git requires locating, installing, configuring, integrating,
and managing a wide assortment of separate tools.  Standing up a developer
................................................................................
Over half of the C code in Fossil is actually an embedded copy of the
current version of SQLite. Much of what is Fossil-specific after you set
SQLite itself aside is SQL code calling into SQLite. The number of lines
of SQL code in Fossil isn't large by percentage, but since SQL is such
an expressive, declarative language, it has an outsized contribution to
Fossil's user-visible functionality.

Fossil isn't entirely C and SQL code. Its web UI [./javascript.md |
uses JavaScript where
necessary]. The server-side
UI scripting uses a custom minimal
[https://en.wikipedia.org/wiki/Tcl|Tcl] dialect called
[https://www.fossil-scm.org/xfer/doc/trunk/www/th1.md|TH1], which is
embedded into Fossil itself. Fossil's build system and test suite are
largely based on Tcl.⁵ All of this is quite portable.

About half of Git's code is POSIX C, and about a third is POSIX shell
code. This is largely why the so-called "Git for Windows" distributions
(both [https://git-scm.com/download/win|first-party] and
[https://gitforwindows.org/|third-party]) are actually an
[http://mingw.org/wiki/msys|MSYS POSIX portability environment] bundled
with all of the Git stuff, because it would be too painful to port Git
natively to Windows. Git is a foreign citizen on Windows, speaking to it
only through a translator.⁶

While Fossil does lean toward POSIX norms when given a choice — LF-only
line endings are treated as first-class citizens over CR+LF, for example
— the Windows build of Fossil is truly native.

The third-party extensions to Git tend to follow this same pattern.
[http://mingw.org/wiki/msys|GitLab isn't portable to Windows at all],
................................................................................

    <li><p><b>No easy drive-by contributions:</b> Git
    [https://www.git-scm.com/docs/git-request-pull|pull requests] offer
    a low-friction path to accepting
    [https://www.jonobacon.com/2012/07/25/building-strong-community-structural-integrity/|drive-by
    contributions]. Fossil's closest equivalent is its unique
    [/help?cmd=bundle|bundle] feature, which requires higher engagement
    than firing off a PR.⁷ This difference comes directly from the
    initial designed purpose for each tool: the SQLite project doesn't
    accept outside contributions from previously-unknown developers, but
    the Linux kernel does.</p></li>

    <li><p><b>No rebasing:</b> When your local repo clone syncs changes
    up to its parent, those changes are sent exactly as they were
    committed locally. [#history|There is no rebasing mechanism in
................................................................................

<h4 id="branches">2.5.4 Individual Branches vs. The Entire Change History</h4>

Both Fossil and Git store history as a directed acyclic graph (DAG)
of changes, but Git tends to focus more on individual branches of
the DAG, whereas Fossil puts more emphasis on the entire DAG.

For example, the default behavior in Git is to only synchronize
a single branch, whereas with Fossil the only sync option is to
sync the entire DAG.  Git commands,
GitHub, and GitLab tend to show only a single branch at
a time, whereas Fossil usually shows all parallel branches at
once.  Git has commands like "rebase" that help keep all relevant
changes on a single branch, whereas Fossil encourages a style of
many concurrent branches constantly springing into existence,
undergoing active development in parallel for a few days or weeks, then
................................................................................
Fossil's implementation of the feature is also simpler to describe. The
brief online help for <tt>[/help?cmd=merge | fossil merge]</tt> is
currently 41 lines long, to which you want to add the 600 lines of
[./branching.wiki | the branching document]. The equivalent
documentation in Git is the aggregation of the man pages for the above
three commands, which is over 1000 lines, much of it mutually redundant.
(e.g.  the <tt>--edit</tt> and <tt>--no-commit</tt> options get
described three times, each time differently.) Fossil's
documentation is not only more concise, it gives a nice split of brief
online help and full online documentation.


<h3 id="hash">2.9 Hash Algorithm: SHA-3 vs SHA-2 vs SHA-1</h3>

Fossil started out using 160-bit SHA-1 hashes to identify check-ins,
................................................................................
[https://shattered.io/|SHAttered attack] broke, demonstrating that SHA-1
collisions were now practical to create. Two weeks later, the creator of
Fossil delivered a new release allowing a clean migration to
[https://en.wikipedia.org/wiki/SHA-3|256-bit SHA-3] with
[./hashpolicy.wiki|full backwards compatibility] to old SHA-1 based
repositories.

By mid-2019, that feature arrived in every software package repository
shipping Fossil, the last mover being Debian's stable package repo,
which has a highly conservative policy on upgrading to new versions.
With that hurdle run, we were able to change the default hash mode in
Fossil 2.10 (released 2019-10-04) to require SHA-3 support both for new
repositories and to create SHA-3 hashes in existing repos, effectively
upgrading them if they were created with Fossil 1.<i>x</i>. This not
only solves the SHAttered problem, it should prevent a reoccurrence of
similar problems for the foreseeable future.





Meanwhile, the Git community took until August 2018 to announce
[https://git-scm.com/docs/hash-function-transition/2.18.0|their plan]
for solving the same problem by moving to SHA-256 (a variant of the
[https://en.wikipedia.org/wiki/SHA-2|older SHA-2 algorithm]) and until
February 2019 to release a version containing the change. It's looking
like this will take years more to percolate through the community.
................................................................................
The practical impact of SHAttered on structured data stores like the one
in Git and Fossil isn't clear, but you want to have your repositories
moved over to a stronger hash algorithm before someone figures out how
to make use of the weaknesses in the old one.  Fossil's developers moved
on this problem quickly and had a widely-deployed solution to it years
ago.























































<hr/>

<h3>Asides and Digressions</h3>

<i><small><ol>
    <li><p>[./mirrorlimitations.md|Many
    things are lost] in making a Git mirror of a Fossil repo due to
................................................................................
    requirements among Digital Ocean's offerings currently costs
    $40/month.

    <li><p>This means you can give up waiting for Fossil to be ported to
    the PDP-11, but we remain hopeful that someone may eventually port
    it to [https://en.wikipedia.org/wiki/Z/OS|z/OS].







    <li><p>"Why is there all this Tcl in and around Fossil?" you may
    ask. It is because D. Richard Hipp is a long-time Tcl user and
    contributor. SQLite started out as an embedded database for Tcl
    specifically. ([https://sqlite.org/tclsqlite.html | [Reference]])
    When he then created Fossil to manage the development of SQLite, it
    was natural for him to use Tcl-based tools for its scripting, build
    system, test system, etc. It came full circle in 2011 when

files in faultless finished form. A wish for collapsed, finalized
check-ins is a wish for a counterfactual situation.

The common counterargument is that collapsed check-ins represent a
better world, the ideal we’re striving for. What that argument overlooks
is that we must throw away valuable information to get there.

## <a name="empathy"></a>7.1 Individual check-ins support developer empathy

Ideally, future developers of our software can understand every feature
in it using only context available in the version of the code they start
work with. Prior to widespread version control, developers had no choice
but to work that way.  Pre-existing codebases could only be understood
as-is or not at all.  Developers in that world had an incentive to
develop software that was easy to understand retrospectively, even if
................................................................................
check-in it was a part of — and then to understand the surrounding
check-ins as necessary — than it is to understand a 500-line check-in
that collapses a whole branch’s worth of changes down to a single
finished feature.

[sdm]: ./fossil-v-git.wiki#durable

## <a name="bisecting"></a>7.2 Bisecting works better on small check-ins

Git lets a developer write a feature in ten check-ins but collapse it
down to an eleventh check-in and then deliberately push only that final
collapsed check-in to the parent repo. Someone else may then do a bisect
that blames the merged check-in as the source of the problem they’re
chasing down; they then have to manually work out which of the 10 steps
the original developer took to create it to find the source of the
................................................................................
actual problem.

Fossil pushes all 11 check-ins to the parent repository by default, so
that someone doing that bisect sees the complete check-in history, so
the bisect will point them at the single original check-in that caused
the problem.

## <a name="comments"></a>7.3 Multiple check-ins require multiple check-in comments

The more comments you have from a given developer on a given body of
code, the more concise documentation you have of that developer’s
thought process. To resume the bisecting example, a developer trying to
work out what the original developer was thinking with a given change
will have more success given a check-in comment that explains what the
one check-in out of ten blamed by the “bisect” command was trying to
accomplish than if they must work that out from the eleventh check-in’s
comment, which only explains the “clean” version of the collapsed
feature.

## <a name="cherrypicking"></a>7.4 Cherry-picks work better with small check-ins

While working on a new feature in one branch, you may come across a bug
in the pre-existing code that you need to fix in order for work on that
feature to proceed. You could choose to switch briefly back to the
parent branch, develop the fix there, check it in, then merge the parent
back up to the feature branch in order to continue work, but that’s
distracting. If the fix isn’t for a critical bug, fixing it on the
................................................................................
complete. If a support organization must manually disentangle a fix from
a feature check-in, they are likely to introduce new bugs on the stable
branch. Even if they manage to do their work without error, it takes
them more time to do the cherry-pick that way.

[rh]: https://en.wikipedia.org/wiki/Red_Hat

## <a name="backouts"></a>7.5 Back-outs also work better with small check-ins

The inverse of the cherry-pick merge is the back-out merge. If you push
only a collapsed version of a private working branch up to the parent
repo, those working from that parent repo cannot automatically back out
any of the individual check-ins that went into that private branch.
Others must either manually disentangle the problematic part of your
merge check-in or back out the entire feature.

files in faultless finished form. A wish for collapsed, finalized
check-ins is a wish for a counterfactual situation.

The common counterargument is that collapsed check-ins represent a
better world, the ideal we’re striving for. What that argument overlooks
is that we must throw away valuable information to get there.

### <a name="empathy"></a>7.1 Individual check-ins support developer empathy

Ideally, future developers of our software can understand every feature
in it using only context available in the version of the code they start
work with. Prior to widespread version control, developers had no choice
but to work that way.  Pre-existing codebases could only be understood
as-is or not at all.  Developers in that world had an incentive to
develop software that was easy to understand retrospectively, even if
................................................................................
check-in it was a part of — and then to understand the surrounding
check-ins as necessary — than it is to understand a 500-line check-in
that collapses a whole branch’s worth of changes down to a single
finished feature.

[sdm]: ./fossil-v-git.wiki#durable

### <a name="bisecting"></a>7.2 Bisecting works better on small check-ins

Git lets a developer write a feature in ten check-ins but collapse it
down to an eleventh check-in and then deliberately push only that final
collapsed check-in to the parent repo. Someone else may then do a bisect
that blames the merged check-in as the source of the problem they’re
chasing down; they then have to manually work out which of the 10 steps
the original developer took to create it to find the source of the
................................................................................
actual problem.

Fossil pushes all 11 check-ins to the parent repository by default, so
that someone doing that bisect sees the complete check-in history, so
the bisect will point them at the single original check-in that caused
the problem.

### <a name="comments"></a>7.3 Multiple check-ins require multiple check-in comments

The more comments you have from a given developer on a given body of
code, the more concise documentation you have of that developer’s
thought process. To resume the bisecting example, a developer trying to
work out what the original developer was thinking with a given change
will have more success given a check-in comment that explains what the
one check-in out of ten blamed by the “bisect” command was trying to
accomplish than if they must work that out from the eleventh check-in’s
comment, which only explains the “clean” version of the collapsed
feature.

### <a name="cherrypicking"></a>7.4 Cherry-picks work better with small check-ins

While working on a new feature in one branch, you may come across a bug
in the pre-existing code that you need to fix in order for work on that
feature to proceed. You could choose to switch briefly back to the
parent branch, develop the fix there, check it in, then merge the parent
back up to the feature branch in order to continue work, but that’s
distracting. If the fix isn’t for a critical bug, fixing it on the
................................................................................
complete. If a support organization must manually disentangle a fix from
a feature check-in, they are likely to introduce new bugs on the stable
branch. Even if they manage to do their work without error, it takes
them more time to do the cherry-pick that way.

[rh]: https://en.wikipedia.org/wiki/Red_Hat

### <a name="backouts"></a>7.5 Back-outs also work better with small check-ins

The inverse of the cherry-pick merge is the back-out merge. If you push
only a collapsed version of a private working branch up to the parent
repo, those working from that parent repo cannot automatically back out
any of the individual check-ins that went into that private branch.
Others must either manually disentangle the problematic part of your
merge check-in or back out the entire feature.

# Using Windows as a Fossil Server



- [Fossil as a Service](service.md)
- [Using stunnel with Fossil on Windows](stunnel.md)

*[Return to the top-level Fossil server article.](../)*

# Using Windows as a Fossil Server

- [Fossil server command](./none.md)
- [Fossil as CGI (IIS)](./iis.md)
- [Fossil as a Service](./service.md)
- [Using stunnel with Fossil on Windows](./stunnel.md)

*[Return to the top-level Fossil server article.](../)*

1. You have Administrative access to a Windows 2012r2 or above server.
2. You have PowerShell 5.1 or above installed.

## Place Fossil on Server

However you obtained your copy of Fossil, it is recommended that you follow
Windows conventions and place it within `\Program Files\FossilSCM`.  Since
Fossil 2.10 is a 64bit binary, this is the proper location for the executable.  This
way Fossil is in an expected location and you will have minimal issues with
Windows interfering in your ability to run Fossil as a service.  You will need
Administrative rights to place fossil at the recommended location.  You do NOT

need to add this location to the path, though you may do so if you wish.

## Make Fossil a Windows Service


Luckily the hard work to use Fossil as a Windows Service has been done by the
Fossil team.  We simply have to install it with the proper command line options.
Fossil on Windows has a command `fossil winsrv` to allow installing Fossil as a
service on Windows, but the options are limited, so an alternative service
install using PowerShell is documented here.  The below should all be entered

































as a single line in an Administrative PowerShell console.


```PowerShell
New-Service -Name fossil -DisplayName fossil -BinaryPathName '"C:\Program Files\FossilSCM\fossil.exe"
server --port 8080 --repolist "D:/Path/to/Repos"' -StartupType Automatic
```

Please note the use of forward slashes in the repolist path passed to Fossil.
Windows will accept either back slashes or forward slashes in path names, but
Fossil has a preference for forward slashes.  The use of `--repolist` will make
this a multiple repository server.  If you want to serve only a single
repository, then leave off the `--repolist` parameter and provide the full path

1. You have Administrative access to a Windows 2012r2 or above server.
2. You have PowerShell 5.1 or above installed.

## Place Fossil on Server

However you obtained your copy of Fossil, it is recommended that you follow
Windows conventions and place it within `\Program Files\FossilSCM`.  Since
Fossil 2.10 is a 64bit binary, this is the proper location for the executable.
This way Fossil is at an expected location and you will have minimal issues with
Windows interfering in your ability to run Fossil as a service.  You will need
Administrative rights to place fossil at the recommended location.  If you will
only be running Fossil as a service, you do not need to add this location to the
path, though you may do so if you wish.


## Installing Fossil as a Service

Luckily the hard work to use Fossil as a Windows Service has been done by the
Fossil team.  We simply have to install it with the proper command line options.
Fossil on Windows has a command `fossil winsrv` to allow installing Fossil as a

service on Windows.  This command is only documented on the windows executable
of Fossil.  You must also run the command as administrator for it to be
successful.

### Fossil winsrv Example

The simplest form of the command is:

```
fossil winsrv create --repository D:/Path/to/Repo.fossil
```

This will create a windows service named 'Fossil-DSCM' running under the local
system account and accessible on port 8080 by default.  `fossil winsrv` can also
start, stop, and delete the service.  For all available options, please execute
`fossil help winsrv` on a windows install of Fossil.

If you wish to server a directory of repositories, the `fossil winsrv` command
requires a slightly different set of options vs. `fossil server`:

```
fossil winsrv create --repository D:/Path/to/Repos --repolist
```

<a name='PowerShell'></a>
### Advanced service installation using PowerShell

As great as `fossil winsrv` is, it does not have one to one reflection of all of
the `fossil server` [options](/help?cmd=server).  When you need to use some of
the more advanced options, such as `--https`, `--skin`, or `--extroot`, you will
need to use PowerShell to configure and install the Windows service.

PowerShell provides the [New-Service](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.management/new-service?view=powershell-5.1)
command, which we can use to install and configure Fossil as a service.  The
below should all be entered as a single line in an Administrative PowerShell
console.

```PowerShell
New-Service -Name fossil -DisplayName fossil -BinaryPathName '"C:\Program Files\FossilSCM\fossil.exe" server --port 8080 --repolist "D:/Path/to/Repos"' -StartupType Automatic

```

Please note the use of forward slashes in the repolist path passed to Fossil.
Windows will accept either back slashes or forward slashes in path names, but
Fossil has a preference for forward slashes.  The use of `--repolist` will make
this a multiple repository server.  If you want to serve only a single
repository, then leave off the `--repolist` parameter and provide the full path

versions may not function in a similar manner.  There is a bug in Fossil 2.9 and
earlier that prevents these versions of Fossil from properly constructing https
URLs when used with stunnel as a proxy.  Please make sure you are using Fossil
2.10 or later on Windows.

## Configure Fossil Service for https

Following most of [Fossil as a Windows Service](./service.md), you will need

to change the command to install the Fossil Service to configure it properly for
use with stunnel as an https proxy.  Run the following instead:

```PowerShell
New-Service -Name fossil-secure -DisplayName fossil-secure -BinaryPathName '"C:\Program Files\FossilSCM\fossil.exe"
server --localhost --port 9000 --https --repolist "D:/Path/to/Repos"' -StartupType Automatic

```

The use of `--localhost` means Fossil will only listen for traffic on the local
host on the designated port - 9000 in this case - and will not respond to
network traffic.  Using `--https` will tell Fossil to generate HTTPS URLs rather
than HTTP ones.

versions may not function in a similar manner.  There is a bug in Fossil 2.9 and
earlier that prevents these versions of Fossil from properly constructing https
URLs when used with stunnel as a proxy.  Please make sure you are using Fossil
2.10 or later on Windows.

## Configure Fossil Service for https

Due to the need for the `--https` option for successfully using Fossil with
stunnel, we will use [Advanced service installation using PowerShell](./service.md#PowerShell).
We will need to change the command to install the Fossil Service to configure
it properly for use with stunnel as an https proxy.  Run the following:

```PowerShell
New-Service -Name fossil-secure -DisplayName fossil-secure -BinaryPathName '"C:\Program Files\FossilSCM\fossil.exe" server --localhost --port 9000 --https --repolist "D:/Path/to/Repos"' -StartupType Automatic


```

The use of `--localhost` means Fossil will only listen for traffic on the local
host on the designated port - 9000 in this case - and will not respond to
network traffic.  Using `--https` will tell Fossil to generate HTTPS URLs rather
than HTTP ones.