Fossil

This skin was contributed by Étienne Deparis.
This skin was originally contributed by Étienne Deparis on 2015-02-22,
promoted to the default on 2015-03-14, and subsequently changed by many:

On 2015-03-14 this skin was promoted from an option to the default, which
involved moving it from its original home in the skins/etienne1 directory
into skins/default.
   https://fossil-scm.org/home/finfo/skins/default/css.txt
   https://fossil-scm.org/home/blame?filename=skins/default/css.txt&checkin=trunk

In February 2024, a sufficiently large set of changes were made to the
skin that we forked the old version for the benefit of those who needed
to reference the old one — as when migrating custom skin changes to work
atop the new default — or who simply preferred it.  See ../etienne.

/* Overall page style */
/* Overall page style; vi: filetype=css
 */

body {
  margin: 0 auto;
  background-color: white;
  font-family: sans-serif;
  font-size: 14pt;
}

a {
  /* Unvisited links are a lightness-adjusted version of this skin's
   * header blue, balancing contrast between the body text and the
   * background in order to meet the goals specified by the WCAG 2
   * accessbility standard, earning us an "AA" grade according to
   * the calculator result here:
   *
   *   https://webaim.org/resources/linkcontrastchecker/?fcolor=2E2E2E&bcolor=FFFFFF&lcolor=3779BF
   *
   * It is for this same reason that our not-quite-black body text
   * color is the shade of dark gray that it is.  It can't be any
   * lighter and still allow us to meet both targets. */
  color: #4183C4;
  color: #3779BF;
  text-decoration: none;
}
a:hover {
  color: #4183C4;
  text-decoration: underline;
}


/* Page title, above menu bars */

.title {
  color: #4183C4;
  float: left;
}
.title h1 {
  display: inline;
}
.title h1:after {
  content: " / ";
  color: #777;
  font-weight: normal;
  font-size: 2.20em;
}
.status {
  float: right;
  font-size: 0.7em;
  font-size: 0.8em;
}
div.logo {
  float: left;
  padding-right: 10px;
}
div.logo img {
  max-height: 2em;    /* smaller than title to keep it above the baseline */
}


/* Main menu and optional sub-menu */

.mainmenu {
  font-size: 0.8em;
  clear: both;
  background: #eaeaea linear-gradient(#fafafa, #eaeaea) repeat-x;
  border: 1px solid #eaeaea;
  border-radius: 5px;
  overflow-x: auto;
  overflow-y: hidden;
  white-space: nowrap;
  z-index: 21;  /* just above hbdrop */
}
.mainmenu a {
  text-decoration: none;
  color: #777;
  border-right: 1px solid #eaeaea;
}
.mainmenu a.active,
.mainmenu a:hover {
  color: #000;
  border-bottom: 2px solid #D26911;
}
div#hbdrop {
nav#hbdrop {
  background-color: white;
  border: 1px solid black;
  border-top: white;
  border-radius: 0 0 0.5em 0.5em;
  display: none;
  font-size: 80%;
  left: 2em;
  width: 90%;
  padding-right: 1em;
  position: absolute;
  z-index: 20;  /* just below mainmenu, but above timeline bubbles */
}

.submenu {
  font-size: .7em;
  font-size: 0.8em;
  padding: 10px;
  border-bottom: 1px solid #ccc;
}
.submenu a, .submenu label {
  padding: 10px 11px;
  text-decoration: none;
  color: #777;

  white-space: nowrap;
}


/* Main document area; elements common to most pages. */

