Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Changes In Branch inskinerator-modern-backport Excluding Merge-Ins
This is equivalent to a diff from 5a09f499 to 8aff4854
2024-02-10
| ||
17:36 | Modernized the default skin, primarily to improve readability, and forked off the old default as "Étienne", named in honor of its creator. ... (check-in: 8a1ba49b user: wyoung tags: trunk) | |
14:29 | Removed redundant sidebar styling; should've been done as part of [bcbd1c1e]. ... (Closed-Leaf check-in: 8aff4854 user: wyoung tags: inskinerator-modern-backport) | |
12:26 | Removed a bunch of manual indents in pre blocks, MD fenced code blocks, etc. The skin does that for us now. ... (check-in: 2a7b1de3 user: wyoung tags: inskinerator-modern-backport) | |
2024-02-09
| ||
13:51 | Sync up with trunk for latest improvements. ... (check-in: 12390507 user: andybradford tags: clone-resume) | |
00:17 | Merged pikchr changes from trunk. (About to rebuild the containers, and we need both sets of changes on the public demo mirror.) ... (check-in: e471c5ff user: wyoung tags: inskinerator-modern-backport) | |
00:12 | Rebuild pikchr.wasm/js with emcc 3.1.53 and adapt the associated build rule in src/main.mk to account for a breaking emcc change (should also be backwards-compatible to older emcc's). ... (check-in: 5a09f499 user: stephan tags: trunk) | |
2024-02-08
| ||
20:45 | Update Pikchr to include fixes to autofit on diamond objects. ... (check-in: f4ec8e0f user: drh tags: trunk) | |
Changes to skins/default/README.md.
|
| | > | > | > > > | | 1 2 3 4 5 6 7 8 9 10 | 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: 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. |
Changes to skins/default/css.txt.
|
| | > < > > > > > > > > > > > | < < < < | | > > > > > > > < | | | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 | /* Overall page style; vi: filetype=css */ body { margin: 0 auto; background-color: white; font-family: sans-serif; } 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: #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; font-size: 2.20em; } .status { float: right; 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 { 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; } 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: 0.8em; padding: 10px; border-bottom: 1px solid #ccc; } .submenu a, .submenu label { padding: 10px 11px; text-decoration: none; color: #777; |
︙ | ︙ | |||
100 101 102 103 104 105 106 | white-space: nowrap; } /* Main document area; elements common to most pages. */ .content { | | < | < < < | < < | | < | | < | 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 | white-space: nowrap; } /* Main document area; elements common to most pages. */ .content { padding: 1ex; color: #2e2e2e; /* justified above in "WCAG 2" comment */ } .content h1 { font-size: 1.60em; color: #444; } .content h2 { font-size: 1.45em; color: #444; } .content h3 { font-size: 1.15em; color: #444; } .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; |
︙ | ︙ | |||
146 147 148 149 150 151 152 | hr { color: #eee; } /* Page footer */ | | | | > > > > > > > > > > > > > > > > > > | > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > < > | 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 | hr { color: #eee; } /* Page footer */ footer { border-top: 1px solid #ccc; padding: 10px; font-size: 0.8em; margin-top: 10px; color: #ccc; } /* Forum */ .forum a:visited { color: #6A7F94; } 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-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: 1px solid #ccc; border-radius: 0.5em; margin: 1em 0; } .report td, .report th { border: 0; font-size: .8em; padding: 10px; } |
︙ | ︙ | |||
222 223 224 225 226 227 228 | white-space: pre-wrap; } /* Timeline */ span.timelineDetail { | | | | > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 | white-space: pre-wrap; } /* Timeline */ span.timelineDetail { font-size: 90%; } div.timelineDate { 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; } } |
Changes to skins/default/footer.txt.
|
| | | | 1 2 3 4 5 | <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 </footer> |
Changes to skins/default/header.txt.
|
| > | > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | > > > | | | | > | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 | <header> <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> </header> <nav class="mainmenu" title="Main Menu"> <th1> html "<a id='hbbtn' href='$home/sitemap' aria-label='Site Map'>☰</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></nav> <nav id="hbdrop" title="sitemap"></nav> <h1 class="page-title">$<title></h1> |
Added skins/etienne/README.md.
> > > > > > > > > > > > > > | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 | 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. |
Added skins/etienne/css.txt.
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 | /* 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; } } |
Added skins/etienne/details.txt.
> > > > | 1 2 3 4 | timeline-arrowheads: 1 timeline-circle-nodes: 1 timeline-color-graph-lines: 1 white-foreground: 0 |
Added skins/etienne/footer.txt.
> > > > > | 1 2 3 4 5 | <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> |
Added skins/etienne/header.txt.
> > > > > > > > > > > > > > > > > > > > > > > > > > | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | <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'>☰</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> |
Changes to src/default.css.
︙ | ︙ | |||
494 495 496 497 498 499 500 | padding: 0; width: 125px; text-align: center; border-collapse: collapse; border-spacing: 0; } table.report { | < | 494 495 496 497 498 499 500 501 502 503 504 505 506 507 | padding: 0; width: 125px; text-align: center; border-collapse: collapse; border-spacing: 0; } table.report { border: 1px solid #999; margin: 1em 0 1em 0; cursor: pointer; } td.rpteditex { border-width: thin; border-color: #000000; |
︙ | ︙ | |||
580 581 582 583 584 585 586 | 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 | | | 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 | 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 */ 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; |
︙ | ︙ | |||
616 617 618 619 620 621 622 | } tr.diffskip.jchunk:hover { /*background-color: rgba(127,127,127,0.5); cursor: pointer;*/ } tr.diffskip > td.chunkctrl { text-align: left; | < | 615 616 617 618 619 620 621 622 623 624 625 626 627 628 | } tr.diffskip.jchunk:hover { /*background-color: rgba(127,127,127,0.5); cursor: pointer;*/ } tr.diffskip > td.chunkctrl { text-align: left; } tr.diffskip > td.chunkctrl > div { display: flex; align-items: center; } tr.diffskip > td.chunkctrl > div > span.error { padding: 0.25em 0.5em; |
︙ | ︙ | |||
1292 1293 1294 1295 1296 1297 1298 | margin: 0; } .flex-container.child-gap-small > * { margin: 0.25em; } #fossil-status-bar { display: block; | < | 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 | margin: 0; } .flex-container.child-gap-small > * { margin: 0.25em; } #fossil-status-bar { display: block; border-width: 1px; border-style: inset; border-color: inherit; min-height: 1.5em; font-size: 1.2em; padding: 0.2em; margin: 0.25em 0; |
︙ | ︙ | |||
1383 1384 1385 1386 1387 1388 1389 | 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 { | < | 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 | 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 { line-height: 1.35; white-space: pre; } table.numbered-lines > tbody > tr > td { font-family: inherit; font-size: inherit; line-height: inherit; |
︙ | ︙ | |||
1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 | color: black; } blockquote.file-content { /* file content block in the /file page */ margin: 0 1em; } /** 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 | > > > > > > > > > > > > > > > > > > > > > > > > | 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 | 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 |
︙ | ︙ | |||
1759 1760 1761 1762 1763 1764 1765 | body.branch .submenu > a.timeline-link { display: none; } body.branch .submenu > a.timeline-link.selected { display: inline; } | > > > > > > > | > > > > | < | 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 | 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: 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; } 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; |
︙ | ︙ | |||
1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857 | } /* Objects in the "desktoponly" class are invisible on mobile */ @media screen and (max-width: 600px) { .desktoponly { display: none; } } /* Objects in the "wideonly" class are invisible only on wide-screen desktops */ @media screen and (max-width: 1200px) { .wideonly { display: none; } } | > > > > > > > > | 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 1895 | } /* 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; } } |
Changes to src/hbmenu.js.
︙ | ︙ | |||
19 20 21 22 23 24 25 | ** ** 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: ** | | | | 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 | ** ** 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 expects the HTML to contain two elements: ** ** <a id="hbbtn"> <--- The hamburger menu button ** <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. ** |
︙ | ︙ |
Changes to src/main.mk.
︙ | ︙ | |||
189 190 191 192 193 194 195 196 197 198 199 200 201 202 | $(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/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 \ | > > > > | 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 | $(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 \ |
︙ | ︙ | |||
2113 2114 2115 2116 2117 2118 2119 | $(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 \ | | | 2117 2118 2119 2120 2121 2122 2123 2124 2125 2126 2127 2128 2129 2130 2131 | $(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 \ -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 |
︙ | ︙ |
Changes to src/skins.c.
︙ | ︙ | |||
43 44 45 46 47 48 49 50 51 52 53 54 55 56 | } aBuiltinSkin[] = { { "Default", "default", 0 }, { "Ardoise", "ardoise", 0 }, { "Black & White", "black_and_white", 0 }, { "Blitz", "blitz", 0 }, { "Dark Mode", "darkmode", 0 }, { "Eagle", "eagle", 0 }, { "Khaki", "khaki", 0 }, { "Original", "original", 0 }, { "Plain Gray", "plain_gray", 0 }, { "Xekri", "xekri", 0 }, }; /* | > | 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 | } 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 }, }; /* |
︙ | ︙ |
Changes to src/wikiformat.c.
︙ | ︙ | |||
1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 | }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>"); } pushStack(p, markup.iCode); renderMarkup(p->pOut, &markup); } }else if( markup.iType==MUTYPE_HYPERLINK ){ if( !isButtonHyperlink(p, &markup, z, &n) ){ popStackToTag(p, markup.iCode); | > | 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 | }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); |
︙ | ︙ |
Changes to test/release-checklist.wiki.
︙ | ︙ | |||
45 46 47 48 49 50 51 | <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: | < | | | 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 | <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: <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 |
︙ | ︙ |
Changes to win/Makefile.mingw.
︙ | ︙ | |||
575 576 577 578 579 580 581 582 583 584 585 586 587 588 | $(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/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 \ | > > > > | 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 | $(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 \ |
︙ | ︙ |
Changes to win/Makefile.msc.
︙ | ︙ | |||
533 534 535 536 537 538 539 540 541 542 543 544 545 546 | "$(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\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" \ | > > > > | 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 | "$(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" \ |
︙ | ︙ | |||
1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 | 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/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" >> $@ | > > > > | 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 | 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" >> $@ |
︙ | ︙ |
Changes to www/aboutcgi.wiki.
1 | <title>How CGI Works In Fossil</title> | > | > | | > | > | | | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 | <title>How CGI Works In Fossil</title> <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. <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: <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> <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 |
︙ | ︙ | |||
83 84 85 86 87 88 89 | 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. | | | > | | > | 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 | 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. <h2>How Fossil Acts As A CGI Program</h2> An appropriate CGI script for running Fossil will look something like the following: <pre> #!/usr/bin/fossil repository: /home/www/repos/project.fossil </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. |
︙ | ︙ | |||
132 133 134 135 136 137 138 139 140 141 142 143 144 145 | 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. | > | | > | | > | > | > | > > | < < | | 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 | 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. <h2>Serving Multiple Fossil Repositories From One CGI Script</h2> 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: <pre> #!/usr/bin/fossil directory: /home/www/repos </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: <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> <h2>Additional CGI Script Options</h2> The CGI script can have additional options used to fine-tune Fossil's behavior. See the [./cgi.wiki|CGI script documentation] for details. <h2>Additional Observations</h2> <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 |
︙ | ︙ | |||
237 238 239 240 241 242 243 | 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> | < | 248 249 250 251 252 253 254 | 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> |
Changes to www/aboutdownload.wiki.
1 | <title>How The Fossil Download Page Works</title> | < | 1 2 3 4 5 6 7 8 | <title>How The Fossil Download Page Works</title> <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 |
︙ | ︙ |
Changes to www/adding_code.wiki.
︙ | ︙ | |||
60 61 62 63 64 65 66 | 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: | | | | 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 | 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: <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> 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.) |
︙ | ︙ | |||
112 113 114 115 116 117 118 | <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: | | | | | | 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 | <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: <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> 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: <verbatim> ** COMMAND: xyzzy* </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 |
︙ | ︙ | |||
171 172 173 174 175 176 177 | <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: | | | | 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 | <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: <verbatim> /* ** WEBPAGE: helloworld */ void helloworld_page(void){ style_header("Hello World!"); @ <p>Hello, World!</p> style_footer(); } </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. |
︙ | ︙ |
Changes to www/alerts.md.
︙ | ︙ | |||
89 90 91 92 93 94 95 | the "From" address above, or it could be a different value like `admin@example.com`. Save your changes. At the command line, say | | | | | | | 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 | 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 If that gives a blank value instead of `sendmail -ti`, say $ 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 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> |
︙ | ︙ | |||
153 154 155 156 157 158 159 | 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: | < | < < | 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 | 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: > Use a different login with greater privilege than FOO to access /subscribe ...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. |
︙ | ︙ | |||
212 213 214 215 216 217 218 | 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: | | | 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 | 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 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. |
︙ | ︙ | |||
262 263 264 265 266 267 268 | ### 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!) | | | | | | | | | 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 | ### 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 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 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 This should also kick off the backoffice processing, if there are any pending alerts to send out. $ 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 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 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 |
︙ | ︙ | |||
422 423 424 425 426 427 428 | 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: | | | 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 | 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 & [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 |
︙ | ︙ | |||
681 682 683 684 685 686 687 | 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: | | | 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 | 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); 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 |
︙ | ︙ |
Changes to www/backoffice.md.
︙ | ︙ | |||
77 78 79 80 81 82 83 | 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: | | | 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 | 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_ 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 |
︙ | ︙ | |||
100 101 102 103 104 105 106 | [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. | | | | 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 | [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 Then arrange to invoke the backoffice separately using a command like this: 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" |
︙ | ︙ | |||
145 146 147 148 149 150 151 | "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: | | | 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 | "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_ 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. |
︙ | ︙ | |||
195 196 197 198 199 200 201 | 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: | | | 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 | 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_ 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 |
︙ | ︙ |
Changes to www/backup.md.
︙ | ︙ | |||
260 261 262 263 264 265 266 | 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: | | | | 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 | 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”) [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 |
︙ | ︙ |
Changes to www/branching.wiki.
︙ | ︙ | |||
244 245 246 247 248 249 250 | 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. | | | | 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 | 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. <p class="blockquote"> <b>Key Distinction:</b> A branch is a <i>named, intentional</i> fork. </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: |
︙ | ︙ | |||
693 694 695 696 697 698 699 | 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> | | | | 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 | 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> <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> 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" |
︙ | ︙ |
Changes to www/build.wiki.
︙ | ︙ | |||
188 189 190 191 192 193 194 | 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: | | | | | | | | | | 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 | 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: <pre> nmake /f Makefile.msc FOSSIL_ENABLE_SSL=1 FOSSIL_BUILD_SSL=1 PERLDIR=C:\full\path\to\Perl\bin </pre> <pre> buildmsvc.bat FOSSIL_ENABLE_SSL=1 FOSSIL_BUILD_SSL=1 PERLDIR=C:\full\path\to\Perl\bin </pre> To enable the optional native [./th1.md#tclEval | Tcl integration feature], run one of the following commands or add the "FOSSIL_ENABLE_TCL=1" argument to one of the other NMAKE command lines: <pre> nmake /f Makefile.msc FOSSIL_ENABLE_TCL=1 </pre> <pre> buildmsvc.bat FOSSIL_ENABLE_TCL=1 </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> |
︙ | ︙ | |||
249 250 251 252 253 254 255 | 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: | | | | 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 | 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: <pre> TCC += -DSQLITE_WITHOUT_ZONEMALLOC TCC += -D_BSD_SOURCE TCC += -DWITHOUT_ICONV TCC += -Dsocketlen_t=int TCC += -DSQLITE_MAX_MMAP_SIZE=0 </pre> </li> </ul> <h2 id="docker" name="oci">5.0 Building a Docker Container</h2> The information on building Fossil inside an |
︙ | ︙ | |||
436 437 438 439 440 441 442 | [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] | | | | | | | | | | > | 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 | [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] <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 \ --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> |
︙ | ︙ | |||
478 479 480 481 482 483 484 485 486 487 488 489 490 491 | 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> 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. | > > > > > > > > > > < < < < < < < < < < | < | < | | | | | | 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 | 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. 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> <div class="sidebar">If that fails with a message along the lines of “<code>setting `EXPORTED_RUNTIME_METHODS` expects `<class 'list'>` but 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> |
︙ | ︙ |
Changes to www/cgi.wiki.
︙ | ︙ | |||
21 22 23 24 25 26 27 | those options. <h1>CGI Script Options</h1> The CGI script used to launch a Fossil server will usually look something like this: | | | | 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 | those options. <h1>CGI Script Options</h1> The CGI script used to launch a Fossil server will usually look something like this: <verbatim> #!/usr/bin/fossil repository: /home/www/fossils/myproject.fossil </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: argument ...</b>". The remainder of this document describes the available properties and their arguments. |
︙ | ︙ |
Changes to www/changes.wiki.
︙ | ︙ | |||
10 11 12 13 14 15 16 17 18 19 20 21 22 23 | * 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. <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 | > > > > | 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 | * 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 |
︙ | ︙ |
Changes to www/chat.md.
︙ | ︙ | |||
77 78 79 80 81 82 83 84 85 86 87 88 89 90 | 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 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 | > > > > > > > > > | 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 | 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 |
︙ | ︙ | |||
110 111 112 113 114 115 116 | 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. | < < < < < < < < < | 119 120 121 122 123 124 125 126 127 128 129 130 131 132 | 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. ### <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). |
︙ | ︙ |
Changes to www/checkin_names.wiki.
1 2 | <title>Check-in Names</title> | | < | | | | | | | | | | | > | | | | | | > | | | | | | | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 | <title>Check-in Names</title> <div class="sidebar no-label"> <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> </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: <pre style="white-space: pre-wrap"> fossil info <i>checkin-name</i> </pre> You are perhaps reading this page from the following URL: <verbatim> https://fossil-scm.org/home/doc/trunk/www/checkin_names.wiki </verbatim> 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: <pre> fossil info e5a734a19a9826973e1d073b49dc2a16aa2308f9 </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: <pre> fossil info e5a734a19a9 fossil info E5a734A fossil info e5a7 </pre> 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: <pre> fossil info release </pre> …results in the following output: <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> 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: <pre> fossil info tag:deed2 </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> |
︙ | ︙ | |||
178 179 180 181 182 183 184 | 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: | | | | | | | | | | | | | | 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 | 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: <pre> https://fossil-scm.org/home/doc/<b>trunk</b>/www/index.wiki </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: <pre> https://fossil-scm.org/home/doc/<b>2009-01-01</b>/www/index.wiki </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: <pre> fossil update trunk:2010-07-01T14:30 </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": <pre> fossil diff --from root:xyzzy --to xyzzy </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 <pre> fossil info merge-in:xyzzy:2022-03-01 </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: <pre> http://localhost:8080/info/tip </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 |
︙ | ︙ | |||
280 281 282 283 284 285 286 | <h2 id="examples">Additional Examples</h2> To view the changes in the most recent check-in prior to the version currently checked out: | | | | | | 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 | <h2 id="examples">Additional Examples</h2> To view the changes in the most recent check-in prior to the version currently checked out: <pre> fossil diff --from previous --to current </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: <pre> fossil diff --from release --to trunk </pre> <h2 id="order">Resolution Order</h2> Fossil currently resolves name strings to artifact hashes in the following order: |
︙ | ︙ |
Changes to www/childprojects.wiki.
︙ | ︙ | |||
26 27 28 29 30 31 32 | 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: | | | | 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 | 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: <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> 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. |
︙ | ︙ |
Changes to www/ckout-workflows.md.
︙ | ︙ | |||
8 9 10 11 12 13 14 | ## <a id="mcw"></a> Multiple-Checkout Workflow With Fossil, it is routine to have multiple check-outs from the same repository: | | | | | | | | | | | | | | | | | | | 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 | ## <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 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 ../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 ../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 |
︙ | ︙ | |||
71 72 73 74 75 76 77 | 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: | | | | | | | | | | | | | | | | 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 | 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 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 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 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 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 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> |
Changes to www/concepts.wiki.
1 | <title>Fossil Concepts</title> | < | 1 2 3 4 5 6 7 8 | <title>Fossil Concepts</title> <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 |
︙ | ︙ | |||
113 114 115 116 117 118 119 | 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: | | | | | | | | 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 | 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: <pre> 6089f0b563a9db0a6d90682fe47fd7161ff867c8 59712614a1b3ccfd84078a37fa5b606e28434326 19dbf73078be9779edd6a0156195e610f81c94f9 b4104959a67175f02d6b415480be22a239f1f077 997c9d6ae03ad114b2b57f04e9eeef17dcb82788 </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. |
︙ | ︙ | |||
237 238 239 240 241 242 243 | 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: | < | < | 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 | 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: <pre>fossil help</pre> 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> |
︙ | ︙ | |||
280 281 282 283 284 285 286 | 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: | | | | | | | 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 | 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: <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. |
︙ | ︙ |
Changes to www/containers.md.
︙ | ︙ | |||
11 12 13 14 15 16 17 | ## 1. Quick Start Fossil ships a `Dockerfile` at the top of its source tree, [here][DF], which you can build like so: | < | < < | < | 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 | ## 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 . 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 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. |
︙ | ︙ | |||
42 43 44 45 46 47 48 | 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: | < | < | 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 | 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' 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 |
︙ | ︙ | |||
79 80 81 82 83 84 85 | ### <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: | < | | | < | 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 | ### <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 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 |
︙ | ︙ | |||
118 119 120 121 122 123 124 | 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: | < | | | | | < | 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 | 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 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 |
︙ | ︙ | |||
149 150 151 152 153 154 155 | #### 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: | < | < | 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 | #### 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 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] |
︙ | ︙ | |||
290 291 292 293 294 295 296 | 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`”: | < | | | | | | | | | < | 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 | 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 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 |
︙ | ︙ | |||
324 325 326 327 328 329 330 | 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: | < | | | | < < | < < | < | 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 | 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 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 . Or equivalently, using Fossil’s `Makefile` convenience target: $ 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 |
︙ | ︙ | |||
382 383 384 385 386 387 388 | 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: | < | < < < < | | < | | | | 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 | 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' 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"' 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 …to this: 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 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 |
︙ | ︙ | |||
461 462 463 464 465 466 467 | 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: | < < < < | 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 | 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. |
︙ | ︙ | |||
553 554 555 556 557 558 559 | 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: | < < < < | 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 | 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 |
︙ | ︙ | |||
604 605 606 607 608 609 610 | 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: | < | < | 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 | 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 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. |
︙ | ︙ | |||
676 677 678 679 680 681 682 | 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: | < | | < < | | | | | | | | | | | < < | < < | < < | | | < < | | | | | | | | | | | | | | | | | | | | | | | | | | | | < | 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 | 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 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 [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 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 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 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 [Files] Bind=/home/fossil/museum/myproject:/museum [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. |
︙ | ︙ | |||
817 818 819 820 821 822 823 | 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: ---- | < | | | | | | | | < < | | < < | | | | | | | < < | < < | < < | | | < | 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 | 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 [Service] ExecStart=systemd-nspawn --settings=override --read-only --machine=%i bin/fossil [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 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 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 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 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 - 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 |
︙ | ︙ |
Changes to www/custom_ticket.wiki.
1 | <title>Customizing The Ticket System</title> | | < > < < > < < | > | | | | | | > | | > | | | > | | > | | | | > | < < | | | | | | | | > | < < | > > | > | | | > > | > > | > | < | | | < | > | < < | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 | <title>Customizing The Ticket System</title> <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> 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? <h2>Next add assignees</h2> 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). <h2>Now modify the 'new ticket' page</h2> Back to the "Tickets" admin page, and click "New Ticket Page". This is a little more tricky. Edit the top part: <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: <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. <h2>Modify the 'view ticket' page</h2> Look for the text "Contact:" (about halfway through). Then insert these lines after the closing tr tag and before the "enable_output" line: <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>. <h2>Modify the 'edit ticket' page</h2> Before the "Severity:" line, add this: <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: <verbatim> <tr> <td align="right">Reported by:</td> <td> <input type="text" name="opened_by" size="40" value="$<opened_by>"> </td> </tr> </verbatim> <h2>What next?</h2> 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: <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() </verbatim> |
Changes to www/customskin.md.
︙ | ︙ | |||
55 56 57 58 59 60 61 | 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: | < < | | < | | < | < | | | | | | | | | | | | | | | | | | | | | | | | 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 | 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: | Fossil-Generated HTML Header | | Content Header | | Fossil-Generated Content | | Content Footer | | Fossil-Generated HTML Footer | 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"> …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; } 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> 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> After the Content is the custom Content Footer section which should follow this template: <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> ## <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 |
︙ | ︙ | |||
177 178 179 180 181 182 183 | 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: | | | | | 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 | 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: <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: <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> 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. |
︙ | ︙ | |||
240 241 242 243 244 245 246 | <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: | | | | | | | 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 | <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: <pre> <script nonce="$nonce"> <th1>styleScript</th1> </script> </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: <pre> <th1>builtin_request_js hbmenu.js</th1> </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> 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 |
︙ | ︙ | |||
332 333 334 335 336 337 338 | * 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: | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 | * 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> 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> 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'>☰</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> 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> 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"`. |
︙ | ︙ |
Changes to www/defcsp.md.
︙ | ︙ | |||
21 22 23 24 25 26 27 | bugs that might lead to a vulnerability. ## The Default Restrictions The default CSP used by Fossil is as follows: <pre> | | | | | < | < | | | | 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 | 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:; </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: default-src *; 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) 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...) 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) 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/ |
︙ | ︙ | |||
97 98 99 100 101 102 103 | 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: | | | 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 | 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> 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 |
︙ | ︙ | |||
172 173 174 175 176 177 178 | 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: | | | 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 | 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> 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. |
︙ | ︙ | |||
196 197 198 199 200 201 202 | 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]: | | | 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 | 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> 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, |
︙ | ︙ | |||
329 330 331 332 333 334 335 | 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: | | | 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 | 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 *' 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 |
︙ | ︙ | |||
364 365 366 367 368 369 370 | `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: | | | 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 | `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'}" After [the above](#admin-ui), this is the cleanest method. [thvar]: ./customskin.md#vars |
︙ | ︙ |
Changes to www/delta-manifests.md.
1 2 3 4 5 6 7 8 9 10 11 12 13 | # Delta Manifests 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. | > > > > < < < < < < | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 | # 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. # 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 |
︙ | ︙ |
Changes to www/delta_format.wiki.
︙ | ︙ | |||
188 189 190 191 192 193 194 | 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: | | | | | 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 | 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: <pre> 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz~ </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> <tr> <th>Value</th> <th>Encoding</th> </tr> <tr> <td>0</td> <td>0</td> |
︙ | ︙ | |||
226 227 228 229 230 231 232 | </tr> </table> <h2 id="examplesdelta">4.2 Delta encoding</h2> An example of a delta using the specified encoding is: | | | | | | 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 | </tr> </table> <h2 id="examplesdelta">4.2 Delta encoding</h2> An example of a delta using the specified encoding is: <pre> 1Xb 4E@0,2:thFN@4C,6:scenda1B@Jd,6:scenda5x@Kt,6:pieces79@Qt,F: Example: eskil~E@Y0,2zMM3E;</pre> </pre> This can be taken apart into the following parts: <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> </td> <td>2:th </td><td>Literal </td><td> 2 'th' </td></tr> <tr><td> </td> <td>FN@4C, </td><td>Copy </td><td> 983 @ 268 </td></tr> <tr><td> </td> <td>6:scenda </td><td>Literal </td><td> 6 'scenda' </td></tr> <tr><td> </td> <td>1B@Jd, </td><td>Copy </td><td> 75 @ 1256 </td></tr> <tr><td> </td> <td>6:scenda </td><td>Literal </td><td> 6 'scenda' </td></tr> <tr><td> </td> <td>5x@Kt, </td><td>Copy </td><td> 380 @ 1336 </td></tr> <tr><td> </td> <td>6:pieces </td><td>Literal </td><td> 6 'pieces' </td></tr> <tr><td> </td> <td>79@Qt, </td><td>Copy </td><td> 457 @ 1720 </td></tr> <tr><td> </td> <td>F: Example: eskil</td><td>Literal </td><td> 15 ' Example: eskil'</td></tr> <tr><td> </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 <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 |
︙ | ︙ | |||
293 294 295 296 297 298 299 | 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) | | < | 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 | 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> <h1 id="notes">Notes</h1> <ul> <li>Pure text files generate a pure text delta. |
︙ | ︙ |
Changes to www/embeddeddoc.wiki.
1 | <title>Project Documentation</title> | < | 1 2 3 4 5 6 7 8 | <title>Project Documentation</title> 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. |
︙ | ︙ | |||
28 29 30 31 32 33 34 | <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: | | | | 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 | <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: <pre> <i><baseurl></i><big><b>/doc/</b></big><i><version></i><big><b>/</b></big><i><filename></i> </pre> The <i><baseurl></i> is the main URL used to access the fossil web server. For example, the <i><baseurl></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><baseurl></i> is usually <b>http://localhost:8080/</b>. |
︙ | ︙ | |||
137 138 139 140 141 142 143 | 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: | | | | | | | | | | | | 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 | 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: <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: <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 "<baseurl>" 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: <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 |
︙ | ︙ | |||
199 200 201 202 203 204 205 | 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: | | | | | 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 | 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: <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: <pre> #!/usr/bin/fossil repository: /fossil/fossil.fossil </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, |
︙ | ︙ | |||
240 241 242 243 244 245 246 | </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: | < < | | < | 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 | </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: <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> 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. |
Changes to www/encryptedrepos.wiki.
1 | <title>How To Use Encrypted Repositories</title> | > | > | | > > | | > | | | | > | | > > | | > > | | > > | | > < | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 | <title>How To Use Encrypted Repositories</title> <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. <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. <pre> ./configure --with-see; make </pre> To build for Windows using MSVC, add the "USE_SEE=1" argument to the "nmake" command line. <pre> nmake -f makefile.msc USE_SEE=1 </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. <h2>Additional Security</h2> Use the FOSSIL_SECURITY_LEVEL environment for additional protection. <pre> export FOSSIL_SECURITY_LEVEL=1 </pre> A setting of 1 or greater prevents fossil from trying to remember the previous sync password. <pre> export FOSSIL_SECURITY_LEVEL=2 </pre> A setting of 2 or greater causes all password prompts to be preceded by a random translation matrix similar to the following: <pre> abcde fghij klmno pqrst uvwyz qresw gjymu dpcoa fhkzv inlbt </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. |
Changes to www/event.wiki.
︙ | ︙ | |||
71 72 73 74 75 76 77 | 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: | < | | | | < < | | | | | < < | | | < | 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 | 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: <verbatim> fossil wiki create TestTechnote -t now --technote-bgcolor lightgreen technote.md Created new tech note 2021-03-15 13:05:56 </verbatim> 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: <verbatim> fossil wiki ls --technote --show-technote-ids z739263a134bf0da1d28e939f4c4367f51ef4c51 2020-12-19 13:20:19 e15a918a8bed71c2ac091d74dc397b8d3340d5e1 2018-09-22 17:40:10 </verbatim> A technote ID is the UUID of the technote. To view an individual technote, use the <b>wiki export</b> command: <verbatim> fossil wiki export --technote version-2.16 Release Notes 2021-07-02 This note describes changes in the Fossil snapshot for ... </verbatim> 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 |
︙ | ︙ |
Changes to www/faq.tcl.
︙ | ︙ | |||
10 11 12 13 14 15 16 | faq { What GUIs are available for fossil? } { The fossil executable comes with a [./webui.wiki | web-based GUI] built in. Just run: | | | | 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | faq { What GUIs are available for fossil? } { The fossil executable comes with a [./webui.wiki | web-based GUI] built in. Just run: <pre> <b>fossil [/help/ui|ui]</b> <i>REPOSITORY-FILENAME</i> </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 { |
︙ | ︙ | |||
40 41 42 43 44 45 46 | 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: | | | | 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 | 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: <pre> <b>fossil [/help/branch|branch] new</b> <i>BRANCH-NAME BASIS</i> </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. |
︙ | ︙ | |||
73 74 75 76 77 78 79 | "--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: | | | | 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 | "--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: <pre> <b>fossil [/help/branch|tag] add</b> <i>TAGNAME</i> <i>CHECK-IN</i> </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 |
︙ | ︙ | |||
125 126 127 128 129 130 131 | 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: | > | | > > | | > > | | | < | | 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 | 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: <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> Once you have the repository cloned, you can open a local check-out as follows: <pre> mkdir src; cd src; fossil [/help/open|open] ../fossil.fossil </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: <pre> fossil [/help/update|update] </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>\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 "$body</li>\n" } puts {</ol>} |
Changes to www/faq.wiki.
1 | <title>Fossil FAQ</title> | < | | | | | | | | | | | | | | | | | | > | | > > | | > > | | | | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 | <title>Fossil FAQ</title> 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> The fossil executable comes with a [./webui.wiki | web-based GUI] built in. Just run: <pre> <b>fossil [/help/ui|ui]</b> <i>REPOSITORY-FILENAME</i> </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.)</li> <p id="q2"><b>(2) What is the difference between a "branch" and a "fork"?</b></p> 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.</li> <p id="q3"><b>(3) How do I create a new branch?</b></p> 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: <pre> <b>fossil [/help/branch|branch] new</b> <i>BRANCH-NAME BASIS</i> </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.</li> <p id="q4"><b>(4) How do I tag a check-in?</b></p> 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: <pre> <b>fossil [/help/branch|tag] add</b> <i>TAGNAME</i> <i>CHECK-IN</i> </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.</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> 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]</li> <p id="q6"><b>(6) How can I delete inappropriate content from my fossil repository?</b></p> 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> 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> Once you have the repository cloned, you can open a local check-out as follows: <pre> mkdir src; cd src; fossil [/help/open|open] ../fossil.fossil </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: <pre> fossil [/help/update|update] </pre></li> <p id="q8"><b>(8) How do I import or export content from and to other version control systems?</b></p> Please see [./inout.wiki | Import And Export]</li> </ol> |
Changes to www/fileformat.wiki.
1 | <title>Fossil File Formats</title> | < < < | 1 2 3 4 5 6 7 8 | <title>Fossil File Formats</title> 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 |
︙ | ︙ | |||
108 109 110 111 112 113 114 | 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: | | | | 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 | 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: <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> </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. |
︙ | ︙ | |||
146 147 148 149 150 151 152 | 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: | | | | 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 | 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: <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> </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 |
︙ | ︙ | |||
261 262 263 264 265 266 267 | 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: | | | | | | 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 | 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: <p class="indent"> <b>M</b> <i>artifact-id</i><br /> <b>Z</b> <i>checksum</i> </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: <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 /> </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 |
︙ | ︙ | |||
336 337 338 339 340 341 342 | <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: | | | | 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 | <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: <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> </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 |
︙ | ︙ | |||
377 378 379 380 381 382 383 | [/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: | | | | 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 | [/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: <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> </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: |
︙ | ︙ | |||
425 426 427 428 429 430 431 | 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: | | | | 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 | 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: <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> </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. |
︙ | ︙ | |||
467 468 469 470 471 472 473 | 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: | | | | 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 | 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: <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> </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. |
︙ | ︙ | |||
532 533 534 535 536 537 538 | <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: | | | | 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 | <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: <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> </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. |
︙ | ︙ | |||
608 609 610 611 612 613 614 | 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. | | | < < < | 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 | 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> <tr> <th>⇩ Card Format / Used By ⇨</th> <th>Manifest</th> <th>Cluster</th> <th>Control</th> <th>Wiki</th> <th>Ticket</th> <th>Attachment</th> <th>Technote</th> |
︙ | ︙ | |||
907 908 909 910 911 912 913 | 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: | | | | 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 | 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: <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." </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> |
︙ | ︙ |
Changes to www/fossil-v-git.wiki.
︙ | ︙ | |||
32 33 34 35 36 37 38 | <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. | | | > | | > | 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 | <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. <table style="width: fit-content"> <tr><th>GIT</th><th>FOSSIL</th><th>more</th></tr> <tr> <td>File versioning only</td> <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 ↓</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 ↓</a></td> </tr> |
︙ | ︙ | |||
95 96 97 98 99 100 101 | <td><a href="#testing">2.8 ↓</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 ↓</a></td> </tr> | | | 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 | <td><a href="#testing">2.8 ↓</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 ↓</a></td> </tr> </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 & bug tracking], [./embeddeddoc.wiki | embedded documentation], |
︙ | ︙ | |||
795 796 797 798 799 800 801 | 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> | | | | | | | | 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 | 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 </pre> ...are all the same command in Fossil: <pre> $ 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 |
︙ | ︙ |
Changes to www/fossil_prompt.wiki.
1 | <title>Fossilized Bash Prompt</title> | < | | | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | <title>Fossilized Bash Prompt</title> 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: <pre> . fossil_prompt.sh </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. |
Changes to www/gitusers.md.
︙ | ︙ | |||
71 72 73 74 75 76 77 | 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: | | | | 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 | 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 …is best given as: 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 |
︙ | ︙ | |||
107 108 109 110 111 112 113 | 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): | | | 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 | 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 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: |
︙ | ︙ | |||
178 179 180 181 182 183 184 | 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: | | | | | | | | | | | | | | | | | | | | | 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 | 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 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 That is approximately equivalent to this in Fossil: 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 . 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 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." 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." 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 |
︙ | ︙ | |||
314 315 316 317 318 319 320 | #### <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: | | | | | | | | | | | | | | | | | | | 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 | #### <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 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 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} …which you can approximate in Fossil as: 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 Rather than use the “dry run” form of [the `update` command][up], you can say: fossil timeline after current …or if you want to restrict the output to the current branch: 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 That’s rather obscure! Fossil answers the same question with a simpler command: 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}..@ 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 …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 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 |
︙ | ︙ | |||
466 467 468 469 470 471 472 | 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: | | | | | 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 | 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 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 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. |
︙ | ︙ | |||
524 525 526 527 528 529 530 | <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: | | | | | | | | | 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 | <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 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 (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 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 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 |
︙ | ︙ | |||
589 590 591 592 593 594 595 | [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: | | | | | 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 | [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 …is simply this in Fossil: 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 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. |
︙ | ︙ | |||
690 691 692 693 694 695 696 | 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.) ``` | | | | | | | | | | | 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 | 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 ``` 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 ``` 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 |
︙ | ︙ | |||
748 749 750 751 752 753 754 | 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: ``` | | | | | | 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 | 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 ``` 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 |
︙ | ︙ | |||
832 833 834 835 836 837 838 | 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: | | | | 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 | 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' 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' 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). |
︙ | ︙ | |||
874 875 876 877 878 879 880 | 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 | | | | | | | | | | | 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 | 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 …gives much the same output as 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 …or equivalently using a different symbolic commit name: 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 …is fossil time -n 1 COMMIT_ID …or with a shorter, more obvious command, though with more verbose output: 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 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 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`. |
︙ | ︙ | |||
997 998 999 1000 1001 1002 1003 | 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: | | | | 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 | 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 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 [mv]: /help?cmd=mv [rm]: /help?cmd=rm ---- |
︙ | ︙ | |||
1030 1031 1032 1033 1034 1035 1036 | 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]: | | | 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 | 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} 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. |
︙ | ︙ | |||
1070 1071 1072 1073 1074 1075 1076 | 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: | | | | | | | | | 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 | 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) 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 “Blast! Forgot the commit ID!” 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 “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) “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) “Better. Let’s check it out:” 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 |
︙ | ︙ | |||
1130 1131 1132 1133 1134 1135 1136 | 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: | | | 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 | 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 …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: |
︙ | ︙ | |||
1179 1180 1181 1182 1183 1184 1185 | 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: | | | | | | | | | | | | | | | | | 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 | 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 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 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 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 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 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 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 |
︙ | ︙ | |||
1276 1277 1278 1279 1280 1281 1282 | 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: | | | | | | | | 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 | 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/ 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 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 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 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. |
︙ | ︙ |
Changes to www/hashpolicy.wiki.
︙ | ︙ | |||
166 167 168 169 170 171 172 | 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: | | | | 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 | 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: <verbatim> fossil hash-policy sha3 </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 |
︙ | ︙ |
Changes to www/image-format-vs-repo-size.md.
︙ | ︙ | |||
157 158 159 160 161 162 163 | 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: | | | | | | | | | | | | | | | | | | | | 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 | 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 .svgz.svg: gzip -dc < $< > $@ .svg.svgz: gzip -9c < $< > $@ .bmp.png: convert -quality 95 $< $@ .png.bmp: convert $< $@ SS_FILES := $(wildcard spreadsheet/*) 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 $(SS_FILES): spreadsheet.xlsx unzip $@ -d $< 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! |
︙ | ︙ |
Changes to www/index.wiki.
1 2 3 4 | <title>Home</title> <h3>What Is Fossil?</h3> | | | | 1 2 3 4 5 6 7 8 9 10 11 12 13 | <title>Home</title> <h3>What Is Fossil?</h3> <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 & Hints] <li> [./changes.wiki | Change Log] <li> [../COPYRIGHT-BSD2.txt | License] |
︙ | ︙ |
Changes to www/inout.wiki.
1 2 3 4 5 6 7 8 9 10 11 12 | <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: | | | | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 | <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: <pre> cd git-repo git fast-export --all | fossil import --git new-repo.fossil </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 |
︙ | ︙ | |||
56 57 58 59 60 61 62 | 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: | | | | 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 | 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: <pre> git init new-repo cd new-repo fossil export --git ../repo.fossil | git fast-import </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. |
︙ | ︙ | |||
95 96 97 98 99 100 101 | 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: | | | | | | | | 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 | 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: <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> 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: <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> Changes in the Git repository can be exported to the Fossil repository and then pushed to the remote: <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> |
Changes to www/javascript.md.
︙ | ︙ | |||
369 370 371 372 373 374 375 | _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 | | | | | | | | | | | | | | | 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 | _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 ....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 |
︙ | ︙ | |||
574 575 576 577 578 579 580 | _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 | | | 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 | _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; …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 |
︙ | ︙ |
Changes to www/loadmgmt.md.
︙ | ︙ | |||
50 51 52 53 54 55 56 | 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: | | | | | 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 | 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 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 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 |
︙ | ︙ |
Changes to www/makefile.wiki.
︙ | ︙ | |||
144 145 146 147 148 149 150 | 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: | | | | | | 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 | 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: <pre> mkversion.exe manifest.uuid manifest VERSION >VERSION.h </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: <pre> mkbuiltin.exe diff.tcl <i>OtherFiles...</i> >builtin_data.h </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> |
︙ | ︙ | |||
183 184 185 186 187 188 189 | 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: | | | | | | 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 | 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: <pre> ./mkindex src.c >page_index.h </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: <pre> ./translate src.c >src_.c </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. |
︙ | ︙ | |||
233 234 235 236 237 238 239 | 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: | | | | 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 | 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: <pre> makeheaders src_.c:src.h sqlite3.h th.h VERSION.h </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 |
︙ | ︙ | |||
302 303 304 305 306 307 308 | 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: | | | | | | 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 | 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: <pre> ./configure --fossil-debug </pre> On Windows: <pre> win\buildmsvc.bat FOSSIL_DEBUG=1 </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] |
Changes to www/mirrortogithub.md.
︙ | ︙ | |||
9 10 11 12 13 14 15 | 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: | | | | | 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 | 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 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 \ 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 |
︙ | ︙ | |||
56 57 58 59 60 61 62 | 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: | | | | 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 | 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 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 ## 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 |
︙ | ︙ | |||
140 141 142 143 144 145 146 | ## <a id='ex1'></a>Example GitHub Mirrors As of this writing (2019-03-16) Fossil’s own repository is mirrored on GitHub at: | < | < | < | 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 | ## <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> In addition, an official Git mirror of SQLite is available: > <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. |
Changes to www/mkindex.tcl.
︙ | ︙ | |||
164 165 166 167 168 169 170 | <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> | | | | 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 | <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> <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 { |
︙ | ︙ |
Changes to www/newrepo.wiki.
︙ | ︙ | |||
36 37 38 39 40 41 42 | 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. | | | | | 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 | 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. <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. </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 |
︙ | ︙ |
Changes to www/password.wiki.
1 | <title>Fossil Password Management</title> | < | 1 2 3 4 5 6 7 8 | <title>Fossil Password Management</title> 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. |
︙ | ︙ | |||
20 21 22 23 24 25 26 | 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 | | | | | | | | 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 | 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 <pre> CE59BB9F186226D80E49D1FA2DB29F935CCA0333/alice/asdfg </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: <pre> fossil test-hash-passwords <i>REPOSITORY-NAME</i> </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: <pre> UPDATE user SET pw='asdfg' WHERE login='alice'; </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", |
︙ | ︙ | |||
115 116 117 118 119 120 121 | 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". | | | | | | 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 | 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". <pre> http://<span style="color:blue">login:password</span>@servername.org/path </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. <pre> http://<span style="color:blue">login:*password</span>@servername.org/path </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. |
Changes to www/permutedindex.html.
︙ | ︙ | |||
9 10 11 12 13 14 15 | <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> | | | | 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 | <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> <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> |
︙ | ︙ |
Changes to www/pop.wiki.
1 | <title>Principles Of Operation</title> | < | 1 2 3 4 5 6 7 8 | <title>Principles Of Operation</title> 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 |
︙ | ︙ |
Changes to www/private.wiki.
1 2 3 4 5 6 7 8 9 10 11 12 | <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: | | | | | > > > > > > > > > > > > > < < < < < < < < < < < < < | | | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 | <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: <pre> fossil commit --private </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: <pre> fossil update trunk fossil merge private fossil commit </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. <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: <verbatim> fossil clone --private http://user@linux.localnetwork:8080/ mac-clone.fossil </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. |
︙ | ︙ | |||
99 100 101 102 103 104 105 | 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: | | | | 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 | 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: <pre> fossil scrub --private </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. |
Changes to www/qandc.wiki.
1 | <title>Questions And Criticisms</title> | < < | | | | | | | | | | | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 | <title>Questions And Criticisms</title> This page is a collection of real questions and criticisms that were raised against Fossil early in its history (circa 2008). This page is old and has not been kept up-to-date. See the [/finfo?name=www/qandc.wiki|change history of this page]. <b>Fossil sounds like a lot of reinvention of the wheel. Why create your own DVCS when you could have reused mercurial?</b> <div class="indent"> I wrote fossil because none of the other available DVCSes met my needs. If the other DVCSes do meet your needs, then you might not need fossil. But they don't meet mine, and so fossil is necessary for me. Features provided by fossil that one does not get with other DVCSes include: <ol> <li> Integrated <a href="wikitheory.wiki">wiki</a>. </li> <li> Integrated <a href="bugtheory.wiki">bug tracking</a> </li> <li> Immutable artifacts </li> <li> Self-contained, stand-alone executable that can be run in a <a href="http://en.wikipedia.org/wiki/Chroot">chroot jail</a> </li> <li> Simple, well-defined, <a href="fileformat.wiki">enduring file format</a> </li> <li> Integrated <a href="webui.wiki">web interface</a> </li> </ol> </div> <b>Why should I use this rather than Trac?</b> <div class="indent"> <ol> <li> Fossil is distributed. You can view and/or edit tickets, wiki, and code while off network, then sync your changes later. With Trac, you can only view and edit tickets and wiki while you are connected to the server. </li> <li> Fossil is lightweight and fully self-contained. It is very easy to setup on a low-resource machine. Fossil does not require an administrator.</li> <li> Fossil integrates code versioning into the same repository with wiki and tickets. There is nothing extra to add or install. Fossil is an all-in-one turnkey solution. </li> </ol> </div> <b>Love the concept here. Anyone using this for real work yet?</b> <div class="indent"> Fossil is <a href="https://fossil-scm.org/">self-hosting</a>. In fact, this page was probably delivered to your web-browser via a working fossil instance. The same virtual machine that hosts https://fossil-scm.org/ (a <a href="http://www.linode.com/">Linode 720</a>) also hosts 24 other fossil repositories for various small projects. The documentation files for <a href="http://www.sqlite.org/">SQLite</a> are hosted in a fossil repository <a href="http://www.sqlite.org/docsrc/">here</a>, for example. Other projects are also adopting fossil. But fossil does not yet have the massive user base of git or mercurial. </div> <b>Fossil looks like the bug tracker that would be in your Linksys Router's administration screen.</b> <div class="indent"> I take a pragmatic approach to software: form follows function. To me, it is more important to have a reliable, fast, efficient, enduring, and simple DVCS than one that looks pretty. On the other hand, if you have patches that improve the appearance of Fossil without seriously compromising its reliability, performance, and/or maintainability, I will be happy to accept them. Fossil is self-hosting. Send email to request a password that will let you push to the main fossil repository. </div> <b>It would be useful to have a separate application that keeps the bug-tracking database in a versioned file. That file can then be pushed and pulled along with the rest repository.</b> <div class="indent"> Fossil already <u>does</u> push and pull bugs along with the files in your repository. But fossil does <u>not</u> track bugs as files in the source tree. That approach to bug tracking was rejected for three reasons: <ol> <li> Check-ins in fossil are immutable. So if |
︙ | ︙ | |||
105 106 107 108 109 110 111 | of tickets to developers with check-in privileges and an installed copy of the fossil executable. Casual passers-by on the internet should be permitted to create tickets. </ol> These points are reiterated in the opening paragraphs of the <a href="bugtheory.wiki">Bug-Tracking In Fossil</a> document. | | | | | | | < | < < | 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 | of tickets to developers with check-in privileges and an installed copy of the fossil executable. Casual passers-by on the internet should be permitted to create tickets. </ol> These points are reiterated in the opening paragraphs of the <a href="bugtheory.wiki">Bug-Tracking In Fossil</a> document. </div> <b>Fossil is already the name of a plan9 versioned append-only filesystem.</b> <div class="indent"> I did not know that. Perhaps they selected the name for the same reason that I did: because a repository with immutable artifacts preserves an excellent fossil record of a long-running project. </div> <b>The idea of storing a repository in a binary blob like an SQLite database terrifies me.</b> <div class="indent"> The use of SQLite to store the database is likely more stable and secure than any other approach, due to the fact that SQLite is transactional. Fossil also implements several internal <a href="selfcheck.wiki">self-checks</a> to insure that no information is ever lost. </div> <b>I am dubious of the benefits of including wikis and bug trackers directly in the VCS - either they are under-featured compared to full software like Trac, or the VCS is massively bloated compared to Subversion or Bazaar.</b> <div class="indent"> I have no doubt that Trac has many features that fossil lacks. But that is not the point. Fossil has several key features that Trac lacks and that I need: most notably the fact that fossil supports disconnected operation. As for bloat: Fossil is a single self-contained executable. You do not need any other packages (diff, patch, merge, cvs, svn, rcs, git, python, perl, tcl, apache, sqlite, and so forth) in order to run fossil. Fossil runs just fine in a chroot jail all by itself. And the self-contained fossil executable is much less than 1MB in size. (Update 2015-01-12: Fossil has grown in the years since the previous sentence was written but is still much less than 2MB according to "size" when compiled using -Os on x64 Linux.) Fossil is the very opposite of bloat. </div> |
Changes to www/quickstart.wiki.
1 | <title>Fossil Quick Start Guide</title> | < < < | | | < | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 | <title>Fossil Quick Start Guide</title> This is a guide to help you get started using the Fossil [https://en.wikipedia.org/wiki/Distributed_version_control|Distributed Version Control System] quickly and painlessly. <h2 id="install">Installing</h2> Fossil is a single self-contained C program. You need to either download a [https://fossil-scm.org/home/uv/download.html|precompiled binary] or <a href="build.wiki">compile it yourself</a> from sources. Install Fossil by putting the fossil binary someplace on your $PATH. You can test that Fossil is present and working like this: <pre><b>fossil version This is fossil version 2.13 [309af345ab] 2020-09-28 04:02:55 UTC </b></pre> <h2 id="workflow" name="fslclone">General Work Flow</h2> Fossil works with repository files (a database in a single file with the project's complete history) and with checked-out local trees (the working directory you use to do your work). (See [./glossary.md | the glossary] for more background.) |
︙ | ︙ | |||
46 47 48 49 50 51 52 | operations. <h2 id="new">Starting A New Project</h2> To start a new project with fossil create a new empty repository this way: ([/help/init | more info]) | < | | < | | < | < < < | | | | | | | | | | < < | < | 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 | operations. <h2 id="new">Starting A New Project</h2> To start a new project with fossil create a new empty repository this way: ([/help/init | more info]) <pre><b>fossil init</b> <i>repository-filename</i> </pre> You can name the database anything you like, and you can place it anywhere in the filesystem. The <tt>.fossil</tt> extension is traditional but only required if you are going to use the <tt>[/help/server | fossil server DIRECTORY]</tt> feature.” <h2 id="clone">Cloning An Existing Repository</h2> Most fossil operations interact with a repository that is on the local disk drive, not on a remote system. Hence, before accessing a remote repository it is necessary to make a local copy of that repository. Making a local copy of a remote repository is called "cloning". Clone a remote repository as follows: ([/help/clone | more info]) <pre><b>fossil clone</b> <i>URL repository-filename</i> </pre> The <i>URL</i> specifies the fossil repository you want to clone. The <i>repository-filename</i> is the new local filename into which the cloned repository will be written. For example, to clone the source code of Fossil itself: <pre><b>fossil clone https://fossil-scm.org/ myclone.fossil</b></pre> If your logged-in username is 'exampleuser', you should see output something like this: <pre><b>Round-trips: 8 Artifacts sent: 0 received: 39421 Clone done, sent: 2424 received: 42965725 ip: 10.10.10.0 Rebuilding repository meta-data... 100% complete... Extra delta compression... Vacuuming the database... project-id: 94259BB9F186226D80E49D1FA2DB29F935CCA0333 server-id: 016595e9043054038a9ea9bc526d7f33f7ac0e42 admin-user: exampleuser (password is "yoWgDR42iv")> </b></pre> If the remote repository requires a login, include a userid in the URL like this: <pre><b>fossil clone https://</b><i>remoteuserid</i><b>@www.example.org/ myclone.fossil</b></pre> You will be prompted separately for the password. Use [https://en.wikipedia.org/wiki/Percent-encoding#Percent-encoding_reserved_characters|"%HH"] escapes for special characters in the userid. For example "/" would be replaced by "%2F" meaning that a userid of "Projects/Budget" would become "Projects%2FBudget") If you are behind a restrictive firewall, you might need to <a href="#proxy">specify an HTTP proxy</a>. |
︙ | ︙ | |||
141 142 143 144 145 146 147 | <h2 id="checkout">Checking Out A Local Tree</h2> To work on a project in fossil, you need to check out a local copy of the source tree. Create the directory you want to be the root of your tree and cd into that directory. Then do this: ([/help/open | more info]) | < | < < < | | | | | | < | | | | | | | | | | | | | | | | | | < < | < < < | | | < < < | | | | | | | | | < | < | | | | | | | | | | | | | | | | < | < | | < > | | < > | | | | < | 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 | <h2 id="checkout">Checking Out A Local Tree</h2> To work on a project in fossil, you need to check out a local copy of the source tree. Create the directory you want to be the root of your tree and cd into that directory. Then do this: ([/help/open | more info]) <pre><b>fossil open</b> <i>repository-filename</i></pre> for example: <pre><b>fossil open ../myclone.fossil BUILD.txt COPYRIGHT-BSD2.txt README.md ︙ </tt></b></pre> (or "fossil open ..\myclone.fossil" on Windows). This leaves you with the newest version of the tree checked out. From anywhere underneath the root of your local tree, you can type commands like the following to find out the status of your local tree: <pre> <b>[/help/info | fossil info]</b> <b>[/help/status | fossil status]</b> <b>[/help/changes | fossil changes]</b> <b>[/help/diff | fossil diff]</b> <b>[/help/timeline | fossil timeline]</b> <b>[/help/ls | fossil ls]</b> <b>[/help/branch | fossil branch]</b> </pre> If you created a new repository using "fossil init" some commands will not produce much output. Note that Fossil allows you to make multiple check-outs in separate directories from the same repository. This enables you, for example, to do builds from multiple branches or versions at the same time without having to generate extra clones. To switch a checkout between different versions and branches, use:< <pre> <b>[/help/update | fossil update]</b> <b>[/help/checkout | fossil checkout]</b> </pre> [/help/update | update] honors the "autosync" option and does a "soft" switch, merging any local changes into the target version, whereas [/help/checkout | checkout] does not automatically sync and does a "hard" switch, overwriting local changes if told to do so. <h2 id="changes">Making and Committing Changes</h2> To add new files to your project or remove existing ones, use these commands: <pre> <b>[/help/add | fossil add]</b> <i>file...</i> <b>[/help/rm | fossil rm]</b> <i>file...</i> <b>[/help/addremove | fossil addremove]</b> <i>file...</i> </pre> The command: <pre><b>[/help/changes | fossil changes]</b></pre> lists files that have changed since the last commit to the repository. For example, if you edit the file "README.md": <pre><b>fossil changes EDITED README.md </b></pre> To see exactly what change was made you can use the command <b>[/help/diff | fossil diff]</b>: <pre><b>fossil diff Index: README.md ============================================================ --- README.md +++ README.md @@ -1,5 +1,6 @@ +Made some changes to the project # Original text </b></pre> "fossil diff" shows the difference between your tree on disk now and as the tree was when you last committed changes. If you haven't committed yet, then it shows the difference relative to the tip-of-trunk commit in the repository, being what you get when you "fossil open" a repository without specifying a version, populating the working directory. To see the most recent changes made to the repository by other users, use "fossil timeline" to find out the most recent commit, and then "fossil diff" between that commit and the current tree: <pre><b>fossil timeline === 2021-03-28 === 03:18:54 [ad75dfa4a0] *CURRENT* Added details to frobnicate command (user: user-one tags: trunk) === 2021-03-27 === 23:58:05 [ab975c6632] Update README.md. (user: user-two tags: trunk) ⋮ fossil diff --from current --to ab975c6632 Index: frobnicate.c ============================================================ --- frobnicate.c +++ frobnicate.c @@ -1,10 +1,11 @@ +/* made a change to the source file */ # Original text </b></pre> "current" is an alias for the checkout version, so the command "fossil diff --from ad75dfa4a0 --to ab975c6632" gives identical results. To commit your changes to a local-only repository: <pre><b>fossil commit</b> <i>(... Fossil will start your editor, if defined)</i><b> # Enter a commit message for this check-in. Lines beginning with # are ignored. # # user: exampleuser # tags: trunk # # EDITED README.md Edited file to add description of code changes New_Version: 7b9a416ced4a69a60589dde1aedd1a30fde8eec3528d265dbeed5135530440ab </b></pre> You will be prompted for check-in comments using whatever editor is specified by your VISUAL or EDITOR environment variable. If none is specified Fossil uses line-editing in the terminal. To commit your changes to a repository that was cloned from a remote repository, you give the same command, but the results are different. |
︙ | ︙ | |||
331 332 333 334 335 336 337 | When you create a new repository, either by cloning an existing project or create a new project of your own, you usually want to do some local configuration. This is easily accomplished using the web-server that is built into fossil. Start the fossil web server like this: ([/help/ui | more info]) | | | | | | | | | | | | | | | | | 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 | When you create a new repository, either by cloning an existing project or create a new project of your own, you usually want to do some local configuration. This is easily accomplished using the web-server that is built into fossil. Start the fossil web server like this: ([/help/ui | more info]) <pre> <b>fossil ui</b> <i>repository-filename</i> </pre> You can omit the <i>repository-filename</i> from the command above if you are inside a checked-out local tree. This starts a web server then automatically launches your web browser and makes it point to this web server. If your system has an unusual configuration, fossil might not be able to figure out how to start your web browser. In that case, first tell fossil where to find your web browser using a command like this: <pre> <b>fossil setting web-browser</b> <i>path-to-web-browser</i> </pre> By default, fossil does not require a login for HTTP connections coming in from the IP loopback address 127.0.0.1. You can, and perhaps should, change this after you create a few users. When you are finished configuring, just press Control-C or use the <b>kill</b> command to shut down the mini-server. <h2 id="sharing">Sharing Changes</h2> When [./concepts.wiki#workflow|autosync] is turned off, the changes you [/help/commit | commit] are only on your local repository. To share those changes with other repositories, do: <pre> <b>[/help/push | fossil push]</b> <i>URL</i> </pre> Where <i>URL</i> is the http: URL of the server repository you want to share your changes with. If you omit the <i>URL</i> argument, fossil will use whatever server you most recently synced with. The [/help/push | push] command only sends your changes to others. To Receive changes from others, use [/help/pull | pull]. Or go both ways at once using [/help/sync | sync]: <pre> <b>[/help/pull | fossil pull]</b> <i>URL</i> <b>[/help/sync | fossil sync]</b> <i>URL</i> </pre> When you pull in changes from others, they go into your repository, not into your checked-out local tree. To get the changes into your local tree, use [/help/update | update]: <pre> <b>[/help/update | fossil update]</b> <i>VERSION</i> </pre> The <i>VERSION</i> can be the name of a branch or tag or any abbreviation to the 40-character artifact identifier for a particular check-in, or it can be a date/time stamp. ([./checkin_names.wiki | more info]) If you omit the <i>VERSION</i>, then fossil moves you to the latest version of the branch your are currently on. The default behavior is for [./concepts.wiki#workflow|autosync] to be turned on. That means that a [/help/pull|pull] automatically occurs when you run [/help/update|update] and a [/help/push|push] happens automatically after you [/help/commit|commit]. So in normal practice, the push, pull, and sync commands are rarely used. But it is important to know about them, all the same. <pre> <b>[/help/checkout | fossil checkout]</b> <i>VERSION</i> </pre> Is similar to update except that it does not honor the autosync setting, nor does it merge in local changes - it prefers to overwrite them and fails if local changes exist unless the <tt>--force</tt> flag is used. <h2 id="branch" name="merge">Branching And Merging</h2> |
︙ | ︙ | |||
426 427 428 429 430 431 432 | To merge two branches back together, first [/help/update | update] to the branch you want to merge into. Then do a [/help/merge|merge] of the other branch that you want to incorporate the changes from. For example, to merge "featureX" changes into "trunk" do this: | | | | | | | 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 | To merge two branches back together, first [/help/update | update] to the branch you want to merge into. Then do a [/help/merge|merge] of the other branch that you want to incorporate the changes from. For example, to merge "featureX" changes into "trunk" do this: <pre> <b>fossil [/help/update|update] trunk</b> <b>fossil [/help/merge|merge] featureX</b> <i># make sure the merge didn't break anything...</i> <b>fossil [/help/commit|commit] </pre> The argument to the [/help/merge|merge] command can be any of the version identifier forms that work for [/help/update|update]. ([./checkin_names.wiki|more info].) The merge command has options to cherry-pick individual changes, or to back out individual changes, if you don't want to do a full merge. |
︙ | ︙ | |||
458 459 460 461 462 463 464 | into trunk previously, you can do so again and Fossil will automatically know to pull in only those changes that have occurred since the previous merge. If a merge or update doesn't work out (perhaps something breaks or there are many merge conflicts) then you back up using: | | | | | | | 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 | into trunk previously, you can do so again and Fossil will automatically know to pull in only those changes that have occurred since the previous merge. If a merge or update doesn't work out (perhaps something breaks or there are many merge conflicts) then you back up using: <pre> <b>[/help/undo | fossil undo]</b> </pre> This will back out the changes that the merge or update made to the working checkout. There is also a [/help/redo|redo] command if you undo by mistake. Undo and redo only work for changes that have not yet been checked in using commit and there is only a single level of undo/redo. <h2 id="server">Setting Up A Server</h2> Fossil can act as a stand-alone web server using one of these commands: <pre> <b>[/help/server | fossil server]</b> <i>repository-filename</i> <b>[/help/ui | fossil ui]</b> <i>repository-filename</i> </pre> The <i>repository-filename</i> can be omitted when these commands are run from within an open check-out, which is a particularly useful shortcut with the <b>fossil ui</b> command. The <b>ui</b> command is intended for accessing the web user interface from a local desktop. (We sometimes call this mode "Fossil UI.") |
︙ | ︙ | |||
525 526 527 528 529 530 531 | If you are behind a restrictive firewall that requires you to use an HTTP proxy to reach the internet, then you can configure the proxy in three different ways. You can tell fossil about your proxy using a command-line option on commands that use the network, <b>sync</b>, <b>clone</b>, <b>push</b>, and <b>pull</b>. | | | | | | | | | | | | | 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 | If you are behind a restrictive firewall that requires you to use an HTTP proxy to reach the internet, then you can configure the proxy in three different ways. You can tell fossil about your proxy using a command-line option on commands that use the network, <b>sync</b>, <b>clone</b>, <b>push</b>, and <b>pull</b>. <pre> <b>fossil clone </b><i>URL</i> <b>--proxy</b> <i>Proxy-URL</i> </pre> It is annoying to have to type in the proxy URL every time you sync your project, though, so you can make the proxy configuration persistent using the [/help/setting | setting] command: <pre> <b>fossil setting proxy </b><i>Proxy-URL</i> </pre> Or, you can set the "<b>http_proxy</b>" environment variable: <pre> <b>export http_proxy=</b><i>Proxy-URL</i> </pre> To stop using the proxy, do: <pre> <b>fossil setting proxy off</b> </pre> Or unset the environment variable. The fossil setting for the HTTP proxy takes precedence over the environment variable and the command-line option overrides both. If you have a persistent proxy setting that you want to override for a one-time sync, that is easily done on the command-line. For example, to sync with a co-worker's repository on your LAN, you might type: <pre> <b>fossil sync http://192.168.1.36:8080/ --proxy off</b> </pre> <h2 id="links">Other Resources</h2> <ul> <li> <a href="./gitusers.md">Hints For Users With Prior Git Experience</a> <li> <a href="./whyusefossil.wiki">Why You Should Use Fossil</a> <li> <a href="./history.md">The History and Purpose of Fossil</a> <li> <a href="./branching.wiki">Branching, Forking, and Tagging</a> <li> <a href="./hints.wiki">Fossil Tips and Usage Hints</a> <li> <a href="./permutedindex.html">Comprehensive Fossil Doc Index</a> </ul> |
Changes to www/quotes.wiki.
1 2 3 4 5 6 | <title>What People Are Saying</title> The following are collected quotes from various forums and blogs about Fossil, Git, and DVCSes in general. This collection is put together by the creator of Fossil, so of course there is selection bias... | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 | <title>What People Are Saying</title> The following are collected quotes from various forums and blogs about Fossil, Git, and DVCSes in general. This collection is put together by the creator of Fossil, so of course there is selection bias... <h2>On The Usability Of Git</h2> <ol> <li>Git approaches the usability of iptables, which is to say, utterly unusable unless you have the manpage tattooed on you arm. <p class="local-indent"> <i>by mml at [http://news.ycombinator.com/item?id=1433387]</i> </p> <li><nowiki>It's simplest to think of the state of your [git] repository as a point in a high-dimensional "code-space", in which branches are represented as n-dimensional membranes, mapping the spatial loci of successive commits onto the projected manifold of each cloned repository.</nowiki> <p class="local-indent"> <i>by Jonathan Hartley at [https://www.tartley.com/posts/a-guide-to-git-using-spatial-analogies]; <br>Quoted here: [https://lwn.net/Articles/420152/].</i> </p> <li>Git is not a Prius. Git is a Model T. Its plumbing and wiring sticks out all over the place. You have to be a mechanic to operate it successfully or you'll be stuck on the side of the road when it breaks down. And it <b>will</b> break down. <p class="local-indent"> <i>Nick Farina at [http://nfarina.com/post/9868516270/git-is-simpler]</i> </p> <li>Initial revision of "git", The information manager from hell <p class="local-indent"> <i>Linus Torvalds - 2005-04-07 22:13:13<br> Commit comment on the very first source-code check-in for git </p> <li>I've been experimenting a lot with git at work. Damn, it's complicated. It has things to trip you up with that sane people just wouldn't ever both with including the ability to allow you to commit stuff in such a way that you can't find it again afterwards (!!!) Demented workflow complexity on acid? <p>* dkf really wishes he could use fossil instead</p> <p class="local-indent"> <i>by Donal K. Fellow (dkf) on the Tcl/Tk chatroom, 2013-04-09.</i> </p> <li>[G]it is <i>designed</i> to forget things. <p class="local-indent"> <i>[http://www.cs.cmu.edu/~davide/howto/git_lose.html] </p> <li>[I]n nearly 31 years of using a computer i have, in total, lost more data to git (while following the instructions!!!) than any other single piece of software. <p class="local-indent"> <i>Stephan Beal on the [http://www.mail-archive.com/fossil-users@lists.fossil-scm.org/msg17181.html|Fossil mailing list] 2014-09-01.</i> </p> <li>If programmers _really_ wanted to help scientists, they'd build a version control system that was more usable than Git. <p class="local-indent"> <i>Tweet by Greg Wilson @gvwilson on 2015-02-22 17:47</i> </p> <li><img src='xkcd-git.gif' align='top'> <p class="local-indent"><i>Randall Munroe. [http://xkcd.com/1597/]</i><p> </ol> <h2>On The Usability Of Fossil</h2> <ol> <li value=11> Fossil mesmerizes me with simplicity especially after I struggled to get a bug-tracking system to work with mercurial. <p class="local-indent"> <i>rawjeev at [https://stackoverflow.com/a/2100469/142454]</i> </p> <li>Fossil is the best thing to happen to my development workflow this year, as I am pretty sure that using Git has resulted in the premature death of too many of my brain cells. I'm glad to be able to replace Git in every place that I possibly can with Fossil. <p class="local-indent"> <i>Joe Prostko at [http://www.mail-archive.com/fossil-users@lists.fossil-scm.org/msg16716.html] </p> <li>This is my favourite VCS. I can carry it on a USB. And it's a complete system, with it's own server, ticketing system, Wiki pages, and a very, very helpful timeline visualization. And the entire program in a single file! <p class="local-indent"> <i>thunderbong commenting on hacker news: [https://news.ycombinator.com/item?id=9131619]</i> </p> </ol> <h2>On Git Versus Fossil</h2> <ol> <li value=14> After prolonged exposure to fossil, i tend to get the jitters when I work with git... <p class="local-indent"> <i>sriku - at [https://news.ycombinator.com/item?id=16104427]</i> </p> <li> Just want to say thanks for fossil making my life easier.... Also <nowiki>[for]</nowiki> not having a misanthropic command line interface. <p class="local-indent"> <i>Joshua Paine at [http://www.mail-archive.com/fossil-users@lists.fossil-scm.org/msg02736.html]</i> </p> <li>We use it at a large university to manage code that small teams write. The runs everywhere, ease of installation and portability is something that seems to be a good fit with the environment we have (highly ditrobuted, sometimes very restrictive firewalls, OSX/Win/Linux). We are happy with it and teaching a Msc/Phd student (read complete novice) fossil has just been a smoother ride than Git was. <p class="local-indent"> <i>viablepanic at [https://www.reddit.com/r/programming/comments/bxcto/why_not_fossil_scm/c0p30b4?utm_source=share&utm_medium=web2x&context=3]</i> </p> <li>In the fossil community - and hence in fossil itself - development history is pretty much sacrosanct. The very name "fossil" was to chosen to reflect the unchanging nature of things in that history. <br><br> In git (or rather, the git community), the development history is part of the published aspect of the project, so it provides tools for rearranging that history so you can present what you "should" have done rather than what you actually did. <p class="local-indent"> <i>Mike Meyer on the Fossil mailing list, 2011-10-04</i> </p> <li>github is such a pale shadow of what fossil does. <p class="local-indent"> <i>dkf on the Tcl chatroom, 2013-12-06</i> </p> <li>[With fossil] I actually enjoy keeping track of source files again. <p class="local-indent"> <a href="https://wholesomedonut.prose.sh/using-fossil-not-git">https://wholesomedonut.prose.sh/using-fossil-not-git</a> </p> </ol> |
Changes to www/reviews.wiki.
1 2 3 4 5 6 7 8 9 10 11 12 | <title>Reviews</title> <b>External links:</b> * [https://www.nixtu.info/2010/03/fossil-dvcs-on-go-first-impressions.html | Fossil DVCS on the Go - First Impressions] <b>See Also:</b> * [./quotes.wiki | Short Quotes on Fossil, Git, And DVCSes] <b>Daniel writes on 2009-01-06:</b> | | | | | | | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 | <title>Reviews</title> <b>External links:</b> * [https://www.nixtu.info/2010/03/fossil-dvcs-on-go-first-impressions.html | Fossil DVCS on the Go - First Impressions] <b>See Also:</b> * [./quotes.wiki | Short Quotes on Fossil, Git, And DVCSes] <b>Daniel writes on 2009-01-06:</b> <div class="indent"> The reasons I use fossil are that it's the only version control I have found that I can get working through the VERY annoying MS firewalls at work.. (albeit through an ntlm proxy) and I just love single .exe applications! </div> <b>Joshua Paine on 2010-10-22:</b> <div class="indent"> With one of my several hats on, I'm in a small team using git. Another team member just checked some stuff into trunk that should have been on a branch. Nothing else had happened since, so in fossil I would have just edited that commit and put it on a new branch. In git that can't actually be done without danger once other people have pulled, so I had to create a new commit rolling back the changes, then branch and cherry pick the earlier changes, then figure out how to make my new branch shared instead of private. Just want to say thanks for fossil making my life easier on most of my projects, and being able to move commits to another branch after the fact and shared-by-default branches are good features. Also not having a misanthropic command line interface. </div> <b>Stephan Beal writes on 2009-01-11:</b> <div class="indent"> Sometime in late 2007 I came across a link to fossil on <a href="http://www.sqlite.org/">sqlite.org</a>. It was a good thing I bookmarked it, because I was never able to find the link again (it might have been in a bug report or something). The reasons I first took a close look at it were (A) it stemmed from the sqlite project, which I've held in high regards for years (e.g. I wrote JavaScript bindings for it: |
︙ | ︙ | |||
133 134 135 136 137 138 139 | I remember my first reaction to fossil being, "this will be an excellent solution for small projects (like the dozens we've all got sitting on our hard drives but which don't justify the hassle of version control)." A year of daily use in over 15 source trees has confirmed that, and I continue to heartily recommend fossil to other developers I know who also have their own collection of "unhosted" pet projects. | | | 133 134 135 136 137 138 139 140 | I remember my first reaction to fossil being, "this will be an excellent solution for small projects (like the dozens we've all got sitting on our hard drives but which don't justify the hassle of version control)." A year of daily use in over 15 source trees has confirmed that, and I continue to heartily recommend fossil to other developers I know who also have their own collection of "unhosted" pet projects. </div> |
Changes to www/scgi.wiki.
1 2 3 4 5 6 | <title>Fossil SCGI</title> To run Fossil using SCGI, start the [/help/server|fossil server] command with the --scgi command-line option. You will probably also want to specific an alternative TCP/IP port using --port. For example: | | | | | | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 | <title>Fossil SCGI</title> To run Fossil using SCGI, start the [/help/server|fossil server] command with the --scgi command-line option. You will probably also want to specific an alternative TCP/IP port using --port. For example: <pre> fossil server $REPOSITORY --port 9000 --scgi </pre> Then configure your SCGI-aware web-server to send SCGI requests to port 9000 on the machine where Fossil is running. A typical configuration for this in Nginx is: <pre> location ~ ^/demo_project/ { include scgi_params; scgi_pass localhost:9000; scgi_param SCRIPT_NAME "/demo_project"; scgi_param HTTPS "on"; } </pre> Note that Nginx does not normally send either the PATH_INFO or SCRIPT_NAME variables via SCGI, but Fossil needs one or the other. So the configuration above needs to add SCRIPT_NAME. If you do not do this, Fossil returns an error. |
Changes to www/selfcheck.wiki.
1 2 | <title>Fossil Repository Integrity Self-Checks</title> | < < | 1 2 3 4 5 6 7 8 9 | <title>Fossil Repository Integrity Self-Checks</title> Fossil is designed with features to give it a high level of integrity so that users can have confidence that content will never be mangled or lost by Fossil. This note describes the defensive measures that Fossil uses to help prevent information loss due to bugs. Fossil has been hosting itself and many other projects for |
︙ | ︙ |
Changes to www/selfhost.wiki.
︙ | ︙ | |||
28 29 30 31 32 33 34 | dozen other smaller projects. This demonstrates that Fossil can run on a low-power host processor. Multiple fossil-based projects can easily be hosted on the same machine, even if that machine is itself one of several dozen virtual machines on single physical box. The CGI script that runs the canonical Fossil self-hosting repository is as follows: | | | | | | | | 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 | dozen other smaller projects. This demonstrates that Fossil can run on a low-power host processor. Multiple fossil-based projects can easily be hosted on the same machine, even if that machine is itself one of several dozen virtual machines on single physical box. The CGI script that runs the canonical Fossil self-hosting repository is as follows: <pre> #!/usr/bin/fossil repository: /fossil/fossil.fossil </pre> Server (3) ran for 10 years as a CGI script on a shared hosting account at <a href="http://www.he.net/">Hurricane Electric</a> in Fremont, CA. This server demonstrated the ability of Fossil to run on an economical shared-host web account with no privileges beyond port 80 HTTP access and CGI. It is not necessary to have a dedicated computer with administrator privileges to run Fossil. As far as we are aware, Fossil is the only full-featured configuration management system that can run in such a restricted environment. The CGI script that ran on the Hurricane Electric server was the same as the CGI script shown above, except that the pathnames are modified to suit the environment: <pre> #!/home/hwaci/bin/fossil repository: /home/hwaci/fossil/fossil.fossil </pre> In recent years, virtual private servers have become a more flexible and less expensive hosting option compared to shared hosting accounts. So on 2017-07-25, server (3) was moved onto a $5/month "droplet" [https://en.wikipedia.org/wiki/Virtual_private_server|VPS] from [https://www.digitalocean.com|Digital Ocean] located in San Francisco. Server (3) is synchronized with the canonical server (1) by running a command similar to the following via cron: <pre> /usr/local/bin/fossil all sync -u </pre> Server (2) is a <a href="http://www.linode.com/">Linode 4096</a> located in Newark, NJ and set up just like the canonical server (1) with the addition of a cron job for synchronization. The same cron job also runs the [/help?cmd=git|fossil git export] command after each sync in order to [./mirrortogithub.md#ex1|mirror all changes to GitHub]. |
Changes to www/server/any/cgi.md.
1 2 3 4 5 6 7 8 9 10 11 12 | # Serving via CGI A Fossil server can be run from most ordinary web servers as a CGI program. This feature allows Fossil to seamlessly integrate into a larger website. The [self-hosting Fossil repository web site](../../selfhost.wiki) is implemented using CGI. See the [How CGI Works](../../aboutcgi.wiki) page for background information on the CGI protocol. To run Fossil as CGI, create a CGI script (here called "repo") in the CGI directory of your web server with content like this: | | | | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 | # Serving via CGI A Fossil server can be run from most ordinary web servers as a CGI program. This feature allows Fossil to seamlessly integrate into a larger website. The [self-hosting Fossil repository web site](../../selfhost.wiki) is implemented using CGI. See the [How CGI Works](../../aboutcgi.wiki) page for background information on the CGI protocol. To run Fossil as CGI, create a CGI script (here called "repo") in the CGI directory of your web server with content like this: #!/usr/bin/fossil repository: /home/fossil/repo.fossil Adjust the paths appropriately. It may be necessary to set certain permissions on this file or to modify an `.htaccess` file or make other server-specific changes. Consult the documentation for your particular web server. The following permissions are *normally* required, but, again, may be different for a particular configuration: |
︙ | ︙ | |||
55 56 57 58 59 60 61 | for scripts like our “`repo`” example. To serve multiple repositories from a directory using CGI, use the "directory:" tag in the CGI script rather than "repository:". You might also want to add a "notfound:" tag to tell where to redirect if the particular repository requested by the URL is not found: | | | | | | | | | 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 | for scripts like our “`repo`” example. To serve multiple repositories from a directory using CGI, use the "directory:" tag in the CGI script rather than "repository:". You might also want to add a "notfound:" tag to tell where to redirect if the particular repository requested by the URL is not found: #!/usr/bin/fossil directory: /home/fossil/repos notfound: http://url-to-go-to-if-repo-not-found/ Once deployed, a URL like: <b>http://mydomain.org/cgi-bin/repo/XYZ</b> will serve up the repository `/home/fossil/repos/XYZ.fossil` if it exists. Additional options available to the CGI script are [documented separately](../../cgi.wiki). #### CGI with Apache behind an Nginx proxy For the case where the Fossil repositories live on a computer, itself behind an Internet-facing machine that employs Nginx to reverse proxy HTTP(S) requests and take care of the TLS part of the connections in a transparent manner for the downstream web servers, the CGI parameter `HTTPS=on` might not be set. However, Fossil in CGI mode needs it in order to generate the correct links. Apache can be instructed to pass this parameter further to the CGI scripts for TLS connections with a stanza like SetEnvIf X-Forwarded-Proto "https" HTTPS=on in its config file section for CGI, provided that proxy_set_header X-Forwarded-Proto $scheme; has been be added in the relevant proxying section of the Nginx config file. *[Return to the top-level Fossil server article.](../)* |
Changes to www/server/any/http-over-ssh.md.
︙ | ︙ | |||
13 14 15 16 17 18 19 | ## 1. Force remote Fossil access through a wrapper script <a id="sshd"></a> Put something like the following into the `sshd_config` file on the Fossil repository server: ``` ssh-config | | | | | | | | | 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 | ## 1. Force remote Fossil access through a wrapper script <a id="sshd"></a> Put something like the following into the `sshd_config` file on the Fossil repository server: ``` ssh-config Match Group fossil X11Forwarding no AllowTcpForwarding no AllowAgentForwarding no ForceCommand /home/fossil/bin/wrapper ``` This file is usually found in `/etc/ssh`, but some OSes put it elsewhere. The first line presumes that we will put all users who need to use our Fossil repositories into the `fossil` group, as we will do [below](#perms). You could instead say something like: ``` ssh-config Match User alice,bob,carol,dave ``` You have to list the users allowed to use Fossil in this case because your system likely has a system administrator that uses SSH for remote shell access, so you want to *exclude* that user from the list. For the same reason, you don’t want to put the `ForceCommand` directive outside a `Match` block of some sort. You could instead list the exceptions: ``` ssh-config Match User !evi ``` This would permit only [Evi the System Administrator][evi] to bypass this mechanism. [evi]: https://en.wikipedia.org/wiki/Evi_Nemeth |
︙ | ︙ | |||
66 67 68 69 70 71 72 | instance with certain parameters in order to set up the HTTP-based sync protocol over that SSH tunnel. We need to preserve some of this command and rewrite other parts to make this work. Here is a simpler variant of Andy’s original wrapper script: ``` sh | | | | | | | | 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 | instance with certain parameters in order to set up the HTTP-based sync protocol over that SSH tunnel. We need to preserve some of this command and rewrite other parts to make this work. Here is a simpler variant of Andy’s original wrapper script: ``` sh #!/bin/bash set -- $SSH_ORIGINAL_COMMAND while [ $# -gt 1 ] ; do shift ; done export REMOTE_USER="$USER" ROOT=/home/fossil exec "$ROOT/bin/fossil" http "$ROOT/museum/$(/bin/basename "$1")" ``` The substantive changes are: 1. Move the command rewriting bits to the start. 2. Be explicit about executable paths. You might extend this idea by |
︙ | ︙ | |||
102 103 104 105 106 107 108 | is not the case everywhere. If the script fails to run on your system, try changing this line to point at `bash`, `dash`, `ksh`, or `zsh`. Also check the absolute paths for local correctness: is `/bin/basename` installed on your system, for example? Under this scheme, you clone with a command like: | | | 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 | is not the case everywhere. If the script fails to run on your system, try changing this line to point at `bash`, `dash`, `ksh`, or `zsh`. Also check the absolute paths for local correctness: is `/bin/basename` installed on your system, for example? Under this scheme, you clone with a command like: $ fossil clone ssh://HOST/repo.fossil This will clone the remote `/home/fossil/museum/repo.fossil` repository to your local machine under the same name and open it into a “`repo/`” subdirectory. Notice that we didn’t have to give the `museum/` part of the path: it’s implicit per point #3 above. This presumes your local user name matches the remote user name. Unlike |
︙ | ︙ | |||
127 128 129 130 131 132 133 | the wrapper script from where you placed it and execute it, and that they have read/write access on the directory where the Fossil repositories are stored. You can achieve all of this on a Linux box with: ``` shell | | | | | | | | | | | | | | 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 | the wrapper script from where you placed it and execute it, and that they have read/write access on the directory where the Fossil repositories are stored. You can achieve all of this on a Linux box with: ``` shell sudo adduser fossil for u in alice bob carol dave ; do sudo adduser $u sudo gpasswd -a fossil $u done sudo -i -u fossil chmod 710 . mkdir -m 750 bin mkdir -m 770 museum ln -s /usr/local/bin/fossil bin ``` You then need to copy the Fossil repositories into `~fossil/museum` and make them readable and writable by group `fossil`. These repositories presumably already have Fossil users configured, with the necessary [user capabilities](../../caps/), the point of this article being to show you how to make Fossil-over-SSH pay attention to those caps. You must also permit use of `REMOTE_USER` on each shared repository. Fossil only pays attention to this environment variable in certain contexts, of which “`fossil http`” is not one. Run this command against each repo to allow that: ``` shell echo "INSERT OR REPLACE INTO config VALUES ('remote_user_ok',1,strftime('%s','now'));" | fossil sql -R museum/repo.fossil ``` Now you can configure SSH authentication for each user. Since Fossil’s password-saving feature doesn’t work in this case, I suggest setting up SSH keys via `~USER/.ssh/authorized_keys` since the SSH authentication occurs on each sync, which Fossil’s default-enabled autosync setting makes frequent. |
︙ | ︙ |
Changes to www/server/any/inetd.md.
1 2 3 4 5 6 | # Serving via inetd A Fossil server can be launched on-demand by `inetd` by using the [`fossil http`](/help/http) command. To do so, add a line like the following to its configuration file, typically `/etc/inetd.conf`: | | | | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 | # Serving via inetd A Fossil server can be launched on-demand by `inetd` by using the [`fossil http`](/help/http) command. To do so, add a line like the following to its configuration file, typically `/etc/inetd.conf`: 80 stream tcp nowait.1000 root /usr/bin/fossil /usr/bin/fossil http /home/fossil/repo.fossil In this example, you are telling `inetd` that when an incoming connection appears on TCP port 80 that it should launch the program `/usr/bin/fossil` with the arguments shown. Obviously you will need to modify the pathnames for your particular setup. The final argument is either the name of the fossil repository to be served or a directory containing multiple repositories. If you use a non-standard TCP port on systems where the port specification must be a symbolic name and cannot be numeric, add the desired name and port to `/etc/services`. For example, if you want your Fossil server running on TCP port 12345 instead of 80, you will need to add: fossil 12345/tcp # fossil server and use the symbolic name “`fossil`” instead of the numeric TCP port number (“12345” in the above example) in `inetd.conf`. Notice that we configured `inetd` to launch Fossil as root. See the top-level section on “[The Fossil Chroot Jail](../../chroot.md)” for the consequences of this and |
︙ | ︙ |
Changes to www/server/any/none.md.
︙ | ︙ | |||
26 27 28 29 30 31 32 | * “`ui`” launches a local web browser pointed at this URL. You can omit the _REPOSITORY_ argument if you run one of the above commands from within a Fossil checkout directory to serve that repository: | | | | | 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 | * “`ui`” launches a local web browser pointed at this URL. You can omit the _REPOSITORY_ argument if you run one of the above commands from within a Fossil checkout directory to serve that repository: $ fossil ui # or... $ fossil server You can abbreviate Fossil sub-commands as long as they are unambiguous. “`server`” can currently be as short as “`ser`”. You can serve a directory containing multiple `*.fossil` files like so: $ fossil server --port 9000 --repolist /path/to/repo/dir There is an [example script](/file/tools/fslsrv) in the Fossil distribution that wraps `fossil server` to produce more complicated effects. Feel free to take it, study it, and modify it to suit your local needs. See the [online documentation](/help/server) for more information on the |
︙ | ︙ |
Changes to www/server/any/scgi.md.
1 2 3 4 5 6 7 8 9 10 11 12 13 | # Serving via SCGI There is an alternative to running Fossil as a [standalone HTTP server](./none.md), which is to run it in SimpleCGI (a.k.a. SCGI) mode, which uses the same [`fossil server`](/help/server) command as for HTTP service. Simply add the `--scgi` command-line option and the stand-alone server will speak the SCGI protocol rather than raw HTTP. This can be used with a web server such as [nginx](http://nginx.org) which does not support [Fossil’s CGI mode](./cgi.md). A basic nginx configuration to support SCGI with Fossil looks like this: | | | | | | | | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 | # Serving via SCGI There is an alternative to running Fossil as a [standalone HTTP server](./none.md), which is to run it in SimpleCGI (a.k.a. SCGI) mode, which uses the same [`fossil server`](/help/server) command as for HTTP service. Simply add the `--scgi` command-line option and the stand-alone server will speak the SCGI protocol rather than raw HTTP. This can be used with a web server such as [nginx](http://nginx.org) which does not support [Fossil’s CGI mode](./cgi.md). A basic nginx configuration to support SCGI with Fossil looks like this: location /code/ { include scgi_params; scgi_param SCRIPT_NAME "/code"; scgi_pass localhost:9000; } The `scgi_params` file comes with nginx, and it simply translates nginx internal variables to `scgi_param` directives to create SCGI environment variables for the proxied program; in this case, Fossil. Our explicit `scgi_param` call to define `SCRIPT_NAME` adds one more variable to this set, which is necessary for this configuration to work properly, because our repo isn’t at the root of the URL hierarchy. Without it, when Fossil generates absolute URLs, they’ll be missing the `/code` part at the start, which will typically cause [404 errors][404]. The final directive simply tells nginx to proxy all calls to URLs under `/code` down to an SCGI program on TCP port 9000. We can temporarily set Fossil up as a server on that port like so: $ fossil server /path/to/repo.fossil --scgi --localhost --port 9000 & The `--scgi` option switches Fossil into SCGI mode from its default, which is [stand-alone HTTP server mode](./none.md). All of the other options discussed in that linked document — such as the ability to serve a directory full of Fossil repositories rather than just a single repository — work the same way in SCGI mode. |
︙ | ︙ |
Changes to www/server/any/xinetd.md.
1 2 3 4 5 6 7 8 9 10 | # Serving via xinetd Some operating systems have replaced the old Unix `inetd` daemon with `xinetd`, which has a similar mission but with a very different configuration file format. The typical configuration file is either `/etc/xinetd.conf` or a subfile in the `/etc/xinetd.d` directory. You need a configuration something like this for Fossil: | | | | | | | | | | | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | # Serving via xinetd Some operating systems have replaced the old Unix `inetd` daemon with `xinetd`, which has a similar mission but with a very different configuration file format. The typical configuration file is either `/etc/xinetd.conf` or a subfile in the `/etc/xinetd.d` directory. You need a configuration something like this for Fossil: service http { port = 80 socket_type = stream wait = no user = root server = /usr/bin/fossil server_args = http /home/fossil/repos/ } This example configures Fossil to serve multiple repositories under the `/home/fossil/repos/` directory. Beyond this, see the general commentary in our article on [the `inetd` method](./inetd.md) as they also apply to service via `xinetd`. |
︙ | ︙ |
Changes to www/server/debian/nginx.md.
︙ | ︙ | |||
99 100 101 102 103 104 105 | ## <a id="deps"></a>Installing the Dependencies The first step is to install some non-default packages we’ll need. SSH into your server, then say: | | | 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 | ## <a id="deps"></a>Installing the Dependencies The first step is to install some non-default packages we’ll need. SSH into your server, then say: $ sudo apt install fossil nginx You can leave “`fossil`” out of that if you’re building Fossil from source to get a more up-to-date version than is shipped with the host OS. ## <a id="scgi"></a>Running Fossil in SCGI Mode |
︙ | ︙ | |||
129 130 131 132 133 134 135 | ## <a id="config"></a>Configuration On Debian and Ubuntu systems the primary user-level configuration file for nginx is `/etc/nginx/sites-enabled/default`. I recommend that this file contain only a list of include statements, one for each site that server hosts: | | | | 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 | ## <a id="config"></a>Configuration On Debian and Ubuntu systems the primary user-level configuration file for nginx is `/etc/nginx/sites-enabled/default`. I recommend that this file contain only a list of include statements, one for each site that server hosts: include local/example.com include local/foo.net Those files then each define one domain’s configuration. Here, `/etc/nginx/local/example.com` contains the configuration for `*.example.com` and its alias `*.example.net`; and `local/foo.net` contains the configuration for `*.foo.net`. The configuration for our `example.com` web site, stored in |
︙ | ︙ | |||
195 196 197 198 199 200 201 | As you can see, this is a pure extension of [the basic nginx service configuration for SCGI][scgii], showing off a few ideas you might want to try on your own site, such as static asset proxying. You also need a `local/code` file containing: | | | | | | | | | 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 | As you can see, this is a pure extension of [the basic nginx service configuration for SCGI][scgii], showing off a few ideas you might want to try on your own site, such as static asset proxying. You also need a `local/code` file containing: include scgi_params; scgi_pass 127.0.0.1:12345; scgi_param SCRIPT_NAME "/code"; We separate that out because nginx refuses to inherit certain settings between nested location blocks, so rather than repeat them, we extract them to this separate file and include it from both locations where it’s needed. You see this above where we set far-future expiration dates on files served by Fossil via URLs that contain hashes that change when the content changes. It tells your browser that the content of these URLs can never change without the URL itself changing, which makes your Fossil-based site considerably faster. Similarly, the `local/generic` file referenced above helps us reduce unnecessary repetition among the multiple sites this configuration hosts: root /var/www/$host; listen 80; listen [::]:80; charset utf-8; There are some configuration directives that nginx refuses to substitute variables into, citing performance considerations, so there is a limit to how much repetition you can squeeze out this way. One such example are the `access_log` and `error_log` directives, which follow an obvious pattern from one host to the next. Sadly, you must tolerate some repetition across `server { }` blocks when setting up multiple domains |
︙ | ︙ | |||
244 245 246 247 248 249 250 | encryption for Fossil](#tls), proxying HTTP instead of SCGI provides no benefit. However, it is still worth showing the proper method of proxying Fossil’s HTTP server through nginx if only to make reading nginx documentation on other sites easier: | | | | | | | | | | | | | | 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 | encryption for Fossil](#tls), proxying HTTP instead of SCGI provides no benefit. However, it is still worth showing the proper method of proxying Fossil’s HTTP server through nginx if only to make reading nginx documentation on other sites easier: location /code { rewrite ^/code(/.*) $1 break; proxy_pass http://127.0.0.1:12345; } The most common thing people get wrong when hand-rolling a configuration like this is to get the slashes wrong. Fossil is sensitive to this. For instance, Fossil will not collapse double slashes down to a single slash, as some other HTTP servers will. ## <a id="large-uv"></a> Allowing Large Unversioned Files By default, nginx only accepts HTTP messages [up to a meg](http://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size) in size. Fossil chunks its sync protocol such that this is not normally a problem, but when sending [unversioned content][uv], it uses a single message for the entire file. Therefore, if you will be storing files larger than this limit as unversioned content, you need to raise the limit. Within the `location` block: # Allow large unversioned file uploads, such as PDFs client_max_body_size 20M; [uv]: ../../unvers.wiki ## <a id="fail2ban"></a> Integrating `fail2ban` One of the nice things that falls out of proxying Fossil behind nginx is that it makes it easier to configure `fail2ban` to recognize attacks on Fossil and automatically block them. Fossil logs the sorts of errors we want to detect, but it does so in places like the repository’s admin log, a SQL table, which `fail2ban` doesn’t know how to query. By putting Fossil behind an nginx proxy, we convert these failures to log file form, which `fail2ban` is designed to handle. First, install `fail2ban`, if you haven’t already: sudo apt install fail2ban We’d like `fail2ban` to react to Fossil `/login` failures. The stock configuration of `fail2ban` only detects a few common sorts of SSH attacks by default, and its included (but disabled) nginx attack detectors don’t include one that knows how to detect an attack on Fossil. We have to teach it by putting the following into `/etc/fail2ban/filter.d/nginx-fossil-login.conf`: [Definition] failregex = ^<HOST> - .*POST .*/login HTTP/..." 401 That teaches `fail2ban` how to recognize the errors logged by Fossil [as of 2.14](/info/39d7eb0e22). (Earlier versions of Fossil returned HTTP status code 200 for this, so you couldn’t distinguish a successful login from a failure.) Then in `/etc/fail2ban/jail.local`, add this section: [nginx-fossil-login] enabled = true logpath = /var/log/nginx/*-https-access.log The last line is the key: it tells `fail2ban` where we’ve put all of our per-repo access logs in the nginx config above. There’s a [lot more you can do][dof2b], but that gets us out of scope of this guide. |
︙ | ︙ | |||
336 337 338 339 340 341 342 | has gotten smarter or our nginx configurations have gotten simpler, so we have removed the manual instructions we used to have here. You may wish to include something like this from each `server { }` block in your configuration to enable TLS in a common, secure way: ``` | | | | | | | | | | | | | | | | | | | | < < | 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 | has gotten smarter or our nginx configurations have gotten simpler, so we have removed the manual instructions we used to have here. You may wish to include something like this from each `server { }` block in your configuration to enable TLS in a common, secure way: ``` # Tell nginx to accept TLS-encrypted HTTPS on the standard TCP port. listen 443 ssl; listen [::]:443 ssl; # Reference the TLS cert files produced by Certbot. ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem; # Load the Let's Encrypt Diffie-Hellman parameters generated for # this server. Without this, the server is vulnerable to Logjam. ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # Tighten things down further, per Qualys’ and Certbot’s advice. ssl_session_cache shared:le_nginx_SSL:1m; ssl_protocols TLSv1.2 TLSv1.3; ssl_prefer_server_ciphers on; ssl_session_timeout 1440m; # Offer OCSP certificate stapling. ssl_stapling on; ssl_stapling_verify on; # Enable HSTS. include local/enable-hsts; ``` The [HSTS] step is optional and should be applied only after due consideration, since it has the potential to lock users out of your site if you later change your mind on the TLS configuration. The `local/enable-hsts` file it references is simply: add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always; It’s a separate file because nginx requires that headers like this be applied separately for each `location { }` block. We’ve therefore factored this out so you can `include` it everywhere you need it. The [OCSP] step is optional, but recommended. |
︙ | ︙ |
Changes to www/server/debian/service.md.
︙ | ︙ | |||
51 52 53 54 55 56 57 | create a listener socket on a high-numbered (≥ 1024) TCP port, suitable for sharing a Fossil repo to a workgroup on a private LAN. To do this, write the following in `~/.local/share/systemd/user/fossil.service`: ```dosini | | | | | | | | | | | | 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 | create a listener socket on a high-numbered (≥ 1024) TCP port, suitable for sharing a Fossil repo to a workgroup on a private LAN. To do this, write the following in `~/.local/share/systemd/user/fossil.service`: ```dosini [Unit] Description=Fossil user server After=network-online.target [Service] WorkingDirectory=/home/fossil/museum ExecStart=/home/fossil/bin/fossil server --port 9000 repo.fossil Restart=always RestartSec=3 [Install] WantedBy=multi-user.target ``` Unlike with `inetd` and `xinetd`, we don’t need to tell `systemd` which user and group to run this service as, because we’ve installed it under the account we’re logged into, which `systemd` will use as the service’s owner. |
︙ | ︙ | |||
88 89 90 91 92 93 94 | follows that it doesn’t need to run as a system service. A user service works perfectly well for this. Because we’ve set this up as a user service, the commands you give to manipulate the service vary somewhat from the sort you’re more likely to find online: | | | | | | | | 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 | follows that it doesn’t need to run as a system service. A user service works perfectly well for this. Because we’ve set this up as a user service, the commands you give to manipulate the service vary somewhat from the sort you’re more likely to find online: $ systemctl --user daemon-reload $ systemctl --user enable fossil $ systemctl --user start fossil $ systemctl --user status fossil -l $ systemctl --user stop fossil That is, we don’t need to talk to `systemd` with `sudo` privileges, but we do need to tell it to look at the user configuration rather than the system-level configuration. This scheme isolates the permissions needed by the Fossil server, which reduces the amount of damage it can do if there is ever a remotely-triggerable security flaw found in Fossil. On some `systemd` based OSes, user services only run while that user is logged in interactively. This is common on systems aiming to provide desktop environments, where this is the behavior you often want. To allow background services to continue to run after logout, say: $ sudo loginctl enable-linger $USER You can paste the command just like that into your terminal, since `$USER` will expand to your login name. [scgi]: ../any/scgi.md |
︙ | ︙ | |||
163 164 165 166 167 168 169 | roughly equivalent to [the ancient `inetd` method](../any/inetd.md). It’s more complicated, but it has some nice properties. We first need to define the privileged socket listener by writing `/etc/systemd/system/fossil.socket`: ```dosini | | | | | | | | | | | | | | | | | | | | | | | | | | 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 | roughly equivalent to [the ancient `inetd` method](../any/inetd.md). It’s more complicated, but it has some nice properties. We first need to define the privileged socket listener by writing `/etc/systemd/system/fossil.socket`: ```dosini [Unit] Description=Fossil socket [Socket] Accept=yes ListenStream=80 NoDelay=true [Install] WantedBy=sockets.target ``` Note the change of configuration directory from the `~/.local` directory to the system level. We need to start this socket listener at the root level because of the low-numbered TCP port restriction we brought up above. This configuration says more or less the same thing as the socket part of an `inted` entry [exemplified elsewhere in this documentation](../any/inetd.md). Next, create the service definition file in that same directory as `fossil@.service`: ```dosini [Unit] Description=Fossil socket server After=network-online.target [Service] WorkingDirectory=/home/fossil/museum ExecStart=/home/fossil/bin/fossil http repo.fossil StandardInput=socket [Install] WantedBy=multi-user.target ``` Notice that we haven’t told `systemd` which user and group to run Fossil under. Since this is a system-level service definition, that means it will run as root, which then causes Fossil to [automatically drop into a `chroot(2)` jail](../../chroot.md) rooted at the `WorkingDirectory` we’ve configured above, shortly after each `fossil http` call starts. The `Restart*` directives we had in the user service configuration above are unnecessary for this method, since Fossil isn’t supposed to remain running under it. Each HTTP hit starts one Fossil instance, which handles that single client’s request and then immediately shuts down. Next, you need to tell `systemd` to reload its system-level configuration files and enable the listening socket: $ sudo systemctl daemon-reload $ sudo systemctl enable fossil.socket And now you can manipulate the socket listener: $ sudo systemctl start fossil.socket $ sudo systemctl status -l fossil.socket $ sudo systemctl stop fossil.socket Notice that we’re working with the *socket*, not the *service*. The fact that we’ve given them the same base name and marked the service as an instantiated service with the “`@`” notation allows `systemd` to automatically start an instance of the service each time a hit comes in on the socket that `systemd` is monitoring on Fossil’s behalf. To see this service instantiation at work, visit a long-running Fossil page (e.g. `/tarball`) and then give a command like this: $ sudo systemctl --full | grep fossil This will show information about the `fossil` socket and service instances, which should show your `/tarball` hit handler, if it’s still running: fossil@20-127.0.0.1:80-127.0.0.1:38304.service You can feed that service instance description to a `systemctl kill` command to stop that single instance without restarting the whole `fossil` service, for example. In all of this, realize that we’re able to manipulate a single socket listener or single service instance at a time, rather than reload the |
︙ | ︙ |
Changes to www/server/index.html.
1 2 3 | <div class='fossil-doc' data-title="How To Configure A Fossil Server"> <style type="text/css"> | < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < | < | < | | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | <div class='fossil-doc' data-title="How To Configure A Fossil Server"> <style type="text/css"> .doc > .content th.fep { font-family: "Helvetica Neue", "Arial Narrow", "Myriad Pro", "Avenir Next Condensed"; font-stretch: condensed; min-width: 3em; padding: 0.4em; white-space: nowrap; } .doc > .content th.host { font-family: "Helvetica Neue", "Arial Narrow", "Myriad Pro", "Avenir Next Condensed"; font-stretch: condensed; padding: 0.4em; text-align: right; } .doc > .content td.doc { text-align: center; } </style> <h2>No Server Required</h2> |
︙ | ︙ | |||
198 199 200 201 202 203 204 | <h2 id="matrix">Activation Tutorials</h2> <p>We've broken the configuration for each method out into a series of sub-articles. Some of these are generic, while others depend on particular operating systems or front-end software:</p> | < | < | 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 | <h2 id="matrix">Activation Tutorials</h2> <p>We've broken the configuration for each method out into a series of sub-articles. Some of these are generic, while others depend on particular operating systems or front-end software:</p> <div class="indent"><table> <tr> <th class="host">⇩ OS / Method ⇨</th> <th class="fep">direct</th> <th class="fep">inetd</th> <th class="fep">stunnel</th> <th class="fep">CGI</th> <th class="fep">SCGI</th> |
︙ | ︙ | |||
278 279 280 281 282 283 284 | <td class="doc"><a href="windows/cgi.md">✅</a></td> <td class="doc">❌</td> <td class="doc">❌</td> <td class="doc">❌</td> <td class="doc"><a href="windows/iis.md">✅</a></td> <td class="doc"><a href="windows/service.md">✅</a></td> </tr> | | | 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 | <td class="doc"><a href="windows/cgi.md">✅</a></td> <td class="doc">❌</td> <td class="doc">❌</td> <td class="doc">❌</td> <td class="doc"><a href="windows/iis.md">✅</a></td> <td class="doc"><a href="windows/service.md">✅</a></td> </tr> </table></div> <p>Where there is a check mark in the "<b>Any</b>" row, the method for that is generic enough that it works across OSes that Fossil is known to work on. The check marks below that usually just link to this generic documentation.</p> <p>The method in the "<b>proxy</b>" column is for the platform's default |
︙ | ︙ |
Changes to www/server/macos/service.md.
︙ | ︙ | |||
16 17 18 19 20 21 22 | However, we will still give two different configurations, just as in the `systemd` article: one for a standalone HTTP server, and one using socket activation. For more information on `launchd`, the single best resource we’ve found is [launchd.info](https://launchd.info). The next best is: | | | | > | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | > | 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 | However, we will still give two different configurations, just as in the `systemd` article: one for a standalone HTTP server, and one using socket activation. For more information on `launchd`, the single best resource we’ve found is [launchd.info](https://launchd.info). The next best is: $ man launchd.plist [la]: http://www.grivet-tools.com/blog/2014/launchdaemons-vs-launchagents/ [ldhome]: https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html [wpa]: https://en.wikipedia.org/wiki/Launchd ## Standalone HTTP Server To configure `launchd` to start Fossil as a standalone HTTP server, write the following as `com.example.dev.FossilHTTP.plist`: ```xml <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>Label</key> <string>com.example.dev.FossilHTTP</string> <key>ProgramArguments</key> <array> <string>/usr/local/bin/fossil</string> <string>server</string> <string>--port</string> <string>9000</string> <string>repo.fossil</string> </array> <key>WorkingDirectory</key> <string>/Users/you/museum</string> <key>KeepAlive</key> <true/> <key>RunAtLoad</key> <true/> <key>StandardErrorPath</key> <string>/tmp/fossil-error.log</string> <key>StandardOutPath</key> <string>/tmp/fossil-info.log</string> <key>UserName</key> <string>you</string> <key>GroupName</key> <string>staff</string> <key>InitGroups</key> <true/> </dict> </plist> ``` In this example, we’re assuming your development organization uses the domain name “`dev.example.org`”, that your short macOS login name is “`you`”, and that you store your Fossils in “`~/museum`”. Adjust these elements of the plist file to suit your local situation. You might be wondering about the use of `UserName`: isn’t Fossil supposed to drop privileges and enter [a `chroot(2)` jail](../../chroot.md) when it’s started as root like this? Why do we need to give it a user name? Won’t Fossil use the owner of the repository file to set that? All I can tell you is that in testing here, if you leave the user and group configuration at the tail end of that plist file out, Fossil will remain running as root! Install that file and set it to start with: $ sudo install -o root -g wheel -m 644 com.example.dev.FossilHTTP.plist \ /Library/LaunchDaemons/ $ sudo launchctl load -w /Library/LaunchDaemons/com.example.dev.FossilHTTP.plist Because we set the `RunAtLoad` key, this will also launch the daemon. Stop the daemon with: $ sudo launchctl unload -w /Library/LaunchDaemons/com.example.dev.FossilHTTP.plist ## Socket Listener Another useful method to serve a Fossil repo via `launchd` is by setting up a socket listener: ```xml <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>Label</key> <string>com.example.dev.FossilSocket</string> <key>ProgramArguments</key> <array> <string>/usr/local/bin/fossil</string> |
︙ | ︙ |
Changes to www/server/openbsd/fastcgi.md.
︙ | ︙ | |||
16 17 18 19 20 21 22 | ## <a id="fslinstall"></a>Install Fossil Use the OpenBSD package manager `pkg_add` to install Fossil, making sure to select the statically linked binary. ```console | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 | ## <a id="fslinstall"></a>Install Fossil Use the OpenBSD package manager `pkg_add` to install Fossil, making sure to select the statically linked binary. ```console $ doas pkg_add fossil quirks-3.325 signed on 2020-06-12T06:24:53Z Ambiguous: choose package for fossil 0: <None> 1: fossil-2.10v0 2: fossil-2.10v0-static Your choice: 2 fossil-2.10v0-static: ok ``` This installs Fossil into the chroot. To facilitate local use, create a symbolic link of the fossil executable into `/usr/local/bin`. ```console $ doas ln -s /var/www/bin/fossil /usr/local/bin/fossil ``` As a privileged user, create the file `/var/www/cgi-bin/scm` with the following contents to make the CGI script that `httpd` will execute in response to `fsl.domain.tld` requests; all paths are relative to the `/var/www` chroot. ```sh #!/bin/fossil directory: /htdocs/fsl.domain.tld notfound: https://domain.tld repolist errorlog: /logs/fossil.log ``` The `directory` directive instructs Fossil to serve all repositories found in `/var/www/htdocs/fsl.domain.tld`, while `errorlog` sets logging to be saved to `/var/www/logs/fossil.log`; create the repository directory and log file—making the latter owned by the `www` user, and the script executable. ```console $ doas mkdir /var/www/htdocs/fsl.domain.tld $ doas touch /var/www/logs/fossil.log $ doas chown www /var/www/logs/fossil.log $ doas chmod 660 /var/www/logs/fossil.log $ doas chmod 755 /var/www/cgi-bin/scm ``` ## <a id="chroot"></a>Setup chroot Fossil needs both `/dev/random` and `/dev/null`, which aren't accessible from within the chroot, so need to be constructed; `/var`, however, is mounted with the `nodev` option. Rather than removing this default setting, create a small memory filesystem and then mount it on to `/var/www/dev` with [`mount_mfs(8)`][mfs] so that the `random` and `null` device files can be created. In order to avoid necessitating a startup script to recreate the device files at boot, create a template of the needed ``/dev`` tree to automatically populate the memory filesystem. ```console $ doas mkdir /var/www/dev $ doas install -d -g daemon /template/dev $ cd /template/dev $ doas /dev/MAKEDEV urandom $ doas mknod -m 666 null c 2 2 $ doas mount_mfs -s 1M -P /template/dev /dev/sd0b /var/www/dev $ ls -l total 0 crw-rw-rw- 1 root daemon 2, 2 Jun 20 08:56 null lrwxr-xr-x 1 root daemon 7 Jun 18 06:30 random@ -> urandom crw-r--r-- 1 root wheel 45, 0 Jun 18 06:30 urandom ``` [mfs]: https://man.openbsd.org/mount_mfs.8 To make the mountable memory filesystem permanent, open `/etc/fstab` as a privileged user and add the following line to automate creation of the filesystem at startup: ```console swap /var/www/dev mfs rw,-s=1048576,-P=/template/dev 0 0 ``` The same user that executes the fossil binary must have writable access to the repository directory that resides within the chroot; on OpenBSD this is `www`. In addition, grant repository directory ownership to the user who will push to, pull from, and create repositories. ```console $ doas chown -R user:www /var/www/htdocs/fsl.domain.tld $ doas chmod 770 /var/www/htdocs/fsl.domain.tld ``` ## <a id="httpdconfig"></a>Configure httpd On OpenBSD, [httpd.conf(5)][httpd] is the configuration file for `httpd`. To setup the server to serve all Fossil repositores within the directory specified in the CGI script, and automatically redirect standard HTTP requests to HTTPS—apart from [Let's Encrypt][LE] challenges issued in response to [acme-client(1)][acme] certificate requests—create `/etc/httpd.conf` as a privileged user with the following contents. [LE]: https://letsencrypt.org [acme]: https://man.openbsd.org/acme-client.1 [httpd.conf(5)]: https://man.openbsd.org/httpd.conf.5 ```apache server "fsl.domain.tld" { listen on * port http root "/htdocs/fsl.domain.tld" location "/.well-known/acme-challenge/*" { root "/acme" request strip 2 } location * { block return 301 "https://$HTTP_HOST$REQUEST_URI" } location "/*" { fastcgi { param SCRIPT_FILENAME "/cgi-bin/scm" } } } server "fsl.domain.tld" { listen on * tls port https root "/htdocs/fsl.domain.tld" tls { certificate "/etc/ssl/domain.tld.fullchain.pem" key "/etc/ssl/private/domain.tld.key" } hsts { max-age 15768000 preload subdomains } connection max request body 104857600 location "/*" { fastcgi { param SCRIPT_FILENAME "/cgi-bin/scm" } } location "/.well-known/acme-challenge/*" { root "/acme" request strip 2 } } ``` [The default limit][dlim] for HTTP messages in OpenBSD’s `httpd` server is 1 MiB. Fossil chunks its sync protocol such that this is not normally a problem, but when sending [unversioned content][uv], it uses a single message for the entire file. Therefore, if you will be storing files larger than this limit as unversioned content, you need to raise |
︙ | ︙ | |||
185 186 187 188 189 190 191 | In order for `httpd` to serve HTTPS, secure a free certificate from Let's Encrypt using `acme-client`. Before issuing the request, however, ensure you have a zone record for the subdomain with your registrar or nameserver. Then open `/etc/acme-client.conf` as a privileged user to configure the request. ```dosini | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 | In order for `httpd` to serve HTTPS, secure a free certificate from Let's Encrypt using `acme-client`. Before issuing the request, however, ensure you have a zone record for the subdomain with your registrar or nameserver. Then open `/etc/acme-client.conf` as a privileged user to configure the request. ```dosini authority letsencrypt { api url "https://acme-v02.api.letsencrypt.org/directory" account key "/etc/acme/letsencrypt-privkey.pem" } authority letsencrypt-staging { api url "https://acme-staging.api.letsencrypt.org/directory" account key "/etc/acme/letsencrypt-staging-privkey.pem" } domain domain.tld { alternative names { www.domain.tld fsl.domain.tld } domain key "/etc/ssl/private/domain.tld.key" domain certificate "/etc/ssl/domain.tld.crt" domain full chain certificate "/etc/ssl/domain.tld.fullchain.pem" sign with letsencrypt } ``` Start `httpd` with the new configuration file, and issue the certificate request. ```console $ doas rcctl start httpd $ doas acme-client -vv domain.tld acme-client: /etc/acme/letsencrypt-privkey.pem: account key exists (not creating) acme-client: /etc/acme/letsencrypt-privkey.pem: loaded RSA account key acme-client: /etc/ssl/private/domain.tld.key: generated RSA domain key acme-client: https://acme-v01.api.letsencrypt.org/directory: directories acme-client: acme-v01.api.letsencrypt.org: DNS: 172.65.32.248 ... N(Q????Z???j?j?>W#????b???? H????eb??T??*? DNosz(???n{L}???D???4[?B] (1174 bytes) acme-client: /etc/ssl/domain.tld.crt: created acme-client: /etc/ssl/domain.tld.fullchain.pem: created ``` A successful result will output the public certificate, full chain of trust, and private key into the `/etc/ssl` directory as specified in `acme-client.conf`. ```console $ doas ls -lR /etc/ssl -r--r--r-- 1 root wheel 2.3K Mar 2 01:31:03 2018 domain.tld.crt -r--r--r-- 1 root wheel 3.9K Mar 2 01:31:03 2018 domain.tld.fullchain.pem /etc/ssl/private: -r-------- 1 root wheel 3.2K Mar 2 01:31:03 2018 domain.tld.key ``` Make sure to reopen `/etc/httpd.conf` to uncomment the second server block responsible for serving HTTPS requests before proceeding. ## <a id="starthttpd"></a>Start `httpd` With `httpd` configured to serve Fossil repositories out of `/var/www/htdocs/fsl.domain.tld`, and the certificates and key in place, enable and start `slowcgi`—OpenBSD's FastCGI wrapper server that will execute the above Fossil CGI script—before checking that the syntax of the `httpd.conf` configuration file is correct, and (re)starting the server (if still running from requesting a Let's Encrypt certificate). ```console $ doas rcctl enable slowcgi $ doas rcctl start slowcgi slowcgi(ok) $ doas httpd -vnf /etc/httpd.conf configuration OK $ doas rcctl start httpd httpd(ok) ``` ## <a id="clientconfig"></a>Configure Client To facilitate creating new repositories and pushing them to the server, add the following function to your `~/.cshrc` or `~/.zprofile` or the config file for whichever shell you are using on your development box. ```sh finit() { fossil init $1.fossil && \ chmod 664 $1.fossil && \ fossil open $1.fossil && \ fossil user password $USER $PASSWD && \ fossil remote-url https://$USER:$PASSWD@fsl.domain.tld/$1 && \ rsync --perms $1.fossil $USER@fsl.domain.tld:/var/www/htdocs/fsl.domain.tld/ >/dev/null && \ chmod 644 $1.fossil && \ fossil ui } ``` This enables a new repository to be made with `finit repo`, which will create the fossil repository file `repo.fossil` in the current working directory; by default, the repository user is set to the environment variable `$USER`. It then opens the repository and sets the user password to the `$PASSWD` environment variable (which you can either set |
︙ | ︙ |
Changes to www/server/openbsd/service.wiki.
1 2 3 4 5 6 7 8 | <title>Serving via rc on OpenBSD</title> OpenBSD provides [https://man.openbsd.org/rc.subr.8|rc.subr(8)], a framework for writing [https://man.openbsd.org/rc.8|rc(8)] scripts. <h2>Creating the daemon</h2> Create the file /etc/rc.d/fossil with contents like the following. | > | | > | | | | | | | | > | | > > | | > | | | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 | <title>Serving via rc on OpenBSD</title> OpenBSD provides [https://man.openbsd.org/rc.subr.8|rc.subr(8)], a framework for writing [https://man.openbsd.org/rc.8|rc(8)] scripts. <h2>Creating the daemon</h2> Create the file /etc/rc.d/fossil with contents like the following. <pre> #!/bin/ksh daemon="/usr/local/bin/fossil" # fossil executable daemon_user="_fossil" # user to run fossil as daemon_flags="server /home/_fossil/example --repolist --port 8888" # fossil command . /etc/rc.d/rc.subr # pexp="$daemon server .*" # See below. rc_reload=NO # Unsupported by Fossil; 'rcctl reload fossil' kills the process. rc_bg=YES # Run in the background, since fossil serve does not daemonize itself rc_cmd $1 </pre> <h3>pexp</h3> You may need to uncomment the "pexp=". rc.subr typically finds the daemon process based by matching the process name and argument list. Without the "pexp=" line, rc.subr would look for this exact command: <pre> /usr/local/bin/fossil server /home/_fossil/example --repolist --port 8888 </pre> Depending on the arguments and their order, fossil may rewrite the arguments for display in the process listing ([https://man.openbsd.org/ps.1|ps(1)]), so rc.subr may fail to find the process through the default match. The example above does not get rewritten, but the same commands in a different order can be rewritten. For example, when I switch the order of the arguments in "daemon_flags", <pre> /usr/local/bin/fossil server --repolist --port 8888 /home/_fossil/example </pre> the process command is changed to this. <pre> /usr/local/bin/fossil server /home/_fossil/example /home/_fossil/example 8888 /home/_fossil/example </pre> The commented "pexp=" line instructs rc.subr to choose the process whose command and arguments text starts with this: <pre> /usr/local/bin/fossil server </pre> <h2>Enabling the daemon</h2> Once you have created /etc/rc.d/fossil, run these commands. <pre> rcctl enable fossil # add fossil to pkg_scripts in /etc/rc.conf.local rcctl start fossil # start the daemon now </pre> The daemon should now be running and set to start at boot. <h2>Multiple daemons</h2> You may want to serve multiple fossil instances with different options. For example, * If different users own different repositories, you may want different users to serve different repositories. * You may want to serve different repositories on different ports so you can control them differently with, for example, HTTP reverse proxies or [https://man.openbsd.org/pf.4|pf(4)]. To run multiple fossil daemons, create multiple files in /etc/rc.d, and enable each of them. Here are two approaches for creating the files in /etc/rc.d: Symbolic links and copies. <h3>Symbolic links</h3> Suppose you want to run one fossil daemon as user "user1" on port 8881 and another as user "user2" on port 8882. Create the files with [https://man.openbsd.org/ln.1|ln(1)], and configure them to run different fossil commands. <pre> cd /etc/rc.d ln -s fossil fossil1 ln -s fossil fossil2 rcctl enable fossil1 fossil2 rcctl set fossil1 user user1 rcctl set fossil2 user user2 rcctl set fossil1 flags 'server /home/user1/repo1.fossil --port 8881' rcctl set fossil2 flags 'server /home/user2/repo2.fossil --port 8882' rcctl start fossil1 fossil2 </pre> <h3>Copies</h3> You may want to run fossil daemons that are too different to configure just with [https://man.openbsd.org/rcctl.8|rcctl(8)]. In particular, you can't change the "pexp" with rcctl. If you want to run fossil commands that are more different, you may prefer to create separate files in /etc/rc.d. Replace "ln -s" above with "cp" to accomplish this. <pre> cp /etc/rc.d/fossil /etc/rc.d/fossil-user1 cp /etc/rc.d/fossil /etc/rc.d/fossil-user2 </pre> You can still use commands like "rcctl set fossil-user1 flags", but you can also edit the "/etc/rc.d/fossil-user1" file. |
Changes to www/server/windows/iis.md.
︙ | ︙ | |||
30 31 32 33 34 35 36 | ## Background Fossil Service Setup You will need to have the Fossil HTTP server running in the background, serving some local repository, bound to localhost on a fixed high-numbered TCP port. For the purposes of testing, simply start it by hand in your command shell of choice: | | | 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 | ## Background Fossil Service Setup You will need to have the Fossil HTTP server running in the background, serving some local repository, bound to localhost on a fixed high-numbered TCP port. For the purposes of testing, simply start it by hand in your command shell of choice: fossil serve --port 9000 --localhost repo.fossil That command assumes you’ve got `fossil.exe` in your `%PATH%` and you’re in a directory holding `repo.fossil`. See [the platform-independent instructions](../any/none.md) for further details. For a more robust setup, we recommend that you [install Fossil as a Windows service](./service.md), which will allow Fossil to start at |
︙ | ︙ |
Changes to www/serverext.wiki.
︙ | ︙ | |||
29 30 31 32 33 34 35 | An administrator activates the CGI extension mechanism by specifying an "Extension Root Directory" or "extroot" as part of the [./server/index.html|server setup]. If the Fossil server is itself run as [./server/any/cgi.md|CGI], then add a line to the [./cgi.wiki#extroot|CGI script file] that says: | | | | | | | | 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 | An administrator activates the CGI extension mechanism by specifying an "Extension Root Directory" or "extroot" as part of the [./server/index.html|server setup]. If the Fossil server is itself run as [./server/any/cgi.md|CGI], then add a line to the [./cgi.wiki#extroot|CGI script file] that says: <pre> extroot: <i>DIRECTORY</i> </pre> Or, if the Fossil server is being run using the "[./server/any/none.md|fossil server]" or "[./server/any/none.md|fossil ui]" or "[./server/any/inetd.md|fossil http]" commands, then add an extra "--extroot <i>DIRECTORY</i>" option to that command. The <i>DIRECTORY</i> is the DOCUMENT_ROOT for the CGI. Files in the DOCUMENT_ROOT are accessed via URLs like this: <pre> https://example-project.org/ext/<i>FILENAME</i> </pre> In other words, access files in DOCUMENT_ROOT by appending the filename relative to DOCUMENT_ROOT to the [/help?cmd=/ext|/ext] page of the Fossil server. Files that are readable but not executable are returned as static content. Files that are executable are run as CGI. <h3>2.1 Example #1</h3> The source code repository for SQLite is a Fossil server that is run as CGI. The URL for the source code repository is [https://sqlite.org/src]. The CGI script looks like this: <verbatim> #!/usr/bin/fossil repository: /fossil/sqlite.fossil errorlog: /logs/errors.txt extroot: /sqlite-src-ext </verbatim> The "extroot: /sqlite-src-ext" line tells Fossil that it should look for extension CGIs in the /sqlite-src-ext directory. (All of this is happening inside of a chroot jail, so putting the document root in a top-level directory is a reasonable thing to do.) When a URL like "https://sqlite.org/src/ext/checklist" is received by the |
︙ | ︙ | |||
99 100 101 102 103 104 105 | main web server which in turn relays the result back to the original client. <h3>2.2 Example #2</h3> The [https://fossil-scm.org/home|Fossil self-hosting repository] is also a CGI that looks like this: | | | | 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 | main web server which in turn relays the result back to the original client. <h3>2.2 Example #2</h3> The [https://fossil-scm.org/home|Fossil self-hosting repository] is also a CGI that looks like this: <verbatim> #!/usr/bin/fossil repository: /fossil/fossil.fossil errorlog: /logs/errors.txt extroot: /fossil-extroot </verbatim> The extroot for this Fossil server is /fossil-extroot and in that directory is an executable file named "fileup1" - another [https://wapp.tcl.tk|Wapp] script. (The extension mechanism is not required to use Wapp. You can use any kind of program you like. But the creator of SQLite and Fossil is fond of [https://www.tcl.tk|Tcl/Tk] and so he tends to gravitate toward Tcl-based technologies like Wapp.) The fileup1 script is a demo program that lets |
︙ | ︙ | |||
199 200 201 202 203 204 205 | header and footer, then the inserted header will include a Content Security Policy (CSP) restriction on the use of javascript within the webpage. Any <script>...</script> elements within the CGI output must include a nonce or else they will be suppressed by the web browser. The FOSSIL_NONCE variable contains the value of that nonce. So, in other words, to get javascript to work, it must be enclosed in: | | | | | | | | 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 | header and footer, then the inserted header will include a Content Security Policy (CSP) restriction on the use of javascript within the webpage. Any <script>...</script> elements within the CGI output must include a nonce or else they will be suppressed by the web browser. The FOSSIL_NONCE variable contains the value of that nonce. So, in other words, to get javascript to work, it must be enclosed in: <verbatim> <script nonce='$FOSSIL_NONCE'>...</script> </verbatim> Except, of course, the $FOSSIL_NONCE is replaced by the value of the FOSSIL_NONCE environment variable. <h3>3.1 Input Content</h3> If the HTTP request includes content (for example if this is a POST request) then the CONTENT_LENGTH value will be positive and the data for the content will be readable on standard input. <h2>4.0 CGI Outputs</h2> CGI programs construct a reply by writing to standard output. The first few lines of output are parameters intended for the web server that invoked the CGI. These are followed by a blank line and then the content. Typical parameter output looks like this: <verbatim> Status: 200 OK Content-Type: text/html </verbatim> CGI programs can return any content type they want - they are not restricted to text replies. It is OK for a CGI program to return (for example) image/png. The fields of the CGI response header can be any valid HTTP header fields. Those that Fossil does not understand are simply relayed back to up the line to the requester. Fossil takes special action with some content types. If the Content-Type is "text/x-fossil-wiki" or "text/x-markdown" then Fossil converts the content from [/wiki_rules|Fossil-Wiki] or [/md_rules|Markdown] into HTML, adding its own header and footer text according to the repository skin. Content of type "text/html" is normally passed straight through unchanged. However, if the text/html content is of the form: <verbatim> <div class='fossil-doc' data-title='DOCUMENT TITLE'> ... HTML content there ... </div> </verbatim> In other words, if the outer-most markup of the HTML is a <div> element with a single class of "fossil-doc", then Fossil will adds its own header and footer to the HTML. The page title contained in the added header will be extracted from the "data-title" attribute. |
︙ | ︙ |
Changes to www/stats.wiki.
1 | <title>Fossil Performance</title> | < | | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 | <title>Fossil Performance</title> The questions will inevitably arise: How does Fossil perform? Does it use a lot of disk space or bandwidth? Is it scalable? In an attempt to answers these questions, this report looks at several projects that use fossil for configuration management and examines how well they are working. The following table is a summary of the results. (Last updated on 2018-06-04.) Explanation and analysis follows the table. <table> <tr> <th>Project</th> <th>Number Of Artifacts</th> <th>Number Of Check-ins</th> <th>Project Duration<br>(as of 2018-06-04)</th> <th>Uncompressed Size</th> <th>Repository Size</th> |
︙ | ︙ |
Changes to www/sync.wiki.
︙ | ︙ | |||
128 129 130 131 132 133 134 | typing in the common case where the client does multiple syncs to the same server.) The client modifies the URL by appending the method name "<b>/xfer</b>" to the end. For example, if the URL specified on the client command line is | < | < < | < | > | < | > | < | 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 | typing in the common case where the client does multiple syncs to the same server.) The client modifies the URL by appending the method name "<b>/xfer</b>" to the end. For example, if the URL specified on the client command line is <pre>https://fossil-scm.org/fossil</pre> Then the URL that is really used to do the synchronization will be: <pre>https://fossil-scm.org/fossil/xfer</pre> <h3>2.2 HTTP Request Format</h3> The client always sends a POST request to the server. The general format of the POST request is as follows: <pre> POST /fossil/xfer HTTP/1.0 Host: fossil-scm.hwaci.com:80 Content-Type: application/x-fossil Content-Length: 4216 </pre> <i><pre>content...</pre></i> In the example above, the pathname given after the POST keyword on the first line is a copy of the URL pathname. The Host: parameter is also taken from the URL. The content type is always either "application/x-fossil" or "application/x-fossil-debug". The "x-fossil" content type is the default. The only difference is that "x-fossil" content is compressed using zlib whereas "x-fossil-debug" is sent uncompressed. A typical reply from the server might look something like this: <pre> HTTP/1.0 200 OK Date: Mon, 10 Sep 2007 12:21:01 GMT Connection: close Cache-control: private Content-Type: application/x-fossil; charset=US-ASCII Content-Length: 265 </pre> <i><pre>content...</pre></i> The content type of the reply is always the same as the content type of the request. <h2>3.0 Fossil Synchronization Content</h2> A synchronization request between a client and server consists of |
︙ | ︙ | |||
200 201 202 203 204 205 206 | are very similar. <h3>3.2 Login Cards</h3> Every message from client to server begins with one or more login cards. Each login card has the following format: | < | < | 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 | are very similar. <h3>3.2 Login Cards</h3> Every message from client to server begins with one or more login cards. Each login card has the following format: <pre><b>login</b> <i>userid nonce signature</i></pre> The userid is the name of the user that is requesting service from the server. The nonce is the SHA1 hash of the remainder of the message - all text that follows the newline character that terminates the login card. The signature is the SHA1 hash of the concatenation of the nonce and the users password. |
︙ | ︙ | |||
239 240 241 242 243 244 245 | For sync protocols, artifacts are transferred using "file" cards. File cards come in two different formats depending on whether the artifact is sent directly or as a [./delta_format.wiki|delta] from some other artifact. | | | | | 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 | For sync protocols, artifacts are transferred using "file" cards. File cards come in two different formats depending on whether the artifact is sent directly or as a [./delta_format.wiki|delta] from some other artifact. <pre> <b>file</b> <i>artifact-id size</i> <b>\n</b> <i>content</i> <b>file</b> <i>artifact-id delta-artifact-id size</i> <b>\n</b> <i>content</i> </pre> File cards are followed by in-line "payload" data. The content of the artifact or the artifact delta is the first <i>size</i> bytes of the x-fossil content that immediately follow the newline that terminates the file card. |
︙ | ︙ | |||
280 281 282 283 284 285 286 | Compressed File cards are similar to File cards, sharing the same in-line "payload" data characteristics and also the same treatment of direct content or delta content. Cfile cards come in two different formats depending on whether the artifact is sent directly or as a delta from some other artifact. | | | | | | 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 | Compressed File cards are similar to File cards, sharing the same in-line "payload" data characteristics and also the same treatment of direct content or delta content. Cfile cards come in two different formats depending on whether the artifact is sent directly or as a delta from some other artifact. <pre> <b>cfile</b> <i>artifact-id usize csize</i> <b>\n</b> <i>content</i> <b>cfile</b> <i>artifact-id delta-artifact-id usize csize</i> <b>\n</b> <i>content</i> </pre> The first argument of the cfile card is the ID of the artifact that is being transferred. The artifact ID is the lower-case hexadecimal representation of the name hash for the artifact. The second argument of the cfile card is the original size in bytes of the artifact. The last argument of the cfile card is the number of compressed bytes of payload that immediately follow the cfile card. If the cfile card has only |
︙ | ︙ | |||
309 310 311 312 313 314 315 | "Private" content consist of artifacts that are not normally synced. However, private content will be synced when the the [/help?cmd=sync|fossil sync] command includes the "--private" option. Private content is marked by a "private" card: | < | < < | < | 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 | "Private" content consist of artifacts that are not normally synced. However, private content will be synced when the the [/help?cmd=sync|fossil sync] command includes the "--private" option. Private content is marked by a "private" card: <pre><b>private</b></pre> The private card has no arguments and must directly precede a file card that contains the private content. <h4>3.3.4 Unversioned File Cards</h4> Unversioned content is sent in both directions (client to server and server to client) using "uvfile" cards in the following format: <pre><b>uvfile</b> <i>name mtime hash size flags</i> <b>\n</b> <i>content</i></pre> The <i>name</i> field is the name of the unversioned file. The <i>mtime</i> is the last modification time of the file in seconds since 1970. The <i>hash</i> field is the hash of the content for the unversioned file, or "<b>-</b>" for deleted content. The <i>size</i> field is the (uncompressed) size of the content in bytes. The <i>flags</i> field is an integer which is interpreted |
︙ | ︙ | |||
358 359 360 361 362 363 364 | Among the first cards in a client-to-server message are the push and pull cards. The push card tells the server that the client is pushing content. The pull card tells the server that the client wants to pull content. In the event of a sync, both cards are sent. The format is as follows: | | | | | 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 | Among the first cards in a client-to-server message are the push and pull cards. The push card tells the server that the client is pushing content. The pull card tells the server that the client wants to pull content. In the event of a sync, both cards are sent. The format is as follows: <pre> <b>push</b> <i>servercode projectcode</i> <b>pull</b> <i>servercode projectcode</i> </pre> The <i>servercode</i> argument is the repository ID for the client. The <i>projectcode</i> is the identifier of the software project that the client repository contains. The projectcode for the client and server must match in order for the transaction to proceed. |
︙ | ︙ | |||
383 384 385 386 387 388 389 | A clone card works like a pull card in that it is sent from client to server in order to tell the server that the client wants to pull content. The clone card comes in two formats. Older clients use the no-argument format and newer clients use the two-argument format. | | | | | | | 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 | A clone card works like a pull card in that it is sent from client to server in order to tell the server that the client wants to pull content. The clone card comes in two formats. Older clients use the no-argument format and newer clients use the two-argument format. <pre> <b>clone</b> <b>clone</b> <i>protocol-version sequence-number</i> </pre> <h4>3.5.1 Protocol 3</h4> The latest clients send a two-argument clone message with a protocol version of "3". (Future versions of Fossil might use larger protocol version numbers.) Version "3" of the protocol enhanced version "2" by introducing the "cfile" card which is intended to speed up clone operations. Instead of sending "file" cards, the server will send "cfile" cards <h4>3.5.2 Protocol 2</h4> The sequence-number sent is the number of artifacts received so far. For the first clone message, the sequence number is 0. The server will respond by sending file cards for some number of artifacts up to the maximum message size. The server will also send a single "clone_seqno" card to the client so that the client can know where the server left off. <pre> <b>clone_seqno</b> <i>sequence-number</i> </pre> The clone message in subsequent HTTP requests for the same clone operation will use the sequence-number from the clone_seqno of the previous reply. In response to an initial clone message, the server also sends the client a push message so that the client can discover the projectcode for |
︙ | ︙ | |||
438 439 440 441 442 443 444 | <h3>3.6 Igot Cards</h3> An igot card can be sent from either client to server or from server to client in order to indicate that the sender holds a copy of a particular artifact. The format is: | | | | | | 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 | <h3>3.6 Igot Cards</h3> An igot card can be sent from either client to server or from server to client in order to indicate that the sender holds a copy of a particular artifact. The format is: <pre> <b>igot</b> <i>artifact-id</i> ?<i>flag</i>? </pre> The first argument of the igot card is the ID of the artifact that the sender possesses. The receiver of an igot card will typically check to see if it also holds the same artifact and if not it will request the artifact using a gimme card in either the reply or in the next message. If the second argument exists and is "1", then the artifact identified by the first argument is private on the sender and should be ignored unless a "--private" [/help?cmd=sync|sync] is occurring. The name "igot" comes from the English slang expression "I got" meaning "I have". <h4>3.6.1 Unversioned Igot Cards</h4> Zero or more "uvigot" cards are sent from server to client when synchronizing unversioned content. The format of a uvigot card is as follows: <pre> <b>uvigot</b> <i>name mtime hash size</i> </pre> The <i>name</i> argument is the name of an unversioned file. The <i>mtime</i> is the last modification time of the unversioned file in seconds since 1970. The <i>hash</i> is the SHA1 or SHA3-256 hash of the unversioned file content, or "<b>-</b>" if the file has been deleted. The <i>size</i> is the uncompressed size of the file in bytes. |
︙ | ︙ | |||
493 494 495 496 497 498 499 | <h3>3.7 Gimme Cards</h3> A gimme card is sent from either client to server or from server to client. The gimme card asks the receiver to send a particular artifact back to the sender. The format of a gimme card is this: | | | | | | | | 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 | <h3>3.7 Gimme Cards</h3> A gimme card is sent from either client to server or from server to client. The gimme card asks the receiver to send a particular artifact back to the sender. The format of a gimme card is this: <pre> <b>gimme</b> <i>artifact-id</i> </pre> The argument to the gimme card is the ID of the artifact that the sender wants. The receiver will typically respond to a gimme card by sending a file card in its reply or in the next message. The "gimme" name means "give me". The imperative "give me" is pronounced as if it were a single word "gimme" in some dialects of English (including the dialect spoken by the original author of Fossil). <h4>3.7.1 Unversioned Gimme Cards</h4> Sync synchronizing unversioned content, the client may send "uvgimme" cards to the server. A uvgimme card requests that the server send unversioned content to the client. The format of a uvgimme card is as follows: <pre> <b>uvgimme</b> <i>name</i> </pre> The <i>name</i> is the name of the unversioned file found on the server that the client would like to have. When a server sees a uvgimme card, it normally responses with a uvfile card, though it might also send another uvigot card if the HTTP reply is already oversized. <h3>3.8 Cookie Cards</h3> A cookie card can be used by a server to record a small amount of state information on a client. The server sends a cookie to the client. The client sends the same cookie back to the server on its next request. The cookie card has a single argument which is its payload. <pre> <b>cookie</b> <i>payload</i> </pre> The client is not required to return the cookie to the server on its next request. Or the client might send a cookie from a different server on the next request. So the server must not depend on the cookie and the server must structure the cookie payload in such a way that it can tell if the cookie it sees is its own cookie or a cookie from another server. (Typically the server will embed |
︙ | ︙ | |||
556 557 558 559 560 561 562 | of the project, the default Cascading Style Sheet (CSS) for the web-interface, and the project logo displayed on the web-interface are all configuration data elements. The reqconfig card is normally sent in response to the "fossil configuration pull" command. The format is as follows: | | | | 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 | of the project, the default Cascading Style Sheet (CSS) for the web-interface, and the project logo displayed on the web-interface are all configuration data elements. The reqconfig card is normally sent in response to the "fossil configuration pull" command. The format is as follows: <pre> <b>reqconfig</b> <i>configuration-name</i> </pre> As of 2018-06-04, the configuration-name must be one of the following values: <table border=0 align="center"> <tr><td valign="top"> <ul> |
︙ | ︙ | |||
601 602 603 604 605 606 607 | <li> ignore-glob <li> keep-glob <li> crlf-glob <ul></td><td valign="top"><ul> <li> crnl-glob <li> encoding-glob <li> empty-dirs | | | 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 | <li> ignore-glob <li> keep-glob <li> crlf-glob <ul></td><td valign="top"><ul> <li> crnl-glob <li> encoding-glob <li> empty-dirs <li> <s title="removed 2020-08, version 2.12.1">allow-symlinks</s> <li> dotfiles <li> parent-project-code <li> parent-projet-name <li> hash-policy <li> mv-rm-files <li> ticket-table <li> ticket-common |
︙ | ︙ | |||
658 659 660 661 662 663 664 | <h3>3.10 Configuration Cards</h3> A "config" card is used to send configuration information from client to server (in response to a "fossil configuration push" command) or from server to client (in response to a "fossil configuration pull" or "fossil clone" command). The format is as follows: | | | | | | 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 | <h3>3.10 Configuration Cards</h3> A "config" card is used to send configuration information from client to server (in response to a "fossil configuration push" command) or from server to client (in response to a "fossil configuration pull" or "fossil clone" command). The format is as follows: <pre> <b>config</b> <i>configuration-name size</i> <b>\n</b> <i>content</i> </pre> The server will only accept a config card if the user has "Admin" privilege. A client will only accept a config card if it had sent a corresponding reqconfig card in its request. The content of the configuration item is used to overwrite the corresponding configuration data in the receiver. <h3>3.11 Pragma Cards</h3> The client may try to influence the behavior of the server by issuing a pragma card: <pre> <b>pragma</i> <i>name value...</i> </pre> The "pragma" card has at least one argument which is the pragma name. The pragma name defines what the pragma does. A pragma might have zero or more "value" arguments depending on the pragma name. New pragma names may be added to the protocol from time to time |
︙ | ︙ | |||
773 774 775 776 777 778 779 | <h3>3.13 Message and Error Cards</h3> If the server discovers anything wrong with a request, it generates an error card in its reply. When the client sees the error card, it displays an error message to the user and aborts the sync operation. An error card looks like this: | | | | | | 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 | <h3>3.13 Message and Error Cards</h3> If the server discovers anything wrong with a request, it generates an error card in its reply. When the client sees the error card, it displays an error message to the user and aborts the sync operation. An error card looks like this: <pre> <b>error</b> <i>error-message</i> </pre> The error message is English text that is encoded in order to be a single token. A space (ASCII 0x20) is represented as "\s" (ASCII 0x5C, 0x73). A newline (ASCII 0x0a) is "\n" (ASCII 0x6C, x6E). A backslash (ASCII 0x5C) is represented as two backslashes "\\". Apart from space and newline, no other whitespace characters nor any unprintable characters are allowed in the error message. The server can also send a message card that also prints a message on the client console, but which is not an error: <pre> <b>message</b> <i>message-text</i> </pre> The message-text uses the same format as an error message. <h3>3.14 Unknown Cards</h3> If either the client or the server sees a card that is not described above, then it generates an error and aborts. |
︙ | ︙ |
Changes to www/tech_overview.wiki.
︙ | ︙ | |||
63 64 65 66 67 68 69 | database. Whenever multiple databases are used at the same time, they are all opened on the same SQLite database connection using SQLite's [http://www.sqlite.org/lang_attach.html | ATTACH] command. The chart below provides a quick summary of how each of these database files are used by Fossil, with detailed discussion following. | | < | | | > > > | | < < < | | < < < | | < | 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 | database. Whenever multiple databases are used at the same time, they are all opened on the same SQLite database connection using SQLite's [http://www.sqlite.org/lang_attach.html | ATTACH] command. The chart below provides a quick summary of how each of these database files are used by Fossil, with detailed discussion following. <table align="center"> <tr valign="bottom"> <th style="text-align:center">Configuration Database<br>"~/.fossil" or<br> "~/.config/fossil.db" <th style="text-align:center">Repository Database<br>"<i>project</i>.fossil" <th style="text-align:center">Checkout Database<br>"_FOSSIL_" or ".fslckout" <tr valign="top"> <td><ul> <li>Global [/help/settings |settings] <li>List of active repositories used by the [/help/all | all] command </ul></td> <td><ul> <li>[./fileformat.wiki | Global state of the project] encoded using delta-compression <li>Local [/help/settings|settings] <li>Web interface display preferences <li>User credentials and permissions <li>Metadata about the global state to facilitate rapid queries </ul></td> <td><ul> <li>The repository database used by this checkout <li>The version currently checked out <li>Other versions [/help/merge | merged] in but not yet [/help/commit | committed] <li>Changes from the [/help/add | add], [/help/delete | delete], and [/help/rename | rename] commands that have not yet been committed <li>"mtime" values and other information used to efficiently detect local edits <li>The "[/help/stash | stash]" <li>Information needed to "[/help/undo|undo]" or "[/help/redo|redo]" </ul></td> </tr> </table> <h3 id="configdb">2.1 The Configuration Database</h3> The configuration database holds cross-repository preferences and a list of all repositories for a single user. |
︙ | ︙ | |||
127 128 129 130 131 132 133 | operations such as "sync" or "rebuild" on all repositories managed by a user. <h4 id="configloc">2.1.1 Location Of The Configuration Database</h4> On Unix systems, the configuration database is named by the following algorithm: | | | | > | | 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 | operations such as "sync" or "rebuild" on all repositories managed by a user. <h4 id="configloc">2.1.1 Location Of The Configuration Database</h4> On Unix systems, the configuration database is named by the following algorithm: <table> <tr><td>1. if environment variable FOSSIL_HOME exists <td> → <td>$FOSSIL_HOME/.fossil <tr><td>2. if file ~/.fossil exists <td> →<td>~/.fossil <tr><td>3. if environment variable XDG_CONFIG_HOME exists <td> →<td>$XDG_CONFIG_HOME/fossil.db <tr><td>4. if the directory ~/.config exists <td> →<td>~/.config/fossil.db <tr><td>5. Otherwise<td> →<td>~/.fossil </table> Another way of thinking of this algorithm is the following: * Use "$FOSSIL_HOME/.fossil" if the FOSSIL_HOME variable is defined * Use the XDG-compatible name (usually ~/.config/fossil.db) on XDG systems if the ~/.fossil file does not already exist * Otherwise, use the traditional unix name of "~/.fossil" |
︙ | ︙ |
Changes to www/th1.md.
︙ | ︙ | |||
52 53 54 55 56 57 58 | that a TH1 script is really just a list of text commands, not a context-free language with a grammar like C/C++. This can be confusing to long-time C/C++ programmers because TH1 does look a lot like C/C++, but the semantics of TH1 are closer to FORTH or Lisp than they are to C. Consider the `if` command in TH1. | | | | | | | 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 | that a TH1 script is really just a list of text commands, not a context-free language with a grammar like C/C++. This can be confusing to long-time C/C++ programmers because TH1 does look a lot like C/C++, but the semantics of TH1 are closer to FORTH or Lisp than they are to C. Consider the `if` command in TH1. if {$current eq "dev"} { puts "hello" } else { puts "world" } The example above is a single command. The first token, and the name of the command, is `if`. The second token is `$current eq "dev"` - an expression. (The outer {...} are removed from each token by the command parser.) The third token is the `puts "hello"`, with its whitespace and newlines. The fourth token is `else` and the fifth and last token is `puts "world"`. |
︙ | ︙ | |||
81 82 83 84 85 86 87 | All of this also explains the emphasis on *unescaped* characters above: the curly braces `{ }` are string quoting characters in Tcl/TH1, not block delimiters as in C. This is how we can have a command that extends over multiple lines. It is also why the `else` keyword must be cuddled up with the closing brace for the `if` clause's scriptlet. The following is invalid Tcl/TH1: | | | | | | | | | | | 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 | All of this also explains the emphasis on *unescaped* characters above: the curly braces `{ }` are string quoting characters in Tcl/TH1, not block delimiters as in C. This is how we can have a command that extends over multiple lines. It is also why the `else` keyword must be cuddled up with the closing brace for the `if` clause's scriptlet. The following is invalid Tcl/TH1: if {$current eq "dev"} { puts "hello" } else { puts "world" } If you try to run this under either Tcl or TH1, the interpreter will tell you that there is no `else` command, because with the newline on the third line, you terminated the `if` command. Occasionally in Tcl/TH1 scripts, you may need to use a backslash at the end of a line to allow a command to extend over multiple lines without being considered two separate commands. Here's an example from one of Fossil's test scripts: return [lindex [regexp -line -inline -nocase -- \ {^uuid:\s+([0-9A-F]{40}) } [eval [getFossilCommand \ $repository "" info trunk]]] end] Those backslashes allow the command to wrap nicely within a standard terminal width while telling the interpreter to consider those three lines as a single command. Summary of Core TH1 Commands |
︙ | ︙ | |||
296 297 298 299 300 301 302 | the term is true if all of the capability letters in that term are available to the "anonymous" user. Or, if the term is "*" then it is always true. Examples: ``` | | | | | | | | 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 | the term is true if all of the capability letters in that term are available to the "anonymous" user. Or, if the term is "*" then it is always true. Examples: ``` capexpr {j o r} True if any one of j, o, or r are available capexpr {oh} True if both o and h are available capexpr {@2 @3 4 5 6} 2 or 3 available for anonymous or one of 4, 5 or 6 is available for the user capexpr L True if the user is logged in capexpr !L True if the user is not logged in ``` The `L` pseudo-capability is intended only to be used on its own or with the `!` prefix for implementing login/logout menus via the `mainmenu` site configuration option: ``` |
︙ | ︙ | |||
681 682 683 684 685 686 687 | 1. **w** -- _Wiki_ To be clear, only one of the document classes identified by each STRING needs to be searchable in order for that argument to be true. But all arguments must be true for this routine to return true. Hence, to see if ALL document classes are searchable: | | | | 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 | 1. **w** -- _Wiki_ To be clear, only one of the document classes identified by each STRING needs to be searchable in order for that argument to be true. But all arguments must be true for this routine to return true. Hence, to see if ALL document classes are searchable: if {[searchable c d t w]} {...} But to see if ANY document class is searchable: if {[searchable cdtw]} {...} This command is useful for enabling or disabling a "Search" entry on the menu bar. <a id="setParameter"></a>TH1 setParameter Command --------------------------------------------------- |
︙ | ︙ |
Changes to www/theory1.wiki.
1 | <title>Thoughts On The Design Of The Fossil DVCS</title> | < | 1 2 3 4 5 6 7 8 | <title>Thoughts On The Design Of The Fossil DVCS</title> Two questions (or criticisms) that arise frequently regarding Fossil can be summarized as follows: 1. Why is Fossil based on SQLite instead of a distributed NoSQL database? 2. Why is Fossil written in C instead of a modern high-level language? |
︙ | ︙ |
Changes to www/tickets.wiki.
︙ | ︙ | |||
45 46 47 48 49 50 51 | <h3>2.1 Ticket Table Schema</h3> The two ticket tables are called TICKET and TICKETCHNG. The default schema (as of this writing) for these two tables is shown below: | | | 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 | <h3>2.1 Ticket Table Schema</h3> The two ticket tables are called TICKET and TICKETCHNG. The default schema (as of this writing) for these two tables is shown below: <verbatim> CREATE TABLE ticket( -- Do not change any column that begins with tkt_ tkt_id INTEGER PRIMARY KEY, tkt_uuid TEXT UNIQUE, tkt_mtime DATE, tkt_ctime DATE, -- Add as many fields as required below this line |
︙ | ︙ | |||
76 77 78 79 80 81 82 | -- Add as many fields as required below this line login TEXT, username TEXT, mimetype TEXT, icomment TEXT ); CREATE INDEX ticketchng_idx1 ON ticketchng(tkt_id, tkt_mtime); | | | 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 | -- Add as many fields as required below this line login TEXT, username TEXT, mimetype TEXT, icomment TEXT ); CREATE INDEX ticketchng_idx1 ON ticketchng(tkt_id, tkt_mtime); </verbatim> Generally speaking, there is one row in the TICKETCHNG table for each change to each ticket. In other words, there is one row in the TICKETCHNG table for each low-level ticket change artifact. The TICKET table, on the other hand, contains a summary of the current status of each ticket. |
︙ | ︙ |
Changes to www/unvers.wiki.
1 | <title>Unversioned Content</title> | < | 1 2 3 4 5 6 7 8 | <title>Unversioned Content</title> "Unversioned content" or "unversioned files" are files stored in a Fossil repository without history, meaning it retains the newest version of each such file, and that alone. Though it omits history, Fossil does sync unversioned content between repositories. In the event of a conflict during a sync, it retains |
︙ | ︙ | |||
32 33 34 35 36 37 38 | the [/help?cmd=/uvlist|/uvlist] URL. ([/uvlist|example]). <h2>Syncing Unversioned Files</h2> Unversioned content does not sync between repositories by default. One must request it via commands such as: | | | | 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 | the [/help?cmd=/uvlist|/uvlist] URL. ([/uvlist|example]). <h2>Syncing Unversioned Files</h2> Unversioned content does not sync between repositories by default. One must request it via commands such as: <pre> fossil sync <b>-u</b> fossil clone <b>-u</b> <i>URL local-repo-name</i> fossil unversioned sync </pre> The [/help?cmd=sync|fossil sync] and [/help?cmd=clone|fossil clone] commands will synchronize unversioned content if and only if they're given the "-u" (or "--unversioned") command-line option. The [/help?cmd=unversioned|fossil unversioned sync] command synchronizes the unversioned content without synchronizing anything else. |
︙ | ︙ | |||
70 71 72 73 74 75 76 | <i>(This section outlines the current implementation of unversioned files. This is not an interface spec and hence subject to change.)</i> Unversioned content is stored in the repository in the "unversioned" table: | | | | | | 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 | <i>(This section outlines the current implementation of unversioned files. This is not an interface spec and hence subject to change.)</i> Unversioned content is stored in the repository in the "unversioned" table: <pre> CREATE TABLE unversioned( uvid INTEGER PRIMARY KEY AUTOINCREMENT, -- unique ID for this file name TEXT UNIQUE, -- Name of the file rcvid INTEGER, -- From whence this file was received mtime DATETIME, -- Last change (seconds since 1970) hash TEXT, -- SHA1 or SHA3-256 hash of uncompressed content sz INTEGER, -- Size of uncompressed content encoding INT, -- 0: plaintext 1: zlib compressed content BLOB -- File content ); </pre> Fossil does not create the table ahead of need. If there are no unversioned files in the repository, the "unversioned" table will not exist. Consequently, one simple way to purge all unversioned content from a repository is to run: <pre> fossil sql "DROP TABLE unversioned; VACUUM;" </pre> Lacking history for unversioned files, Fossil does not attempt delta compression on them. Fossil servers exchange unversioned content whole; it does not attempt to "diff" your local version against the remote and send only the changes. We point this out because one use-case for unversioned content |
︙ | ︙ |
Changes to www/webui.wiki.
︙ | ︙ | |||
30 31 32 33 34 35 36 | As an example of how useful this web interface can be, the entire [./index.wiki | Fossil website], including the document you are now reading, is rendered using the Fossil web interface, with no enhancements, and little customization. | | | | | | 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 | As an example of how useful this web interface can be, the entire [./index.wiki | Fossil website], including the document you are now reading, is rendered using the Fossil web interface, with no enhancements, and little customization. <p class="indent"> <b>Key point:</b> <i>The Fossil website is just a running instance of Fossil! </p> Note also that because Fossil is a distributed system, you can run the web interface on your local machine while off network (for example, while on an airplane) including making changes to wiki pages and/or trouble ticket, then synchronize with your co-workers after you reconnect. When you clone a Fossil repository, you don't just get the project source code, you get the entire project management website. <h2>Very Simple Startup</h2> To start using the built-in Fossil web interface on an existing Fossil repository, simply type this: <pre>fossil ui existing-repository.fossil</pre> Substitute the name of your repository, of course. The "ui" command will start a web server running (it figures out an available TCP port to use on its own) and then automatically launches your web browser to point at that server. If you run the "ui" command from within an open check-out, you can omit the repository name: <pre>fossil ui</pre> The latter case is a very useful short-cut when you are working on a Fossil project and you want to quickly do some work with the web interface. Notice that Fossil automatically finds an unused TCP port to run the server on and automatically points your web browser to the correct URL. So there is never any fumbling around trying to find an open port or to type arcane strings into your browser URL entry box. |
︙ | ︙ | |||
151 152 153 154 155 156 157 | available to a distributed team by simply copying the single repository file up to a web server that supports CGI or SCGI. To run Fossil as CGI, just put the <b>sample-project.fossil</b> file in a directory where CGI scripts have both read and write permission on the file and the directory that contains the file, then add a CGI script that looks something like this: | < | | < < | | < | 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 | available to a distributed team by simply copying the single repository file up to a web server that supports CGI or SCGI. To run Fossil as CGI, just put the <b>sample-project.fossil</b> file in a directory where CGI scripts have both read and write permission on the file and the directory that contains the file, then add a CGI script that looks something like this: <verbatim> #!/usr/local/bin/fossil repository: /home/www/sample-project.fossil</verbatim> Adjust the script above so that the paths are correct for your system, of course, and also make sure the Fossil binary is installed on the server. But that is <u>all</u> you have to do. You now have everything you need to host a distributed software development project in less than five minutes using a two-line CGI script. Instructions for setting up an SCGI server are [./scgi.wiki | available separately]. You don't have a CGI- or SCGI-capable web server running on your server machine? Not a problem. The Fossil interface can also be launched via inetd or xinetd. An inetd configuration line sufficient to launch the Fossil web interface looks like this: <verbatim> 80 stream tcp nowait.1000 root /usr/local/bin/fossil \ /usr/local/bin/fossil http /home/www/sample-project.fossil</verbatim> As always, you'll want to adjust the pathnames to whatever is appropriate for your system. The xinetd setup uses a different syntax but follows the same idea. |