.content {
  padding-top: 10px;
  padding: 1ex;
  font-size: 0.8em;
  color: #444;
  color: #2e2e2e;   /* justified above in "WCAG 2" comment */
}
.content blockquote {
  padding: 0 15px;
}
.content h1 {
.content h1 { font-size: 1.60em; color: #444; }
  font-size: 1.25em;
}
.content h2 {
  font-size: 1.15em;
.content h2 { font-size: 1.45em; color: #444; }
.content h3 { font-size: 1.15em; color: #444; }
}
.content h3 {
  font-size: 1.05em;
.content h4 { font-size: 1.05em; color: #444; }
.content h5 { font-size: 1.00em; color: #444; }
}

.section {
  font-size: 1em;
  font-weight: bold;
  background-color: #f5f5f5;
  border: 1px solid #d8d8d8;
  border-radius: 3px 3px 0 0;

hr {
  color: #eee;
}


/* Page footer */

.footer {
footer {
  border-top: 1px solid #ccc;
  padding: 10px;
  font-size: 0.7em;
  font-size: 0.8em;
  margin-top: 10px;
  color: #ccc;
}

/* Forum */

.forum a:visited {
  color: #6A7F94;
}

.forum blockquote {
div.forumSel {
  animation: 1s linear 0s sel-fade;
  background-color: white;      /* animation end state */
  border-left: 4px solid black; /* after-animation selection indicator */
}
@keyframes sel-fade {
  from { background-color: #cef;  }
    to { background-color: white; }
}

.forum form input {
  margin: 0.5em 0;
}


/* Markdown and Wiki-formatted pages: /wiki, /doc, /file... */

.markdown blockquote, p.blockquote, .sidebar {
  /* Override default.css version with our accent colors. */
  background-color: rgba(65, 131, 196, 0.1);
  border-left: 3px solid #254769;
  padding: .1em 1em;
  border-left-color: #4183c4;
}

/* Mark inline code fragments in the near-universal manner pioneered by
 * Stack Overflow, then picked up by approximately everyone, including
 * us, now.
 *
 * This combinatoric selector explosion results from a need to apply
 * these stylings inside multiple page container types, multiplied by
 * the surprisingly large number of tags HTML defines for semantically
 * differentiated monospaced inline markup.  If we do not target the
 * elements we want to affect carefully, we'll end up overreaching,
 * styling Fossil UI elements that use these tags for local purposes.
 *
 * HTML generated and emitted by Fossil UI does not always fall under
 * the skin's generic rules; we must avoid intruding on its domain.
 * Our limited intent here is to style user content only, where it is
 * unreasonable to expect its author to take the time to hand-craft
 * per-document styling.  Contrast Fossil UI, which often does exactly
 * that in order to get particular results.
 *
 * The equivalent Sass syntax is far more compact, thus clearer:
 * 
 * .artifact, .dir, .doc, .wiki                // the page types we target
 *   > .content                                // hands off header & footer
 *     &, > .fossil-doc, > .markdown           // wiki, HTML & MD emb docs
 *       > p                                   // inline elements only
 *         > code, > kbd, > samp, > tt, > var  // monospaced tag types
 *           background-color: #eee            // pale gray box that…
 *           padding: 0 4px                    // …extends around the sides
 *
 * We generated the CSS below by:
 *
 *   $ sassc code.sass | sed -e 's/, /,\n/g'
 *
 * …then hand-cleansed it to make it _somewhat_ more understandable.
 */
.artifact > .content               > p > code,
.artifact > .content               > p > kbd,
.artifact > .content               > p > samp,
.artifact > .content               > p > tt,
.artifact > .content               > p > var,
.artifact > .content > .fossil-doc > p > code,
.artifact > .content > .fossil-doc > p > kbd,
.artifact > .content > .fossil-doc > p > samp,
.artifact > .content > .fossil-doc > p > tt,
.artifact > .content > .fossil-doc > p > var,
.artifact > .content > .markdown   > p > code,
.artifact > .content > .markdown   > p > kbd,
.artifact > .content > .markdown   > p > samp,
.artifact > .content > .markdown   > p > tt,
.artifact > .content > .markdown   > p > var,
.dir      > .content               > p > code,
.dir      > .content               > p > kbd,
.dir      > .content               > p > samp,
.dir      > .content               > p > tt,
.dir      > .content               > p > var,
.dir      > .content > .fossil-doc > p > code,
.dir      > .content > .fossil-doc > p > kbd,
.dir      > .content > .fossil-doc > p > samp,
.dir      > .content > .fossil-doc > p > tt,
.dir      > .content > .fossil-doc > p > var,
.dir      > .content > .markdown   > p > code,
.dir      > .content > .markdown   > p > kbd,
.dir      > .content > .markdown   > p > samp,
.dir      > .content > .markdown   > p > tt,
.dir      > .content > .markdown   > p > var,
.doc      > .content               > p > code,
.doc      > .content               > p > kbd,
.doc      > .content               > p > samp,
.doc      > .content               > p > tt,
.doc      > .content               > p > var,
.doc      > .content > .fossil-doc > p > code,
.doc      > .content > .fossil-doc > p > kbd,
.doc      > .content > .fossil-doc > p > samp,
.doc      > .content > .fossil-doc > p > tt,
.doc      > .content > .fossil-doc > p > var,
.doc      > .content > .markdown   > p > code,
.doc      > .content > .markdown   > p > kbd,
.doc      > .content > .markdown   > p > samp,
.doc      > .content > .markdown   > p > tt,
.doc      > .content > .markdown   > p > var,
.wiki     > .content               > p > code,
.wiki     > .content               > p > kbd,
.wiki     > .content               > p > samp,
.wiki     > .content               > p > tt,
.wiki     > .content               > p > var,
.wiki     > .content > .fossil-doc > p > code,
.wiki     > .content > .fossil-doc > p > kbd,
.wiki     > .content > .fossil-doc > p > samp,
.wiki     > .content > .fossil-doc > p > tt,
.wiki     > .content > .fossil-doc > p > var,
.wiki     > .content > .markdown   > p > code,
.wiki     > .content > .markdown   > p > kbd,
.wiki     > .content > .markdown   > p > samp,
.wiki     > .content > .markdown   > p > tt,
.wiki     > .content > .markdown   > p > var {
  background-color: #eee;
  padding: 0 4px;
}
.content pre {
  hyphens: none;
  line-height: 1.25;
}

.content .pikchr-wrapper {
  /* Pikchr was developed with the assumption that it would be
   * integrated into a Fossil repo using the old 0.9em body font
   * size, which no longer obtians.  This gives us a choice:
   *
   * 1. Change Pikchr to track this skin change, potentially breaking
   *    uses of alternate skins with differing default font sizes.
   * 2. Restore the old default for Pikchr diagrams so the old
   *    assumptions continue to be valid.
   * 3. Make everyone with custom skins set pikchr-scale=1.11 (1/0.9)
   *    in their skin's footer.txt to increase the diagram's relative
   *    size to compensate for the font size change.
   *
   * We choose #2 because it puts both adjustments in the same file. */
  font-size: 0.9em;
}

.content ul li {
  list-style-type: disc;
}

.doc > .content table {
  background-color: #f0f5f9;
  border: 1px solid #a7c2dc;
  border-radius: 0.5em;
  border-spacing: 0;
  padding: 6px;
}
.doc > .content th {
  border-bottom: 1px solid #dee8f2;
  padding-bottom: 4px;
  padding-right: 6px;
  text-align: left;
}
.doc > .content tr > th {
  background-color: #dee8f0;
}
.doc > .content tr:nth-child(odd) {
  background-color: #e0e8ee;
}
.doc > .content td {
  padding-bottom: 4px;
  padding-right: 6px;
  text-align: left;
}

/* Wiki adjustments */
pre.verbatim {
  /* keep code examples from crashing into sidebars, etc. */
  white-space: pre-wrap;  
}
textarea.wikiedit {
  /* Monospace fonts tend to have smaller x-heights; compensate.
   * Can't do this generally because not all fonts have this problem.
   * A textarea stands alone, whereas inline <code> has to work with
   * the browser's choice of sans-serif proportional font. */
  font-size: 1.1em;  
}


/* Tickets */

table.report {
  cursor: auto;
  border-radius: 5px;
  border: 1px solid #ccc;
  border-radius: 0.5em;
  margin: 1em 0;
}
.report td, .report th {
 border: 0;
 font-size: .8em;
 padding: 10px;
}

  white-space: pre-wrap;
}


/* Timeline */

span.timelineDetail {
    font-size: 90%;
  font-size: 90%;
}
div.timelineDate {
    font-weight: bold;
    white-space: nowrap;
  font-weight: bold;
  white-space: nowrap;
}

tr.timelineSelected, tr.timelineCurrent {
  /* etienne/css.txt puts these styles on the whole row. We want them only
   * on the comment/details cell within the table, not over the time
   * and graph columns as well. */
  background-color: unset;
  border: unset;
  box-shadow: unset;
}
tr.timelineCurrent td.timelineModernCell,
tr.timelineCurrent td.timelineColumnarCell {
  border: 1px dashed #446979;
  border-radius: 1em;
}
tr.timelineSelected td.timelineModernCell,
tr.timelineSelected td.timelineColumnarCell {
  background-color: #fbe8d5;
  border-radius: 1em;
}
tr.timelineSecondary td.timelineModernCell,
tr.timelineSecondary td.timelineColumnarCell {
  background-color: #d5e8fb;
}
span.timelineSelected {
  background-color: #fbe8d5;
}
span.timelineSecondary {
  background-color: #d5e8fb;
}


/* Miscellaneous UI elements */

.fossil-tooltip.help-buttonlet-content {
  background-color: lightyellow;
}


/* Exceptions for specific screen sizes */

@media screen and (max-width: 600px) {
  /* Spacing for mobile */
  body {
    padding-left: 4px;
    padding-right: 4px;
  }
  .content {
    font-size: 0.9em;
  }
  .title {
    padding-top: 0px;
    padding-bottom: 0px;
  }
  .title > .page-title {
    display: none;      /* use h1 in body area, below menu bar */
  }
  h1.page-title {
    font-size: 1.60em;  /* match content > h1 */
    margin-bottom: 0;   /* div.content top margin suffices */
  }
  .status {padding-top: 0px;}
  .mainmenu a {
    padding: 8px 10px;
  }
  .mainmenu {
    padding: 10px;
  }
}
@media screen and (min-width: 600px) {
  /* Spacing for desktop */
  body {
    padding-left: 20px;
    padding-right: 20px;
  }
  .title {
    padding-top: 10px;
    padding-bottom: 10px;
  }
  .title h1:after {
    content: " / ";
    color: #777;
    font-weight: normal;
  }
  h1.page-title {
    display: none;  /* use h1 in title area, above menu bar */
  }
  span.page-title {
    font-size: 18px;
  }
  div.logo {
    padding-top: 10px;
  }
  .status {padding-top: 30px;}
  .mainmenu a {
    padding: 8px 20px;
  }
  .mainmenu {
    padding: 10px;
  }
}

  /* Wide screens mean long lines.  Add extra leading to give the eye a
   * "gutter" to follow from the end of one to the start of the next. */
  .content dd,
  .content dt,
  .content div,
  .content li,
  .content p,
  .content table {
    line-height: 1.4em;
  }

  /* This horror show has the same cause that informed our handling of
   * <code> and friends above; see "combinatorial selector explosion."
   * Without this careful targeting, we'd not only overreach into areas
   * of Fossil UI where our meddling is not wanted, we would mistakenly
   * apply double indents to nested formatting in MD forum posts, p
   * within td tags, and more.
   *
   * Rather than give the equivalent Sass code here, see the SCSS file
   * that the [Inskinerator](https://tangentsoft.com/inskinerator/)
   * project ships as override/modern/media.scss.  Rendering that
   * through sassc gives substantially identical output, modulo the
   * hand-polishing we've done here. */
  .artifact > .content               > p,
  .artifact > .content > .markdown   > p,
  .artifact > .content > .fossil-doc > p,
  .artifact > .content               > ol, .artifact > .content               > ul,
  .artifact > .content > .markdown   > ol, .artifact > .content > .markdown   > ul,
  .artifact > .content > .fossil-doc > ol, .artifact > .content > .fossil-doc > ul,
  .artifact > .content               > table,
  .artifact > .content > .markdown   > table,
  .artifact > .content > .fossil-doc > table,
  .dir      > .content               > p,
  .dir      > .content > .markdown   > p,
  .dir      > .content > .fossil-doc > p,
  .dir      > .content               > ol, .dir > .content               > ul,
  .dir      > .content > .markdown   > ol, .dir > .content > .markdown   > ul,
  .dir      > .content > .fossil-doc > ol, .dir > .content > .fossil-doc > ul,
  .dir      > .content               > table,
  .dir      > .content > .markdown   > table,
  .dir      > .content > .fossil-doc > table,
  .doc      > .content               > p,
  .doc      > .content > .markdown   > p,
  .doc      > .content > .fossil-doc > p,
  .doc      > .content               > ol, .doc > .content               > ul,
  .doc      > .content > .markdown   > ol, .doc > .content > .markdown   > ul,
  .doc      > .content > .fossil-doc > ol, .doc > .content > .fossil-doc > ul,
  .doc      > .content               > table,
  .doc      > .content > .markdown   > table,
  .doc      > .content > .fossil-doc > table,
  .wiki     > .content               > p,
  .wiki     > .content > .markdown   > p,
  .wiki     > .content > .fossil-doc > p,
  .wiki     > .content               > ol, .wiki > .content               > ul,
  .wiki     > .content > .markdown   > ol, .wiki > .content > .markdown   > ul,
  .wiki     > .content > .fossil-doc > ol, .wiki > .content > .fossil-doc > ul,
  .wiki     > .content               > table,
  .wiki     > .content > .markdown   > table,
  .wiki     > .content > .fossil-doc > table,
  #fileedit-tab-preview-wrapper > p,
  #fileedit-tab-preview-wrapper > ol,
  #fileedit-tab-preview-wrapper > ul,
  #fileedit-tab-preview-wrapper > table,
  #fileedit-tab-preview-wrapper > .markdown > p,
  #fileedit-tab-preview-wrapper > .markdown > ol,
  #fileedit-tab-preview-wrapper > .markdown > ul,
  #fileedit-tab-preview-wrapper > .markdown > table,
  #wikiedit-tab-preview-wrapper > p,
  #wikiedit-tab-preview-wrapper > ol,
  #wikiedit-tab-preview-wrapper > ul,
  #wikiedit-tab-preview-wrapper > table,
  #wikiedit-tab-preview-wrapper > .markdown > p,
  #wikiedit-tab-preview-wrapper > .markdown > ol,
  #wikiedit-tab-preview-wrapper > .markdown > ul,
  #wikiedit-tab-preview-wrapper > .markdown > table {
    margin-left:  50pt;
    margin-right: 50pt;
  }

  /* Code blocks get extra indenting.  We need a selector explosion
   * equally powerful to the one above for inline <code> fragments and
   * similar elements, for essentially the same reason: Fossil UI also
   * uses <pre>, and we want to affect user content only.
   *
   * The equivalent Sass code is:
   *
   *   .artifact, .dir, .doc, .wiki       // doc types we target
   *     > .content                       // hands off header & footer
   *       @import 'pre-doc-margins.sass'
   *
   *   #fileedit-tab-preview-wrapper,     // include /fileedit previews
   *   #wikiedit-tab-preview-wrapper      // ditto /wikiedit
   *     @import 'pre-doc-margins.sass'
   * 
   * …where pre-doc-margins.sass contains the elements common to both:
   * 
   *   &, > .fossil-doc, > .markdown      // wiki, HTML & MD doc types
   *     > pre                            // direct pre descendants only
   *       margin-left: 70pt;
   *       margin-right: 50pt;
   *
   * This is a technical overreach since /wiki & /wikiedit lack support
   * for Fossil's HTML embedded doc markup capability, but we prefer to
   * draw the /fileedit parallel in our Sass example over the dubious
   * pleasure of being nit-picky on this point.  Instead, we've chosen
   * to back that overreach out by hand below.
   */
  .artifact > .content               > pre,
  .artifact > .content > .fossil-doc > pre,
  .artifact > .content > .markdown   > pre,
  .dir      > .content               > pre,
  .dir      > .content > .fossil-doc > pre,
  .dir      > .content > .markdown   > pre,
  .doc      > .content               > pre,
  .doc      > .content > .fossil-doc > pre,
  .doc      > .content > .markdown   > pre,
  .wiki     > .content               > pre,
  .wiki     > .content > .markdown   > pre {
    margin-left:  70pt;
    margin-right: 50pt;
  }
  #fileedit-tab-preview-wrapper               > pre,
  #wikiedit-tab-preview-wrapper               > pre,
  #fileedit-tab-preview-wrapper > .fossil-doc > pre,
  #fileedit-tab-preview-wrapper > .markdown   > pre,
  #wikiedit-tab-preview-wrapper > .markdown   > pre {
    margin-left:  70pt;
    margin-right: 50pt;
  }

  /* Fossil UI uses these, but in sufficiently constrained ways that we
   * don't have to be nearly as careful to avoid an overreach. */
  .doc > .content h1, .artifact h1, .dir h1, .fileedit h1, .wiki h1 { margin-left: 10pt; }
  .doc > .content h2, .artifact h2, .dir h2, .fileedit h2, .wiki h2 { margin-left: 20pt; }
  .doc > .content h3, .artifact h3, .dir h3, .fileedit h3, .wiki h3 { margin-left: 30pt; }
  .doc > .content h4, .artifact h4, .dir h4, .fileedit h4, .wiki h4 { margin-left: 40pt; }
  .doc > .content h5, .artifact h5, .dir h5, .fileedit h5, .wiki h5 { margin-left: 50pt; }
  .doc > .content hr, .artifact hr, .dir hr, .fileedit hr, .wiki hr { margin-left: 10pt; }

  /* Don't need to be nearly as careful with tags Fossil UI doesn't use. */
  .doc dd, .artifact dd, .dir dd, .fileedit dd, .wikiedit dd { margin-left: 30pt; margin-bottom: 1em; }
  .doc dl, .artifact dl, .dir dl, .fileedit dl, .wikiedit dl { margin-left: 60pt; }
  .doc dt, .artifact dt, .dir dt, .fileedit dt, .wikiedit dt { margin-left: 10pt; }

  /* Fossil UI doesn't use Pikchr at all (yet?) so we can be quite loose
   * with these selectors. */
  .content .pikchr-wrapper { margin-left: 70pt; }
  div.pikchr-wrapper.indent:not(.source) {
    /* Selector naming scheme mismatch is intentional: it must match the
     * way it's given in default.css exactly if it is to override it. */
    margin-left: 70pt;
    margin-right: 50pt;
  }
  div.pikchr-wrapper.center:not(.source) {
    margin-left: 0;
  }

  /* Special treatment for backward compatibility. */
  .indent,                /* clean alternative to misusing <blockquote> */
  .artifact > .content > blockquote:not(.file-content),
  .dir      > .content > blockquote,
  .doc      > .content > blockquote,
  .fileedit > .content > blockquote,
  .wiki     > .content > blockquote {
    /* We must apply extra indent relative to "p" since Fossil's wiki
     * generator misuses the blockquote tag against HTML and MD norms
     * to mean "indented paragraph."  Skip it for file content retrieved
     * by /dir URLs. */
    margin-left: 80pt;
  }
  .artifact > .content > .markdown > blockquote,
  .dir      > .content > .markdown > blockquote,
  .doc      > .content > .markdown > blockquote,
  .fileedit > .content > .markdown > blockquote,
  .wiki     > .content > .markdown > blockquote {
    /* Fossil MD didn't inherit that bug; its HTML generator emits
     * blockquote tags only for _block quotes_!  A moderate indent
     * suffices due to the visual styling applied above. */
    margin-left: 60pt;
  }

  /* Alternative to BLOCK.indent when wrapped in something that is
   * itself indented.  The value is the delta between p and blockquote
   * above, expressed as padding instead of margin so it adds to the
   * outer margin instead of forcing the browser into picking one. */
  .local-indent {
    padding-left: 30pt;
  }
}

<div class="footer">
<footer>
This page was generated in about
<th1>puts [expr {([utime]+[stime]+1000)/1000*0.001}]</th1>s by
Fossil $release_version $manifest_version $manifest_date
</div>
</footer>

<header>
<div class="header">
  <div class="title"><h1>$<project_name></h1>$<title></div>
  <div class="logo">
    <th1>
    ## See skins/original/header.txt for commentary; not repeated here.
    proc getLogoUrl { baseurl } {
      set idx(first) [string first // $baseurl]
      if {$idx(first) != -1} {
        set idx(first+1) [expr {$idx(first) + 2}]
        set idx(nextRange) [string range $baseurl $idx(first+1) end]
        set idx(next) [string first / $idx(nextRange)]
        if {$idx(next) != -1} {
          set idx(next) [expr {$idx(next) + $idx(first+1)}]
          set idx(next-1) [expr {$idx(next) - 1}]
          set scheme [string range $baseurl 0 $idx(first)]
          set host [string range $baseurl $idx(first+1) $idx(next-1)]
          if {[string compare $scheme http:/] == 0} {
            set scheme http://
          } else {
            set scheme https://
          }
          set logourl $scheme$host/
        } else {
          set logourl $baseurl
        }
      } else {
        set logourl $baseurl
      }
      return $logourl
    }
    set logourl [getLogoUrl $baseurl]
    </th1>
    <a href="$logourl">
      <img src="$logo_image_url" border="0" alt="$project_name">
    </a>
  </div>
  <div class="title">
    <h1>$<project_name></h1>
    <span class="page-title">$<title></span>
  </div>
    <div class="status"><th1>
 if {[info exists login]} {
   html "<a href='$home/login'>$login</a>\n"
 } else {
   html "<a href='$home/login'>Login</a>\n"
 }
    </th1></div>
</div>
<div class="mainmenu">
</header>
<nav class="mainmenu" title="Main Menu">
<th1>
html "<a id='hbbtn' href='$home/sitemap' aria-label='Site Map'>&#9776;</a>"
builtin_request_js hbmenu.js
foreach {name url expr class} $mainmenu {
  if {![capexpr $expr]} continue
  if {[string match /* $url]} {
    if {[string match $url\[/?#\]* /$current_page/]} {
      set class "active $class"
    }
    set url $home$url
  }
  html "<a href='$url' class='$class'>$name</a>\n"
}
</th1></div>
<div id='hbdrop'></div>
</th1></nav>
<nav id="hbdrop" title="sitemap"></nav>
<h1 class="page-title">$<title></h1>

This skin was contributed by Étienne Deparis.

It was promoted to the default from 2015-03-14 until February 2024, when
it was forked into this location for use by those who do not want the
large number of changes merged into trunk at that time.  Even if you
agree with us that the changes improve readability, you may prefer to
pack more information onto the screen at the expense of readability.
Other reasons to choose this fork are to migrate custom skin changes to
work atop the new base, or to make a comparative design evaluation.

A bare minimum of changes have been made to this fork, primarily to
allow this skin to render the Fossil documentation in a readable
fashion. The intent is that you be able to toggle between these two
skins at will.

/* Overall page style; vi: filetype=css
 */

body {
  margin: 0 auto;
  background-color: white;
  font-family: sans-serif;
  font-size: 14pt;
}

a {
  color: #4183C4;
  text-decoration: none;
}
a:hover {
  color: #4183C4;
  text-decoration: underline;
}


/* Page title, above menu bars */

.title {
  color: #4183C4;
  float: left;
}
.title h1 {
  display: inline;
}
.title h1:after {
  content: " / ";
  color: #777;
  font-weight: normal;
}
.status {
  float: right;
  font-size: 0.7em;
}


/* Main menu and optional sub-menu */

.mainmenu {
  font-size: 0.8em;
  clear: both;
  background: #eaeaea linear-gradient(#fafafa, #eaeaea) repeat-x;
  border: 1px solid #eaeaea;
  border-radius: 5px;
  overflow-x: auto;
  overflow-y: hidden;
  white-space: nowrap;
  z-index: 21;  /* just above hbdrop */
}
.mainmenu a {
  text-decoration: none;
  color: #777;
  border-right: 1px solid #eaeaea;
}
.mainmenu a.active,
.mainmenu a:hover {
  color: #000;
  border-bottom: 2px solid #D26911;
}
div#hbdrop {
  background-color: white;
  border: 1px solid black;
  border-top: white;
  border-radius: 0 0 0.5em 0.5em;
  display: none;
  font-size: 80%;
  left: 2em;
  width: 90%;
  padding-right: 1em;
  position: absolute;
  z-index: 20;  /* just below mainmenu, but above timeline bubbles */
}

.submenu {
  font-size: .7em;
  padding: 10px;
  border-bottom: 1px solid #ccc;
}
.submenu a, .submenu label {
  padding: 10px 11px;
  text-decoration: none;
  color: #777;
}
.submenu label {
  white-space: nowrap;
}
.submenu a:hover, .submenu label:hover {
  padding: 6px 10px;
  border: 1px solid #ccc;
  border-radius: 5px;
  color: #000;
}
span.submenuctrl, span.submenuctrl input, select.submenuctrl {
  color: #777;
}
span.submenuctrl {
  white-space: nowrap;
}


/* Main document area; elements common to most pages. */

.content {
  padding-top: 10px;
  font-size: 0.8em;
  color: #444;
}
.content blockquote {
  padding: 0 15px;
}
.content h1 {
  font-size: 1.25em;
}
.content h2 {
  font-size: 1.15em;
}
.content h3 {
  font-size: 1.05em;
}

.section {
  font-size: 1em;
  font-weight: bold;
  background-color: #f5f5f5;
  border: 1px solid #d8d8d8;
  border-radius: 3px 3px 0 0;
  padding: 9px 10px 10px;
  margin: 10px 0;
}
.sectionmenu {
  border: 1px solid #d8d8d8;
  border-radius: 0 0 3px 3px;
  border-top: 0;
  margin-top: -10px;
  margin-bottom: 10px;
  padding: 10px;
}
.sectionmenu a {
  display: inline-block;
  margin-right: 1em;
}

hr {
  color: #eee;
}


/* Page footer */

.footer {
  border-top: 1px solid #ccc;
  padding: 10px;
  font-size: 0.7em;
  margin-top: 10px;
  color: #ccc;
}

/* Forum */

.forum a:visited {
  color: #6A7F94;
}

.forum blockquote {
  background-color: rgba(65, 131, 196, 0.1);
  border-left: 3px solid #254769;
  padding: .1em 1em;
}


/* Markdown and Wiki-formatted pages: /wiki, /doc, /file... */

.doc > .content table {
  background-color: rgba(0, 0, 0, 0.05);
  border: 1px solid #aaa;
  border-radius: 0.5em;
  border-spacing: 0;
  padding: 6px;
}
.doc > .content th {
  border-bottom: 1px solid #ddd;
  padding-bottom: 4px;
  padding-right: 6px;
  text-align: left;
}
.doc > .content tr > th {
  background-color: #eee;
}
.doc > .content tr:nth-child(odd) {
  background-color: #e8e8e8;
}
.doc > .content td {
  padding-bottom: 4px;
  padding-right: 6px;
  text-align: left;
}


/* Tickets */

table.report {
  cursor: auto;
  border-radius: 5px;
  border: 1px solid #ccc;
  margin: 1em 0;
}
.report td, .report th {
 border: 0;
 font-size: .8em;
 padding: 10px;
}
.report td:first-child {
  border-top-left-radius: 5px;
}
.report tbody tr:last-child td:first-child {
  border-bottom-left-radius: 5px;
}
.report td:last-child {
  border-top-right-radius: 5px;
}
.report tbody tr:last-child {
  border-bottom-left-radius: 5px;
  border-bottom-right-radius: 5px;
}
.report tbody tr:last-child td:last-child {
  border-bottom-right-radius: 5px;
}
.report th {
  cursor: pointer;
}
.report thead+tbody tr:hover {
  background-color: #f5f9fc !important;
}

td.tktDspLabel {
  width: 70px;
  text-align: right;
  overflow: hidden;
}
td.tktDspValue {
  text-align: left;
  vertical-align: top;
  background-color: #f8f8f8;
  border: 1px solid #ccc;
}
td.tktDspValue pre {
  white-space: pre-wrap;
}


/* Timeline */

span.timelineDetail {
  font-size: 90%;
}
div.timelineDate {
  font-weight: bold;
  white-space: nowrap;
}


/* Miscellaneous UI elements */

.fossil-tooltip.help-buttonlet-content {
  background-color: lightyellow;
}


/* Exceptions for specific screen sizes */

@media screen and (max-width: 600px) {
  /* Spacing for mobile */
  body {
    padding-left: 4px;
    padding-right: 4px;
  }
  .title {
    padding-top: 0px;
    padding-bottom: 0px;
  }
  .status {padding-top: 0px;}
  .mainmenu a {
    padding: 8px 10px;
  }
  .mainmenu {
    padding: 10px;
  }
}
@media screen and (min-width: 600px) {
  /* Spacing for desktop */
  body {
    padding-left: 20px;
    padding-right: 20px;
  }
  .title {
    padding-top: 10px;
    padding-bottom: 10px;
  }
  .status {padding-top: 30px;}
  .mainmenu a {
    padding: 8px 20px;
  }
  .mainmenu {
    padding: 10px;
  }
}

timeline-arrowheads:        1
timeline-circle-nodes:      1
timeline-color-graph-lines: 1
white-foreground:           0

<div class="footer">
This page was generated in about
<th1>puts [expr {([utime]+[stime]+1000)/1000*0.001}]</th1>s by
Fossil $release_version $manifest_version $manifest_date
</div>

<div class="header">
  <div class="title"><h1>$<project_name></h1>$<title></div>
    <div class="status"><th1>
 if {[info exists login]} {
   html "<a href='$home/login'>$login</a>\n"
 } else {
   html "<a href='$home/login'>Login</a>\n"
 }
    </th1></div>
</div>
<div class="mainmenu">
<th1>
html "<a id='hbbtn' href='$home/sitemap' aria-label='Site Map'>&#9776;</a>"
builtin_request_js hbmenu.js
foreach {name url expr class} $mainmenu {
  if {![capexpr $expr]} continue
  if {[string match /* $url]} {
    if {[string match $url\[/?#\]* /$current_page/]} {
      set class "active $class"
    }
    set url $home$url
  }
  html "<a href='$url' class='$class'>$name</a>\n"
}
</th1></div>
<div id='hbdrop'></div>

  padding: 0;
  width: 125px;
  text-align: center;
  border-collapse: collapse;
  border-spacing: 0;
}
table.report {
  border-collapse:collapse;
  border: 1px solid #999;
  margin: 1em 0 1em 0;
  cursor: pointer;
}
td.rpteditex {
  border-width: thin;
  border-color: #000000;

  line-height: 1.275/*for mobile: forum post e6f4ee7de98b55c0*/;
  text-size-adjust: none
  /* ^^^ attempt to keep mobile from inflating some text */;
}
table.diff pre > ins,
table.diff pre > del {
  /* Fill platform-dependent color gaps caused by
     inflated line-height */;
     inflated line-height */
  padding: 0.062em 0 0.062em 0;
}
table.diff pre > ins > *,
table.diff pre > del > *{
  /* Avoid odd-looking color swatches in conjunction with
     (table.diff pre > ins/del) padding */
  padding: inherit;

}
tr.diffskip.jchunk:hover {
  /*background-color: rgba(127,127,127,0.5);
  cursor: pointer;*/
}
tr.diffskip > td.chunkctrl {
  text-align: left;
  font-family: monospace;
}
tr.diffskip > td.chunkctrl > div {
  display: flex;
  align-items: center;
}
tr.diffskip > td.chunkctrl > div > span.error {
  padding: 0.25em 0.5em;

  margin: 0;
}
.flex-container.child-gap-small > * {
  margin: 0.25em;
}
#fossil-status-bar {
  display: block;
  font-family: monospace;
  border-width: 1px;
  border-style: inset;
  border-color: inherit;
  min-height: 1.5em;
  font-size: 1.2em;
  padding: 0.2em;
  margin: 0.25em 0;

table.numbered-lines {
  width: 100%;
  table-layout: fixed /* required to keep ultra-wide code from exceeding
                         window width, and instead force a scrollbar
                         on them. */;
}
table.numbered-lines > tbody > tr {
  font-family: monospace;
  line-height: 1.35;
  white-space: pre;
}
table.numbered-lines > tbody > tr > td {
  font-family: inherit;
  font-size: inherit;
  line-height: inherit;

  color: black;
}

blockquote.file-content {
  /* file content block in the /file page */
  margin: 0 1em;
}

/* Generic sidebar styling inherited by skins that don't make their own
 * arrangements. */
.markdown blockquote, p.blockquote, .sidebar {
  background-color: rgba(0, 0, 0, 0.05);
  border-left: 3px solid #777;
  padding: 0.1em 1em;
}
.sidebar {
  font-size: 90%;
}
.sidebar {
  /* Generic form that can be applied to any block element. */
  font-size: 0.9em;
}
div.sidebar {
  /* Special exception for div-type sidebars, where there is no p
   * wrapper inside to give us the extra padding we want. */
  padding: 1em;
}
div.sidebar:not(.no-label):before {
  content: "Sidebar: ";
  font-weight: bold;
}


/**
   Circular "help" buttons intended to be placed to the right of
   another element and hold text text for it. These typically get
   initialized automatically at page startup via
   fossil.popupwidget.js, and can be manually initialized/created

body.branch .submenu > a.timeline-link {
  display: none;
}
body.branch .submenu > a.timeline-link.selected {
  display: inline;
}

/* Candidate fonts for various forms of monospaced text. Collected here
 * to avoid repeating this long list of fonts. */
code, kbd, pre, samp, tt, var,
    div.markdown ol.footnotes > li.fn-joined > sup.fn-joined,
    table.numbered-lines > tbody > tr,
    tr.diffskip > td.chunkctrl,
    #fossil-status-bar,
.monospace {
  font-family: monospace;
    .monospace {
  font-family: Source Code Pro, Menlo, Monaco, Consolas,
               Andale Mono, Ubuntu Mono, Deja Vu Sans Mono,
               Letter Gothic, Letter Gothic Std, Prestige Elite Std,
               Courier, Courier New,
               monospace;
}

div.markdown > ol.footnotes {
  font-size: 90%;
}
div.markdown > ol.footnotes > li {
  margin-bottom: 0.5em;
}
div.markdown ol.footnotes > li.fn-joined > sup.fn-joined {
  color: gray;
  font-family: monospace;
}
div.markdown ol.footnotes > li.fn-joined > sup.fn-joined::after {
  content: "(joined from multiple locations) ";
}
div.markdown ol.footnotes > li.fn-misreference {
  margin-top:    0.75em;
  margin-bottom: 0.75em;

}

/* Objects in the "desktoponly" class are invisible on mobile */
@media screen and (max-width: 600px) {
  .desktoponly {
    display: none;
  }
}
/* Float sidebars to the right of the main content only if there's room. */
@media screen and (min-width: 600px) {
  .sidebar {
    float: right;
    max-width: 33%;
    margin-left: 1em;
  }
}
/* Objects in the "wideonly" class are invisible only on wide-screen desktops */
@media screen and (max-width: 1200px) {
  .wideonly {
    display: none;
  }
}

**
** This was original the "js.txt" file for the default skin.  It was subsequently
** moved into src/hbmenu.js so that it could be more easily reused by other skins
** using the "builtin_request_js" TH1 command.
**
** Operation:
**
** This script request that the HTML contain two elements:
** This script expects the HTML to contain two elements:
**
**      <a id="hbbtn">       <--- The hamburger menu button
**      <div id="hbdrop">    <--- Container for the hamburger menu
**      <nav id="hbdrop">    <--- Container for the hamburger menu
**      
** Bindings are made on hbbtn so that when it is clicked, the following
** happens:
**
**    1.  An XHR is made to /sitemap?popup to fetch the HTML for the
**        popup menu.
**

  $(SRCDIR)/../skins/default/details.txt \
  $(SRCDIR)/../skins/default/footer.txt \
  $(SRCDIR)/../skins/default/header.txt \
  $(SRCDIR)/../skins/eagle/css.txt \
  $(SRCDIR)/../skins/eagle/details.txt \
  $(SRCDIR)/../skins/eagle/footer.txt \
  $(SRCDIR)/../skins/eagle/header.txt \
  $(SRCDIR)/../skins/etienne/css.txt \
  $(SRCDIR)/../skins/etienne/details.txt \
  $(SRCDIR)/../skins/etienne/footer.txt \
  $(SRCDIR)/../skins/etienne/header.txt \
  $(SRCDIR)/../skins/khaki/css.txt \
  $(SRCDIR)/../skins/khaki/details.txt \
  $(SRCDIR)/../skins/khaki/footer.txt \
  $(SRCDIR)/../skins/khaki/header.txt \
  $(SRCDIR)/../skins/original/css.txt \
  $(SRCDIR)/../skins/original/details.txt \
  $(SRCDIR)/../skins/original/footer.txt \

	$(XTCC) $(PIKCHR_OPTIONS) -c $(SRCDIR_extsrc)/pikchr.c -o $@

$(OBJDIR)/cson_amalgamation.o: $(SRCDIR_extsrc)/cson_amalgamation.c
	$(XTCC) -c $(SRCDIR_extsrc)/cson_amalgamation.c -o $@

$(SRCDIR_extsrc)/pikchr.js: $(SRCDIR_extsrc)/pikchr.c
	$(EMCC_WRAPPER) -o $@ $(EMCC_OPT) --no-entry \
        -sEXPORTED_RUNTIME_METHODS=cwrap,setValue,getValue,stackSave,stackRestore,stackAlloc \
        -sEXPORTED_RUNTIME_METHODS=cwrap,setValue,getValue,stackSave,stackRestore \
        -sEXPORTED_FUNCTIONS=_pikchr $(SRCDIR_extsrc)/pikchr.c \
        -sENVIRONMENT=web \
        -sMODULARIZE \
        -sEXPORT_NAME=initPikchrModule \
        --minify 0
	@chmod -x $(SRCDIR_extsrc)/pikchr.wasm
wasm: $(SRCDIR_extsrc)/pikchr.js

} aBuiltinSkin[] = {
  { "Default",                           "default",           0 },
  { "Ardoise",                           "ardoise",           0 },
  { "Black & White",                     "black_and_white",   0 },
  { "Blitz",                             "blitz",             0 },
  { "Dark Mode",                         "darkmode",          0 },
  { "Eagle",                             "eagle",             0 },
  { "Étienne",                           "etienne",           0 },
  { "Khaki",                             "khaki",             0 },
  { "Original",                          "original",          0 },
  { "Plain Gray",                        "plain_gray",        0 },
  { "Xekri",                             "xekri",             0 },
};

/*

        }else
        if( markup.iType==MUTYPE_TD ){
          if( backupToType(p, MUTYPE_TABLE|MUTYPE_TR) ){
            if( stackTopType(p)==MUTYPE_TABLE ){
              pushStack(p, MARKUP_TR);
              blob_append_string(p->pOut, "<tr>");
            }
            p->wantAutoParagraph = 0;
            pushStack(p, markup.iCode);
            renderMarkup(p->pOut, &markup);
          }
        }else
        if( markup.iType==MUTYPE_HYPERLINK ){
          if( !isButtonHyperlink(p, &markup, z, &n) ){
            popStackToTag(p, markup.iCode);

<li><p>
Shift-click on each of the links in [./fileage-test-1.wiki] and verify
correct operation of the file-age computation.

<li><p>
Verify correct name-change tracking behavior (no net changes) for:
<blockquote><b>
fossil test-name-changes --debug  b120bc8b262ac 374920b20944b
</b></blockquote>
<pre><b>fossil test-name-changes --debug  b120bc8b262ac 374920b20944b
</b></pre>

<li><p>
Compile for all of the following platforms:
<ol type="a">
<li> Linux x86
<li> Linux x86_64
<li> Mac x86

  $(SRCDIR)/../skins/default/details.txt \
  $(SRCDIR)/../skins/default/footer.txt \
  $(SRCDIR)/../skins/default/header.txt \
  $(SRCDIR)/../skins/eagle/css.txt \
  $(SRCDIR)/../skins/eagle/details.txt \
  $(SRCDIR)/../skins/eagle/footer.txt \
  $(SRCDIR)/../skins/eagle/header.txt \
  $(SRCDIR)/../skins/etienne/css.txt \
  $(SRCDIR)/../skins/etienne/details.txt \
  $(SRCDIR)/../skins/etienne/footer.txt \
  $(SRCDIR)/../skins/etienne/header.txt \
  $(SRCDIR)/../skins/khaki/css.txt \
  $(SRCDIR)/../skins/khaki/details.txt \
  $(SRCDIR)/../skins/khaki/footer.txt \
  $(SRCDIR)/../skins/khaki/header.txt \
  $(SRCDIR)/../skins/original/css.txt \
  $(SRCDIR)/../skins/original/details.txt \
  $(SRCDIR)/../skins/original/footer.txt \

        "$(SRCDIR)\..\skins\default\details.txt" \
        "$(SRCDIR)\..\skins\default\footer.txt" \
        "$(SRCDIR)\..\skins\default\header.txt" \
        "$(SRCDIR)\..\skins\eagle\css.txt" \
        "$(SRCDIR)\..\skins\eagle\details.txt" \
        "$(SRCDIR)\..\skins\eagle\footer.txt" \
        "$(SRCDIR)\..\skins\eagle\header.txt" \
        "$(SRCDIR)\..\skins\etienne\css.txt" \
        "$(SRCDIR)\..\skins\etienne\details.txt" \
        "$(SRCDIR)\..\skins\etienne\footer.txt" \
        "$(SRCDIR)\..\skins\etienne\header.txt" \
        "$(SRCDIR)\..\skins\khaki\css.txt" \
        "$(SRCDIR)\..\skins\khaki\details.txt" \
        "$(SRCDIR)\..\skins\khaki\footer.txt" \
        "$(SRCDIR)\..\skins\khaki\header.txt" \
        "$(SRCDIR)\..\skins\original\css.txt" \
        "$(SRCDIR)\..\skins\original\details.txt" \
        "$(SRCDIR)\..\skins\original\footer.txt" \

	echo "$(SRCDIR)\../skins/default/details.txt" >> $@
	echo "$(SRCDIR)\../skins/default/footer.txt" >> $@
	echo "$(SRCDIR)\../skins/default/header.txt" >> $@
	echo "$(SRCDIR)\../skins/eagle/css.txt" >> $@
	echo "$(SRCDIR)\../skins/eagle/details.txt" >> $@
	echo "$(SRCDIR)\../skins/eagle/footer.txt" >> $@
	echo "$(SRCDIR)\../skins/eagle/header.txt" >> $@
	echo "$(SRCDIR)\../skins/etienne/css.txt" >> $@
	echo "$(SRCDIR)\../skins/etienne/details.txt" >> $@
	echo "$(SRCDIR)\../skins/etienne/footer.txt" >> $@
	echo "$(SRCDIR)\../skins/etienne/header.txt" >> $@
	echo "$(SRCDIR)\../skins/khaki/css.txt" >> $@
	echo "$(SRCDIR)\../skins/khaki/details.txt" >> $@
	echo "$(SRCDIR)\../skins/khaki/footer.txt" >> $@
	echo "$(SRCDIR)\../skins/khaki/header.txt" >> $@
	echo "$(SRCDIR)\../skins/original/css.txt" >> $@
	echo "$(SRCDIR)\../skins/original/details.txt" >> $@
	echo "$(SRCDIR)\../skins/original/footer.txt" >> $@

<title>How CGI Works In Fossil</title>

<h2>Introduction</h2><blockquote>
<h2>Introduction</h2>

CGI or "Common Gateway Interface" is a venerable yet reliable technique for
generating dynamic web content.  This article gives a quick background on how
CGI works and describes how Fossil can act as a CGI service.

This is a "how it works" guide.  This document provides background
information on the CGI protocol so that you can better understand what
is going on behind the scenes.  If you just want to set up Fossil
as a CGI server, see the [./server/ | Fossil Server Setup] page.  Or
if you want to development CGI-based extensions to Fossil, see
the [./serverext.wiki|CGI Server Extensions] page.
</blockquote>
<h2>A Quick Review Of CGI</h2><blockquote>

<h2>A Quick Review Of CGI</h2>

An HTTP request is a block of text that is sent by a client application
(usually a web browser) and arrives at the web server over a network
connection.  The HTTP request contains a URL that describes the information
being requested.  The URL in the HTTP request is typically the same URL
that appears in the URL bar at the top of the web browser that is making
the request.  The URL might contain a "?" character followed
query parameters.  The HTTP will usually also contain other information
such as the name of the application that made the request, whether or
not the requesting application can accept a compressed reply, POST
parameters from forms, and so forth.

The job of the web server is to interpret the HTTP request and formulate
an appropriate reply.
The web server is free to interpret the HTTP request in any way it wants.
But most web servers follow a similar pattern, described below.
(Note: details may vary from one web server to another.)

Suppose the filename component of the URL in the HTTP request looks like this:

<blockquote><b>/one/two/timeline/four</b></blockquote>
<pre>/one/two/timeline/four</pre>

Most web servers will search their content area for files that match
some prefix of the URL.  The search starts with <b>/one</b>, then goes to
<b>/one/two</b>, then <b>/one/two/timeline</b>, and finally
<b>/one/two/timeline/four</b> is checked.  The search stops at the first
match.

Suppose the first match is <b>/one/two</b>.  If <b>/one/two</b> is an
ordinary file in the content area, then that file is returned as static
content.  The "<b>/timeline/four</b>" suffix is silently ignored.

If <b>/one/two</b> is a CGI script (or program), then the web server
executes the <b>/one/two</b> script.  The output generated by
the script is collected and repackaged as the HTTP reply.

Before executing the CGI script, the web server will set up various
environment variables with information useful to the CGI script:
<table border=1 cellpadding=5>
<tr><th>Environment<br>Variable<th>Meaning
<table>
<tr><th>Variable<th>Meaning
<tr><td>GATEWAY_INTERFACE<td>Always set to "CGI/1.0"
<tr><td>REQUEST_URI
    <td>The input URL from the HTTP request.
<tr><td>SCRIPT_NAME
    <td>The prefix of the input URL that matches the CGI script name.
    In this example: "/one/two".
<tr><td>PATH_INFO

The CGI script exits as soon as it generates a single reply.
The web server will (usually) persist and handle multiple HTTP requests,
but a CGI script handles just one HTTP request and then exits.

The above is a rough outline of how CGI works.
There are many details omitted from this brief discussion.
See other on-line CGI tutorials for further information.
</blockquote>

<h2>How Fossil Acts As A CGI Program</h2>
<blockquote>

An appropriate CGI script for running Fossil will look something
like the following:

<blockquote><pre>
<pre>
#!/usr/bin/fossil
repository: /home/www/repos/project.fossil
</pre></blockquote>
</pre>

The first line of the script is a
"[https://en.wikipedia.org/wiki/Shebang_%28Unix%29|shebang]"
that tells the operating system what program to use as the interpreter
for this script.  On unix, when you execute a script that starts with
a shebang, the operating system runs the program identified by the
shebang with a single argument that is the full pathname of the script
itself.

With Fossil, terms of PATH_INFO beyond the webpage name are converted into
the "name" query parameter.  Hence, the following two URLs mean
exactly the same thing to Fossil:
<ol type='A'>
<li> [https://fossil-scm.org/home/info/c14ecc43]
<li> [https://fossil-scm.org/home/info?name=c14ecc43]
</ol>

In both cases, the CGI script is called "/fossil".  For case (A),
the PATH_INFO variable will be "info/c14ecc43" and so the
"[/help?cmd=/info|/info]" webpage will be generated and the suffix of
PATH_INFO will be converted into the "name" query parameter, which
identifies the artifact about which information is requested.
In case (B), the PATH_INFO is just "info", but the same "name"
query parameter is set explicitly by the URL itself.
</blockquote>

<h2>Serving Multiple Fossil Repositories From One CGI Script</h2>
<blockquote>

The previous example showed how to serve a single Fossil repository
using a single CGI script.
On a website that wants to serve multiple repositories, one could
simply create multiple CGI scripts, one script for each repository.
But it is also possible to serve multiple Fossil repositories from
a single CGI script.

If the CGI script for Fossil contains a "directory:" line instead of
a "repository:" line, then the argument to "directory:" is the name
of a directory that contains multiple repository files, each ending
with ".fossil".  For example:

<blockquote><pre>
<pre>
#!/usr/bin/fossil
directory: /home/www/repos
</pre></blockquote>
</pre>

Suppose the /home/www/repos directory contains files named
<b>one.fossil</b>, <b>two.fossil</b>, and <b>subdir/three.fossil</b>.
Further suppose that the name of the CGI script (relative to the root
of the webserver document area) is "cgis/example2".  Then to
see the timeline for the "three.fossil" repository, the URL would be:
<blockquote>
<b>http://example.com/cgis/example2/subdir/three/timeline</b>
</blockquote>

<pre>
http://example.com/cgis/example2/subdir/three/timeline
</pre>

Here is what happens:
<ol>
<li> The input URI on the HTTP request is
     <b>/cgis/example2/subdir/three/timeline</b>
<li> The web server searches prefixes of the input URI until it finds
     the "cgis/example2" script.  The web server then sets
     PATH_INFO to the "subdir/three/timeline" suffix and invokes the
     "cgis/example2" script.
<li> Fossil runs and sees the "directory:" line pointing to
     "/home/www/repos".  Fossil then starts pulling terms off the
     front of the PATH_INFO looking for a repository.  It first looks
     at "/home/www/resps/subdir.fossil" but there is no such repository.
     So then it looks at "/home/www/repos/subdir/three.fossil" and finds
     a repository.  The PATH_INFO is shortened by removing
     "subdir/three/" leaving it at just "timeline".
<li> Fossil looks at the rest of PATH_INFO to see that the webpage
     requested is "timeline".
</ol>
<a id="cgivar"></a>

The web server sets many environment variables in step 2 in addition
to just PATH_INFO.  The following diagram shows a few of these variables
and their relationship to the request URL:

<pre>
                                       REQUEST_URI
                         ___________________|_______________________
                        /                                           \
      http://example.com/cgis/example2/subdir/three/timeline?c=55d7e1
             \_________/\____________/\____________________/ \______/
                  |            |                 |               |
              HTTP_HOST   SCRIPT_NAME        PATH_INFO      QUERY_STRING
</pre>
</blockquote>

<h2>Additional CGI Script Options</h2>
<blockquote>

The CGI script can have additional options used to fine-tune
Fossil's behavior.  See the [./cgi.wiki|CGI script documentation]
for details.

</blockquote>
<h2>Additional Observations</h2>
<blockquote><ol type="I">
<ol type="I">
<li><p>
Fossil does not distinguish between the various HTTP methods (GET, PUT,
DELETE, etc).  Fossil figures out what it needs to do purely from the
webpage term of the URI.</p></li>
<li><p>
Fossil does not distinguish between query parameters that are part of the
URI, application/x-www-form-urlencoded or multipart/form-data encoded

converted into CGI, then Fossil creates a separate child Fossil
process to handle each CGI request.</p></li>
<li><p>
Fossil is itself often launched using CGI.  But Fossil can also then
turn around and launch [./serverext.wiki|sub-CGI scripts to implement
extensions].</p></li>
</ol>
</blockquote>

<title>How The Fossil Download Page Works</title>
<h1 align="center">How The Download Page Works</h1>

<h2>1.0 Overview</h2>

The [/uv/download.html|Download] page for the Fossil self-hosting
repository is implemented using [./unvers.wiki|unversioned files].
The "download.html" screen itself, and the various build products
are all stored as unversioned content.  The download.html page

your system already, they are easy to install.  A popular choice is the
[http://www.activestate.com/activetcl|Active Tcl] installation from
ActiveState.

After the makefiles have been updated, create the xyzzy.c source file
from the following template:

<blockquote><verbatim>
<verbatim>
/*
** Copyright boilerplate goes here.
*****************************************************
** High-level description of what this module goes
** here.
*/
#include "config.h"
#include "xyzzy.h"

#if INTERFACE
/* Exported object (structure) definitions or #defines
** go here */
#endif /* INTERFACE */

/* New code goes here */
</verbatim></blockquote>
</verbatim>

Note in particular the <b>#include "xyzzy.h"</b> line near the top.
The "xyzzy.h" file is automatically generated by makeheaders.  Every
normal Fossil source file must have a #include at the top that imports
its private header file.  (Some source files, such as "sqlite3.c" are
exceptions to this rule.  Don't worry about those exceptions.  The
files you write will require this #include line.)

    <b>fossil diff xyzzy.c</b>

The "command" is "diff".  Commands may optionally be followed by
arguments and/or options.  To create new commands in Fossil, add code
(either to an existing source file, or to a new source file created as
described above) according to the following template:

<blockquote><verbatim>
<verbatim>
/*
** COMMAND: xyzzy
**
** Help text goes here.  Backslashes must be escaped.
*/
void xyzzy_cmd(void){
  /* Implement the command here */
  fossil_print("Hello, World!\n");
}
</verbatim></blockquote>
</verbatim>

The example above creates a new command named "xyzzy" that prints the
message "Hello, World!" on the console.  This command is a normal command
that will show up in the list of command from [/help/help|fossil help].
If you add an asterisk to the end of the command name, like this:

<blockquote><verbatim>
<verbatim>
** COMMAND: xyzzy*
</verbatim></blockquote>
</verbatim>

Then the command will only show up if you add the "--all" option to
[/help/help|fossil help].  Or, if the command name starts with
"test" then the command will be considered experimental and will only
show up when the --test option is used with [/help/help|fossil help].

The example above is a fully functioning Fossil command.  You can add

<h2 id="newpage">5.0 Creating A New Web Page</h2>

As with commands, new webpages can be added simply by inserting a function
that generates the webpage together with a special header comment.  A
template follows:

<blockquote><verbatim>
<verbatim>
/*
** WEBPAGE: helloworld
*/
void helloworld_page(void){
  style_header("Hello World!");
  @ <p>Hello, World!</p>
  style_footer();
}
</verbatim></blockquote>
</verbatim>

Add the code above to a new or existing Fossil source code file, then
recompile fossil and run [/help/ui|fossil ui] then enter
"http://localhost:8080/helloworld" in your web browser and the routine
above will generate a web page that says "Hello World."
It really is that simple.

    the "From" address above, or it could be a different value like
    `admin@example.com`.

Save your changes.

At the command line, say

      $ fossil set email-send-command
    $ fossil set email-send-command

If that gives a blank value instead of `sendmail -ti`, say

      $ fossil set email-send-command "sendmail -ti"
    $ fossil set email-send-command "sendmail -ti"

to force the setting. That works around a [known
bug](https://fossil-scm.org/forum/forumpost/840b676410) which may be
squished by the time you read this.

If you're running Postfix or Exim, you might think that command is
wrong, since you aren't running Sendmail. These mail servers provide a
`sendmail` command for compatibility with software like Fossil that has
no good reason to care exactly which SMTP server implementation is
running at a given site. There may be other SMTP servers that also
provide a compatible `sendmail` command, in which case they may work
with Fossil using the same steps as above.

<a id="status"></a>
If you reload the Admin → Notification page, the Status section at the
top should show:

      Outgoing Email: Piped to command "sendmail -ti"
      Pending Alerts: 0 normal, 0 digest
      Subscribers:    0 active, 0 total
    Outgoing Email: Piped to command "sendmail -ti"
    Pending Alerts: 0 normal, 0 digest
    Subscribers:    0 active, 0 total

Before you move on to the next section, you might like to read up on
[some subtleties](#pipe) with the "pipe to a command" method that we did
not cover above.


<a id="usage"></a>

by the way: a user can be signed up for email alerts without having a
full-fledged Fossil user account. Only when both user names are the same
are the two records tied together under the hood. For more on this, see
[Users vs Subscribers below](#uvs).

If you are seeing the following complaint from Fossil:

<blockquote>
  Use a different login with greater privilege than FOO to access
> Use a different login with greater privilege than FOO to access /subscribe
  /subscribe
</blockquote>

...then the repository's administrator forgot to give the
[**EmailAlert** capability][cap7]
to that user or to a user category that the user is a member of.

After a subscriber signs up for alerts for the first time, a single
verification email is sent to that subscriber's given email address.

Announcement](/announce)" link at the top of the "Email Notification
Setup" page.  Put your email address in the "To:" line and a test
message below, then press "Send Message" to verify that outgoing email
is working.

Another method is from the command line:

      $ fossil alerts test-message you@example.com --body README.md --subject Test
    $ fossil alerts test-message you@example.com --body README.md --subject Test

That should send you an email with "Test" in the subject line and the
contents of your project's `README.md` file in the body.

That command assumes that your project contains a "readme" file, but of
course it does, because you have followed the [Programming Style Guide
Checklist][cl], right? Right.

### Troubleshooting

If email alerts aren't working, there are several useful commands you
can give to figure out why.

(Be sure to [`cd` into a repo checkout directory](#cd) first!)

      $ fossil alerts status
    $ fossil alerts status

This should give much the same information as you saw [above](#status).
One difference is that, since you've created a forum post, the
`pending-alerts` value should only be zero if you did in fact get the
requested email alert. If it's zero, check your mailer's spam folder. If
it's nonzero, continue with these troubleshooting steps.

      $ fossil backoffice
    $ fossil backoffice

That forces Fossil to run its ["back office" process](./backoffice.md).
Its only purpose at the time of this writing is to push out alert
emails, but it might do other things later. Sometimes it can get stuck
and needs to be kicked. For that reason, you might want to set up a
crontab entry to make sure it runs occasionally.

      $ fossil alerts send
    $ fossil alerts send

This should also kick off the backoffice processing, if there are any
pending alerts to send out.

      $ fossil alert pending
    $ fossil alert pending

Show any pending alerts. The number of lines output here should equal
the [status output above](#status).

      $ fossil test-add-alerts f5900
      $ fossil alert send
    $ fossil test-add-alerts f5900
    $ fossil alert send

Manually create an email alert and push it out immediately.

The `f` in the first command's final parameter means you're scheduling a
"forum" alert. The integer is the ID of a forum post, which you can find
by visiting `/timeline?showid` on your Fossil instance.

The second command above is necessary because the `test-add-alerts`
command doesn't kick off a backoffice run.

      $ fossil ale send
    $ fossil ale send

This only does the same thing as the final command above, rather than
send you an ale, as you might be hoping. Sorry.


<a id="advanced"></a>
## Advanced Email Setups

corruption][rdbc] if used with a file sharing technology that doesn't
use proper file locking.

You can start this Tcl script as a daemon automatically on most Unix and
Unix-like systems by adding the following line to the `/etc/rc.local`
file of the server that hosts the repository sending email alerts:

      /usr/bin/tclsh /home/www/fossil/email-sender.tcl &
    /usr/bin/tclsh /home/www/fossil/email-sender.tcl &

[cj]:   https://en.wikipedia.org/wiki/Chroot
[rdbc]: https://www.sqlite.org/howtocorrupt.html#_filesystems_with_broken_or_missing_lock_implementations


<a id="dir"></a>
### Method 3: Store in a Directory

    attacker with the `subscriberCode`.  Nor can knowledge of the
    `subscriberCode` lead to an email flood or other annoyance attack, as
    far as I can see.

If the `subscriberCodes` for a Fossil repository are ever compromised,
new ones can be generated as follows:

        UPDATE subscriber SET subscriberCode=randomblob(32);
    UPDATE subscriber SET subscriberCode=randomblob(32);

Since this then affects all new email alerts going out from Fossil, your
end users may never even realize that they're getting new codes, as long
as they don't click on the URLs in the footer of old alert messages.

With that in mind, a Fossil server administrator could choose to
randomize the `subscriberCodes` periodically, such as just before the

However, the daily digest of email notifications is handled by the
backoffice.  If a Fossil server can sometimes go more than a day without
being accessed, then the automatic backoffice will never run, and the
daily digest might not go out until somebody does visit a webpage.
If this is a problem, an administrator can set up a cron job to
periodically run:

>   fossil backoffice _REPOSITORY_
    fossil backoffice _REPOSITORY_

That command will cause backoffice processing to occur immediately.
Note that this is almost never necessary for an internet-facing
Fossil repository, since most repositories will get multiple accesses
per day from random robots, which will be sufficient to kick off the
daily digest emails.  And even for a private server, if there is very
little traffic, then the daily digests are probably a no-op anyhow

[Fossil Forum](https://fossil-scm.org/forum) so that we can perhaps
fix the problem.)  For now, the backoffice must be run manually
on OpenBSD systems.

To set up fully-manual backoffice, first disable the automatic backoffice
using the "[backoffice-disable](/help?cmd=backoffice-disable)" setting.

>   fossil setting backoffice-disable on
    fossil setting backoffice-disable on

Then arrange to invoke the backoffice separately using a command
like this:

>   fossil backoffice --poll 30 _REPOSITORY-LIST_
    fossil backoffice --poll 30 _REPOSITORY-LIST_

Multiple repositories can be named.  This one command will handle
launching the backoffice for all of them.  There are additional useful
command-line options.  See the "[fossil backoffice](/help?cmd=backoffice)"
documentation for details.

The backoffice processes run manually using the "fossil backoffice"

"no process".  Sometimes the process id will be non-zero even if there
is no corresponding process. Fossil knows how to figure out whether or
not a process still exists.

You can print out a decoded copy of the current backoffice lease using
this command:

>  fossil test-backoffice-lease -R _REPOSITORY_
    fossil test-backoffice-lease -R _REPOSITORY_

If a system has been idle for a long time, then there will be no
backoffice processes.  (Either the process id entries in the lease
will be zero, or there will exist no process associated with the
process id.) When a new web request comes in, the system
sees that no backoffice process is active and so it kicks off a separate
process to run backoffice.

The backoffice should "just work".  It should not require administrator
attention.  However, if you suspect that something is not working right,
there are some debugging aids.

We have already mentioned the command that shows the backoffice lease
for a repository:

>  fossil test-backoffice-lease -R _REPOSITORY_
    fossil test-backoffice-lease -R _REPOSITORY_

Running that command every few seconds should show what is going on with
backoffice processing in a particular repository.

There are also settings that control backoffice behavior.  The
"backoffice-nodelay" setting prevents the "next" process from taking a
lease and sleeping.  If "backoffice-nodelay" is set, that causes all

lacked this capability until Ventura (13.0). If you’re on Monterey (12)
or older, we recommend use of the [Homebrew][hb] OpenSSL package rather
than give up on the security afforded by use of configurable-iteration
PBKDF2. To avoid a conflict with the platform’s `openssl` binary,
Homebrew’s installation is [unlinked][hbul] by default, so you have to
give an explicit path to it, one of:

       /usr/local/opt/openssl/bin/openssl ...     # Intel x86 Macs
       /opt/homebrew/opt/openssl/bin/openssl ...  # ARM Macs (“Apple silicon”)
    /usr/local/opt/openssl/bin/openssl ...     # Intel x86 Macs
    /opt/homebrew/opt/openssl/bin/openssl ...  # ARM Macs (“Apple silicon”)

[lssl]: https://www.libressl.org/


## <a id="rest"></a> Restoring From An Encrypted Backup

The “restore” script for the above fragment is basically an inverse of

branches identified only by the commit ID currently at its tip, being a
long string of hex digits.  Therefore, Fossil conflates two concepts:
branching as intentional forking and the naming of forks as branches.
They are in fact separate concepts, but since Fossil is intended to be
used primarily by humans, we combine them in Fossil's human user
interfaces.

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

Unnamed forks <i>may</i> be intentional, but most of the time, they're
accidental and left unnamed.

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

bad, which is why [./concepts.wiki#workflow|Fossil tries so hard to avoid them], why it warns you
about it when they do occur, and why it makes it relatively [#fix|quick and
painless to fix them] when they do occur.


<h2>Review Of Terminology</h2>

<blockquote><dl>
<dl>
<dt><b>Branch</b></dt>
<dd><p>A branch is a set of check-ins with the same value for their
"branch" property.</p></dd>
<dt><b>Leaf</b></dt>
<dd><p>A leaf is a check-in with no children in the same branch.</p></dd>
<dt><b>Closed Leaf</b></dt>
<dd><p>A closed leaf is any leaf with the <b>closed</b> tag.  These leaves
are intended to never be extended with descendants and hence are omitted
from lists of leaves in the command-line and web interface.</p></dd>
<dt><b>Open Leaf</b></dt>
<dd><p>A open leaf is a leaf that is not closed.</p></dd>
<dt><b>Fork</b></dt>
<dd><p>A fork is when a check-in has two or more direct (non-merge)
children in the same branch.</p></dd>
<dt><b>Branch Point</b></dt>
<dd><p>A branch point occurs when a check-in has two or more direct (non-merge)
children in different branches.  A branch point is similar to a fork,
except that the children are in different branches.</p></dd>
</dl></blockquote>
</dl>

Check-in 4 of Figure 3 is not a leaf because it has a child (check-in 5)
in the same branch.  Check-in 9 of Figure 5 also has a child (check-in 10)
but that child is in a different branch, so check-in 9 is a leaf.  Because
of the <b>closed</b> tag on check-in 9, it is a closed leaf.

Check-in 2 of Figure 3 is considered a "fork"

the optional <a href="https://www.openssl.org/">OpenSSL</a> support,
first <a href="https://www.openssl.org/source/">download the official
source code for OpenSSL</a> and extract it to an appropriately named
"<b>openssl</b>" subdirectory within the local
[/tree?ci=trunk&name=compat | compat] directory then make sure that some recent
<a href="http://www.perl.org/">Perl</a> binaries are installed locally,
and finally run one of the following commands:
<blockquote><pre>
<pre>
nmake /f Makefile.msc FOSSIL_ENABLE_SSL=1 FOSSIL_BUILD_SSL=1 PERLDIR=C:\full\path\to\Perl\bin
</pre></blockquote>
<blockquote><pre>
</pre>
<pre>
buildmsvc.bat FOSSIL_ENABLE_SSL=1 FOSSIL_BUILD_SSL=1 PERLDIR=C:\full\path\to\Perl\bin
</pre></blockquote>
</pre>
To enable the optional native [./th1.md#tclEval | Tcl integration feature],
run one of the following commands or add the &quot;FOSSIL_ENABLE_TCL=1&quot;
argument to one of the other NMAKE command lines:
<blockquote><pre>
<pre>
nmake /f Makefile.msc FOSSIL_ENABLE_TCL=1
</pre></blockquote>
<blockquote><pre>
</pre>
<pre>
buildmsvc.bat FOSSIL_ENABLE_TCL=1
</pre></blockquote>
</pre>

<li><i>Cygwin</i> → The same as other Unix-like systems. It is
recommended to configure using: "<b>configure --disable-internal-sqlite</b>",
making sure you have the "libsqlite3-devel" , "zlib-devel" and
"openssl-devel" packages installed first.</li>
</ol>
</ol>

  be installed on the local machine.  You can get Tcl/Tk from
  [http://www.activestate.com/activetcl|ActiveState].
</li>

<li>
  To build on older Macs (circa 2002, MacOS 10.2) edit the Makefile
  generated by configure to add the following lines:
  <blockquote><pre>
  <pre>
  TCC += -DSQLITE_WITHOUT_ZONEMALLOC
  TCC += -D_BSD_SOURCE
  TCC += -DWITHOUT_ICONV
  TCC += -Dsocketlen_t=int
  TCC += -DSQLITE_MAX_MMAP_SIZE=0
  </pre></blockquote>
  </pre>
</li>
</ul>


<h2 id="docker" name="oci">5.0 Building a Docker Container</h2>

The information on building Fossil inside an

[https://emscripten.org/docs/getting_started/downloads.html]

For instructions on keeping the SDK up to date, see:

[https://emscripten.org/docs/tools_reference/emsdk.html]

    Sidebar: getting Emscripten up and running is trivial and
    painless, at least on Linux systems, but the installer downloads
    many hundreds of megabytes of tools and dependencies, all of which
    will be installed under the single SDK directory (as opposed to
    being installed at the system level). It does, however, require
    that python3 be installed at the system level and it can
    optionally make use of a system-level cmake for certain tasks
    unrelated to how fossil uses the SDK.
<div class="sidebar">Getting Emscripten up and running is trivial and
painless, at least on Linux systems, but the installer downloads
many hundreds of megabytes of tools and dependencies, all of which
will be installed under the single SDK directory (as opposed to
being installed at the system level). It does, however, require
that python3 be installed at the system level and it can
optionally make use of a system-level cmake for certain tasks
unrelated to how fossil uses the SDK.</div>

After installing the SDK, configure the fossil tree with emsdk
support:

<pre><code>$ ./configure --with-emsdk=/path/to/emsdk ...other options...
<pre><code>$ ./configure --with-emsdk=/path/to/emsdk \
  --and-other-options...
</code></pre>

If the <tt>--with-emsdk</tt> flag is not provided, the configure
script will check for the environment variable <tt>EMSDK</tt>, which
is one of the standard variables the SDK environment uses. If that
variable is found, its value will implicitly be used in place of the
missing <tt>--with-emsdk</tt> flag. Thus, if the <tt>emsdk_env.sh</tt>

build cycle. They are instead explicitly built as described below.

From the top of the source tree, all WASM-related components can be
built with:

<pre><code>$ make wasm</code></pre>

<div class="sidebar">The file
<tt>[/file/extsrc/pikcher-worker.js|extsrc/pikcher-worker.js]</tt>
is hand-coded and intended to be loaded as a "Worker" in
JavaScript. That file loads the main module and provides an
interface via which a main JavaScript thread can communicate with
pikchr running in a Worker thread. The file
<tt>[/file/src/fossil.page.pikchrshowasm.js|src/fossil.page.pikchrshowasm.js]</tt>
implements the [/pikchrshow] app and demonstrates how
<tt>pikchr-worker.js</tt> is used.</div>

As of this writing, those parts include:

   *  <tt>extsrc/pikchr.wasm</tt> is a WASM-compiled form of
      <tt>extsrc/pikchr.c</tt>.
   *  <tt>extsrc/pikchr.js</tt> is JS/WASM glue code generated by Emscripten
      to give JS code access to the API exported by the WASM file.

    Sidebar: The file
    <tt>[/file/extsrc/pikcher-worker.js|extsrc/pikcher-worker.js]</tt>
    is hand-coded and intended to be loaded as a "Worker" in
    JavaScript. That file loads the main module and provides an
    interface via which a main JavaScript thread can communicate with
    pikchr running in a Worker thread. The file
    <tt>[/file/src/fossil.page.pikchrshowasm.js|src/fossil.page.pikchrshowasm.js]</tt>
    implements the [/pikchrshow] app and demonstrates how
    <tt>pikchr-worker.js</tt> is used.

When a new version of <tt>extsrc/pikchr.c</tt> is installed, the
files <tt>pikchr.{js,wasm}</tt> will need to be recompiled to account
for that. Running <tt>make wasm</tt> will, if the build is set up for
the emsdk, recompile those:

<pre><code>$ make wasm
./tools/emcc.sh -o extsrc/pikchr.js ...
$ ls -la extsrc/pikchr.{js,wasm}
-rw-rw-r-- 1 stephan stephan 17263 Jun  8 03:59 extsrc/pikchr.js
-rw-rw-r-- 1 stephan stephan 97578 Jun  8 03:59 extsrc/pikchr.wasm
</code></pre>

<blockquote>Sidebar: if that fails with a message along the lines of:
<div class="sidebar">If that fails with a message along the lines of

<pre><code>setting `EXPORTED_RUNTIME_METHODS` expects `<class 'list'>` but got `<class 'str'>`</code></pre>
“<code>setting `EXPORTED_RUNTIME_METHODS` expects `<class 'list'>` but

then the emcc being invoked is too old: emcc changed the format of
list-type arguments at some point. The required minimum version is
unknown, but any SDK version from May 2022 or later "should" (as of
this writing) suffice. Any older version may or may not work.
</blockquote>
got `<class 'str'>`</code>” then the emcc being invoked is too old: emcc
changed the format of list-type arguments at some point.  The required
minimum version is unknown, but any SDK version from May 2022 or later
"should" (as of this writing) suffice. Any older version may or may not
work.</div>

After that succeeds, we need to run the normal build so that those
generated files can be compiled in to the fossil binary, accessible
via the [/help?cmd=/builtin|/builtin page]:

<pre><code>$ make</code></pre>

those options.

<h1>CGI Script Options</h1>

The CGI script used to launch a Fossil server will usually look something
like this:

<blockquote><verbatim>
<verbatim>
#!/usr/bin/fossil
repository: /home/www/fossils/myproject.fossil
</verbatim></blockquote>
</verbatim>

Of course, pathnames will likely be different.  The first line 
(the "[wikipedia:/wiki/Shebang_(Unix)|shebang]")
always gives the name of the Fossil executable.  Subsequent lines are of
the form "<b>property:&nbsp;argument&nbsp;...</b>".
The remainder of this document describes the available properties and
their arguments.

  *  Moved the /museum/repo.fossil file referenced from the Dockerfile from
     the ENTRYPOINT to the CMD part to allow use of --repolist mode.
  *  The /uvlist page now shows the hash algorithm used so that
     outsiders don't have to guess it from the hash length when
     double-checking hashes of downloaded files on their end.
  *  The hash itself is now shown in a fixed-width font on the /uvlist
     page, suiting this tabular display.
  *  Reworked the default skin to make everything more readable: larger
     fonts, more whitespace, added indents to show hierarchy and to
     offset command examples, etc.  Colors are slightly adjusted to bring
     things into better accord with the WCAG accessibility guidelines.

<h2 id='v2_23'>Changes for version 2.23 (2023-11-01)</h2>

  *  Add ability to "close" forum threads, such that unprivileged users
     may no longer respond to them. Only administrators can close
     threads or respond to them by default, and the
     [/help?cmd=forum-close-policy|forum-close-policy setting] can be

Send button is pressed, any pending text is submitted along with the
selected file. Image files sent this way will, by default, appear
inline in messages, but each user may toggle that via the settings
popup menu, such that images instead appear as downloadable links.
Non-image files always appear in messages as download links.

### Deletion of Messages

<div class="sidebar">Message deletion is itself a type of message, which
is why deletions count towards updates in the recent activity list.  (It
is counted for the person who performed the deletion, not the author of
the deleted comment.) That can potentially lead to odd corner cases
where a user shows up in the list but has no messages which are
currently visible because they were deleted, or an admin user who has
not posted anything but deleted a message. That is a known minor
cosmetic-only bug with a resolution of "will not fix."</div>

Any user may *locally* delete a given message by clicking on the "tab"
at the top of the message and clicking the button which appears. Such
deletions are local-only, and the messages will reappear if the page
is reloaded. The user who posted a given message, or any Admin users,
may additionally choose to globally delete a message from the chat
record, which deletes it not only from their own browser but also

online, but it gives an overview of which users have been active most
recently, noting that "lurkers" (people who post no messages) will not
show up in that list, nor does the chat infrastructure have a way to
track and present those. That list can be used to filter messages on a
specific user by tapping on that user's name, tapping a second time to
remove the filter.

Sidebar: message deletion is a type of message and deletions count
towards updates in the recent activity list (counted for the person
who performed the deletion, not the author of the deleted
comment). That can potentially lead to odd corner cases where a user
shows up in the list but has no messages which are currently visible
because they were deleted, or an admin user who has not posted
anything but deleted a message. That is a known minor cosmetic-only
bug with a resolution of "will not fix."

### <a id="cli"></a> The `fossil chat` Command

Type [fossil chat](/help?cmd=chat) from within any open check-out
to bring up a chatroom for the project that is in that checkout.
The new chat window will attempt to connect to the default sync
target for that check-out (the server whose URL is shown by the
[fossil remote](/help?cmd=remote) command).

<title>Check-in Names</title>

<table align="right" border="1" width="33%" cellpadding="10">
<div class="sidebar no-label">
<tr><td>
<h3>Quick Reference</h3>
<b>Quick Reference</b>
<ul>
<li> Hash prefix
<li> Branch name
<li> Tag name
<li> Timestamp:  <i>YYYY-MM-DD HH:MM:SS</i>
<li> <i>tag-name</i> <big><b>:</b></big> <i>timestamp</i>
<li> <b>root <big>:</big></b> <i>branchname</i>
<li> <b>start <big>:</big></b> <i>branchname</i>
<li> <b>merge-in <big>:</big></b> <i>branchname</i>
<li> Special names:
<ul>
<li> <b>tip</b>
<li> <b>current</b>
<li> <b>next</b>
<li> <b>previous</b> or <b>prev</b>
<li> <b>ckout</b> (<a href='./embeddeddoc.wiki'>embedded docs</a> only)
</ul>
</ul>
</td></tr>
</table>
</div>

Many Fossil [/help|commands] and [./webui.wiki | web interface] URLs accept
check-in names as an argument.  For example, the "[/help/info|info]" command
accepts an optional check-in name to identify the specific check-in
about which information is desired:

<blockquote>
<tt>fossil info</tt> <i>checkin-name</i>
</blockquote>
<pre style="white-space: pre-wrap">
fossil info <i>checkin-name</i>
</pre>

You are perhaps reading this page from the following URL:

<blockquote>
https://fossil-scm.org/home/doc/<b>trunk</b>/www/checkin_names.wiki
</blockquote>
<verbatim>
https://fossil-scm.org/home/doc/trunk/www/checkin_names.wiki
</verbatim>

The URL above is an example of an [./embeddeddoc.wiki | embedded documentation]
page in Fossil.  The bold term of the pathname is a check-in name that
This is an example of an [./embeddeddoc.wiki | embedded documentation]
page URL.  The "trunk" element of the pathname is a
[./glossary.md#check-in | check-in] name that
determines which version of the documentation to display.

Fossil provides a variety of ways to specify a check-in.  This
document describes the various methods.

<h2 id="canonical">Canonical Check-in Name</h2>

The canonical name of a check-in is the hash of its
[./fileformat.wiki#manifest | manifest] expressed as a
[./hashes.md | long lowercase hexadecimal number].  For example:

<blockquote><pre>
<pre>
fossil info e5a734a19a9826973e1d073b49dc2a16aa2308f9
</pre></blockquote>
</pre>

The full 40 or 64 character hash is unwieldy to remember and type, though,
so Fossil also accepts a unique prefix of the hash, using any combination
of upper and lower case letters, as long as the prefix is at least 4
characters long.  Hence the following commands all
accomplish the same thing as the above:

<blockquote><pre>
<pre>
fossil info e5a734a19a9
fossil info E5a734A
fossil info e5a7
</blockquote>
</pre>

Many web interface screens identify check-ins by 10- or 16-character
prefix of canonical name.
Fossil uses this feature itself, identifying check-ins by 8 to 16-character
prefixes of the canonical name in places where it doesn't want to chew
up the screen real estate required to display the whole hash.

<h2 id="tags">Tags And Branch Names</h2>

Using a tag or branch name where a check-in name is expected causes
Fossil to choose the most recent check-in with that tag or branch name.
So for example, the most recent check-in that
is tagged with "release" as of this writing is [b98ce23d4fc].
The command:

<blockquote><pre>
<pre>
fossil info release
</pre></blockquote>
</pre>

…results in the following output:

<blockquote><pre>
<pre>
hash:         b98ce23d4fc3b734cdc058ee8a67e6dad675ca13 2020-08-20 13:27:04 UTC
parent:       40feec329163103293d98dfcc2d119d1a16b227a 2020-08-20 13:01:51 UTC
tags:         release, branch-2.12, version-2.12.1
comment:      Version 2.12.1 (user: drh)
</pre></blockquote>
</pre>

There are multiple check-ins that are tagged with "release" but
(as of this writing) the [b98ce23d4fc]
check-in is the most recent so it is the one that is selected.

Note that unlike some other version control systems, a "branch" in Fossil
is not anything special: it is simply a sequence of check-ins that
share a common tag, so the same mechanism that resolves tag names
also resolves branch names.

<a id="tagpfx"></a>
Note also that there can — in theory, if rarely in practice — be an ambiguity
between tag names and canonical names.  Suppose, for example, you had a
check-in with the canonical name deed28aa99… and you
also happened to have tagged a different check-in with "deed2".  If
you use the "deed2" name, does it choose the canonical name or the tag
name?  In such cases, you can prefix the tag name with "tag:".
For example:

<blockquote><tt>
<pre>
fossil info tag:deed2
</tt></blockquote>
</pre>

The "tag:deed2" name will refer to the most recent check-in
tagged with "deed2" rather than the
check-in whose canonical name begins with "deed2".

<h2 id="whole-branches">Whole Branches</h2>

repo could have release tags like “2020-04-01”, the date the release was
cut, but you could force Fossil to interpret that string as a date
rather than as a tag by passing “date:2020-04-01”.

For an example of how timestamps are useful,
consider the homepage for the Fossil website itself:

<blockquote>
<pre>
https://fossil-scm.org/home/doc/<b>trunk</b>/www/index.wiki
</blockquote>
</pre>

The bold component of that URL is a check-in name.  To see the stored content
of the Fossil website repository as of January 1, 2009, one has merely to change
the URL to the following:

<blockquote>
<pre>
https://fossil-scm.org/home/doc/<b>2009-01-01</b>/www/index.wiki
</blockquote>
</pre>

(Note that this won't roll you back to the <i>skin</i> and other
cosmetic configurations as of that date. It also won't change screens
like the timeline, which has an independent date selector.)

<h2 id="tag-ts">Tag And Timestamp</h2>

A check-in name can also take the form of a tag or branch name followed by
a colon and then a timestamp.  The combination means to take the most
recent check-in with the given tag or branch which is not more recent than
the timestamp.  So, for example:

<blockquote><tt>
<pre>
fossil update trunk:2010-07-01T14:30
</tt></blockquote>
</pre>

Would cause Fossil to update the working check-out to be the most recent
check-in on the trunk that is not more recent than 14:30 (UTC) on
July 1, 2010.

<h2 id="root">Root Of A Branch</h2>

A branch name that begins with the "<tt>root:</tt>" prefix refers to the
last check-in on the parent branch prior to the beginning of the branch.
Such a label is useful, for example, in computing all diffs for a single
branch.  The following example will show all changes in the hypothetical
branch "xyzzy":

<blockquote><tt>
<pre>
fossil diff --from root:xyzzy --to xyzzy
</tt></blockquote>
</pre>

<a id="merge-in"></a>
That doesn't do what you might expect after you merge the parent
branch's changes into the child branch: the above command will include
changes made on the parent branch as well.

You can solve this by using the prefix "<tt>merge-in:</tt>" instead of
"<tt>root:</tt>" to tell Fossil to find
the most recent merge-in point for that branch.
The resulting diff will then show only the changes in
the branch itself, omitting
any changes that have already been merged in from the parent branch.

<a id="start"></a>
The prefix "<tt>start:</tt>" gives the first check-in of the named branch.

The prefixes "<tt>root:</tt>", "<tt>start:</tt>", and  "<tt>merge-in:</tt>"
can be chained: one can say for example 

<blockquote><tt>
<pre>
fossil info merge-in:xyzzy:2022-03-01
</tt></blockquote>
</pre>

to get informations about the most recent merge-in point on the branch 
"xyzzy" that happened on or before March 1, 2022.

<h2 id="special">Special Tags</h2>

The tag "tip" means the most recent check-in.  The "tip" tag is practically
equivalent to the timestamp "9999-12-31".

This special name works anywhere you can pass a "NAME", such as with
<tt>/info</tt> URLs:

<blockquote><pre>
<pre>
http://localhost:8080/info/tip
</pre></blockquote>
</pre>

There are several other special names, but they only work from within a
check-out directory because they are relative to the current checked-out
version:

  *  "current": the current checked-out version
  *  "next": the youngest child of the current checked-out version

<h2 id="examples">Additional Examples</h2>

To view the changes in the most recent check-in prior to the version currently
checked out:

<blockquote><pre>
<pre>
fossil diff --from previous --to current
</pre></blockquote>
</pre>

Suppose you are of the habit of tagging each release with a "release" tag.
Then to see everything that has changed on the trunk since the last release:

<blockquote><pre>
<pre>
fossil diff --from release --to trunk
</pre></blockquote>
</pre>


<h2 id="order">Resolution Order</h2>

Fossil currently resolves name strings to artifact hashes in the
following order:

at the request of the child.

<h2>Creating a Child Project</h2>

To create a new child project, first clone the parent.  Then make manual
SQL changes to the child repository as follows:

<blockquote><verbatim>
<verbatim>
UPDATE config SET name='parent-project-code' WHERE name='project-code';
UPDATE config SET name='parent-project-name' WHERE name='project-name';
INSERT INTO config(name,value)
   VALUES('project-code',lower(hex(randomblob(20))));
INSERT INTO config(name,value)
   VALUES('project-name','CHILD-PROJECT-NAME');
</verbatim></blockquote>
</verbatim>

Modify the CHILD-PROJECT-NAME in the last statement to be the name of
the child project, of course.

The repository is now a separate project, independent from its parent.
Clone the new project to the developers as needed.

## <a id="mcw"></a> Multiple-Checkout Workflow

With Fossil, it is routine to have multiple check-outs from the same
repository:

        fossil clone https://example.com/repo /path/to/repo.fossil
    fossil clone https://example.com/repo /path/to/repo.fossil

        mkdir -p ~/src/my-project/trunk
        cd ~/src/my-project/trunk
        fossil open /path/to/repo.fossil    # implicitly opens “trunk”
    mkdir -p ~/src/my-project/trunk
    cd ~/src/my-project/trunk
    fossil open /path/to/repo.fossil    # implicitly opens “trunk”

        mkdir ../release
        cd ../release
        fossil open /path/to/repo.fossil release
    mkdir ../release
    cd ../release
    fossil open /path/to/repo.fossil release

        mkdir ../my-other-branch
        cd ../my-other-branch
        fossil open /path/to/repo.fossil my-other-branch
    mkdir ../my-other-branch
    cd ../my-other-branch
    fossil open /path/to/repo.fossil my-other-branch

        mkdir ../scratch
        cd ../scratch
        fossil open /path/to/repo.fossil abcd1234
    mkdir ../scratch
    cd ../scratch
    fossil open /path/to/repo.fossil abcd1234

        mkdir ../test
        cd ../test
        fossil open /path/to/repo.fossil 2019-04-01
        
    mkdir ../test
    cd ../test
    fossil open /path/to/repo.fossil 2019-04-01

Now you have five separate check-out directories: one each for:

*   trunk
*   the latest tagged public release
*   an alternate branch you’re working on
*   a “scratch” directory for experiments you don’t want to do in the
    other check-out directories; and

Nevertheless, it is possible to work in a more typical Git sort of
style, switching between versions in a single check-out directory.

#### <a id="idiomatic"></a> The Idiomatic Fossil Way

The most idiomatic way is as follows:

        fossil clone https://example.com/repo /path/to/repo.fossil
        mkdir work-dir
        cd work-dir
        fossil open /path/to/repo.fossil
        ...work on trunk...
    fossil clone https://example.com/repo /path/to/repo.fossil
    mkdir work-dir
    cd work-dir
    fossil open /path/to/repo.fossil
    ...work on trunk...

        fossil update my-other-branch
        ...work on your other branch in the same directory...
    fossil update my-other-branch
    ...work on your other branch in the same directory...

Basically, you replace the `cd` commands in the multiple checkouts
workflow above with `fossil up` commands.


#### <a id="open"></a> Opening a Repository by URI

In Fossil 2.12, we added a feature to simplify the single-worktree use
case:

        mkdir work-dir
        cd work-dir
        fossil open https://example.com/repo
    mkdir work-dir
    cd work-dir
    fossil open https://example.com/repo

Now you have “trunk” open in `work-dir`, with the repo file stored as
`repo.fossil` in that same directory.

Users of Git may be surprised that it doesn’t create a directory for you
and that you `cd` into it *before* the clone-and-open step, not after.
This is because we’re overloading the “open” command, which already had
the behavior of opening into the current working directory. Changing it
to behave like `git clone` would therefore make the behavior surprising
to Fossil users. (See [our discussions][caod] if you want the full
details.)


#### <a id="clone"></a> Git-Like Clone-and-Open

In Fossil 2.14, we added a more Git-like alternative:

        fossil clone https://fossil-scm.org/fossil
        cd fossil
    fossil clone https://fossil-scm.org/fossil
    cd fossil

This results in a `fossil.fossil` repo DB file and a `fossil/` working
directory.

Note that our `clone URI` behavior does not commingle the repo and
check-out, solving our major problem with the Git design.

If you want the repo to be named something else, adjust the URL:

        fossil clone https://fossil-scm.org/fossil/fsl
    fossil clone https://fossil-scm.org/fossil/fsl

That gets you `fsl.fossil` checked out into `fsl/`.

For sites where the repo isn’t served from a subdirectory like this, you
might need another form of the URL. For example, you might have your
repo served from `dev.example.com` and want it cloned as `my-project`:

        fossil clone https://dev.example.com/repo/my-project
    fossil clone https://dev.example.com/repo/my-project

The `/repo` addition is the key: whatever comes after is used as the
repository name. [See the docs][clone] for more details.

[caod]:  https://fossil-scm.org/forum/forumpost/3f143cec74
[clone]: /help?cmd=clone

<div style="height:50em" id="this-space-intentionally-left-blank"></div>

<title>Fossil Concepts</title>
<h1 align="center">Fossil Concepts</h1>

<h2>1.0 Introduction</h2>

[./index.wiki | Fossil] is a
[http://en.wikipedia.org/wiki/Software_configuration_management | software configuration management] system.
Fossil is software that is designed to control and track the
development of a software project and to record the history

identifier for a blob of data, such as a file. Given any file, it is
simple to find the artifact ID for that file. But given an artifact ID,
it is computationally intractable to generate a file that will have that
same artifact ID.

Artifact IDs look something like this:

<blockquote><b>
6089f0b563a9db0a6d90682fe47fd7161ff867c8<br>
59712614a1b3ccfd84078a37fa5b606e28434326<br>
19dbf73078be9779edd6a0156195e610f81c94f9<br>
b4104959a67175f02d6b415480be22a239f1f077<br>
<pre>
6089f0b563a9db0a6d90682fe47fd7161ff867c8
59712614a1b3ccfd84078a37fa5b606e28434326
19dbf73078be9779edd6a0156195e610f81c94f9
b4104959a67175f02d6b415480be22a239f1f077
997c9d6ae03ad114b2b57f04e9eeef17dcb82788
</b></blockquote>
</pre>

When referring to an artifact using Fossil, you can use a unique
prefix of the artifact ID that is four characters or longer.  This saves
a lot of typing.  When displaying artifact IDs, Fossil will usually only
show the first 10 digits since that is normally enough to uniquely
identify a file.

an upgrade.  Running "all rebuild" never hurts, so when upgrading it
is a good policy to run it even if it is not strictly necessary.

To use Fossil, simply type the name of the executable in your
shell, followed by one of the various built-in commands and
arguments appropriate for that command.  For example:

<blockquote><b>
fossil help
<pre>fossil help</pre>
</b></blockquote>

In the next section, when we say things like "use the <b>help</b>
command" we mean to use the command name "help" as the first
token after the name of the Fossil executable, as shown above.

<h2 id="workflow">4.0 Workflow</h2>

An interesting feature of Fossil is that it supports both autosync
and manual-merge work flows.

The default setting for Fossil is to be in autosync mode.  You
can change the autosync setting or check the current autosync
setting using commands like:

<blockquote>
<b>fossil setting autosync on<br>
fossil setting autosync off<br>
<b>fossil settings</b>
</blockquote>
<pre>
fossil setting autosync on
fossil setting autosync off
fossil settings
</pre>

By default, Fossil runs with autosync mode turned on.  The
authors finds that projects run more smoothly in autosync mode since
autosync helps to prevent pointless forking and merging and helps keeps
all collaborators working on exactly the same code rather than on their
own personal forks of the code.  In the author's view, manual-merge mode
should be reserved for disconnected operation.

## 1. Quick Start

Fossil ships a `Dockerfile` at the top of its source tree,
[here][DF], which you can build like so:

```
  $ docker build -t fossil .
    $ docker build -t fossil .
```

If the image built successfully, you can create a container from it and
test that it runs:

```
  $ docker run --name fossil -p 9999:8080/tcp fossil
    $ docker run --name fossil -p 9999:8080/tcp fossil
```

This shows us remapping the internal TCP listening port as 9999 on the
host. This feature of OCI runtimes means there’s little point to using
the “`fossil server --port`” feature inside the container. We can let
Fossil default to 8080 internally, then remap it to wherever we want it
on the host instead.

fresh container based on that image. You can pass extra arguments to the
first command via the Makefile’s `DBFLAGS` variable and to the second
with the `DCFLAGS` variable. (DB is short for “`docker build`”, and DC
is short for “`docker create`”, a sub-step of the “run” target.)
To get the custom port setting as in
second command above, say:

```
  $ make container-run DCFLAGS='-p 9999:8080/tcp'
    $ make container-run DCFLAGS='-p 9999:8080/tcp'
```

Contrast the raw “`docker`” commands above, which create an
_unversioned_ image called `fossil:latest` and from that a container
simply called `fossil`. The unversioned names are more convenient for
interactive use, while the versioned ones are good for CI/CD type
applications since they avoid a conflict with past versions; it lets you
keep old containers around for quick roll-backs while replacing them

### <a id="repo-inside"></a> 2.1 Storing the Repo Inside the Container

The simplest method is to stop the container if it was running, then
say:

```
  $ docker cp /path/to/my-project.fossil fossil:/museum/repo.fossil
  $ docker start fossil
  $ docker exec fossil chown -R 499 /museum
    $ docker cp /path/to/my-project.fossil fossil:/museum/repo.fossil
    $ docker start fossil
    $ docker exec fossil chown -R 499 /museum
```

That copies the local Fossil repo into the container where the server
expects to find it, so that the “start” command causes it to serve from
that copied-in file instead. Since it lives atop the immutable base
layers, it persists as part of the container proper, surviving restarts.

Notice that the copy command changes the name of the repository

The simple storage method above has a problem: containers are
designed to be killed off at the slightest cause, rebuilt, and
redeployed. If you do that with the repo inside the container, it gets
destroyed, too. The solution is to replace the “run” command above with
the following:

```
  $ docker run \
    --publish 9999:8080 \
    --name fossil-bind-mount \
    --volume ~/museum:/museum \
    fossil
    $ docker run \
      --publish 9999:8080 \
      --name fossil-bind-mount \
      --volume ~/museum:/museum \
      fossil
```

Because this bind mount maps a host-side directory (`~/museum`) into the
container, you don’t need to `docker cp` the repo into the container at
all. It still expects to find the repository as `repo.fossil` under that
directory, but now both the host and the container can see that repo DB.

Instead of a bind mount, you could instead set up a separate

#### 2.2.1 <a id="wal-mode"></a>WAL Mode Interactions

You might be aware that OCI containers allow mapping a single file into
the repository rather than a whole directory.  Since Fossil repositories
are specially-formatted SQLite databases, you might be wondering why we
don’t say things like:

```
  --volume ~/museum/my-project.fossil:/museum/repo.fossil
    --volume ~/museum/my-project.fossil:/museum/repo.fossil
```

That lets us have a convenient file name for the project outside the
container while letting the configuration inside the container refer to
the generic “`/museum/repo.fossil`” name. Why should we have to name
the repo generically on the outside merely to placate the container?

The reason is, you might be serving that repo with [WAL mode][wal]

    granularity beyond the classic Unix ones inside the container, so we
    drop root’s ability to change them.

All together, we recommend adding the following options to your
“`docker run`” commands, as well as to any “`docker create`” command
that will be followed by “`docker start`”:

```
  --cap-drop AUDIT_WRITE \
  --cap-drop CHOWN \
  --cap-drop FSETID \
  --cap-drop KILL \
  --cap-drop MKNOD \
  --cap-drop NET_BIND_SERVICE \
  --cap-drop NET_RAW \
  --cap-drop SETFCAP \
  --cap-drop SETPCAP
    --cap-drop AUDIT_WRITE \
    --cap-drop CHOWN \
    --cap-drop FSETID \
    --cap-drop KILL \
    --cap-drop MKNOD \
    --cap-drop NET_BIND_SERVICE \
    --cap-drop NET_RAW \
    --cap-drop SETFCAP \
    --cap-drop SETPCAP
```

In the next section, we’ll show a case where you create a container
without ever running it, making these options pointless.

[backoffice]: ./backoffice.md
[defcap]:     https://docs.docker.com/engine/security/#linux-kernel-capabilities
[capchg]:     https://stackoverflow.com/a/45752205/142454

A secondary benefit falls out of this process for free: it’s arguably
the easiest way to build a purely static Fossil binary for Linux. Most
modern Linux distros make this [surprisingly difficult][lsl], but Alpine’s
back-to-basics nature makes static builds work the way they used to,
back in the day. If that’s all you’re after, you can do so as easily as
this:

```
  $ docker build -t fossil .
  $ docker create --name fossil-static-tmp fossil
  $ docker cp fossil-static-tmp:/bin/fossil .
  $ docker container rm fossil-static-tmp
    $ docker build -t fossil .
    $ docker create --name fossil-static-tmp fossil
    $ docker cp fossil-static-tmp:/bin/fossil .
    $ docker container rm fossil-static-tmp
```

The result is six or seven megs, depending on the CPU architecture you
build for. It’s built stripped.

[lsl]: https://stackoverflow.com/questions/3430400/linux-static-linking-is-dead


## 5. <a id="custom" name="args"></a>Customization Points

### <a id="pkg-vers"></a> 5.1 Fossil Version

The default version of Fossil fetched in the build is the version in the
checkout directory at the time you run it.  You could override it to get
a release build like so:

```
  $ docker build -t fossil --build-arg FSLVER=version-2.20 .
    $ docker build -t fossil --build-arg FSLVER=version-2.20 .
```

Or equivalently, using Fossil’s `Makefile` convenience target:

```
  $ make container-image DBFLAGS='--build-arg FSLVER=version-2.20'
    $ make container-image DBFLAGS='--build-arg FSLVER=version-2.20'
```

While you could instead use the generic
“`release`” tag here, it’s better to use a specific version number
since container builders cache downloaded files, hoping to
reuse them across builds. If you ask for “`release`” before a new
version is tagged and then immediately after, you might expect to get
two different tarballs, but because the underlying source tarball URL

leaving those below it for system users like this Fossil daemon owner.
Since it’s typical for these to start at 0 and go upward, we started at
500 and went *down* one instead to reduce the chance of a conflict to as
close to zero as we can manage.

To change it to something else, say:

```
  $ make container-image DBFLAGS='--build-arg UID=501'
    $ make container-image DBFLAGS='--build-arg UID=501'
```

This is particularly useful if you’re putting your repository on a
separate volume since the IDs “leak” out into the host environment via
file permissions. You may therefore wish them to mean something on both
sides of the container barrier rather than have “499” appear on the host
in “`ls -l`” output.


### 5.3 <a id="cengine"></a>Container Engine

Although the Fossil container build system defaults to Docker, we allow
for use of any OCI container system that implements the same interfaces.
We go into more details about this [below](#light), but
for now, it suffices to point out that you can switch to Podman while
using our `Makefile` convenience targets unchanged by saying:

```
    $ make CENGINE=podman container-run
```


### 5.4 <a id="config"></a>Fossil Configuration Options

You can use this same mechanism to enable non-default Fossil
configuration options in your build. For instance, to turn on
the JSON API and the TH1 docs extension:

```
  $ make container-image \
    DBFLAGS='--build-arg FSLCFG="--json --with-th1-docs"'
    $ make container-image \
      DBFLAGS='--build-arg FSLCFG="--json --with-th1-docs"'
```

If you also wanted [the Tcl evaluation extension](./th1.md#tclEval),
that brings us to [the next point](#run).


### 5.5 <a id="run"></a>Elaborating the Run Layer

If you want a basic shell environment for temporary debugging of the
running container, that’s easily added. Simply change this line in the
`Dockerfile`…

      FROM scratch AS run
    FROM scratch AS run

…to this:

      FROM busybox AS run
    FROM busybox AS run

Rebuild and redeploy to give your Fossil container a [BusyBox]-based
shell environment that you can get into via:

      $ docker exec -it -u fossil $(make container-version) sh
    $ docker exec -it -u fossil $(make container-version) sh

That command assumes you built it via “`make container`” and are
therefore using its versioning scheme.

You will likely want to remove the `PATH` override in the “RUN” stage
when doing this since it’s written for the case where everything is in
`/bin`, and that will no longer be the case with a more full-featured

Let’s say the extension is written in Python. Because this is one of the
most popular programming languages in the world, we have many options
for achieving this. For instance, there is a whole class of
“[distroless]” images that will do this efficiently by changing
“`STAGE 2`” in the `Dockefile` to this:

```
    ## ---------------------------------------------------------------------
    ## STAGE 2: Pare that back to the bare essentials, plus Python.
    ## ---------------------------------------------------------------------
    FROM cgr.dev/chainguard/python:latest
    USER root
    ARG UID=499
    ENV PATH "/sbin:/usr/sbin:/bin:/usr/bin"
    COPY --from=builder /tmp/fossil /bin/
    COPY --from=builder /bin/busybox.static /bin/busybox
    RUN [ "/bin/busybox", "--install", "/bin" ]
    RUN set -x                                                              \
        && echo "fossil:x:${UID}:${UID}:User:/museum:/false" >> /etc/passwd \
        && echo "fossil:x:${UID}:fossil"                     >> /etc/group  \
        && install -d -m 700 -o fossil -g fossil log museum
```

You will also have to add `busybox-static` to the APK package list in
STAGE 1 for the `RUN` script at the end of that stage to work, since the
[Chainguard Python image][cgimgs] lacks a shell, on purpose. The need to
install root-level binaries is why we change `USER` temporarily here.

Build it and test that it works like so:

```
    $ make container-run &&
      docker exec -i $(make container-version) python --version 
    3.11.2
```

The compensation for the hassle of using Chainguard over something more
general purpose like changing the `run` layer to Alpine and then adding
a “`apk add python`” command to the `Dockerfile`
is huge: we no longer leave a package manager sitting around inside the
container, waiting for some malefactor to figure out how to abuse it.

default under the theory that you don’t want those services to run until
you’ve logged into the GUI as that user. If you find yourself running
into this, [enable linger
mode](https://www.freedesktop.org/software/systemd/man/loginctl.html).)
so I was able to create a unit file called
`~/.local/share/systemd/user/alert-sender@.service` with these contents:

```
    [Unit]
    Description=Fossil email alert sender for %I

    [Service]
    WorkingDirectory=/home/fossil/museum
    ExecStart=/home/fossil/bin/alert-sender %I/mail.db
    Restart=always
    RestartSec=3

    [Install]
    WantedBy=default.target
```

I was then able to enable email alert forwarding for select repositories
after configuring them per [the docs](./alerts.md) by saying:

```
    $ systemctl --user daemon-reload
    $ systemctl --user enable alert-sender@myproject
    $ systemctl --user start  alert-sender@myproject
```

Because this is a parameterized script and we’ve set our repository
paths predictably, you can do this for as many repositories as you need
to by passing their names after the “`@`” sign in the commands above.


## 6. <a id="light"></a>Lightweight Alternatives to Docker

leaving the benefits of containerization to those with bigger budgets.

For the sake of simple examples in this section, we’ll assume you’re
integrating Fossil into a larger web site, such as with our [Debian +
nginx + TLS][DNT] plan. This is why all of the examples below create
the container with this option:

```
  --publish 127.0.0.1:9999:8080
    --publish 127.0.0.1:9999:8080
```

The assumption is that there’s a reverse proxy running somewhere that
redirects public web hits to localhost port 9999, which in turn goes to
port 8080 inside the container.  This use of port
publishing effectively replaces the use of the
“`fossil server --localhost`” option.

On Ubuntu 22.04, the installation size is about 38 MiB, roughly a
tenth the size of Docker Engine.

For our purposes here, the only thing that changes relative to the
examples at the top of this document are the initial command:

```
  $ podman build -t fossil .
  $ podman run --name fossil -p 9999:8080/tcp fossil
    $ podman build -t fossil .
    $ podman run --name fossil -p 9999:8080/tcp fossil
```

Your Linux package repo may have a `podman-docker` package which
provides a “`docker`” script that calls “`podman`” for you, eliminating
even the command name difference. With that installed, the `make`
commands above will work with Podman as-is.

The only difference that matters here is that Podman doesn’t have the
same [default Linux kernel capability set](#caps) as Docker, which
affects the `--cap-drop` flags recommended above to:

```
  $ podman create \
    --name fossil \
    --cap-drop CHOWN \
    --cap-drop FSETID \
    --cap-drop KILL \
    --cap-drop NET_BIND_SERVICE \
    --cap-drop SETFCAP \
    --cap-drop SETPCAP \
    --publish 127.0.0.1:9999:8080 \
    localhost/fossil
  $ podman start fossil
    $ podman create \
      --name fossil \
      --cap-drop CHOWN \
      --cap-drop FSETID \
      --cap-drop KILL \
      --cap-drop NET_BIND_SERVICE \
      --cap-drop SETFCAP \
      --cap-drop SETPCAP \
      --publish 127.0.0.1:9999:8080 \
      localhost/fossil
    $ podman start fossil
```

[pmmac]:  https://podman.io/getting-started/installation.html#macos
[pmwin]:  https://github.com/containers/podman/blob/main/docs/tutorials/podman-for-windows.md
[Podman]: https://podman.io/
[rl]:     https://github.com/containers/podman/blob/main/docs/tutorials/rootless_tutorial.md
[whatis]: https://podman.io/whatis.html


### 6.3 <a id="nspawn"></a>`systemd-container`

If even the Podman stack is too big for you, the next-best option I’m
aware of is the `systemd-container` infrastructure on modern Linuxes,
available since version 239 or so.  Its runtime tooling requires only
about 1.4 MiB of disk space:

```
  $ sudo apt install systemd-container btrfs-tools
    $ sudo apt install systemd-container btrfs-tools
```

That command assumes the primary test environment for
this guide, Ubuntu 22.04 LTS with `systemd` 249.  For best
results, `/var/lib/machines` should be a btrfs volume, because
[`$REASONS`][mcfad]. For CentOS Stream 9 and other Red Hattish
systems, you will have to make several adjustments, which we’ve
collected [below](#nspawn-centos) to keep these examples clear.

We’ll assume your Fossil repository stores something called
“`myproject`” within `~/museum/myproject/repo.fossil`, named according
to the reasons given [above](#repo-inside). We’ll make consistent use of
this naming scheme in the examples below so that you will be able to
replace the “`myproject`” element of the various file and path names.

If you use [the stock `Dockerfile`][DF] to generate your
base image, `nspawn` won’t recognize it as containing an OS unless you
change the “`FROM scratch AS os`” line at the top of the second stage
to something like this:

```
  FROM gcr.io/distroless/static-debian11 AS os
    FROM gcr.io/distroless/static-debian11 AS os
```

Using that as a base image provides all the files `nspawn` checks for to
determine whether the container is sufficiently close to a Linux VM for
the following step to proceed:

```
  $ make container
  $ docker container export $(make container-version) |
    machinectl import-tar - myproject
    $ make container
    $ docker container export $(make container-version) |
      machinectl import-tar - myproject
```

Next, create `/etc/systemd/nspawn/myproject.nspawn`:

----

```
[Exec]
WorkingDirectory=/
Parameters=bin/fossil server                \
    --baseurl https://example.com/myproject \
    --create                                \
    --jsmode bundled                        \
    --localhost                             \
    --port 9000                             \
    --scgi                                  \
    --user admin                            \
    museum/repo.fossil
DropCapability=          \
    CAP_AUDIT_WRITE      \
    CAP_CHOWN            \
    CAP_FSETID           \
    CAP_KILL             \
    CAP_MKNOD            \
    CAP_NET_BIND_SERVICE \
    CAP_NET_RAW          \
    CAP_SETFCAP          \
    CAP_SETPCAP
ProcessTwo=yes
LinkJournal=no
Timezone=no
    [Exec]
    WorkingDirectory=/
    Parameters=bin/fossil server                \
        --baseurl https://example.com/myproject \
        --create                                \
        --jsmode bundled                        \
        --localhost                             \
        --port 9000                             \
        --scgi                                  \
        --user admin                            \
        museum/repo.fossil
    DropCapability=          \
        CAP_AUDIT_WRITE      \
        CAP_CHOWN            \
        CAP_FSETID           \
        CAP_KILL             \
        CAP_MKNOD            \
        CAP_NET_BIND_SERVICE \
        CAP_NET_RAW          \
        CAP_SETFCAP          \
        CAP_SETPCAP
    ProcessTwo=yes
    LinkJournal=no
    Timezone=no

[Files]
Bind=/home/fossil/museum/myproject:/museum
    [Files]
    Bind=/home/fossil/museum/myproject:/museum

[Network]
VirtualEthernet=no
    [Network]
    VirtualEthernet=no
```

----

If you recognize most of that from the `Dockerfile` discussion above,
congratulations, you’ve been paying attention. The rest should also
be clear from context.

    on the host for the reasons given [above](#bind-mount).

That being done, we also need a generic `systemd` unit file called
`/etc/systemd/system/fossil@.service`, containing:

----

```
[Unit]
Description=Fossil %i Repo Service
Wants=modprobe@tun.service modprobe@loop.service
After=network.target systemd-resolved.service modprobe@tun.service modprobe@loop.service
    [Unit]
    Description=Fossil %i Repo Service
    Wants=modprobe@tun.service modprobe@loop.service
    After=network.target systemd-resolved.service modprobe@tun.service modprobe@loop.service

[Service]
ExecStart=systemd-nspawn --settings=override --read-only --machine=%i bin/fossil
    [Service]
    ExecStart=systemd-nspawn --settings=override --read-only --machine=%i bin/fossil

[Install]
WantedBy=multi-user.target
    [Install]
    WantedBy=multi-user.target
```

----

You shouldn’t have to change any of this because we’ve given the
`--setting=override` flag, meaning any setting in the nspawn file
overrides the setting passed to `systemd-nspawn`.  This arrangement
not only keeps the unit file simple, it allows multiple services to
share the base configuration, varying on a per-repo level through
adjustments to their individual `*.nspawn` files.

You may then start the service in the normal way:

```
  $ sudo systemctl enable fossil@myproject
  $ sudo systemctl start  fossil@myproject
    $ sudo systemctl enable fossil@myproject
    $ sudo systemctl start  fossil@myproject
```

You should then find it running on localhost port 9000 per the nspawn
configuration file above, suitable for proxying Fossil out to the
public using nginx via SCGI. If you aren’t using a front-end proxy
and want Fossil exposed to the world via HTTPS, you might say this instead in
the `*.nspawn` file:

```
Parameters=bin/fossil server \
    --cert /path/to/cert.pem \
    --create                 \
    --jsmode bundled         \
    --port 443               \
    --user admin             \
    museum/repo.fossil
    Parameters=bin/fossil server \
        --cert /path/to/cert.pem \
        --create                 \
        --jsmode bundled         \
        --port 443               \
        --user admin             \
        museum/repo.fossil
```

You would also need to un-drop the `CAP_NET_BIND_SERVICE` capability
to allow Fossil to bind to this low-numbered port.

We use the `systemd` template file feature to allow multiple Fossil
servers running on a single machine, each on a different TCP port,
as when proxying them out as subdirectories of a larger site.
To add another project, you must first clone the base “machine” layer:

```
  $ sudo machinectl clone myproject otherthing
    $ sudo machinectl clone myproject otherthing
```

That will not only create a clone of `/var/lib/machines/myproject`
as `../otherthing`, it will create a matching `otherthing.nspawn` file for you
as a copy of the first one.  Adjust its contents to suit, then enable
and start it as above.

[mcfad]: https://www.freedesktop.org/software/systemd/man/machinectl.html#Files%20and%20Directories


### 6.3.1 <a id="nspawn-rhel"></a>Getting It Working on a RHEL Clone

The biggest difference between doing this on OSes like CentOS versus
Ubuntu is that RHEL (thus also its clones) doesn’t ship btrfs in
its kernel, thus ships with no package repositories containing `mkfs.btrfs`, which
[`machinectl`][mctl] depends on for achieving its various purposes.

Fortunately, there are workarounds.

First, the `apt install` command above becomes:

```
  $ sudo dnf install systemd-container
    $ sudo dnf install systemd-container
```

Second, you have to hack around the lack of `machinectl import-tar`:

```
  $ rootfs=/var/lib/machines/fossil
  $ sudo mkdir -p $rootfs
  $ docker container export fossil | sudo tar -xf -C $rootfs -
    $ rootfs=/var/lib/machines/fossil
    $ sudo mkdir -p $rootfs
    $ docker container export fossil | sudo tar -xf -C $rootfs -
```

The parent directory path in the `rootfs` variable is important,
because although we aren’t able to use `machinectl` on such systems, the
`systemd-nspawn` developers assume you’re using them together; when you give
`--machine`, it assumes the `machinectl` directory scheme.  You could
instead use `--directory`, allowing you to store the rootfs wherever
you like, but why make things difficult?  It’s a perfectly sensible

<title>Customizing The Ticket System</title>
<nowiki>

<h2>Introduction</h2>

This guide will explain how to add the "assigned_to" and "submitted_by" fields
to the ticket system in Fossil, as well as making the system more useful.  You
must have "admin" access to the repository to implement these instructions.

<h2>First modify the TICKET table</h2>

<blockquote>
Click on the "Admin" menu, then "Tickets", then "Table".  After the other fields
and before the final ")", insert:
<pre>
  ,
  assigned_to TEXT,
  opened_by TEXT
</pre>

And "Apply Changes".  You have just added two more fields to the ticket
database!  NOTE: I won't tell you to "Apply Changes" after each step from here
on out.  Now, how do you use these fields?
</blockquote>

<h2>Next add assignees</h2>

<blockquote>
Back to the "Tickets" admin page, and click "Common".  Add something like this:
<pre>
set assigned_choices {
  unassigned
  tom
  dick
  harriet
}
</pre>

Obviously, choose names corresponding to the logins on your system.  The
'unassigned' entry is important, as it prevents you from having a NULL in that
field (which causes problems later when editing).
</blockquote>

<h2>Now modify the 'new ticket' page</h2>

<blockquote>
Back to the "Tickets" admin page, and click "New Ticket Page".  This is a little
more tricky.  Edit the top part:
<pre>
  if {[info exists submit]} {
     set status Open
     set opened_by $login
	 set assigned_to "unassigned"
     submit_ticket
  }
</pre>

<verbatim>
if {[info exists submit]} {
  set status Open
  set opened_by $login
  set assigned_to "unassigned"
  submit_ticket
}
</verbatim>

Note the "set opened_by" bit -- that will automatically set the "opened_by"
field to the login name of the bug reporter.  Now, skip to the part with "EMail"
and modify it like so:
<pre>
&lt;th1>enable_output [expr { "$login" eq "anonymous"}]&lt;/th1>
&lt;tr>
&lt;td align="right">EMail:
&lt;input type="text" name="private_contact" value="$&lt;private_contact>" size="30">
&lt;/td>
&lt;td>&lt;u>Not publicly visible&lt;/u>. Used by developers to contact you with
questions.&lt;/td>
&lt;/tr>
&lt;th1>enable_output 1&lt;/th1>
</pre>

<verbatim>
<th1>enable_output expr { "$login" eq "anonymous"}</th1>
<tr>
<td align="right">
  EMail:
  <input type="text" name="private_contact" value="$<private_contact>" size="30">
</td>
<td>
  <u>Not publicly visible</u>. Used by developers to contact you with questions.
</td>
</tr>
<th1>enable_output 1</th1>
</verbatim>

This bit of code will get rid of the "email" field entry for logged-in users.
Since we know the user's information, we don't have to ask for it. NOTE: it
might be good to automatically scoop up the user's email and put it here.

You might also want to enable people to actually assign the ticket to a specific
person during creation. For this to work, you need to add the code
for "assigned_to" as shown below under the heading "Modify the 'edit ticket' page".
This will give you an additional combobox where you can choose a person during
ticket creation.
</blockquote>

<h2>Modify the 'view ticket' page</h2>

<blockquote>
Look for the text "Contact:" (about halfway through).  Then insert these lines
after the closing tr tag and before the "enable_output" line:
<pre>
<tr>
  &lt;td align="right">Assigned to:&lt;/td>&lt;td bgcolor="#d0d0d0">
  $&lt;assigned_to>
  &lt;/td>
  &lt;td align="right">Opened by:&lt;/td>&lt;td bgcolor="#d0d0d0">
  $&lt;opened_by>
  &lt;/td>
</pre>

<verbatim>
<td align="right">Assigned to:</td><td bgcolor="#d0d0d0">
  $<assigned_to>
</td>
<td align="right">Opened by:</td><td bgcolor="#d0d0d0">
  $<opened_by>
</td>
</verbatim>

This will add a row which displays these two fields, in the event the user has
<a href="./caps/ref.html#w">ticket "edit" capability</a>.
</blockquote>

<h2>Modify the 'edit ticket' page</h2>

<blockquote>
Before the "Severity:" line, add this:
<pre>
&lt;tr>&lt;td align="right">Assigned to:&lt;/td>&lt;td>
&lt;th1>combobox assigned_to $assigned_choices 1&lt;/th1>
&lt;/td>&lt;/tr>
</pre>

<verbatim>
<tr>
  <td align="right">Assigned to:</td>
  <td>
      <th1>combobox assigned_to $assigned_choices 1</th1>
  </td>
</tr>
</verbatim>

That will give you a drop-down list of assignees. The first argument to the TH1
command 'combobox' is the database field which the combobox is associated to.
The next argument is the list of choices you want to show in the combobox (and
that you specified in the second step above. The last argument should be 1 for a
true combobox (see the <a href="th1.md#combobox">TH1 documentation</a> for
details).

Now, similar to the previous
section, look for "Contact:" and add this:
<pre>
  &lt;tr>&lt;td align="right">Reported by:&lt;/td>&lt;td>
  &lt;input type="text" name="opened_by" size="40"

<verbatim>
<tr>
  <td align="right">Reported by:</td>
  <td>
    <input type="text" name="opened_by" size="40" value="$<opened_by>">
   value="$&lt;opened_by>">
  &lt;/td>&lt;/tr>
</pre>
</blockquote>
  </td>
</tr>
</verbatim>

<h2>What next?</h2>

<blockquote>
Now you can add custom reports which select based on the person to whom the
ticket is assigned.  For example, an "Assigned to me" report could be:
<pre>

<verbatim>
SELECT
  CASE WHEN status IN ('Open','Verified') THEN '#f2dcdc'
       WHEN status='Review' THEN '#e8e8e8'
       WHEN status='Fixed' THEN '#cfe8bd'
       WHEN status='Tested' THEN '#bde5d6'
       WHEN status='Deferred' THEN '#cacae5'
       ELSE '#c8c8c8' END AS 'bgcolor',
  substr(tkt_uuid,1,10) AS '#',
  datetime(tkt_mtime) AS 'mtime',
  type,
  status,
  subsystem,
  title
FROM ticket
WHERE assigned_to=user()
</pre>
</verbatim>
</blockquote>
</nowiki>

When cloning a repository, the skin of the new repository is initialized to
the skin of the repository from which it was cloned.

# Structure Of A Fossil Web Page

Every HTML page generated by Fossil has the same basic structure:

<blockquote><table border=1 cellpadding=10><tbody>
<tr><td style='background-color:lightgreen;text-align:center;'>
Fossil-Generated HTML Header</td></tr>
<tr><td style='background-color:lightblue;text-align:center;'>Content Header</td></tr>
| Fossil-Generated HTML Header |
| Content Header               |
<tr><td style='background-color:lightgreen;text-align:center;'>
Fossil-Generated Content</td></tr>
<tr><td style='background-color:lightblue;text-align:center;'>Content Footer</td></tr>
| Fossil-Generated Content     |
| Content Footer               |
<tr><td style='background-color:lightgreen;text-align:center;'>
Fossil-Generated HTML Footer</td></tr>
| Fossil-Generated HTML Footer |
</tbody></table></blockquote>

The green parts are *usually* generated by Fossil.  The blue parts
are things that you, the administrator, get to modify in order to
customize the skin.

Fossil *usually* (but not always - [see below](#override))
generates the initial HTML Header section of a page.  The
generated HTML Header will look something like this:

         <html>
         <head>
         <base href="...">
         <meta http-equiv="Content-Security-Policy" content="....">
         <meta name="viewport" content="width=device-width, initial-scale=1.0">
         <title>....</title>
         <link rel="stylesheet" href="..." type="text/css">
         </head>
         <body class="FEATURE">
    <html>
    <head>
    <base href="...">
    <meta http-equiv="Content-Security-Policy" content="....">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>....</title>
    <link rel="stylesheet" href="..." type="text/css">
    </head>
    <body class="FEATURE">

…where `FEATURE` is either the top-level URL element (e.g. `doc`) or a
feature class that groups multiple URLs under a single name such as
`forum` to contain `/forummain`, `/forumpost`, `/forume2`, etc. This
allows per-feature CSS such as

         body.forum div.markdown blockquote {
           margin-left: 10px;
         }
     body.forum div.markdown blockquote {
       margin-left: 10px;
     }

That is, affect HTML `<blockquote>` tags specially only for forum posts
written in Markdown, leaving all other block quotes alone.

In most cases, it is best to leave the Fossil-generated HTML Header
alone. (One exception is when the administrator needs to include links
to additional CSS files.) The configurable part of the skin begins
with the Content Header section which should follow this template:

        <div class="header">
          ... top banner and menu bar ...
        </div>
    <div class="header">
      ... top banner and menu bar ...
    </div>

Note that `<div class="header">` and `</div>` tags must be included in
the Content Header text of the skin.  In other words, you, the
administrator, need to supply that text as part of your skin
customization.

The Fossil-generated Content section immediately follows the Content Header.
The Content section will looks like this:

        <div class="content">
          ... Fossil-generated content here ...
        </div>
    <div class="content">
      ... Fossil-generated content here ...
    </div>

After the Content is the custom Content Footer section which should
follow this template:

        <div class="footer">
          ... skin-specific stuff here ...
        </div>
    <div class="footer">
      ... skin-specific stuff here ...
    </div>

As with the Content Header, the template elements of the Content Footer
should appear exactly as they are shown.

Finally, Fossil always adds its own footer (unless overridden)
to close out the generated HTML:

        </body>
        </html>
    </body>
    </html>

## <a id="mainmenu"></a>Changing the Main Menu Contents

As of Fossil 2.15, the actual text content of the skin’s main menu is no
longer part of the skin proper if you’re using one of the stock skins.
If you look at the Header section of the skin, you’ll find a
`<div class="mainmenu">` element whose contents are set by a short

It is possible to develop a new skin from scratch.  But a better and easier
approach is to use one of the existing built-in skins as a baseline and
make incremental modifications, testing after each step, to obtain the
desired result.

The skin is controlled by five files:

<blockquote><dl>
<dl>
<dt><b>css.txt</b></dt>

<dd>The css.txt file is the text of the CSS for Fossil.
Fossil might add additional CSS elements after
the css.txt file, if it sees that the css.txt omits some
CSS components that Fossil needs.  But for the most part,
the content of the css.txt is the CSS for the page.</dd>

<dt><b>details.txt</b><dt>

<dd>The details.txt file is short list of settings that control
the look and feel, mostly of the timeline.  The default
details.txt file looks like this:

<blockquote><pre>
<pre>
pikchr-background:          ""
pikchr-fontscale:           ""
pikchr-foreground:          ""
pikchr-scale:               ""
timeline-arrowheads:        1
timeline-circle-nodes:      1
timeline-color-graph-lines: 1
white-foreground:           0
</pre></blockquote>
</pre>

The three "timeline-" settings in details.txt control the appearance
of certain aspects of the timeline graph.  The number on the
right is a boolean - "1" to activate the feature and "0" to
disable it.  The "white-foreground:" setting should be set to
"1" if the page color has light-color text on a darker background,
and "0" if the page has dark text on a light-colored background.

<dt><b>js.txt</b></dt>

<dd>The js.txt file is optional.  It is intended to be javascript.
The complete text of this javascript might be inserted into
the Content Footer, after being processed using TH1, using
code like the following in the "footer.txt" file:

<blockquote><pre>
<pre>
&lt;script nonce="$nonce"&gt;
  &lt;th1&gt;styleScript&lt;/th1&gt;
&lt;/script&gt;
</pre></blockquote>
</pre>

The js.txt file was originally used to insert javascript
that controls the hamburger menu in the default skin.  More
recently, the javascript for the hamburger menu was moved into
a separate built-in file.  Skins that use the hamburger menu
typically cause the javascript to be loaded by including the
following TH1 code in the "header.txt" file:

<blockquote><pre>
<pre>
&lt;th1&gt;builtin_request_js hbmenu.js&lt;/th1&gt;
</pre></blockquote>
</pre>

The difference between styleScript and builtin_request_js
is that the styleScript command interprets the file
using TH1 and injects the content directly into the output
stream, whereas the builtin_request_js command inserts the
javascript verbatim and does so at some unspecified future time
down inside the Fossil-generated footer.  The built-in skins
of Fossil originally used the styleScript command to load
the hamburger menu javascript, but as of version 2.15 switched
to using the builtin_request_js method.  You can use either
approach in custom skins that you right yourself.

Note that the "js.txt" file is *not* automatically inserted into
the generate HTML for a page.  You, the skin designer, must
cause the javascript to be inserted by issuing appropriate
TH1 commands in the "header.txt" or "footer.txt" files.</dd>
</dl></blockquote>
</dl>

Developing a new skin is simply a matter of creating appropriate
versions of these five control files.

### Skin Development Using The Web Interface

Users with admin privileges can use the Admin/Skin configuration page

  *  Text of the form "$NAME" or "$<NAME>" is replaced with
     the value of the TH1 variable NAME.

For example, first few lines of a typical Content Header will look
like this:

        <div class="header">
          <div class="title"><h1>$<project_name></h1>$<title>/div>
    <div class="header">
      <div class="title"><h1>$<project_name></h1>$<title>/div>

After variables are substituted by TH1, that will look more like this:

        <div class="header">
          <div class="title"><h1>Project Name</h1>Page Title</div>
    <div class="header">
      <div class="title"><h1>Project Name</h1>Page Title</div>

As you can see, two TH1 variable substitutions were done.

The same TH1 interpreter is used for both the header and the footer
and for all scripts contained within them both.  Hence, any global
TH1 variables that are set by the header are available to the footer.

## <a id="menu"></a>Customizing the ≡ Hamburger Menu

The menu bar of the default skin has an entry to open a drop-down menu with
additional navigation links, represented by the ≡ button (hence the name
"hamburger menu"). The Javascript logic to open and close the hamburger menu
when the button is clicked is usually handled by a script named
"hbmenu.js" that is one of the [built-in resource files](/test-builtin-files)
that are part of Fossil.

The ≡ button for the hamburger menu is added to the menu bar by the following
TH1 commands in the `header.txt` file, right before the menu bar links:

        html "<a id='hbbtn' href='$home/sitemap'>&#9776;</a>"
        builtin_request_js hbmenu.js
    html "<a id='hbbtn' href='$home/sitemap'>&#9776;</a>"
    builtin_request_js hbmenu.js

The hamburger button can be repositioned between the other menu links (but the
drop-down menu is always left-aligned with the menu bar), or it can be removed
by deleting the above statements.  The "html" statement inserts the appropriate
`<a>` for the hamburger menu button (some skins require something slightly
different - for example the ardoise skins wants "`<li><a>`").  The
"builtin_request_js hbmenu.js" asks Fossil to include the "hbmenu.js" 
resource files in the Fossil-generated footer.

The hbmenu.js script requires
the following `<div>` element somewhere in your header, in which to build
the hamburger menu.

        <div id='hbdrop'></div>
    <div id='hbdrop'></div>

Out of the box, the contents of the panel is populated with the [Site
Map](/sitemap), but only if the panel does not already contain any HTML
elements (that is, not just comments, plain text or non-presentational white
space). So the hamburger menu can be customized by replacing the empty `<div
id='hbdrop'></div>` element with a menu structure knitted according to the
following template:

        <div id="hbdrop" data-anim-ms="400">
         <ul class="columns" style="column-width: 20em; column-count: auto">
          <!-- NEW GROUP WITH HEADING LINK -->
          <li>
           <a href="$home$index_page">Link: Home</a>
           <ul>
            <li><a href="$home/timeline">Link: Timeline</a></li>
            <li><a href="$home/dir?ci=tip">Link: File List</a></li>
           </ul>
          </li>
          <!-- NEW GROUP WITH HEADING TEXT -->
          <li>
           Heading Text
           <ul>
            <li><a href="$home/doc/trunk/www/customskin.md">Link: Theming</a></li>
            <li><a href="$home/doc/trunk/www/th1.md">Link: TH1 Scripts</a></li>
           </ul>
          </li>
          <!-- NEXT GROUP GOES HERE -->
         </ul>
        </div>
    <div id="hbdrop" data-anim-ms="400">
     <ul class="columns" style="column-width: 20em; column-count: auto">
      <!-- NEW GROUP WITH HEADING LINK -->
      <li>
       <a href="$home$index_page">Link: Home</a>
       <ul>
        <li><a href="$home/timeline">Link: Timeline</a></li>
        <li><a href="$home/dir?ci=tip">Link: File List</a></li>
       </ul>
      </li>
      <!-- NEW GROUP WITH HEADING TEXT -->
      <li>
       Heading Text
       <ul>
        <li><a href="$home/doc/trunk/www/customskin.md">Link: Theming</a></li>
        <li><a href="$home/doc/trunk/www/th1.md">Link: TH1 Scripts</a></li>
       </ul>
      </li>
      <!-- NEXT GROUP GOES HERE -->
     </ul>
    </div>

The custom `data-anim-ms` attribute can be added to the panel element to direct
the Javascript logic to override the default menu animation duration of 400 ms.
A faster animation duration of 80-200 ms may be preferred for smaller menus. The
animation is disabled by setting the attribute to `"0"`.

bugs that might lead to a vulnerability.

## The Default Restrictions

The default CSP used by Fossil is as follows:

<pre>
     default-src 'self' data:;
     script-src 'self' 'nonce-$nonce';
     style-src 'self' 'unsafe-inline';
     img-src * data:;
default-src 'self' data:;
script-src 'self' 'nonce-$nonce';
style-src 'self' 'unsafe-inline';
img-src * data:;
</pre>

The default is recommended for most installations.  However,
the site administrators can overwrite this default CSP using the
[default-csp setting](/help?cmd=default-csp).  For example,
CSP restrictions can be completely disabled by setting the default-csp to:

<pre>
     default-src *;
    default-src *;
</pre>

The following sections detail the maining of the default CSP setting.

### <a id="base"></a> default-src 'self' data:

This policy means mixed-origin content isn’t allowed, so you can’t refer
to resources on other web domains. Browsers will ignore a link like the
one in the following Markdown under our default CSP:

         ![fancy 3D Fossil logotype](https://i.imgur.com/HalpMgt.png)
    ![fancy 3D Fossil logotype](https://i.imgur.com/HalpMgt.png)

If you look in the browser’s developer console, you should see a CSP
error when attempting to render such a page.

The default policy does allow inline `data:` URIs, which means you could
[data-encode][de] your image content and put it inline within the
document:

         ![small inline image](data:image/gif;base64,R0lGODlh...)
    ![small inline image](data:image/gif;base64,R0lGODlh...)

That method is best used for fairly small resources. Large `data:` URIs
are hard to read and edit. There are secondary problems as well: if you
put a large image into a Fossil forum post this way, anyone subscribed
to email alerts will get a copy of the raw URI text, which can amount to
pages and pages of [ugly Base64-encoded text][b64].

For inline images within [embedded documentation][ed], it suffices to
store the referred-to files in the repo and then refer to them using
repo-relative URLs:

         ![large inline image](./inlineimage.jpg)
    ![large inline image](./inlineimage.jpg)

This avoids bloating the doc text with `data:` URI blobs:

There are many other cases, [covered below](#serving).

[b64]: https://en.wikipedia.org/wiki/Base64
[svr]: ./server/

This policy allows CSS information to come from separate files hosted
under the Fossil repo server’s Internet domain. It also allows inline CSS
`<style>` tags within the document text.

The `'unsafe-inline'` declaration allows CSS within individual HTML
elements:

        <p style="margin-left: 4em">Indented text.</p>
    <p style="margin-left: 4em">Indented text.</p>

As the "`unsafe-`" prefix on the name implies, the `'unsafe-inline'`
feature is suboptimal for security.  However, there are
a few places in the Fossil-generated HTML that benefit from this
flexibility and the work-arounds are verbose and difficult to maintain.
Furthermore, the harm that can be done with style injections is far
less than the harm possible with injected javascript.  And so the

offers free Fossil repository hosting to anyone on the Internet, all
served under the same `http://chiselapp.com/user/$NAME/$REPO` URL
scheme. Any one of those hundreds of repositories could trick you into
visiting their repository home page, set to [an HTML-formatted embedded
doc page][hfed] via Admin → Configuration → Index Page, with this
content:

         <script src="/doc/trunk/bad.js"></script>
    <script src="/doc/trunk/bad.js"></script>

That script can then do anything allowed in JavaScript to *any other*
Chisel repository your browser can access. The possibilities for mischief
are *vast*. For just one example, if you have login cookies on four
different Chisel repositories, your attacker could harvest the login
cookies for all of them through this path if we allowed Fossil to serve
JavaScript files under the same CSP policy as we do for CSS files.

path around this restriction.  If you are serving a Fossil repository
that has any user you do not implicitly trust to a level that you would
willingly run any JavaScript code they’ve provided, blind, you **must
not** give the `--with-th1-docs` option when configuring Fossil, because
that allows substitution of the [pre-defined `$nonce` TH1
variable](./th1.md#nonce) into [HTML-formatted embedded docs][hfed]:

         <script src="/doc/trunk/bad.js" nonce="$nonce"></script>
    <script src="/doc/trunk/bad.js" nonce="$nonce"></script>

Even with this feature enabled, you cannot put `<script>` tags into
Fossil Wiki or Markdown-formatted content, because our HTML generators
for those formats purposely strip or disable such tags in the output.
Therefore, if you trust those users with check-in rights to provide
JavaScript but not those allowed to file tickets, append to wiki
articles, etc., you might justify enabling TH1 docs on your repository,

Changing this setting is the easiest way to set a nonstandard CSP on
your site.

Because a blank setting tells Fossil to use its hard-coded default CSP,
you have to say something like the following to get a repository without
content security policy restrictions:

        $ fossil set -R /path/to/served/repo.fossil default-csp 'default-src *'
    $ fossil set -R /path/to/served/repo.fossil default-csp 'default-src *'

We recommend that instead of using the command line to change this
setting that you do it via the repository’s web interface, in
Admin → Settings.  Write your CSP rules in the edit box marked
"`default-csp`". Do not add hard newlines in that box: the setting needs
to be on a single long line. Beware that changes take effect
immediately, so be careful with your edits: you could end up locking

`default-csp` setting and uses *that* to inject the value into generated
HTML pages in its stock configuration.

This means that another way you can override this value is to use
the [`th1-setup` hook script](./th1-hooks.md), which runs before TH1
processing happens during skin processing:

        $ fossil set th1-setup "set default_csp {default-src 'self'}"
    $ fossil set th1-setup "set default_csp {default-src 'self'}"

After [the above](#admin-ui), this is the cleanest method.

[thvar]: ./customskin.md#vars

# Delta Manifests

<div class="sidebar">Do not confuse these with the core [Fossil delta
format](./delta_format.wiki). This document describes an optional
feature not enabled by default.</div>

This article describes "delta manifests," a special-case form of
checkin manifest which is intended to take up far less space than
a normal checkin manifest, in particular for repositories with
many files. We'll see, however, that the space savings, if indeed
there are any, come with some caveats.

This article assumes that the reader is at least moderately familiar
with Fossil's [artifact file format](./fileformat.wiki), in particular
the structure of checkin manifests, and it won't make much sense to
readers unfamiliar with that topic.

Sidebar: delta manifests are not to be confused with the core [Fossil
delta format](./delta_format.wiki). The former is a special-case form
of delta which applies *only* to checkin manifests whereas the latter
is a general-purpose delta compression which can apply to any
Fossil-stored data (including delta manifests).

# Background and Motivation of Delta Manifests

A checkin manifest includes a list of every file in that checkin.  A
moderately-sized project can easily have a thousand files, and every
checkin manifest will include those thousand files. As of this writing
Fossil's own checkins contain 989 files and the manifests are 80kb
each. Thus a checkin which changes only 2 bytes of source code

The format currently handles only 32 bit integer numbers. They are
written base-64 encoded, MSB first, and without leading
"0"-characters, except if they are significant (i.e. 0 => "0").

The base-64 encoding uses one character for each 6 bits of
the integer to be encoded.  The encoding characters are:

<blockquote><pre>
<pre>
0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz~
</pre></blockquote>
</pre>

The least significant 6 bits of the integer are encoded by
the first character, followed by
the next 6 bits, and so on until all non-zero bits of the integer
are encoded.  The minimum number of encoding characters is used.
Note that for integers less than 10, the base-64 coding is a
ASCII decimal rendering of the number itself.

<h1 id="examples">4.0 Examples</h1>

<h2 id="examplesint">4.1 Integer encoding</h2>

<table border=1>
<table>
<tr>
<th>Value</th>
<th>Encoding</th>
</tr>
<tr>
<td>0</td>
<td>0</td>

</tr>
</table>

<h2 id="examplesdelta">4.2 Delta encoding</h2>

An example of a delta using the specified encoding is:

<table border=1><tr><td><pre>
<pre>
1Xb
4E@0,2:thFN@4C,6:scenda1B@Jd,6:scenda5x@Kt,6:pieces79@Qt,F: Example: eskil~E@Y0,2zMM3E;</pre>
</td></tr></table>
</pre>

This can be taken apart into the following parts:

<table border=1>
<table>
<tr><th>What  </th> <th>Encoding         </th><th>Meaning </th><th>Details</th></tr>
<tr><td>Header</td> <td>1Xb              </td><td>Size    </td><td> 6246         </td></tr>
<tr><td>S-List</td> <td>4E@0,            </td><td>Copy    </td><td> 270 @ 0      </td></tr>
<tr><td>&nbsp;</td> <td>2:th             </td><td>Literal </td><td> 2 'th'       </td></tr>
<tr><td>&nbsp;</td> <td>FN@4C,           </td><td>Copy    </td><td> 983 @ 268        </td></tr>
<tr><td>&nbsp;</td> <td>6:scenda         </td><td>Literal </td><td> 6 'scenda'       </td></tr>
<tr><td>&nbsp;</td> <td>1B@Jd,           </td><td>Copy    </td><td> 75 @ 1256        </td></tr>
<tr><td>&nbsp;</td> <td>6:scenda         </td><td>Literal </td><td> 6 'scenda'       </td></tr>
<tr><td>&nbsp;</td> <td>5x@Kt,           </td><td>Copy    </td><td> 380 @ 1336       </td></tr>
<tr><td>&nbsp;</td> <td>6:pieces     </td><td>Literal </td><td> 6 'pieces'       </td></tr>
<tr><td>&nbsp;</td> <td>79@Qt,           </td><td>Copy    </td><td> 457 @ 1720     </td></tr>
<tr><td>&nbsp;</td> <td>F: Example: eskil</td><td>Literal </td><td> 15 ' Example: eskil'</td></tr>
<tr><td>&nbsp;</td> <td>~E@Y0,           </td><td>Copy    </td><td>  4046 @ 2176        </td></tr>
<tr><td>Trailer</td><td>2zMM3E           </td><td>Checksum</td><td> -1101438770         </td></tr>
</table>

The unified diff behind the above delta is

<table border=1><tr><td><pre>
<verbatim>
bluepeak:(761) ~/Projects/Tcl/Fossil/Devel/devel > diff -u ../DELTA/old ../DELTA/new
--- ../DELTA/old        2007-08-23 21:14:40.000000000 -0700
+++ ../DELTA/new        2007-08-23 21:14:33.000000000 -0700
@@ -5,7 +5,7 @@

  *  If the server does not have write permission on the database
     file, or on the directory containing the database file (and

     single file.  Allow diffs against any two arbitrary versions,
     not just diffs against the current check-out.  Allow
     configuration options to replace tkdiff with some other
-    visual differ of the users choice.
+    visual differ of the users choice. Example: eskil.

  *  Ticketing interface (expand this bullet)

</verbatim>
</pre></td></tr></table>



<h1 id="notes">Notes</h1>

<ul>
<li>Pure text files generate a pure text delta.

<title>Project Documentation</title>
<h1 align="center">Project Documentation</h1>

Fossil provides a built-in <a href="wikitheory.wiki">wiki</a>
that can be used to store the
documentation for a project.  This is sufficient for many projects.
If your project is well-served by wiki documentation, then you
need read no further.

<h1>1.0 Fossil Support For Embedded Documentation</h1>

The fossil web interface supports embedded documentation using
the "/doc" page.  To access embedded documentation, one points
a web browser to a fossil URL of the following form:

<blockquote>
<pre>
<i>&lt;baseurl&gt;</i><big><b>/doc/</b></big><i>&lt;version&gt;</i><big><b>/</b></big><i>&lt;filename&gt;</i>
</blockquote>
</pre>

The <i>&lt;baseurl&gt;</i> is the main URL used to access the fossil web server.
For example, the <i>&lt;baseurl&gt;</i> for the fossil project itself is
[https://fossil-scm.org/home].
If you launch the web server using the "[/help?cmd=ui|fossil ui]" command line,
then the <i>&lt;baseurl&gt;</i> is usually
<b>http://localhost:8080/</b>.

Hyperlinks in Markdown and HTML embedded documents can reference 
the root of the Fossil repository using the special text "$ROOT"
at the beginning of a URL. For example, a Markdown hyperlink to
the Markdown formatting rules might be
written in the embedded document like this:

<nowiki><pre>
        [Markdown formatting rules]($ROOT/wiki_rules)
</pre></nowiki>
<verbatim>
[Markdown formatting rules]($ROOT/wiki_rules)
</verbatim>

Depending on how the how the Fossil server is configured, that hyperlink
might be renderer like one of the following:

<nowiki><pre>
        &lt;a href="/wiki_rules"&gt;Wiki formatting rules&lt;/a&gt;
        &lt;a href="/cgi-bin/fossil/wiki_rules"&gt;Wiki formatting rules&lt;/a&gt;
</pre></nowiki>
<verbatim>
<a href="/wiki_rules">Wiki formatting rule</a>
<a href="/cgi-bin/fossil/wiki_rules">Wiki formatting rules</a>
</verbatim>

So, in other words, the "$ROOT" text is converted into whatever
the "&lt;baseurl&gt;" is for the document.

This substitution works for HTML and Markdown documents.
It does not work for Wiki embedded documents, since with
Wiki you can just begin a URL with "/" and it automatically knows
to prepend the $ROOT.

<h2>2.2 "$CURRENT" In "/doc/" Hyperlinks</h2>

Similarly, URLs of the form "/doc/$CURRENT/..." have the check-in
hash of the check-in currently being viewed substituted in place of
the "$CURRENT" text.  This feature, in combination with the "$ROOT"
substitution above, allows an absolute path to be used for hyperlinks.

For example, if an embedded document documented wanted to reference
some other document in a separate file named "www/otherdoc.md",
it could use a URL like this:

<nowiki><pre>
        [Other Document]($ROOT/doc/$CURRENT/www/otherdoc.md)
</pre></nowiki>
<verbatim>
[Other Document]($ROOT/doc/$CURRENT/www/otherdoc.md)
</verbatim>

As with "$ROOT", this substitution only works for Markdown and HTML
documents.  For Wiki documents, you would need to use a relative URL.

<h2 id="th1">2.3 TH1 Documents</h2>

Fossil will substitute the value of [./th1.md | TH1 expressions] within

This file that you are currently reading is an example of
embedded documentation.  The name of this file in the fossil
source tree is "<b>www/embeddeddoc.wiki</b>".
You are perhaps looking at this
file using the URL:

   [https://fossil-scm.org/home/doc/trunk/www/embeddeddoc.wiki].
<pre>[https://fossil-scm.org/home/doc/trunk/www/embeddeddoc.wiki]</pre>

The first part of this path, the "[https://fossil-scm.org/home]",
is the base URL.  You might have originally typed:
[https://fossil-scm.org/].  The web server at the fossil-scm.org
site automatically redirects such links by appending "home".  The
"home" file on fossil-scm.org is really a [./server/any/cgi.md|CGI script]
which runs the fossil web service in CGI mode.
The "home" CGI script looks like this:

<blockquote><pre>
<pre>
#!/usr/bin/fossil
repository: /fossil/fossil.fossil
</pre></blockquote>
</pre>

This is one of the many ways to set up a
<a href="./server/">Fossil server</a>.

The "<b>/trunk/</b>" part of the URL tells fossil to use
the documentation files from the most recent trunk check-in.
If you wanted to see an historical version of this document,

</ul>

When the symbolic name is a date and time, fossil shows the version
of the document that was most recently checked in as of the date
and time specified.  So, for example, to see what the fossil website
looked like at the beginning of 2010, enter:

<blockquote>
<a href="/doc/2010-01-01/www/index.wiki">
https://fossil-scm.org/home/doc/<b>2010-01-01</b>/www/index.wiki
</a>
<pre><a href="/doc/2010-01-01/www/index.wiki">https://fossil-scm.org/home/doc/<b>2010-01-01</b>/www/index.wiki
</a></pre>
</blockquote>

The file that encodes this document is stored in the fossil source tree under
the name "<b>www/embeddeddoc.wiki</b>" and so that name forms the
last part of the URL for this document.

As I sit writing this documentation file, I am testing my work by
running the "<b>fossil ui</b>" command line and viewing
<b>http://localhost:8080/doc/ckout/www/embeddeddoc.wiki</b> in
Firefox.  I am doing this even though I have not yet checked in
the "<b>www/embeddeddoc.wiki</b>" file for the first time.  Using
the special "<b>ckout</b>" version identifier on the "<b>/doc</b>" page
it is easy to make multiple changes to multiple files and see how they all
look together before committing anything to the repository.

<title>How To Use Encrypted Repositories</title>

<h2>Introduction</h2><blockquote>
<h2>Introduction</h2>

Fossil can be compiled so that it works with encrypted repositories using
the [https://www.sqlite.org/see/doc/trunk/www/readme.wiki|SQLite Encryption Extension].
This technical note explains the process.
</blockquote>
<h2>Building An Encryption-Enabled Fossil</h2><blockquote>

<h2>Building An Encryption-Enabled Fossil</h2>

The SQLite Encryption Extension (SEE) is proprietary software and requires
[https://sqlite.org/purchase/see|purchasing a license].

Assuming you have an SEE license, the first step of compiling Fossil to
use SEE is to create an SEE-enabled version of the SQLite database source code.
This alternative SQLite database source file should be called "sqlite3-see.c"
and should be placed in the extsrc/ subfolder of the Fossil sources, right beside
the public-domain "sqlite3.c" source file.  Also make a copy of the SEE-enabled
"shell.c" file, renamed as "shell-see.c", and place it in the extsrc/ subfolder
beside the original "shell.c".

Add the --with-see command-line option to the configuration script to enable
the use of SEE on unix-like systems.

<blockquote><pre>
<pre>
./configure --with-see; make
</pre></blockquote>
</pre>

To build for Windows using MSVC, add
the "USE_SEE=1" argument to the "nmake" command line.

<blockquote><pre>
<pre>
nmake -f makefile.msc USE_SEE=1
</pre></blockquote>
</blockquote>
<h2>Using Encrypted Repositories</h2><blockquote>
</pre>

<h2>Using Encrypted Repositories</h2>

Any Fossil repositories whose filename ends with ".efossil" is taken to be
an encrypted repository.  Fossil will prompt for the encryption password and
attempt to open the repository database using that password.

Every invocation of fossil on an encrypted repository requires retyping the
encryption password.
To avoid excess password typing, consider using the "fossil shell"
command which prompts for the password just once, then reuses it for each
subsequent Fossil command entered at the prompt.

On Windows, the "fossil server", "fossil ui", and "fossil shell" commands do not
(currently) work on an encrypted repository.
</blockquote>
<h2>Additional Security</h2><blockquote>

<h2>Additional Security</h2>

Use the FOSSIL_SECURITY_LEVEL environment for additional protection.

<blockquote><pre>
<pre>
export FOSSIL_SECURITY_LEVEL=1
</pre></blockquote>
</pre>

A setting of 1 or greater
prevents fossil from trying to remember the previous sync password.

<blockquote><pre>
<pre>
export FOSSIL_SECURITY_LEVEL=2
</pre></blockquote>
</pre>

A setting of 2 or greater
causes all password prompts to be preceded by a random translation matrix similar
to the following:

<blockquote><pre>
<pre>
abcde fghij klmno pqrst uvwyz
qresw gjymu dpcoa fhkzv inlbt
</pre></blockquote>
</pre>

When entering the password, the user must substitute the letter on the second
line that corresponds to the letter on the first line.  Uppercase substitutes
for uppercase inputs, and lowercase substitutes for lowercase inputs.  Letters
that are not in the translation matrix (digits, punctuation, and "x") are not
modified.  For example, given the
translation matrix above, if the password is "pilot-9crazy-xube", then the user
must type "fmpav-9ekqtb-xirw".  This simple substitution cypher helps prevent
password capture by keyloggers.
</blockquote>

There is a hyperlink under the /wikihelp menu that can be used to create
new technotes.  And there is a submenu hyperlink on technote displays for
editing existing technotes.

Technotes can also be created using the <b>wiki create</b> command:

<blockquote>
<b>
fossil wiki create TestTechnote -t now --technote-bgcolor lightgreen technote.md<br>
<tt>Created new tech note 2021-03-15 13:05:56</tt><br>
</b>
<verbatim>
fossil wiki create TestTechnote -t now --technote-bgcolor lightgreen technote.md
Created new tech note 2021-03-15 13:05:56
</verbatim>
</blockquote>

This command inserts a light green technote in the timeline at 2021-03-15 13:05:56, with 
the contents of file <b>technote.md</b> and comment "TestTechnote". Specifying a different time using
<b>-t DATETIME</b> will insert the technote at the specified timestamp location in the timeline.
Different technotes can have the same timestamp.

The first argument to create, <b>TECHNOTE-COMMENT</b>, is the title text for the technote
that appears in the timeline. 

To view all technotes, use the <b>wiki ls</b> command:

<blockquote>
<b>
fossil wiki ls --technote --show-technote-ids<br>
<tt>z739263a134bf0da1d28e939f4c4367f51ef4c51 2020-12-19 13:20:19</tt><br>
<tt>e15a918a8bed71c2ac091d74dc397b8d3340d5e1 2018-09-22 17:40:10</tt><br>
</b>
<verbatim>
fossil wiki ls --technote --show-technote-ids
z739263a134bf0da1d28e939f4c4367f51ef4c51 2020-12-19 13:20:19
e15a918a8bed71c2ac091d74dc397b8d3340d5e1 2018-09-22 17:40:10
</verbatim>
</blockquote>

A technote ID is the UUID of the technote.

To view an individual technote, use the <b>wiki export</b> command:

<blockquote>
<b>
fossil wiki export --technote version-2.16<br>
<verbatim>
fossil wiki export --technote version-2.16
Release Notes 2021-07-02

This note describes changes in the Fossil snapshot for ...
</b>
</verbatim>
</blockquote>

The <b>-t|--technote</b> option to the <b>export</b> subcommand takes one of
three identifiers: <b>DATETIME</b>; <b>TECHNOTE-ID</b>; and <b>TAG</b>.
See the [/help?cmd=wiki | wiki help] for specifics.

Users must have check-in privileges (permission "i") in order to
create or edit technotes.  In addition, users must have create-wiki

faq {
  What GUIs are available for fossil?
} {
  The fossil executable comes with a [./webui.wiki | web-based GUI] built in.
  Just run:

  <blockquote>
  <pre>
  <b>fossil [/help/ui|ui]</b> <i>REPOSITORY-FILENAME</i>
  </blockquote>
  </pre>

  And your default web browser should pop up and automatically point to
  the fossil interface.  (Hint:  You can omit the <i>REPOSITORY-FILENAME</i>
  if you are within an open check-out.)
}

faq {

  When you are checking in a new change using the <b>[/help/commit|commit]</b>
  command, you can add the option  "--branch <i>BRANCH-NAME</i>" to
  make the new check-in be the first check-in for a new branch.

  If you want to create a new branch whose initial content is the
  same as an existing check-in, use this command:

  <blockquote>
  <pre>
  <b>fossil [/help/branch|branch] new</b> <i>BRANCH-NAME BASIS</i>
  </blockquote>
  </pre>

  The <i>BRANCH-NAME</i> argument is the name of the new branch and the
  <i>BASIS</i> argument is the name of the check-in that the branch splits
  off from.

  If you already have a fork in your check-in tree and you want to convert
  that fork to a branch, you can do this from the web interface.

  "--tag <i>TAGNAME</i>" command-line option.  You can repeat the --tag
  option to give a check-in multiple tags.  Tags need not be unique.  So,
  for example, it is common to give every released version a "release" tag.

  If you want add a tag to an existing check-in, you can use the
  <b>[/help/tag|tag]</b> command.  For example:

  <blockquote>
  <pre>
  <b>fossil [/help/branch|tag] add</b> <i>TAGNAME</i> <i>CHECK-IN</i>
  </blockquote>
  </pre>

  The CHECK-IN in the previous line can be any
  [./checkin_names.wiki | valid check-in name format].

  You can also add (and remove) tags from a check-in using the
  [./webui.wiki | web interface].  First locate the check-in that you
  what to tag on the timeline, then click on the link to go the detailed

  See the article on [./shunning.wiki | "shunning"] for details.
}

faq {
  How do I make a clone of the fossil self-hosting repository?
} {
  Any of the following commands should work:

  <blockquote><pre>
  <pre>
  fossil [/help/clone|clone]  https://fossil-scm.org/  fossil.fossil
  fossil [/help/clone|clone]  https://www2.fossil-scm.org/  fossil.fossil
  fossil [/help/clone|clone]  https://www3.fossil-scm.org/site.cgi  fossil.fossil
  </pre></blockquote>
  </pre>

  Once you have the repository cloned, you can open a local check-out
  as follows:

  <blockquote><pre>
  <pre>
  mkdir src; cd src; fossil [/help/open|open] ../fossil.fossil
  </pre></blockquote>
  </pre>

  Thereafter you should be able to keep your local check-out up to date
  with the latest code in the public repository by typing:

  <blockquote><pre>
  <pre>
  fossil [/help/update|update]
  </pre></blockquote>
  </pre>
}

faq {
  How do I import or export content from and to other version control systems?
} {
  Please see [./inout.wiki | Import And Export]
}



#############################################################################
# Code to actually generate the FAQ
#
puts "<title>Fossil FAQ</title>"
puts "<title>Fossil FAQ</title>\n"
puts "<h1 align=\"center\">Frequently Asked Questions</h1>\n"
puts "Note: See also <a href=\"qandc.wiki\">Questions and Criticisms</a>.\n"

puts {<ol>}
for {set i 1} {$i<$cnt} {incr i} {
  puts "<li><a href=\"#q$i\">[lindex $faq($i) 0]</a></li>"
}
puts {</ol>}
puts {<hr>}

for {set i 1} {$i<$cnt} {incr i} {
  puts "<p id=\"q$i\"><b>($i) [lindex $faq($i) 0]</b></p>\n"
  set body [lindex $faq($i) 1]
  regsub -all "\n *" [string trim $body] "\n" body
  puts "<blockquote>$body</blockquote></li>\n"
  puts "$body</li>\n"
}
puts {</ol>}

<title>Fossil FAQ</title>
<h1 align="center">Frequently Asked Questions</h1>

Note: See also <a href="qandc.wiki">Questions and Criticisms</a>.

<ol>
<li><a href="#q1">What GUIs are available for fossil?</a></li>
<li><a href="#q2">What is the difference between a "branch" and a "fork"?</a></li>
<li><a href="#q3">How do I create a new branch?</a></li>
<li><a href="#q4">How do I tag a check-in?</a></li>
<li><a href="#q5">How do I create a private branch that won't get pushed back to the
  main repository.</a></li>
<li><a href="#q6">How can I delete inappropriate content from my fossil repository?</a></li>
<li><a href="#q7">How do I make a clone of the fossil self-hosting repository?</a></li>
<li><a href="#q8">How do I import or export content from and to other version control systems?</a></li>
</ol>
<hr>
<p id="q1"><b>(1) What GUIs are available for fossil?</b></p>

<blockquote>The fossil executable comes with a [./webui.wiki | web-based GUI] built in.
The fossil executable comes with a [./webui.wiki | web-based GUI] built in.
Just run:

<blockquote>
<pre>
<b>fossil [/help/ui|ui]</b> <i>REPOSITORY-FILENAME</i>
</blockquote>
</pre>

And your default web browser should pop up and automatically point to
the fossil interface.  (Hint:  You can omit the <i>REPOSITORY-FILENAME</i>
if you are within an open check-out.)</blockquote></li>
if you are within an open check-out.)</li>

<p id="q2"><b>(2) What is the difference between a "branch" and a "fork"?</b></p>

<blockquote>This is a big question - too big to answer in a FAQ.  Please
This is a big question - too big to answer in a FAQ.  Please
read the <a href="branching.wiki">Branching, Forking, Merging,
and Tagging</a> document.</blockquote></li>
and Tagging</a> document.</li>

<p id="q3"><b>(3) How do I create a new branch?</b></p>

<blockquote>There are lots of ways:
There are lots of ways:

When you are checking in a new change using the <b>[/help/commit|commit]</b>
command, you can add the option  "--branch <i>BRANCH-NAME</i>" to
make the new check-in be the first check-in for a new branch.

If you want to create a new branch whose initial content is the
same as an existing check-in, use this command:

<blockquote>
<pre>
<b>fossil [/help/branch|branch] new</b> <i>BRANCH-NAME BASIS</i>
</blockquote>
</pre>

The <i>BRANCH-NAME</i> argument is the name of the new branch and the
<i>BASIS</i> argument is the name of the check-in that the branch splits
off from.

If you already have a fork in your check-in tree and you want to convert
that fork to a branch, you can do this from the web interface.
First locate the check-in that you want to be
the initial check-in of your branch on the timeline and click on its
link so that you are on the <b>ci</b> page.  Then find the "<b>edit</b>"
link (near the "Commands:" label) and click on that.  On the
"Edit Check-in" page, check the box beside "Branching:" and fill in
the name of your new branch to the right and press the "Apply Changes"
button.</blockquote></li>
button.</li>

<p id="q4"><b>(4) How do I tag a check-in?</b></p>

<blockquote>There are several ways:
There are several ways:

When you are checking in a new change using the <b>[/help/commit|commit]</b>
command, you can add a tag to that check-in using the
"--tag <i>TAGNAME</i>" command-line option.  You can repeat the --tag
option to give a check-in multiple tags.  Tags need not be unique.  So,
for example, it is common to give every released version a "release" tag.

If you want add a tag to an existing check-in, you can use the
<b>[/help/tag|tag]</b> command.  For example:

<blockquote>
<pre>
<b>fossil [/help/branch|tag] add</b> <i>TAGNAME</i> <i>CHECK-IN</i>
</blockquote>
</pre>

The CHECK-IN in the previous line can be any
[./checkin_names.wiki | valid check-in name format].

You can also add (and remove) tags from a check-in using the
[./webui.wiki | web interface].  First locate the check-in that you
what to tag on the timeline, then click on the link to go the detailed
information page for that check-in.  Then find the "<b>edit</b>"
link (near the "Commands:" label) and click on that.  There are
controls on the edit page that allow new tags to be added and existing
tags to be removed.</blockquote></li>
tags to be removed.</li>

<p id="q5"><b>(5) How do I create a private branch that won't get pushed back to the
  main repository.</b></p>

<blockquote>Use the <b>--private</b> command-line option on the
Use the <b>--private</b> command-line option on the
<b>commit</b> command.  The result will be a check-in which exists on
your local repository only and is never pushed to other repositories.
All descendants of a private check-in are also private.

Unless you specify something different using the <b>--branch</b> and/or
<b>--bgcolor</b> options, the new private check-in will be put on a branch
named "private" with an orange background color.

You can merge from the trunk into your private branch in order to keep
your private branch in sync with the latest changes on the trunk.  Once
you have everything in your private branch the way you want it, you can
then merge your private branch back into the trunk and push.  Only the
final merge operation will appear in other repositories.  It will seem
as if all the changes that occurred on your private branch occurred in
a single check-in.
Of course, you can also keep your branch private forever simply
by not merging the changes in the private branch back into the trunk.

[./private.wiki | Additional information]</blockquote></li>
[./private.wiki | Additional information]</li>

<p id="q6"><b>(6) How can I delete inappropriate content from my fossil repository?</b></p>

<blockquote>See the article on [./shunning.wiki | "shunning"] for details.</blockquote></li>
See the article on [./shunning.wiki | "shunning"] for details.</li>

<p id="q7"><b>(7) How do I make a clone of the fossil self-hosting repository?</b></p>

<blockquote>Any of the following commands should work:
<blockquote><pre>
Any of the following commands should work:

<pre>
fossil [/help/clone|clone]  https://fossil-scm.org/  fossil.fossil
fossil [/help/clone|clone]  https://www2.fossil-scm.org/  fossil.fossil
fossil [/help/clone|clone]  https://www3.fossil-scm.org/site.cgi  fossil.fossil
</pre></blockquote>
</pre>

Once you have the repository cloned, you can open a local check-out
as follows:

<blockquote><pre>
<pre>
mkdir src; cd src; fossil [/help/open|open] ../fossil.fossil
</pre></blockquote>
</pre>

Thereafter you should be able to keep your local check-out up to date
with the latest code in the public repository by typing:

<blockquote><pre>
<pre>
fossil [/help/update|update]
</pre></blockquote></blockquote></li>
</pre></li>

<p id="q8"><b>(8) How do I import or export content from and to other version control systems?</b></p>

<blockquote>Please see [./inout.wiki | Import And Export]</blockquote></li>
Please see [./inout.wiki | Import And Export]</li>

</ol>

<title>Fossil File Formats</title>
<h1 align="center">
Fossil File Formats
</h1>

The global state of a fossil repository is kept simple so that it can
endure in useful form for decades or centuries.
A fossil repository is intended to be readable,
searchable, and extensible by people not yet born.

The global state of a fossil repository is an unordered

well as information such as parent check-ins, the username of the
programmer who created the check-in, the date and time when
the check-in was created, and any check-in comments associated
with the check-in.

Allowed cards in the manifest are as follows:

<blockquote>
<p class="indent">
<b>B</b> <i>baseline-manifest</i><br>
<b>C</b> <i>checkin-comment</i><br>
<b>D</b> <i>time-and-date-stamp</i><br>
<b>F</b> <i>filename</i> ?<i>hash</i>? ?<i>permissions</i>? ?<i>old-name</i>?<br>
<b>N</b> <i>mimetype</i><br>
<b>P</b> <i>artifact-hash</i>+<br>
<b>Q</b> (<b>+</b>|<b>-</b>)<i>artifact-hash</i> ?<i>artifact-hash</i>?<br>
<b>R</b> <i>repository-checksum</i><br>
<b>T</b> (<b>+</b>|<b>-</b>|<b>*</b>)<i>tag-name</i> <b>*</b> ?<i>value</i>?<br>
<b>U</b> <i>user-login</i><br>
<b>Z</b> <i>manifest-checksum</i>
</blockquote>
</p>

A manifest may optionally have a single <b>B</b> card.  The <b>B</b> card specifies
another manifest that serves as the "baseline" for this manifest.  A
manifest that has a <b>B</b> card is called a delta-manifest and a manifest
that omits the <b>B</b> card is a baseline-manifest.  The other manifest
identified by the argument of the <b>B</b> card must be a baseline-manifest.
A baseline-manifest records the complete contents of a check-in.

in the comment.

A manifest must have exactly one <b>D</b> card.  The sole argument to
the <b>D</b> card is a date-time stamp in the ISO8601 format.  The
date and time should be in coordinated universal time (UTC).
The format one of:

<blockquote>
<p class="indent">
<i>YYYY</i><b>-</b><i>MM</i><b>-</b><i>DD</i><b>T</b><i>HH</i><b>:</b><i>MM</i><b>:</b><i>SS</i><br>
<i>YYYY</i><b>-</b><i>MM</i><b>-</b><i>DD</i><b>T</b><i>HH</i><b>:</b><i>MM</i><b>:</b><i>SS</i><b>.</b><i>SSS</i>
</blockquote>
</p>

A manifest has zero or more <b>F</b> cards.  Each <b>F</b> card identifies a file
that is part of the check-in.  There are one, two, three, or four
arguments.  The first argument is the pathname of the file in the
check-in relative to the root of the project file hierarchy.  No ".."
or "." directories are allowed within the filename.  Space characters
are escaped as in <b>C</b> card comment text.  Backslash characters and

Clusters are used during repository synchronization to help
reduce network traffic.  As such, clusters are an optimization and
may be removed from a repository without loss or damage to the
underlying project code.

Allowed cards in the cluster are as follows:

<blockquote>
<p class="indent">
<b>M</b> <i>artifact-id</i><br />
<b>Z</b> <i>checksum</i>
</blockquote>
</p>

A cluster contains one or more <b>M</b> cards followed by a single <b>Z</b> card.
Each <b>M</b> card has a single argument which is the artifact ID of
another artifact in the repository.  The <b>Z</b> card works exactly like
the <b>Z</b> card of a manifest.  The argument to the <b>Z</b> card is the
lower-case hexadecimal representation of the MD5 checksum of all
prior cards in the cluster.  The <b>Z</b> card is required.

An example cluster from Fossil can be seen
[/artifact/d03dbdd73a2a8 | here].

<h3 id="ctrl">2.3 Control Artifacts</h3>

Control artifacts are used to assign properties to other artifacts
within the repository.
Allowed cards in a control artifact are as follows:

<blockquote>
<p class="indent">
<b>D</b> <i>time-and-date-stamp</i><br />
<b>T</b> (<b>+</b>|<b>-</b>|<b>*</b>)<i>tag-name</i> <i>artifact-id</i> ?<i>value</i>?<br />
<b>U</b> <i>user-name</i><br />
<b>Z</b> <i>checksum</i><br />
</blockquote>
</p>

A control artifact must have one <b>D</b> card, one <b>U</b> card, one <b>Z</b> card and
one or more <b>T</b> cards.  No other cards or other text is
allowed in a control artifact.  Control artifacts might be PGP
clearsigned.

The <b>D</b> card and the <b>Z</b> card of a control artifact are the same

<h3 id="wikichng">2.4 Wiki Pages</h3>

A wiki artifact defines a single version of a
single wiki page.
Wiki artifacts accept
the following card types:

<blockquote>
<p class="indent">
<b>C</b> <i>change-comment</i><br>
<b>D</b> <i>time-and-date-stamp</i><br />
<b>L</b> <i>wiki-title</i><br />
<b>N</b> <i>mimetype</i><br />
<b>P</b> <i>parent-artifact-id</i>+<br />
<b>U</b> <i>user-name</i><br />
<b>W</b> <i>size</i> <b>\n</b> <i>text</i> <b>\n</b><br />
<b>Z</b> <i>checksum</i>
</blockquote>
</p>

The <b>D</b> card is the date and time when the wiki page was edited.
The <b>P</b> card specifies the parent wiki pages, if any.  The <b>L</b> card
gives the name of the wiki page.  The optional <b>N</b> card specifies
the mimetype of the wiki text.  If the <b>N</b> card is omitted, the
mimetype is assumed to be text/x-fossil-wiki.
The <b>U</b> card specifies the login

[/artifact?name=7b2f5fd0e0&txt=1 | here].

<h3 id="tktchng">2.5 Ticket Changes</h3>

A ticket-change artifact represents a change to a trouble ticket.
The following cards are allowed on a ticket change artifact:

<blockquote>
<p class="indent">
<b>D</b> <i>time-and-date-stamp</i><br />
<b>J</b> ?<b>+</b>?<i>name</i> ?<i>value</i>?<br />
<b>K</b> <i>ticket-id</i><br />
<b>U</b> <i>user-name</i><br />
<b>Z</b> <i>checksum</i>
</blockquote>
</p>

The <b>D</b> card is the usual date and time stamp and represents the point
in time when the change was entered.  The <b>U</b> card is the login of the
programmer who entered this change.  The <b>Z</b> card is the required checksum over
the entire artifact.

Every ticket has a distinct ticket-id:

An attachment artifact associates some other artifact that is the
attachment (the source artifact) with a ticket or wiki page or
technical note to which
the attachment is connected (the target artifact).
The following cards are allowed on an attachment artifact:

<blockquote>
<p class="indent">
<b>A</b> <i>filename target</i> ?<i>source</i>?<br />
<b>C</b> <i>comment</i><br />
<b>D</b> <i>time-and-date-stamp</i><br />
<b>N</b> <i>mimetype</i><br />
<b>U</b> <i>user-name</i><br />
<b>Z</b> <i>checksum</i>
</blockquote>
</p>

The <b>A</b> card specifies a filename for the attachment in its first argument.
The second argument to the <b>A</b> card is the name of the wiki page or
ticket or technical note to which the attachment is connected.  The
third argument is either missing or else it is the lower-case artifact
ID of the attachment itself.  A missing third argument means that the
attachment should be deleted.

A technical note or "technote" artifact (formerly known as an "event" artifact)
associates a timeline comment and a page of text
(similar to a wiki page) with a point in time.  Technotes can be used
to record project milestones, release notes, blog entries, process
checkpoints, or news articles.
The following cards are allowed on an technote artifact:

<blockquote>
<p class="indent">
<b>C</b> <i>comment</i><br>
<b>D</b> <i>time-and-date-stamp</i><br />
<b>E</b> <i>technote-time</i> <i>technote-id</i><br />
<b>N</b> <i>mimetype</i><br />
<b>P</b> <i>parent-artifact-id</i>+<br />
<b>T</b> <b>+</b><i>tag-name</i> <b>*</b> ?<i>value</i>?<br />
<b>U</b> <i>user-name</i><br />
<b>W</b> <i>size</i> <b>\n</b> <i>text</i> <b>\n</b><br />
<b>Z</b> <i>checksum</i>
</blockquote>
</p>

The <b>C</b> card contains text that is displayed on the timeline for the
technote.  The <b>C</b> card is optional, but there can only be one.

A single <b>D</b> card is required to give the date and time when the
technote artifact was created.  This is different from the time at which
the technote appears on the timeline.

<h3 id="forum">2.8 Forum Posts</h3>

Forum posts are intended as a mechanism for users and developers to
discuss a project.  Forum posts are like messages on a mailing list.

The following cards are allowed on an forum post artifact:

<blockquote>
<p class="indent">
<b>D</b> <i>time-and-date-stamp</i><br />
<b>G</b> <i>thread-root</i><br />
<b>H</b> <i>thread-title</i><br />
<b>I</b> <i>in-reply-to</i><br />
<b>N</b> <i>mimetype</i><br />
<b>P</b> <i>parent-artifact-id</i><br />
<b>U</b> <i>user-name</i><br />
<b>W</b> <i>size</i> <b>\n</b> <i>text</i> <b>\n</b><br />
<b>Z</b> <i>checksum</i>
</blockquote>
</p>

Every forum post must have either one <b>I</b> card and one <b>G</b> card
or one <b>H</b> card.
Forum posts are organized into topic threads.  The initial
post for a thread (the root post) has an <b>H</b> card giving the title or
subject for that thread.  The argument to the <b>H</b> card is a string
in the same format as a comment string in a <b>C</b> card.

The following table summarizes the various kinds of cards that appear
on Fossil artifacts. A blank entry means that combination of card and
artifact is not legal. A number or range of numbers indicates the number
of times a card may (or must) appear in the corresponding artifact type.
e.g. a value of 1 indicates a required unique card and 1+ indicates that one
or more such cards are required.

<table border=1 width="100%">
<table>
<tr>
<th rowspan=2 valign=bottom>Card Format</th>
<th>⇩ Card Format / Used By ⇨</th>
<th colspan=8>Used By</th>
</tr>
<tr>
<th>Manifest</th>
<th>Cluster</th>
<th>Control</th>
<th>Wiki</th>
<th>Ticket</th>
<th>Attachment</th>
<th>Technote</th>

wrong order.

Both bugs have now been fixed.  However, to prevent historical
Technical Note artifacts that were inserted by users in good faith
from being rejected by newer Fossil builds, the card ordering
requirement is relaxed slightly.  The actual implementation is this:

<blockquote>
<p class=blockquote>
"All cards must be in strict lexicographic order, except that the
N and P cards of a Technical Note artifact are allowed to be
interchanged."
</blockquote>
</p>

Future versions of Fossil might strengthen this slightly to only allow
the out of order N and P cards for Technical Notes entered before
a certain date.

<h3>4.2 R-Card Hash Calculation</h3>

<h2>2.0 Differences Between Fossil And Git</h2>

Differences between Fossil and Git are summarized by the following table,
with further description in the text that follows.

<blockquote><table border=1 cellpadding=5 align=center>
<tr><th width="49%">GIT</th><th width="49%">FOSSIL</th><th width="2%">more</th></tr>
<table style="width: fit-content">
<tr><th>GIT</th><th>FOSSIL</th><th>more</th></tr>
<tr>
    <td>File versioning only</td>
    <td>
    <td>VCS, tickets, wiki, docs, notes, forum, chat, UI,
    [https://en.wikipedia.org/wiki/Role-based_access_control|RBAC]</td>
      VCS, tickets, wiki, docs, notes, forum, chat, UI,
      [https://en.wikipedia.org/wiki/Role-based_access_control|RBAC]
    </td>
    <td><a href="#features">2.1&nbsp;&darr;</a></td>
</tr>
<tr>
    <td>A federation of many small programs</td>
    <td>One self-contained, stand-alone executable</td>
    <td><a href="#selfcontained">2.2&nbsp;&darr;</a></td>
</tr>

    <td><a href="#testing">2.8&nbsp;&darr;</a></td>
</tr>
<tr>
    <td>SHA-1 or SHA-2</td>
    <td>SHA-1 and/or SHA-3, in the same repository</td>
    <td><a href="#hash">2.9&nbsp;&darr;</a></td>
</tr>
</table></blockquote>
</table>

<h3 id="features">2.1 Featureful</h3>

Git provides file versioning services only, whereas Fossil adds
an integrated [./wikitheory.wiki | wiki],
[./bugtheory.wiki | ticketing &amp; bug tracking],
[./embeddeddoc.wiki | embedded documentation], 

which every commit is tested first. It encourages thinking before
acting. We believe this is an inherently good thing.

Incidentally, this is a good example of Git's messy command design.
These three commands:

<pre>
    $ git merge HASH 
    $ git cherry-pick HASH 
    $ git revert HASH
$ git merge HASH 
$ git cherry-pick HASH 
$ git revert HASH
</pre>

...are all the same command in Fossil:

<pre>
    $ fossil merge HASH
    $ fossil merge --cherrypick HASH
    $ fossil merge --backout HASH
$ fossil merge HASH
$ fossil merge --cherrypick HASH
$ fossil merge --backout HASH
</pre>

If you think about it, they're all the same function: apply work done on
one branch to another. All that changes between these commands is how
much work gets applied — just one check-in or a whole branch — and the
merge direction.  This is the sort of thing we mean when we point out
that Fossil's command interface is simpler than Git's: there are fewer

<title>Fossilized Bash Prompt</title>
<h1>2013-02-21</h1>

Dan Kennedy has contributed a
[./fossil_prompt.sh?mimetype=text/plain | bash script]
that manipulates the bash prompt to show the status of
the Fossil repository that the user is currently visiting.
The prompt shows the branch, version, and time stamp for the
current checkout, and the prompt changes colors from blue to
red when there are uncommitted changes.

To try out this script, simply download it from the link above, then
type:

<blockquote><pre>
<pre>
. fossil_prompt.sh
</pre></blockquote>
</pre>

For a permanent installation, you can graft the code into your
<tt>.bashrc</tt> file in your home directory.

The code is very simple (only 32 non-comment lines, as of this writing)
and hence easy to customized.

advocate a switch-in-place working mode instead, so that is how most
users end up working with Git. Contrast [Fossil’s check-out workflow
document][ckwf] to see the practical differences.

There is one Git-specific detail we wish to add beyond what that
document already covers. This command:

        git checkout some-branch
    git checkout some-branch

…is best given as:

        fossil update some-branch
    fossil update some-branch

…in Fossil. There is a [`fossil checkout`][co] command, but it has
[several differences](./co-vs-up.md) that make it less broadly useful
than [`fossil update`][up] in everyday operation, so we recommend that
Git users moving to Fossil develop a habit of typing `fossil up` rather
than `fossil checkout`. That said, one of those differences does match
up with Git users’ expectations: `fossil checkout` doesn’t pull changes

choice also tends to make Fossil feel comfortable to Subversion
expatriates.)

The `fossil pull` command is simply the reverse of
`fossil push`, so that `fossil sync` [is functionally equivalent
to](./sync.wiki#sync):

        fossil push ; fossil pull
    fossil push ; fossil pull

There is no implicit “and update the local working directory” step in Fossil’s
push, pull, or sync commands, as there is with `git pull`.

Someone coming from the Git perspective may perceive that `fossil up`
has two purposes:

There are at least three different ways to get [Fossil-style multiple
check-out directories][mcw] with Git.

The old way is to simply symlink the `.git` directory between working
trees:

        mkdir ../foo-branch
        ln -s ../actual-clone-dir/.git .
        git checkout foo-branch
    mkdir ../foo-branch
    ln -s ../actual-clone-dir/.git .
    git checkout foo-branch

The symlink trick has a number of problems, the largest being that
symlinks weren’t available on Windows until Vista, and until the Windows
10 Creators Update was released in spring of 2017, you had to be an
Administrator to use the feature besides. ([Source][wsyml]) Git 2.5 solved
this problem back when Windows XP was Microsoft’s current offering
by adding the `git-worktree` command:

        git worktree add ../foo-branch foo-branch
        cd ../foo-branch
    git worktree add ../foo-branch foo-branch
    cd ../foo-branch

That is approximately equivalent to this in Fossil:

        mkdir ../foo-branch
        cd ../foo-branch
        fossil open /path/to/repo.fossil foo-branch
    mkdir ../foo-branch
    cd ../foo-branch
    fossil open /path/to/repo.fossil foo-branch

The Fossil alternative is wordier, but since this tends to be one-time setup,
not something you do everyday, the overhead is insignificant. This author keeps a “scratch” check-out
for cases where it’s inappropriate to reuse the “trunk” check-out,
isolating all of my expedient switch-in-place actions to that one
working directory. Since the other peer check-outs track long-lived
branches, and that set rarely changes once a development machine is set
up, I rarely pay the cost of these wordier commands.

That then leads us to the closest equivalent in Git to [closing a Fossil
check-out](#close):

        git worktree remove .
    git worktree remove .

Note, however, that unlike `fossil close`, once the Git command
determines that there are no uncommitted changes, it blows away all of
the checked-out files! Fossil’s alternative is shorter, easier to
remember, and safer.

There’s another way to get Fossil-like separate worktrees in Git:

        git clone --separate-git-dir repo.git https://example.com/repo
    git clone --separate-git-dir repo.git https://example.com/repo

This allows you to have your Git repository directory entirely separate
from your working tree, with `.git` in the check-out directory being a
file that points to `../repo.git`, in this example.

[mcw]:   ./ckout-workflows.md#mcw
[wsyml]: https://blogs.windows.com/windowsdeveloper/2016/12/02/symlinks-windows-10/


#### <a id="iip"></a> Init in Place

To illustrate the differences that Fossil’s separation of repository
from working directory creates in practice, consider this common Git “init in place”
method for creating a new repository from an existing tree of files,
perhaps because you are placing that project under version control for
the first time:

        cd long-established-project
        git init
        git add *
        git commit -m "Initial commit of project."
    cd long-established-project
    git init
    git add *
    git commit -m "Initial commit of project."

The closest equivalent in Fossil is:

        cd long-established-project
        fossil init .fsl
        fossil open --force .fsl
        fossil add *
        fossil ci -m "Initial commit of project."
    cd long-established-project
    fossil init .fsl
    fossil open --force .fsl
    fossil add *
    fossil ci -m "Initial commit of project."

Note that unlike in Git, you can abbreviate the “`commit`” command in
Fossil as “`ci`” for compatibility with CVS, Subversion, etc.

This creates a `.fsl` repo DB at the root of the project check-out to
emulate the `.git` repo dir. We have to use the `--force` flag on
opening the new repo because Fossil expects you to open a repo into an

#### <a id="emu-log"></a> Emulating `git log`

If you truly need a backwards-in-time-only view of history in Fossil to
emulate `git log`, this is as close as you can currently come:

        fossil timeline parents current
    fossil timeline parents current

Again, though, this isn’t restricted to a single branch, as `git log`
is.

Another useful rough equivalent is:

        git log --raw
        fossil time -v
    git log --raw
    fossil time -v

This shows what changed in each version, though Fossil’s view is more a
summary than a list of raw changes. To dig deeper into single commits,
you can use Fossil’s [`info` command][infoc] or its [`/info` view][infow].

Inversely, you may more exactly emulate the default `fossil timeline`
output with `git log --name-status`.


#### <a id="whatchanged"></a> What Changed?

A related — though deprecated — command is `git whatchanged`, which gives results similar to
`git log --raw`, so we cover it here.

Though there is no `fossil whatchanged` command, the same sort of
information is available. For example, to pull the current changes from
the remote repository and then inspect them before updating the local
working directory, you might say this in Git:

        git fetch
        git whatchanged ..@{u}
    git fetch
    git whatchanged ..@{u}

…which you can approximate in Fossil as:

        fossil pull
        fossil up -n
        fossil diff --from tip
    fossil pull
    fossil up -n
    fossil diff --from tip

To invert the `diff` to show a more natural patch, the command needs to
be a bit more complicated, since you can’t currently give `--to`
without `--from`.

        fossil diff --from current --to tip
    fossil diff --from current --to tip

Rather than use the “dry run” form of [the `update` command][up], you can
say:

        fossil timeline after current
    fossil timeline after current

…or if you want to restrict the output to the current branch:

        fossil timeline descendants current
    fossil timeline descendants current


#### <a id="ckin-names"></a> Symbolic Check-In Names

Note the use of [human-readable symbolic version names][scin] in Fossil
rather than [Git’s cryptic notations][gcn].

For a more dramatic example of this, let us ask Git, “What changed since the
beginning of last month?” being October 2020 as I write this:

        git log master@{2020-10-01}..HEAD
    git log master@{2020-10-01}..HEAD

That’s rather obscure! Fossil answers the same question with a simpler
command:

        fossil timeline after 2020-10-01
    fossil timeline after 2020-10-01

You may need to add `-n 0` to bypass the default output limit of
`fossil timeline`, 20 entries. Without that, this command reads
almost like English.

Some Git users like to write commands like the above so:

        git log @{2020-10-01}..@
    git log @{2020-10-01}..@

Is that better? “@” now means two different things: an at-time reference
and a shortcut for `HEAD`!

If you are one of those that like short commands, Fossil’s method is
less cryptic: it lets you shorten words in most cases up to the point
that they become ambiguous. For example, you may abbreviate the last
`fossil` command in the prior section:

        fossil tim d c
    fossil tim d c

…beyond which the `timeline` command becomes ambiguous with `ticket`.

Some Fossil users employ shell aliases, symlinks, or scripts to shorten
the command still further:

        alias f=fossil
        f tim d c
    alias f=fossil
    f tim d c

Granted, that’s rather obscure, but you you can also choose something
intermediate like “`f time desc curr`”, which is reasonably clear.

[35pct]: https://www.sqlite.org/fasterthanfs.html
[btree]: https://sqlite.org/btreemodule.html
[gcn]:   https://git-scm.com/docs/gitrevisions

Fossil omits the "Git index" or "staging area" concept.  When you
type "`fossil commit`" _all_ changes in your check-out are committed,
automatically.  There is no need for the "-a" option as with Git.

If you only want to commit _some_ of the changes, list the names
of the files or directories you want to commit as arguments, like this:

        fossil commit src/feature.c doc/feature.md examples/feature
    fossil commit src/feature.c doc/feature.md examples/feature

Note that the last element is a directory name, meaning “any changed
file under the `examples/feature` directory.”

Although there are currently no
<a id="csplit"></a>[commit splitting][gcspl] features in Fossil like
`git add -p`, `git commit -p`, or `git rebase -i`, you can get the same
effect by converting an uncommitted change set to a patch and then
running it through [Patchouli].

Rather than use `fossil diff -i` to produce such a patch, a safer and
more idiomatic method would be:

        fossil stash save -m 'my big ball-o-hackage'
        fossil stash diff > my-changes.patch
    fossil stash save -m 'my big ball-o-hackage'
    fossil stash diff > my-changes.patch

That stores your changes in the stash, then lets you operate on a copy
of that patch. Each time you re-run the second command, it will take the
current state of the working directory into account to produce a
potentially different patch, likely smaller because it leaves out patch
hunks already applied.

<a id="bneed"></a>
## Create Branches at Point of Need, Rather Than Ahead of Need

Fossil prefers that you create new branches as part of the first commit
on that branch:

        fossil commit --branch my-branch
    fossil commit --branch my-branch

If that commit is successful, your local check-out directory is then
switched to the tip of that branch, so subsequent commits don’t need the
“`--branch`” option. You simply say `fossil commit` again to continue
adding commits to the tip of that branch.

To switch back to the parent branch, say something like:

        fossil update trunk
    fossil update trunk

(This is approximately equivalent to `git checkout master`.)

Fossil does also support the Git style, creating the branch ahead of
need:

        fossil branch new my-branch
        fossil up my-branch
        ...work on first commit...
        fossil commit
    fossil branch new my-branch
    fossil up my-branch
    ...work on first commit...
    fossil commit

This is more verbose, giving the same overall effect though the initial
actions are inverted: create a new branch for the first commit, switch
the check-out directory to that branch, and make that first commit. As
above, subsequent commits are descendants of that initial branch commit.
We think you’ll agree that creating a branch as part of the initial
commit is simpler.

Fossil also allows you to move a check-in to a different branch
*after* you commit it, using the "`fossil amend`" command.
For example:

        fossil amend current --branch my-branch
    fossil amend current --branch my-branch

This works by inserting a tag into the repository that causes the web UI
to relabel commits from that point forward with the new name. Like Git,
Fossil’s fundamental data structure is the interlinked DAG of commit
hashes; branch names are supplemental data for making it easier for the
humans to understand this DAG, so this command does not change the core
history of the project, only annotate it for better display to the

[Fossil is an AP-mode system][capt], which in this case means it works
*very hard* to ensure that all repos are as close to identical as it can
make them under this eventually-consistent design philosophy.

Branch *names* sync automatically in Fossil, not just the
content of those branches. That means this common Git command:

        git push origin master
    git push origin master

…is simply this in Fossil:

        fossil push
    fossil push

Fossil doesn’t need to be told what to push or where to push it: it just
keeps using the same remote server URL you gave it last
until you [tell it to do something different][rem]. It pushes all
branches, not just one named local branch.

[capt]: ./cap-theorem.md
[rem]:  /help?cmd=remote


<a id="autosync"></a>
## Autosync

Fossil’s [autosync][wflow] feature, normally enabled, has no
equivalent in Git. If you want Fossil to behave like Git, you can turn
it off:

        fossil set autosync 0
    fossil set autosync 0

Let’s say that you have a typical server-and-workstations model with two
working clones on different machines, that you have disabled autosync,
and that this common sequence then occurs:

1.  Alice commits to her local clone and *separately* pushes the change
    up to Condor — their central server — in typical Git fashion.

We make no guarantee that there will always be a line beginning with
“`repo`” and that it will be separated from the repository’s file name
by a colon. The simplified example above is also liable to become
confused by whitespace in file names.)


```
  $ repo=$(fossil status | grep ^repo | cut -f2 -d:)
  $ url=$(fossil remote)
  $ fossil close             # Stop here and think if it warns you!
  $ mv $repo ${repo}.old
  $ fossil clone $url $repo
  $ fossil open --force $repo
$ repo=$(fossil status | grep ^repo | cut -f2 -d:)
$ url=$(fossil remote)
$ fossil close             # Stop here and think if it warns you!
$ mv $repo ${repo}.old
$ fossil clone $url $repo
$ fossil open --force $repo
```

What, then, should you as a Git transplant do instead when you find
yourself reaching for “`git reset`”?

Since the correct answer to that depends on why you think it’s a good
solution to your immediate problem, we’ll take our motivating scenario
from the problem setup above, where we discussed Fossil’s [autosync]
feature.  Let us further say Alice’s pique results from a belief that
Bob’s commit is objectively wrong-headed and should be expunged
henceforth. Since Fossil goes out of its way to ensure that [commits are
durable][wdm], it should be no further surprise that there is no easier
method to reset Bob’s clone in favor of Alice’s than the above sequence
in Fossil’s command set. Except in extreme situations, we believe that
sort of thing is unnecessary.

Instead, Bob can say something like this:

```
  fossil amend --branch MISTAKE --hide --close -m "mea culpa" tip
  fossil up trunk
  fossil push
fossil amend --branch MISTAKE --hide --close -m "mea culpa" tip
fossil up trunk
fossil push
```

Unlike in Git, the “`amend`” command doesn’t modify prior committed
artifacts. Bob’s first command doesn’t delete anything, merely tells
Fossil to hide his mistake from timeline views by inserting a few new
records into the local repository to change how the client interprets
the data it finds there henceforth.(^One to change the tag marking this

to return her check-out’s parent commit to the previous version lest her
next attempted commit land atop this mistake branch. The fact that Bob
marked the branch as closed will prevent that from going thru, cluing
Alice into what she needs to do to remedy the situation, but that merely
shows why it’s a better workflow if Alice makes the amendment herself:

```
  fossil amend --branch MISTAKE --hide --close \
    -m "shunt Bob’s erroneous commit off" tip
  fossil up trunk
  fossil push
fossil amend --branch MISTAKE --hide --close \
  -m "shunt Bob’s erroneous commit off" tip
fossil up trunk
fossil push
```

Then she can fire off an email listing Bob’s assorted failings and go
about her work. This asynchronous workflow solves the problem without
requiring explicit coordination with Bob. When he gets his email, he can
then say “`fossil up trunk`” himself, which by default will trigger an
autosync, pulling down Alice’s amendments and getting him back onto her

format][udiff] output, suitable for producing a [patch file][pfile].

Nevertheless, there are multiple ways to get colorized diff output from
Fossil:

*   The most direct method is to delegate diff behavior back to Git:

          fossil set --global diff-command 'git diff --no-index'
      fossil set --global diff-command 'git diff --no-index'

    The flag permits it to diff files that aren’t inside a Git repository.

*   Another method is to install [`colordiff`][cdiff] — included in
    [many package systems][cdpkg] — then say:

          fossil set --global diff-command 'colordiff -wu'
      fossil set --global diff-command 'colordiff -wu'

    Because this is unconditional, unlike `git diff --color=auto`, you
    will then have to remember to add the `-i` option to `fossil diff`
    commands when you want color disabled, such as when producing
    `patch(1)` files or piping diff output to another command that
    doesn’t understand ANSI escape sequences. There’s an example of this
    [below](#dstat).

While there is no direct equivalent to Git’s “`show`” command, similar
functionality is present in Fossil under other commands:


#### <a id="patch"></a> Show a Patch for a Commit

        git show -p COMMIT_ID
    git show -p COMMIT_ID

…gives much the same output as

        fossil diff --checkin COMMIT_ID
    fossil diff --checkin COMMIT_ID

…only without the patch email header. Git comes out of the [LKML] world,
where emailing a patch is a normal thing to do. Fossil is [designed for
cohesive teams][devorg] where drive-by patches are rarer.

You can use any of [Fossil’s special check-in names][scin] in place of
the `COMMIT_ID` in this and later examples. Fossil docs usually say
“`VERSION`” or “`NAME`” where this is allowed, since the version string
or name might not refer to a commit ID, but instead to a forum post, a
wiki document, etc. For instance, the following command answers the question “What did
I just commit?”

        fossil diff --checkin tip
    fossil diff --checkin tip

…or equivalently using a different symbolic commit name:

        fossil diff --from prev
    fossil diff --from prev

[devorg]: ./fossil-v-git.wiki#devorg
[LKML]:   https://lkml.org/


#### <a id="cmsg"></a> Show a Specific Commit Message

        git show -s COMMIT_ID
    git show -s COMMIT_ID


…is

        fossil time -n 1 COMMIT_ID
    fossil time -n 1 COMMIT_ID

…or with a shorter, more obvious command, though with more verbose output:

        fossil info COMMIT_ID
    fossil info COMMIT_ID

The `fossil info` command isn’t otherwise a good equivalent to
`git show`; it just overlaps its functionality in some areas. Much of
what’s missing is present in the corresponding [`/info` web
view][infow], though.


#### <a id="dstat"></a> Diff Statistics

Fossil’s closest internal equivalent to commands like
`git show --stat` is:

        fossil diff -i --from 2020-04-01 --numstat
    fossil diff -i --from 2020-04-01 --numstat

The `--numstat` output is a bit cryptic, so we recommend delegating
this task to [the widely-available `diffstat` tool][dst], which gives
a histogram in its default output mode rather than bare integers:

        fossil diff -i -v --from 2020-04-01 | diffstat
    fossil diff -i -v --from 2020-04-01 | diffstat

We gave the `-i` flag in both cases to force Fossil to use its internal
diff implementation, bypassing [your local `diff-command` setting][dcset].
The `--numstat` option has no effect when you have an external diff
command set, and some diff command alternatives like
[`colordiff`][cdiff] (covered [above](#cdiff)) produce output that confuses `diffstat`.

The "[`fossil mv`][mv]" and "[`fossil rm`][rm]" commands work like they
do in CVS in that they schedule the changes for the next commit by
default: they do not actually rename or delete the files in your
check-out.

If you don’t like that default, you can change it globally:

        fossil setting --global mv-rm-files 1
    fossil setting --global mv-rm-files 1

Now these commands behave like in Git in any Fossil repository where
this setting hasn’t been overridden locally.

If you want to keep Fossil’s soft `mv/rm` behavior most of the time, you
can cast it away on a per-command basis:

        fossil mv --hard old-name new-name
    fossil mv --hard old-name new-name

[mv]: /help?cmd=mv
[rm]: /help?cmd=rm


----

history to find a “good” version to anchor the start point of a
[`fossil bisect`][fbis] operation.

My search engine’s first result for “git checkout by date” is [this
highly-upvoted accepted Stack Overflow answer][gcod]. The first command
it gives is based on Git’s [`rev-parse` feature][grp]:

        git checkout master@{2020-03-17}
    git checkout master@{2020-03-17}

There are a number of weaknesses in this command. From least to most
critical:

1.  It’s a bit cryptic. Leave off the refname or punctuation, and it
    means something else. You cannot simplify the cryptic incantation in
    the typical use case.

Consequently, we cannot recommend this command at all. It’s unreliable even in the
best case.

That same Stack Overflow answer therefore goes on to recommend an
entirely different command:

        git checkout $(git rev-list -n 1 --first-parent --before="2020-03-17" master)
    git checkout $(git rev-list -n 1 --first-parent --before="2020-03-17" master)

We believe you get such answers to Git help requests in part
because of its lack of an always-up-to-date [index into its log](#log) and in
part because of its “small tools loosely joined” design philosophy. This
sort of command is therefore composed piece by piece:

<p style="text-align:center">◆  ◆  ◆</p>

“Oh, I know, I’ll search the rev-list, which outputs commit IDs by
parsing the log backwards from `HEAD`! Easy!”

        git rev-list --before=2020-03-17
    git rev-list --before=2020-03-17

“Blast! Forgot the commit ID!”

        git rev-list --before=2020-03-17 master
    git rev-list --before=2020-03-17 master

“Double blast! It just spammed my terminal with revision IDs! I need to
limit it to the single closest match:

        git rev-list -n 1 --before=2020-03-17 master
    git rev-list -n 1 --before=2020-03-17 master

“Okay, it gives me a single revision ID now, but is it what I’m after?
Let’s take a look…”

        git show $(git rev-list -n 1 --before=2020-03-17 master)
    git show $(git rev-list -n 1 --before=2020-03-17 master)

“Oops, that’s giving me a merge commit, not what I want.
Off to search the web… Okay, it says I need to give either the
`--first-parent` or `--no-merges` flag to show only regular commits,
not merge-commits. Let’s try the first one:”

        git show $(git rev-list -n 1 --first-parent --before=2020-03-17 master)
    git show $(git rev-list -n 1 --first-parent --before=2020-03-17 master)

“Better. Let’s check it out:”

        git checkout $(git rev-list -n 1 --first-parent --before=2020-03-17 master)
    git checkout $(git rev-list -n 1 --first-parent --before=2020-03-17 master)

“Success, I guess?”

<p style="text-align:center">◆  ◆  ◆</p>

This vignette is meant to explain some of Git’s popularity: it rewards
the sort of people who enjoy puzzles, many of whom are software

second `git show` command above on [Git’s own repository][gitgh], your
results may vary because there were four non-merge commits to Git on the
17th of March, 2020.

You may be asking with an exasperated huff, “What is your *point*, man?”
The point is that the equivalent in Fossil is simply:

        fossil up 2020-03-17
    fossil up 2020-03-17

…which will *always* give the commit closest to midnight UTC on the 17th
of March, 2020, no matter whether you do it on a fresh clone or a stale
one.  The answer won’t shift about from one clone to the next or from
one local time of day to the next. We owe this reliability and stability
to three Fossil design choices:

and your family’s home NAS.

#### Git Method

We first need to clone the work repo down to our laptop, so we can work on it
at home:

        git clone https://dev-server.example.com/repo
        cd repo
        git remote rename origin work
    git clone https://dev-server.example.com/repo
    cd repo
    git remote rename origin work

The last command is optional, strictly speaking. We could continue to
use Git’s default name for the work repo’s origin — sensibly enough
called “`origin`” — but it makes later commands harder to understand, so
we rename it here. This will also make the parallel with Fossil easier
to draw.

The first time we go home after this, we have to reverse-clone the work
repo up to the NAS:

        ssh my-nas.local 'git init --bare /SHARES/dayjob/repo.git'
        git push --all ssh://my-nas.local//SHARES/dayjob/repo.git
    ssh my-nas.local 'git init --bare /SHARES/dayjob/repo.git'
    git push --all ssh://my-nas.local//SHARES/dayjob/repo.git

Realize that this is carefully optimized down to these two long
commands. In practice, we’d expect a user typing these commands by hand from memory
to need to give four or more commands here instead.
Packing the “`git init`” call into the “`ssh`” call is something more
often done in scripts and documentation examples than done interactively,
which then necessitates a third command before the push, “`exit`”.
There’s also a good chance that you’ll forget the need for the `--bare`
option here to avoid a fatal complaint from Git that the laptop can’t
push into a non-empty repo. If you fall into this trap, among the many
that Git lays for newbies, you have to nuke the incorrectly initted
repo, search the web or Git man pages to find out about `--bare`, and try again.

Having navigated that little minefield,
we can tell Git that there is a second origin, a “home” repo in
addition to the named “work” repo we set up earlier:

        git remote add home ssh://my-nas.local//SHARES/dayjob/repo.git
        git config master.remote home
    git remote add home ssh://my-nas.local//SHARES/dayjob/repo.git
    git config master.remote home

We don’t have to push or pull because the remote repo is a complete
clone of the repo on the laptop at this point, so we can just get to
work now, committing along the way to get our work safely off-machine
and onto our home NAS, like so:

        git add
        git commit
        git push
    git add
    git commit
    git push

We didn’t need to give a remote name on the push because we told it the
new upstream is the home NAS earlier.

Now Friday comes along, and one of your office-mates needs a feature
you’re working on. You agree to come into the office later that
afternoon to sync up via the dev server:

        git push work master      # send your changes from home up
        git pull work master      # get your coworkers’ changes
    git push work master      # send your changes from home up
    git pull work master      # get your coworkers’ changes

Alternately, we could add “`--set-upstream/-u work`” to the first
command if we were coming into work long enough to do several Git-based things, not just pop in and sync.
That would allow the second to be just “`git pull`”, but the cost is
that when returning home, you’d have to manually reset the upstream
again.

This example also shows a consequence of that fact that
[Git doesn’t sync branch names](#syncall): you have to keep repeating
yourself like an obsequious supplicant: “Master, master.” Didn’t we
invent computers to serve humans, rather than the other way around?


#### Fossil Method

Now we’re going to do the same thing using Fossil, with
the commands arranged in blocks corresponding to those above for comparison.

We start the same way, cloning the work repo down to the laptop:

        fossil clone https://dev-server.example.com/repo
        cd repo
        fossil remote add work https://dev-server.example.com/repo
    fossil clone https://dev-server.example.com/repo
    cd repo
    fossil remote add work https://dev-server.example.com/repo

We’ve chosen the new “`fossil clone URI`” syntax added in Fossil 2.14 rather than separate
`clone` and `open` commands to make the parallel with Git clearer. [See
above](#mwd) for more on that topic.

Our [`remote` command][rem] is longer than the Git equivalent because
Fossil currently has no short command

they’re one-time setup costs,
easily amortized to insignificance by the shorter day-to-day commands
below.

On first beginning to work from home, we reverse-clone the Fossil repo
up to the NAS:

        rsync repo.fossil my-nas.local:/SHARES/dayjob/
    rsync repo.fossil my-nas.local:/SHARES/dayjob/

Now we’re beginning to see the advantage of Fossil’s simpler model,
relative to the tricky “`git init && git push`” sequence above.
Fossil’s alternative is almost impossible to get
wrong: copy this to that.  *Done.*

We’re relying on the `rsync` feature that creates up to one level of
missing directory (here, `dayjob/`) on the remote. If you know in
advance that the remote directory already exists, you could use a
slightly shorter `scp` command instead. Even with the extra 2 characters
in the `rsync` form, it’s much shorter because a Fossil repository is a
single SQLite database file, not a tree containing a pile of assorted
files.  Because of this, it works reliably without any of [the caveats
inherent in using `rsync` to clone a Git repo][grsync].

Now we set up the second remote, which is again simpler in the Fossil
case:

        fossil remote add home ssh://my-nas.local//SHARES/dayjob/repo.fossil
        fossil remote home
    fossil remote add home ssh://my-nas.local//SHARES/dayjob/repo.fossil
    fossil remote home

The first command is nearly identical to the Git version, but the second
is considerably simpler. And to be fair, you won’t find the
“`git config`” command above in all Git tutorials. The more common
alternative we found with web searches is even longer:
“`git push --set-upstream home master`”.

Where Fossil really wins is in the next step, making the initial commit
from home:

        fossil ci
    fossil ci

It’s one short command for Fossil instead of three for Git — or two if
you abbreviate it as “`git commit -a && git push`” — because of Fossil’s
[autosync] feature and deliberate omission of a
[staging feature](#staging).

The “Friday afternoon sync-up” case is simpler, too:

        fossil remote work
        fossil sync
    fossil remote work
    fossil sync

Back at home, it’s simpler still: we may be able to do away with the second command,
saying just “`fossil remote home`” because the sync will happen as part
of the next commit, thanks once again to Fossil’s autosync feature. If
the working branch now has commits from other developers after syncing
with the central repository, though, you’ll want to say “`fossil up`” to
avoid creating an inadvertent fork in the branch.

repositories can be overridden using the "--sha1" option to the
"fossil new" command.

If you are still on Fossil 2.1 through 2.9 but you want Fossil to go
ahead and start using SHA3 hashes, change the hash policy to
"sha3" using a command like this:

<blockquote><verbatim>
<verbatim>
fossil hash-policy sha3
</verbatim></blockquote>
</verbatim>

The next check-in will use a SHA3 hash, so that when that check-in is pushed
to colleagues, their clones will include the new SHA3-named artifact, so
their local Fossil instances will automatically convert their clones to
"sha3" mode as well.

Of course, if some members of your team stubbornly refuse to upgrade past

Since programs that produce and consume binary-compressed data files
often make it either difficult or impossible to work with the
uncompressed form, we want an automated method for producing the
uncompressed form to make Fossil happy while still having the compressed
form to keep our content creation applications happy.  This `Makefile`
should[^makefile] do that for BMP, PNG, SVG, and XLSX files:

        .SUFFIXES: .bmp .png .svg .svgz
    .SUFFIXES: .bmp .png .svg .svgz

        .svgz.svg:
            gzip -dc < $< > $@
    .svgz.svg:
        gzip -dc < $< > $@

        .svg.svgz:
            gzip -9c < $< > $@
    .svg.svgz:
        gzip -9c < $< > $@

        .bmp.png:
            convert -quality 95 $< $@
    .bmp.png:
        convert -quality 95 $< $@

        .png.bmp:
            convert $< $@
    .png.bmp:
        convert $< $@

        SS_FILES := $(wildcard spreadsheet/*)
    SS_FILES := $(wildcard spreadsheet/*)


        all: $(SS_FILES) illus.svg image.bmp doc-big.pdf
    all: $(SS_FILES) illus.svg image.bmp doc-big.pdf

        reconstitute: illus.svgz image.png
            ( cd spreadsheet ; zip -9 ../spreadsheet.xlsx) * )
            qpdf doc-big.pdf doc-small.pdf
    reconstitute: illus.svgz image.png
        ( cd spreadsheet ; zip -9 ../spreadsheet.xlsx) * )
        qpdf doc-big.pdf doc-small.pdf


        $(SS_FILES): spreadsheet.xlsx
            unzip $@ -d $<
    $(SS_FILES): spreadsheet.xlsx
        unzip $@ -d $<

        doc-big.pdf: doc-small.pdf
            qpdf --stream-data=uncompress $@ $<
    doc-big.pdf: doc-small.pdf
        qpdf --stream-data=uncompress $@ $<

This `Makefile` allows you to treat the compressed version as the
process input, but to actually check in only the changes against the
uncompressed version by typing “`make`” before “`fossil ci`”. This is
not actually an extra step in practice, since if you’ve got a
`Makefile`-based project, you should be building — and testing — it
before checking each change in anyway!

<title>Home</title>

<h3>What Is Fossil?</h3>

<div style='float:right;border:2px solid #446979;padding:0 15px 10px 0;margin:0 0 10px 10px;'>
<ul style='margin-left: -10px;'>
<div class="nomargins" style='float:right;border:2px solid #446979;padding:0 15px 10px 0;margin:0 50px 0 10px'>
<ul>
<li> [/uv/download.html | Download]
<li> [./quickstart.wiki | Quick Start]
<li> [./build.wiki | Install]
<li> [https://fossil-scm.org/forum | Support/Forum ]
<li> [./hints.wiki | Tips &amp; Hints]
<li> [./changes.wiki | Change Log]
<li> [../COPYRIGHT-BSD2.txt | License]

<title>Import And Export</title>

Fossil has the ability to import and export repositories from and to
[http://git-scm.com/ | Git].  And since most other version control
systems will also import/export from Git, that means that you can
import/export a Fossil repository to most version control systems using
Git as an intermediary.

<h2>Git → Fossil</h2>

To import a Git repository into Fossil, say something like:

<blockquote><pre>
<pre>
cd git-repo
git fast-export --all | fossil import --git new-repo.fossil
</pre></blockquote>
</pre>

The 3rd argument to the "fossil import"
command is the name of a new Fossil repository that is created to hold the Git
content.

The --git option is not actually required.  The git-fast-export file format
is currently the only VCS interchange format that Fossil understands.  But

any dependency on the amount of data involved.

<h2>Fossil → Git</h2>

To convert a Fossil repository into a Git repository, run commands like
this:

<blockquote><pre>
<pre>
git init new-repo
cd new-repo
fossil export --git ../repo.fossil | git fast-import
</pre></blockquote>
</pre>

In other words, create a new Git repository, then pipe the output from the
"fossil export --git" command into the "git fast-import" command.

Note that the "fossil export --git" command only exports the versioned files.
Tickets and wiki and events are not exported, since Git does not understand
those concepts.

artifacts which are known by both Git and Fossil to exist at a given point in
time.

To illustrate, consider the example of a remote Fossil repository that a
user wants to import into a local Git repository.  First, the user would clone
the remote repository and import it into a new Git repository:

<blockquote><pre>
<pre>
fossil clone /path/to/remote/repo.fossil repo.fossil
mkdir repo
cd repo
fossil open ../repo.fossil
mkdir ../repo.git
cd ../repo.git
git init .
fossil export --git --export-marks ../repo/fossil.marks  \
       ../repo.fossil | git fast-import                  \
       --export-marks=../repo/git.marks
</pre></blockquote>
</pre>

Once the import has completed, the user would need to <tt>git checkout
trunk</tt>.  At any point after this, new changes can be imported from the
remote Fossil repository:

<blockquote><pre>
<pre>
cd ../repo
fossil pull
cd ../repo.git
fossil export --git --import-marks ../repo/fossil.marks  \
       --export-marks ../repo/fossil.marks               \
       ../repo.fossil | git fast-import                  \
       --import-marks=../repo/git.marks                  \
       --export-marks=../repo/git.marks
</pre></blockquote>
</pre>

Changes in the Git repository can be exported to the Fossil repository and then
pushed to the remote:

<blockquote><pre>
<pre>
git fast-export --import-marks=../repo/git.marks                  \
    --export-marks=../repo/git.marks --all | fossil import --git  \
    --incremental --import-marks ../repo/fossil.marks             \
    --export-marks ../repo/fossil.marks ../repo.fossil
cd ../repo
fossil push
</pre></blockquote>
</pre>

_Workaround:_ You don’t have to use the browser-based wiki editor to
maintain your repository’s wiki at all. Fossil’s [`wiki` command][fwc]
lets you manipulate wiki documents from the command line. For example,
consider this Vi based workflow:

```shell
    $ vi 'My Article.wiki'                   # begin work on new article
      ...write, write, write...
    :w                                       # save changes to disk copy
    :!fossil wiki create 'My Article' '%'    # current file (%) to new article
      ...write, write, write some more...
    :w                                       # save again
    :!fossil wiki commit 'My Article' '%'    # update article from disk
    :q                                       # done writing for today
$ vi 'My Article.wiki'                   # begin work on new article
  ...write, write, write...
:w                                       # save changes to disk copy
:!fossil wiki create 'My Article' '%'    # current file (%) to new article
  ...write, write, write some more...
:w                                       # save again
:!fossil wiki commit 'My Article' '%'    # update article from disk
:q                                       # done writing for today

      ....days later...
    $ vi                                     # work sans named file today
    :r !fossil wiki export 'My Article' -    # pull article text into vi buffer
      ...write, write, write yet more...
    :w !fossil wiki commit -                 # vi buffer updates article
  ....days later...
$ vi                                     # work sans named file today
:r !fossil wiki export 'My Article' -    # pull article text into vi buffer
  ...write, write, write yet more...
:w !fossil wiki commit -                 # vi buffer updates article
```

Extending this concept to other text editors is an exercise left to the
reader.

[fwc]: /help?cmd=wiki
[fwt]: ./wikitheory.wiki

_Potential Workaround:_ It would not be especially difficult for someone
sufficiently motivated to build a Fossil chat gateway, connecting to
IRC, Jabber, etc. The messages are stored in the repository’s `chat`
table with monotonically increasing IDs, so a poller that did something
like

       SELECT xfrom, xmsg FROM chat WHERE msgid > 1234;
    SELECT xfrom, xmsg FROM chat WHERE msgid > 1234;

…would pull the messages submitted since the last poll. Making the
gateway bidirectional should be possible as well, as long as it properly
uses SQLite transactions.

### <a id="brlist"></a>List of branches

Server Overload” replies will be issued for expensive requests.  On the
self-hosting Fossil server, that value is set to 1.5, but you could
easily set it higher on a multi-core server.

The maximum load average can also be set on the command line using
commands like this:

        fossil set max-loadavg 1.5
        fossil all set max-loadavg 1.5
    fossil set max-loadavg 1.5
    fossil all set max-loadavg 1.5

The second form is especially useful for changing the maximum load
average simultaneously on a large number of repositories.

Note that this load-average limiting feature is only available on
operating systems that support the [`getloadavg()`][gla] API.  Most
modern Unix systems have this interface, but Windows does not, so the
feature will not work on Windows.

Because Linux implements `getloadavg()` by accessing the `/proc/loadavg`
virtual file, you will need to make sure `/proc` is available to the
Fossil server. The most common reason for it to not be available is that
you are running a Fossil instance [inside a `chroot(2)`
jail](./chroot.md) and you have not mounted the `/proc` virtual file
system inside that jail. On the [self-hosting Fossil repositories][sh],
this was accomplished by adding a line to the `/etc/fstab` file:

        chroot_jail_proc /home/www/proc proc ro 0 0
    chroot_jail_proc /home/www/proc proc ro 0 0

The `/home/www/proc` pathname should be adjusted so that the `/proc`
component is at the root of the chroot jail, of course.

To see if the load-average limiter is functional, visit the
[`/test_env`][hte] page of the server to view the current load average.
If the value for the load average is greater than zero, that means that

The VERSION.h header file is generated by
a C program: tools/mkversion.c.
To run the VERSION.h generator, first compile the tools/mkversion.c
 source file into a command-line program (named "mkversion.exe")
then run:

<blockquote><pre>
<pre>
mkversion.exe manifest.uuid manifest VERSION &gt;VERSION.h
</pre></blockquote>
</pre>

The pathnames in the above command might need to be adjusted to get the
directories right.  The point is that the manifest.uuid, manifest, and
VERSION files
in the root of the source tree are the three arguments and
the generated VERSION.h file appears on standard output.

The builtin_data.h header file is generated by a C program: tools/mkbuiltin.c.
The builtin_data.h file contains C-language byte-array definitions for
the content of resource files used by Fossil.  To generate the
builtin_data.h file, first compile the mkbuiltin.c program, then run:

<blockquote><pre>
<pre>
mkbuiltin.exe diff.tcl <i>OtherFiles...</i> &gt;builtin_data.h
</pre></blockquote>
</pre>

At the time of this writing, the "diff.tcl" script (a Tcl/Tk script used
to generate implement --tk option on the diff command) is the only resource
file processed using mkbuiltin.exe.  However, new resources will likely be
added using this facility in future versions of Fossil.

<h1 id="preprocessing">4.0 Preprocessing</h1>

The mkindex program scans the "src.c" source files looking for special
comments that identify routines that implement various Fossil commands,
web interface methods, and help text comments.  The mkindex program
generates some C code that Fossil uses in order to dispatch commands and
HTTP requests and to show on-line help.  Compile the mkindex program
from the mkindex.c source file.  Then run:

<blockquote><pre>
<pre>
./mkindex src.c >page_index.h
</pre></blockquote>
</pre>

Note that "src.c" in the above is a stand-in for the (79) regular source
files of Fossil - all source files except for the exceptions described in
section 2.0 above.

The output of the mkindex program is a header file that is #include-ed by
the main.c source file during the final compilation step.

<h2>4.2 The translate preprocessor</h2>

The translate preprocessor looks for lines of source code that begin
with "@" and converts those lines into string constants or (depending on
context) into special "printf" operations for generating the output of
an HTTP request.  The translate preprocessor is a simple C program whose
sources are in the translate.c source file.  The translate preprocess
is run on each of the other ordinary source files separately, like this:

<blockquote><pre>
<pre>
./translate src.c >src_.c
</pre></blockquote>
</pre>

In this case, the "src.c" file represents any single source file from the
set of ordinary source files as described in section 2.0 above.  Note that
each source file is translated separately.  By convention, the names of
the translated source files are the names of the input sources with a
single "_" character at the end.  But a new makefile can use any naming
convention it wants - the "_" is not critical to the build process.

The makeheaders program is run once.  It scans all inputs source files and
generates header files for each one.  Note that the sqlite3.c and shell.c
source files are not scanned by makeheaders.  Makeheaders only runs over
"ordinary" source files, not the exceptional source files.  However,
makeheaders also uses some extra header files as input.  The general format
is like this:

<blockquote><pre>
<pre>
makeheaders src_.c:src.h sqlite3.h th.h VERSION.h
</pre></blockquote>
</pre>

In the example above the "src_.c" and "src.h" names represent all of the
(79) ordinary C source files, each as a separate argument.

<h1>5.0 Compilation</h1>

After all generated files have been created and all ordinary source files

However, in practice it is instead recommended to add a respective configure
option for the target platform and then perform a clean build. This way the
Debug flags are consistently applied across the whole build process. For
example, use these Debug flags in addition to other flags passed to the
configure scripts:

On Linux, *NIX and similar platforms:
<blockquote><pre>
<pre>
./configure --fossil-debug
</pre></blockquote>
</pre>

On Windows:
<blockquote><pre>
<pre>
win\buildmsvc.bat FOSSIL_DEBUG=1
</pre></blockquote>
</pre>

The resulting fossil binary could then be loaded into a platform-specific
debugger. Source files displayed in the debugger correspond to the ones
generated from the translation stage of the build process, that is what was
actually compiled into the object files.

<h1>8.0 See Also</h1>

  *  [./tech_overview.wiki | A Technical Overview Of Fossil]
  *  [./adding_code.wiki | How To Add Features To Fossil]

2.  Create a new project.  GitHub will ask you if you want to prepopulate
    your project with various things like a README file.  Answer "no" to
    everything.  You want a completely blank project.  GitHub will then
    supply you with a URL for your project that will look something
    like this:

                https://github.com/username/project.git
          https://github.com/username/project.git

3.  Back on your workstation, move to a checkout for your Fossil
    project and type:

    <blockquote>
    <pre>
      $ fossil git export /path/to/git/repo --autopush &bsol;
        https://<font color="orange">username</font>:<font color="red">password</font>@github.com/username/project.git
    $ fossil git export /path/to/git/repo --autopush &bsol;
      https://<font color="orange">username</font>:<font color="red">password</font>@github.com/username/project.git
    </pre>
    </blockquote>

    In place of the <code>/path/to...</code> argument above, put in
    some directory name that is <i>outside</i> of your Fossil checkout. If
    you keep multiple Fossil checkouts in a directory of their own,
    consider using <code>../git-mirror</code> to place the Git export

5.  And you are done!  Assuming everything worked, your project is now
    mirrored on GitHub.

6.  Whenever you update your project, simply run this command to update
    the mirror:

                $ fossil git export
          $ fossil git export

    Unlike with the first time you ran that command, you don’t need
    the remaining arguments, because Fossil remembers those things.
    Subsequent mirror updates should usually happen in a fraction of
    a second.

7.  To see the status of your mirror, run:

                $ fossil git status
          $ fossil git status

## Notes:

  *  Unless you specify --force, the mirroring only happens if the Fossil
     repo has changed, with Fossil reporting "no changes", because Fossil 
     does not care about the success or failure of the mirror run. If a mirror
     run failed (for example, due to an incorrect password, or a transient

## <a id='ex1'></a>Example GitHub Mirrors

As of this writing (2019-03-16) Fossil’s own repository is mirrored
on GitHub at:

>
<https://github.com/drhsqlite/fossil-mirror>
> <https://github.com/drhsqlite/fossil-mirror>

In addition, an official Git mirror of SQLite is available:

>
<https://github.com/sqlite/sqlite>
> <https://github.com/sqlite/sqlite>

The Fossil source repositories for these mirrors are at
<https://www2.fossil-scm.org/fossil> and <https://www2.sqlite.org/src>,
respectively.  Both repositories are hosted on the same VM at
[Linode](https://www.linode.com).  On that machine, there is a 
[cron job](https://linux.die.net/man/8/cron)
that runs at 17 minutes after the hour, every hour that does:

>
    /usr/bin/fossil sync -u -R /home/www/fossil/fossil.fossil
    /usr/bin/fossil sync -R /home/www/fossil/sqlite.fossil
    /usr/bin/fossil git export -R /home/www/fossil/fossil.fossil
    /usr/bin/fossil git export -R /home/www/fossil/sqlite.fossil

The initial two "sync" commands pull in changes from the primary
Fossil repositories for Fossil and SQLite.  The last two lines
export the changes to Git and push the results up to GitHub.

<li> <a href='quickstart.wiki'>Quick-start Guide</a>
<li> <a href='$ROOT/help'>Built-in help for commands and webpages</a>
<li> <a href='history.md'>Purpose and History of Fossil</a>
<li> <a href='build.wiki'>Compiling and installing Fossil</a>
<li> <a href='../COPYRIGHT-BSD2.txt'>License</a>
<li> <a href='userlinks.wiki'>Miscellaneous Docs for Fossil Users</a>
<li> <a href='hacker-howto.wiki'>Fossil Developer's Guide</a>
  <ul><li><a href='$ROOT/wiki?name=Release Build How-To'>Release Build How-To</a>, a.k.a.
  how deliverables are built</li></ul>
<li><a href='$ROOT/wiki?name=Release Build How-To'>Release Build How-To</a>,
a.k.a.  how deliverables are built</li>
</li>
<li> <a href='$ROOT/wiki?name=To+Do+List'>To Do List (Wiki)</a>
<li> <a href='https://fossil-scm.org/fossil-book/'>Fossil book</a>
</ul>
<h2 id="pindex">Other Documents:</h2>
<ul>}
foreach entry $permindex {

set your account name and password, and grant your account all access
privileges. (I also like to grant Clone access to the anonymous user,
but that's personal preference.)

Once you are done, kill the fossil server (with Ctrl-C or equivalent)
and close the browser window.

<blockquote>
Tip: it is not strictly required to configure a repository
<div class="sidebar">
It is not strictly required to configure a repository
this way, but if you are going to share a repo over the net then it
is highly recommended. If you are only going to work with the repo
locally, you can skip the configuration step and do it later if
you decide you want to share your repo.
</blockquote>
</div>

The next thing we need to do is <em>open</em> the repository. To do so
we create a working directory and then <tt>cd</tt> to it:

<verbatim>
$ mkdir demo
$ cd demo

<title>Fossil Password Management</title>
<h1 align="center">Password Management</h1>

Fossil handles user authentication using passwords.
Passwords are unique to each repository.  Passwords are not part of the
persistent state of a project.  Passwords are not versioned and
are not transmitted from one repository to another during a sync.
Passwords are local configuration information that can (and usually does)
vary from one repository to the next within the same project.

The SHA1 hash in the USER.PW field is a hash of a string composed of
the project-code, the user login, and the user cleartext password.
Suppose user "alice" with password "asdfg" had an account on the
Fossil self-hosting repository.  Then the value of USER.PW
for alice would be the SHA1 hash of

<blockquote>
<pre>
CE59BB9F186226D80E49D1FA2DB29F935CCA0333/alice/asdfg
</blockquote>
</pre>

Note that by including the project-code and the login as part of the
hash, a different USER.PW value results even if two or more users on
the repository select the same "asdfg" password or if user alice
reuses the same password on multiple projects.

Whenever a password is changed using the web interface or using the
"user" command-line method, the new password is stored using the SHA1
encoding.  Thus, cleartext passwords will gradually migrate to become
SHA1 passwords.  All remaining cleartext passwords can be converted to
SHA1 passwords using the following command:

<blockquote><pre>
<pre>
fossil test-hash-passwords <i>REPOSITORY-NAME</i>
</pre></blockquote>
</pre>

Remember that converting from cleartext to SHA1 passwords is an
irreversible operation.

The only way to insert a new cleartext password into the USER table
is to do so manually using SQL commands.  For example:

<blockquote><pre>
<pre>
UPDATE user SET pw='asdfg' WHERE login='alice';
</pre></blockquote>
</pre>

Note that an password that is an empty string or NULL will disable
all login for that user.   Thus, to lock a user out of the system,
one has only to set their password to an empty string, using either
the web interface or direct SQL manipulation of the USER table.
Note also that the password field is
essentially ignored for the special users named "anonymous", "developer",

This means that when USER.PW holds a cleartext password, the login card
will work for both older and newer clients.  If the USER.PW on the server
only holds the SHA1 hash of the password, then only newer clients will be
able to authenticate to the server.

The client normally gets the login and password from the "remote URL".

<blockquote><pre>
<pre>
http://<span style="color:blue">login:password</span>@servername.org/path
</pre></blockquote>
</pre>

For older clients, the password is used for the shared secret as stated
in the URL and with no encoding.
For newer clients, the shared secret is derived from the password
by transformed the password using the SHA1 hash encoding
described above.  However, if the first character of the password is
"*" (ASCII 0x2a) then the "*" is skipped and the rest of the password
is used directly as the share secret without the SHA1 encoding.

<blockquote><pre>
<pre>
http://<span style="color:blue">login:*password</span>@servername.org/path
</pre></blockquote>
</pre>

This *-before-the-password trick can be used by newer clients to
sync against a legacy server that does not understand the new SHA1
password encoding.

<li> <a href='quickstart.wiki'>Quick-start Guide</a>
<li> <a href='$ROOT/help'>Built-in help for commands and webpages</a>
<li> <a href='history.md'>Purpose and History of Fossil</a>
<li> <a href='build.wiki'>Compiling and installing Fossil</a>
<li> <a href='../COPYRIGHT-BSD2.txt'>License</a>
<li> <a href='userlinks.wiki'>Miscellaneous Docs for Fossil Users</a>
<li> <a href='hacker-howto.wiki'>Fossil Developer's Guide</a>
  <ul><li><a href='$ROOT/wiki?name=Release Build How-To'>Release Build How-To</a>, a.k.a.
  how deliverables are built</li></ul>
<li><a href='$ROOT/wiki?name=Release Build How-To'>Release Build How-To</a>,
a.k.a.  how deliverables are built</li>
</li>
<li> <a href='$ROOT/wiki?name=To+Do+List'>To Do List (Wiki)</a>
<li> <a href='https://fossil-scm.org/fossil-book/'>Fossil book</a>
</ul>
<h2 id="pindex">Other Documents:</h2>
<ul>
<li><a href="tech_overview.wiki">A Technical Overview Of The Design And Implementation Of Fossil</a></li>

<title>Principles Of Operation</title>
<h1 align="center">Principles Of Operation</h1>

This page attempts to define the foundational principals upon
which Fossil is built.

  *  A project consists of source files, wiki pages, and
     trouble tickets, and control files (collectively "artifacts").
     All historical copies of all artifacts

<title>Private Branches</title>

By default, everything you check into a Fossil repository is shared
to all clones of that repository.  In Fossil, you don't push and pull
individual branches; you push and pull everything all at once.

But sometimes users want to keep some private work that is not
shared with others.  This might be a preliminary or experimental change
that needs further refinement before it is shared and which might never
be shared at all.  To do this in Fossil, simply commit the change with
the --private command-line option:

<blockquote><pre>
<pre>
fossil commit --private
</pre></blockquote>
</pre>

The --private option causes Fossil to put the check-in in a new branch
named "private".  That branch will not participate in subsequent clone,
sync, push, or pull operations.  The branch will remain on the one local
repository where it was created.  Note that you only use the --private
option for the first check-in that creates the private branch.
Additional checkins into the private branch remain private automatically.

<h2>Publishing Private Changes</h2>

After additional work, one might desire to publish the changes associated
with a private branch.  The usual way to do this is to merge those
changes into a public branch.  For example:

<blockquote><pre>
<pre>
fossil update trunk
fossil merge private
fossil commit
</pre></blockquote>
</pre>

The private branch remains private and is not recorded as a parent
in the merge manifest's P-card, but all of the changes associated with
the private branch are now folded into the public branch and are hence
visible to other users of the project.

A private branch created with Fossil version 1.30 or newer can also be
converted into a public branch using the <code>fossil publish</code>
command.  However, there is no way to convert a private branch created with
older versions of Fossil into a public branch.

<div class="sidebar">
To avoid generating a missing artifact
reference on peer repositories without the private branch, the merge parent
is not recorded when merging the private branch into a public branch.  As a
consequence, the web UI timeline does not draw a merge line from the private
merge parent to the public merge child.  Moreover, repeat private-to-public
merge operations (without the [/help?cmd=merge | --force option]) with files
added on the private branch may only work once, but later abort with
"WARNING: no common ancestor for FILE", as the parent-child relationship is
not recorded. (See the [/doc/trunk/www/branching.wiki | Branching, Forking,
Merging, and Tagging] document for more information.)
</div>

The <code>--integrate</code> option of <code>fossil merge</code> (to close
the merged branch when committing) is ignored for a private branch -- or the
check-in manifest of the resulting merge child would include a
<code>+close</code> tag referring to the leaf check-in on the private branch,
and generate a missing artifact reference on repository clones without that
private branch.  It's still possible to close the leaf of the private branch
(after committing the merge child) with the <code>fossil amend --close</code>
command.

<blockquote><small>
Side note: For the same reason, i.e. so as not to generate a missing artifact
reference on peer repositories without the private branch, the merge parent
is not recorded when merging the private branch into a public branch.  As a
consequence, the web UI timeline does not draw a merge line from the private
merge parent to the public merge child.  Moreover, repeat private-to-public
merge operations (without the [/help?cmd=merge | --force option]) with files
added on the private branch may only work once, but later abort with
"WARNING: no common ancestor for FILE", as the parent-child relationship is
not recorded (see the [/doc/trunk/www/branching.wiki | Branching, Forking,
Merging, and Tagging] document for more information).
</small></blockquote>

<h2>Syncing Private Branches</h2>

A private branch normally stays on the one repository where it was
originally created.  But sometimes you want to share private branches
with another repository.  For example, you might be building a cross-platform
application and have separate repositories on your Windows laptop,
your Linux desktop, and your iMac.  You can transfer private branches
between these machines by using the --private option on the "sync",
"push", "pull", and "clone" commands.  For example, if you are running
"fossil server" on your Linux box and you want to clone that repository
to your Mac, including all private branches, use:

<blockquote><pre>
<verbatim>
fossil clone --private http://user@linux.localnetwork:8080/ mac-clone.fossil
</pre></blockquote>
</verbatim>

You'll have to supply a username and password in order for this to work.
Fossil will not clone (or sync) private branches anonymously.

By default, there are no users that can do private branch syncing.  You
will have to give a user
the "Private" capability ("x") if you want them to be able to do this.

again, this restriction is designed to make it hard to accidentally
push private branches beyond their intended audience.

<h2>Purging Private Branches</h2>

You can remove all private branches from a repository using this command:

<blockquote><pre>
<pre>
fossil scrub --private
</pre></blockquote>
</pre>

Note that the above is a permanent and irreversible change.  You will
be asked to confirm before continuing.  Once the private branches are
removed, they cannot be retrieved (unless you have synced them to another
repository.)  So be careful with the command.

<h2>Additional Notes</h2>

All of the features above apply to <u>all</u> private branches in a
single repository at once.  There is no mechanism in Fossil (currently)
that allows you to push, pull, clone, sync, or scrub an individual
private branch within a repository that contains multiple private
branches.