Fossil SCM
Modernized the default skin, primarily to improve readability, and forked off the old default as "Étienne", named in honor of its creator.
Commit
8a1ba49b73da1b58b2a09d562d97be778ee9b198679b360554d46ff8b91b58e6
Parent
5a09f499a8bfe2b…
90 files changed
+9
-4
+462
-37
+2
-2
+44
-6
+14
+201
+3
+4
+28
+46
-8
+2
-2
+5
-1
+1
+1
+2
-3
+4
+8
+32
-22
-1
+8
-8
+16
-19
+5
-5
+2
-2
+4
-4
+37
-38
+2
-2
+4
+9
-9
+42
-41
+2
-2
+37
-37
+12
-15
+106
-166
+60
-55
+64
-69
+13
-15
+4
-6
+8
-9
+17
-21
+30
-18
+12
-18
+19
-15
+30
-26
+22
-28
+13
-11
+2
-3
+108
-108
+2
-2
+29
-29
+2
-2
+10
-10
+15
-15
+3
-3
+14
-14
+7
-10
+2
-2
+3
-3
+10
-11
+2
-2
-1
+21
-21
+17
-22
+119
-152
+37
-37
+6
-6
+4
-4
-2
+6
-6
+9
-9
+26
-26
+2
-2
+3
-3
+6
-6
+9
-9
+46
-48
+46
-46
+5
-44
+40
-38
+119
-119
+22
-16
+1
-1
+14
-14
+1
-2
+47
-57
+18
-22
+22
-22
-1
+2
-2
+6
-7
+8
-12
~
skins/default/README.md
~
skins/default/css.txt
~
skins/default/footer.txt
~
skins/default/header.txt
~
skins/etienne/README.md
~
skins/etienne/css.txt
~
skins/etienne/details.txt
~
skins/etienne/footer.txt
~
skins/etienne/header.txt
~
src/default.css
~
src/hbmenu.js
~
src/main.mk
~
src/skins.c
~
src/wikiformat.c
~
test/release-checklist.wiki
~
win/Makefile.mingw
~
win/Makefile.msc
~
www/aboutcgi.wiki
~
www/aboutdownload.wiki
~
www/adding_code.wiki
~
www/alerts.md
~
www/backoffice.md
~
www/backup.md
~
www/branching.wiki
~
www/build.wiki
~
www/cgi.wiki
~
www/changes.wiki
~
www/chat.md
~
www/checkin_names.wiki
~
www/childprojects.wiki
~
www/ckout-workflows.md
~
www/concepts.wiki
~
www/containers.md
~
www/custom_ticket.wiki
~
www/customskin.md
~
www/defcsp.md
~
www/delta-manifests.md
~
www/delta_format.wiki
~
www/embeddeddoc.wiki
~
www/encryptedrepos.wiki
~
www/event.wiki
~
www/faq.tcl
~
www/faq.wiki
~
www/fileformat.wiki
~
www/fossil-v-git.wiki
~
www/fossil_prompt.wiki
~
www/gitusers.md
~
www/hashpolicy.wiki
~
www/image-format-vs-repo-size.md
~
www/index.wiki
~
www/inout.wiki
~
www/javascript.md
~
www/loadmgmt.md
~
www/makefile.wiki
~
www/mirrortogithub.md
~
www/mkindex.tcl
~
www/newrepo.wiki
~
www/password.wiki
~
www/permutedindex.html
~
www/pop.wiki
~
www/private.wiki
~
www/qandc.wiki
~
www/quickstart.wiki
~
www/quotes.wiki
~
www/reviews.wiki
~
www/scgi.wiki
~
www/selfcheck.wiki
~
www/selfhost.wiki
~
www/server/any/cgi.md
~
www/server/any/http-over-ssh.md
~
www/server/any/inetd.md
~
www/server/any/none.md
~
www/server/any/scgi.md
~
www/server/any/xinetd.md
~
www/server/debian/nginx.md
~
www/server/debian/service.md
~
www/server/index.html
~
www/server/macos/service.md
~
www/server/openbsd/fastcgi.md
~
www/server/openbsd/service.wiki
~
www/server/windows/iis.md
~
www/serverext.wiki
~
www/stats.wiki
~
www/sync.wiki
~
www/tech_overview.wiki
~
www/th1.md
~
www/theory1.wiki
~
www/tickets.wiki
~
www/unvers.wiki
~
www/webui.wiki
+9
-4
| --- skins/default/README.md | ||
| +++ skins/default/README.md | ||
| @@ -1,5 +1,10 @@ | ||
| 1 | -This skin was contributed by Étienne Deparis. | |
| 1 | +This skin was originally contributed by Étienne Deparis on 2015-02-22, | |
| 2 | +promoted to the default on 2015-03-14, and subsequently changed by many: | |
| 3 | + | |
| 4 | + https://fossil-scm.org/home/finfo/skins/default/css.txt | |
| 5 | + https://fossil-scm.org/home/blame?filename=skins/default/css.txt&checkin=trunk | |
| 2 | 6 | |
| 3 | -On 2015-03-14 this skin was promoted from an option to the default, which | |
| 4 | -involved moving it from its original home in the skins/etienne1 directory | |
| 5 | -into skins/default. | |
| 7 | +In February 2024, a sufficiently large set of changes were made to the | |
| 8 | +skin that we forked the old version for the benefit of those who needed | |
| 9 | +to reference the old one — as when migrating custom skin changes to work | |
| 10 | +atop the new default — or who simply preferred it. See ../etienne. | |
| 6 | 11 |
| --- skins/default/README.md | |
| +++ skins/default/README.md | |
| @@ -1,5 +1,10 @@ | |
| 1 | This skin was contributed by Étienne Deparis. |
| 2 | |
| 3 | On 2015-03-14 this skin was promoted from an option to the default, which |
| 4 | involved moving it from its original home in the skins/etienne1 directory |
| 5 | into skins/default. |
| 6 |
| --- skins/default/README.md | |
| +++ skins/default/README.md | |
| @@ -1,5 +1,10 @@ | |
| 1 | This skin was originally contributed by Étienne Deparis on 2015-02-22, |
| 2 | promoted to the default on 2015-03-14, and subsequently changed by many: |
| 3 | |
| 4 | https://fossil-scm.org/home/finfo/skins/default/css.txt |
| 5 | https://fossil-scm.org/home/blame?filename=skins/default/css.txt&checkin=trunk |
| 6 | |
| 7 | In February 2024, a sufficiently large set of changes were made to the |
| 8 | skin that we forked the old version for the benefit of those who needed |
| 9 | to reference the old one — as when migrating custom skin changes to work |
| 10 | atop the new default — or who simply preferred it. See ../etienne. |
| 11 |
+462
-37
| --- skins/default/css.txt | ||
| +++ skins/default/css.txt | ||
| @@ -1,16 +1,27 @@ | ||
| 1 | -/* Overall page style */ | |
| 1 | +/* Overall page style; vi: filetype=css | |
| 2 | + */ | |
| 2 | 3 | |
| 3 | 4 | body { |
| 4 | 5 | margin: 0 auto; |
| 5 | 6 | background-color: white; |
| 6 | 7 | font-family: sans-serif; |
| 7 | - font-size: 14pt; | |
| 8 | 8 | } |
| 9 | 9 | |
| 10 | 10 | a { |
| 11 | - color: #4183C4; | |
| 11 | + /* Unvisited links are a lightness-adjusted version of this skin's | |
| 12 | + * header blue, balancing contrast between the body text and the | |
| 13 | + * background in order to meet the goals specified by the WCAG 2 | |
| 14 | + * accessbility standard, earning us an "AA" grade according to | |
| 15 | + * the calculator result here: | |
| 16 | + * | |
| 17 | + * https://webaim.org/resources/linkcontrastchecker/?fcolor=2E2E2E&bcolor=FFFFFF&lcolor=3779BF | |
| 18 | + * | |
| 19 | + * It is for this same reason that our not-quite-black body text | |
| 20 | + * color is the shade of dark gray that it is. It can't be any | |
| 21 | + * lighter and still allow us to meet both targets. */ | |
| 22 | + color: #3779BF; | |
| 12 | 23 | text-decoration: none; |
| 13 | 24 | } |
| 14 | 25 | a:hover { |
| 15 | 26 | color: #4183C4; |
| 16 | 27 | text-decoration: underline; |
| @@ -23,26 +34,28 @@ | ||
| 23 | 34 | color: #4183C4; |
| 24 | 35 | float: left; |
| 25 | 36 | } |
| 26 | 37 | .title h1 { |
| 27 | 38 | display: inline; |
| 28 | -} | |
| 29 | -.title h1:after { | |
| 30 | - content: " / "; | |
| 31 | - color: #777; | |
| 32 | - font-weight: normal; | |
| 39 | + font-size: 2.20em; | |
| 33 | 40 | } |
| 34 | 41 | .status { |
| 35 | 42 | float: right; |
| 36 | - font-size: 0.7em; | |
| 43 | + font-size: 0.8em; | |
| 44 | +} | |
| 45 | +div.logo { | |
| 46 | + float: left; | |
| 47 | + padding-right: 10px; | |
| 48 | +} | |
| 49 | +div.logo img { | |
| 50 | + max-height: 2em; /* smaller than title to keep it above the baseline */ | |
| 37 | 51 | } |
| 38 | 52 | |
| 39 | 53 | |
| 40 | 54 | /* Main menu and optional sub-menu */ |
| 41 | 55 | |
| 42 | 56 | .mainmenu { |
| 43 | - font-size: 0.8em; | |
| 44 | 57 | clear: both; |
| 45 | 58 | background: #eaeaea linear-gradient(#fafafa, #eaeaea) repeat-x; |
| 46 | 59 | border: 1px solid #eaeaea; |
| 47 | 60 | border-radius: 5px; |
| 48 | 61 | overflow-x: auto; |
| @@ -58,11 +71,11 @@ | ||
| 58 | 71 | .mainmenu a.active, |
| 59 | 72 | .mainmenu a:hover { |
| 60 | 73 | color: #000; |
| 61 | 74 | border-bottom: 2px solid #D26911; |
| 62 | 75 | } |
| 63 | -div#hbdrop { | |
| 76 | +nav#hbdrop { | |
| 64 | 77 | background-color: white; |
| 65 | 78 | border: 1px solid black; |
| 66 | 79 | border-top: white; |
| 67 | 80 | border-radius: 0 0 0.5em 0.5em; |
| 68 | 81 | display: none; |
| @@ -73,11 +86,11 @@ | ||
| 73 | 86 | position: absolute; |
| 74 | 87 | z-index: 20; /* just below mainmenu, but above timeline bubbles */ |
| 75 | 88 | } |
| 76 | 89 | |
| 77 | 90 | .submenu { |
| 78 | - font-size: .7em; | |
| 91 | + font-size: 0.8em; | |
| 79 | 92 | padding: 10px; |
| 80 | 93 | border-bottom: 1px solid #ccc; |
| 81 | 94 | } |
| 82 | 95 | .submenu a, .submenu label { |
| 83 | 96 | padding: 10px 11px; |
| @@ -102,26 +115,18 @@ | ||
| 102 | 115 | |
| 103 | 116 | |
| 104 | 117 | /* Main document area; elements common to most pages. */ |
| 105 | 118 | |
| 106 | 119 | .content { |
| 107 | - padding-top: 10px; | |
| 108 | - font-size: 0.8em; | |
| 109 | - color: #444; | |
| 110 | -} | |
| 111 | -.content blockquote { | |
| 112 | - padding: 0 15px; | |
| 113 | -} | |
| 114 | -.content h1 { | |
| 115 | - font-size: 1.25em; | |
| 116 | -} | |
| 117 | -.content h2 { | |
| 118 | - font-size: 1.15em; | |
| 119 | -} | |
| 120 | -.content h3 { | |
| 121 | - font-size: 1.05em; | |
| 122 | -} | |
| 120 | + padding: 1ex; | |
| 121 | + color: #2e2e2e; /* justified above in "WCAG 2" comment */ | |
| 122 | +} | |
| 123 | +.content h1 { font-size: 1.60em; color: #444; } | |
| 124 | +.content h2 { font-size: 1.45em; color: #444; } | |
| 125 | +.content h3 { font-size: 1.15em; color: #444; } | |
| 126 | +.content h4 { font-size: 1.05em; color: #444; } | |
| 127 | +.content h5 { font-size: 1.00em; color: #444; } | |
| 123 | 128 | |
| 124 | 129 | .section { |
| 125 | 130 | font-size: 1em; |
| 126 | 131 | font-weight: bold; |
| 127 | 132 | background-color: #f5f5f5; |
| @@ -148,14 +153,14 @@ | ||
| 148 | 153 | } |
| 149 | 154 | |
| 150 | 155 | |
| 151 | 156 | /* Page footer */ |
| 152 | 157 | |
| 153 | -.footer { | |
| 158 | +footer { | |
| 154 | 159 | border-top: 1px solid #ccc; |
| 155 | 160 | padding: 10px; |
| 156 | - font-size: 0.7em; | |
| 161 | + font-size: 0.8em; | |
| 157 | 162 | margin-top: 10px; |
| 158 | 163 | color: #ccc; |
| 159 | 164 | } |
| 160 | 165 | |
| 161 | 166 | /* Forum */ |
| @@ -162,23 +167,201 @@ | ||
| 162 | 167 | |
| 163 | 168 | .forum a:visited { |
| 164 | 169 | color: #6A7F94; |
| 165 | 170 | } |
| 166 | 171 | |
| 167 | -.forum blockquote { | |
| 172 | +div.forumSel { | |
| 173 | + animation: 1s linear 0s sel-fade; | |
| 174 | + background-color: white; /* animation end state */ | |
| 175 | + border-left: 4px solid black; /* after-animation selection indicator */ | |
| 176 | +} | |
| 177 | +@keyframes sel-fade { | |
| 178 | + from { background-color: #cef; } | |
| 179 | + to { background-color: white; } | |
| 180 | +} | |
| 181 | + | |
| 182 | +.forum form input { | |
| 183 | + margin: 0.5em 0; | |
| 184 | +} | |
| 185 | + | |
| 186 | + | |
| 187 | +/* Markdown and Wiki-formatted pages: /wiki, /doc, /file... */ | |
| 188 | + | |
| 189 | +.markdown blockquote, p.blockquote, .sidebar { | |
| 190 | + /* Override default.css version with our accent colors. */ | |
| 168 | 191 | background-color: rgba(65, 131, 196, 0.1); |
| 169 | - border-left: 3px solid #254769; | |
| 170 | - padding: .1em 1em; | |
| 192 | + border-left-color: #4183c4; | |
| 193 | +} | |
| 194 | + | |
| 195 | +/* Mark inline code fragments in the near-universal manner pioneered by | |
| 196 | + * Stack Overflow, then picked up by approximately everyone, including | |
| 197 | + * us, now. | |
| 198 | + * | |
| 199 | + * This combinatoric selector explosion results from a need to apply | |
| 200 | + * these stylings inside multiple page container types, multiplied by | |
| 201 | + * the surprisingly large number of tags HTML defines for semantically | |
| 202 | + * differentiated monospaced inline markup. If we do not target the | |
| 203 | + * elements we want to affect carefully, we'll end up overreaching, | |
| 204 | + * styling Fossil UI elements that use these tags for local purposes. | |
| 205 | + * | |
| 206 | + * HTML generated and emitted by Fossil UI does not always fall under | |
| 207 | + * the skin's generic rules; we must avoid intruding on its domain. | |
| 208 | + * Our limited intent here is to style user content only, where it is | |
| 209 | + * unreasonable to expect its author to take the time to hand-craft | |
| 210 | + * per-document styling. Contrast Fossil UI, which often does exactly | |
| 211 | + * that in order to get particular results. | |
| 212 | + * | |
| 213 | + * The equivalent Sass syntax is far more compact, thus clearer: | |
| 214 | + * | |
| 215 | + * .artifact, .dir, .doc, .wiki // the page types we target | |
| 216 | + * > .content // hands off header & footer | |
| 217 | + * &, > .fossil-doc, > .markdown // wiki, HTML & MD emb docs | |
| 218 | + * > p // inline elements only | |
| 219 | + * > code, > kbd, > samp, > tt, > var // monospaced tag types | |
| 220 | + * background-color: #eee // pale gray box that… | |
| 221 | + * padding: 0 4px // …extends around the sides | |
| 222 | + * | |
| 223 | + * We generated the CSS below by: | |
| 224 | + * | |
| 225 | + * $ sassc code.sass | sed -e 's/, /,\n/g' | |
| 226 | + * | |
| 227 | + * …then hand-cleansed it to make it _somewhat_ more understandable. | |
| 228 | + */ | |
| 229 | +.artifact > .content > p > code, | |
| 230 | +.artifact > .content > p > kbd, | |
| 231 | +.artifact > .content > p > samp, | |
| 232 | +.artifact > .content > p > tt, | |
| 233 | +.artifact > .content > p > var, | |
| 234 | +.artifact > .content > .fossil-doc > p > code, | |
| 235 | +.artifact > .content > .fossil-doc > p > kbd, | |
| 236 | +.artifact > .content > .fossil-doc > p > samp, | |
| 237 | +.artifact > .content > .fossil-doc > p > tt, | |
| 238 | +.artifact > .content > .fossil-doc > p > var, | |
| 239 | +.artifact > .content > .markdown > p > code, | |
| 240 | +.artifact > .content > .markdown > p > kbd, | |
| 241 | +.artifact > .content > .markdown > p > samp, | |
| 242 | +.artifact > .content > .markdown > p > tt, | |
| 243 | +.artifact > .content > .markdown > p > var, | |
| 244 | +.dir > .content > p > code, | |
| 245 | +.dir > .content > p > kbd, | |
| 246 | +.dir > .content > p > samp, | |
| 247 | +.dir > .content > p > tt, | |
| 248 | +.dir > .content > p > var, | |
| 249 | +.dir > .content > .fossil-doc > p > code, | |
| 250 | +.dir > .content > .fossil-doc > p > kbd, | |
| 251 | +.dir > .content > .fossil-doc > p > samp, | |
| 252 | +.dir > .content > .fossil-doc > p > tt, | |
| 253 | +.dir > .content > .fossil-doc > p > var, | |
| 254 | +.dir > .content > .markdown > p > code, | |
| 255 | +.dir > .content > .markdown > p > kbd, | |
| 256 | +.dir > .content > .markdown > p > samp, | |
| 257 | +.dir > .content > .markdown > p > tt, | |
| 258 | +.dir > .content > .markdown > p > var, | |
| 259 | +.doc > .content > p > code, | |
| 260 | +.doc > .content > p > kbd, | |
| 261 | +.doc > .content > p > samp, | |
| 262 | +.doc > .content > p > tt, | |
| 263 | +.doc > .content > p > var, | |
| 264 | +.doc > .content > .fossil-doc > p > code, | |
| 265 | +.doc > .content > .fossil-doc > p > kbd, | |
| 266 | +.doc > .content > .fossil-doc > p > samp, | |
| 267 | +.doc > .content > .fossil-doc > p > tt, | |
| 268 | +.doc > .content > .fossil-doc > p > var, | |
| 269 | +.doc > .content > .markdown > p > code, | |
| 270 | +.doc > .content > .markdown > p > kbd, | |
| 271 | +.doc > .content > .markdown > p > samp, | |
| 272 | +.doc > .content > .markdown > p > tt, | |
| 273 | +.doc > .content > .markdown > p > var, | |
| 274 | +.wiki > .content > p > code, | |
| 275 | +.wiki > .content > p > kbd, | |
| 276 | +.wiki > .content > p > samp, | |
| 277 | +.wiki > .content > p > tt, | |
| 278 | +.wiki > .content > p > var, | |
| 279 | +.wiki > .content > .fossil-doc > p > code, | |
| 280 | +.wiki > .content > .fossil-doc > p > kbd, | |
| 281 | +.wiki > .content > .fossil-doc > p > samp, | |
| 282 | +.wiki > .content > .fossil-doc > p > tt, | |
| 283 | +.wiki > .content > .fossil-doc > p > var, | |
| 284 | +.wiki > .content > .markdown > p > code, | |
| 285 | +.wiki > .content > .markdown > p > kbd, | |
| 286 | +.wiki > .content > .markdown > p > samp, | |
| 287 | +.wiki > .content > .markdown > p > tt, | |
| 288 | +.wiki > .content > .markdown > p > var { | |
| 289 | + background-color: #eee; | |
| 290 | + padding: 0 4px; | |
| 291 | +} | |
| 292 | +.content pre { | |
| 293 | + hyphens: none; | |
| 294 | + line-height: 1.25; | |
| 295 | +} | |
| 296 | + | |
| 297 | +.content .pikchr-wrapper { | |
| 298 | + /* Pikchr was developed with the assumption that it would be | |
| 299 | + * integrated into a Fossil repo using the old 0.9em body font | |
| 300 | + * size, which no longer obtians. This gives us a choice: | |
| 301 | + * | |
| 302 | + * 1. Change Pikchr to track this skin change, potentially breaking | |
| 303 | + * uses of alternate skins with differing default font sizes. | |
| 304 | + * 2. Restore the old default for Pikchr diagrams so the old | |
| 305 | + * assumptions continue to be valid. | |
| 306 | + * 3. Make everyone with custom skins set pikchr-scale=1.11 (1/0.9) | |
| 307 | + * in their skin's footer.txt to increase the diagram's relative | |
| 308 | + * size to compensate for the font size change. | |
| 309 | + * | |
| 310 | + * We choose #2 because it puts both adjustments in the same file. */ | |
| 311 | + font-size: 0.9em; | |
| 312 | +} | |
| 313 | + | |
| 314 | +.content ul li { | |
| 315 | + list-style-type: disc; | |
| 316 | +} | |
| 317 | + | |
| 318 | +.doc > .content table { | |
| 319 | + background-color: #f0f5f9; | |
| 320 | + border: 1px solid #a7c2dc; | |
| 321 | + border-radius: 0.5em; | |
| 322 | + border-spacing: 0; | |
| 323 | + padding: 6px; | |
| 324 | +} | |
| 325 | +.doc > .content th { | |
| 326 | + border-bottom: 1px solid #dee8f2; | |
| 327 | + padding-bottom: 4px; | |
| 328 | + padding-right: 6px; | |
| 329 | + text-align: left; | |
| 330 | +} | |
| 331 | +.doc > .content tr > th { | |
| 332 | + background-color: #dee8f0; | |
| 333 | +} | |
| 334 | +.doc > .content tr:nth-child(odd) { | |
| 335 | + background-color: #e0e8ee; | |
| 336 | +} | |
| 337 | +.doc > .content td { | |
| 338 | + padding-bottom: 4px; | |
| 339 | + padding-right: 6px; | |
| 340 | + text-align: left; | |
| 341 | +} | |
| 342 | + | |
| 343 | +/* Wiki adjustments */ | |
| 344 | +pre.verbatim { | |
| 345 | + /* keep code examples from crashing into sidebars, etc. */ | |
| 346 | + white-space: pre-wrap; | |
| 347 | +} | |
| 348 | +textarea.wikiedit { | |
| 349 | + /* Monospace fonts tend to have smaller x-heights; compensate. | |
| 350 | + * Can't do this generally because not all fonts have this problem. | |
| 351 | + * A textarea stands alone, whereas inline <code> has to work with | |
| 352 | + * the browser's choice of sans-serif proportional font. */ | |
| 353 | + font-size: 1.1em; | |
| 171 | 354 | } |
| 172 | 355 | |
| 173 | 356 | |
| 174 | 357 | /* Tickets */ |
| 175 | 358 | |
| 176 | 359 | table.report { |
| 177 | 360 | cursor: auto; |
| 178 | - border-radius: 5px; | |
| 179 | 361 | border: 1px solid #ccc; |
| 362 | + border-radius: 0.5em; | |
| 180 | 363 | margin: 1em 0; |
| 181 | 364 | } |
| 182 | 365 | .report td, .report th { |
| 183 | 366 | border: 0; |
| 184 | 367 | font-size: .8em; |
| @@ -224,15 +407,44 @@ | ||
| 224 | 407 | |
| 225 | 408 | |
| 226 | 409 | /* Timeline */ |
| 227 | 410 | |
| 228 | 411 | span.timelineDetail { |
| 229 | - font-size: 90%; | |
| 412 | + font-size: 90%; | |
| 230 | 413 | } |
| 231 | 414 | div.timelineDate { |
| 232 | - font-weight: bold; | |
| 233 | - white-space: nowrap; | |
| 415 | + font-weight: bold; | |
| 416 | + white-space: nowrap; | |
| 417 | +} | |
| 418 | + | |
| 419 | +tr.timelineSelected, tr.timelineCurrent { | |
| 420 | + /* etienne/css.txt puts these styles on the whole row. We want them only | |
| 421 | + * on the comment/details cell within the table, not over the time | |
| 422 | + * and graph columns as well. */ | |
| 423 | + background-color: unset; | |
| 424 | + border: unset; | |
| 425 | + box-shadow: unset; | |
| 426 | +} | |
| 427 | +tr.timelineCurrent td.timelineModernCell, | |
| 428 | +tr.timelineCurrent td.timelineColumnarCell { | |
| 429 | + border: 1px dashed #446979; | |
| 430 | + border-radius: 1em; | |
| 431 | +} | |
| 432 | +tr.timelineSelected td.timelineModernCell, | |
| 433 | +tr.timelineSelected td.timelineColumnarCell { | |
| 434 | + background-color: #fbe8d5; | |
| 435 | + border-radius: 1em; | |
| 436 | +} | |
| 437 | +tr.timelineSecondary td.timelineModernCell, | |
| 438 | +tr.timelineSecondary td.timelineColumnarCell { | |
| 439 | + background-color: #d5e8fb; | |
| 440 | +} | |
| 441 | +span.timelineSelected { | |
| 442 | + background-color: #fbe8d5; | |
| 443 | +} | |
| 444 | +span.timelineSecondary { | |
| 445 | + background-color: #d5e8fb; | |
| 234 | 446 | } |
| 235 | 447 | |
| 236 | 448 | |
| 237 | 449 | /* Miscellaneous UI elements */ |
| 238 | 450 | |
| @@ -247,14 +459,24 @@ | ||
| 247 | 459 | /* Spacing for mobile */ |
| 248 | 460 | body { |
| 249 | 461 | padding-left: 4px; |
| 250 | 462 | padding-right: 4px; |
| 251 | 463 | } |
| 464 | + .content { | |
| 465 | + font-size: 0.9em; | |
| 466 | + } | |
| 252 | 467 | .title { |
| 253 | 468 | padding-top: 0px; |
| 254 | 469 | padding-bottom: 0px; |
| 255 | 470 | } |
| 471 | + .title > .page-title { | |
| 472 | + display: none; /* use h1 in body area, below menu bar */ | |
| 473 | + } | |
| 474 | + h1.page-title { | |
| 475 | + font-size: 1.60em; /* match content > h1 */ | |
| 476 | + margin-bottom: 0; /* div.content top margin suffices */ | |
| 477 | + } | |
| 256 | 478 | .status {padding-top: 0px;} |
| 257 | 479 | .mainmenu a { |
| 258 | 480 | padding: 8px 10px; |
| 259 | 481 | } |
| 260 | 482 | .mainmenu { |
| @@ -269,13 +491,216 @@ | ||
| 269 | 491 | } |
| 270 | 492 | .title { |
| 271 | 493 | padding-top: 10px; |
| 272 | 494 | padding-bottom: 10px; |
| 273 | 495 | } |
| 496 | + .title h1:after { | |
| 497 | + content: " / "; | |
| 498 | + color: #777; | |
| 499 | + font-weight: normal; | |
| 500 | + } | |
| 501 | + h1.page-title { | |
| 502 | + display: none; /* use h1 in title area, above menu bar */ | |
| 503 | + } | |
| 504 | + span.page-title { | |
| 505 | + font-size: 18px; | |
| 506 | + } | |
| 507 | + div.logo { | |
| 508 | + padding-top: 10px; | |
| 509 | + } | |
| 274 | 510 | .status {padding-top: 30px;} |
| 275 | 511 | .mainmenu a { |
| 276 | 512 | padding: 8px 20px; |
| 277 | 513 | } |
| 278 | 514 | .mainmenu { |
| 279 | 515 | padding: 10px; |
| 280 | 516 | } |
| 517 | + | |
| 518 | + /* Wide screens mean long lines. Add extra leading to give the eye a | |
| 519 | + * "gutter" to follow from the end of one to the start of the next. */ | |
| 520 | + .content dd, | |
| 521 | + .content dt, | |
| 522 | + .content div, | |
| 523 | + .content li, | |
| 524 | + .content p, | |
| 525 | + .content table { | |
| 526 | + line-height: 1.4em; | |
| 527 | + } | |
| 528 | + | |
| 529 | + /* This horror show has the same cause that informed our handling of | |
| 530 | + * <code> and friends above; see "combinatorial selector explosion." | |
| 531 | + * Without this careful targeting, we'd not only overreach into areas | |
| 532 | + * of Fossil UI where our meddling is not wanted, we would mistakenly | |
| 533 | + * apply double indents to nested formatting in MD forum posts, p | |
| 534 | + * within td tags, and more. | |
| 535 | + * | |
| 536 | + * Rather than give the equivalent Sass code here, see the SCSS file | |
| 537 | + * that the [Inskinerator](https://tangentsoft.com/inskinerator/) | |
| 538 | + * project ships as override/modern/media.scss. Rendering that | |
| 539 | + * through sassc gives substantially identical output, modulo the | |
| 540 | + * hand-polishing we've done here. */ | |
| 541 | + .artifact > .content > p, | |
| 542 | + .artifact > .content > .markdown > p, | |
| 543 | + .artifact > .content > .fossil-doc > p, | |
| 544 | + .artifact > .content > ol, .artifact > .content > ul, | |
| 545 | + .artifact > .content > .markdown > ol, .artifact > .content > .markdown > ul, | |
| 546 | + .artifact > .content > .fossil-doc > ol, .artifact > .content > .fossil-doc > ul, | |
| 547 | + .artifact > .content > table, | |
| 548 | + .artifact > .content > .markdown > table, | |
| 549 | + .artifact > .content > .fossil-doc > table, | |
| 550 | + .dir > .content > p, | |
| 551 | + .dir > .content > .markdown > p, | |
| 552 | + .dir > .content > .fossil-doc > p, | |
| 553 | + .dir > .content > ol, .dir > .content > ul, | |
| 554 | + .dir > .content > .markdown > ol, .dir > .content > .markdown > ul, | |
| 555 | + .dir > .content > .fossil-doc > ol, .dir > .content > .fossil-doc > ul, | |
| 556 | + .dir > .content > table, | |
| 557 | + .dir > .content > .markdown > table, | |
| 558 | + .dir > .content > .fossil-doc > table, | |
| 559 | + .doc > .content > p, | |
| 560 | + .doc > .content > .markdown > p, | |
| 561 | + .doc > .content > .fossil-doc > p, | |
| 562 | + .doc > .content > ol, .doc > .content > ul, | |
| 563 | + .doc > .content > .markdown > ol, .doc > .content > .markdown > ul, | |
| 564 | + .doc > .content > .fossil-doc > ol, .doc > .content > .fossil-doc > ul, | |
| 565 | + .doc > .content > table, | |
| 566 | + .doc > .content > .markdown > table, | |
| 567 | + .doc > .content > .fossil-doc > table, | |
| 568 | + .wiki > .content > p, | |
| 569 | + .wiki > .content > .markdown > p, | |
| 570 | + .wiki > .content > .fossil-doc > p, | |
| 571 | + .wiki > .content > ol, .wiki > .content > ul, | |
| 572 | + .wiki > .content > .markdown > ol, .wiki > .content > .markdown > ul, | |
| 573 | + .wiki > .content > .fossil-doc > ol, .wiki > .content > .fossil-doc > ul, | |
| 574 | + .wiki > .content > table, | |
| 575 | + .wiki > .content > .markdown > table, | |
| 576 | + .wiki > .content > .fossil-doc > table, | |
| 577 | + #fileedit-tab-preview-wrapper > p, | |
| 578 | + #fileedit-tab-preview-wrapper > ol, | |
| 579 | + #fileedit-tab-preview-wrapper > ul, | |
| 580 | + #fileedit-tab-preview-wrapper > table, | |
| 581 | + #fileedit-tab-preview-wrapper > .markdown > p, | |
| 582 | + #fileedit-tab-preview-wrapper > .markdown > ol, | |
| 583 | + #fileedit-tab-preview-wrapper > .markdown > ul, | |
| 584 | + #fileedit-tab-preview-wrapper > .markdown > table, | |
| 585 | + #wikiedit-tab-preview-wrapper > p, | |
| 586 | + #wikiedit-tab-preview-wrapper > ol, | |
| 587 | + #wikiedit-tab-preview-wrapper > ul, | |
| 588 | + #wikiedit-tab-preview-wrapper > table, | |
| 589 | + #wikiedit-tab-preview-wrapper > .markdown > p, | |
| 590 | + #wikiedit-tab-preview-wrapper > .markdown > ol, | |
| 591 | + #wikiedit-tab-preview-wrapper > .markdown > ul, | |
| 592 | + #wikiedit-tab-preview-wrapper > .markdown > table { | |
| 593 | + margin-left: 50pt; | |
| 594 | + margin-right: 50pt; | |
| 595 | + } | |
| 596 | + | |
| 597 | + /* Code blocks get extra indenting. We need a selector explosion | |
| 598 | + * equally powerful to the one above for inline <code> fragments and | |
| 599 | + * similar elements, for essentially the same reason: Fossil UI also | |
| 600 | + * uses <pre>, and we want to affect user content only. | |
| 601 | + * | |
| 602 | + * The equivalent Sass code is: | |
| 603 | + * | |
| 604 | + * .artifact, .dir, .doc, .wiki // doc types we target | |
| 605 | + * > .content // hands off header & footer | |
| 606 | + * @import 'pre-doc-margins.sass' | |
| 607 | + * | |
| 608 | + * #fileedit-tab-preview-wrapper, // include /fileedit previews | |
| 609 | + * #wikiedit-tab-preview-wrapper // ditto /wikiedit | |
| 610 | + * @import 'pre-doc-margins.sass' | |
| 611 | + * | |
| 612 | + * …where pre-doc-margins.sass contains the elements common to both: | |
| 613 | + * | |
| 614 | + * &, > .fossil-doc, > .markdown // wiki, HTML & MD doc types | |
| 615 | + * > pre // direct pre descendants only | |
| 616 | + * margin-left: 70pt; | |
| 617 | + * margin-right: 50pt; | |
| 618 | + * | |
| 619 | + * This is a technical overreach since /wiki & /wikiedit lack support | |
| 620 | + * for Fossil's HTML embedded doc markup capability, but we prefer to | |
| 621 | + * draw the /fileedit parallel in our Sass example over the dubious | |
| 622 | + * pleasure of being nit-picky on this point. Instead, we've chosen | |
| 623 | + * to back that overreach out by hand below. | |
| 624 | + */ | |
| 625 | + .artifact > .content > pre, | |
| 626 | + .artifact > .content > .fossil-doc > pre, | |
| 627 | + .artifact > .content > .markdown > pre, | |
| 628 | + .dir > .content > pre, | |
| 629 | + .dir > .content > .fossil-doc > pre, | |
| 630 | + .dir > .content > .markdown > pre, | |
| 631 | + .doc > .content > pre, | |
| 632 | + .doc > .content > .fossil-doc > pre, | |
| 633 | + .doc > .content > .markdown > pre, | |
| 634 | + .wiki > .content > pre, | |
| 635 | + .wiki > .content > .markdown > pre { | |
| 636 | + margin-left: 70pt; | |
| 637 | + margin-right: 50pt; | |
| 638 | + } | |
| 639 | + #fileedit-tab-preview-wrapper > pre, | |
| 640 | + #wikiedit-tab-preview-wrapper > pre, | |
| 641 | + #fileedit-tab-preview-wrapper > .fossil-doc > pre, | |
| 642 | + #fileedit-tab-preview-wrapper > .markdown > pre, | |
| 643 | + #wikiedit-tab-preview-wrapper > .markdown > pre { | |
| 644 | + margin-left: 70pt; | |
| 645 | + margin-right: 50pt; | |
| 646 | + } | |
| 647 | + | |
| 648 | + /* Fossil UI uses these, but in sufficiently constrained ways that we | |
| 649 | + * don't have to be nearly as careful to avoid an overreach. */ | |
| 650 | + .doc > .content h1, .artifact h1, .dir h1, .fileedit h1, .wiki h1 { margin-left: 10pt; } | |
| 651 | + .doc > .content h2, .artifact h2, .dir h2, .fileedit h2, .wiki h2 { margin-left: 20pt; } | |
| 652 | + .doc > .content h3, .artifact h3, .dir h3, .fileedit h3, .wiki h3 { margin-left: 30pt; } | |
| 653 | + .doc > .content h4, .artifact h4, .dir h4, .fileedit h4, .wiki h4 { margin-left: 40pt; } | |
| 654 | + .doc > .content h5, .artifact h5, .dir h5, .fileedit h5, .wiki h5 { margin-left: 50pt; } | |
| 655 | + .doc > .content hr, .artifact hr, .dir hr, .fileedit hr, .wiki hr { margin-left: 10pt; } | |
| 656 | + | |
| 657 | + /* Don't need to be nearly as careful with tags Fossil UI doesn't use. */ | |
| 658 | + .doc dd, .artifact dd, .dir dd, .fileedit dd, .wikiedit dd { margin-left: 30pt; margin-bottom: 1em; } | |
| 659 | + .doc dl, .artifact dl, .dir dl, .fileedit dl, .wikiedit dl { margin-left: 60pt; } | |
| 660 | + .doc dt, .artifact dt, .dir dt, .fileedit dt, .wikiedit dt { margin-left: 10pt; } | |
| 661 | + | |
| 662 | + /* Fossil UI doesn't use Pikchr at all (yet?) so we can be quite loose | |
| 663 | + * with these selectors. */ | |
| 664 | + .content .pikchr-wrapper { margin-left: 70pt; } | |
| 665 | + div.pikchr-wrapper.indent:not(.source) { | |
| 666 | + /* Selector naming scheme mismatch is intentional: it must match the | |
| 667 | + * way it's given in default.css exactly if it is to override it. */ | |
| 668 | + margin-left: 70pt; | |
| 669 | + margin-right: 50pt; | |
| 670 | + } | |
| 671 | + div.pikchr-wrapper.center:not(.source) { | |
| 672 | + margin-left: 0; | |
| 673 | + } | |
| 674 | + | |
| 675 | + /* Special treatment for backward compatibility. */ | |
| 676 | + .indent, /* clean alternative to misusing <blockquote> */ | |
| 677 | + .artifact > .content > blockquote:not(.file-content), | |
| 678 | + .dir > .content > blockquote, | |
| 679 | + .doc > .content > blockquote, | |
| 680 | + .fileedit > .content > blockquote, | |
| 681 | + .wiki > .content > blockquote { | |
| 682 | + /* We must apply extra indent relative to "p" since Fossil's wiki | |
| 683 | + * generator misuses the blockquote tag against HTML and MD norms | |
| 684 | + * to mean "indented paragraph." Skip it for file content retrieved | |
| 685 | + * by /dir URLs. */ | |
| 686 | + margin-left: 80pt; | |
| 687 | + } | |
| 688 | + .artifact > .content > .markdown > blockquote, | |
| 689 | + .dir > .content > .markdown > blockquote, | |
| 690 | + .doc > .content > .markdown > blockquote, | |
| 691 | + .fileedit > .content > .markdown > blockquote, | |
| 692 | + .wiki > .content > .markdown > blockquote { | |
| 693 | + /* Fossil MD didn't inherit that bug; its HTML generator emits | |
| 694 | + * blockquote tags only for _block quotes_! A moderate indent | |
| 695 | + * suffices due to the visual styling applied above. */ | |
| 696 | + margin-left: 60pt; | |
| 697 | + } | |
| 698 | + | |
| 699 | + /* Alternative to BLOCK.indent when wrapped in something that is | |
| 700 | + * itself indented. The value is the delta between p and blockquote | |
| 701 | + * above, expressed as padding instead of margin so it adds to the | |
| 702 | + * outer margin instead of forcing the browser into picking one. */ | |
| 703 | + .local-indent { | |
| 704 | + padding-left: 30pt; | |
| 705 | + } | |
| 281 | 706 | } |
| 282 | 707 |
| --- skins/default/css.txt | |
| +++ skins/default/css.txt | |
| @@ -1,16 +1,27 @@ | |
| 1 | /* Overall page style */ |
| 2 | |
| 3 | body { |
| 4 | margin: 0 auto; |
| 5 | background-color: white; |
| 6 | font-family: sans-serif; |
| 7 | font-size: 14pt; |
| 8 | } |
| 9 | |
| 10 | a { |
| 11 | color: #4183C4; |
| 12 | text-decoration: none; |
| 13 | } |
| 14 | a:hover { |
| 15 | color: #4183C4; |
| 16 | text-decoration: underline; |
| @@ -23,26 +34,28 @@ | |
| 23 | color: #4183C4; |
| 24 | float: left; |
| 25 | } |
| 26 | .title h1 { |
| 27 | display: inline; |
| 28 | } |
| 29 | .title h1:after { |
| 30 | content: " / "; |
| 31 | color: #777; |
| 32 | font-weight: normal; |
| 33 | } |
| 34 | .status { |
| 35 | float: right; |
| 36 | font-size: 0.7em; |
| 37 | } |
| 38 | |
| 39 | |
| 40 | /* Main menu and optional sub-menu */ |
| 41 | |
| 42 | .mainmenu { |
| 43 | font-size: 0.8em; |
| 44 | clear: both; |
| 45 | background: #eaeaea linear-gradient(#fafafa, #eaeaea) repeat-x; |
| 46 | border: 1px solid #eaeaea; |
| 47 | border-radius: 5px; |
| 48 | overflow-x: auto; |
| @@ -58,11 +71,11 @@ | |
| 58 | .mainmenu a.active, |
| 59 | .mainmenu a:hover { |
| 60 | color: #000; |
| 61 | border-bottom: 2px solid #D26911; |
| 62 | } |
| 63 | div#hbdrop { |
| 64 | background-color: white; |
| 65 | border: 1px solid black; |
| 66 | border-top: white; |
| 67 | border-radius: 0 0 0.5em 0.5em; |
| 68 | display: none; |
| @@ -73,11 +86,11 @@ | |
| 73 | position: absolute; |
| 74 | z-index: 20; /* just below mainmenu, but above timeline bubbles */ |
| 75 | } |
| 76 | |
| 77 | .submenu { |
| 78 | font-size: .7em; |
| 79 | padding: 10px; |
| 80 | border-bottom: 1px solid #ccc; |
| 81 | } |
| 82 | .submenu a, .submenu label { |
| 83 | padding: 10px 11px; |
| @@ -102,26 +115,18 @@ | |
| 102 | |
| 103 | |
| 104 | /* Main document area; elements common to most pages. */ |
| 105 | |
| 106 | .content { |
| 107 | padding-top: 10px; |
| 108 | font-size: 0.8em; |
| 109 | color: #444; |
| 110 | } |
| 111 | .content blockquote { |
| 112 | padding: 0 15px; |
| 113 | } |
| 114 | .content h1 { |
| 115 | font-size: 1.25em; |
| 116 | } |
| 117 | .content h2 { |
| 118 | font-size: 1.15em; |
| 119 | } |
| 120 | .content h3 { |
| 121 | font-size: 1.05em; |
| 122 | } |
| 123 | |
| 124 | .section { |
| 125 | font-size: 1em; |
| 126 | font-weight: bold; |
| 127 | background-color: #f5f5f5; |
| @@ -148,14 +153,14 @@ | |
| 148 | } |
| 149 | |
| 150 | |
| 151 | /* Page footer */ |
| 152 | |
| 153 | .footer { |
| 154 | border-top: 1px solid #ccc; |
| 155 | padding: 10px; |
| 156 | font-size: 0.7em; |
| 157 | margin-top: 10px; |
| 158 | color: #ccc; |
| 159 | } |
| 160 | |
| 161 | /* Forum */ |
| @@ -162,23 +167,201 @@ | |
| 162 | |
| 163 | .forum a:visited { |
| 164 | color: #6A7F94; |
| 165 | } |
| 166 | |
| 167 | .forum blockquote { |
| 168 | background-color: rgba(65, 131, 196, 0.1); |
| 169 | border-left: 3px solid #254769; |
| 170 | padding: .1em 1em; |
| 171 | } |
| 172 | |
| 173 | |
| 174 | /* Tickets */ |
| 175 | |
| 176 | table.report { |
| 177 | cursor: auto; |
| 178 | border-radius: 5px; |
| 179 | border: 1px solid #ccc; |
| 180 | margin: 1em 0; |
| 181 | } |
| 182 | .report td, .report th { |
| 183 | border: 0; |
| 184 | font-size: .8em; |
| @@ -224,15 +407,44 @@ | |
| 224 | |
| 225 | |
| 226 | /* Timeline */ |
| 227 | |
| 228 | span.timelineDetail { |
| 229 | font-size: 90%; |
| 230 | } |
| 231 | div.timelineDate { |
| 232 | font-weight: bold; |
| 233 | white-space: nowrap; |
| 234 | } |
| 235 | |
| 236 | |
| 237 | /* Miscellaneous UI elements */ |
| 238 | |
| @@ -247,14 +459,24 @@ | |
| 247 | /* Spacing for mobile */ |
| 248 | body { |
| 249 | padding-left: 4px; |
| 250 | padding-right: 4px; |
| 251 | } |
| 252 | .title { |
| 253 | padding-top: 0px; |
| 254 | padding-bottom: 0px; |
| 255 | } |
| 256 | .status {padding-top: 0px;} |
| 257 | .mainmenu a { |
| 258 | padding: 8px 10px; |
| 259 | } |
| 260 | .mainmenu { |
| @@ -269,13 +491,216 @@ | |
| 269 | } |
| 270 | .title { |
| 271 | padding-top: 10px; |
| 272 | padding-bottom: 10px; |
| 273 | } |
| 274 | .status {padding-top: 30px;} |
| 275 | .mainmenu a { |
| 276 | padding: 8px 20px; |
| 277 | } |
| 278 | .mainmenu { |
| 279 | padding: 10px; |
| 280 | } |
| 281 | } |
| 282 |
| --- skins/default/css.txt | |
| +++ skins/default/css.txt | |
| @@ -1,16 +1,27 @@ | |
| 1 | /* Overall page style; vi: filetype=css |
| 2 | */ |
| 3 | |
| 4 | body { |
| 5 | margin: 0 auto; |
| 6 | background-color: white; |
| 7 | font-family: sans-serif; |
| 8 | } |
| 9 | |
| 10 | a { |
| 11 | /* Unvisited links are a lightness-adjusted version of this skin's |
| 12 | * header blue, balancing contrast between the body text and the |
| 13 | * background in order to meet the goals specified by the WCAG 2 |
| 14 | * accessbility standard, earning us an "AA" grade according to |
| 15 | * the calculator result here: |
| 16 | * |
| 17 | * https://webaim.org/resources/linkcontrastchecker/?fcolor=2E2E2E&bcolor=FFFFFF&lcolor=3779BF |
| 18 | * |
| 19 | * It is for this same reason that our not-quite-black body text |
| 20 | * color is the shade of dark gray that it is. It can't be any |
| 21 | * lighter and still allow us to meet both targets. */ |
| 22 | color: #3779BF; |
| 23 | text-decoration: none; |
| 24 | } |
| 25 | a:hover { |
| 26 | color: #4183C4; |
| 27 | text-decoration: underline; |
| @@ -23,26 +34,28 @@ | |
| 34 | color: #4183C4; |
| 35 | float: left; |
| 36 | } |
| 37 | .title h1 { |
| 38 | display: inline; |
| 39 | font-size: 2.20em; |
| 40 | } |
| 41 | .status { |
| 42 | float: right; |
| 43 | font-size: 0.8em; |
| 44 | } |
| 45 | div.logo { |
| 46 | float: left; |
| 47 | padding-right: 10px; |
| 48 | } |
| 49 | div.logo img { |
| 50 | max-height: 2em; /* smaller than title to keep it above the baseline */ |
| 51 | } |
| 52 | |
| 53 | |
| 54 | /* Main menu and optional sub-menu */ |
| 55 | |
| 56 | .mainmenu { |
| 57 | clear: both; |
| 58 | background: #eaeaea linear-gradient(#fafafa, #eaeaea) repeat-x; |
| 59 | border: 1px solid #eaeaea; |
| 60 | border-radius: 5px; |
| 61 | overflow-x: auto; |
| @@ -58,11 +71,11 @@ | |
| 71 | .mainmenu a.active, |
| 72 | .mainmenu a:hover { |
| 73 | color: #000; |
| 74 | border-bottom: 2px solid #D26911; |
| 75 | } |
| 76 | nav#hbdrop { |
| 77 | background-color: white; |
| 78 | border: 1px solid black; |
| 79 | border-top: white; |
| 80 | border-radius: 0 0 0.5em 0.5em; |
| 81 | display: none; |
| @@ -73,11 +86,11 @@ | |
| 86 | position: absolute; |
| 87 | z-index: 20; /* just below mainmenu, but above timeline bubbles */ |
| 88 | } |
| 89 | |
| 90 | .submenu { |
| 91 | font-size: 0.8em; |
| 92 | padding: 10px; |
| 93 | border-bottom: 1px solid #ccc; |
| 94 | } |
| 95 | .submenu a, .submenu label { |
| 96 | padding: 10px 11px; |
| @@ -102,26 +115,18 @@ | |
| 115 | |
| 116 | |
| 117 | /* Main document area; elements common to most pages. */ |
| 118 | |
| 119 | .content { |
| 120 | padding: 1ex; |
| 121 | color: #2e2e2e; /* justified above in "WCAG 2" comment */ |
| 122 | } |
| 123 | .content h1 { font-size: 1.60em; color: #444; } |
| 124 | .content h2 { font-size: 1.45em; color: #444; } |
| 125 | .content h3 { font-size: 1.15em; color: #444; } |
| 126 | .content h4 { font-size: 1.05em; color: #444; } |
| 127 | .content h5 { font-size: 1.00em; color: #444; } |
| 128 | |
| 129 | .section { |
| 130 | font-size: 1em; |
| 131 | font-weight: bold; |
| 132 | background-color: #f5f5f5; |
| @@ -148,14 +153,14 @@ | |
| 153 | } |
| 154 | |
| 155 | |
| 156 | /* Page footer */ |
| 157 | |
| 158 | footer { |
| 159 | border-top: 1px solid #ccc; |
| 160 | padding: 10px; |
| 161 | font-size: 0.8em; |
| 162 | margin-top: 10px; |
| 163 | color: #ccc; |
| 164 | } |
| 165 | |
| 166 | /* Forum */ |
| @@ -162,23 +167,201 @@ | |
| 167 | |
| 168 | .forum a:visited { |
| 169 | color: #6A7F94; |
| 170 | } |
| 171 | |
| 172 | div.forumSel { |
| 173 | animation: 1s linear 0s sel-fade; |
| 174 | background-color: white; /* animation end state */ |
| 175 | border-left: 4px solid black; /* after-animation selection indicator */ |
| 176 | } |
| 177 | @keyframes sel-fade { |
| 178 | from { background-color: #cef; } |
| 179 | to { background-color: white; } |
| 180 | } |
| 181 | |
| 182 | .forum form input { |
| 183 | margin: 0.5em 0; |
| 184 | } |
| 185 | |
| 186 | |
| 187 | /* Markdown and Wiki-formatted pages: /wiki, /doc, /file... */ |
| 188 | |
| 189 | .markdown blockquote, p.blockquote, .sidebar { |
| 190 | /* Override default.css version with our accent colors. */ |
| 191 | background-color: rgba(65, 131, 196, 0.1); |
| 192 | border-left-color: #4183c4; |
| 193 | } |
| 194 | |
| 195 | /* Mark inline code fragments in the near-universal manner pioneered by |
| 196 | * Stack Overflow, then picked up by approximately everyone, including |
| 197 | * us, now. |
| 198 | * |
| 199 | * This combinatoric selector explosion results from a need to apply |
| 200 | * these stylings inside multiple page container types, multiplied by |
| 201 | * the surprisingly large number of tags HTML defines for semantically |
| 202 | * differentiated monospaced inline markup. If we do not target the |
| 203 | * elements we want to affect carefully, we'll end up overreaching, |
| 204 | * styling Fossil UI elements that use these tags for local purposes. |
| 205 | * |
| 206 | * HTML generated and emitted by Fossil UI does not always fall under |
| 207 | * the skin's generic rules; we must avoid intruding on its domain. |
| 208 | * Our limited intent here is to style user content only, where it is |
| 209 | * unreasonable to expect its author to take the time to hand-craft |
| 210 | * per-document styling. Contrast Fossil UI, which often does exactly |
| 211 | * that in order to get particular results. |
| 212 | * |
| 213 | * The equivalent Sass syntax is far more compact, thus clearer: |
| 214 | * |
| 215 | * .artifact, .dir, .doc, .wiki // the page types we target |
| 216 | * > .content // hands off header & footer |
| 217 | * &, > .fossil-doc, > .markdown // wiki, HTML & MD emb docs |
| 218 | * > p // inline elements only |
| 219 | * > code, > kbd, > samp, > tt, > var // monospaced tag types |
| 220 | * background-color: #eee // pale gray box that… |
| 221 | * padding: 0 4px // …extends around the sides |
| 222 | * |
| 223 | * We generated the CSS below by: |
| 224 | * |
| 225 | * $ sassc code.sass | sed -e 's/, /,\n/g' |
| 226 | * |
| 227 | * …then hand-cleansed it to make it _somewhat_ more understandable. |
| 228 | */ |
| 229 | .artifact > .content > p > code, |
| 230 | .artifact > .content > p > kbd, |
| 231 | .artifact > .content > p > samp, |
| 232 | .artifact > .content > p > tt, |
| 233 | .artifact > .content > p > var, |
| 234 | .artifact > .content > .fossil-doc > p > code, |
| 235 | .artifact > .content > .fossil-doc > p > kbd, |
| 236 | .artifact > .content > .fossil-doc > p > samp, |
| 237 | .artifact > .content > .fossil-doc > p > tt, |
| 238 | .artifact > .content > .fossil-doc > p > var, |
| 239 | .artifact > .content > .markdown > p > code, |
| 240 | .artifact > .content > .markdown > p > kbd, |
| 241 | .artifact > .content > .markdown > p > samp, |
| 242 | .artifact > .content > .markdown > p > tt, |
| 243 | .artifact > .content > .markdown > p > var, |
| 244 | .dir > .content > p > code, |
| 245 | .dir > .content > p > kbd, |
| 246 | .dir > .content > p > samp, |
| 247 | .dir > .content > p > tt, |
| 248 | .dir > .content > p > var, |
| 249 | .dir > .content > .fossil-doc > p > code, |
| 250 | .dir > .content > .fossil-doc > p > kbd, |
| 251 | .dir > .content > .fossil-doc > p > samp, |
| 252 | .dir > .content > .fossil-doc > p > tt, |
| 253 | .dir > .content > .fossil-doc > p > var, |
| 254 | .dir > .content > .markdown > p > code, |
| 255 | .dir > .content > .markdown > p > kbd, |
| 256 | .dir > .content > .markdown > p > samp, |
| 257 | .dir > .content > .markdown > p > tt, |
| 258 | .dir > .content > .markdown > p > var, |
| 259 | .doc > .content > p > code, |
| 260 | .doc > .content > p > kbd, |
| 261 | .doc > .content > p > samp, |
| 262 | .doc > .content > p > tt, |
| 263 | .doc > .content > p > var, |
| 264 | .doc > .content > .fossil-doc > p > code, |
| 265 | .doc > .content > .fossil-doc > p > kbd, |
| 266 | .doc > .content > .fossil-doc > p > samp, |
| 267 | .doc > .content > .fossil-doc > p > tt, |
| 268 | .doc > .content > .fossil-doc > p > var, |
| 269 | .doc > .content > .markdown > p > code, |
| 270 | .doc > .content > .markdown > p > kbd, |
| 271 | .doc > .content > .markdown > p > samp, |
| 272 | .doc > .content > .markdown > p > tt, |
| 273 | .doc > .content > .markdown > p > var, |
| 274 | .wiki > .content > p > code, |
| 275 | .wiki > .content > p > kbd, |
| 276 | .wiki > .content > p > samp, |
| 277 | .wiki > .content > p > tt, |
| 278 | .wiki > .content > p > var, |
| 279 | .wiki > .content > .fossil-doc > p > code, |
| 280 | .wiki > .content > .fossil-doc > p > kbd, |
| 281 | .wiki > .content > .fossil-doc > p > samp, |
| 282 | .wiki > .content > .fossil-doc > p > tt, |
| 283 | .wiki > .content > .fossil-doc > p > var, |
| 284 | .wiki > .content > .markdown > p > code, |
| 285 | .wiki > .content > .markdown > p > kbd, |
| 286 | .wiki > .content > .markdown > p > samp, |
| 287 | .wiki > .content > .markdown > p > tt, |
| 288 | .wiki > .content > .markdown > p > var { |
| 289 | background-color: #eee; |
| 290 | padding: 0 4px; |
| 291 | } |
| 292 | .content pre { |
| 293 | hyphens: none; |
| 294 | line-height: 1.25; |
| 295 | } |
| 296 | |
| 297 | .content .pikchr-wrapper { |
| 298 | /* Pikchr was developed with the assumption that it would be |
| 299 | * integrated into a Fossil repo using the old 0.9em body font |
| 300 | * size, which no longer obtians. This gives us a choice: |
| 301 | * |
| 302 | * 1. Change Pikchr to track this skin change, potentially breaking |
| 303 | * uses of alternate skins with differing default font sizes. |
| 304 | * 2. Restore the old default for Pikchr diagrams so the old |
| 305 | * assumptions continue to be valid. |
| 306 | * 3. Make everyone with custom skins set pikchr-scale=1.11 (1/0.9) |
| 307 | * in their skin's footer.txt to increase the diagram's relative |
| 308 | * size to compensate for the font size change. |
| 309 | * |
| 310 | * We choose #2 because it puts both adjustments in the same file. */ |
| 311 | font-size: 0.9em; |
| 312 | } |
| 313 | |
| 314 | .content ul li { |
| 315 | list-style-type: disc; |
| 316 | } |
| 317 | |
| 318 | .doc > .content table { |
| 319 | background-color: #f0f5f9; |
| 320 | border: 1px solid #a7c2dc; |
| 321 | border-radius: 0.5em; |
| 322 | border-spacing: 0; |
| 323 | padding: 6px; |
| 324 | } |
| 325 | .doc > .content th { |
| 326 | border-bottom: 1px solid #dee8f2; |
| 327 | padding-bottom: 4px; |
| 328 | padding-right: 6px; |
| 329 | text-align: left; |
| 330 | } |
| 331 | .doc > .content tr > th { |
| 332 | background-color: #dee8f0; |
| 333 | } |
| 334 | .doc > .content tr:nth-child(odd) { |
| 335 | background-color: #e0e8ee; |
| 336 | } |
| 337 | .doc > .content td { |
| 338 | padding-bottom: 4px; |
| 339 | padding-right: 6px; |
| 340 | text-align: left; |
| 341 | } |
| 342 | |
| 343 | /* Wiki adjustments */ |
| 344 | pre.verbatim { |
| 345 | /* keep code examples from crashing into sidebars, etc. */ |
| 346 | white-space: pre-wrap; |
| 347 | } |
| 348 | textarea.wikiedit { |
| 349 | /* Monospace fonts tend to have smaller x-heights; compensate. |
| 350 | * Can't do this generally because not all fonts have this problem. |
| 351 | * A textarea stands alone, whereas inline <code> has to work with |
| 352 | * the browser's choice of sans-serif proportional font. */ |
| 353 | font-size: 1.1em; |
| 354 | } |
| 355 | |
| 356 | |
| 357 | /* Tickets */ |
| 358 | |
| 359 | table.report { |
| 360 | cursor: auto; |
| 361 | border: 1px solid #ccc; |
| 362 | border-radius: 0.5em; |
| 363 | margin: 1em 0; |
| 364 | } |
| 365 | .report td, .report th { |
| 366 | border: 0; |
| 367 | font-size: .8em; |
| @@ -224,15 +407,44 @@ | |
| 407 | |
| 408 | |
| 409 | /* Timeline */ |
| 410 | |
| 411 | span.timelineDetail { |
| 412 | font-size: 90%; |
| 413 | } |
| 414 | div.timelineDate { |
| 415 | font-weight: bold; |
| 416 | white-space: nowrap; |
| 417 | } |
| 418 | |
| 419 | tr.timelineSelected, tr.timelineCurrent { |
| 420 | /* etienne/css.txt puts these styles on the whole row. We want them only |
| 421 | * on the comment/details cell within the table, not over the time |
| 422 | * and graph columns as well. */ |
| 423 | background-color: unset; |
| 424 | border: unset; |
| 425 | box-shadow: unset; |
| 426 | } |
| 427 | tr.timelineCurrent td.timelineModernCell, |
| 428 | tr.timelineCurrent td.timelineColumnarCell { |
| 429 | border: 1px dashed #446979; |
| 430 | border-radius: 1em; |
| 431 | } |
| 432 | tr.timelineSelected td.timelineModernCell, |
| 433 | tr.timelineSelected td.timelineColumnarCell { |
| 434 | background-color: #fbe8d5; |
| 435 | border-radius: 1em; |
| 436 | } |
| 437 | tr.timelineSecondary td.timelineModernCell, |
| 438 | tr.timelineSecondary td.timelineColumnarCell { |
| 439 | background-color: #d5e8fb; |
| 440 | } |
| 441 | span.timelineSelected { |
| 442 | background-color: #fbe8d5; |
| 443 | } |
| 444 | span.timelineSecondary { |
| 445 | background-color: #d5e8fb; |
| 446 | } |
| 447 | |
| 448 | |
| 449 | /* Miscellaneous UI elements */ |
| 450 | |
| @@ -247,14 +459,24 @@ | |
| 459 | /* Spacing for mobile */ |
| 460 | body { |
| 461 | padding-left: 4px; |
| 462 | padding-right: 4px; |
| 463 | } |
| 464 | .content { |
| 465 | font-size: 0.9em; |
| 466 | } |
| 467 | .title { |
| 468 | padding-top: 0px; |
| 469 | padding-bottom: 0px; |
| 470 | } |
| 471 | .title > .page-title { |
| 472 | display: none; /* use h1 in body area, below menu bar */ |
| 473 | } |
| 474 | h1.page-title { |
| 475 | font-size: 1.60em; /* match content > h1 */ |
| 476 | margin-bottom: 0; /* div.content top margin suffices */ |
| 477 | } |
| 478 | .status {padding-top: 0px;} |
| 479 | .mainmenu a { |
| 480 | padding: 8px 10px; |
| 481 | } |
| 482 | .mainmenu { |
| @@ -269,13 +491,216 @@ | |
| 491 | } |
| 492 | .title { |
| 493 | padding-top: 10px; |
| 494 | padding-bottom: 10px; |
| 495 | } |
| 496 | .title h1:after { |
| 497 | content: " / "; |
| 498 | color: #777; |
| 499 | font-weight: normal; |
| 500 | } |
| 501 | h1.page-title { |
| 502 | display: none; /* use h1 in title area, above menu bar */ |
| 503 | } |
| 504 | span.page-title { |
| 505 | font-size: 18px; |
| 506 | } |
| 507 | div.logo { |
| 508 | padding-top: 10px; |
| 509 | } |
| 510 | .status {padding-top: 30px;} |
| 511 | .mainmenu a { |
| 512 | padding: 8px 20px; |
| 513 | } |
| 514 | .mainmenu { |
| 515 | padding: 10px; |
| 516 | } |
| 517 | |
| 518 | /* Wide screens mean long lines. Add extra leading to give the eye a |
| 519 | * "gutter" to follow from the end of one to the start of the next. */ |
| 520 | .content dd, |
| 521 | .content dt, |
| 522 | .content div, |
| 523 | .content li, |
| 524 | .content p, |
| 525 | .content table { |
| 526 | line-height: 1.4em; |
| 527 | } |
| 528 | |
| 529 | /* This horror show has the same cause that informed our handling of |
| 530 | * <code> and friends above; see "combinatorial selector explosion." |
| 531 | * Without this careful targeting, we'd not only overreach into areas |
| 532 | * of Fossil UI where our meddling is not wanted, we would mistakenly |
| 533 | * apply double indents to nested formatting in MD forum posts, p |
| 534 | * within td tags, and more. |
| 535 | * |
| 536 | * Rather than give the equivalent Sass code here, see the SCSS file |
| 537 | * that the [Inskinerator](https://tangentsoft.com/inskinerator/) |
| 538 | * project ships as override/modern/media.scss. Rendering that |
| 539 | * through sassc gives substantially identical output, modulo the |
| 540 | * hand-polishing we've done here. */ |
| 541 | .artifact > .content > p, |
| 542 | .artifact > .content > .markdown > p, |
| 543 | .artifact > .content > .fossil-doc > p, |
| 544 | .artifact > .content > ol, .artifact > .content > ul, |
| 545 | .artifact > .content > .markdown > ol, .artifact > .content > .markdown > ul, |
| 546 | .artifact > .content > .fossil-doc > ol, .artifact > .content > .fossil-doc > ul, |
| 547 | .artifact > .content > table, |
| 548 | .artifact > .content > .markdown > table, |
| 549 | .artifact > .content > .fossil-doc > table, |
| 550 | .dir > .content > p, |
| 551 | .dir > .content > .markdown > p, |
| 552 | .dir > .content > .fossil-doc > p, |
| 553 | .dir > .content > ol, .dir > .content > ul, |
| 554 | .dir > .content > .markdown > ol, .dir > .content > .markdown > ul, |
| 555 | .dir > .content > .fossil-doc > ol, .dir > .content > .fossil-doc > ul, |
| 556 | .dir > .content > table, |
| 557 | .dir > .content > .markdown > table, |
| 558 | .dir > .content > .fossil-doc > table, |
| 559 | .doc > .content > p, |
| 560 | .doc > .content > .markdown > p, |
| 561 | .doc > .content > .fossil-doc > p, |
| 562 | .doc > .content > ol, .doc > .content > ul, |
| 563 | .doc > .content > .markdown > ol, .doc > .content > .markdown > ul, |
| 564 | .doc > .content > .fossil-doc > ol, .doc > .content > .fossil-doc > ul, |
| 565 | .doc > .content > table, |
| 566 | .doc > .content > .markdown > table, |
| 567 | .doc > .content > .fossil-doc > table, |
| 568 | .wiki > .content > p, |
| 569 | .wiki > .content > .markdown > p, |
| 570 | .wiki > .content > .fossil-doc > p, |
| 571 | .wiki > .content > ol, .wiki > .content > ul, |
| 572 | .wiki > .content > .markdown > ol, .wiki > .content > .markdown > ul, |
| 573 | .wiki > .content > .fossil-doc > ol, .wiki > .content > .fossil-doc > ul, |
| 574 | .wiki > .content > table, |
| 575 | .wiki > .content > .markdown > table, |
| 576 | .wiki > .content > .fossil-doc > table, |
| 577 | #fileedit-tab-preview-wrapper > p, |
| 578 | #fileedit-tab-preview-wrapper > ol, |
| 579 | #fileedit-tab-preview-wrapper > ul, |
| 580 | #fileedit-tab-preview-wrapper > table, |
| 581 | #fileedit-tab-preview-wrapper > .markdown > p, |
| 582 | #fileedit-tab-preview-wrapper > .markdown > ol, |
| 583 | #fileedit-tab-preview-wrapper > .markdown > ul, |
| 584 | #fileedit-tab-preview-wrapper > .markdown > table, |
| 585 | #wikiedit-tab-preview-wrapper > p, |
| 586 | #wikiedit-tab-preview-wrapper > ol, |
| 587 | #wikiedit-tab-preview-wrapper > ul, |
| 588 | #wikiedit-tab-preview-wrapper > table, |
| 589 | #wikiedit-tab-preview-wrapper > .markdown > p, |
| 590 | #wikiedit-tab-preview-wrapper > .markdown > ol, |
| 591 | #wikiedit-tab-preview-wrapper > .markdown > ul, |
| 592 | #wikiedit-tab-preview-wrapper > .markdown > table { |
| 593 | margin-left: 50pt; |
| 594 | margin-right: 50pt; |
| 595 | } |
| 596 | |
| 597 | /* Code blocks get extra indenting. We need a selector explosion |
| 598 | * equally powerful to the one above for inline <code> fragments and |
| 599 | * similar elements, for essentially the same reason: Fossil UI also |
| 600 | * uses <pre>, and we want to affect user content only. |
| 601 | * |
| 602 | * The equivalent Sass code is: |
| 603 | * |
| 604 | * .artifact, .dir, .doc, .wiki // doc types we target |
| 605 | * > .content // hands off header & footer |
| 606 | * @import 'pre-doc-margins.sass' |
| 607 | * |
| 608 | * #fileedit-tab-preview-wrapper, // include /fileedit previews |
| 609 | * #wikiedit-tab-preview-wrapper // ditto /wikiedit |
| 610 | * @import 'pre-doc-margins.sass' |
| 611 | * |
| 612 | * …where pre-doc-margins.sass contains the elements common to both: |
| 613 | * |
| 614 | * &, > .fossil-doc, > .markdown // wiki, HTML & MD doc types |
| 615 | * > pre // direct pre descendants only |
| 616 | * margin-left: 70pt; |
| 617 | * margin-right: 50pt; |
| 618 | * |
| 619 | * This is a technical overreach since /wiki & /wikiedit lack support |
| 620 | * for Fossil's HTML embedded doc markup capability, but we prefer to |
| 621 | * draw the /fileedit parallel in our Sass example over the dubious |
| 622 | * pleasure of being nit-picky on this point. Instead, we've chosen |
| 623 | * to back that overreach out by hand below. |
| 624 | */ |
| 625 | .artifact > .content > pre, |
| 626 | .artifact > .content > .fossil-doc > pre, |
| 627 | .artifact > .content > .markdown > pre, |
| 628 | .dir > .content > pre, |
| 629 | .dir > .content > .fossil-doc > pre, |
| 630 | .dir > .content > .markdown > pre, |
| 631 | .doc > .content > pre, |
| 632 | .doc > .content > .fossil-doc > pre, |
| 633 | .doc > .content > .markdown > pre, |
| 634 | .wiki > .content > pre, |
| 635 | .wiki > .content > .markdown > pre { |
| 636 | margin-left: 70pt; |
| 637 | margin-right: 50pt; |
| 638 | } |
| 639 | #fileedit-tab-preview-wrapper > pre, |
| 640 | #wikiedit-tab-preview-wrapper > pre, |
| 641 | #fileedit-tab-preview-wrapper > .fossil-doc > pre, |
| 642 | #fileedit-tab-preview-wrapper > .markdown > pre, |
| 643 | #wikiedit-tab-preview-wrapper > .markdown > pre { |
| 644 | margin-left: 70pt; |
| 645 | margin-right: 50pt; |
| 646 | } |
| 647 | |
| 648 | /* Fossil UI uses these, but in sufficiently constrained ways that we |
| 649 | * don't have to be nearly as careful to avoid an overreach. */ |
| 650 | .doc > .content h1, .artifact h1, .dir h1, .fileedit h1, .wiki h1 { margin-left: 10pt; } |
| 651 | .doc > .content h2, .artifact h2, .dir h2, .fileedit h2, .wiki h2 { margin-left: 20pt; } |
| 652 | .doc > .content h3, .artifact h3, .dir h3, .fileedit h3, .wiki h3 { margin-left: 30pt; } |
| 653 | .doc > .content h4, .artifact h4, .dir h4, .fileedit h4, .wiki h4 { margin-left: 40pt; } |
| 654 | .doc > .content h5, .artifact h5, .dir h5, .fileedit h5, .wiki h5 { margin-left: 50pt; } |
| 655 | .doc > .content hr, .artifact hr, .dir hr, .fileedit hr, .wiki hr { margin-left: 10pt; } |
| 656 | |
| 657 | /* Don't need to be nearly as careful with tags Fossil UI doesn't use. */ |
| 658 | .doc dd, .artifact dd, .dir dd, .fileedit dd, .wikiedit dd { margin-left: 30pt; margin-bottom: 1em; } |
| 659 | .doc dl, .artifact dl, .dir dl, .fileedit dl, .wikiedit dl { margin-left: 60pt; } |
| 660 | .doc dt, .artifact dt, .dir dt, .fileedit dt, .wikiedit dt { margin-left: 10pt; } |
| 661 | |
| 662 | /* Fossil UI doesn't use Pikchr at all (yet?) so we can be quite loose |
| 663 | * with these selectors. */ |
| 664 | .content .pikchr-wrapper { margin-left: 70pt; } |
| 665 | div.pikchr-wrapper.indent:not(.source) { |
| 666 | /* Selector naming scheme mismatch is intentional: it must match the |
| 667 | * way it's given in default.css exactly if it is to override it. */ |
| 668 | margin-left: 70pt; |
| 669 | margin-right: 50pt; |
| 670 | } |
| 671 | div.pikchr-wrapper.center:not(.source) { |
| 672 | margin-left: 0; |
| 673 | } |
| 674 | |
| 675 | /* Special treatment for backward compatibility. */ |
| 676 | .indent, /* clean alternative to misusing <blockquote> */ |
| 677 | .artifact > .content > blockquote:not(.file-content), |
| 678 | .dir > .content > blockquote, |
| 679 | .doc > .content > blockquote, |
| 680 | .fileedit > .content > blockquote, |
| 681 | .wiki > .content > blockquote { |
| 682 | /* We must apply extra indent relative to "p" since Fossil's wiki |
| 683 | * generator misuses the blockquote tag against HTML and MD norms |
| 684 | * to mean "indented paragraph." Skip it for file content retrieved |
| 685 | * by /dir URLs. */ |
| 686 | margin-left: 80pt; |
| 687 | } |
| 688 | .artifact > .content > .markdown > blockquote, |
| 689 | .dir > .content > .markdown > blockquote, |
| 690 | .doc > .content > .markdown > blockquote, |
| 691 | .fileedit > .content > .markdown > blockquote, |
| 692 | .wiki > .content > .markdown > blockquote { |
| 693 | /* Fossil MD didn't inherit that bug; its HTML generator emits |
| 694 | * blockquote tags only for _block quotes_! A moderate indent |
| 695 | * suffices due to the visual styling applied above. */ |
| 696 | margin-left: 60pt; |
| 697 | } |
| 698 | |
| 699 | /* Alternative to BLOCK.indent when wrapped in something that is |
| 700 | * itself indented. The value is the delta between p and blockquote |
| 701 | * above, expressed as padding instead of margin so it adds to the |
| 702 | * outer margin instead of forcing the browser into picking one. */ |
| 703 | .local-indent { |
| 704 | padding-left: 30pt; |
| 705 | } |
| 706 | } |
| 707 |
+2
-2
| --- skins/default/footer.txt | ||
| +++ skins/default/footer.txt | ||
| @@ -1,5 +1,5 @@ | ||
| 1 | -<div class="footer"> | |
| 1 | +<footer> | |
| 2 | 2 | This page was generated in about |
| 3 | 3 | <th1>puts [expr {([utime]+[stime]+1000)/1000*0.001}]</th1>s by |
| 4 | 4 | Fossil $release_version $manifest_version $manifest_date |
| 5 | -</div> | |
| 5 | +</footer> | |
| 6 | 6 |
| --- skins/default/footer.txt | |
| +++ skins/default/footer.txt | |
| @@ -1,5 +1,5 @@ | |
| 1 | <div class="footer"> |
| 2 | This page was generated in about |
| 3 | <th1>puts [expr {([utime]+[stime]+1000)/1000*0.001}]</th1>s by |
| 4 | Fossil $release_version $manifest_version $manifest_date |
| 5 | </div> |
| 6 |
| --- skins/default/footer.txt | |
| +++ skins/default/footer.txt | |
| @@ -1,5 +1,5 @@ | |
| 1 | <footer> |
| 2 | This page was generated in about |
| 3 | <th1>puts [expr {([utime]+[stime]+1000)/1000*0.001}]</th1>s by |
| 4 | Fossil $release_version $manifest_version $manifest_date |
| 5 | </footer> |
| 6 |
+44
-6
| --- skins/default/header.txt | ||
| +++ skins/default/header.txt | ||
| @@ -1,16 +1,53 @@ | ||
| 1 | -<div class="header"> | |
| 2 | - <div class="title"><h1>$<project_name></h1>$<title></div> | |
| 1 | +<header> | |
| 2 | + <div class="logo"> | |
| 3 | + <th1> | |
| 4 | + ## See skins/original/header.txt for commentary; not repeated here. | |
| 5 | + proc getLogoUrl { baseurl } { | |
| 6 | + set idx(first) [string first // $baseurl] | |
| 7 | + if {$idx(first) != -1} { | |
| 8 | + set idx(first+1) [expr {$idx(first) + 2}] | |
| 9 | + set idx(nextRange) [string range $baseurl $idx(first+1) end] | |
| 10 | + set idx(next) [string first / $idx(nextRange)] | |
| 11 | + if {$idx(next) != -1} { | |
| 12 | + set idx(next) [expr {$idx(next) + $idx(first+1)}] | |
| 13 | + set idx(next-1) [expr {$idx(next) - 1}] | |
| 14 | + set scheme [string range $baseurl 0 $idx(first)] | |
| 15 | + set host [string range $baseurl $idx(first+1) $idx(next-1)] | |
| 16 | + if {[string compare $scheme http:/] == 0} { | |
| 17 | + set scheme http:// | |
| 18 | + } else { | |
| 19 | + set scheme https:// | |
| 20 | + } | |
| 21 | + set logourl $scheme$host/ | |
| 22 | + } else { | |
| 23 | + set logourl $baseurl | |
| 24 | + } | |
| 25 | + } else { | |
| 26 | + set logourl $baseurl | |
| 27 | + } | |
| 28 | + return $logourl | |
| 29 | + } | |
| 30 | + set logourl [getLogoUrl $baseurl] | |
| 31 | + </th1> | |
| 32 | + <a href="$logourl"> | |
| 33 | + <img src="$logo_image_url" border="0" alt="$project_name"> | |
| 34 | + </a> | |
| 35 | + </div> | |
| 36 | + <div class="title"> | |
| 37 | + <h1>$<project_name></h1> | |
| 38 | + <span class="page-title">$<title></span> | |
| 39 | + </div> | |
| 3 | 40 | <div class="status"><th1> |
| 4 | 41 | if {[info exists login]} { |
| 5 | 42 | html "<a href='$home/login'>$login</a>\n" |
| 6 | 43 | } else { |
| 7 | 44 | html "<a href='$home/login'>Login</a>\n" |
| 8 | 45 | } |
| 9 | 46 | </th1></div> |
| 10 | -</div> | |
| 11 | -<div class="mainmenu"> | |
| 47 | +</header> | |
| 48 | +<nav class="mainmenu" title="Main Menu"> | |
| 12 | 49 | <th1> |
| 13 | 50 | html "<a id='hbbtn' href='$home/sitemap' aria-label='Site Map'>☰</a>" |
| 14 | 51 | builtin_request_js hbmenu.js |
| 15 | 52 | foreach {name url expr class} $mainmenu { |
| 16 | 53 | if {![capexpr $expr]} continue |
| @@ -20,7 +57,8 @@ | ||
| 20 | 57 | } |
| 21 | 58 | set url $home$url |
| 22 | 59 | } |
| 23 | 60 | html "<a href='$url' class='$class'>$name</a>\n" |
| 24 | 61 | } |
| 25 | -</th1></div> | |
| 26 | -<div id='hbdrop'></div> | |
| 62 | +</th1></nav> | |
| 63 | +<nav id="hbdrop" title="sitemap"></nav> | |
| 64 | +<h1 class="page-title">$<title></h1> | |
| 27 | 65 | |
| 28 | 66 | ADDED skins/etienne/README.md |
| 29 | 67 | ADDED skins/etienne/css.txt |
| 30 | 68 | ADDED skins/etienne/details.txt |
| 31 | 69 | ADDED skins/etienne/footer.txt |
| 32 | 70 | ADDED skins/etienne/header.txt |
| --- skins/default/header.txt | |
| +++ skins/default/header.txt | |
| @@ -1,16 +1,53 @@ | |
| 1 | <div class="header"> |
| 2 | <div class="title"><h1>$<project_name></h1>$<title></div> |
| 3 | <div class="status"><th1> |
| 4 | if {[info exists login]} { |
| 5 | html "<a href='$home/login'>$login</a>\n" |
| 6 | } else { |
| 7 | html "<a href='$home/login'>Login</a>\n" |
| 8 | } |
| 9 | </th1></div> |
| 10 | </div> |
| 11 | <div class="mainmenu"> |
| 12 | <th1> |
| 13 | html "<a id='hbbtn' href='$home/sitemap' aria-label='Site Map'>☰</a>" |
| 14 | builtin_request_js hbmenu.js |
| 15 | foreach {name url expr class} $mainmenu { |
| 16 | if {![capexpr $expr]} continue |
| @@ -20,7 +57,8 @@ | |
| 20 | } |
| 21 | set url $home$url |
| 22 | } |
| 23 | html "<a href='$url' class='$class'>$name</a>\n" |
| 24 | } |
| 25 | </th1></div> |
| 26 | <div id='hbdrop'></div> |
| 27 | |
| 28 | DDED skins/etienne/README.md |
| 29 | DDED skins/etienne/css.txt |
| 30 | DDED skins/etienne/details.txt |
| 31 | DDED skins/etienne/footer.txt |
| 32 | DDED skins/etienne/header.txt |
| --- skins/default/header.txt | |
| +++ skins/default/header.txt | |
| @@ -1,16 +1,53 @@ | |
| 1 | <header> |
| 2 | <div class="logo"> |
| 3 | <th1> |
| 4 | ## See skins/original/header.txt for commentary; not repeated here. |
| 5 | proc getLogoUrl { baseurl } { |
| 6 | set idx(first) [string first // $baseurl] |
| 7 | if {$idx(first) != -1} { |
| 8 | set idx(first+1) [expr {$idx(first) + 2}] |
| 9 | set idx(nextRange) [string range $baseurl $idx(first+1) end] |
| 10 | set idx(next) [string first / $idx(nextRange)] |
| 11 | if {$idx(next) != -1} { |
| 12 | set idx(next) [expr {$idx(next) + $idx(first+1)}] |
| 13 | set idx(next-1) [expr {$idx(next) - 1}] |
| 14 | set scheme [string range $baseurl 0 $idx(first)] |
| 15 | set host [string range $baseurl $idx(first+1) $idx(next-1)] |
| 16 | if {[string compare $scheme http:/] == 0} { |
| 17 | set scheme http:// |
| 18 | } else { |
| 19 | set scheme https:// |
| 20 | } |
| 21 | set logourl $scheme$host/ |
| 22 | } else { |
| 23 | set logourl $baseurl |
| 24 | } |
| 25 | } else { |
| 26 | set logourl $baseurl |
| 27 | } |
| 28 | return $logourl |
| 29 | } |
| 30 | set logourl [getLogoUrl $baseurl] |
| 31 | </th1> |
| 32 | <a href="$logourl"> |
| 33 | <img src="$logo_image_url" border="0" alt="$project_name"> |
| 34 | </a> |
| 35 | </div> |
| 36 | <div class="title"> |
| 37 | <h1>$<project_name></h1> |
| 38 | <span class="page-title">$<title></span> |
| 39 | </div> |
| 40 | <div class="status"><th1> |
| 41 | if {[info exists login]} { |
| 42 | html "<a href='$home/login'>$login</a>\n" |
| 43 | } else { |
| 44 | html "<a href='$home/login'>Login</a>\n" |
| 45 | } |
| 46 | </th1></div> |
| 47 | </header> |
| 48 | <nav class="mainmenu" title="Main Menu"> |
| 49 | <th1> |
| 50 | html "<a id='hbbtn' href='$home/sitemap' aria-label='Site Map'>☰</a>" |
| 51 | builtin_request_js hbmenu.js |
| 52 | foreach {name url expr class} $mainmenu { |
| 53 | if {![capexpr $expr]} continue |
| @@ -20,7 +57,8 @@ | |
| 57 | } |
| 58 | set url $home$url |
| 59 | } |
| 60 | html "<a href='$url' class='$class'>$name</a>\n" |
| 61 | } |
| 62 | </th1></nav> |
| 63 | <nav id="hbdrop" title="sitemap"></nav> |
| 64 | <h1 class="page-title">$<title></h1> |
| 65 | |
| 66 | DDED skins/etienne/README.md |
| 67 | DDED skins/etienne/css.txt |
| 68 | DDED skins/etienne/details.txt |
| 69 | DDED skins/etienne/footer.txt |
| 70 | DDED skins/etienne/header.txt |
+14
| --- a/skins/etienne/README.md | ||
| +++ b/skins/etienne/README.md | ||
| @@ -0,0 +1,14 @@ | ||
| 1 | +This skin was contributed by Étienne Deparis. | |
| 2 | + | |
| 3 | +It was promoted to the default from 2015-03-14 until February 2024, when | |
| 4 | +it was forked into this location for use by those who do not want the | |
| 5 | +large number of changes merged into trunk at that time. Even if you | |
| 6 | +agree with us that the changes improve readability, you may prefer to | |
| 7 | +pack more information onto the screen at the expense of readability. | |
| 8 | +Other reasons to choose this fork are to migrate custom skin changes to | |
| 9 | +work atop the new base, or to make a comparative design evaluation. | |
| 10 | + | |
| 11 | +A bare minimum of changes have been made to this fork, primarily to | |
| 12 | +allow this skin to render the Fossil documentation in a readable | |
| 13 | +fashion. The intent is that you be able to toggle between these two | |
| 14 | +skins at will. |
| --- a/skins/etienne/README.md | |
| +++ b/skins/etienne/README.md | |
| @@ -0,0 +1,14 @@ | |
| --- a/skins/etienne/README.md | |
| +++ b/skins/etienne/README.md | |
| @@ -0,0 +1,14 @@ | |
| 1 | This skin was contributed by Étienne Deparis. |
| 2 | |
| 3 | It was promoted to the default from 2015-03-14 until February 2024, when |
| 4 | it was forked into this location for use by those who do not want the |
| 5 | large number of changes merged into trunk at that time. Even if you |
| 6 | agree with us that the changes improve readability, you may prefer to |
| 7 | pack more information onto the screen at the expense of readability. |
| 8 | Other reasons to choose this fork are to migrate custom skin changes to |
| 9 | work atop the new base, or to make a comparative design evaluation. |
| 10 | |
| 11 | A bare minimum of changes have been made to this fork, primarily to |
| 12 | allow this skin to render the Fossil documentation in a readable |
| 13 | fashion. The intent is that you be able to toggle between these two |
| 14 | skins at will. |
+201
| --- a/skins/etienne/css.txt | ||
| +++ b/skins/etienne/css.txt | ||
| @@ -0,0 +1,201 @@ | ||
| 1 | +/* Overall page style; vi: filetype=css | |
| 2 | + */ | |
| 3 | + | |
| 4 | +body { | |
| 5 | + margin: 0 auto; | |
| 6 | + background-color: white; | |
| 7 | + font-family: sans-serif; | |
| 8 | + font-size: 14pt; | |
| 9 | +} | |
| 10 | + | |
| 11 | +a { | |
| 12 | + color: #4183C4; | |
| 13 | + text-decoration: none; | |
| 14 | +} | |
| 15 | +a:hover { | |
| 16 | + color: #4183C4; | |
| 17 | + text-decoration: underline; | |
| 18 | +} | |
| 19 | + | |
| 20 | + | |
| 21 | +/* Page title, above menu bars */ | |
| 22 | + | |
| 23 | +.title { | |
| 24 | + color: #4183C4; | |
| 25 | + float: left; | |
| 26 | +} | |
| 27 | +.title h1 { | |
| 28 | + display: inline; | |
| 29 | +} | |
| 30 | +.title h1:after { | |
| 31 | + content: " / "; | |
| 32 | + color: #777; | |
| 33 | + font-weight: normal; | |
| 34 | +} | |
| 35 | +.status { | |
| 36 | + float: right; | |
| 37 | + font-size: 0.7em; | |
| 38 | +} | |
| 39 | + | |
| 40 | + | |
| 41 | +/* Main menu and optional sub-menu */ | |
| 42 | + | |
| 43 | +.mainmenu { | |
| 44 | + font-size: 0.8em; | |
| 45 | + clear: both; | |
| 46 | + background: #eaeaea linear-gradient(#fafafa, #eaeaea) repeat-x; | |
| 47 | + border: 1px solid #eaeaea; | |
| 48 | + border-radius: 5px; | |
| 49 | + overflow-x: auto; | |
| 50 | + overflow-y: hidden; | |
| 51 | + white-space: nowrap; | |
| 52 | + z-index: 21; /* just above hbdrop */ | |
| 53 | +} | |
| 54 | +.mainmenu a { | |
| 55 | + text-decoration: none; | |
| 56 | + color: #777; | |
| 57 | + border-right: 1px solid #eaeaea; | |
| 58 | +} | |
| 59 | +.mainmenu a.active, | |
| 60 | +.mainmenu a:hover { | |
| 61 | + color: #000; | |
| 62 | + border-bottom: 2px solid #D26911; | |
| 63 | +} | |
| 64 | +div#hbdrop { | |
| 65 | + background-color: white; | |
| 66 | + border: 1px solid black; | |
| 67 | + border-top: white; | |
| 68 | + border-radius: 0 0 0.5em 0.5em; | |
| 69 | + display: none; | |
| 70 | + font-size: 80%; | |
| 71 | + left: 2em; | |
| 72 | + width: 90%; | |
| 73 | + padding-right: 1em; | |
| 74 | + position: absolute; | |
| 75 | + z-index: 20; /* just below mainmenu, but above timeline bubbles */ | |
| 76 | +} | |
| 77 | + | |
| 78 | +.submenu { | |
| 79 | + font-size: .7em; | |
| 80 | + padding: 10px; | |
| 81 | + border-bottom: 1px solid #ccc; | |
| 82 | +} | |
| 83 | +.submenu a, .submenu label { | |
| 84 | + padding: 10px 11px; | |
| 85 | + text-decoration: none; | |
| 86 | + color: #777; | |
| 87 | +} | |
| 88 | +.submenu label { | |
| 89 | + white-space: nowrap; | |
| 90 | +} | |
| 91 | +.submenu a:hover, .submenu label:hover { | |
| 92 | + padding: 6px 10px; | |
| 93 | + border: 1px solid #ccc; | |
| 94 | + border-radius: 5px; | |
| 95 | + color: #000; | |
| 96 | +} | |
| 97 | +span.submenuctrl, span.submenuctrl input, select.submenuctrl { | |
| 98 | + color: #777; | |
| 99 | +} | |
| 100 | +span.submenuctrl { | |
| 101 | + white-space: nowrap; | |
| 102 | +} | |
| 103 | + | |
| 104 | + | |
| 105 | +/* Main document area; elements common to most pages. */ | |
| 106 | + | |
| 107 | +.content { | |
| 108 | + padding-top: 10px; | |
| 109 | + font-size: 0.8em; | |
| 110 | + color: #444; | |
| 111 | +} | |
| 112 | +.content blockquote { | |
| 113 | + padding: 0 15px; | |
| 114 | +} | |
| 115 | +.content h1 { | |
| 116 | + font-size: 1.25em; | |
| 117 | +} | |
| 118 | +.content h2 { | |
| 119 | + font-size: 1.15em; | |
| 120 | +} | |
| 121 | +.content h3 { | |
| 122 | + font-size: 1.05em; | |
| 123 | +} | |
| 124 | + | |
| 125 | +.section { | |
| 126 | + font-size: 1em; | |
| 127 | + font-weight: bold; | |
| 128 | + background-color: #f5f5f5; | |
| 129 | + border: 1px solid #d8d8d8; | |
| 130 | + border-radius: 3px 3px 0 0; | |
| 131 | + padding: 9px 10px 10px; | |
| 132 | + margin: 10px 0; | |
| 133 | +} | |
| 134 | +.sectionmenu { | |
| 135 | + border: 1px solid #d8d8d8; | |
| 136 | + border-radius: 0 0 3px 3px; | |
| 137 | + border-top: 0; | |
| 138 | + margin-top: -10px; | |
| 139 | + margin-bottom: 10px; | |
| 140 | + padding: 10px; | |
| 141 | +} | |
| 142 | +.sectionmenu a { | |
| 143 | + display: inline-block; | |
| 144 | + margin-right: 1em; | |
| 145 | +} | |
| 146 | + | |
| 147 | +hr { | |
| 148 | + color: #eee; | |
| 149 | +} | |
| 150 | + | |
| 151 | + | |
| 152 | +/* Page footer */ | |
| 153 | + | |
| 154 | +.dden; | |
| 155 | + white-space: nowrap; | |
| 156 | + z-index: 21; /* just above hbdrop */ | |
| 157 | +} | |
| 158 | +.mainmenu a { | |
| 159 | + text-decoration: none; | |
| 160 | + color: #777; | |
| 161 | + border-right: 1px solid #eaeaea; | |
| 162 | +} | |
| 163 | +.mainmenu a.active, | |
| 164 | +.mainmenu a:hover { | |
| 165 | + color: #000; | |
| 166 | + border-bottom: 2px solid #D26911; | |
| 167 | +} | |
| 168 | +nav#hbdrop { | |
| 169 | + background-color: white; | |
| 170 | + border: 1px solid black; | |
| 171 | + border-top: white; | |
| 172 | + border-radius: 0 0 0.5em 0.5em; | |
| 173 | + display: none; | |
| 174 | + font-size: 80%; | |
| 175 | + left: 2em; | |
| 176 | + width: 90%; | |
| 177 | + padding-right: 1em; | |
| 178 | + position: absolute; | |
| 179 | + z-index: 20; /* just below mainmenu, but above timeline bubbles */ | |
| 180 | +} | |
| 181 | + | |
| 182 | +.submenu { | |
| 183 | + font-size: .7em; | |
| 184 | + padding: 10px; | |
| 185 | + border-bottom: 1px solid #ccc; | |
| 186 | +} | |
| 187 | +.submenu a, .submenu label { | |
| 188 | + padding: 10px 11px; | |
| 189 | + text-decoration: none; | |
| 190 | + color: #777; | |
| 191 | +} | |
| 192 | +.submenu label { | |
| 193 | + white-space: nowrap; | |
| 194 | +} | |
| 195 | +.submenu a:hover, .submenu label:hover { | |
| 196 | + padding: 6px 10px; | |
| 197 | + border: 1px solid #ccc; | |
| 198 | + border-radius: 5px; | |
| 199 | + color: #000; | |
| 200 | +} | |
| 201 | +span.submenuct |
| --- a/skins/etienne/css.txt | |
| +++ b/skins/etienne/css.txt | |
| @@ -0,0 +1,201 @@ | |
| --- a/skins/etienne/css.txt | |
| +++ b/skins/etienne/css.txt | |
| @@ -0,0 +1,201 @@ | |
| 1 | /* Overall page style; vi: filetype=css |
| 2 | */ |
| 3 | |
| 4 | body { |
| 5 | margin: 0 auto; |
| 6 | background-color: white; |
| 7 | font-family: sans-serif; |
| 8 | font-size: 14pt; |
| 9 | } |
| 10 | |
| 11 | a { |
| 12 | color: #4183C4; |
| 13 | text-decoration: none; |
| 14 | } |
| 15 | a:hover { |
| 16 | color: #4183C4; |
| 17 | text-decoration: underline; |
| 18 | } |
| 19 | |
| 20 | |
| 21 | /* Page title, above menu bars */ |
| 22 | |
| 23 | .title { |
| 24 | color: #4183C4; |
| 25 | float: left; |
| 26 | } |
| 27 | .title h1 { |
| 28 | display: inline; |
| 29 | } |
| 30 | .title h1:after { |
| 31 | content: " / "; |
| 32 | color: #777; |
| 33 | font-weight: normal; |
| 34 | } |
| 35 | .status { |
| 36 | float: right; |
| 37 | font-size: 0.7em; |
| 38 | } |
| 39 | |
| 40 | |
| 41 | /* Main menu and optional sub-menu */ |
| 42 | |
| 43 | .mainmenu { |
| 44 | font-size: 0.8em; |
| 45 | clear: both; |
| 46 | background: #eaeaea linear-gradient(#fafafa, #eaeaea) repeat-x; |
| 47 | border: 1px solid #eaeaea; |
| 48 | border-radius: 5px; |
| 49 | overflow-x: auto; |
| 50 | overflow-y: hidden; |
| 51 | white-space: nowrap; |
| 52 | z-index: 21; /* just above hbdrop */ |
| 53 | } |
| 54 | .mainmenu a { |
| 55 | text-decoration: none; |
| 56 | color: #777; |
| 57 | border-right: 1px solid #eaeaea; |
| 58 | } |
| 59 | .mainmenu a.active, |
| 60 | .mainmenu a:hover { |
| 61 | color: #000; |
| 62 | border-bottom: 2px solid #D26911; |
| 63 | } |
| 64 | div#hbdrop { |
| 65 | background-color: white; |
| 66 | border: 1px solid black; |
| 67 | border-top: white; |
| 68 | border-radius: 0 0 0.5em 0.5em; |
| 69 | display: none; |
| 70 | font-size: 80%; |
| 71 | left: 2em; |
| 72 | width: 90%; |
| 73 | padding-right: 1em; |
| 74 | position: absolute; |
| 75 | z-index: 20; /* just below mainmenu, but above timeline bubbles */ |
| 76 | } |
| 77 | |
| 78 | .submenu { |
| 79 | font-size: .7em; |
| 80 | padding: 10px; |
| 81 | border-bottom: 1px solid #ccc; |
| 82 | } |
| 83 | .submenu a, .submenu label { |
| 84 | padding: 10px 11px; |
| 85 | text-decoration: none; |
| 86 | color: #777; |
| 87 | } |
| 88 | .submenu label { |
| 89 | white-space: nowrap; |
| 90 | } |
| 91 | .submenu a:hover, .submenu label:hover { |
| 92 | padding: 6px 10px; |
| 93 | border: 1px solid #ccc; |
| 94 | border-radius: 5px; |
| 95 | color: #000; |
| 96 | } |
| 97 | span.submenuctrl, span.submenuctrl input, select.submenuctrl { |
| 98 | color: #777; |
| 99 | } |
| 100 | span.submenuctrl { |
| 101 | white-space: nowrap; |
| 102 | } |
| 103 | |
| 104 | |
| 105 | /* Main document area; elements common to most pages. */ |
| 106 | |
| 107 | .content { |
| 108 | padding-top: 10px; |
| 109 | font-size: 0.8em; |
| 110 | color: #444; |
| 111 | } |
| 112 | .content blockquote { |
| 113 | padding: 0 15px; |
| 114 | } |
| 115 | .content h1 { |
| 116 | font-size: 1.25em; |
| 117 | } |
| 118 | .content h2 { |
| 119 | font-size: 1.15em; |
| 120 | } |
| 121 | .content h3 { |
| 122 | font-size: 1.05em; |
| 123 | } |
| 124 | |
| 125 | .section { |
| 126 | font-size: 1em; |
| 127 | font-weight: bold; |
| 128 | background-color: #f5f5f5; |
| 129 | border: 1px solid #d8d8d8; |
| 130 | border-radius: 3px 3px 0 0; |
| 131 | padding: 9px 10px 10px; |
| 132 | margin: 10px 0; |
| 133 | } |
| 134 | .sectionmenu { |
| 135 | border: 1px solid #d8d8d8; |
| 136 | border-radius: 0 0 3px 3px; |
| 137 | border-top: 0; |
| 138 | margin-top: -10px; |
| 139 | margin-bottom: 10px; |
| 140 | padding: 10px; |
| 141 | } |
| 142 | .sectionmenu a { |
| 143 | display: inline-block; |
| 144 | margin-right: 1em; |
| 145 | } |
| 146 | |
| 147 | hr { |
| 148 | color: #eee; |
| 149 | } |
| 150 | |
| 151 | |
| 152 | /* Page footer */ |
| 153 | |
| 154 | .dden; |
| 155 | white-space: nowrap; |
| 156 | z-index: 21; /* just above hbdrop */ |
| 157 | } |
| 158 | .mainmenu a { |
| 159 | text-decoration: none; |
| 160 | color: #777; |
| 161 | border-right: 1px solid #eaeaea; |
| 162 | } |
| 163 | .mainmenu a.active, |
| 164 | .mainmenu a:hover { |
| 165 | color: #000; |
| 166 | border-bottom: 2px solid #D26911; |
| 167 | } |
| 168 | nav#hbdrop { |
| 169 | background-color: white; |
| 170 | border: 1px solid black; |
| 171 | border-top: white; |
| 172 | border-radius: 0 0 0.5em 0.5em; |
| 173 | display: none; |
| 174 | font-size: 80%; |
| 175 | left: 2em; |
| 176 | width: 90%; |
| 177 | padding-right: 1em; |
| 178 | position: absolute; |
| 179 | z-index: 20; /* just below mainmenu, but above timeline bubbles */ |
| 180 | } |
| 181 | |
| 182 | .submenu { |
| 183 | font-size: .7em; |
| 184 | padding: 10px; |
| 185 | border-bottom: 1px solid #ccc; |
| 186 | } |
| 187 | .submenu a, .submenu label { |
| 188 | padding: 10px 11px; |
| 189 | text-decoration: none; |
| 190 | color: #777; |
| 191 | } |
| 192 | .submenu label { |
| 193 | white-space: nowrap; |
| 194 | } |
| 195 | .submenu a:hover, .submenu label:hover { |
| 196 | padding: 6px 10px; |
| 197 | border: 1px solid #ccc; |
| 198 | border-radius: 5px; |
| 199 | color: #000; |
| 200 | } |
| 201 | span.submenuct |
| --- a/skins/etienne/details.txt | ||
| +++ b/skins/etienne/details.txt | ||
| @@ -0,0 +1,3 @@ | ||
| 1 | +timeline-arrowheads: 1 | |
| 2 | +t1 | |
| 3 | +timeline-color-graph-lines: 1 |
| --- a/skins/etienne/details.txt | |
| +++ b/skins/etienne/details.txt | |
| @@ -0,0 +1,3 @@ | |
| --- a/skins/etienne/details.txt | |
| +++ b/skins/etienne/details.txt | |
| @@ -0,0 +1,3 @@ | |
| 1 | timeline-arrowheads: 1 |
| 2 | t1 |
| 3 | timeline-color-graph-lines: 1 |
| --- a/skins/etienne/footer.txt | ||
| +++ b/skins/etienne/footer.txt | ||
| @@ -0,0 +1,4 @@ | ||
| 1 | +<div class="footer"> | |
| 2 | +This page was generated in about | |
| 3 | +<th1>puts [expr {([utime]+[stime]+1000)/1000*0.001}]</th1>s by | |
| 4 | +Fossil $release_version $manifest_ver |
| --- a/skins/etienne/footer.txt | |
| +++ b/skins/etienne/footer.txt | |
| @@ -0,0 +1,4 @@ | |
| --- a/skins/etienne/footer.txt | |
| +++ b/skins/etienne/footer.txt | |
| @@ -0,0 +1,4 @@ | |
| 1 | <div class="footer"> |
| 2 | This page was generated in about |
| 3 | <th1>puts [expr {([utime]+[stime]+1000)/1000*0.001}]</th1>s by |
| 4 | Fossil $release_version $manifest_ver |
+28
| --- a/skins/etienne/header.txt | ||
| +++ b/skins/etienne/header.txt | ||
| @@ -0,0 +1,28 @@ | ||
| 1 | +<div class="header"ect_name"> | |
| 2 | + </a> | |
| 3 | + <<h1>$<project_name></h1>$<title>us"><th1> | |
| 4 | + if {[info exists login]} { | |
| 5 | + \n" | |
| 6 | + } else { | |
| 7 | + } else { | |
| 8 | +/a title='Logout h$login</a>\n" | |
| 9 | + } else { | |
| 10 | +/a>\n" | |
| 11 | + } els} | |
| 12 | + </th1>a>\n" | |
| 13 | + div> | |
| 14 | +<div class="mainmbtn' href='$home/sitemap' aria-labelxpr $expr]} continue | |
| 15 | + if {[string match /* $url]} { | |
| 16 | + if {[string match $url\[/?#\]*set class "active $class" | |
| 17 | + } | |
| 18 | + set url $home$url | |
| 19 | + } | |
| 20 | +a>\n" | |
| 21 | + } else } | |
| 22 | + html "<a href='$url' c} | |
| 23 | +</th1>name</a>\n" | |
| 24 | + } | |
| 25 | + </thtitle="sitemap"></nav> | |
| 26 | +<h1 class='hbdrop' title="Sitemap"></nav> | |
| 27 | +div> | |
| 28 | +<div id='hbdrop'></div> |
| --- a/skins/etienne/header.txt | |
| +++ b/skins/etienne/header.txt | |
| @@ -0,0 +1,28 @@ | |
| --- a/skins/etienne/header.txt | |
| +++ b/skins/etienne/header.txt | |
| @@ -0,0 +1,28 @@ | |
| 1 | <div class="header"ect_name"> |
| 2 | </a> |
| 3 | <<h1>$<project_name></h1>$<title>us"><th1> |
| 4 | if {[info exists login]} { |
| 5 | \n" |
| 6 | } else { |
| 7 | } else { |
| 8 | /a title='Logout h$login</a>\n" |
| 9 | } else { |
| 10 | /a>\n" |
| 11 | } els} |
| 12 | </th1>a>\n" |
| 13 | div> |
| 14 | <div class="mainmbtn' href='$home/sitemap' aria-labelxpr $expr]} continue |
| 15 | if {[string match /* $url]} { |
| 16 | if {[string match $url\[/?#\]*set class "active $class" |
| 17 | } |
| 18 | set url $home$url |
| 19 | } |
| 20 | a>\n" |
| 21 | } else } |
| 22 | html "<a href='$url' c} |
| 23 | </th1>name</a>\n" |
| 24 | } |
| 25 | </thtitle="sitemap"></nav> |
| 26 | <h1 class='hbdrop' title="Sitemap"></nav> |
| 27 | div> |
| 28 | <div id='hbdrop'></div> |
+46
-8
| --- src/default.css | ||
| +++ src/default.css | ||
| @@ -496,11 +496,10 @@ | ||
| 496 | 496 | text-align: center; |
| 497 | 497 | border-collapse: collapse; |
| 498 | 498 | border-spacing: 0; |
| 499 | 499 | } |
| 500 | 500 | table.report { |
| 501 | - border-collapse:collapse; | |
| 502 | 501 | border: 1px solid #999; |
| 503 | 502 | margin: 1em 0 1em 0; |
| 504 | 503 | cursor: pointer; |
| 505 | 504 | } |
| 506 | 505 | td.rpteditex { |
| @@ -582,11 +581,11 @@ | ||
| 582 | 581 | /* ^^^ attempt to keep mobile from inflating some text */; |
| 583 | 582 | } |
| 584 | 583 | table.diff pre > ins, |
| 585 | 584 | table.diff pre > del { |
| 586 | 585 | /* Fill platform-dependent color gaps caused by |
| 587 | - inflated line-height */; | |
| 586 | + inflated line-height */ | |
| 588 | 587 | padding: 0.062em 0 0.062em 0; |
| 589 | 588 | } |
| 590 | 589 | table.diff pre > ins > *, |
| 591 | 590 | table.diff pre > del > *{ |
| 592 | 591 | /* Avoid odd-looking color swatches in conjunction with |
| @@ -618,11 +617,10 @@ | ||
| 618 | 617 | /*background-color: rgba(127,127,127,0.5); |
| 619 | 618 | cursor: pointer;*/ |
| 620 | 619 | } |
| 621 | 620 | tr.diffskip > td.chunkctrl { |
| 622 | 621 | text-align: left; |
| 623 | - font-family: monospace; | |
| 624 | 622 | } |
| 625 | 623 | tr.diffskip > td.chunkctrl > div { |
| 626 | 624 | display: flex; |
| 627 | 625 | align-items: center; |
| 628 | 626 | } |
| @@ -1294,11 +1292,10 @@ | ||
| 1294 | 1292 | .flex-container.child-gap-small > * { |
| 1295 | 1293 | margin: 0.25em; |
| 1296 | 1294 | } |
| 1297 | 1295 | #fossil-status-bar { |
| 1298 | 1296 | display: block; |
| 1299 | - font-family: monospace; | |
| 1300 | 1297 | border-width: 1px; |
| 1301 | 1298 | border-style: inset; |
| 1302 | 1299 | border-color: inherit; |
| 1303 | 1300 | min-height: 1.5em; |
| 1304 | 1301 | font-size: 1.2em; |
| @@ -1385,11 +1382,10 @@ | ||
| 1385 | 1382 | table-layout: fixed /* required to keep ultra-wide code from exceeding |
| 1386 | 1383 | window width, and instead force a scrollbar |
| 1387 | 1384 | on them. */; |
| 1388 | 1385 | } |
| 1389 | 1386 | table.numbered-lines > tbody > tr { |
| 1390 | - font-family: monospace; | |
| 1391 | 1387 | line-height: 1.35; |
| 1392 | 1388 | white-space: pre; |
| 1393 | 1389 | } |
| 1394 | 1390 | table.numbered-lines > tbody > tr > td { |
| 1395 | 1391 | font-family: inherit; |
| @@ -1535,10 +1531,34 @@ | ||
| 1535 | 1531 | |
| 1536 | 1532 | blockquote.file-content { |
| 1537 | 1533 | /* file content block in the /file page */ |
| 1538 | 1534 | margin: 0 1em; |
| 1539 | 1535 | } |
| 1536 | + | |
| 1537 | +/* Generic sidebar styling inherited by skins that don't make their own | |
| 1538 | + * arrangements. */ | |
| 1539 | +.markdown blockquote, p.blockquote, .sidebar { | |
| 1540 | + background-color: rgba(0, 0, 0, 0.05); | |
| 1541 | + border-left: 3px solid #777; | |
| 1542 | + padding: 0.1em 1em; | |
| 1543 | +} | |
| 1544 | +.sidebar { | |
| 1545 | + font-size: 90%; | |
| 1546 | +} | |
| 1547 | +.sidebar { | |
| 1548 | + /* Generic form that can be applied to any block element. */ | |
| 1549 | + font-size: 0.9em; | |
| 1550 | +} | |
| 1551 | +div.sidebar { | |
| 1552 | + /* Special exception for div-type sidebars, where there is no p | |
| 1553 | + * wrapper inside to give us the extra padding we want. */ | |
| 1554 | + padding: 1em; | |
| 1555 | +} | |
| 1556 | +div.sidebar:not(.no-label):before { | |
| 1557 | + content: "Sidebar: "; | |
| 1558 | + font-weight: bold; | |
| 1559 | +} | |
| 1540 | 1560 | |
| 1541 | 1561 | |
| 1542 | 1562 | /** |
| 1543 | 1563 | Circular "help" buttons intended to be placed to the right of |
| 1544 | 1564 | another element and hold text text for it. These typically get |
| @@ -1761,12 +1781,23 @@ | ||
| 1761 | 1781 | } |
| 1762 | 1782 | body.branch .submenu > a.timeline-link.selected { |
| 1763 | 1783 | display: inline; |
| 1764 | 1784 | } |
| 1765 | 1785 | |
| 1766 | -.monospace { | |
| 1767 | - font-family: monospace; | |
| 1786 | +/* Candidate fonts for various forms of monospaced text. Collected here | |
| 1787 | + * to avoid repeating this long list of fonts. */ | |
| 1788 | +code, kbd, pre, samp, tt, var, | |
| 1789 | + div.markdown ol.footnotes > li.fn-joined > sup.fn-joined, | |
| 1790 | + table.numbered-lines > tbody > tr, | |
| 1791 | + tr.diffskip > td.chunkctrl, | |
| 1792 | + #fossil-status-bar, | |
| 1793 | + .monospace { | |
| 1794 | + font-family: Source Code Pro, Menlo, Monaco, Consolas, | |
| 1795 | + Andale Mono, Ubuntu Mono, Deja Vu Sans Mono, | |
| 1796 | + Letter Gothic, Letter Gothic Std, Prestige Elite Std, | |
| 1797 | + Courier, Courier New, | |
| 1798 | + monospace; | |
| 1768 | 1799 | } |
| 1769 | 1800 | |
| 1770 | 1801 | div.markdown > ol.footnotes { |
| 1771 | 1802 | font-size: 90%; |
| 1772 | 1803 | } |
| @@ -1773,11 +1804,10 @@ | ||
| 1773 | 1804 | div.markdown > ol.footnotes > li { |
| 1774 | 1805 | margin-bottom: 0.5em; |
| 1775 | 1806 | } |
| 1776 | 1807 | div.markdown ol.footnotes > li.fn-joined > sup.fn-joined { |
| 1777 | 1808 | color: gray; |
| 1778 | - font-family: monospace; | |
| 1779 | 1809 | } |
| 1780 | 1810 | div.markdown ol.footnotes > li.fn-joined > sup.fn-joined::after { |
| 1781 | 1811 | content: "(joined from multiple locations) "; |
| 1782 | 1812 | } |
| 1783 | 1813 | div.markdown ol.footnotes > li.fn-misreference { |
| @@ -1846,12 +1876,20 @@ | ||
| 1846 | 1876 | /* Objects in the "desktoponly" class are invisible on mobile */ |
| 1847 | 1877 | @media screen and (max-width: 600px) { |
| 1848 | 1878 | .desktoponly { |
| 1849 | 1879 | display: none; |
| 1850 | 1880 | } |
| 1881 | +} | |
| 1882 | +/* Float sidebars to the right of the main content only if there's room. */ | |
| 1883 | +@media screen and (min-width: 600px) { | |
| 1884 | + .sidebar { | |
| 1885 | + float: right; | |
| 1886 | + max-width: 33%; | |
| 1887 | + margin-left: 1em; | |
| 1888 | + } | |
| 1851 | 1889 | } |
| 1852 | 1890 | /* Objects in the "wideonly" class are invisible only on wide-screen desktops */ |
| 1853 | 1891 | @media screen and (max-width: 1200px) { |
| 1854 | 1892 | .wideonly { |
| 1855 | 1893 | display: none; |
| 1856 | 1894 | } |
| 1857 | 1895 | } |
| 1858 | 1896 |
| --- src/default.css | |
| +++ src/default.css | |
| @@ -496,11 +496,10 @@ | |
| 496 | text-align: center; |
| 497 | border-collapse: collapse; |
| 498 | border-spacing: 0; |
| 499 | } |
| 500 | table.report { |
| 501 | border-collapse:collapse; |
| 502 | border: 1px solid #999; |
| 503 | margin: 1em 0 1em 0; |
| 504 | cursor: pointer; |
| 505 | } |
| 506 | td.rpteditex { |
| @@ -582,11 +581,11 @@ | |
| 582 | /* ^^^ attempt to keep mobile from inflating some text */; |
| 583 | } |
| 584 | table.diff pre > ins, |
| 585 | table.diff pre > del { |
| 586 | /* Fill platform-dependent color gaps caused by |
| 587 | inflated line-height */; |
| 588 | padding: 0.062em 0 0.062em 0; |
| 589 | } |
| 590 | table.diff pre > ins > *, |
| 591 | table.diff pre > del > *{ |
| 592 | /* Avoid odd-looking color swatches in conjunction with |
| @@ -618,11 +617,10 @@ | |
| 618 | /*background-color: rgba(127,127,127,0.5); |
| 619 | cursor: pointer;*/ |
| 620 | } |
| 621 | tr.diffskip > td.chunkctrl { |
| 622 | text-align: left; |
| 623 | font-family: monospace; |
| 624 | } |
| 625 | tr.diffskip > td.chunkctrl > div { |
| 626 | display: flex; |
| 627 | align-items: center; |
| 628 | } |
| @@ -1294,11 +1292,10 @@ | |
| 1294 | .flex-container.child-gap-small > * { |
| 1295 | margin: 0.25em; |
| 1296 | } |
| 1297 | #fossil-status-bar { |
| 1298 | display: block; |
| 1299 | font-family: monospace; |
| 1300 | border-width: 1px; |
| 1301 | border-style: inset; |
| 1302 | border-color: inherit; |
| 1303 | min-height: 1.5em; |
| 1304 | font-size: 1.2em; |
| @@ -1385,11 +1382,10 @@ | |
| 1385 | table-layout: fixed /* required to keep ultra-wide code from exceeding |
| 1386 | window width, and instead force a scrollbar |
| 1387 | on them. */; |
| 1388 | } |
| 1389 | table.numbered-lines > tbody > tr { |
| 1390 | font-family: monospace; |
| 1391 | line-height: 1.35; |
| 1392 | white-space: pre; |
| 1393 | } |
| 1394 | table.numbered-lines > tbody > tr > td { |
| 1395 | font-family: inherit; |
| @@ -1535,10 +1531,34 @@ | |
| 1535 | |
| 1536 | blockquote.file-content { |
| 1537 | /* file content block in the /file page */ |
| 1538 | margin: 0 1em; |
| 1539 | } |
| 1540 | |
| 1541 | |
| 1542 | /** |
| 1543 | Circular "help" buttons intended to be placed to the right of |
| 1544 | another element and hold text text for it. These typically get |
| @@ -1761,12 +1781,23 @@ | |
| 1761 | } |
| 1762 | body.branch .submenu > a.timeline-link.selected { |
| 1763 | display: inline; |
| 1764 | } |
| 1765 | |
| 1766 | .monospace { |
| 1767 | font-family: monospace; |
| 1768 | } |
| 1769 | |
| 1770 | div.markdown > ol.footnotes { |
| 1771 | font-size: 90%; |
| 1772 | } |
| @@ -1773,11 +1804,10 @@ | |
| 1773 | div.markdown > ol.footnotes > li { |
| 1774 | margin-bottom: 0.5em; |
| 1775 | } |
| 1776 | div.markdown ol.footnotes > li.fn-joined > sup.fn-joined { |
| 1777 | color: gray; |
| 1778 | font-family: monospace; |
| 1779 | } |
| 1780 | div.markdown ol.footnotes > li.fn-joined > sup.fn-joined::after { |
| 1781 | content: "(joined from multiple locations) "; |
| 1782 | } |
| 1783 | div.markdown ol.footnotes > li.fn-misreference { |
| @@ -1846,12 +1876,20 @@ | |
| 1846 | /* Objects in the "desktoponly" class are invisible on mobile */ |
| 1847 | @media screen and (max-width: 600px) { |
| 1848 | .desktoponly { |
| 1849 | display: none; |
| 1850 | } |
| 1851 | } |
| 1852 | /* Objects in the "wideonly" class are invisible only on wide-screen desktops */ |
| 1853 | @media screen and (max-width: 1200px) { |
| 1854 | .wideonly { |
| 1855 | display: none; |
| 1856 | } |
| 1857 | } |
| 1858 |
| --- src/default.css | |
| +++ src/default.css | |
| @@ -496,11 +496,10 @@ | |
| 496 | text-align: center; |
| 497 | border-collapse: collapse; |
| 498 | border-spacing: 0; |
| 499 | } |
| 500 | table.report { |
| 501 | border: 1px solid #999; |
| 502 | margin: 1em 0 1em 0; |
| 503 | cursor: pointer; |
| 504 | } |
| 505 | td.rpteditex { |
| @@ -582,11 +581,11 @@ | |
| 581 | /* ^^^ attempt to keep mobile from inflating some text */; |
| 582 | } |
| 583 | table.diff pre > ins, |
| 584 | table.diff pre > del { |
| 585 | /* Fill platform-dependent color gaps caused by |
| 586 | inflated line-height */ |
| 587 | padding: 0.062em 0 0.062em 0; |
| 588 | } |
| 589 | table.diff pre > ins > *, |
| 590 | table.diff pre > del > *{ |
| 591 | /* Avoid odd-looking color swatches in conjunction with |
| @@ -618,11 +617,10 @@ | |
| 617 | /*background-color: rgba(127,127,127,0.5); |
| 618 | cursor: pointer;*/ |
| 619 | } |
| 620 | tr.diffskip > td.chunkctrl { |
| 621 | text-align: left; |
| 622 | } |
| 623 | tr.diffskip > td.chunkctrl > div { |
| 624 | display: flex; |
| 625 | align-items: center; |
| 626 | } |
| @@ -1294,11 +1292,10 @@ | |
| 1292 | .flex-container.child-gap-small > * { |
| 1293 | margin: 0.25em; |
| 1294 | } |
| 1295 | #fossil-status-bar { |
| 1296 | display: block; |
| 1297 | border-width: 1px; |
| 1298 | border-style: inset; |
| 1299 | border-color: inherit; |
| 1300 | min-height: 1.5em; |
| 1301 | font-size: 1.2em; |
| @@ -1385,11 +1382,10 @@ | |
| 1382 | table-layout: fixed /* required to keep ultra-wide code from exceeding |
| 1383 | window width, and instead force a scrollbar |
| 1384 | on them. */; |
| 1385 | } |
| 1386 | table.numbered-lines > tbody > tr { |
| 1387 | line-height: 1.35; |
| 1388 | white-space: pre; |
| 1389 | } |
| 1390 | table.numbered-lines > tbody > tr > td { |
| 1391 | font-family: inherit; |
| @@ -1535,10 +1531,34 @@ | |
| 1531 | |
| 1532 | blockquote.file-content { |
| 1533 | /* file content block in the /file page */ |
| 1534 | margin: 0 1em; |
| 1535 | } |
| 1536 | |
| 1537 | /* Generic sidebar styling inherited by skins that don't make their own |
| 1538 | * arrangements. */ |
| 1539 | .markdown blockquote, p.blockquote, .sidebar { |
| 1540 | background-color: rgba(0, 0, 0, 0.05); |
| 1541 | border-left: 3px solid #777; |
| 1542 | padding: 0.1em 1em; |
| 1543 | } |
| 1544 | .sidebar { |
| 1545 | font-size: 90%; |
| 1546 | } |
| 1547 | .sidebar { |
| 1548 | /* Generic form that can be applied to any block element. */ |
| 1549 | font-size: 0.9em; |
| 1550 | } |
| 1551 | div.sidebar { |
| 1552 | /* Special exception for div-type sidebars, where there is no p |
| 1553 | * wrapper inside to give us the extra padding we want. */ |
| 1554 | padding: 1em; |
| 1555 | } |
| 1556 | div.sidebar:not(.no-label):before { |
| 1557 | content: "Sidebar: "; |
| 1558 | font-weight: bold; |
| 1559 | } |
| 1560 | |
| 1561 | |
| 1562 | /** |
| 1563 | Circular "help" buttons intended to be placed to the right of |
| 1564 | another element and hold text text for it. These typically get |
| @@ -1761,12 +1781,23 @@ | |
| 1781 | } |
| 1782 | body.branch .submenu > a.timeline-link.selected { |
| 1783 | display: inline; |
| 1784 | } |
| 1785 | |
| 1786 | /* Candidate fonts for various forms of monospaced text. Collected here |
| 1787 | * to avoid repeating this long list of fonts. */ |
| 1788 | code, kbd, pre, samp, tt, var, |
| 1789 | div.markdown ol.footnotes > li.fn-joined > sup.fn-joined, |
| 1790 | table.numbered-lines > tbody > tr, |
| 1791 | tr.diffskip > td.chunkctrl, |
| 1792 | #fossil-status-bar, |
| 1793 | .monospace { |
| 1794 | font-family: Source Code Pro, Menlo, Monaco, Consolas, |
| 1795 | Andale Mono, Ubuntu Mono, Deja Vu Sans Mono, |
| 1796 | Letter Gothic, Letter Gothic Std, Prestige Elite Std, |
| 1797 | Courier, Courier New, |
| 1798 | monospace; |
| 1799 | } |
| 1800 | |
| 1801 | div.markdown > ol.footnotes { |
| 1802 | font-size: 90%; |
| 1803 | } |
| @@ -1773,11 +1804,10 @@ | |
| 1804 | div.markdown > ol.footnotes > li { |
| 1805 | margin-bottom: 0.5em; |
| 1806 | } |
| 1807 | div.markdown ol.footnotes > li.fn-joined > sup.fn-joined { |
| 1808 | color: gray; |
| 1809 | } |
| 1810 | div.markdown ol.footnotes > li.fn-joined > sup.fn-joined::after { |
| 1811 | content: "(joined from multiple locations) "; |
| 1812 | } |
| 1813 | div.markdown ol.footnotes > li.fn-misreference { |
| @@ -1846,12 +1876,20 @@ | |
| 1876 | /* Objects in the "desktoponly" class are invisible on mobile */ |
| 1877 | @media screen and (max-width: 600px) { |
| 1878 | .desktoponly { |
| 1879 | display: none; |
| 1880 | } |
| 1881 | } |
| 1882 | /* Float sidebars to the right of the main content only if there's room. */ |
| 1883 | @media screen and (min-width: 600px) { |
| 1884 | .sidebar { |
| 1885 | float: right; |
| 1886 | max-width: 33%; |
| 1887 | margin-left: 1em; |
| 1888 | } |
| 1889 | } |
| 1890 | /* Objects in the "wideonly" class are invisible only on wide-screen desktops */ |
| 1891 | @media screen and (max-width: 1200px) { |
| 1892 | .wideonly { |
| 1893 | display: none; |
| 1894 | } |
| 1895 | } |
| 1896 |
+2
-2
| --- src/hbmenu.js | ||
| +++ src/hbmenu.js | ||
| @@ -21,14 +21,14 @@ | ||
| 21 | 21 | ** moved into src/hbmenu.js so that it could be more easily reused by other skins |
| 22 | 22 | ** using the "builtin_request_js" TH1 command. |
| 23 | 23 | ** |
| 24 | 24 | ** Operation: |
| 25 | 25 | ** |
| 26 | -** This script request that the HTML contain two elements: | |
| 26 | +** This script expects the HTML to contain two elements: | |
| 27 | 27 | ** |
| 28 | 28 | ** <a id="hbbtn"> <--- The hamburger menu button |
| 29 | -** <div id="hbdrop"> <--- Container for the hamburger menu | |
| 29 | +** <nav id="hbdrop"> <--- Container for the hamburger menu | |
| 30 | 30 | ** |
| 31 | 31 | ** Bindings are made on hbbtn so that when it is clicked, the following |
| 32 | 32 | ** happens: |
| 33 | 33 | ** |
| 34 | 34 | ** 1. An XHR is made to /sitemap?popup to fetch the HTML for the |
| 35 | 35 |
| --- src/hbmenu.js | |
| +++ src/hbmenu.js | |
| @@ -21,14 +21,14 @@ | |
| 21 | ** moved into src/hbmenu.js so that it could be more easily reused by other skins |
| 22 | ** using the "builtin_request_js" TH1 command. |
| 23 | ** |
| 24 | ** Operation: |
| 25 | ** |
| 26 | ** This script request that the HTML contain two elements: |
| 27 | ** |
| 28 | ** <a id="hbbtn"> <--- The hamburger menu button |
| 29 | ** <div id="hbdrop"> <--- Container for the hamburger menu |
| 30 | ** |
| 31 | ** Bindings are made on hbbtn so that when it is clicked, the following |
| 32 | ** happens: |
| 33 | ** |
| 34 | ** 1. An XHR is made to /sitemap?popup to fetch the HTML for the |
| 35 |
| --- src/hbmenu.js | |
| +++ src/hbmenu.js | |
| @@ -21,14 +21,14 @@ | |
| 21 | ** moved into src/hbmenu.js so that it could be more easily reused by other skins |
| 22 | ** using the "builtin_request_js" TH1 command. |
| 23 | ** |
| 24 | ** Operation: |
| 25 | ** |
| 26 | ** This script expects the HTML to contain two elements: |
| 27 | ** |
| 28 | ** <a id="hbbtn"> <--- The hamburger menu button |
| 29 | ** <nav id="hbdrop"> <--- Container for the hamburger menu |
| 30 | ** |
| 31 | ** Bindings are made on hbbtn so that when it is clicked, the following |
| 32 | ** happens: |
| 33 | ** |
| 34 | ** 1. An XHR is made to /sitemap?popup to fetch the HTML for the |
| 35 |
+5
-1
| --- src/main.mk | ||
| +++ src/main.mk | ||
| @@ -191,10 +191,14 @@ | ||
| 191 | 191 | $(SRCDIR)/../skins/default/header.txt \ |
| 192 | 192 | $(SRCDIR)/../skins/eagle/css.txt \ |
| 193 | 193 | $(SRCDIR)/../skins/eagle/details.txt \ |
| 194 | 194 | $(SRCDIR)/../skins/eagle/footer.txt \ |
| 195 | 195 | $(SRCDIR)/../skins/eagle/header.txt \ |
| 196 | + $(SRCDIR)/../skins/etienne/css.txt \ | |
| 197 | + $(SRCDIR)/../skins/etienne/details.txt \ | |
| 198 | + $(SRCDIR)/../skins/etienne/footer.txt \ | |
| 199 | + $(SRCDIR)/../skins/etienne/header.txt \ | |
| 196 | 200 | $(SRCDIR)/../skins/khaki/css.txt \ |
| 197 | 201 | $(SRCDIR)/../skins/khaki/details.txt \ |
| 198 | 202 | $(SRCDIR)/../skins/khaki/footer.txt \ |
| 199 | 203 | $(SRCDIR)/../skins/khaki/header.txt \ |
| 200 | 204 | $(SRCDIR)/../skins/original/css.txt \ |
| @@ -2115,11 +2119,11 @@ | ||
| 2115 | 2119 | $(OBJDIR)/cson_amalgamation.o: $(SRCDIR_extsrc)/cson_amalgamation.c |
| 2116 | 2120 | $(XTCC) -c $(SRCDIR_extsrc)/cson_amalgamation.c -o $@ |
| 2117 | 2121 | |
| 2118 | 2122 | $(SRCDIR_extsrc)/pikchr.js: $(SRCDIR_extsrc)/pikchr.c |
| 2119 | 2123 | $(EMCC_WRAPPER) -o $@ $(EMCC_OPT) --no-entry \ |
| 2120 | - -sEXPORTED_RUNTIME_METHODS=cwrap,setValue,getValue,stackSave,stackRestore,stackAlloc \ | |
| 2124 | + -sEXPORTED_RUNTIME_METHODS=cwrap,setValue,getValue,stackSave,stackRestore \ | |
| 2121 | 2125 | -sEXPORTED_FUNCTIONS=_pikchr $(SRCDIR_extsrc)/pikchr.c \ |
| 2122 | 2126 | -sENVIRONMENT=web \ |
| 2123 | 2127 | -sMODULARIZE \ |
| 2124 | 2128 | -sEXPORT_NAME=initPikchrModule \ |
| 2125 | 2129 | --minify 0 |
| 2126 | 2130 |
| --- src/main.mk | |
| +++ src/main.mk | |
| @@ -191,10 +191,14 @@ | |
| 191 | $(SRCDIR)/../skins/default/header.txt \ |
| 192 | $(SRCDIR)/../skins/eagle/css.txt \ |
| 193 | $(SRCDIR)/../skins/eagle/details.txt \ |
| 194 | $(SRCDIR)/../skins/eagle/footer.txt \ |
| 195 | $(SRCDIR)/../skins/eagle/header.txt \ |
| 196 | $(SRCDIR)/../skins/khaki/css.txt \ |
| 197 | $(SRCDIR)/../skins/khaki/details.txt \ |
| 198 | $(SRCDIR)/../skins/khaki/footer.txt \ |
| 199 | $(SRCDIR)/../skins/khaki/header.txt \ |
| 200 | $(SRCDIR)/../skins/original/css.txt \ |
| @@ -2115,11 +2119,11 @@ | |
| 2115 | $(OBJDIR)/cson_amalgamation.o: $(SRCDIR_extsrc)/cson_amalgamation.c |
| 2116 | $(XTCC) -c $(SRCDIR_extsrc)/cson_amalgamation.c -o $@ |
| 2117 | |
| 2118 | $(SRCDIR_extsrc)/pikchr.js: $(SRCDIR_extsrc)/pikchr.c |
| 2119 | $(EMCC_WRAPPER) -o $@ $(EMCC_OPT) --no-entry \ |
| 2120 | -sEXPORTED_RUNTIME_METHODS=cwrap,setValue,getValue,stackSave,stackRestore,stackAlloc \ |
| 2121 | -sEXPORTED_FUNCTIONS=_pikchr $(SRCDIR_extsrc)/pikchr.c \ |
| 2122 | -sENVIRONMENT=web \ |
| 2123 | -sMODULARIZE \ |
| 2124 | -sEXPORT_NAME=initPikchrModule \ |
| 2125 | --minify 0 |
| 2126 |
| --- src/main.mk | |
| +++ src/main.mk | |
| @@ -191,10 +191,14 @@ | |
| 191 | $(SRCDIR)/../skins/default/header.txt \ |
| 192 | $(SRCDIR)/../skins/eagle/css.txt \ |
| 193 | $(SRCDIR)/../skins/eagle/details.txt \ |
| 194 | $(SRCDIR)/../skins/eagle/footer.txt \ |
| 195 | $(SRCDIR)/../skins/eagle/header.txt \ |
| 196 | $(SRCDIR)/../skins/etienne/css.txt \ |
| 197 | $(SRCDIR)/../skins/etienne/details.txt \ |
| 198 | $(SRCDIR)/../skins/etienne/footer.txt \ |
| 199 | $(SRCDIR)/../skins/etienne/header.txt \ |
| 200 | $(SRCDIR)/../skins/khaki/css.txt \ |
| 201 | $(SRCDIR)/../skins/khaki/details.txt \ |
| 202 | $(SRCDIR)/../skins/khaki/footer.txt \ |
| 203 | $(SRCDIR)/../skins/khaki/header.txt \ |
| 204 | $(SRCDIR)/../skins/original/css.txt \ |
| @@ -2115,11 +2119,11 @@ | |
| 2119 | $(OBJDIR)/cson_amalgamation.o: $(SRCDIR_extsrc)/cson_amalgamation.c |
| 2120 | $(XTCC) -c $(SRCDIR_extsrc)/cson_amalgamation.c -o $@ |
| 2121 | |
| 2122 | $(SRCDIR_extsrc)/pikchr.js: $(SRCDIR_extsrc)/pikchr.c |
| 2123 | $(EMCC_WRAPPER) -o $@ $(EMCC_OPT) --no-entry \ |
| 2124 | -sEXPORTED_RUNTIME_METHODS=cwrap,setValue,getValue,stackSave,stackRestore \ |
| 2125 | -sEXPORTED_FUNCTIONS=_pikchr $(SRCDIR_extsrc)/pikchr.c \ |
| 2126 | -sENVIRONMENT=web \ |
| 2127 | -sMODULARIZE \ |
| 2128 | -sEXPORT_NAME=initPikchrModule \ |
| 2129 | --minify 0 |
| 2130 |
+1
| --- src/skins.c | ||
| +++ src/skins.c | ||
| @@ -45,10 +45,11 @@ | ||
| 45 | 45 | { "Ardoise", "ardoise", 0 }, |
| 46 | 46 | { "Black & White", "black_and_white", 0 }, |
| 47 | 47 | { "Blitz", "blitz", 0 }, |
| 48 | 48 | { "Dark Mode", "darkmode", 0 }, |
| 49 | 49 | { "Eagle", "eagle", 0 }, |
| 50 | + { "Étienne", "etienne", 0 }, | |
| 50 | 51 | { "Khaki", "khaki", 0 }, |
| 51 | 52 | { "Original", "original", 0 }, |
| 52 | 53 | { "Plain Gray", "plain_gray", 0 }, |
| 53 | 54 | { "Xekri", "xekri", 0 }, |
| 54 | 55 | }; |
| 55 | 56 |
| --- src/skins.c | |
| +++ src/skins.c | |
| @@ -45,10 +45,11 @@ | |
| 45 | { "Ardoise", "ardoise", 0 }, |
| 46 | { "Black & White", "black_and_white", 0 }, |
| 47 | { "Blitz", "blitz", 0 }, |
| 48 | { "Dark Mode", "darkmode", 0 }, |
| 49 | { "Eagle", "eagle", 0 }, |
| 50 | { "Khaki", "khaki", 0 }, |
| 51 | { "Original", "original", 0 }, |
| 52 | { "Plain Gray", "plain_gray", 0 }, |
| 53 | { "Xekri", "xekri", 0 }, |
| 54 | }; |
| 55 |
| --- src/skins.c | |
| +++ src/skins.c | |
| @@ -45,10 +45,11 @@ | |
| 45 | { "Ardoise", "ardoise", 0 }, |
| 46 | { "Black & White", "black_and_white", 0 }, |
| 47 | { "Blitz", "blitz", 0 }, |
| 48 | { "Dark Mode", "darkmode", 0 }, |
| 49 | { "Eagle", "eagle", 0 }, |
| 50 | { "Étienne", "etienne", 0 }, |
| 51 | { "Khaki", "khaki", 0 }, |
| 52 | { "Original", "original", 0 }, |
| 53 | { "Plain Gray", "plain_gray", 0 }, |
| 54 | { "Xekri", "xekri", 0 }, |
| 55 | }; |
| 56 |
+1
| --- src/wikiformat.c | ||
| +++ src/wikiformat.c | ||
| @@ -1781,10 +1781,11 @@ | ||
| 1781 | 1781 | if( backupToType(p, MUTYPE_TABLE|MUTYPE_TR) ){ |
| 1782 | 1782 | if( stackTopType(p)==MUTYPE_TABLE ){ |
| 1783 | 1783 | pushStack(p, MARKUP_TR); |
| 1784 | 1784 | blob_append_string(p->pOut, "<tr>"); |
| 1785 | 1785 | } |
| 1786 | + p->wantAutoParagraph = 0; | |
| 1786 | 1787 | pushStack(p, markup.iCode); |
| 1787 | 1788 | renderMarkup(p->pOut, &markup); |
| 1788 | 1789 | } |
| 1789 | 1790 | }else |
| 1790 | 1791 | if( markup.iType==MUTYPE_HYPERLINK ){ |
| 1791 | 1792 |
| --- src/wikiformat.c | |
| +++ src/wikiformat.c | |
| @@ -1781,10 +1781,11 @@ | |
| 1781 | if( backupToType(p, MUTYPE_TABLE|MUTYPE_TR) ){ |
| 1782 | if( stackTopType(p)==MUTYPE_TABLE ){ |
| 1783 | pushStack(p, MARKUP_TR); |
| 1784 | blob_append_string(p->pOut, "<tr>"); |
| 1785 | } |
| 1786 | pushStack(p, markup.iCode); |
| 1787 | renderMarkup(p->pOut, &markup); |
| 1788 | } |
| 1789 | }else |
| 1790 | if( markup.iType==MUTYPE_HYPERLINK ){ |
| 1791 |
| --- src/wikiformat.c | |
| +++ src/wikiformat.c | |
| @@ -1781,10 +1781,11 @@ | |
| 1781 | if( backupToType(p, MUTYPE_TABLE|MUTYPE_TR) ){ |
| 1782 | if( stackTopType(p)==MUTYPE_TABLE ){ |
| 1783 | pushStack(p, MARKUP_TR); |
| 1784 | blob_append_string(p->pOut, "<tr>"); |
| 1785 | } |
| 1786 | p->wantAutoParagraph = 0; |
| 1787 | pushStack(p, markup.iCode); |
| 1788 | renderMarkup(p->pOut, &markup); |
| 1789 | } |
| 1790 | }else |
| 1791 | if( markup.iType==MUTYPE_HYPERLINK ){ |
| 1792 |
+2
-3
| --- test/release-checklist.wiki | ||
| +++ test/release-checklist.wiki | ||
| @@ -47,13 +47,12 @@ | ||
| 47 | 47 | Shift-click on each of the links in [./fileage-test-1.wiki] and verify |
| 48 | 48 | correct operation of the file-age computation. |
| 49 | 49 | |
| 50 | 50 | <li><p> |
| 51 | 51 | Verify correct name-change tracking behavior (no net changes) for: |
| 52 | -<blockquote><b> | |
| 53 | -fossil test-name-changes --debug b120bc8b262ac 374920b20944b | |
| 54 | -</b></blockquote> | |
| 52 | +<pre><b>fossil test-name-changes --debug b120bc8b262ac 374920b20944b | |
| 53 | +</b></pre> | |
| 55 | 54 | |
| 56 | 55 | <li><p> |
| 57 | 56 | Compile for all of the following platforms: |
| 58 | 57 | <ol type="a"> |
| 59 | 58 | <li> Linux x86 |
| 60 | 59 |
| --- test/release-checklist.wiki | |
| +++ test/release-checklist.wiki | |
| @@ -47,13 +47,12 @@ | |
| 47 | Shift-click on each of the links in [./fileage-test-1.wiki] and verify |
| 48 | correct operation of the file-age computation. |
| 49 | |
| 50 | <li><p> |
| 51 | Verify correct name-change tracking behavior (no net changes) for: |
| 52 | <blockquote><b> |
| 53 | fossil test-name-changes --debug b120bc8b262ac 374920b20944b |
| 54 | </b></blockquote> |
| 55 | |
| 56 | <li><p> |
| 57 | Compile for all of the following platforms: |
| 58 | <ol type="a"> |
| 59 | <li> Linux x86 |
| 60 |
| --- test/release-checklist.wiki | |
| +++ test/release-checklist.wiki | |
| @@ -47,13 +47,12 @@ | |
| 47 | Shift-click on each of the links in [./fileage-test-1.wiki] and verify |
| 48 | correct operation of the file-age computation. |
| 49 | |
| 50 | <li><p> |
| 51 | Verify correct name-change tracking behavior (no net changes) for: |
| 52 | <pre><b>fossil test-name-changes --debug b120bc8b262ac 374920b20944b |
| 53 | </b></pre> |
| 54 | |
| 55 | <li><p> |
| 56 | Compile for all of the following platforms: |
| 57 | <ol type="a"> |
| 58 | <li> Linux x86 |
| 59 |
+4
| --- win/Makefile.mingw | ||
| +++ win/Makefile.mingw | ||
| @@ -577,10 +577,14 @@ | ||
| 577 | 577 | $(SRCDIR)/../skins/default/header.txt \ |
| 578 | 578 | $(SRCDIR)/../skins/eagle/css.txt \ |
| 579 | 579 | $(SRCDIR)/../skins/eagle/details.txt \ |
| 580 | 580 | $(SRCDIR)/../skins/eagle/footer.txt \ |
| 581 | 581 | $(SRCDIR)/../skins/eagle/header.txt \ |
| 582 | + $(SRCDIR)/../skins/etienne/css.txt \ | |
| 583 | + $(SRCDIR)/../skins/etienne/details.txt \ | |
| 584 | + $(SRCDIR)/../skins/etienne/footer.txt \ | |
| 585 | + $(SRCDIR)/../skins/etienne/header.txt \ | |
| 582 | 586 | $(SRCDIR)/../skins/khaki/css.txt \ |
| 583 | 587 | $(SRCDIR)/../skins/khaki/details.txt \ |
| 584 | 588 | $(SRCDIR)/../skins/khaki/footer.txt \ |
| 585 | 589 | $(SRCDIR)/../skins/khaki/header.txt \ |
| 586 | 590 | $(SRCDIR)/../skins/original/css.txt \ |
| 587 | 591 |
| --- win/Makefile.mingw | |
| +++ win/Makefile.mingw | |
| @@ -577,10 +577,14 @@ | |
| 577 | $(SRCDIR)/../skins/default/header.txt \ |
| 578 | $(SRCDIR)/../skins/eagle/css.txt \ |
| 579 | $(SRCDIR)/../skins/eagle/details.txt \ |
| 580 | $(SRCDIR)/../skins/eagle/footer.txt \ |
| 581 | $(SRCDIR)/../skins/eagle/header.txt \ |
| 582 | $(SRCDIR)/../skins/khaki/css.txt \ |
| 583 | $(SRCDIR)/../skins/khaki/details.txt \ |
| 584 | $(SRCDIR)/../skins/khaki/footer.txt \ |
| 585 | $(SRCDIR)/../skins/khaki/header.txt \ |
| 586 | $(SRCDIR)/../skins/original/css.txt \ |
| 587 |
| --- win/Makefile.mingw | |
| +++ win/Makefile.mingw | |
| @@ -577,10 +577,14 @@ | |
| 577 | $(SRCDIR)/../skins/default/header.txt \ |
| 578 | $(SRCDIR)/../skins/eagle/css.txt \ |
| 579 | $(SRCDIR)/../skins/eagle/details.txt \ |
| 580 | $(SRCDIR)/../skins/eagle/footer.txt \ |
| 581 | $(SRCDIR)/../skins/eagle/header.txt \ |
| 582 | $(SRCDIR)/../skins/etienne/css.txt \ |
| 583 | $(SRCDIR)/../skins/etienne/details.txt \ |
| 584 | $(SRCDIR)/../skins/etienne/footer.txt \ |
| 585 | $(SRCDIR)/../skins/etienne/header.txt \ |
| 586 | $(SRCDIR)/../skins/khaki/css.txt \ |
| 587 | $(SRCDIR)/../skins/khaki/details.txt \ |
| 588 | $(SRCDIR)/../skins/khaki/footer.txt \ |
| 589 | $(SRCDIR)/../skins/khaki/header.txt \ |
| 590 | $(SRCDIR)/../skins/original/css.txt \ |
| 591 |
+8
| --- win/Makefile.msc | ||
| +++ win/Makefile.msc | ||
| @@ -535,10 +535,14 @@ | ||
| 535 | 535 | "$(SRCDIR)\..\skins\default\header.txt" \ |
| 536 | 536 | "$(SRCDIR)\..\skins\eagle\css.txt" \ |
| 537 | 537 | "$(SRCDIR)\..\skins\eagle\details.txt" \ |
| 538 | 538 | "$(SRCDIR)\..\skins\eagle\footer.txt" \ |
| 539 | 539 | "$(SRCDIR)\..\skins\eagle\header.txt" \ |
| 540 | + "$(SRCDIR)\..\skins\etienne\css.txt" \ | |
| 541 | + "$(SRCDIR)\..\skins\etienne\details.txt" \ | |
| 542 | + "$(SRCDIR)\..\skins\etienne\footer.txt" \ | |
| 543 | + "$(SRCDIR)\..\skins\etienne\header.txt" \ | |
| 540 | 544 | "$(SRCDIR)\..\skins\khaki\css.txt" \ |
| 541 | 545 | "$(SRCDIR)\..\skins\khaki\details.txt" \ |
| 542 | 546 | "$(SRCDIR)\..\skins\khaki\footer.txt" \ |
| 543 | 547 | "$(SRCDIR)\..\skins\khaki\header.txt" \ |
| 544 | 548 | "$(SRCDIR)\..\skins\original\css.txt" \ |
| @@ -1160,10 +1164,14 @@ | ||
| 1160 | 1164 | echo "$(SRCDIR)\../skins/default/header.txt" >> $@ |
| 1161 | 1165 | echo "$(SRCDIR)\../skins/eagle/css.txt" >> $@ |
| 1162 | 1166 | echo "$(SRCDIR)\../skins/eagle/details.txt" >> $@ |
| 1163 | 1167 | echo "$(SRCDIR)\../skins/eagle/footer.txt" >> $@ |
| 1164 | 1168 | echo "$(SRCDIR)\../skins/eagle/header.txt" >> $@ |
| 1169 | + echo "$(SRCDIR)\../skins/etienne/css.txt" >> $@ | |
| 1170 | + echo "$(SRCDIR)\../skins/etienne/details.txt" >> $@ | |
| 1171 | + echo "$(SRCDIR)\../skins/etienne/footer.txt" >> $@ | |
| 1172 | + echo "$(SRCDIR)\../skins/etienne/header.txt" >> $@ | |
| 1165 | 1173 | echo "$(SRCDIR)\../skins/khaki/css.txt" >> $@ |
| 1166 | 1174 | echo "$(SRCDIR)\../skins/khaki/details.txt" >> $@ |
| 1167 | 1175 | echo "$(SRCDIR)\../skins/khaki/footer.txt" >> $@ |
| 1168 | 1176 | echo "$(SRCDIR)\../skins/khaki/header.txt" >> $@ |
| 1169 | 1177 | echo "$(SRCDIR)\../skins/original/css.txt" >> $@ |
| 1170 | 1178 |
| --- win/Makefile.msc | |
| +++ win/Makefile.msc | |
| @@ -535,10 +535,14 @@ | |
| 535 | "$(SRCDIR)\..\skins\default\header.txt" \ |
| 536 | "$(SRCDIR)\..\skins\eagle\css.txt" \ |
| 537 | "$(SRCDIR)\..\skins\eagle\details.txt" \ |
| 538 | "$(SRCDIR)\..\skins\eagle\footer.txt" \ |
| 539 | "$(SRCDIR)\..\skins\eagle\header.txt" \ |
| 540 | "$(SRCDIR)\..\skins\khaki\css.txt" \ |
| 541 | "$(SRCDIR)\..\skins\khaki\details.txt" \ |
| 542 | "$(SRCDIR)\..\skins\khaki\footer.txt" \ |
| 543 | "$(SRCDIR)\..\skins\khaki\header.txt" \ |
| 544 | "$(SRCDIR)\..\skins\original\css.txt" \ |
| @@ -1160,10 +1164,14 @@ | |
| 1160 | echo "$(SRCDIR)\../skins/default/header.txt" >> $@ |
| 1161 | echo "$(SRCDIR)\../skins/eagle/css.txt" >> $@ |
| 1162 | echo "$(SRCDIR)\../skins/eagle/details.txt" >> $@ |
| 1163 | echo "$(SRCDIR)\../skins/eagle/footer.txt" >> $@ |
| 1164 | echo "$(SRCDIR)\../skins/eagle/header.txt" >> $@ |
| 1165 | echo "$(SRCDIR)\../skins/khaki/css.txt" >> $@ |
| 1166 | echo "$(SRCDIR)\../skins/khaki/details.txt" >> $@ |
| 1167 | echo "$(SRCDIR)\../skins/khaki/footer.txt" >> $@ |
| 1168 | echo "$(SRCDIR)\../skins/khaki/header.txt" >> $@ |
| 1169 | echo "$(SRCDIR)\../skins/original/css.txt" >> $@ |
| 1170 |
| --- win/Makefile.msc | |
| +++ win/Makefile.msc | |
| @@ -535,10 +535,14 @@ | |
| 535 | "$(SRCDIR)\..\skins\default\header.txt" \ |
| 536 | "$(SRCDIR)\..\skins\eagle\css.txt" \ |
| 537 | "$(SRCDIR)\..\skins\eagle\details.txt" \ |
| 538 | "$(SRCDIR)\..\skins\eagle\footer.txt" \ |
| 539 | "$(SRCDIR)\..\skins\eagle\header.txt" \ |
| 540 | "$(SRCDIR)\..\skins\etienne\css.txt" \ |
| 541 | "$(SRCDIR)\..\skins\etienne\details.txt" \ |
| 542 | "$(SRCDIR)\..\skins\etienne\footer.txt" \ |
| 543 | "$(SRCDIR)\..\skins\etienne\header.txt" \ |
| 544 | "$(SRCDIR)\..\skins\khaki\css.txt" \ |
| 545 | "$(SRCDIR)\..\skins\khaki\details.txt" \ |
| 546 | "$(SRCDIR)\..\skins\khaki\footer.txt" \ |
| 547 | "$(SRCDIR)\..\skins\khaki\header.txt" \ |
| 548 | "$(SRCDIR)\..\skins\original\css.txt" \ |
| @@ -1160,10 +1164,14 @@ | |
| 1164 | echo "$(SRCDIR)\../skins/default/header.txt" >> $@ |
| 1165 | echo "$(SRCDIR)\../skins/eagle/css.txt" >> $@ |
| 1166 | echo "$(SRCDIR)\../skins/eagle/details.txt" >> $@ |
| 1167 | echo "$(SRCDIR)\../skins/eagle/footer.txt" >> $@ |
| 1168 | echo "$(SRCDIR)\../skins/eagle/header.txt" >> $@ |
| 1169 | echo "$(SRCDIR)\../skins/etienne/css.txt" >> $@ |
| 1170 | echo "$(SRCDIR)\../skins/etienne/details.txt" >> $@ |
| 1171 | echo "$(SRCDIR)\../skins/etienne/footer.txt" >> $@ |
| 1172 | echo "$(SRCDIR)\../skins/etienne/header.txt" >> $@ |
| 1173 | echo "$(SRCDIR)\../skins/khaki/css.txt" >> $@ |
| 1174 | echo "$(SRCDIR)\../skins/khaki/details.txt" >> $@ |
| 1175 | echo "$(SRCDIR)\../skins/khaki/footer.txt" >> $@ |
| 1176 | echo "$(SRCDIR)\../skins/khaki/header.txt" >> $@ |
| 1177 | echo "$(SRCDIR)\../skins/original/css.txt" >> $@ |
| 1178 |
+32
-22
| --- www/aboutcgi.wiki | ||
| +++ www/aboutcgi.wiki | ||
| @@ -1,7 +1,9 @@ | ||
| 1 | 1 | <title>How CGI Works In Fossil</title> |
| 2 | -<h2>Introduction</h2><blockquote> | |
| 2 | + | |
| 3 | +<h2>Introduction</h2> | |
| 4 | + | |
| 3 | 5 | CGI or "Common Gateway Interface" is a venerable yet reliable technique for |
| 4 | 6 | generating dynamic web content. This article gives a quick background on how |
| 5 | 7 | CGI works and describes how Fossil can act as a CGI service. |
| 6 | 8 | |
| 7 | 9 | This is a "how it works" guide. This document provides background |
| @@ -8,12 +10,12 @@ | ||
| 8 | 10 | information on the CGI protocol so that you can better understand what |
| 9 | 11 | is going on behind the scenes. If you just want to set up Fossil |
| 10 | 12 | as a CGI server, see the [./server/ | Fossil Server Setup] page. Or |
| 11 | 13 | if you want to development CGI-based extensions to Fossil, see |
| 12 | 14 | the [./serverext.wiki|CGI Server Extensions] page. |
| 13 | -</blockquote> | |
| 14 | -<h2>A Quick Review Of CGI</h2><blockquote> | |
| 15 | + | |
| 16 | +<h2>A Quick Review Of CGI</h2> | |
| 15 | 17 | |
| 16 | 18 | An HTTP request is a block of text that is sent by a client application |
| 17 | 19 | (usually a web browser) and arrives at the web server over a network |
| 18 | 20 | connection. The HTTP request contains a URL that describes the information |
| 19 | 21 | being requested. The URL in the HTTP request is typically the same URL |
| @@ -29,11 +31,13 @@ | ||
| 29 | 31 | The web server is free to interpret the HTTP request in any way it wants. |
| 30 | 32 | But most web servers follow a similar pattern, described below. |
| 31 | 33 | (Note: details may vary from one web server to another.) |
| 32 | 34 | |
| 33 | 35 | Suppose the filename component of the URL in the HTTP request looks like this: |
| 34 | -<blockquote><b>/one/two/timeline/four</b></blockquote> | |
| 36 | + | |
| 37 | +<pre>/one/two/timeline/four</pre> | |
| 38 | + | |
| 35 | 39 | Most web servers will search their content area for files that match |
| 36 | 40 | some prefix of the URL. The search starts with <b>/one</b>, then goes to |
| 37 | 41 | <b>/one/two</b>, then <b>/one/two/timeline</b>, and finally |
| 38 | 42 | <b>/one/two/timeline/four</b> is checked. The search stops at the first |
| 39 | 43 | match. |
| @@ -46,12 +50,12 @@ | ||
| 46 | 50 | executes the <b>/one/two</b> script. The output generated by |
| 47 | 51 | the script is collected and repackaged as the HTTP reply. |
| 48 | 52 | |
| 49 | 53 | Before executing the CGI script, the web server will set up various |
| 50 | 54 | environment variables with information useful to the CGI script: |
| 51 | -<table border=1 cellpadding=5> | |
| 52 | -<tr><th>Environment<br>Variable<th>Meaning | |
| 55 | +<table> | |
| 56 | +<tr><th>Variable<th>Meaning | |
| 53 | 57 | <tr><td>GATEWAY_INTERFACE<td>Always set to "CGI/1.0" |
| 54 | 58 | <tr><td>REQUEST_URI |
| 55 | 59 | <td>The input URL from the HTTP request. |
| 56 | 60 | <tr><td>SCRIPT_NAME |
| 57 | 61 | <td>The prefix of the input URL that matches the CGI script name. |
| @@ -85,19 +89,21 @@ | ||
| 85 | 89 | but a CGI script handles just one HTTP request and then exits. |
| 86 | 90 | |
| 87 | 91 | The above is a rough outline of how CGI works. |
| 88 | 92 | There are many details omitted from this brief discussion. |
| 89 | 93 | See other on-line CGI tutorials for further information. |
| 90 | -</blockquote> | |
| 94 | + | |
| 91 | 95 | <h2>How Fossil Acts As A CGI Program</h2> |
| 92 | -<blockquote> | |
| 96 | + | |
| 93 | 97 | An appropriate CGI script for running Fossil will look something |
| 94 | 98 | like the following: |
| 95 | -<blockquote><pre> | |
| 99 | + | |
| 100 | +<pre> | |
| 96 | 101 | #!/usr/bin/fossil |
| 97 | 102 | repository: /home/www/repos/project.fossil |
| 98 | -</pre></blockquote> | |
| 103 | +</pre> | |
| 104 | + | |
| 99 | 105 | The first line of the script is a |
| 100 | 106 | "[https://en.wikipedia.org/wiki/Shebang_%28Unix%29|shebang]" |
| 101 | 107 | that tells the operating system what program to use as the interpreter |
| 102 | 108 | for this script. On unix, when you execute a script that starts with |
| 103 | 109 | a shebang, the operating system runs the program identified by the |
| @@ -134,20 +140,21 @@ | ||
| 134 | 140 | exactly the same thing to Fossil: |
| 135 | 141 | <ol type='A'> |
| 136 | 142 | <li> [https://fossil-scm.org/home/info/c14ecc43] |
| 137 | 143 | <li> [https://fossil-scm.org/home/info?name=c14ecc43] |
| 138 | 144 | </ol> |
| 145 | + | |
| 139 | 146 | In both cases, the CGI script is called "/fossil". For case (A), |
| 140 | 147 | the PATH_INFO variable will be "info/c14ecc43" and so the |
| 141 | 148 | "[/help?cmd=/info|/info]" webpage will be generated and the suffix of |
| 142 | 149 | PATH_INFO will be converted into the "name" query parameter, which |
| 143 | 150 | identifies the artifact about which information is requested. |
| 144 | 151 | In case (B), the PATH_INFO is just "info", but the same "name" |
| 145 | 152 | query parameter is set explicitly by the URL itself. |
| 146 | -</blockquote> | |
| 153 | + | |
| 147 | 154 | <h2>Serving Multiple Fossil Repositories From One CGI Script</h2> |
| 148 | -<blockquote> | |
| 155 | + | |
| 149 | 156 | The previous example showed how to serve a single Fossil repository |
| 150 | 157 | using a single CGI script. |
| 151 | 158 | On a website that wants to serve multiple repositories, one could |
| 152 | 159 | simply create multiple CGI scripts, one script for each repository. |
| 153 | 160 | But it is also possible to serve multiple Fossil repositories from |
| @@ -155,22 +162,26 @@ | ||
| 155 | 162 | |
| 156 | 163 | If the CGI script for Fossil contains a "directory:" line instead of |
| 157 | 164 | a "repository:" line, then the argument to "directory:" is the name |
| 158 | 165 | of a directory that contains multiple repository files, each ending |
| 159 | 166 | with ".fossil". For example: |
| 160 | -<blockquote><pre> | |
| 167 | + | |
| 168 | +<pre> | |
| 161 | 169 | #!/usr/bin/fossil |
| 162 | 170 | directory: /home/www/repos |
| 163 | -</pre></blockquote> | |
| 171 | +</pre> | |
| 172 | + | |
| 164 | 173 | Suppose the /home/www/repos directory contains files named |
| 165 | 174 | <b>one.fossil</b>, <b>two.fossil</b>, and <b>subdir/three.fossil</b>. |
| 166 | 175 | Further suppose that the name of the CGI script (relative to the root |
| 167 | 176 | of the webserver document area) is "cgis/example2". Then to |
| 168 | 177 | see the timeline for the "three.fossil" repository, the URL would be: |
| 169 | -<blockquote> | |
| 170 | -<b>http://example.com/cgis/example2/subdir/three/timeline</b> | |
| 171 | -</blockquote> | |
| 178 | + | |
| 179 | +<pre> | |
| 180 | +http://example.com/cgis/example2/subdir/three/timeline | |
| 181 | +</pre> | |
| 182 | + | |
| 172 | 183 | Here is what happens: |
| 173 | 184 | <ol> |
| 174 | 185 | <li> The input URI on the HTTP request is |
| 175 | 186 | <b>/cgis/example2/subdir/three/timeline</b> |
| 176 | 187 | <li> The web server searches prefixes of the input URI until it finds |
| @@ -186,33 +197,33 @@ | ||
| 186 | 197 | "subdir/three/" leaving it at just "timeline". |
| 187 | 198 | <li> Fossil looks at the rest of PATH_INFO to see that the webpage |
| 188 | 199 | requested is "timeline". |
| 189 | 200 | </ol> |
| 190 | 201 | <a id="cgivar"></a> |
| 202 | + | |
| 191 | 203 | The web server sets many environment variables in step 2 in addition |
| 192 | 204 | to just PATH_INFO. The following diagram shows a few of these variables |
| 193 | 205 | and their relationship to the request URL: |
| 206 | + | |
| 194 | 207 | <pre> |
| 195 | 208 | REQUEST_URI |
| 196 | 209 | ___________________|_______________________ |
| 197 | 210 | / \ |
| 198 | 211 | http://example.com/cgis/example2/subdir/three/timeline?c=55d7e1 |
| 199 | 212 | \_________/\____________/\____________________/ \______/ |
| 200 | 213 | | | | | |
| 201 | 214 | HTTP_HOST SCRIPT_NAME PATH_INFO QUERY_STRING |
| 202 | 215 | </pre> |
| 203 | -</blockquote> | |
| 216 | + | |
| 204 | 217 | <h2>Additional CGI Script Options</h2> |
| 205 | -<blockquote> | |
| 206 | 218 | |
| 207 | 219 | The CGI script can have additional options used to fine-tune |
| 208 | 220 | Fossil's behavior. See the [./cgi.wiki|CGI script documentation] |
| 209 | 221 | for details. |
| 210 | 222 | |
| 211 | -</blockquote> | |
| 212 | 223 | <h2>Additional Observations</h2> |
| 213 | -<blockquote><ol type="I"> | |
| 224 | +<ol type="I"> | |
| 214 | 225 | <li><p> |
| 215 | 226 | Fossil does not distinguish between the various HTTP methods (GET, PUT, |
| 216 | 227 | DELETE, etc). Fossil figures out what it needs to do purely from the |
| 217 | 228 | webpage term of the URI.</p></li> |
| 218 | 229 | <li><p> |
| @@ -239,6 +250,5 @@ | ||
| 239 | 250 | <li><p> |
| 240 | 251 | Fossil is itself often launched using CGI. But Fossil can also then |
| 241 | 252 | turn around and launch [./serverext.wiki|sub-CGI scripts to implement |
| 242 | 253 | extensions].</p></li> |
| 243 | 254 | </ol> |
| 244 | -</blockquote> | |
| 245 | 255 |
| --- www/aboutcgi.wiki | |
| +++ www/aboutcgi.wiki | |
| @@ -1,7 +1,9 @@ | |
| 1 | <title>How CGI Works In Fossil</title> |
| 2 | <h2>Introduction</h2><blockquote> |
| 3 | CGI or "Common Gateway Interface" is a venerable yet reliable technique for |
| 4 | generating dynamic web content. This article gives a quick background on how |
| 5 | CGI works and describes how Fossil can act as a CGI service. |
| 6 | |
| 7 | This is a "how it works" guide. This document provides background |
| @@ -8,12 +10,12 @@ | |
| 8 | information on the CGI protocol so that you can better understand what |
| 9 | is going on behind the scenes. If you just want to set up Fossil |
| 10 | as a CGI server, see the [./server/ | Fossil Server Setup] page. Or |
| 11 | if you want to development CGI-based extensions to Fossil, see |
| 12 | the [./serverext.wiki|CGI Server Extensions] page. |
| 13 | </blockquote> |
| 14 | <h2>A Quick Review Of CGI</h2><blockquote> |
| 15 | |
| 16 | An HTTP request is a block of text that is sent by a client application |
| 17 | (usually a web browser) and arrives at the web server over a network |
| 18 | connection. The HTTP request contains a URL that describes the information |
| 19 | being requested. The URL in the HTTP request is typically the same URL |
| @@ -29,11 +31,13 @@ | |
| 29 | The web server is free to interpret the HTTP request in any way it wants. |
| 30 | But most web servers follow a similar pattern, described below. |
| 31 | (Note: details may vary from one web server to another.) |
| 32 | |
| 33 | Suppose the filename component of the URL in the HTTP request looks like this: |
| 34 | <blockquote><b>/one/two/timeline/four</b></blockquote> |
| 35 | Most web servers will search their content area for files that match |
| 36 | some prefix of the URL. The search starts with <b>/one</b>, then goes to |
| 37 | <b>/one/two</b>, then <b>/one/two/timeline</b>, and finally |
| 38 | <b>/one/two/timeline/four</b> is checked. The search stops at the first |
| 39 | match. |
| @@ -46,12 +50,12 @@ | |
| 46 | executes the <b>/one/two</b> script. The output generated by |
| 47 | the script is collected and repackaged as the HTTP reply. |
| 48 | |
| 49 | Before executing the CGI script, the web server will set up various |
| 50 | environment variables with information useful to the CGI script: |
| 51 | <table border=1 cellpadding=5> |
| 52 | <tr><th>Environment<br>Variable<th>Meaning |
| 53 | <tr><td>GATEWAY_INTERFACE<td>Always set to "CGI/1.0" |
| 54 | <tr><td>REQUEST_URI |
| 55 | <td>The input URL from the HTTP request. |
| 56 | <tr><td>SCRIPT_NAME |
| 57 | <td>The prefix of the input URL that matches the CGI script name. |
| @@ -85,19 +89,21 @@ | |
| 85 | but a CGI script handles just one HTTP request and then exits. |
| 86 | |
| 87 | The above is a rough outline of how CGI works. |
| 88 | There are many details omitted from this brief discussion. |
| 89 | See other on-line CGI tutorials for further information. |
| 90 | </blockquote> |
| 91 | <h2>How Fossil Acts As A CGI Program</h2> |
| 92 | <blockquote> |
| 93 | An appropriate CGI script for running Fossil will look something |
| 94 | like the following: |
| 95 | <blockquote><pre> |
| 96 | #!/usr/bin/fossil |
| 97 | repository: /home/www/repos/project.fossil |
| 98 | </pre></blockquote> |
| 99 | The first line of the script is a |
| 100 | "[https://en.wikipedia.org/wiki/Shebang_%28Unix%29|shebang]" |
| 101 | that tells the operating system what program to use as the interpreter |
| 102 | for this script. On unix, when you execute a script that starts with |
| 103 | a shebang, the operating system runs the program identified by the |
| @@ -134,20 +140,21 @@ | |
| 134 | exactly the same thing to Fossil: |
| 135 | <ol type='A'> |
| 136 | <li> [https://fossil-scm.org/home/info/c14ecc43] |
| 137 | <li> [https://fossil-scm.org/home/info?name=c14ecc43] |
| 138 | </ol> |
| 139 | In both cases, the CGI script is called "/fossil". For case (A), |
| 140 | the PATH_INFO variable will be "info/c14ecc43" and so the |
| 141 | "[/help?cmd=/info|/info]" webpage will be generated and the suffix of |
| 142 | PATH_INFO will be converted into the "name" query parameter, which |
| 143 | identifies the artifact about which information is requested. |
| 144 | In case (B), the PATH_INFO is just "info", but the same "name" |
| 145 | query parameter is set explicitly by the URL itself. |
| 146 | </blockquote> |
| 147 | <h2>Serving Multiple Fossil Repositories From One CGI Script</h2> |
| 148 | <blockquote> |
| 149 | The previous example showed how to serve a single Fossil repository |
| 150 | using a single CGI script. |
| 151 | On a website that wants to serve multiple repositories, one could |
| 152 | simply create multiple CGI scripts, one script for each repository. |
| 153 | But it is also possible to serve multiple Fossil repositories from |
| @@ -155,22 +162,26 @@ | |
| 155 | |
| 156 | If the CGI script for Fossil contains a "directory:" line instead of |
| 157 | a "repository:" line, then the argument to "directory:" is the name |
| 158 | of a directory that contains multiple repository files, each ending |
| 159 | with ".fossil". For example: |
| 160 | <blockquote><pre> |
| 161 | #!/usr/bin/fossil |
| 162 | directory: /home/www/repos |
| 163 | </pre></blockquote> |
| 164 | Suppose the /home/www/repos directory contains files named |
| 165 | <b>one.fossil</b>, <b>two.fossil</b>, and <b>subdir/three.fossil</b>. |
| 166 | Further suppose that the name of the CGI script (relative to the root |
| 167 | of the webserver document area) is "cgis/example2". Then to |
| 168 | see the timeline for the "three.fossil" repository, the URL would be: |
| 169 | <blockquote> |
| 170 | <b>http://example.com/cgis/example2/subdir/three/timeline</b> |
| 171 | </blockquote> |
| 172 | Here is what happens: |
| 173 | <ol> |
| 174 | <li> The input URI on the HTTP request is |
| 175 | <b>/cgis/example2/subdir/three/timeline</b> |
| 176 | <li> The web server searches prefixes of the input URI until it finds |
| @@ -186,33 +197,33 @@ | |
| 186 | "subdir/three/" leaving it at just "timeline". |
| 187 | <li> Fossil looks at the rest of PATH_INFO to see that the webpage |
| 188 | requested is "timeline". |
| 189 | </ol> |
| 190 | <a id="cgivar"></a> |
| 191 | The web server sets many environment variables in step 2 in addition |
| 192 | to just PATH_INFO. The following diagram shows a few of these variables |
| 193 | and their relationship to the request URL: |
| 194 | <pre> |
| 195 | REQUEST_URI |
| 196 | ___________________|_______________________ |
| 197 | / \ |
| 198 | http://example.com/cgis/example2/subdir/three/timeline?c=55d7e1 |
| 199 | \_________/\____________/\____________________/ \______/ |
| 200 | | | | | |
| 201 | HTTP_HOST SCRIPT_NAME PATH_INFO QUERY_STRING |
| 202 | </pre> |
| 203 | </blockquote> |
| 204 | <h2>Additional CGI Script Options</h2> |
| 205 | <blockquote> |
| 206 | |
| 207 | The CGI script can have additional options used to fine-tune |
| 208 | Fossil's behavior. See the [./cgi.wiki|CGI script documentation] |
| 209 | for details. |
| 210 | |
| 211 | </blockquote> |
| 212 | <h2>Additional Observations</h2> |
| 213 | <blockquote><ol type="I"> |
| 214 | <li><p> |
| 215 | Fossil does not distinguish between the various HTTP methods (GET, PUT, |
| 216 | DELETE, etc). Fossil figures out what it needs to do purely from the |
| 217 | webpage term of the URI.</p></li> |
| 218 | <li><p> |
| @@ -239,6 +250,5 @@ | |
| 239 | <li><p> |
| 240 | Fossil is itself often launched using CGI. But Fossil can also then |
| 241 | turn around and launch [./serverext.wiki|sub-CGI scripts to implement |
| 242 | extensions].</p></li> |
| 243 | </ol> |
| 244 | </blockquote> |
| 245 |
| --- www/aboutcgi.wiki | |
| +++ www/aboutcgi.wiki | |
| @@ -1,7 +1,9 @@ | |
| 1 | <title>How CGI Works In Fossil</title> |
| 2 | |
| 3 | <h2>Introduction</h2> |
| 4 | |
| 5 | CGI or "Common Gateway Interface" is a venerable yet reliable technique for |
| 6 | generating dynamic web content. This article gives a quick background on how |
| 7 | CGI works and describes how Fossil can act as a CGI service. |
| 8 | |
| 9 | This is a "how it works" guide. This document provides background |
| @@ -8,12 +10,12 @@ | |
| 10 | information on the CGI protocol so that you can better understand what |
| 11 | is going on behind the scenes. If you just want to set up Fossil |
| 12 | as a CGI server, see the [./server/ | Fossil Server Setup] page. Or |
| 13 | if you want to development CGI-based extensions to Fossil, see |
| 14 | the [./serverext.wiki|CGI Server Extensions] page. |
| 15 | |
| 16 | <h2>A Quick Review Of CGI</h2> |
| 17 | |
| 18 | An HTTP request is a block of text that is sent by a client application |
| 19 | (usually a web browser) and arrives at the web server over a network |
| 20 | connection. The HTTP request contains a URL that describes the information |
| 21 | being requested. The URL in the HTTP request is typically the same URL |
| @@ -29,11 +31,13 @@ | |
| 31 | The web server is free to interpret the HTTP request in any way it wants. |
| 32 | But most web servers follow a similar pattern, described below. |
| 33 | (Note: details may vary from one web server to another.) |
| 34 | |
| 35 | Suppose the filename component of the URL in the HTTP request looks like this: |
| 36 | |
| 37 | <pre>/one/two/timeline/four</pre> |
| 38 | |
| 39 | Most web servers will search their content area for files that match |
| 40 | some prefix of the URL. The search starts with <b>/one</b>, then goes to |
| 41 | <b>/one/two</b>, then <b>/one/two/timeline</b>, and finally |
| 42 | <b>/one/two/timeline/four</b> is checked. The search stops at the first |
| 43 | match. |
| @@ -46,12 +50,12 @@ | |
| 50 | executes the <b>/one/two</b> script. The output generated by |
| 51 | the script is collected and repackaged as the HTTP reply. |
| 52 | |
| 53 | Before executing the CGI script, the web server will set up various |
| 54 | environment variables with information useful to the CGI script: |
| 55 | <table> |
| 56 | <tr><th>Variable<th>Meaning |
| 57 | <tr><td>GATEWAY_INTERFACE<td>Always set to "CGI/1.0" |
| 58 | <tr><td>REQUEST_URI |
| 59 | <td>The input URL from the HTTP request. |
| 60 | <tr><td>SCRIPT_NAME |
| 61 | <td>The prefix of the input URL that matches the CGI script name. |
| @@ -85,19 +89,21 @@ | |
| 89 | but a CGI script handles just one HTTP request and then exits. |
| 90 | |
| 91 | The above is a rough outline of how CGI works. |
| 92 | There are many details omitted from this brief discussion. |
| 93 | See other on-line CGI tutorials for further information. |
| 94 | |
| 95 | <h2>How Fossil Acts As A CGI Program</h2> |
| 96 | |
| 97 | An appropriate CGI script for running Fossil will look something |
| 98 | like the following: |
| 99 | |
| 100 | <pre> |
| 101 | #!/usr/bin/fossil |
| 102 | repository: /home/www/repos/project.fossil |
| 103 | </pre> |
| 104 | |
| 105 | The first line of the script is a |
| 106 | "[https://en.wikipedia.org/wiki/Shebang_%28Unix%29|shebang]" |
| 107 | that tells the operating system what program to use as the interpreter |
| 108 | for this script. On unix, when you execute a script that starts with |
| 109 | a shebang, the operating system runs the program identified by the |
| @@ -134,20 +140,21 @@ | |
| 140 | exactly the same thing to Fossil: |
| 141 | <ol type='A'> |
| 142 | <li> [https://fossil-scm.org/home/info/c14ecc43] |
| 143 | <li> [https://fossil-scm.org/home/info?name=c14ecc43] |
| 144 | </ol> |
| 145 | |
| 146 | In both cases, the CGI script is called "/fossil". For case (A), |
| 147 | the PATH_INFO variable will be "info/c14ecc43" and so the |
| 148 | "[/help?cmd=/info|/info]" webpage will be generated and the suffix of |
| 149 | PATH_INFO will be converted into the "name" query parameter, which |
| 150 | identifies the artifact about which information is requested. |
| 151 | In case (B), the PATH_INFO is just "info", but the same "name" |
| 152 | query parameter is set explicitly by the URL itself. |
| 153 | |
| 154 | <h2>Serving Multiple Fossil Repositories From One CGI Script</h2> |
| 155 | |
| 156 | The previous example showed how to serve a single Fossil repository |
| 157 | using a single CGI script. |
| 158 | On a website that wants to serve multiple repositories, one could |
| 159 | simply create multiple CGI scripts, one script for each repository. |
| 160 | But it is also possible to serve multiple Fossil repositories from |
| @@ -155,22 +162,26 @@ | |
| 162 | |
| 163 | If the CGI script for Fossil contains a "directory:" line instead of |
| 164 | a "repository:" line, then the argument to "directory:" is the name |
| 165 | of a directory that contains multiple repository files, each ending |
| 166 | with ".fossil". For example: |
| 167 | |
| 168 | <pre> |
| 169 | #!/usr/bin/fossil |
| 170 | directory: /home/www/repos |
| 171 | </pre> |
| 172 | |
| 173 | Suppose the /home/www/repos directory contains files named |
| 174 | <b>one.fossil</b>, <b>two.fossil</b>, and <b>subdir/three.fossil</b>. |
| 175 | Further suppose that the name of the CGI script (relative to the root |
| 176 | of the webserver document area) is "cgis/example2". Then to |
| 177 | see the timeline for the "three.fossil" repository, the URL would be: |
| 178 | |
| 179 | <pre> |
| 180 | http://example.com/cgis/example2/subdir/three/timeline |
| 181 | </pre> |
| 182 | |
| 183 | Here is what happens: |
| 184 | <ol> |
| 185 | <li> The input URI on the HTTP request is |
| 186 | <b>/cgis/example2/subdir/three/timeline</b> |
| 187 | <li> The web server searches prefixes of the input URI until it finds |
| @@ -186,33 +197,33 @@ | |
| 197 | "subdir/three/" leaving it at just "timeline". |
| 198 | <li> Fossil looks at the rest of PATH_INFO to see that the webpage |
| 199 | requested is "timeline". |
| 200 | </ol> |
| 201 | <a id="cgivar"></a> |
| 202 | |
| 203 | The web server sets many environment variables in step 2 in addition |
| 204 | to just PATH_INFO. The following diagram shows a few of these variables |
| 205 | and their relationship to the request URL: |
| 206 | |
| 207 | <pre> |
| 208 | REQUEST_URI |
| 209 | ___________________|_______________________ |
| 210 | / \ |
| 211 | http://example.com/cgis/example2/subdir/three/timeline?c=55d7e1 |
| 212 | \_________/\____________/\____________________/ \______/ |
| 213 | | | | | |
| 214 | HTTP_HOST SCRIPT_NAME PATH_INFO QUERY_STRING |
| 215 | </pre> |
| 216 | |
| 217 | <h2>Additional CGI Script Options</h2> |
| 218 | |
| 219 | The CGI script can have additional options used to fine-tune |
| 220 | Fossil's behavior. See the [./cgi.wiki|CGI script documentation] |
| 221 | for details. |
| 222 | |
| 223 | <h2>Additional Observations</h2> |
| 224 | <ol type="I"> |
| 225 | <li><p> |
| 226 | Fossil does not distinguish between the various HTTP methods (GET, PUT, |
| 227 | DELETE, etc). Fossil figures out what it needs to do purely from the |
| 228 | webpage term of the URI.</p></li> |
| 229 | <li><p> |
| @@ -239,6 +250,5 @@ | |
| 250 | <li><p> |
| 251 | Fossil is itself often launched using CGI. But Fossil can also then |
| 252 | turn around and launch [./serverext.wiki|sub-CGI scripts to implement |
| 253 | extensions].</p></li> |
| 254 | </ol> |
| 255 |
| --- www/aboutdownload.wiki | ||
| +++ www/aboutdownload.wiki | ||
| @@ -1,7 +1,6 @@ | ||
| 1 | 1 | <title>How The Fossil Download Page Works</title> |
| 2 | -<h1 align="center">How The Download Page Works</h1> | |
| 3 | 2 | |
| 4 | 3 | <h2>1.0 Overview</h2> |
| 5 | 4 | |
| 6 | 5 | The [/uv/download.html|Download] page for the Fossil self-hosting |
| 7 | 6 | repository is implemented using [./unvers.wiki|unversioned files]. |
| 8 | 7 |
| --- www/aboutdownload.wiki | |
| +++ www/aboutdownload.wiki | |
| @@ -1,7 +1,6 @@ | |
| 1 | <title>How The Fossil Download Page Works</title> |
| 2 | <h1 align="center">How The Download Page Works</h1> |
| 3 | |
| 4 | <h2>1.0 Overview</h2> |
| 5 | |
| 6 | The [/uv/download.html|Download] page for the Fossil self-hosting |
| 7 | repository is implemented using [./unvers.wiki|unversioned files]. |
| 8 |
| --- www/aboutdownload.wiki | |
| +++ www/aboutdownload.wiki | |
| @@ -1,7 +1,6 @@ | |
| 1 | <title>How The Fossil Download Page Works</title> |
| 2 | |
| 3 | <h2>1.0 Overview</h2> |
| 4 | |
| 5 | The [/uv/download.html|Download] page for the Fossil self-hosting |
| 6 | repository is implemented using [./unvers.wiki|unversioned files]. |
| 7 |
+8
-8
| --- www/adding_code.wiki | ||
| +++ www/adding_code.wiki | ||
| @@ -62,11 +62,11 @@ | ||
| 62 | 62 | ActiveState. |
| 63 | 63 | |
| 64 | 64 | After the makefiles have been updated, create the xyzzy.c source file |
| 65 | 65 | from the following template: |
| 66 | 66 | |
| 67 | -<blockquote><verbatim> | |
| 67 | +<verbatim> | |
| 68 | 68 | /* |
| 69 | 69 | ** Copyright boilerplate goes here. |
| 70 | 70 | ***************************************************** |
| 71 | 71 | ** High-level description of what this module goes |
| 72 | 72 | ** here. |
| @@ -78,11 +78,11 @@ | ||
| 78 | 78 | /* Exported object (structure) definitions or #defines |
| 79 | 79 | ** go here */ |
| 80 | 80 | #endif /* INTERFACE */ |
| 81 | 81 | |
| 82 | 82 | /* New code goes here */ |
| 83 | -</verbatim></blockquote> | |
| 83 | +</verbatim> | |
| 84 | 84 | |
| 85 | 85 | Note in particular the <b>#include "xyzzy.h"</b> line near the top. |
| 86 | 86 | The "xyzzy.h" file is automatically generated by makeheaders. Every |
| 87 | 87 | normal Fossil source file must have a #include at the top that imports |
| 88 | 88 | its private header file. (Some source files, such as "sqlite3.c" are |
| @@ -114,30 +114,30 @@ | ||
| 114 | 114 | The "command" is "diff". Commands may optionally be followed by |
| 115 | 115 | arguments and/or options. To create new commands in Fossil, add code |
| 116 | 116 | (either to an existing source file, or to a new source file created as |
| 117 | 117 | described above) according to the following template: |
| 118 | 118 | |
| 119 | -<blockquote><verbatim> | |
| 119 | +<verbatim> | |
| 120 | 120 | /* |
| 121 | 121 | ** COMMAND: xyzzy |
| 122 | 122 | ** |
| 123 | 123 | ** Help text goes here. Backslashes must be escaped. |
| 124 | 124 | */ |
| 125 | 125 | void xyzzy_cmd(void){ |
| 126 | 126 | /* Implement the command here */ |
| 127 | 127 | fossil_print("Hello, World!\n"); |
| 128 | 128 | } |
| 129 | -</verbatim></blockquote> | |
| 129 | +</verbatim> | |
| 130 | 130 | |
| 131 | 131 | The example above creates a new command named "xyzzy" that prints the |
| 132 | 132 | message "Hello, World!" on the console. This command is a normal command |
| 133 | 133 | that will show up in the list of command from [/help/help|fossil help]. |
| 134 | 134 | If you add an asterisk to the end of the command name, like this: |
| 135 | 135 | |
| 136 | -<blockquote><verbatim> | |
| 136 | +<verbatim> | |
| 137 | 137 | ** COMMAND: xyzzy* |
| 138 | -</verbatim></blockquote> | |
| 138 | +</verbatim> | |
| 139 | 139 | |
| 140 | 140 | Then the command will only show up if you add the "--all" option to |
| 141 | 141 | [/help/help|fossil help]. Or, if the command name starts with |
| 142 | 142 | "test" then the command will be considered experimental and will only |
| 143 | 143 | show up when the --test option is used with [/help/help|fossil help]. |
| @@ -173,20 +173,20 @@ | ||
| 173 | 173 | |
| 174 | 174 | As with commands, new webpages can be added simply by inserting a function |
| 175 | 175 | that generates the webpage together with a special header comment. A |
| 176 | 176 | template follows: |
| 177 | 177 | |
| 178 | -<blockquote><verbatim> | |
| 178 | +<verbatim> | |
| 179 | 179 | /* |
| 180 | 180 | ** WEBPAGE: helloworld |
| 181 | 181 | */ |
| 182 | 182 | void helloworld_page(void){ |
| 183 | 183 | style_header("Hello World!"); |
| 184 | 184 | @ <p>Hello, World!</p> |
| 185 | 185 | style_footer(); |
| 186 | 186 | } |
| 187 | -</verbatim></blockquote> | |
| 187 | +</verbatim> | |
| 188 | 188 | |
| 189 | 189 | Add the code above to a new or existing Fossil source code file, then |
| 190 | 190 | recompile fossil and run [/help/ui|fossil ui] then enter |
| 191 | 191 | "http://localhost:8080/helloworld" in your web browser and the routine |
| 192 | 192 | above will generate a web page that says "Hello World." |
| 193 | 193 |
| --- www/adding_code.wiki | |
| +++ www/adding_code.wiki | |
| @@ -62,11 +62,11 @@ | |
| 62 | ActiveState. |
| 63 | |
| 64 | After the makefiles have been updated, create the xyzzy.c source file |
| 65 | from the following template: |
| 66 | |
| 67 | <blockquote><verbatim> |
| 68 | /* |
| 69 | ** Copyright boilerplate goes here. |
| 70 | ***************************************************** |
| 71 | ** High-level description of what this module goes |
| 72 | ** here. |
| @@ -78,11 +78,11 @@ | |
| 78 | /* Exported object (structure) definitions or #defines |
| 79 | ** go here */ |
| 80 | #endif /* INTERFACE */ |
| 81 | |
| 82 | /* New code goes here */ |
| 83 | </verbatim></blockquote> |
| 84 | |
| 85 | Note in particular the <b>#include "xyzzy.h"</b> line near the top. |
| 86 | The "xyzzy.h" file is automatically generated by makeheaders. Every |
| 87 | normal Fossil source file must have a #include at the top that imports |
| 88 | its private header file. (Some source files, such as "sqlite3.c" are |
| @@ -114,30 +114,30 @@ | |
| 114 | The "command" is "diff". Commands may optionally be followed by |
| 115 | arguments and/or options. To create new commands in Fossil, add code |
| 116 | (either to an existing source file, or to a new source file created as |
| 117 | described above) according to the following template: |
| 118 | |
| 119 | <blockquote><verbatim> |
| 120 | /* |
| 121 | ** COMMAND: xyzzy |
| 122 | ** |
| 123 | ** Help text goes here. Backslashes must be escaped. |
| 124 | */ |
| 125 | void xyzzy_cmd(void){ |
| 126 | /* Implement the command here */ |
| 127 | fossil_print("Hello, World!\n"); |
| 128 | } |
| 129 | </verbatim></blockquote> |
| 130 | |
| 131 | The example above creates a new command named "xyzzy" that prints the |
| 132 | message "Hello, World!" on the console. This command is a normal command |
| 133 | that will show up in the list of command from [/help/help|fossil help]. |
| 134 | If you add an asterisk to the end of the command name, like this: |
| 135 | |
| 136 | <blockquote><verbatim> |
| 137 | ** COMMAND: xyzzy* |
| 138 | </verbatim></blockquote> |
| 139 | |
| 140 | Then the command will only show up if you add the "--all" option to |
| 141 | [/help/help|fossil help]. Or, if the command name starts with |
| 142 | "test" then the command will be considered experimental and will only |
| 143 | show up when the --test option is used with [/help/help|fossil help]. |
| @@ -173,20 +173,20 @@ | |
| 173 | |
| 174 | As with commands, new webpages can be added simply by inserting a function |
| 175 | that generates the webpage together with a special header comment. A |
| 176 | template follows: |
| 177 | |
| 178 | <blockquote><verbatim> |
| 179 | /* |
| 180 | ** WEBPAGE: helloworld |
| 181 | */ |
| 182 | void helloworld_page(void){ |
| 183 | style_header("Hello World!"); |
| 184 | @ <p>Hello, World!</p> |
| 185 | style_footer(); |
| 186 | } |
| 187 | </verbatim></blockquote> |
| 188 | |
| 189 | Add the code above to a new or existing Fossil source code file, then |
| 190 | recompile fossil and run [/help/ui|fossil ui] then enter |
| 191 | "http://localhost:8080/helloworld" in your web browser and the routine |
| 192 | above will generate a web page that says "Hello World." |
| 193 |
| --- www/adding_code.wiki | |
| +++ www/adding_code.wiki | |
| @@ -62,11 +62,11 @@ | |
| 62 | ActiveState. |
| 63 | |
| 64 | After the makefiles have been updated, create the xyzzy.c source file |
| 65 | from the following template: |
| 66 | |
| 67 | <verbatim> |
| 68 | /* |
| 69 | ** Copyright boilerplate goes here. |
| 70 | ***************************************************** |
| 71 | ** High-level description of what this module goes |
| 72 | ** here. |
| @@ -78,11 +78,11 @@ | |
| 78 | /* Exported object (structure) definitions or #defines |
| 79 | ** go here */ |
| 80 | #endif /* INTERFACE */ |
| 81 | |
| 82 | /* New code goes here */ |
| 83 | </verbatim> |
| 84 | |
| 85 | Note in particular the <b>#include "xyzzy.h"</b> line near the top. |
| 86 | The "xyzzy.h" file is automatically generated by makeheaders. Every |
| 87 | normal Fossil source file must have a #include at the top that imports |
| 88 | its private header file. (Some source files, such as "sqlite3.c" are |
| @@ -114,30 +114,30 @@ | |
| 114 | The "command" is "diff". Commands may optionally be followed by |
| 115 | arguments and/or options. To create new commands in Fossil, add code |
| 116 | (either to an existing source file, or to a new source file created as |
| 117 | described above) according to the following template: |
| 118 | |
| 119 | <verbatim> |
| 120 | /* |
| 121 | ** COMMAND: xyzzy |
| 122 | ** |
| 123 | ** Help text goes here. Backslashes must be escaped. |
| 124 | */ |
| 125 | void xyzzy_cmd(void){ |
| 126 | /* Implement the command here */ |
| 127 | fossil_print("Hello, World!\n"); |
| 128 | } |
| 129 | </verbatim> |
| 130 | |
| 131 | The example above creates a new command named "xyzzy" that prints the |
| 132 | message "Hello, World!" on the console. This command is a normal command |
| 133 | that will show up in the list of command from [/help/help|fossil help]. |
| 134 | If you add an asterisk to the end of the command name, like this: |
| 135 | |
| 136 | <verbatim> |
| 137 | ** COMMAND: xyzzy* |
| 138 | </verbatim> |
| 139 | |
| 140 | Then the command will only show up if you add the "--all" option to |
| 141 | [/help/help|fossil help]. Or, if the command name starts with |
| 142 | "test" then the command will be considered experimental and will only |
| 143 | show up when the --test option is used with [/help/help|fossil help]. |
| @@ -173,20 +173,20 @@ | |
| 173 | |
| 174 | As with commands, new webpages can be added simply by inserting a function |
| 175 | that generates the webpage together with a special header comment. A |
| 176 | template follows: |
| 177 | |
| 178 | <verbatim> |
| 179 | /* |
| 180 | ** WEBPAGE: helloworld |
| 181 | */ |
| 182 | void helloworld_page(void){ |
| 183 | style_header("Hello World!"); |
| 184 | @ <p>Hello, World!</p> |
| 185 | style_footer(); |
| 186 | } |
| 187 | </verbatim> |
| 188 | |
| 189 | Add the code above to a new or existing Fossil source code file, then |
| 190 | recompile fossil and run [/help/ui|fossil ui] then enter |
| 191 | "http://localhost:8080/helloworld" in your web browser and the routine |
| 192 | above will generate a web page that says "Hello World." |
| 193 |
+16
-19
| --- www/alerts.md | ||
| +++ www/alerts.md | ||
| @@ -91,15 +91,15 @@ | ||
| 91 | 91 | |
| 92 | 92 | Save your changes. |
| 93 | 93 | |
| 94 | 94 | At the command line, say |
| 95 | 95 | |
| 96 | - $ fossil set email-send-command | |
| 96 | + $ fossil set email-send-command | |
| 97 | 97 | |
| 98 | 98 | If that gives a blank value instead of `sendmail -ti`, say |
| 99 | 99 | |
| 100 | - $ fossil set email-send-command "sendmail -ti" | |
| 100 | + $ fossil set email-send-command "sendmail -ti" | |
| 101 | 101 | |
| 102 | 102 | to force the setting. That works around a [known |
| 103 | 103 | bug](https://fossil-scm.org/forum/forumpost/840b676410) which may be |
| 104 | 104 | squished by the time you read this. |
| 105 | 105 | |
| @@ -113,13 +113,13 @@ | ||
| 113 | 113 | |
| 114 | 114 | <a id="status"></a> |
| 115 | 115 | If you reload the Admin → Notification page, the Status section at the |
| 116 | 116 | top should show: |
| 117 | 117 | |
| 118 | - Outgoing Email: Piped to command "sendmail -ti" | |
| 119 | - Pending Alerts: 0 normal, 0 digest | |
| 120 | - Subscribers: 0 active, 0 total | |
| 118 | + Outgoing Email: Piped to command "sendmail -ti" | |
| 119 | + Pending Alerts: 0 normal, 0 digest | |
| 120 | + Subscribers: 0 active, 0 total | |
| 121 | 121 | |
| 122 | 122 | Before you move on to the next section, you might like to read up on |
| 123 | 123 | [some subtleties](#pipe) with the "pipe to a command" method that we did |
| 124 | 124 | not cover above. |
| 125 | 125 | |
| @@ -155,14 +155,11 @@ | ||
| 155 | 155 | are the two records tied together under the hood. For more on this, see |
| 156 | 156 | [Users vs Subscribers below](#uvs). |
| 157 | 157 | |
| 158 | 158 | If you are seeing the following complaint from Fossil: |
| 159 | 159 | |
| 160 | -<blockquote> | |
| 161 | - Use a different login with greater privilege than FOO to access | |
| 162 | - /subscribe | |
| 163 | -</blockquote> | |
| 160 | +> Use a different login with greater privilege than FOO to access /subscribe | |
| 164 | 161 | |
| 165 | 162 | ...then the repository's administrator forgot to give the |
| 166 | 163 | [**EmailAlert** capability][cap7] |
| 167 | 164 | to that user or to a user category that the user is a member of. |
| 168 | 165 | |
| @@ -214,11 +211,11 @@ | ||
| 214 | 211 | message below, then press "Send Message" to verify that outgoing email |
| 215 | 212 | is working. |
| 216 | 213 | |
| 217 | 214 | Another method is from the command line: |
| 218 | 215 | |
| 219 | - $ fossil alerts test-message [email protected] --body README.md --subject Test | |
| 216 | + $ fossil alerts test-message [email protected] --body README.md --subject Test | |
| 220 | 217 | |
| 221 | 218 | That should send you an email with "Test" in the subject line and the |
| 222 | 219 | contents of your project's `README.md` file in the body. |
| 223 | 220 | |
| 224 | 221 | That command assumes that your project contains a "readme" file, but of |
| @@ -264,38 +261,38 @@ | ||
| 264 | 261 | If email alerts aren't working, there are several useful commands you |
| 265 | 262 | can give to figure out why. |
| 266 | 263 | |
| 267 | 264 | (Be sure to [`cd` into a repo checkout directory](#cd) first!) |
| 268 | 265 | |
| 269 | - $ fossil alerts status | |
| 266 | + $ fossil alerts status | |
| 270 | 267 | |
| 271 | 268 | This should give much the same information as you saw [above](#status). |
| 272 | 269 | One difference is that, since you've created a forum post, the |
| 273 | 270 | `pending-alerts` value should only be zero if you did in fact get the |
| 274 | 271 | requested email alert. If it's zero, check your mailer's spam folder. If |
| 275 | 272 | it's nonzero, continue with these troubleshooting steps. |
| 276 | 273 | |
| 277 | - $ fossil backoffice | |
| 274 | + $ fossil backoffice | |
| 278 | 275 | |
| 279 | 276 | That forces Fossil to run its ["back office" process](./backoffice.md). |
| 280 | 277 | Its only purpose at the time of this writing is to push out alert |
| 281 | 278 | emails, but it might do other things later. Sometimes it can get stuck |
| 282 | 279 | and needs to be kicked. For that reason, you might want to set up a |
| 283 | 280 | crontab entry to make sure it runs occasionally. |
| 284 | 281 | |
| 285 | - $ fossil alerts send | |
| 282 | + $ fossil alerts send | |
| 286 | 283 | |
| 287 | 284 | This should also kick off the backoffice processing, if there are any |
| 288 | 285 | pending alerts to send out. |
| 289 | 286 | |
| 290 | - $ fossil alert pending | |
| 287 | + $ fossil alert pending | |
| 291 | 288 | |
| 292 | 289 | Show any pending alerts. The number of lines output here should equal |
| 293 | 290 | the [status output above](#status). |
| 294 | 291 | |
| 295 | - $ fossil test-add-alerts f5900 | |
| 296 | - $ fossil alert send | |
| 292 | + $ fossil test-add-alerts f5900 | |
| 293 | + $ fossil alert send | |
| 297 | 294 | |
| 298 | 295 | Manually create an email alert and push it out immediately. |
| 299 | 296 | |
| 300 | 297 | The `f` in the first command's final parameter means you're scheduling a |
| 301 | 298 | "forum" alert. The integer is the ID of a forum post, which you can find |
| @@ -302,11 +299,11 @@ | ||
| 302 | 299 | by visiting `/timeline?showid` on your Fossil instance. |
| 303 | 300 | |
| 304 | 301 | The second command above is necessary because the `test-add-alerts` |
| 305 | 302 | command doesn't kick off a backoffice run. |
| 306 | 303 | |
| 307 | - $ fossil ale send | |
| 304 | + $ fossil ale send | |
| 308 | 305 | |
| 309 | 306 | This only does the same thing as the final command above, rather than |
| 310 | 307 | send you an ale, as you might be hoping. Sorry. |
| 311 | 308 | |
| 312 | 309 | |
| @@ -424,11 +421,11 @@ | ||
| 424 | 421 | |
| 425 | 422 | You can start this Tcl script as a daemon automatically on most Unix and |
| 426 | 423 | Unix-like systems by adding the following line to the `/etc/rc.local` |
| 427 | 424 | file of the server that hosts the repository sending email alerts: |
| 428 | 425 | |
| 429 | - /usr/bin/tclsh /home/www/fossil/email-sender.tcl & | |
| 426 | + /usr/bin/tclsh /home/www/fossil/email-sender.tcl & | |
| 430 | 427 | |
| 431 | 428 | [cj]: https://en.wikipedia.org/wiki/Chroot |
| 432 | 429 | [rdbc]: https://www.sqlite.org/howtocorrupt.html#_filesystems_with_broken_or_missing_lock_implementations |
| 433 | 430 | |
| 434 | 431 | |
| @@ -683,11 +680,11 @@ | ||
| 683 | 680 | far as I can see. |
| 684 | 681 | |
| 685 | 682 | If the `subscriberCodes` for a Fossil repository are ever compromised, |
| 686 | 683 | new ones can be generated as follows: |
| 687 | 684 | |
| 688 | - UPDATE subscriber SET subscriberCode=randomblob(32); | |
| 685 | + UPDATE subscriber SET subscriberCode=randomblob(32); | |
| 689 | 686 | |
| 690 | 687 | Since this then affects all new email alerts going out from Fossil, your |
| 691 | 688 | end users may never even realize that they're getting new codes, as long |
| 692 | 689 | as they don't click on the URLs in the footer of old alert messages. |
| 693 | 690 | |
| 694 | 691 |
| --- www/alerts.md | |
| +++ www/alerts.md | |
| @@ -91,15 +91,15 @@ | |
| 91 | |
| 92 | Save your changes. |
| 93 | |
| 94 | At the command line, say |
| 95 | |
| 96 | $ fossil set email-send-command |
| 97 | |
| 98 | If that gives a blank value instead of `sendmail -ti`, say |
| 99 | |
| 100 | $ fossil set email-send-command "sendmail -ti" |
| 101 | |
| 102 | to force the setting. That works around a [known |
| 103 | bug](https://fossil-scm.org/forum/forumpost/840b676410) which may be |
| 104 | squished by the time you read this. |
| 105 | |
| @@ -113,13 +113,13 @@ | |
| 113 | |
| 114 | <a id="status"></a> |
| 115 | If you reload the Admin → Notification page, the Status section at the |
| 116 | top should show: |
| 117 | |
| 118 | Outgoing Email: Piped to command "sendmail -ti" |
| 119 | Pending Alerts: 0 normal, 0 digest |
| 120 | Subscribers: 0 active, 0 total |
| 121 | |
| 122 | Before you move on to the next section, you might like to read up on |
| 123 | [some subtleties](#pipe) with the "pipe to a command" method that we did |
| 124 | not cover above. |
| 125 | |
| @@ -155,14 +155,11 @@ | |
| 155 | are the two records tied together under the hood. For more on this, see |
| 156 | [Users vs Subscribers below](#uvs). |
| 157 | |
| 158 | If you are seeing the following complaint from Fossil: |
| 159 | |
| 160 | <blockquote> |
| 161 | Use a different login with greater privilege than FOO to access |
| 162 | /subscribe |
| 163 | </blockquote> |
| 164 | |
| 165 | ...then the repository's administrator forgot to give the |
| 166 | [**EmailAlert** capability][cap7] |
| 167 | to that user or to a user category that the user is a member of. |
| 168 | |
| @@ -214,11 +211,11 @@ | |
| 214 | message below, then press "Send Message" to verify that outgoing email |
| 215 | is working. |
| 216 | |
| 217 | Another method is from the command line: |
| 218 | |
| 219 | $ fossil alerts test-message [email protected] --body README.md --subject Test |
| 220 | |
| 221 | That should send you an email with "Test" in the subject line and the |
| 222 | contents of your project's `README.md` file in the body. |
| 223 | |
| 224 | That command assumes that your project contains a "readme" file, but of |
| @@ -264,38 +261,38 @@ | |
| 264 | If email alerts aren't working, there are several useful commands you |
| 265 | can give to figure out why. |
| 266 | |
| 267 | (Be sure to [`cd` into a repo checkout directory](#cd) first!) |
| 268 | |
| 269 | $ fossil alerts status |
| 270 | |
| 271 | This should give much the same information as you saw [above](#status). |
| 272 | One difference is that, since you've created a forum post, the |
| 273 | `pending-alerts` value should only be zero if you did in fact get the |
| 274 | requested email alert. If it's zero, check your mailer's spam folder. If |
| 275 | it's nonzero, continue with these troubleshooting steps. |
| 276 | |
| 277 | $ fossil backoffice |
| 278 | |
| 279 | That forces Fossil to run its ["back office" process](./backoffice.md). |
| 280 | Its only purpose at the time of this writing is to push out alert |
| 281 | emails, but it might do other things later. Sometimes it can get stuck |
| 282 | and needs to be kicked. For that reason, you might want to set up a |
| 283 | crontab entry to make sure it runs occasionally. |
| 284 | |
| 285 | $ fossil alerts send |
| 286 | |
| 287 | This should also kick off the backoffice processing, if there are any |
| 288 | pending alerts to send out. |
| 289 | |
| 290 | $ fossil alert pending |
| 291 | |
| 292 | Show any pending alerts. The number of lines output here should equal |
| 293 | the [status output above](#status). |
| 294 | |
| 295 | $ fossil test-add-alerts f5900 |
| 296 | $ fossil alert send |
| 297 | |
| 298 | Manually create an email alert and push it out immediately. |
| 299 | |
| 300 | The `f` in the first command's final parameter means you're scheduling a |
| 301 | "forum" alert. The integer is the ID of a forum post, which you can find |
| @@ -302,11 +299,11 @@ | |
| 302 | by visiting `/timeline?showid` on your Fossil instance. |
| 303 | |
| 304 | The second command above is necessary because the `test-add-alerts` |
| 305 | command doesn't kick off a backoffice run. |
| 306 | |
| 307 | $ fossil ale send |
| 308 | |
| 309 | This only does the same thing as the final command above, rather than |
| 310 | send you an ale, as you might be hoping. Sorry. |
| 311 | |
| 312 | |
| @@ -424,11 +421,11 @@ | |
| 424 | |
| 425 | You can start this Tcl script as a daemon automatically on most Unix and |
| 426 | Unix-like systems by adding the following line to the `/etc/rc.local` |
| 427 | file of the server that hosts the repository sending email alerts: |
| 428 | |
| 429 | /usr/bin/tclsh /home/www/fossil/email-sender.tcl & |
| 430 | |
| 431 | [cj]: https://en.wikipedia.org/wiki/Chroot |
| 432 | [rdbc]: https://www.sqlite.org/howtocorrupt.html#_filesystems_with_broken_or_missing_lock_implementations |
| 433 | |
| 434 | |
| @@ -683,11 +680,11 @@ | |
| 683 | far as I can see. |
| 684 | |
| 685 | If the `subscriberCodes` for a Fossil repository are ever compromised, |
| 686 | new ones can be generated as follows: |
| 687 | |
| 688 | UPDATE subscriber SET subscriberCode=randomblob(32); |
| 689 | |
| 690 | Since this then affects all new email alerts going out from Fossil, your |
| 691 | end users may never even realize that they're getting new codes, as long |
| 692 | as they don't click on the URLs in the footer of old alert messages. |
| 693 | |
| 694 |
| --- www/alerts.md | |
| +++ www/alerts.md | |
| @@ -91,15 +91,15 @@ | |
| 91 | |
| 92 | Save your changes. |
| 93 | |
| 94 | At the command line, say |
| 95 | |
| 96 | $ fossil set email-send-command |
| 97 | |
| 98 | If that gives a blank value instead of `sendmail -ti`, say |
| 99 | |
| 100 | $ fossil set email-send-command "sendmail -ti" |
| 101 | |
| 102 | to force the setting. That works around a [known |
| 103 | bug](https://fossil-scm.org/forum/forumpost/840b676410) which may be |
| 104 | squished by the time you read this. |
| 105 | |
| @@ -113,13 +113,13 @@ | |
| 113 | |
| 114 | <a id="status"></a> |
| 115 | If you reload the Admin → Notification page, the Status section at the |
| 116 | top should show: |
| 117 | |
| 118 | Outgoing Email: Piped to command "sendmail -ti" |
| 119 | Pending Alerts: 0 normal, 0 digest |
| 120 | Subscribers: 0 active, 0 total |
| 121 | |
| 122 | Before you move on to the next section, you might like to read up on |
| 123 | [some subtleties](#pipe) with the "pipe to a command" method that we did |
| 124 | not cover above. |
| 125 | |
| @@ -155,14 +155,11 @@ | |
| 155 | are the two records tied together under the hood. For more on this, see |
| 156 | [Users vs Subscribers below](#uvs). |
| 157 | |
| 158 | If you are seeing the following complaint from Fossil: |
| 159 | |
| 160 | > Use a different login with greater privilege than FOO to access /subscribe |
| 161 | |
| 162 | ...then the repository's administrator forgot to give the |
| 163 | [**EmailAlert** capability][cap7] |
| 164 | to that user or to a user category that the user is a member of. |
| 165 | |
| @@ -214,11 +211,11 @@ | |
| 211 | message below, then press "Send Message" to verify that outgoing email |
| 212 | is working. |
| 213 | |
| 214 | Another method is from the command line: |
| 215 | |
| 216 | $ fossil alerts test-message [email protected] --body README.md --subject Test |
| 217 | |
| 218 | That should send you an email with "Test" in the subject line and the |
| 219 | contents of your project's `README.md` file in the body. |
| 220 | |
| 221 | That command assumes that your project contains a "readme" file, but of |
| @@ -264,38 +261,38 @@ | |
| 261 | If email alerts aren't working, there are several useful commands you |
| 262 | can give to figure out why. |
| 263 | |
| 264 | (Be sure to [`cd` into a repo checkout directory](#cd) first!) |
| 265 | |
| 266 | $ fossil alerts status |
| 267 | |
| 268 | This should give much the same information as you saw [above](#status). |
| 269 | One difference is that, since you've created a forum post, the |
| 270 | `pending-alerts` value should only be zero if you did in fact get the |
| 271 | requested email alert. If it's zero, check your mailer's spam folder. If |
| 272 | it's nonzero, continue with these troubleshooting steps. |
| 273 | |
| 274 | $ fossil backoffice |
| 275 | |
| 276 | That forces Fossil to run its ["back office" process](./backoffice.md). |
| 277 | Its only purpose at the time of this writing is to push out alert |
| 278 | emails, but it might do other things later. Sometimes it can get stuck |
| 279 | and needs to be kicked. For that reason, you might want to set up a |
| 280 | crontab entry to make sure it runs occasionally. |
| 281 | |
| 282 | $ fossil alerts send |
| 283 | |
| 284 | This should also kick off the backoffice processing, if there are any |
| 285 | pending alerts to send out. |
| 286 | |
| 287 | $ fossil alert pending |
| 288 | |
| 289 | Show any pending alerts. The number of lines output here should equal |
| 290 | the [status output above](#status). |
| 291 | |
| 292 | $ fossil test-add-alerts f5900 |
| 293 | $ fossil alert send |
| 294 | |
| 295 | Manually create an email alert and push it out immediately. |
| 296 | |
| 297 | The `f` in the first command's final parameter means you're scheduling a |
| 298 | "forum" alert. The integer is the ID of a forum post, which you can find |
| @@ -302,11 +299,11 @@ | |
| 299 | by visiting `/timeline?showid` on your Fossil instance. |
| 300 | |
| 301 | The second command above is necessary because the `test-add-alerts` |
| 302 | command doesn't kick off a backoffice run. |
| 303 | |
| 304 | $ fossil ale send |
| 305 | |
| 306 | This only does the same thing as the final command above, rather than |
| 307 | send you an ale, as you might be hoping. Sorry. |
| 308 | |
| 309 | |
| @@ -424,11 +421,11 @@ | |
| 421 | |
| 422 | You can start this Tcl script as a daemon automatically on most Unix and |
| 423 | Unix-like systems by adding the following line to the `/etc/rc.local` |
| 424 | file of the server that hosts the repository sending email alerts: |
| 425 | |
| 426 | /usr/bin/tclsh /home/www/fossil/email-sender.tcl & |
| 427 | |
| 428 | [cj]: https://en.wikipedia.org/wiki/Chroot |
| 429 | [rdbc]: https://www.sqlite.org/howtocorrupt.html#_filesystems_with_broken_or_missing_lock_implementations |
| 430 | |
| 431 | |
| @@ -683,11 +680,11 @@ | |
| 680 | far as I can see. |
| 681 | |
| 682 | If the `subscriberCodes` for a Fossil repository are ever compromised, |
| 683 | new ones can be generated as follows: |
| 684 | |
| 685 | UPDATE subscriber SET subscriberCode=randomblob(32); |
| 686 | |
| 687 | Since this then affects all new email alerts going out from Fossil, your |
| 688 | end users may never even realize that they're getting new codes, as long |
| 689 | as they don't click on the URLs in the footer of old alert messages. |
| 690 | |
| 691 |
+5
-5
| --- www/backoffice.md | ||
| +++ www/backoffice.md | ||
| @@ -79,11 +79,11 @@ | ||
| 79 | 79 | being accessed, then the automatic backoffice will never run, and the |
| 80 | 80 | daily digest might not go out until somebody does visit a webpage. |
| 81 | 81 | If this is a problem, an administrator can set up a cron job to |
| 82 | 82 | periodically run: |
| 83 | 83 | |
| 84 | -> fossil backoffice _REPOSITORY_ | |
| 84 | + fossil backoffice _REPOSITORY_ | |
| 85 | 85 | |
| 86 | 86 | That command will cause backoffice processing to occur immediately. |
| 87 | 87 | Note that this is almost never necessary for an internet-facing |
| 88 | 88 | Fossil repository, since most repositories will get multiple accesses |
| 89 | 89 | per day from random robots, which will be sufficient to kick off the |
| @@ -102,16 +102,16 @@ | ||
| 102 | 102 | on OpenBSD systems. |
| 103 | 103 | |
| 104 | 104 | To set up fully-manual backoffice, first disable the automatic backoffice |
| 105 | 105 | using the "[backoffice-disable](/help?cmd=backoffice-disable)" setting. |
| 106 | 106 | |
| 107 | -> fossil setting backoffice-disable on | |
| 107 | + fossil setting backoffice-disable on | |
| 108 | 108 | |
| 109 | 109 | Then arrange to invoke the backoffice separately using a command |
| 110 | 110 | like this: |
| 111 | 111 | |
| 112 | -> fossil backoffice --poll 30 _REPOSITORY-LIST_ | |
| 112 | + fossil backoffice --poll 30 _REPOSITORY-LIST_ | |
| 113 | 113 | |
| 114 | 114 | Multiple repositories can be named. This one command will handle |
| 115 | 115 | launching the backoffice for all of them. There are additional useful |
| 116 | 116 | command-line options. See the "[fossil backoffice](/help?cmd=backoffice)" |
| 117 | 117 | documentation for details. |
| @@ -147,11 +147,11 @@ | ||
| 147 | 147 | not a process still exists. |
| 148 | 148 | |
| 149 | 149 | You can print out a decoded copy of the current backoffice lease using |
| 150 | 150 | this command: |
| 151 | 151 | |
| 152 | -> fossil test-backoffice-lease -R _REPOSITORY_ | |
| 152 | + fossil test-backoffice-lease -R _REPOSITORY_ | |
| 153 | 153 | |
| 154 | 154 | If a system has been idle for a long time, then there will be no |
| 155 | 155 | backoffice processes. (Either the process id entries in the lease |
| 156 | 156 | will be zero, or there will exist no process associated with the |
| 157 | 157 | process id.) When a new web request comes in, the system |
| @@ -197,11 +197,11 @@ | ||
| 197 | 197 | there are some debugging aids. |
| 198 | 198 | |
| 199 | 199 | We have already mentioned the command that shows the backoffice lease |
| 200 | 200 | for a repository: |
| 201 | 201 | |
| 202 | -> fossil test-backoffice-lease -R _REPOSITORY_ | |
| 202 | + fossil test-backoffice-lease -R _REPOSITORY_ | |
| 203 | 203 | |
| 204 | 204 | Running that command every few seconds should show what is going on with |
| 205 | 205 | backoffice processing in a particular repository. |
| 206 | 206 | |
| 207 | 207 | There are also settings that control backoffice behavior. The |
| 208 | 208 |
| --- www/backoffice.md | |
| +++ www/backoffice.md | |
| @@ -79,11 +79,11 @@ | |
| 79 | being accessed, then the automatic backoffice will never run, and the |
| 80 | daily digest might not go out until somebody does visit a webpage. |
| 81 | If this is a problem, an administrator can set up a cron job to |
| 82 | periodically run: |
| 83 | |
| 84 | > fossil backoffice _REPOSITORY_ |
| 85 | |
| 86 | That command will cause backoffice processing to occur immediately. |
| 87 | Note that this is almost never necessary for an internet-facing |
| 88 | Fossil repository, since most repositories will get multiple accesses |
| 89 | per day from random robots, which will be sufficient to kick off the |
| @@ -102,16 +102,16 @@ | |
| 102 | on OpenBSD systems. |
| 103 | |
| 104 | To set up fully-manual backoffice, first disable the automatic backoffice |
| 105 | using the "[backoffice-disable](/help?cmd=backoffice-disable)" setting. |
| 106 | |
| 107 | > fossil setting backoffice-disable on |
| 108 | |
| 109 | Then arrange to invoke the backoffice separately using a command |
| 110 | like this: |
| 111 | |
| 112 | > fossil backoffice --poll 30 _REPOSITORY-LIST_ |
| 113 | |
| 114 | Multiple repositories can be named. This one command will handle |
| 115 | launching the backoffice for all of them. There are additional useful |
| 116 | command-line options. See the "[fossil backoffice](/help?cmd=backoffice)" |
| 117 | documentation for details. |
| @@ -147,11 +147,11 @@ | |
| 147 | not a process still exists. |
| 148 | |
| 149 | You can print out a decoded copy of the current backoffice lease using |
| 150 | this command: |
| 151 | |
| 152 | > fossil test-backoffice-lease -R _REPOSITORY_ |
| 153 | |
| 154 | If a system has been idle for a long time, then there will be no |
| 155 | backoffice processes. (Either the process id entries in the lease |
| 156 | will be zero, or there will exist no process associated with the |
| 157 | process id.) When a new web request comes in, the system |
| @@ -197,11 +197,11 @@ | |
| 197 | there are some debugging aids. |
| 198 | |
| 199 | We have already mentioned the command that shows the backoffice lease |
| 200 | for a repository: |
| 201 | |
| 202 | > fossil test-backoffice-lease -R _REPOSITORY_ |
| 203 | |
| 204 | Running that command every few seconds should show what is going on with |
| 205 | backoffice processing in a particular repository. |
| 206 | |
| 207 | There are also settings that control backoffice behavior. The |
| 208 |
| --- www/backoffice.md | |
| +++ www/backoffice.md | |
| @@ -79,11 +79,11 @@ | |
| 79 | being accessed, then the automatic backoffice will never run, and the |
| 80 | daily digest might not go out until somebody does visit a webpage. |
| 81 | If this is a problem, an administrator can set up a cron job to |
| 82 | periodically run: |
| 83 | |
| 84 | fossil backoffice _REPOSITORY_ |
| 85 | |
| 86 | That command will cause backoffice processing to occur immediately. |
| 87 | Note that this is almost never necessary for an internet-facing |
| 88 | Fossil repository, since most repositories will get multiple accesses |
| 89 | per day from random robots, which will be sufficient to kick off the |
| @@ -102,16 +102,16 @@ | |
| 102 | on OpenBSD systems. |
| 103 | |
| 104 | To set up fully-manual backoffice, first disable the automatic backoffice |
| 105 | using the "[backoffice-disable](/help?cmd=backoffice-disable)" setting. |
| 106 | |
| 107 | fossil setting backoffice-disable on |
| 108 | |
| 109 | Then arrange to invoke the backoffice separately using a command |
| 110 | like this: |
| 111 | |
| 112 | fossil backoffice --poll 30 _REPOSITORY-LIST_ |
| 113 | |
| 114 | Multiple repositories can be named. This one command will handle |
| 115 | launching the backoffice for all of them. There are additional useful |
| 116 | command-line options. See the "[fossil backoffice](/help?cmd=backoffice)" |
| 117 | documentation for details. |
| @@ -147,11 +147,11 @@ | |
| 147 | not a process still exists. |
| 148 | |
| 149 | You can print out a decoded copy of the current backoffice lease using |
| 150 | this command: |
| 151 | |
| 152 | fossil test-backoffice-lease -R _REPOSITORY_ |
| 153 | |
| 154 | If a system has been idle for a long time, then there will be no |
| 155 | backoffice processes. (Either the process id entries in the lease |
| 156 | will be zero, or there will exist no process associated with the |
| 157 | process id.) When a new web request comes in, the system |
| @@ -197,11 +197,11 @@ | |
| 197 | there are some debugging aids. |
| 198 | |
| 199 | We have already mentioned the command that shows the backoffice lease |
| 200 | for a repository: |
| 201 | |
| 202 | fossil test-backoffice-lease -R _REPOSITORY_ |
| 203 | |
| 204 | Running that command every few seconds should show what is going on with |
| 205 | backoffice processing in a particular repository. |
| 206 | |
| 207 | There are also settings that control backoffice behavior. The |
| 208 |
+2
-2
| --- www/backup.md | ||
| +++ www/backup.md | ||
| @@ -262,12 +262,12 @@ | ||
| 262 | 262 | than give up on the security afforded by use of configurable-iteration |
| 263 | 263 | PBKDF2. To avoid a conflict with the platform’s `openssl` binary, |
| 264 | 264 | Homebrew’s installation is [unlinked][hbul] by default, so you have to |
| 265 | 265 | give an explicit path to it, one of: |
| 266 | 266 | |
| 267 | - /usr/local/opt/openssl/bin/openssl ... # Intel x86 Macs | |
| 268 | - /opt/homebrew/opt/openssl/bin/openssl ... # ARM Macs (“Apple silicon”) | |
| 267 | + /usr/local/opt/openssl/bin/openssl ... # Intel x86 Macs | |
| 268 | + /opt/homebrew/opt/openssl/bin/openssl ... # ARM Macs (“Apple silicon”) | |
| 269 | 269 | |
| 270 | 270 | [lssl]: https://www.libressl.org/ |
| 271 | 271 | |
| 272 | 272 | |
| 273 | 273 | ## <a id="rest"></a> Restoring From An Encrypted Backup |
| 274 | 274 |
| --- www/backup.md | |
| +++ www/backup.md | |
| @@ -262,12 +262,12 @@ | |
| 262 | than give up on the security afforded by use of configurable-iteration |
| 263 | PBKDF2. To avoid a conflict with the platform’s `openssl` binary, |
| 264 | Homebrew’s installation is [unlinked][hbul] by default, so you have to |
| 265 | give an explicit path to it, one of: |
| 266 | |
| 267 | /usr/local/opt/openssl/bin/openssl ... # Intel x86 Macs |
| 268 | /opt/homebrew/opt/openssl/bin/openssl ... # ARM Macs (“Apple silicon”) |
| 269 | |
| 270 | [lssl]: https://www.libressl.org/ |
| 271 | |
| 272 | |
| 273 | ## <a id="rest"></a> Restoring From An Encrypted Backup |
| 274 |
| --- www/backup.md | |
| +++ www/backup.md | |
| @@ -262,12 +262,12 @@ | |
| 262 | than give up on the security afforded by use of configurable-iteration |
| 263 | PBKDF2. To avoid a conflict with the platform’s `openssl` binary, |
| 264 | Homebrew’s installation is [unlinked][hbul] by default, so you have to |
| 265 | give an explicit path to it, one of: |
| 266 | |
| 267 | /usr/local/opt/openssl/bin/openssl ... # Intel x86 Macs |
| 268 | /opt/homebrew/opt/openssl/bin/openssl ... # ARM Macs (“Apple silicon”) |
| 269 | |
| 270 | [lssl]: https://www.libressl.org/ |
| 271 | |
| 272 | |
| 273 | ## <a id="rest"></a> Restoring From An Encrypted Backup |
| 274 |
+4
-4
| --- www/branching.wiki | ||
| +++ www/branching.wiki | ||
| @@ -246,13 +246,13 @@ | ||
| 246 | 246 | branching as intentional forking and the naming of forks as branches. |
| 247 | 247 | They are in fact separate concepts, but since Fossil is intended to be |
| 248 | 248 | used primarily by humans, we combine them in Fossil's human user |
| 249 | 249 | interfaces. |
| 250 | 250 | |
| 251 | -<blockquote> | |
| 251 | +<p class="blockquote"> | |
| 252 | 252 | <b>Key Distinction:</b> A branch is a <i>named, intentional</i> fork. |
| 253 | -</blockquote> | |
| 253 | +</p> | |
| 254 | 254 | |
| 255 | 255 | Unnamed forks <i>may</i> be intentional, but most of the time, they're |
| 256 | 256 | accidental and left unnamed. |
| 257 | 257 | |
| 258 | 258 | Fossil offers two primary ways to create named, intentional forks, |
| @@ -695,11 +695,11 @@ | ||
| 695 | 695 | painless to fix them] when they do occur. |
| 696 | 696 | |
| 697 | 697 | |
| 698 | 698 | <h2>Review Of Terminology</h2> |
| 699 | 699 | |
| 700 | -<blockquote><dl> | |
| 700 | +<dl> | |
| 701 | 701 | <dt><b>Branch</b></dt> |
| 702 | 702 | <dd><p>A branch is a set of check-ins with the same value for their |
| 703 | 703 | "branch" property.</p></dd> |
| 704 | 704 | <dt><b>Leaf</b></dt> |
| 705 | 705 | <dd><p>A leaf is a check-in with no children in the same branch.</p></dd> |
| @@ -714,11 +714,11 @@ | ||
| 714 | 714 | children in the same branch.</p></dd> |
| 715 | 715 | <dt><b>Branch Point</b></dt> |
| 716 | 716 | <dd><p>A branch point occurs when a check-in has two or more direct (non-merge) |
| 717 | 717 | children in different branches. A branch point is similar to a fork, |
| 718 | 718 | except that the children are in different branches.</p></dd> |
| 719 | -</dl></blockquote> | |
| 719 | +</dl> | |
| 720 | 720 | |
| 721 | 721 | Check-in 4 of Figure 3 is not a leaf because it has a child (check-in 5) |
| 722 | 722 | in the same branch. Check-in 9 of Figure 5 also has a child (check-in 10) |
| 723 | 723 | but that child is in a different branch, so check-in 9 is a leaf. Because |
| 724 | 724 | of the <b>closed</b> tag on check-in 9, it is a closed leaf. |
| 725 | 725 |
| --- www/branching.wiki | |
| +++ www/branching.wiki | |
| @@ -246,13 +246,13 @@ | |
| 246 | branching as intentional forking and the naming of forks as branches. |
| 247 | They are in fact separate concepts, but since Fossil is intended to be |
| 248 | used primarily by humans, we combine them in Fossil's human user |
| 249 | interfaces. |
| 250 | |
| 251 | <blockquote> |
| 252 | <b>Key Distinction:</b> A branch is a <i>named, intentional</i> fork. |
| 253 | </blockquote> |
| 254 | |
| 255 | Unnamed forks <i>may</i> be intentional, but most of the time, they're |
| 256 | accidental and left unnamed. |
| 257 | |
| 258 | Fossil offers two primary ways to create named, intentional forks, |
| @@ -695,11 +695,11 @@ | |
| 695 | painless to fix them] when they do occur. |
| 696 | |
| 697 | |
| 698 | <h2>Review Of Terminology</h2> |
| 699 | |
| 700 | <blockquote><dl> |
| 701 | <dt><b>Branch</b></dt> |
| 702 | <dd><p>A branch is a set of check-ins with the same value for their |
| 703 | "branch" property.</p></dd> |
| 704 | <dt><b>Leaf</b></dt> |
| 705 | <dd><p>A leaf is a check-in with no children in the same branch.</p></dd> |
| @@ -714,11 +714,11 @@ | |
| 714 | children in the same branch.</p></dd> |
| 715 | <dt><b>Branch Point</b></dt> |
| 716 | <dd><p>A branch point occurs when a check-in has two or more direct (non-merge) |
| 717 | children in different branches. A branch point is similar to a fork, |
| 718 | except that the children are in different branches.</p></dd> |
| 719 | </dl></blockquote> |
| 720 | |
| 721 | Check-in 4 of Figure 3 is not a leaf because it has a child (check-in 5) |
| 722 | in the same branch. Check-in 9 of Figure 5 also has a child (check-in 10) |
| 723 | but that child is in a different branch, so check-in 9 is a leaf. Because |
| 724 | of the <b>closed</b> tag on check-in 9, it is a closed leaf. |
| 725 |
| --- www/branching.wiki | |
| +++ www/branching.wiki | |
| @@ -246,13 +246,13 @@ | |
| 246 | branching as intentional forking and the naming of forks as branches. |
| 247 | They are in fact separate concepts, but since Fossil is intended to be |
| 248 | used primarily by humans, we combine them in Fossil's human user |
| 249 | interfaces. |
| 250 | |
| 251 | <p class="blockquote"> |
| 252 | <b>Key Distinction:</b> A branch is a <i>named, intentional</i> fork. |
| 253 | </p> |
| 254 | |
| 255 | Unnamed forks <i>may</i> be intentional, but most of the time, they're |
| 256 | accidental and left unnamed. |
| 257 | |
| 258 | Fossil offers two primary ways to create named, intentional forks, |
| @@ -695,11 +695,11 @@ | |
| 695 | painless to fix them] when they do occur. |
| 696 | |
| 697 | |
| 698 | <h2>Review Of Terminology</h2> |
| 699 | |
| 700 | <dl> |
| 701 | <dt><b>Branch</b></dt> |
| 702 | <dd><p>A branch is a set of check-ins with the same value for their |
| 703 | "branch" property.</p></dd> |
| 704 | <dt><b>Leaf</b></dt> |
| 705 | <dd><p>A leaf is a check-in with no children in the same branch.</p></dd> |
| @@ -714,11 +714,11 @@ | |
| 714 | children in the same branch.</p></dd> |
| 715 | <dt><b>Branch Point</b></dt> |
| 716 | <dd><p>A branch point occurs when a check-in has two or more direct (non-merge) |
| 717 | children in different branches. A branch point is similar to a fork, |
| 718 | except that the children are in different branches.</p></dd> |
| 719 | </dl> |
| 720 | |
| 721 | Check-in 4 of Figure 3 is not a leaf because it has a child (check-in 5) |
| 722 | in the same branch. Check-in 9 of Figure 5 also has a child (check-in 10) |
| 723 | but that child is in a different branch, so check-in 9 is a leaf. Because |
| 724 | of the <b>closed</b> tag on check-in 9, it is a closed leaf. |
| 725 |
+37
-38
| --- www/build.wiki | ||
| +++ www/build.wiki | ||
| @@ -190,25 +190,25 @@ | ||
| 190 | 190 | source code for OpenSSL</a> and extract it to an appropriately named |
| 191 | 191 | "<b>openssl</b>" subdirectory within the local |
| 192 | 192 | [/tree?ci=trunk&name=compat | compat] directory then make sure that some recent |
| 193 | 193 | <a href="http://www.perl.org/">Perl</a> binaries are installed locally, |
| 194 | 194 | and finally run one of the following commands: |
| 195 | -<blockquote><pre> | |
| 195 | +<pre> | |
| 196 | 196 | nmake /f Makefile.msc FOSSIL_ENABLE_SSL=1 FOSSIL_BUILD_SSL=1 PERLDIR=C:\full\path\to\Perl\bin |
| 197 | -</pre></blockquote> | |
| 198 | -<blockquote><pre> | |
| 197 | +</pre> | |
| 198 | +<pre> | |
| 199 | 199 | buildmsvc.bat FOSSIL_ENABLE_SSL=1 FOSSIL_BUILD_SSL=1 PERLDIR=C:\full\path\to\Perl\bin |
| 200 | -</pre></blockquote> | |
| 200 | +</pre> | |
| 201 | 201 | To enable the optional native [./th1.md#tclEval | Tcl integration feature], |
| 202 | 202 | run one of the following commands or add the "FOSSIL_ENABLE_TCL=1" |
| 203 | 203 | argument to one of the other NMAKE command lines: |
| 204 | -<blockquote><pre> | |
| 204 | +<pre> | |
| 205 | 205 | nmake /f Makefile.msc FOSSIL_ENABLE_TCL=1 |
| 206 | -</pre></blockquote> | |
| 207 | -<blockquote><pre> | |
| 206 | +</pre> | |
| 207 | +<pre> | |
| 208 | 208 | buildmsvc.bat FOSSIL_ENABLE_TCL=1 |
| 209 | -</pre></blockquote> | |
| 209 | +</pre> | |
| 210 | 210 | |
| 211 | 211 | <li><i>Cygwin</i> → The same as other Unix-like systems. It is |
| 212 | 212 | recommended to configure using: "<b>configure --disable-internal-sqlite</b>", |
| 213 | 213 | making sure you have the "libsqlite3-devel" , "zlib-devel" and |
| 214 | 214 | "openssl-devel" packages installed first.</li> |
| @@ -251,17 +251,17 @@ | ||
| 251 | 251 | </li> |
| 252 | 252 | |
| 253 | 253 | <li> |
| 254 | 254 | To build on older Macs (circa 2002, MacOS 10.2) edit the Makefile |
| 255 | 255 | generated by configure to add the following lines: |
| 256 | - <blockquote><pre> | |
| 256 | + <pre> | |
| 257 | 257 | TCC += -DSQLITE_WITHOUT_ZONEMALLOC |
| 258 | 258 | TCC += -D_BSD_SOURCE |
| 259 | 259 | TCC += -DWITHOUT_ICONV |
| 260 | 260 | TCC += -Dsocketlen_t=int |
| 261 | 261 | TCC += -DSQLITE_MAX_MMAP_SIZE=0 |
| 262 | - </pre></blockquote> | |
| 262 | + </pre> | |
| 263 | 263 | </li> |
| 264 | 264 | </ul> |
| 265 | 265 | |
| 266 | 266 | |
| 267 | 267 | <h2 id="docker" name="oci">5.0 Building a Docker Container</h2> |
| @@ -438,23 +438,24 @@ | ||
| 438 | 438 | |
| 439 | 439 | For instructions on keeping the SDK up to date, see: |
| 440 | 440 | |
| 441 | 441 | [https://emscripten.org/docs/tools_reference/emsdk.html] |
| 442 | 442 | |
| 443 | - Sidebar: getting Emscripten up and running is trivial and | |
| 444 | - painless, at least on Linux systems, but the installer downloads | |
| 445 | - many hundreds of megabytes of tools and dependencies, all of which | |
| 446 | - will be installed under the single SDK directory (as opposed to | |
| 447 | - being installed at the system level). It does, however, require | |
| 448 | - that python3 be installed at the system level and it can | |
| 449 | - optionally make use of a system-level cmake for certain tasks | |
| 450 | - unrelated to how fossil uses the SDK. | |
| 443 | +<div class="sidebar">Getting Emscripten up and running is trivial and | |
| 444 | +painless, at least on Linux systems, but the installer downloads | |
| 445 | +many hundreds of megabytes of tools and dependencies, all of which | |
| 446 | +will be installed under the single SDK directory (as opposed to | |
| 447 | +being installed at the system level). It does, however, require | |
| 448 | +that python3 be installed at the system level and it can | |
| 449 | +optionally make use of a system-level cmake for certain tasks | |
| 450 | +unrelated to how fossil uses the SDK.</div> | |
| 451 | 451 | |
| 452 | 452 | After installing the SDK, configure the fossil tree with emsdk |
| 453 | 453 | support: |
| 454 | 454 | |
| 455 | -<pre><code>$ ./configure --with-emsdk=/path/to/emsdk ...other options... | |
| 455 | +<pre><code>$ ./configure --with-emsdk=/path/to/emsdk \ | |
| 456 | + --and-other-options... | |
| 456 | 457 | </code></pre> |
| 457 | 458 | |
| 458 | 459 | If the <tt>--with-emsdk</tt> flag is not provided, the configure |
| 459 | 460 | script will check for the environment variable <tt>EMSDK</tt>, which |
| 460 | 461 | is one of the standard variables the SDK environment uses. If that |
| @@ -480,27 +481,27 @@ | ||
| 480 | 481 | From the top of the source tree, all WASM-related components can be |
| 481 | 482 | built with: |
| 482 | 483 | |
| 483 | 484 | <pre><code>$ make wasm</code></pre> |
| 484 | 485 | |
| 486 | +<div class="sidebar">The file | |
| 487 | +<tt>[/file/extsrc/pikcher-worker.js|extsrc/pikcher-worker.js]</tt> | |
| 488 | +is hand-coded and intended to be loaded as a "Worker" in | |
| 489 | +JavaScript. That file loads the main module and provides an | |
| 490 | +interface via which a main JavaScript thread can communicate with | |
| 491 | +pikchr running in a Worker thread. The file | |
| 492 | +<tt>[/file/src/fossil.page.pikchrshowasm.js|src/fossil.page.pikchrshowasm.js]</tt> | |
| 493 | +implements the [/pikchrshow] app and demonstrates how | |
| 494 | +<tt>pikchr-worker.js</tt> is used.</div> | |
| 495 | + | |
| 485 | 496 | As of this writing, those parts include: |
| 486 | 497 | |
| 487 | 498 | * <tt>extsrc/pikchr.wasm</tt> is a WASM-compiled form of |
| 488 | 499 | <tt>extsrc/pikchr.c</tt>. |
| 489 | 500 | * <tt>extsrc/pikchr.js</tt> is JS/WASM glue code generated by Emscripten |
| 490 | 501 | to give JS code access to the API exported by the WASM file. |
| 491 | 502 | |
| 492 | - Sidebar: The file | |
| 493 | - <tt>[/file/extsrc/pikcher-worker.js|extsrc/pikcher-worker.js]</tt> | |
| 494 | - is hand-coded and intended to be loaded as a "Worker" in | |
| 495 | - JavaScript. That file loads the main module and provides an | |
| 496 | - interface via which a main JavaScript thread can communicate with | |
| 497 | - pikchr running in a Worker thread. The file | |
| 498 | - <tt>[/file/src/fossil.page.pikchrshowasm.js|src/fossil.page.pikchrshowasm.js]</tt> | |
| 499 | - implements the [/pikchrshow] app and demonstrates how | |
| 500 | - <tt>pikchr-worker.js</tt> is used. | |
| 501 | - | |
| 502 | 503 | When a new version of <tt>extsrc/pikchr.c</tt> is installed, the |
| 503 | 504 | files <tt>pikchr.{js,wasm}</tt> will need to be recompiled to account |
| 504 | 505 | for that. Running <tt>make wasm</tt> will, if the build is set up for |
| 505 | 506 | the emsdk, recompile those: |
| 506 | 507 | |
| @@ -509,19 +510,17 @@ | ||
| 509 | 510 | $ ls -la extsrc/pikchr.{js,wasm} |
| 510 | 511 | -rw-rw-r-- 1 stephan stephan 17263 Jun 8 03:59 extsrc/pikchr.js |
| 511 | 512 | -rw-rw-r-- 1 stephan stephan 97578 Jun 8 03:59 extsrc/pikchr.wasm |
| 512 | 513 | </code></pre> |
| 513 | 514 | |
| 514 | -<blockquote>Sidebar: if that fails with a message along the lines of: | |
| 515 | - | |
| 516 | -<pre><code>setting `EXPORTED_RUNTIME_METHODS` expects `<class 'list'>` but got `<class 'str'>`</code></pre> | |
| 517 | - | |
| 518 | -then the emcc being invoked is too old: emcc changed the format of | |
| 519 | -list-type arguments at some point. The required minimum version is | |
| 520 | -unknown, but any SDK version from May 2022 or later "should" (as of | |
| 521 | -this writing) suffice. Any older version may or may not work. | |
| 522 | -</blockquote> | |
| 515 | +<div class="sidebar">If that fails with a message along the lines of | |
| 516 | +“<code>setting `EXPORTED_RUNTIME_METHODS` expects `<class 'list'>` but | |
| 517 | +got `<class 'str'>`</code>” then the emcc being invoked is too old: emcc | |
| 518 | +changed the format of list-type arguments at some point. The required | |
| 519 | +minimum version is unknown, but any SDK version from May 2022 or later | |
| 520 | +"should" (as of this writing) suffice. Any older version may or may not | |
| 521 | +work.</div> | |
| 523 | 522 | |
| 524 | 523 | After that succeeds, we need to run the normal build so that those |
| 525 | 524 | generated files can be compiled in to the fossil binary, accessible |
| 526 | 525 | via the [/help?cmd=/builtin|/builtin page]: |
| 527 | 526 | |
| 528 | 527 |
| --- www/build.wiki | |
| +++ www/build.wiki | |
| @@ -190,25 +190,25 @@ | |
| 190 | source code for OpenSSL</a> and extract it to an appropriately named |
| 191 | "<b>openssl</b>" subdirectory within the local |
| 192 | [/tree?ci=trunk&name=compat | compat] directory then make sure that some recent |
| 193 | <a href="http://www.perl.org/">Perl</a> binaries are installed locally, |
| 194 | and finally run one of the following commands: |
| 195 | <blockquote><pre> |
| 196 | nmake /f Makefile.msc FOSSIL_ENABLE_SSL=1 FOSSIL_BUILD_SSL=1 PERLDIR=C:\full\path\to\Perl\bin |
| 197 | </pre></blockquote> |
| 198 | <blockquote><pre> |
| 199 | buildmsvc.bat FOSSIL_ENABLE_SSL=1 FOSSIL_BUILD_SSL=1 PERLDIR=C:\full\path\to\Perl\bin |
| 200 | </pre></blockquote> |
| 201 | To enable the optional native [./th1.md#tclEval | Tcl integration feature], |
| 202 | run one of the following commands or add the "FOSSIL_ENABLE_TCL=1" |
| 203 | argument to one of the other NMAKE command lines: |
| 204 | <blockquote><pre> |
| 205 | nmake /f Makefile.msc FOSSIL_ENABLE_TCL=1 |
| 206 | </pre></blockquote> |
| 207 | <blockquote><pre> |
| 208 | buildmsvc.bat FOSSIL_ENABLE_TCL=1 |
| 209 | </pre></blockquote> |
| 210 | |
| 211 | <li><i>Cygwin</i> → The same as other Unix-like systems. It is |
| 212 | recommended to configure using: "<b>configure --disable-internal-sqlite</b>", |
| 213 | making sure you have the "libsqlite3-devel" , "zlib-devel" and |
| 214 | "openssl-devel" packages installed first.</li> |
| @@ -251,17 +251,17 @@ | |
| 251 | </li> |
| 252 | |
| 253 | <li> |
| 254 | To build on older Macs (circa 2002, MacOS 10.2) edit the Makefile |
| 255 | generated by configure to add the following lines: |
| 256 | <blockquote><pre> |
| 257 | TCC += -DSQLITE_WITHOUT_ZONEMALLOC |
| 258 | TCC += -D_BSD_SOURCE |
| 259 | TCC += -DWITHOUT_ICONV |
| 260 | TCC += -Dsocketlen_t=int |
| 261 | TCC += -DSQLITE_MAX_MMAP_SIZE=0 |
| 262 | </pre></blockquote> |
| 263 | </li> |
| 264 | </ul> |
| 265 | |
| 266 | |
| 267 | <h2 id="docker" name="oci">5.0 Building a Docker Container</h2> |
| @@ -438,23 +438,24 @@ | |
| 438 | |
| 439 | For instructions on keeping the SDK up to date, see: |
| 440 | |
| 441 | [https://emscripten.org/docs/tools_reference/emsdk.html] |
| 442 | |
| 443 | Sidebar: getting Emscripten up and running is trivial and |
| 444 | painless, at least on Linux systems, but the installer downloads |
| 445 | many hundreds of megabytes of tools and dependencies, all of which |
| 446 | will be installed under the single SDK directory (as opposed to |
| 447 | being installed at the system level). It does, however, require |
| 448 | that python3 be installed at the system level and it can |
| 449 | optionally make use of a system-level cmake for certain tasks |
| 450 | unrelated to how fossil uses the SDK. |
| 451 | |
| 452 | After installing the SDK, configure the fossil tree with emsdk |
| 453 | support: |
| 454 | |
| 455 | <pre><code>$ ./configure --with-emsdk=/path/to/emsdk ...other options... |
| 456 | </code></pre> |
| 457 | |
| 458 | If the <tt>--with-emsdk</tt> flag is not provided, the configure |
| 459 | script will check for the environment variable <tt>EMSDK</tt>, which |
| 460 | is one of the standard variables the SDK environment uses. If that |
| @@ -480,27 +481,27 @@ | |
| 480 | From the top of the source tree, all WASM-related components can be |
| 481 | built with: |
| 482 | |
| 483 | <pre><code>$ make wasm</code></pre> |
| 484 | |
| 485 | As of this writing, those parts include: |
| 486 | |
| 487 | * <tt>extsrc/pikchr.wasm</tt> is a WASM-compiled form of |
| 488 | <tt>extsrc/pikchr.c</tt>. |
| 489 | * <tt>extsrc/pikchr.js</tt> is JS/WASM glue code generated by Emscripten |
| 490 | to give JS code access to the API exported by the WASM file. |
| 491 | |
| 492 | Sidebar: The file |
| 493 | <tt>[/file/extsrc/pikcher-worker.js|extsrc/pikcher-worker.js]</tt> |
| 494 | is hand-coded and intended to be loaded as a "Worker" in |
| 495 | JavaScript. That file loads the main module and provides an |
| 496 | interface via which a main JavaScript thread can communicate with |
| 497 | pikchr running in a Worker thread. The file |
| 498 | <tt>[/file/src/fossil.page.pikchrshowasm.js|src/fossil.page.pikchrshowasm.js]</tt> |
| 499 | implements the [/pikchrshow] app and demonstrates how |
| 500 | <tt>pikchr-worker.js</tt> is used. |
| 501 | |
| 502 | When a new version of <tt>extsrc/pikchr.c</tt> is installed, the |
| 503 | files <tt>pikchr.{js,wasm}</tt> will need to be recompiled to account |
| 504 | for that. Running <tt>make wasm</tt> will, if the build is set up for |
| 505 | the emsdk, recompile those: |
| 506 | |
| @@ -509,19 +510,17 @@ | |
| 509 | $ ls -la extsrc/pikchr.{js,wasm} |
| 510 | -rw-rw-r-- 1 stephan stephan 17263 Jun 8 03:59 extsrc/pikchr.js |
| 511 | -rw-rw-r-- 1 stephan stephan 97578 Jun 8 03:59 extsrc/pikchr.wasm |
| 512 | </code></pre> |
| 513 | |
| 514 | <blockquote>Sidebar: if that fails with a message along the lines of: |
| 515 | |
| 516 | <pre><code>setting `EXPORTED_RUNTIME_METHODS` expects `<class 'list'>` but got `<class 'str'>`</code></pre> |
| 517 | |
| 518 | then the emcc being invoked is too old: emcc changed the format of |
| 519 | list-type arguments at some point. The required minimum version is |
| 520 | unknown, but any SDK version from May 2022 or later "should" (as of |
| 521 | this writing) suffice. Any older version may or may not work. |
| 522 | </blockquote> |
| 523 | |
| 524 | After that succeeds, we need to run the normal build so that those |
| 525 | generated files can be compiled in to the fossil binary, accessible |
| 526 | via the [/help?cmd=/builtin|/builtin page]: |
| 527 | |
| 528 |
| --- www/build.wiki | |
| +++ www/build.wiki | |
| @@ -190,25 +190,25 @@ | |
| 190 | source code for OpenSSL</a> and extract it to an appropriately named |
| 191 | "<b>openssl</b>" subdirectory within the local |
| 192 | [/tree?ci=trunk&name=compat | compat] directory then make sure that some recent |
| 193 | <a href="http://www.perl.org/">Perl</a> binaries are installed locally, |
| 194 | and finally run one of the following commands: |
| 195 | <pre> |
| 196 | nmake /f Makefile.msc FOSSIL_ENABLE_SSL=1 FOSSIL_BUILD_SSL=1 PERLDIR=C:\full\path\to\Perl\bin |
| 197 | </pre> |
| 198 | <pre> |
| 199 | buildmsvc.bat FOSSIL_ENABLE_SSL=1 FOSSIL_BUILD_SSL=1 PERLDIR=C:\full\path\to\Perl\bin |
| 200 | </pre> |
| 201 | To enable the optional native [./th1.md#tclEval | Tcl integration feature], |
| 202 | run one of the following commands or add the "FOSSIL_ENABLE_TCL=1" |
| 203 | argument to one of the other NMAKE command lines: |
| 204 | <pre> |
| 205 | nmake /f Makefile.msc FOSSIL_ENABLE_TCL=1 |
| 206 | </pre> |
| 207 | <pre> |
| 208 | buildmsvc.bat FOSSIL_ENABLE_TCL=1 |
| 209 | </pre> |
| 210 | |
| 211 | <li><i>Cygwin</i> → The same as other Unix-like systems. It is |
| 212 | recommended to configure using: "<b>configure --disable-internal-sqlite</b>", |
| 213 | making sure you have the "libsqlite3-devel" , "zlib-devel" and |
| 214 | "openssl-devel" packages installed first.</li> |
| @@ -251,17 +251,17 @@ | |
| 251 | </li> |
| 252 | |
| 253 | <li> |
| 254 | To build on older Macs (circa 2002, MacOS 10.2) edit the Makefile |
| 255 | generated by configure to add the following lines: |
| 256 | <pre> |
| 257 | TCC += -DSQLITE_WITHOUT_ZONEMALLOC |
| 258 | TCC += -D_BSD_SOURCE |
| 259 | TCC += -DWITHOUT_ICONV |
| 260 | TCC += -Dsocketlen_t=int |
| 261 | TCC += -DSQLITE_MAX_MMAP_SIZE=0 |
| 262 | </pre> |
| 263 | </li> |
| 264 | </ul> |
| 265 | |
| 266 | |
| 267 | <h2 id="docker" name="oci">5.0 Building a Docker Container</h2> |
| @@ -438,23 +438,24 @@ | |
| 438 | |
| 439 | For instructions on keeping the SDK up to date, see: |
| 440 | |
| 441 | [https://emscripten.org/docs/tools_reference/emsdk.html] |
| 442 | |
| 443 | <div class="sidebar">Getting Emscripten up and running is trivial and |
| 444 | painless, at least on Linux systems, but the installer downloads |
| 445 | many hundreds of megabytes of tools and dependencies, all of which |
| 446 | will be installed under the single SDK directory (as opposed to |
| 447 | being installed at the system level). It does, however, require |
| 448 | that python3 be installed at the system level and it can |
| 449 | optionally make use of a system-level cmake for certain tasks |
| 450 | unrelated to how fossil uses the SDK.</div> |
| 451 | |
| 452 | After installing the SDK, configure the fossil tree with emsdk |
| 453 | support: |
| 454 | |
| 455 | <pre><code>$ ./configure --with-emsdk=/path/to/emsdk \ |
| 456 | --and-other-options... |
| 457 | </code></pre> |
| 458 | |
| 459 | If the <tt>--with-emsdk</tt> flag is not provided, the configure |
| 460 | script will check for the environment variable <tt>EMSDK</tt>, which |
| 461 | is one of the standard variables the SDK environment uses. If that |
| @@ -480,27 +481,27 @@ | |
| 481 | From the top of the source tree, all WASM-related components can be |
| 482 | built with: |
| 483 | |
| 484 | <pre><code>$ make wasm</code></pre> |
| 485 | |
| 486 | <div class="sidebar">The file |
| 487 | <tt>[/file/extsrc/pikcher-worker.js|extsrc/pikcher-worker.js]</tt> |
| 488 | is hand-coded and intended to be loaded as a "Worker" in |
| 489 | JavaScript. That file loads the main module and provides an |
| 490 | interface via which a main JavaScript thread can communicate with |
| 491 | pikchr running in a Worker thread. The file |
| 492 | <tt>[/file/src/fossil.page.pikchrshowasm.js|src/fossil.page.pikchrshowasm.js]</tt> |
| 493 | implements the [/pikchrshow] app and demonstrates how |
| 494 | <tt>pikchr-worker.js</tt> is used.</div> |
| 495 | |
| 496 | As of this writing, those parts include: |
| 497 | |
| 498 | * <tt>extsrc/pikchr.wasm</tt> is a WASM-compiled form of |
| 499 | <tt>extsrc/pikchr.c</tt>. |
| 500 | * <tt>extsrc/pikchr.js</tt> is JS/WASM glue code generated by Emscripten |
| 501 | to give JS code access to the API exported by the WASM file. |
| 502 | |
| 503 | When a new version of <tt>extsrc/pikchr.c</tt> is installed, the |
| 504 | files <tt>pikchr.{js,wasm}</tt> will need to be recompiled to account |
| 505 | for that. Running <tt>make wasm</tt> will, if the build is set up for |
| 506 | the emsdk, recompile those: |
| 507 | |
| @@ -509,19 +510,17 @@ | |
| 510 | $ ls -la extsrc/pikchr.{js,wasm} |
| 511 | -rw-rw-r-- 1 stephan stephan 17263 Jun 8 03:59 extsrc/pikchr.js |
| 512 | -rw-rw-r-- 1 stephan stephan 97578 Jun 8 03:59 extsrc/pikchr.wasm |
| 513 | </code></pre> |
| 514 | |
| 515 | <div class="sidebar">If that fails with a message along the lines of |
| 516 | “<code>setting `EXPORTED_RUNTIME_METHODS` expects `<class 'list'>` but |
| 517 | got `<class 'str'>`</code>” then the emcc being invoked is too old: emcc |
| 518 | changed the format of list-type arguments at some point. The required |
| 519 | minimum version is unknown, but any SDK version from May 2022 or later |
| 520 | "should" (as of this writing) suffice. Any older version may or may not |
| 521 | work.</div> |
| 522 | |
| 523 | After that succeeds, we need to run the normal build so that those |
| 524 | generated files can be compiled in to the fossil binary, accessible |
| 525 | via the [/help?cmd=/builtin|/builtin page]: |
| 526 | |
| 527 |
+2
-2
| --- www/cgi.wiki | ||
| +++ www/cgi.wiki | ||
| @@ -23,14 +23,14 @@ | ||
| 23 | 23 | <h1>CGI Script Options</h1> |
| 24 | 24 | |
| 25 | 25 | The CGI script used to launch a Fossil server will usually look something |
| 26 | 26 | like this: |
| 27 | 27 | |
| 28 | -<blockquote><verbatim> | |
| 28 | +<verbatim> | |
| 29 | 29 | #!/usr/bin/fossil |
| 30 | 30 | repository: /home/www/fossils/myproject.fossil |
| 31 | -</verbatim></blockquote> | |
| 31 | +</verbatim> | |
| 32 | 32 | |
| 33 | 33 | Of course, pathnames will likely be different. The first line |
| 34 | 34 | (the "[wikipedia:/wiki/Shebang_(Unix)|shebang]") |
| 35 | 35 | always gives the name of the Fossil executable. Subsequent lines are of |
| 36 | 36 | the form "<b>property: argument ...</b>". |
| 37 | 37 |
| --- www/cgi.wiki | |
| +++ www/cgi.wiki | |
| @@ -23,14 +23,14 @@ | |
| 23 | <h1>CGI Script Options</h1> |
| 24 | |
| 25 | The CGI script used to launch a Fossil server will usually look something |
| 26 | like this: |
| 27 | |
| 28 | <blockquote><verbatim> |
| 29 | #!/usr/bin/fossil |
| 30 | repository: /home/www/fossils/myproject.fossil |
| 31 | </verbatim></blockquote> |
| 32 | |
| 33 | Of course, pathnames will likely be different. The first line |
| 34 | (the "[wikipedia:/wiki/Shebang_(Unix)|shebang]") |
| 35 | always gives the name of the Fossil executable. Subsequent lines are of |
| 36 | the form "<b>property: argument ...</b>". |
| 37 |
| --- www/cgi.wiki | |
| +++ www/cgi.wiki | |
| @@ -23,14 +23,14 @@ | |
| 23 | <h1>CGI Script Options</h1> |
| 24 | |
| 25 | The CGI script used to launch a Fossil server will usually look something |
| 26 | like this: |
| 27 | |
| 28 | <verbatim> |
| 29 | #!/usr/bin/fossil |
| 30 | repository: /home/www/fossils/myproject.fossil |
| 31 | </verbatim> |
| 32 | |
| 33 | Of course, pathnames will likely be different. The first line |
| 34 | (the "[wikipedia:/wiki/Shebang_(Unix)|shebang]") |
| 35 | always gives the name of the Fossil executable. Subsequent lines are of |
| 36 | the form "<b>property: argument ...</b>". |
| 37 |
+4
| --- www/changes.wiki | ||
| +++ www/changes.wiki | ||
| @@ -12,10 +12,14 @@ | ||
| 12 | 12 | * The /uvlist page now shows the hash algorithm used so that |
| 13 | 13 | outsiders don't have to guess it from the hash length when |
| 14 | 14 | double-checking hashes of downloaded files on their end. |
| 15 | 15 | * The hash itself is now shown in a fixed-width font on the /uvlist |
| 16 | 16 | page, suiting this tabular display. |
| 17 | + * Reworked the default skin to make everything more readable: larger | |
| 18 | + fonts, more whitespace, added indents to show hierarchy and to | |
| 19 | + offset command examples, etc. Colors are slightly adjusted to bring | |
| 20 | + things into better accord with the WCAG accessibility guidelines. | |
| 17 | 21 | |
| 18 | 22 | <h2 id='v2_23'>Changes for version 2.23 (2023-11-01)</h2> |
| 19 | 23 | |
| 20 | 24 | * Add ability to "close" forum threads, such that unprivileged users |
| 21 | 25 | may no longer respond to them. Only administrators can close |
| 22 | 26 |
| --- www/changes.wiki | |
| +++ www/changes.wiki | |
| @@ -12,10 +12,14 @@ | |
| 12 | * The /uvlist page now shows the hash algorithm used so that |
| 13 | outsiders don't have to guess it from the hash length when |
| 14 | double-checking hashes of downloaded files on their end. |
| 15 | * The hash itself is now shown in a fixed-width font on the /uvlist |
| 16 | page, suiting this tabular display. |
| 17 | |
| 18 | <h2 id='v2_23'>Changes for version 2.23 (2023-11-01)</h2> |
| 19 | |
| 20 | * Add ability to "close" forum threads, such that unprivileged users |
| 21 | may no longer respond to them. Only administrators can close |
| 22 |
| --- www/changes.wiki | |
| +++ www/changes.wiki | |
| @@ -12,10 +12,14 @@ | |
| 12 | * The /uvlist page now shows the hash algorithm used so that |
| 13 | outsiders don't have to guess it from the hash length when |
| 14 | double-checking hashes of downloaded files on their end. |
| 15 | * The hash itself is now shown in a fixed-width font on the /uvlist |
| 16 | page, suiting this tabular display. |
| 17 | * Reworked the default skin to make everything more readable: larger |
| 18 | fonts, more whitespace, added indents to show hierarchy and to |
| 19 | offset command examples, etc. Colors are slightly adjusted to bring |
| 20 | things into better accord with the WCAG accessibility guidelines. |
| 21 | |
| 22 | <h2 id='v2_23'>Changes for version 2.23 (2023-11-01)</h2> |
| 23 | |
| 24 | * Add ability to "close" forum threads, such that unprivileged users |
| 25 | may no longer respond to them. Only administrators can close |
| 26 |
+9
-9
| --- www/chat.md | ||
| +++ www/chat.md | ||
| @@ -79,10 +79,19 @@ | ||
| 79 | 79 | inline in messages, but each user may toggle that via the settings |
| 80 | 80 | popup menu, such that images instead appear as downloadable links. |
| 81 | 81 | Non-image files always appear in messages as download links. |
| 82 | 82 | |
| 83 | 83 | ### Deletion of Messages |
| 84 | + | |
| 85 | +<div class="sidebar">Message deletion is itself a type of message, which | |
| 86 | +is why deletions count towards updates in the recent activity list. (It | |
| 87 | +is counted for the person who performed the deletion, not the author of | |
| 88 | +the deleted comment.) That can potentially lead to odd corner cases | |
| 89 | +where a user shows up in the list but has no messages which are | |
| 90 | +currently visible because they were deleted, or an admin user who has | |
| 91 | +not posted anything but deleted a message. That is a known minor | |
| 92 | +cosmetic-only bug with a resolution of "will not fix."</div> | |
| 84 | 93 | |
| 85 | 94 | Any user may *locally* delete a given message by clicking on the "tab" |
| 86 | 95 | at the top of the message and clicking the button which appears. Such |
| 87 | 96 | deletions are local-only, and the messages will reappear if the page |
| 88 | 97 | is reloaded. The user who posted a given message, or any Admin users, |
| @@ -112,19 +121,10 @@ | ||
| 112 | 121 | show up in that list, nor does the chat infrastructure have a way to |
| 113 | 122 | track and present those. That list can be used to filter messages on a |
| 114 | 123 | specific user by tapping on that user's name, tapping a second time to |
| 115 | 124 | remove the filter. |
| 116 | 125 | |
| 117 | -Sidebar: message deletion is a type of message and deletions count | |
| 118 | -towards updates in the recent activity list (counted for the person | |
| 119 | -who performed the deletion, not the author of the deleted | |
| 120 | -comment). That can potentially lead to odd corner cases where a user | |
| 121 | -shows up in the list but has no messages which are currently visible | |
| 122 | -because they were deleted, or an admin user who has not posted | |
| 123 | -anything but deleted a message. That is a known minor cosmetic-only | |
| 124 | -bug with a resolution of "will not fix." | |
| 125 | - | |
| 126 | 126 | ### <a id="cli"></a> The `fossil chat` Command |
| 127 | 127 | |
| 128 | 128 | Type [fossil chat](/help?cmd=chat) from within any open check-out |
| 129 | 129 | to bring up a chatroom for the project that is in that checkout. |
| 130 | 130 | The new chat window will attempt to connect to the default sync |
| 131 | 131 |
| --- www/chat.md | |
| +++ www/chat.md | |
| @@ -79,10 +79,19 @@ | |
| 79 | inline in messages, but each user may toggle that via the settings |
| 80 | popup menu, such that images instead appear as downloadable links. |
| 81 | Non-image files always appear in messages as download links. |
| 82 | |
| 83 | ### Deletion of Messages |
| 84 | |
| 85 | Any user may *locally* delete a given message by clicking on the "tab" |
| 86 | at the top of the message and clicking the button which appears. Such |
| 87 | deletions are local-only, and the messages will reappear if the page |
| 88 | is reloaded. The user who posted a given message, or any Admin users, |
| @@ -112,19 +121,10 @@ | |
| 112 | show up in that list, nor does the chat infrastructure have a way to |
| 113 | track and present those. That list can be used to filter messages on a |
| 114 | specific user by tapping on that user's name, tapping a second time to |
| 115 | remove the filter. |
| 116 | |
| 117 | Sidebar: message deletion is a type of message and deletions count |
| 118 | towards updates in the recent activity list (counted for the person |
| 119 | who performed the deletion, not the author of the deleted |
| 120 | comment). That can potentially lead to odd corner cases where a user |
| 121 | shows up in the list but has no messages which are currently visible |
| 122 | because they were deleted, or an admin user who has not posted |
| 123 | anything but deleted a message. That is a known minor cosmetic-only |
| 124 | bug with a resolution of "will not fix." |
| 125 | |
| 126 | ### <a id="cli"></a> The `fossil chat` Command |
| 127 | |
| 128 | Type [fossil chat](/help?cmd=chat) from within any open check-out |
| 129 | to bring up a chatroom for the project that is in that checkout. |
| 130 | The new chat window will attempt to connect to the default sync |
| 131 |
| --- www/chat.md | |
| +++ www/chat.md | |
| @@ -79,10 +79,19 @@ | |
| 79 | inline in messages, but each user may toggle that via the settings |
| 80 | popup menu, such that images instead appear as downloadable links. |
| 81 | Non-image files always appear in messages as download links. |
| 82 | |
| 83 | ### Deletion of Messages |
| 84 | |
| 85 | <div class="sidebar">Message deletion is itself a type of message, which |
| 86 | is why deletions count towards updates in the recent activity list. (It |
| 87 | is counted for the person who performed the deletion, not the author of |
| 88 | the deleted comment.) That can potentially lead to odd corner cases |
| 89 | where a user shows up in the list but has no messages which are |
| 90 | currently visible because they were deleted, or an admin user who has |
| 91 | not posted anything but deleted a message. That is a known minor |
| 92 | cosmetic-only bug with a resolution of "will not fix."</div> |
| 93 | |
| 94 | Any user may *locally* delete a given message by clicking on the "tab" |
| 95 | at the top of the message and clicking the button which appears. Such |
| 96 | deletions are local-only, and the messages will reappear if the page |
| 97 | is reloaded. The user who posted a given message, or any Admin users, |
| @@ -112,19 +121,10 @@ | |
| 121 | show up in that list, nor does the chat infrastructure have a way to |
| 122 | track and present those. That list can be used to filter messages on a |
| 123 | specific user by tapping on that user's name, tapping a second time to |
| 124 | remove the filter. |
| 125 | |
| 126 | ### <a id="cli"></a> The `fossil chat` Command |
| 127 | |
| 128 | Type [fossil chat](/help?cmd=chat) from within any open check-out |
| 129 | to bring up a chatroom for the project that is in that checkout. |
| 130 | The new chat window will attempt to connect to the default sync |
| 131 |
+42
-41
| --- www/checkin_names.wiki | ||
| +++ www/checkin_names.wiki | ||
| @@ -1,10 +1,9 @@ | ||
| 1 | 1 | <title>Check-in Names</title> |
| 2 | 2 | |
| 3 | -<table align="right" border="1" width="33%" cellpadding="10"> | |
| 4 | -<tr><td> | |
| 5 | -<h3>Quick Reference</h3> | |
| 3 | +<div class="sidebar no-label"> | |
| 4 | +<b>Quick Reference</b> | |
| 6 | 5 | <ul> |
| 7 | 6 | <li> Hash prefix |
| 8 | 7 | <li> Branch name |
| 9 | 8 | <li> Tag name |
| 10 | 9 | <li> Timestamp: <i>YYYY-MM-DD HH:MM:SS</i> |
| @@ -19,29 +18,30 @@ | ||
| 19 | 18 | <li> <b>next</b> |
| 20 | 19 | <li> <b>previous</b> or <b>prev</b> |
| 21 | 20 | <li> <b>ckout</b> (<a href='./embeddeddoc.wiki'>embedded docs</a> only) |
| 22 | 21 | </ul> |
| 23 | 22 | </ul> |
| 24 | -</td></tr> | |
| 25 | -</table> | |
| 23 | +</div> | |
| 24 | + | |
| 26 | 25 | Many Fossil [/help|commands] and [./webui.wiki | web interface] URLs accept |
| 27 | 26 | check-in names as an argument. For example, the "[/help/info|info]" command |
| 28 | 27 | accepts an optional check-in name to identify the specific check-in |
| 29 | 28 | about which information is desired: |
| 30 | 29 | |
| 31 | -<blockquote> | |
| 32 | -<tt>fossil info</tt> <i>checkin-name</i> | |
| 33 | -</blockquote> | |
| 30 | +<pre style="white-space: pre-wrap"> | |
| 31 | +fossil info <i>checkin-name</i> | |
| 32 | +</pre> | |
| 34 | 33 | |
| 35 | 34 | You are perhaps reading this page from the following URL: |
| 36 | 35 | |
| 37 | -<blockquote> | |
| 38 | -https://fossil-scm.org/home/doc/<b>trunk</b>/www/checkin_names.wiki | |
| 39 | -</blockquote> | |
| 36 | +<verbatim> | |
| 37 | +https://fossil-scm.org/home/doc/trunk/www/checkin_names.wiki | |
| 38 | +</verbatim> | |
| 40 | 39 | |
| 41 | -The URL above is an example of an [./embeddeddoc.wiki | embedded documentation] | |
| 42 | -page in Fossil. The bold term of the pathname is a check-in name that | |
| 40 | +This is an example of an [./embeddeddoc.wiki | embedded documentation] | |
| 41 | +page URL. The "trunk" element of the pathname is a | |
| 42 | +[./glossary.md#check-in | check-in] name that | |
| 43 | 43 | determines which version of the documentation to display. |
| 44 | 44 | |
| 45 | 45 | Fossil provides a variety of ways to specify a check-in. This |
| 46 | 46 | document describes the various methods. |
| 47 | 47 | |
| @@ -49,49 +49,50 @@ | ||
| 49 | 49 | |
| 50 | 50 | The canonical name of a check-in is the hash of its |
| 51 | 51 | [./fileformat.wiki#manifest | manifest] expressed as a |
| 52 | 52 | [./hashes.md | long lowercase hexadecimal number]. For example: |
| 53 | 53 | |
| 54 | -<blockquote><pre> | |
| 54 | +<pre> | |
| 55 | 55 | fossil info e5a734a19a9826973e1d073b49dc2a16aa2308f9 |
| 56 | -</pre></blockquote> | |
| 56 | +</pre> | |
| 57 | 57 | |
| 58 | 58 | The full 40 or 64 character hash is unwieldy to remember and type, though, |
| 59 | 59 | so Fossil also accepts a unique prefix of the hash, using any combination |
| 60 | 60 | of upper and lower case letters, as long as the prefix is at least 4 |
| 61 | 61 | characters long. Hence the following commands all |
| 62 | 62 | accomplish the same thing as the above: |
| 63 | 63 | |
| 64 | -<blockquote><pre> | |
| 64 | +<pre> | |
| 65 | 65 | fossil info e5a734a19a9 |
| 66 | 66 | fossil info E5a734A |
| 67 | 67 | fossil info e5a7 |
| 68 | -</blockquote> | |
| 68 | +</pre> | |
| 69 | 69 | |
| 70 | -Many web interface screens identify check-ins by 10- or 16-character | |
| 71 | -prefix of canonical name. | |
| 70 | +Fossil uses this feature itself, identifying check-ins by 8 to 16-character | |
| 71 | +prefixes of the canonical name in places where it doesn't want to chew | |
| 72 | +up the screen real estate required to display the whole hash. | |
| 72 | 73 | |
| 73 | 74 | <h2 id="tags">Tags And Branch Names</h2> |
| 74 | 75 | |
| 75 | 76 | Using a tag or branch name where a check-in name is expected causes |
| 76 | 77 | Fossil to choose the most recent check-in with that tag or branch name. |
| 77 | 78 | So for example, the most recent check-in that |
| 78 | 79 | is tagged with "release" as of this writing is [b98ce23d4fc]. |
| 79 | 80 | The command: |
| 80 | 81 | |
| 81 | -<blockquote><pre> | |
| 82 | +<pre> | |
| 82 | 83 | fossil info release |
| 83 | -</pre></blockquote> | |
| 84 | +</pre> | |
| 84 | 85 | |
| 85 | 86 | …results in the following output: |
| 86 | 87 | |
| 87 | -<blockquote><pre> | |
| 88 | +<pre> | |
| 88 | 89 | hash: b98ce23d4fc3b734cdc058ee8a67e6dad675ca13 2020-08-20 13:27:04 UTC |
| 89 | 90 | parent: 40feec329163103293d98dfcc2d119d1a16b227a 2020-08-20 13:01:51 UTC |
| 90 | 91 | tags: release, branch-2.12, version-2.12.1 |
| 91 | 92 | comment: Version 2.12.1 (user: drh) |
| 92 | -</pre></blockquote> | |
| 93 | +</pre> | |
| 93 | 94 | |
| 94 | 95 | There are multiple check-ins that are tagged with "release" but |
| 95 | 96 | (as of this writing) the [b98ce23d4fc] |
| 96 | 97 | check-in is the most recent so it is the one that is selected. |
| 97 | 98 | |
| @@ -107,13 +108,13 @@ | ||
| 107 | 108 | also happened to have tagged a different check-in with "deed2". If |
| 108 | 109 | you use the "deed2" name, does it choose the canonical name or the tag |
| 109 | 110 | name? In such cases, you can prefix the tag name with "tag:". |
| 110 | 111 | For example: |
| 111 | 112 | |
| 112 | -<blockquote><tt> | |
| 113 | +<pre> | |
| 113 | 114 | fossil info tag:deed2 |
| 114 | -</tt></blockquote> | |
| 115 | +</pre> | |
| 115 | 116 | |
| 116 | 117 | The "tag:deed2" name will refer to the most recent check-in |
| 117 | 118 | tagged with "deed2" rather than the |
| 118 | 119 | check-in whose canonical name begins with "deed2". |
| 119 | 120 | |
| @@ -180,21 +181,21 @@ | ||
| 180 | 181 | rather than as a tag by passing “date:2020-04-01”. |
| 181 | 182 | |
| 182 | 183 | For an example of how timestamps are useful, |
| 183 | 184 | consider the homepage for the Fossil website itself: |
| 184 | 185 | |
| 185 | -<blockquote> | |
| 186 | +<pre> | |
| 186 | 187 | https://fossil-scm.org/home/doc/<b>trunk</b>/www/index.wiki |
| 187 | -</blockquote> | |
| 188 | +</pre> | |
| 188 | 189 | |
| 189 | 190 | The bold component of that URL is a check-in name. To see the stored content |
| 190 | 191 | of the Fossil website repository as of January 1, 2009, one has merely to change |
| 191 | 192 | the URL to the following: |
| 192 | 193 | |
| 193 | -<blockquote> | |
| 194 | +<pre> | |
| 194 | 195 | https://fossil-scm.org/home/doc/<b>2009-01-01</b>/www/index.wiki |
| 195 | -</blockquote> | |
| 196 | +</pre> | |
| 196 | 197 | |
| 197 | 198 | (Note that this won't roll you back to the <i>skin</i> and other |
| 198 | 199 | cosmetic configurations as of that date. It also won't change screens |
| 199 | 200 | like the timeline, which has an independent date selector.) |
| 200 | 201 | |
| @@ -203,13 +204,13 @@ | ||
| 203 | 204 | A check-in name can also take the form of a tag or branch name followed by |
| 204 | 205 | a colon and then a timestamp. The combination means to take the most |
| 205 | 206 | recent check-in with the given tag or branch which is not more recent than |
| 206 | 207 | the timestamp. So, for example: |
| 207 | 208 | |
| 208 | -<blockquote><tt> | |
| 209 | +<pre> | |
| 209 | 210 | fossil update trunk:2010-07-01T14:30 |
| 210 | -</tt></blockquote> | |
| 211 | +</pre> | |
| 211 | 212 | |
| 212 | 213 | Would cause Fossil to update the working check-out to be the most recent |
| 213 | 214 | check-in on the trunk that is not more recent than 14:30 (UTC) on |
| 214 | 215 | July 1, 2010. |
| 215 | 216 | |
| @@ -219,13 +220,13 @@ | ||
| 219 | 220 | last check-in on the parent branch prior to the beginning of the branch. |
| 220 | 221 | Such a label is useful, for example, in computing all diffs for a single |
| 221 | 222 | branch. The following example will show all changes in the hypothetical |
| 222 | 223 | branch "xyzzy": |
| 223 | 224 | |
| 224 | -<blockquote><tt> | |
| 225 | +<pre> | |
| 225 | 226 | fossil diff --from root:xyzzy --to xyzzy |
| 226 | -</tt></blockquote> | |
| 227 | +</pre> | |
| 227 | 228 | |
| 228 | 229 | <a id="merge-in"></a> |
| 229 | 230 | That doesn't do what you might expect after you merge the parent |
| 230 | 231 | branch's changes into the child branch: the above command will include |
| 231 | 232 | changes made on the parent branch as well. |
| @@ -241,13 +242,13 @@ | ||
| 241 | 242 | The prefix "<tt>start:</tt>" gives the first check-in of the named branch. |
| 242 | 243 | |
| 243 | 244 | The prefixes "<tt>root:</tt>", "<tt>start:</tt>", and "<tt>merge-in:</tt>" |
| 244 | 245 | can be chained: one can say for example |
| 245 | 246 | |
| 246 | -<blockquote><tt> | |
| 247 | +<pre> | |
| 247 | 248 | fossil info merge-in:xyzzy:2022-03-01 |
| 248 | -</tt></blockquote> | |
| 249 | +</pre> | |
| 249 | 250 | |
| 250 | 251 | to get informations about the most recent merge-in point on the branch |
| 251 | 252 | "xyzzy" that happened on or before March 1, 2022. |
| 252 | 253 | |
| 253 | 254 | <h2 id="special">Special Tags</h2> |
| @@ -256,13 +257,13 @@ | ||
| 256 | 257 | equivalent to the timestamp "9999-12-31". |
| 257 | 258 | |
| 258 | 259 | This special name works anywhere you can pass a "NAME", such as with |
| 259 | 260 | <tt>/info</tt> URLs: |
| 260 | 261 | |
| 261 | -<blockquote><pre> | |
| 262 | +<pre> | |
| 262 | 263 | http://localhost:8080/info/tip |
| 263 | -</pre></blockquote> | |
| 264 | +</pre> | |
| 264 | 265 | |
| 265 | 266 | There are several other special names, but they only work from within a |
| 266 | 267 | check-out directory because they are relative to the current checked-out |
| 267 | 268 | version: |
| 268 | 269 | |
| @@ -282,20 +283,20 @@ | ||
| 282 | 283 | <h2 id="examples">Additional Examples</h2> |
| 283 | 284 | |
| 284 | 285 | To view the changes in the most recent check-in prior to the version currently |
| 285 | 286 | checked out: |
| 286 | 287 | |
| 287 | -<blockquote><pre> | |
| 288 | +<pre> | |
| 288 | 289 | fossil diff --from previous --to current |
| 289 | -</pre></blockquote> | |
| 290 | +</pre> | |
| 290 | 291 | |
| 291 | 292 | Suppose you are of the habit of tagging each release with a "release" tag. |
| 292 | 293 | Then to see everything that has changed on the trunk since the last release: |
| 293 | 294 | |
| 294 | -<blockquote><pre> | |
| 295 | +<pre> | |
| 295 | 296 | fossil diff --from release --to trunk |
| 296 | -</pre></blockquote> | |
| 297 | +</pre> | |
| 297 | 298 | |
| 298 | 299 | |
| 299 | 300 | <h2 id="order">Resolution Order</h2> |
| 300 | 301 | |
| 301 | 302 | Fossil currently resolves name strings to artifact hashes in the |
| 302 | 303 |
| --- www/checkin_names.wiki | |
| +++ www/checkin_names.wiki | |
| @@ -1,10 +1,9 @@ | |
| 1 | <title>Check-in Names</title> |
| 2 | |
| 3 | <table align="right" border="1" width="33%" cellpadding="10"> |
| 4 | <tr><td> |
| 5 | <h3>Quick Reference</h3> |
| 6 | <ul> |
| 7 | <li> Hash prefix |
| 8 | <li> Branch name |
| 9 | <li> Tag name |
| 10 | <li> Timestamp: <i>YYYY-MM-DD HH:MM:SS</i> |
| @@ -19,29 +18,30 @@ | |
| 19 | <li> <b>next</b> |
| 20 | <li> <b>previous</b> or <b>prev</b> |
| 21 | <li> <b>ckout</b> (<a href='./embeddeddoc.wiki'>embedded docs</a> only) |
| 22 | </ul> |
| 23 | </ul> |
| 24 | </td></tr> |
| 25 | </table> |
| 26 | Many Fossil [/help|commands] and [./webui.wiki | web interface] URLs accept |
| 27 | check-in names as an argument. For example, the "[/help/info|info]" command |
| 28 | accepts an optional check-in name to identify the specific check-in |
| 29 | about which information is desired: |
| 30 | |
| 31 | <blockquote> |
| 32 | <tt>fossil info</tt> <i>checkin-name</i> |
| 33 | </blockquote> |
| 34 | |
| 35 | You are perhaps reading this page from the following URL: |
| 36 | |
| 37 | <blockquote> |
| 38 | https://fossil-scm.org/home/doc/<b>trunk</b>/www/checkin_names.wiki |
| 39 | </blockquote> |
| 40 | |
| 41 | The URL above is an example of an [./embeddeddoc.wiki | embedded documentation] |
| 42 | page in Fossil. The bold term of the pathname is a check-in name that |
| 43 | determines which version of the documentation to display. |
| 44 | |
| 45 | Fossil provides a variety of ways to specify a check-in. This |
| 46 | document describes the various methods. |
| 47 | |
| @@ -49,49 +49,50 @@ | |
| 49 | |
| 50 | The canonical name of a check-in is the hash of its |
| 51 | [./fileformat.wiki#manifest | manifest] expressed as a |
| 52 | [./hashes.md | long lowercase hexadecimal number]. For example: |
| 53 | |
| 54 | <blockquote><pre> |
| 55 | fossil info e5a734a19a9826973e1d073b49dc2a16aa2308f9 |
| 56 | </pre></blockquote> |
| 57 | |
| 58 | The full 40 or 64 character hash is unwieldy to remember and type, though, |
| 59 | so Fossil also accepts a unique prefix of the hash, using any combination |
| 60 | of upper and lower case letters, as long as the prefix is at least 4 |
| 61 | characters long. Hence the following commands all |
| 62 | accomplish the same thing as the above: |
| 63 | |
| 64 | <blockquote><pre> |
| 65 | fossil info e5a734a19a9 |
| 66 | fossil info E5a734A |
| 67 | fossil info e5a7 |
| 68 | </blockquote> |
| 69 | |
| 70 | Many web interface screens identify check-ins by 10- or 16-character |
| 71 | prefix of canonical name. |
| 72 | |
| 73 | <h2 id="tags">Tags And Branch Names</h2> |
| 74 | |
| 75 | Using a tag or branch name where a check-in name is expected causes |
| 76 | Fossil to choose the most recent check-in with that tag or branch name. |
| 77 | So for example, the most recent check-in that |
| 78 | is tagged with "release" as of this writing is [b98ce23d4fc]. |
| 79 | The command: |
| 80 | |
| 81 | <blockquote><pre> |
| 82 | fossil info release |
| 83 | </pre></blockquote> |
| 84 | |
| 85 | …results in the following output: |
| 86 | |
| 87 | <blockquote><pre> |
| 88 | hash: b98ce23d4fc3b734cdc058ee8a67e6dad675ca13 2020-08-20 13:27:04 UTC |
| 89 | parent: 40feec329163103293d98dfcc2d119d1a16b227a 2020-08-20 13:01:51 UTC |
| 90 | tags: release, branch-2.12, version-2.12.1 |
| 91 | comment: Version 2.12.1 (user: drh) |
| 92 | </pre></blockquote> |
| 93 | |
| 94 | There are multiple check-ins that are tagged with "release" but |
| 95 | (as of this writing) the [b98ce23d4fc] |
| 96 | check-in is the most recent so it is the one that is selected. |
| 97 | |
| @@ -107,13 +108,13 @@ | |
| 107 | also happened to have tagged a different check-in with "deed2". If |
| 108 | you use the "deed2" name, does it choose the canonical name or the tag |
| 109 | name? In such cases, you can prefix the tag name with "tag:". |
| 110 | For example: |
| 111 | |
| 112 | <blockquote><tt> |
| 113 | fossil info tag:deed2 |
| 114 | </tt></blockquote> |
| 115 | |
| 116 | The "tag:deed2" name will refer to the most recent check-in |
| 117 | tagged with "deed2" rather than the |
| 118 | check-in whose canonical name begins with "deed2". |
| 119 | |
| @@ -180,21 +181,21 @@ | |
| 180 | rather than as a tag by passing “date:2020-04-01”. |
| 181 | |
| 182 | For an example of how timestamps are useful, |
| 183 | consider the homepage for the Fossil website itself: |
| 184 | |
| 185 | <blockquote> |
| 186 | https://fossil-scm.org/home/doc/<b>trunk</b>/www/index.wiki |
| 187 | </blockquote> |
| 188 | |
| 189 | The bold component of that URL is a check-in name. To see the stored content |
| 190 | of the Fossil website repository as of January 1, 2009, one has merely to change |
| 191 | the URL to the following: |
| 192 | |
| 193 | <blockquote> |
| 194 | https://fossil-scm.org/home/doc/<b>2009-01-01</b>/www/index.wiki |
| 195 | </blockquote> |
| 196 | |
| 197 | (Note that this won't roll you back to the <i>skin</i> and other |
| 198 | cosmetic configurations as of that date. It also won't change screens |
| 199 | like the timeline, which has an independent date selector.) |
| 200 | |
| @@ -203,13 +204,13 @@ | |
| 203 | A check-in name can also take the form of a tag or branch name followed by |
| 204 | a colon and then a timestamp. The combination means to take the most |
| 205 | recent check-in with the given tag or branch which is not more recent than |
| 206 | the timestamp. So, for example: |
| 207 | |
| 208 | <blockquote><tt> |
| 209 | fossil update trunk:2010-07-01T14:30 |
| 210 | </tt></blockquote> |
| 211 | |
| 212 | Would cause Fossil to update the working check-out to be the most recent |
| 213 | check-in on the trunk that is not more recent than 14:30 (UTC) on |
| 214 | July 1, 2010. |
| 215 | |
| @@ -219,13 +220,13 @@ | |
| 219 | last check-in on the parent branch prior to the beginning of the branch. |
| 220 | Such a label is useful, for example, in computing all diffs for a single |
| 221 | branch. The following example will show all changes in the hypothetical |
| 222 | branch "xyzzy": |
| 223 | |
| 224 | <blockquote><tt> |
| 225 | fossil diff --from root:xyzzy --to xyzzy |
| 226 | </tt></blockquote> |
| 227 | |
| 228 | <a id="merge-in"></a> |
| 229 | That doesn't do what you might expect after you merge the parent |
| 230 | branch's changes into the child branch: the above command will include |
| 231 | changes made on the parent branch as well. |
| @@ -241,13 +242,13 @@ | |
| 241 | The prefix "<tt>start:</tt>" gives the first check-in of the named branch. |
| 242 | |
| 243 | The prefixes "<tt>root:</tt>", "<tt>start:</tt>", and "<tt>merge-in:</tt>" |
| 244 | can be chained: one can say for example |
| 245 | |
| 246 | <blockquote><tt> |
| 247 | fossil info merge-in:xyzzy:2022-03-01 |
| 248 | </tt></blockquote> |
| 249 | |
| 250 | to get informations about the most recent merge-in point on the branch |
| 251 | "xyzzy" that happened on or before March 1, 2022. |
| 252 | |
| 253 | <h2 id="special">Special Tags</h2> |
| @@ -256,13 +257,13 @@ | |
| 256 | equivalent to the timestamp "9999-12-31". |
| 257 | |
| 258 | This special name works anywhere you can pass a "NAME", such as with |
| 259 | <tt>/info</tt> URLs: |
| 260 | |
| 261 | <blockquote><pre> |
| 262 | http://localhost:8080/info/tip |
| 263 | </pre></blockquote> |
| 264 | |
| 265 | There are several other special names, but they only work from within a |
| 266 | check-out directory because they are relative to the current checked-out |
| 267 | version: |
| 268 | |
| @@ -282,20 +283,20 @@ | |
| 282 | <h2 id="examples">Additional Examples</h2> |
| 283 | |
| 284 | To view the changes in the most recent check-in prior to the version currently |
| 285 | checked out: |
| 286 | |
| 287 | <blockquote><pre> |
| 288 | fossil diff --from previous --to current |
| 289 | </pre></blockquote> |
| 290 | |
| 291 | Suppose you are of the habit of tagging each release with a "release" tag. |
| 292 | Then to see everything that has changed on the trunk since the last release: |
| 293 | |
| 294 | <blockquote><pre> |
| 295 | fossil diff --from release --to trunk |
| 296 | </pre></blockquote> |
| 297 | |
| 298 | |
| 299 | <h2 id="order">Resolution Order</h2> |
| 300 | |
| 301 | Fossil currently resolves name strings to artifact hashes in the |
| 302 |
| --- www/checkin_names.wiki | |
| +++ www/checkin_names.wiki | |
| @@ -1,10 +1,9 @@ | |
| 1 | <title>Check-in Names</title> |
| 2 | |
| 3 | <div class="sidebar no-label"> |
| 4 | <b>Quick Reference</b> |
| 5 | <ul> |
| 6 | <li> Hash prefix |
| 7 | <li> Branch name |
| 8 | <li> Tag name |
| 9 | <li> Timestamp: <i>YYYY-MM-DD HH:MM:SS</i> |
| @@ -19,29 +18,30 @@ | |
| 18 | <li> <b>next</b> |
| 19 | <li> <b>previous</b> or <b>prev</b> |
| 20 | <li> <b>ckout</b> (<a href='./embeddeddoc.wiki'>embedded docs</a> only) |
| 21 | </ul> |
| 22 | </ul> |
| 23 | </div> |
| 24 | |
| 25 | Many Fossil [/help|commands] and [./webui.wiki | web interface] URLs accept |
| 26 | check-in names as an argument. For example, the "[/help/info|info]" command |
| 27 | accepts an optional check-in name to identify the specific check-in |
| 28 | about which information is desired: |
| 29 | |
| 30 | <pre style="white-space: pre-wrap"> |
| 31 | fossil info <i>checkin-name</i> |
| 32 | </pre> |
| 33 | |
| 34 | You are perhaps reading this page from the following URL: |
| 35 | |
| 36 | <verbatim> |
| 37 | https://fossil-scm.org/home/doc/trunk/www/checkin_names.wiki |
| 38 | </verbatim> |
| 39 | |
| 40 | This is an example of an [./embeddeddoc.wiki | embedded documentation] |
| 41 | page URL. The "trunk" element of the pathname is a |
| 42 | [./glossary.md#check-in | check-in] name that |
| 43 | determines which version of the documentation to display. |
| 44 | |
| 45 | Fossil provides a variety of ways to specify a check-in. This |
| 46 | document describes the various methods. |
| 47 | |
| @@ -49,49 +49,50 @@ | |
| 49 | |
| 50 | The canonical name of a check-in is the hash of its |
| 51 | [./fileformat.wiki#manifest | manifest] expressed as a |
| 52 | [./hashes.md | long lowercase hexadecimal number]. For example: |
| 53 | |
| 54 | <pre> |
| 55 | fossil info e5a734a19a9826973e1d073b49dc2a16aa2308f9 |
| 56 | </pre> |
| 57 | |
| 58 | The full 40 or 64 character hash is unwieldy to remember and type, though, |
| 59 | so Fossil also accepts a unique prefix of the hash, using any combination |
| 60 | of upper and lower case letters, as long as the prefix is at least 4 |
| 61 | characters long. Hence the following commands all |
| 62 | accomplish the same thing as the above: |
| 63 | |
| 64 | <pre> |
| 65 | fossil info e5a734a19a9 |
| 66 | fossil info E5a734A |
| 67 | fossil info e5a7 |
| 68 | </pre> |
| 69 | |
| 70 | Fossil uses this feature itself, identifying check-ins by 8 to 16-character |
| 71 | prefixes of the canonical name in places where it doesn't want to chew |
| 72 | up the screen real estate required to display the whole hash. |
| 73 | |
| 74 | <h2 id="tags">Tags And Branch Names</h2> |
| 75 | |
| 76 | Using a tag or branch name where a check-in name is expected causes |
| 77 | Fossil to choose the most recent check-in with that tag or branch name. |
| 78 | So for example, the most recent check-in that |
| 79 | is tagged with "release" as of this writing is [b98ce23d4fc]. |
| 80 | The command: |
| 81 | |
| 82 | <pre> |
| 83 | fossil info release |
| 84 | </pre> |
| 85 | |
| 86 | …results in the following output: |
| 87 | |
| 88 | <pre> |
| 89 | hash: b98ce23d4fc3b734cdc058ee8a67e6dad675ca13 2020-08-20 13:27:04 UTC |
| 90 | parent: 40feec329163103293d98dfcc2d119d1a16b227a 2020-08-20 13:01:51 UTC |
| 91 | tags: release, branch-2.12, version-2.12.1 |
| 92 | comment: Version 2.12.1 (user: drh) |
| 93 | </pre> |
| 94 | |
| 95 | There are multiple check-ins that are tagged with "release" but |
| 96 | (as of this writing) the [b98ce23d4fc] |
| 97 | check-in is the most recent so it is the one that is selected. |
| 98 | |
| @@ -107,13 +108,13 @@ | |
| 108 | also happened to have tagged a different check-in with "deed2". If |
| 109 | you use the "deed2" name, does it choose the canonical name or the tag |
| 110 | name? In such cases, you can prefix the tag name with "tag:". |
| 111 | For example: |
| 112 | |
| 113 | <pre> |
| 114 | fossil info tag:deed2 |
| 115 | </pre> |
| 116 | |
| 117 | The "tag:deed2" name will refer to the most recent check-in |
| 118 | tagged with "deed2" rather than the |
| 119 | check-in whose canonical name begins with "deed2". |
| 120 | |
| @@ -180,21 +181,21 @@ | |
| 181 | rather than as a tag by passing “date:2020-04-01”. |
| 182 | |
| 183 | For an example of how timestamps are useful, |
| 184 | consider the homepage for the Fossil website itself: |
| 185 | |
| 186 | <pre> |
| 187 | https://fossil-scm.org/home/doc/<b>trunk</b>/www/index.wiki |
| 188 | </pre> |
| 189 | |
| 190 | The bold component of that URL is a check-in name. To see the stored content |
| 191 | of the Fossil website repository as of January 1, 2009, one has merely to change |
| 192 | the URL to the following: |
| 193 | |
| 194 | <pre> |
| 195 | https://fossil-scm.org/home/doc/<b>2009-01-01</b>/www/index.wiki |
| 196 | </pre> |
| 197 | |
| 198 | (Note that this won't roll you back to the <i>skin</i> and other |
| 199 | cosmetic configurations as of that date. It also won't change screens |
| 200 | like the timeline, which has an independent date selector.) |
| 201 | |
| @@ -203,13 +204,13 @@ | |
| 204 | A check-in name can also take the form of a tag or branch name followed by |
| 205 | a colon and then a timestamp. The combination means to take the most |
| 206 | recent check-in with the given tag or branch which is not more recent than |
| 207 | the timestamp. So, for example: |
| 208 | |
| 209 | <pre> |
| 210 | fossil update trunk:2010-07-01T14:30 |
| 211 | </pre> |
| 212 | |
| 213 | Would cause Fossil to update the working check-out to be the most recent |
| 214 | check-in on the trunk that is not more recent than 14:30 (UTC) on |
| 215 | July 1, 2010. |
| 216 | |
| @@ -219,13 +220,13 @@ | |
| 220 | last check-in on the parent branch prior to the beginning of the branch. |
| 221 | Such a label is useful, for example, in computing all diffs for a single |
| 222 | branch. The following example will show all changes in the hypothetical |
| 223 | branch "xyzzy": |
| 224 | |
| 225 | <pre> |
| 226 | fossil diff --from root:xyzzy --to xyzzy |
| 227 | </pre> |
| 228 | |
| 229 | <a id="merge-in"></a> |
| 230 | That doesn't do what you might expect after you merge the parent |
| 231 | branch's changes into the child branch: the above command will include |
| 232 | changes made on the parent branch as well. |
| @@ -241,13 +242,13 @@ | |
| 242 | The prefix "<tt>start:</tt>" gives the first check-in of the named branch. |
| 243 | |
| 244 | The prefixes "<tt>root:</tt>", "<tt>start:</tt>", and "<tt>merge-in:</tt>" |
| 245 | can be chained: one can say for example |
| 246 | |
| 247 | <pre> |
| 248 | fossil info merge-in:xyzzy:2022-03-01 |
| 249 | </pre> |
| 250 | |
| 251 | to get informations about the most recent merge-in point on the branch |
| 252 | "xyzzy" that happened on or before March 1, 2022. |
| 253 | |
| 254 | <h2 id="special">Special Tags</h2> |
| @@ -256,13 +257,13 @@ | |
| 257 | equivalent to the timestamp "9999-12-31". |
| 258 | |
| 259 | This special name works anywhere you can pass a "NAME", such as with |
| 260 | <tt>/info</tt> URLs: |
| 261 | |
| 262 | <pre> |
| 263 | http://localhost:8080/info/tip |
| 264 | </pre> |
| 265 | |
| 266 | There are several other special names, but they only work from within a |
| 267 | check-out directory because they are relative to the current checked-out |
| 268 | version: |
| 269 | |
| @@ -282,20 +283,20 @@ | |
| 283 | <h2 id="examples">Additional Examples</h2> |
| 284 | |
| 285 | To view the changes in the most recent check-in prior to the version currently |
| 286 | checked out: |
| 287 | |
| 288 | <pre> |
| 289 | fossil diff --from previous --to current |
| 290 | </pre> |
| 291 | |
| 292 | Suppose you are of the habit of tagging each release with a "release" tag. |
| 293 | Then to see everything that has changed on the trunk since the last release: |
| 294 | |
| 295 | <pre> |
| 296 | fossil diff --from release --to trunk |
| 297 | </pre> |
| 298 | |
| 299 | |
| 300 | <h2 id="order">Resolution Order</h2> |
| 301 | |
| 302 | Fossil currently resolves name strings to artifact hashes in the |
| 303 |
+2
-2
| --- www/childprojects.wiki | ||
| +++ www/childprojects.wiki | ||
| @@ -28,18 +28,18 @@ | ||
| 28 | 28 | <h2>Creating a Child Project</h2> |
| 29 | 29 | |
| 30 | 30 | To create a new child project, first clone the parent. Then make manual |
| 31 | 31 | SQL changes to the child repository as follows: |
| 32 | 32 | |
| 33 | -<blockquote><verbatim> | |
| 33 | +<verbatim> | |
| 34 | 34 | UPDATE config SET name='parent-project-code' WHERE name='project-code'; |
| 35 | 35 | UPDATE config SET name='parent-project-name' WHERE name='project-name'; |
| 36 | 36 | INSERT INTO config(name,value) |
| 37 | 37 | VALUES('project-code',lower(hex(randomblob(20)))); |
| 38 | 38 | INSERT INTO config(name,value) |
| 39 | 39 | VALUES('project-name','CHILD-PROJECT-NAME'); |
| 40 | -</verbatim></blockquote> | |
| 40 | +</verbatim> | |
| 41 | 41 | |
| 42 | 42 | Modify the CHILD-PROJECT-NAME in the last statement to be the name of |
| 43 | 43 | the child project, of course. |
| 44 | 44 | |
| 45 | 45 | The repository is now a separate project, independent from its parent. |
| 46 | 46 |
| --- www/childprojects.wiki | |
| +++ www/childprojects.wiki | |
| @@ -28,18 +28,18 @@ | |
| 28 | <h2>Creating a Child Project</h2> |
| 29 | |
| 30 | To create a new child project, first clone the parent. Then make manual |
| 31 | SQL changes to the child repository as follows: |
| 32 | |
| 33 | <blockquote><verbatim> |
| 34 | UPDATE config SET name='parent-project-code' WHERE name='project-code'; |
| 35 | UPDATE config SET name='parent-project-name' WHERE name='project-name'; |
| 36 | INSERT INTO config(name,value) |
| 37 | VALUES('project-code',lower(hex(randomblob(20)))); |
| 38 | INSERT INTO config(name,value) |
| 39 | VALUES('project-name','CHILD-PROJECT-NAME'); |
| 40 | </verbatim></blockquote> |
| 41 | |
| 42 | Modify the CHILD-PROJECT-NAME in the last statement to be the name of |
| 43 | the child project, of course. |
| 44 | |
| 45 | The repository is now a separate project, independent from its parent. |
| 46 |
| --- www/childprojects.wiki | |
| +++ www/childprojects.wiki | |
| @@ -28,18 +28,18 @@ | |
| 28 | <h2>Creating a Child Project</h2> |
| 29 | |
| 30 | To create a new child project, first clone the parent. Then make manual |
| 31 | SQL changes to the child repository as follows: |
| 32 | |
| 33 | <verbatim> |
| 34 | UPDATE config SET name='parent-project-code' WHERE name='project-code'; |
| 35 | UPDATE config SET name='parent-project-name' WHERE name='project-name'; |
| 36 | INSERT INTO config(name,value) |
| 37 | VALUES('project-code',lower(hex(randomblob(20)))); |
| 38 | INSERT INTO config(name,value) |
| 39 | VALUES('project-name','CHILD-PROJECT-NAME'); |
| 40 | </verbatim> |
| 41 | |
| 42 | Modify the CHILD-PROJECT-NAME in the last statement to be the name of |
| 43 | the child project, of course. |
| 44 | |
| 45 | The repository is now a separate project, independent from its parent. |
| 46 |
+37
-37
| --- www/ckout-workflows.md | ||
| +++ www/ckout-workflows.md | ||
| @@ -10,32 +10,32 @@ | ||
| 10 | 10 | ## <a id="mcw"></a> Multiple-Checkout Workflow |
| 11 | 11 | |
| 12 | 12 | With Fossil, it is routine to have multiple check-outs from the same |
| 13 | 13 | repository: |
| 14 | 14 | |
| 15 | - fossil clone https://example.com/repo /path/to/repo.fossil | |
| 16 | - | |
| 17 | - mkdir -p ~/src/my-project/trunk | |
| 18 | - cd ~/src/my-project/trunk | |
| 19 | - fossil open /path/to/repo.fossil # implicitly opens “trunk” | |
| 20 | - | |
| 21 | - mkdir ../release | |
| 22 | - cd ../release | |
| 23 | - fossil open /path/to/repo.fossil release | |
| 24 | - | |
| 25 | - mkdir ../my-other-branch | |
| 26 | - cd ../my-other-branch | |
| 27 | - fossil open /path/to/repo.fossil my-other-branch | |
| 28 | - | |
| 29 | - mkdir ../scratch | |
| 30 | - cd ../scratch | |
| 31 | - fossil open /path/to/repo.fossil abcd1234 | |
| 32 | - | |
| 33 | - mkdir ../test | |
| 34 | - cd ../test | |
| 35 | - fossil open /path/to/repo.fossil 2019-04-01 | |
| 36 | - | |
| 15 | + fossil clone https://example.com/repo /path/to/repo.fossil | |
| 16 | + | |
| 17 | + mkdir -p ~/src/my-project/trunk | |
| 18 | + cd ~/src/my-project/trunk | |
| 19 | + fossil open /path/to/repo.fossil # implicitly opens “trunk” | |
| 20 | + | |
| 21 | + mkdir ../release | |
| 22 | + cd ../release | |
| 23 | + fossil open /path/to/repo.fossil release | |
| 24 | + | |
| 25 | + mkdir ../my-other-branch | |
| 26 | + cd ../my-other-branch | |
| 27 | + fossil open /path/to/repo.fossil my-other-branch | |
| 28 | + | |
| 29 | + mkdir ../scratch | |
| 30 | + cd ../scratch | |
| 31 | + fossil open /path/to/repo.fossil abcd1234 | |
| 32 | + | |
| 33 | + mkdir ../test | |
| 34 | + cd ../test | |
| 35 | + fossil open /path/to/repo.fossil 2019-04-01 | |
| 36 | + | |
| 37 | 37 | Now you have five separate check-out directories: one each for: |
| 38 | 38 | |
| 39 | 39 | * trunk |
| 40 | 40 | * the latest tagged public release |
| 41 | 41 | * an alternate branch you’re working on |
| @@ -73,18 +73,18 @@ | ||
| 73 | 73 | |
| 74 | 74 | #### <a id="idiomatic"></a> The Idiomatic Fossil Way |
| 75 | 75 | |
| 76 | 76 | The most idiomatic way is as follows: |
| 77 | 77 | |
| 78 | - fossil clone https://example.com/repo /path/to/repo.fossil | |
| 79 | - mkdir work-dir | |
| 80 | - cd work-dir | |
| 81 | - fossil open /path/to/repo.fossil | |
| 82 | - ...work on trunk... | |
| 83 | - | |
| 84 | - fossil update my-other-branch | |
| 85 | - ...work on your other branch in the same directory... | |
| 78 | + fossil clone https://example.com/repo /path/to/repo.fossil | |
| 79 | + mkdir work-dir | |
| 80 | + cd work-dir | |
| 81 | + fossil open /path/to/repo.fossil | |
| 82 | + ...work on trunk... | |
| 83 | + | |
| 84 | + fossil update my-other-branch | |
| 85 | + ...work on your other branch in the same directory... | |
| 86 | 86 | |
| 87 | 87 | Basically, you replace the `cd` commands in the multiple checkouts |
| 88 | 88 | workflow above with `fossil up` commands. |
| 89 | 89 | |
| 90 | 90 | |
| @@ -91,13 +91,13 @@ | ||
| 91 | 91 | #### <a id="open"></a> Opening a Repository by URI |
| 92 | 92 | |
| 93 | 93 | In Fossil 2.12, we added a feature to simplify the single-worktree use |
| 94 | 94 | case: |
| 95 | 95 | |
| 96 | - mkdir work-dir | |
| 97 | - cd work-dir | |
| 98 | - fossil open https://example.com/repo | |
| 96 | + mkdir work-dir | |
| 97 | + cd work-dir | |
| 98 | + fossil open https://example.com/repo | |
| 99 | 99 | |
| 100 | 100 | Now you have “trunk” open in `work-dir`, with the repo file stored as |
| 101 | 101 | `repo.fossil` in that same directory. |
| 102 | 102 | |
| 103 | 103 | Users of Git may be surprised that it doesn’t create a directory for you |
| @@ -111,33 +111,33 @@ | ||
| 111 | 111 | |
| 112 | 112 | #### <a id="clone"></a> Git-Like Clone-and-Open |
| 113 | 113 | |
| 114 | 114 | In Fossil 2.14, we added a more Git-like alternative: |
| 115 | 115 | |
| 116 | - fossil clone https://fossil-scm.org/fossil | |
| 117 | - cd fossil | |
| 116 | + fossil clone https://fossil-scm.org/fossil | |
| 117 | + cd fossil | |
| 118 | 118 | |
| 119 | 119 | This results in a `fossil.fossil` repo DB file and a `fossil/` working |
| 120 | 120 | directory. |
| 121 | 121 | |
| 122 | 122 | Note that our `clone URI` behavior does not commingle the repo and |
| 123 | 123 | check-out, solving our major problem with the Git design. |
| 124 | 124 | |
| 125 | 125 | If you want the repo to be named something else, adjust the URL: |
| 126 | 126 | |
| 127 | - fossil clone https://fossil-scm.org/fossil/fsl | |
| 127 | + fossil clone https://fossil-scm.org/fossil/fsl | |
| 128 | 128 | |
| 129 | 129 | That gets you `fsl.fossil` checked out into `fsl/`. |
| 130 | 130 | |
| 131 | 131 | For sites where the repo isn’t served from a subdirectory like this, you |
| 132 | 132 | might need another form of the URL. For example, you might have your |
| 133 | 133 | repo served from `dev.example.com` and want it cloned as `my-project`: |
| 134 | 134 | |
| 135 | - fossil clone https://dev.example.com/repo/my-project | |
| 135 | + fossil clone https://dev.example.com/repo/my-project | |
| 136 | 136 | |
| 137 | 137 | The `/repo` addition is the key: whatever comes after is used as the |
| 138 | 138 | repository name. [See the docs][clone] for more details. |
| 139 | 139 | |
| 140 | 140 | [caod]: https://fossil-scm.org/forum/forumpost/3f143cec74 |
| 141 | 141 | [clone]: /help?cmd=clone |
| 142 | 142 | |
| 143 | 143 | <div style="height:50em" id="this-space-intentionally-left-blank"></div> |
| 144 | 144 |
| --- www/ckout-workflows.md | |
| +++ www/ckout-workflows.md | |
| @@ -10,32 +10,32 @@ | |
| 10 | ## <a id="mcw"></a> Multiple-Checkout Workflow |
| 11 | |
| 12 | With Fossil, it is routine to have multiple check-outs from the same |
| 13 | repository: |
| 14 | |
| 15 | fossil clone https://example.com/repo /path/to/repo.fossil |
| 16 | |
| 17 | mkdir -p ~/src/my-project/trunk |
| 18 | cd ~/src/my-project/trunk |
| 19 | fossil open /path/to/repo.fossil # implicitly opens “trunk” |
| 20 | |
| 21 | mkdir ../release |
| 22 | cd ../release |
| 23 | fossil open /path/to/repo.fossil release |
| 24 | |
| 25 | mkdir ../my-other-branch |
| 26 | cd ../my-other-branch |
| 27 | fossil open /path/to/repo.fossil my-other-branch |
| 28 | |
| 29 | mkdir ../scratch |
| 30 | cd ../scratch |
| 31 | fossil open /path/to/repo.fossil abcd1234 |
| 32 | |
| 33 | mkdir ../test |
| 34 | cd ../test |
| 35 | fossil open /path/to/repo.fossil 2019-04-01 |
| 36 | |
| 37 | Now you have five separate check-out directories: one each for: |
| 38 | |
| 39 | * trunk |
| 40 | * the latest tagged public release |
| 41 | * an alternate branch you’re working on |
| @@ -73,18 +73,18 @@ | |
| 73 | |
| 74 | #### <a id="idiomatic"></a> The Idiomatic Fossil Way |
| 75 | |
| 76 | The most idiomatic way is as follows: |
| 77 | |
| 78 | fossil clone https://example.com/repo /path/to/repo.fossil |
| 79 | mkdir work-dir |
| 80 | cd work-dir |
| 81 | fossil open /path/to/repo.fossil |
| 82 | ...work on trunk... |
| 83 | |
| 84 | fossil update my-other-branch |
| 85 | ...work on your other branch in the same directory... |
| 86 | |
| 87 | Basically, you replace the `cd` commands in the multiple checkouts |
| 88 | workflow above with `fossil up` commands. |
| 89 | |
| 90 | |
| @@ -91,13 +91,13 @@ | |
| 91 | #### <a id="open"></a> Opening a Repository by URI |
| 92 | |
| 93 | In Fossil 2.12, we added a feature to simplify the single-worktree use |
| 94 | case: |
| 95 | |
| 96 | mkdir work-dir |
| 97 | cd work-dir |
| 98 | fossil open https://example.com/repo |
| 99 | |
| 100 | Now you have “trunk” open in `work-dir`, with the repo file stored as |
| 101 | `repo.fossil` in that same directory. |
| 102 | |
| 103 | Users of Git may be surprised that it doesn’t create a directory for you |
| @@ -111,33 +111,33 @@ | |
| 111 | |
| 112 | #### <a id="clone"></a> Git-Like Clone-and-Open |
| 113 | |
| 114 | In Fossil 2.14, we added a more Git-like alternative: |
| 115 | |
| 116 | fossil clone https://fossil-scm.org/fossil |
| 117 | cd fossil |
| 118 | |
| 119 | This results in a `fossil.fossil` repo DB file and a `fossil/` working |
| 120 | directory. |
| 121 | |
| 122 | Note that our `clone URI` behavior does not commingle the repo and |
| 123 | check-out, solving our major problem with the Git design. |
| 124 | |
| 125 | If you want the repo to be named something else, adjust the URL: |
| 126 | |
| 127 | fossil clone https://fossil-scm.org/fossil/fsl |
| 128 | |
| 129 | That gets you `fsl.fossil` checked out into `fsl/`. |
| 130 | |
| 131 | For sites where the repo isn’t served from a subdirectory like this, you |
| 132 | might need another form of the URL. For example, you might have your |
| 133 | repo served from `dev.example.com` and want it cloned as `my-project`: |
| 134 | |
| 135 | fossil clone https://dev.example.com/repo/my-project |
| 136 | |
| 137 | The `/repo` addition is the key: whatever comes after is used as the |
| 138 | repository name. [See the docs][clone] for more details. |
| 139 | |
| 140 | [caod]: https://fossil-scm.org/forum/forumpost/3f143cec74 |
| 141 | [clone]: /help?cmd=clone |
| 142 | |
| 143 | <div style="height:50em" id="this-space-intentionally-left-blank"></div> |
| 144 |
| --- www/ckout-workflows.md | |
| +++ www/ckout-workflows.md | |
| @@ -10,32 +10,32 @@ | |
| 10 | ## <a id="mcw"></a> Multiple-Checkout Workflow |
| 11 | |
| 12 | With Fossil, it is routine to have multiple check-outs from the same |
| 13 | repository: |
| 14 | |
| 15 | fossil clone https://example.com/repo /path/to/repo.fossil |
| 16 | |
| 17 | mkdir -p ~/src/my-project/trunk |
| 18 | cd ~/src/my-project/trunk |
| 19 | fossil open /path/to/repo.fossil # implicitly opens “trunk” |
| 20 | |
| 21 | mkdir ../release |
| 22 | cd ../release |
| 23 | fossil open /path/to/repo.fossil release |
| 24 | |
| 25 | mkdir ../my-other-branch |
| 26 | cd ../my-other-branch |
| 27 | fossil open /path/to/repo.fossil my-other-branch |
| 28 | |
| 29 | mkdir ../scratch |
| 30 | cd ../scratch |
| 31 | fossil open /path/to/repo.fossil abcd1234 |
| 32 | |
| 33 | mkdir ../test |
| 34 | cd ../test |
| 35 | fossil open /path/to/repo.fossil 2019-04-01 |
| 36 | |
| 37 | Now you have five separate check-out directories: one each for: |
| 38 | |
| 39 | * trunk |
| 40 | * the latest tagged public release |
| 41 | * an alternate branch you’re working on |
| @@ -73,18 +73,18 @@ | |
| 73 | |
| 74 | #### <a id="idiomatic"></a> The Idiomatic Fossil Way |
| 75 | |
| 76 | The most idiomatic way is as follows: |
| 77 | |
| 78 | fossil clone https://example.com/repo /path/to/repo.fossil |
| 79 | mkdir work-dir |
| 80 | cd work-dir |
| 81 | fossil open /path/to/repo.fossil |
| 82 | ...work on trunk... |
| 83 | |
| 84 | fossil update my-other-branch |
| 85 | ...work on your other branch in the same directory... |
| 86 | |
| 87 | Basically, you replace the `cd` commands in the multiple checkouts |
| 88 | workflow above with `fossil up` commands. |
| 89 | |
| 90 | |
| @@ -91,13 +91,13 @@ | |
| 91 | #### <a id="open"></a> Opening a Repository by URI |
| 92 | |
| 93 | In Fossil 2.12, we added a feature to simplify the single-worktree use |
| 94 | case: |
| 95 | |
| 96 | mkdir work-dir |
| 97 | cd work-dir |
| 98 | fossil open https://example.com/repo |
| 99 | |
| 100 | Now you have “trunk” open in `work-dir`, with the repo file stored as |
| 101 | `repo.fossil` in that same directory. |
| 102 | |
| 103 | Users of Git may be surprised that it doesn’t create a directory for you |
| @@ -111,33 +111,33 @@ | |
| 111 | |
| 112 | #### <a id="clone"></a> Git-Like Clone-and-Open |
| 113 | |
| 114 | In Fossil 2.14, we added a more Git-like alternative: |
| 115 | |
| 116 | fossil clone https://fossil-scm.org/fossil |
| 117 | cd fossil |
| 118 | |
| 119 | This results in a `fossil.fossil` repo DB file and a `fossil/` working |
| 120 | directory. |
| 121 | |
| 122 | Note that our `clone URI` behavior does not commingle the repo and |
| 123 | check-out, solving our major problem with the Git design. |
| 124 | |
| 125 | If you want the repo to be named something else, adjust the URL: |
| 126 | |
| 127 | fossil clone https://fossil-scm.org/fossil/fsl |
| 128 | |
| 129 | That gets you `fsl.fossil` checked out into `fsl/`. |
| 130 | |
| 131 | For sites where the repo isn’t served from a subdirectory like this, you |
| 132 | might need another form of the URL. For example, you might have your |
| 133 | repo served from `dev.example.com` and want it cloned as `my-project`: |
| 134 | |
| 135 | fossil clone https://dev.example.com/repo/my-project |
| 136 | |
| 137 | The `/repo` addition is the key: whatever comes after is used as the |
| 138 | repository name. [See the docs][clone] for more details. |
| 139 | |
| 140 | [caod]: https://fossil-scm.org/forum/forumpost/3f143cec74 |
| 141 | [clone]: /help?cmd=clone |
| 142 | |
| 143 | <div style="height:50em" id="this-space-intentionally-left-blank"></div> |
| 144 |
+12
-15
| --- www/concepts.wiki | ||
| +++ www/concepts.wiki | ||
| @@ -1,7 +1,6 @@ | ||
| 1 | 1 | <title>Fossil Concepts</title> |
| 2 | -<h1 align="center">Fossil Concepts</h1> | |
| 3 | 2 | |
| 4 | 3 | <h2>1.0 Introduction</h2> |
| 5 | 4 | |
| 6 | 5 | [./index.wiki | Fossil] is a |
| 7 | 6 | [http://en.wikipedia.org/wiki/Software_configuration_management | software configuration management] system. |
| @@ -115,17 +114,17 @@ | ||
| 115 | 114 | it is computationally intractable to generate a file that will have that |
| 116 | 115 | same artifact ID. |
| 117 | 116 | |
| 118 | 117 | Artifact IDs look something like this: |
| 119 | 118 | |
| 120 | -<blockquote><b> | |
| 121 | -6089f0b563a9db0a6d90682fe47fd7161ff867c8<br> | |
| 122 | -59712614a1b3ccfd84078a37fa5b606e28434326<br> | |
| 123 | -19dbf73078be9779edd6a0156195e610f81c94f9<br> | |
| 124 | -b4104959a67175f02d6b415480be22a239f1f077<br> | |
| 119 | +<pre> | |
| 120 | +6089f0b563a9db0a6d90682fe47fd7161ff867c8 | |
| 121 | +59712614a1b3ccfd84078a37fa5b606e28434326 | |
| 122 | +19dbf73078be9779edd6a0156195e610f81c94f9 | |
| 123 | +b4104959a67175f02d6b415480be22a239f1f077 | |
| 125 | 124 | 997c9d6ae03ad114b2b57f04e9eeef17dcb82788 |
| 126 | -</b></blockquote> | |
| 125 | +</pre> | |
| 127 | 126 | |
| 128 | 127 | When referring to an artifact using Fossil, you can use a unique |
| 129 | 128 | prefix of the artifact ID that is four characters or longer. This saves |
| 130 | 129 | a lot of typing. When displaying artifact IDs, Fossil will usually only |
| 131 | 130 | show the first 10 digits since that is normally enough to uniquely |
| @@ -239,13 +238,11 @@ | ||
| 239 | 238 | |
| 240 | 239 | To use Fossil, simply type the name of the executable in your |
| 241 | 240 | shell, followed by one of the various built-in commands and |
| 242 | 241 | arguments appropriate for that command. For example: |
| 243 | 242 | |
| 244 | -<blockquote><b> | |
| 245 | -fossil help | |
| 246 | -</b></blockquote> | |
| 243 | +<pre>fossil help</pre> | |
| 247 | 244 | |
| 248 | 245 | In the next section, when we say things like "use the <b>help</b> |
| 249 | 246 | command" we mean to use the command name "help" as the first |
| 250 | 247 | token after the name of the Fossil executable, as shown above. |
| 251 | 248 | |
| @@ -282,15 +279,15 @@ | ||
| 282 | 279 | |
| 283 | 280 | The default setting for Fossil is to be in autosync mode. You |
| 284 | 281 | can change the autosync setting or check the current autosync |
| 285 | 282 | setting using commands like: |
| 286 | 283 | |
| 287 | -<blockquote> | |
| 288 | -<b>fossil setting autosync on<br> | |
| 289 | -fossil setting autosync off<br> | |
| 290 | -<b>fossil settings</b> | |
| 291 | -</blockquote> | |
| 284 | +<pre> | |
| 285 | +fossil setting autosync on | |
| 286 | +fossil setting autosync off | |
| 287 | +fossil settings | |
| 288 | +</pre> | |
| 292 | 289 | |
| 293 | 290 | By default, Fossil runs with autosync mode turned on. The |
| 294 | 291 | authors finds that projects run more smoothly in autosync mode since |
| 295 | 292 | autosync helps to prevent pointless forking and merging and helps keeps |
| 296 | 293 | all collaborators working on exactly the same code rather than on their |
| 297 | 294 |
| --- www/concepts.wiki | |
| +++ www/concepts.wiki | |
| @@ -1,7 +1,6 @@ | |
| 1 | <title>Fossil Concepts</title> |
| 2 | <h1 align="center">Fossil Concepts</h1> |
| 3 | |
| 4 | <h2>1.0 Introduction</h2> |
| 5 | |
| 6 | [./index.wiki | Fossil] is a |
| 7 | [http://en.wikipedia.org/wiki/Software_configuration_management | software configuration management] system. |
| @@ -115,17 +114,17 @@ | |
| 115 | it is computationally intractable to generate a file that will have that |
| 116 | same artifact ID. |
| 117 | |
| 118 | Artifact IDs look something like this: |
| 119 | |
| 120 | <blockquote><b> |
| 121 | 6089f0b563a9db0a6d90682fe47fd7161ff867c8<br> |
| 122 | 59712614a1b3ccfd84078a37fa5b606e28434326<br> |
| 123 | 19dbf73078be9779edd6a0156195e610f81c94f9<br> |
| 124 | b4104959a67175f02d6b415480be22a239f1f077<br> |
| 125 | 997c9d6ae03ad114b2b57f04e9eeef17dcb82788 |
| 126 | </b></blockquote> |
| 127 | |
| 128 | When referring to an artifact using Fossil, you can use a unique |
| 129 | prefix of the artifact ID that is four characters or longer. This saves |
| 130 | a lot of typing. When displaying artifact IDs, Fossil will usually only |
| 131 | show the first 10 digits since that is normally enough to uniquely |
| @@ -239,13 +238,11 @@ | |
| 239 | |
| 240 | To use Fossil, simply type the name of the executable in your |
| 241 | shell, followed by one of the various built-in commands and |
| 242 | arguments appropriate for that command. For example: |
| 243 | |
| 244 | <blockquote><b> |
| 245 | fossil help |
| 246 | </b></blockquote> |
| 247 | |
| 248 | In the next section, when we say things like "use the <b>help</b> |
| 249 | command" we mean to use the command name "help" as the first |
| 250 | token after the name of the Fossil executable, as shown above. |
| 251 | |
| @@ -282,15 +279,15 @@ | |
| 282 | |
| 283 | The default setting for Fossil is to be in autosync mode. You |
| 284 | can change the autosync setting or check the current autosync |
| 285 | setting using commands like: |
| 286 | |
| 287 | <blockquote> |
| 288 | <b>fossil setting autosync on<br> |
| 289 | fossil setting autosync off<br> |
| 290 | <b>fossil settings</b> |
| 291 | </blockquote> |
| 292 | |
| 293 | By default, Fossil runs with autosync mode turned on. The |
| 294 | authors finds that projects run more smoothly in autosync mode since |
| 295 | autosync helps to prevent pointless forking and merging and helps keeps |
| 296 | all collaborators working on exactly the same code rather than on their |
| 297 |
| --- www/concepts.wiki | |
| +++ www/concepts.wiki | |
| @@ -1,7 +1,6 @@ | |
| 1 | <title>Fossil Concepts</title> |
| 2 | |
| 3 | <h2>1.0 Introduction</h2> |
| 4 | |
| 5 | [./index.wiki | Fossil] is a |
| 6 | [http://en.wikipedia.org/wiki/Software_configuration_management | software configuration management] system. |
| @@ -115,17 +114,17 @@ | |
| 114 | it is computationally intractable to generate a file that will have that |
| 115 | same artifact ID. |
| 116 | |
| 117 | Artifact IDs look something like this: |
| 118 | |
| 119 | <pre> |
| 120 | 6089f0b563a9db0a6d90682fe47fd7161ff867c8 |
| 121 | 59712614a1b3ccfd84078a37fa5b606e28434326 |
| 122 | 19dbf73078be9779edd6a0156195e610f81c94f9 |
| 123 | b4104959a67175f02d6b415480be22a239f1f077 |
| 124 | 997c9d6ae03ad114b2b57f04e9eeef17dcb82788 |
| 125 | </pre> |
| 126 | |
| 127 | When referring to an artifact using Fossil, you can use a unique |
| 128 | prefix of the artifact ID that is four characters or longer. This saves |
| 129 | a lot of typing. When displaying artifact IDs, Fossil will usually only |
| 130 | show the first 10 digits since that is normally enough to uniquely |
| @@ -239,13 +238,11 @@ | |
| 238 | |
| 239 | To use Fossil, simply type the name of the executable in your |
| 240 | shell, followed by one of the various built-in commands and |
| 241 | arguments appropriate for that command. For example: |
| 242 | |
| 243 | <pre>fossil help</pre> |
| 244 | |
| 245 | In the next section, when we say things like "use the <b>help</b> |
| 246 | command" we mean to use the command name "help" as the first |
| 247 | token after the name of the Fossil executable, as shown above. |
| 248 | |
| @@ -282,15 +279,15 @@ | |
| 279 | |
| 280 | The default setting for Fossil is to be in autosync mode. You |
| 281 | can change the autosync setting or check the current autosync |
| 282 | setting using commands like: |
| 283 | |
| 284 | <pre> |
| 285 | fossil setting autosync on |
| 286 | fossil setting autosync off |
| 287 | fossil settings |
| 288 | </pre> |
| 289 | |
| 290 | By default, Fossil runs with autosync mode turned on. The |
| 291 | authors finds that projects run more smoothly in autosync mode since |
| 292 | autosync helps to prevent pointless forking and merging and helps keeps |
| 293 | all collaborators working on exactly the same code rather than on their |
| 294 |
+106
-166
| --- www/containers.md | ||
| +++ www/containers.md | ||
| @@ -13,20 +13,16 @@ | ||
| 13 | 13 | ## 1. Quick Start |
| 14 | 14 | |
| 15 | 15 | Fossil ships a `Dockerfile` at the top of its source tree, |
| 16 | 16 | [here][DF], which you can build like so: |
| 17 | 17 | |
| 18 | -``` | |
| 19 | - $ docker build -t fossil . | |
| 20 | -``` | |
| 18 | + $ docker build -t fossil . | |
| 21 | 19 | |
| 22 | 20 | If the image built successfully, you can create a container from it and |
| 23 | 21 | test that it runs: |
| 24 | 22 | |
| 25 | -``` | |
| 26 | - $ docker run --name fossil -p 9999:8080/tcp fossil | |
| 27 | -``` | |
| 23 | + $ docker run --name fossil -p 9999:8080/tcp fossil | |
| 28 | 24 | |
| 29 | 25 | This shows us remapping the internal TCP listening port as 9999 on the |
| 30 | 26 | host. This feature of OCI runtimes means there’s little point to using |
| 31 | 27 | the “`fossil server --port`” feature inside the container. We can let |
| 32 | 28 | Fossil default to 8080 internally, then remap it to wherever we want it |
| @@ -44,13 +40,11 @@ | ||
| 44 | 40 | with the `DCFLAGS` variable. (DB is short for “`docker build`”, and DC |
| 45 | 41 | is short for “`docker create`”, a sub-step of the “run” target.) |
| 46 | 42 | To get the custom port setting as in |
| 47 | 43 | second command above, say: |
| 48 | 44 | |
| 49 | -``` | |
| 50 | - $ make container-run DCFLAGS='-p 9999:8080/tcp' | |
| 51 | -``` | |
| 45 | + $ make container-run DCFLAGS='-p 9999:8080/tcp' | |
| 52 | 46 | |
| 53 | 47 | Contrast the raw “`docker`” commands above, which create an |
| 54 | 48 | _unversioned_ image called `fossil:latest` and from that a container |
| 55 | 49 | simply called `fossil`. The unversioned names are more convenient for |
| 56 | 50 | interactive use, while the versioned ones are good for CI/CD type |
| @@ -81,15 +75,13 @@ | ||
| 81 | 75 | ### <a id="repo-inside"></a> 2.1 Storing the Repo Inside the Container |
| 82 | 76 | |
| 83 | 77 | The simplest method is to stop the container if it was running, then |
| 84 | 78 | say: |
| 85 | 79 | |
| 86 | -``` | |
| 87 | - $ docker cp /path/to/my-project.fossil fossil:/museum/repo.fossil | |
| 88 | - $ docker start fossil | |
| 89 | - $ docker exec fossil chown -R 499 /museum | |
| 90 | -``` | |
| 80 | + $ docker cp /path/to/my-project.fossil fossil:/museum/repo.fossil | |
| 81 | + $ docker start fossil | |
| 82 | + $ docker exec fossil chown -R 499 /museum | |
| 91 | 83 | |
| 92 | 84 | That copies the local Fossil repo into the container where the server |
| 93 | 85 | expects to find it, so that the “start” command causes it to serve from |
| 94 | 86 | that copied-in file instead. Since it lives atop the immutable base |
| 95 | 87 | layers, it persists as part of the container proper, surviving restarts. |
| @@ -120,17 +112,15 @@ | ||
| 120 | 112 | designed to be killed off at the slightest cause, rebuilt, and |
| 121 | 113 | redeployed. If you do that with the repo inside the container, it gets |
| 122 | 114 | destroyed, too. The solution is to replace the “run” command above with |
| 123 | 115 | the following: |
| 124 | 116 | |
| 125 | -``` | |
| 126 | - $ docker run \ | |
| 127 | - --publish 9999:8080 \ | |
| 128 | - --name fossil-bind-mount \ | |
| 129 | - --volume ~/museum:/museum \ | |
| 130 | - fossil | |
| 131 | -``` | |
| 117 | + $ docker run \ | |
| 118 | + --publish 9999:8080 \ | |
| 119 | + --name fossil-bind-mount \ | |
| 120 | + --volume ~/museum:/museum \ | |
| 121 | + fossil | |
| 132 | 122 | |
| 133 | 123 | Because this bind mount maps a host-side directory (`~/museum`) into the |
| 134 | 124 | container, you don’t need to `docker cp` the repo into the container at |
| 135 | 125 | all. It still expects to find the repository as `repo.fossil` under that |
| 136 | 126 | directory, but now both the host and the container can see that repo DB. |
| @@ -151,13 +141,11 @@ | ||
| 151 | 141 | You might be aware that OCI containers allow mapping a single file into |
| 152 | 142 | the repository rather than a whole directory. Since Fossil repositories |
| 153 | 143 | are specially-formatted SQLite databases, you might be wondering why we |
| 154 | 144 | don’t say things like: |
| 155 | 145 | |
| 156 | -``` | |
| 157 | - --volume ~/museum/my-project.fossil:/museum/repo.fossil | |
| 158 | -``` | |
| 146 | + --volume ~/museum/my-project.fossil:/museum/repo.fossil | |
| 159 | 147 | |
| 160 | 148 | That lets us have a convenient file name for the project outside the |
| 161 | 149 | container while letting the configuration inside the container refer to |
| 162 | 150 | the generic “`/museum/repo.fossil`” name. Why should we have to name |
| 163 | 151 | the repo generically on the outside merely to placate the container? |
| @@ -292,21 +280,19 @@ | ||
| 292 | 280 | |
| 293 | 281 | All together, we recommend adding the following options to your |
| 294 | 282 | “`docker run`” commands, as well as to any “`docker create`” command |
| 295 | 283 | that will be followed by “`docker start`”: |
| 296 | 284 | |
| 297 | -``` | |
| 298 | - --cap-drop AUDIT_WRITE \ | |
| 299 | - --cap-drop CHOWN \ | |
| 300 | - --cap-drop FSETID \ | |
| 301 | - --cap-drop KILL \ | |
| 302 | - --cap-drop MKNOD \ | |
| 303 | - --cap-drop NET_BIND_SERVICE \ | |
| 304 | - --cap-drop NET_RAW \ | |
| 305 | - --cap-drop SETFCAP \ | |
| 306 | - --cap-drop SETPCAP | |
| 307 | -``` | |
| 285 | + --cap-drop AUDIT_WRITE \ | |
| 286 | + --cap-drop CHOWN \ | |
| 287 | + --cap-drop FSETID \ | |
| 288 | + --cap-drop KILL \ | |
| 289 | + --cap-drop MKNOD \ | |
| 290 | + --cap-drop NET_BIND_SERVICE \ | |
| 291 | + --cap-drop NET_RAW \ | |
| 292 | + --cap-drop SETFCAP \ | |
| 293 | + --cap-drop SETPCAP | |
| 308 | 294 | |
| 309 | 295 | In the next section, we’ll show a case where you create a container |
| 310 | 296 | without ever running it, making these options pointless. |
| 311 | 297 | |
| 312 | 298 | [backoffice]: ./backoffice.md |
| @@ -326,16 +312,14 @@ | ||
| 326 | 312 | modern Linux distros make this [surprisingly difficult][lsl], but Alpine’s |
| 327 | 313 | back-to-basics nature makes static builds work the way they used to, |
| 328 | 314 | back in the day. If that’s all you’re after, you can do so as easily as |
| 329 | 315 | this: |
| 330 | 316 | |
| 331 | -``` | |
| 332 | - $ docker build -t fossil . | |
| 333 | - $ docker create --name fossil-static-tmp fossil | |
| 334 | - $ docker cp fossil-static-tmp:/bin/fossil . | |
| 335 | - $ docker container rm fossil-static-tmp | |
| 336 | -``` | |
| 317 | + $ docker build -t fossil . | |
| 318 | + $ docker create --name fossil-static-tmp fossil | |
| 319 | + $ docker cp fossil-static-tmp:/bin/fossil . | |
| 320 | + $ docker container rm fossil-static-tmp | |
| 337 | 321 | |
| 338 | 322 | The result is six or seven megs, depending on the CPU architecture you |
| 339 | 323 | build for. It’s built stripped. |
| 340 | 324 | |
| 341 | 325 | [lsl]: https://stackoverflow.com/questions/3430400/linux-static-linking-is-dead |
| @@ -347,19 +331,15 @@ | ||
| 347 | 331 | |
| 348 | 332 | The default version of Fossil fetched in the build is the version in the |
| 349 | 333 | checkout directory at the time you run it. You could override it to get |
| 350 | 334 | a release build like so: |
| 351 | 335 | |
| 352 | -``` | |
| 353 | - $ docker build -t fossil --build-arg FSLVER=version-2.20 . | |
| 354 | -``` | |
| 336 | + $ docker build -t fossil --build-arg FSLVER=version-2.20 . | |
| 355 | 337 | |
| 356 | 338 | Or equivalently, using Fossil’s `Makefile` convenience target: |
| 357 | 339 | |
| 358 | -``` | |
| 359 | - $ make container-image DBFLAGS='--build-arg FSLVER=version-2.20' | |
| 360 | -``` | |
| 340 | + $ make container-image DBFLAGS='--build-arg FSLVER=version-2.20' | |
| 361 | 341 | |
| 362 | 342 | While you could instead use the generic |
| 363 | 343 | “`release`” tag here, it’s better to use a specific version number |
| 364 | 344 | since container builders cache downloaded files, hoping to |
| 365 | 345 | reuse them across builds. If you ask for “`release`” before a new |
| @@ -384,13 +364,11 @@ | ||
| 384 | 364 | 500 and went *down* one instead to reduce the chance of a conflict to as |
| 385 | 365 | close to zero as we can manage. |
| 386 | 366 | |
| 387 | 367 | To change it to something else, say: |
| 388 | 368 | |
| 389 | -``` | |
| 390 | - $ make container-image DBFLAGS='--build-arg UID=501' | |
| 391 | -``` | |
| 369 | + $ make container-image DBFLAGS='--build-arg UID=501' | |
| 392 | 370 | |
| 393 | 371 | This is particularly useful if you’re putting your repository on a |
| 394 | 372 | separate volume since the IDs “leak” out into the host environment via |
| 395 | 373 | file permissions. You may therefore wish them to mean something on both |
| 396 | 374 | sides of the container barrier rather than have “499” appear on the host |
| @@ -403,25 +381,21 @@ | ||
| 403 | 381 | for use of any OCI container system that implements the same interfaces. |
| 404 | 382 | We go into more details about this [below](#light), but |
| 405 | 383 | for now, it suffices to point out that you can switch to Podman while |
| 406 | 384 | using our `Makefile` convenience targets unchanged by saying: |
| 407 | 385 | |
| 408 | -``` | |
| 409 | 386 | $ make CENGINE=podman container-run |
| 410 | -``` | |
| 411 | 387 | |
| 412 | 388 | |
| 413 | 389 | ### 5.4 <a id="config"></a>Fossil Configuration Options |
| 414 | 390 | |
| 415 | 391 | You can use this same mechanism to enable non-default Fossil |
| 416 | 392 | configuration options in your build. For instance, to turn on |
| 417 | 393 | the JSON API and the TH1 docs extension: |
| 418 | 394 | |
| 419 | -``` | |
| 420 | - $ make container-image \ | |
| 421 | - DBFLAGS='--build-arg FSLCFG="--json --with-th1-docs"' | |
| 422 | -``` | |
| 395 | + $ make container-image \ | |
| 396 | + DBFLAGS='--build-arg FSLCFG="--json --with-th1-docs"' | |
| 423 | 397 | |
| 424 | 398 | If you also wanted [the Tcl evaluation extension](./th1.md#tclEval), |
| 425 | 399 | that brings us to [the next point](#run). |
| 426 | 400 | |
| 427 | 401 | |
| @@ -429,20 +403,20 @@ | ||
| 429 | 403 | |
| 430 | 404 | If you want a basic shell environment for temporary debugging of the |
| 431 | 405 | running container, that’s easily added. Simply change this line in the |
| 432 | 406 | `Dockerfile`… |
| 433 | 407 | |
| 434 | - FROM scratch AS run | |
| 408 | + FROM scratch AS run | |
| 435 | 409 | |
| 436 | 410 | …to this: |
| 437 | 411 | |
| 438 | - FROM busybox AS run | |
| 412 | + FROM busybox AS run | |
| 439 | 413 | |
| 440 | 414 | Rebuild and redeploy to give your Fossil container a [BusyBox]-based |
| 441 | 415 | shell environment that you can get into via: |
| 442 | 416 | |
| 443 | - $ docker exec -it -u fossil $(make container-version) sh | |
| 417 | + $ docker exec -it -u fossil $(make container-version) sh | |
| 444 | 418 | |
| 445 | 419 | That command assumes you built it via “`make container`” and are |
| 446 | 420 | therefore using its versioning scheme. |
| 447 | 421 | |
| 448 | 422 | You will likely want to remove the `PATH` override in the “RUN” stage |
| @@ -463,11 +437,10 @@ | ||
| 463 | 437 | most popular programming languages in the world, we have many options |
| 464 | 438 | for achieving this. For instance, there is a whole class of |
| 465 | 439 | “[distroless]” images that will do this efficiently by changing |
| 466 | 440 | “`STAGE 2`” in the `Dockefile` to this: |
| 467 | 441 | |
| 468 | -``` | |
| 469 | 442 | ## --------------------------------------------------------------------- |
| 470 | 443 | ## STAGE 2: Pare that back to the bare essentials, plus Python. |
| 471 | 444 | ## --------------------------------------------------------------------- |
| 472 | 445 | FROM cgr.dev/chainguard/python:latest |
| 473 | 446 | USER root |
| @@ -478,24 +451,21 @@ | ||
| 478 | 451 | RUN [ "/bin/busybox", "--install", "/bin" ] |
| 479 | 452 | RUN set -x \ |
| 480 | 453 | && echo "fossil:x:${UID}:${UID}:User:/museum:/false" >> /etc/passwd \ |
| 481 | 454 | && echo "fossil:x:${UID}:fossil" >> /etc/group \ |
| 482 | 455 | && install -d -m 700 -o fossil -g fossil log museum |
| 483 | -``` | |
| 484 | 456 | |
| 485 | 457 | You will also have to add `busybox-static` to the APK package list in |
| 486 | 458 | STAGE 1 for the `RUN` script at the end of that stage to work, since the |
| 487 | 459 | [Chainguard Python image][cgimgs] lacks a shell, on purpose. The need to |
| 488 | 460 | install root-level binaries is why we change `USER` temporarily here. |
| 489 | 461 | |
| 490 | 462 | Build it and test that it works like so: |
| 491 | 463 | |
| 492 | -``` | |
| 493 | 464 | $ make container-run && |
| 494 | 465 | docker exec -i $(make container-version) python --version |
| 495 | 466 | 3.11.2 |
| 496 | -``` | |
| 497 | 467 | |
| 498 | 468 | The compensation for the hassle of using Chainguard over something more |
| 499 | 469 | general purpose like changing the `run` layer to Alpine and then adding |
| 500 | 470 | a “`apk add python`” command to the `Dockerfile` |
| 501 | 471 | is huge: we no longer leave a package manager sitting around inside the |
| @@ -555,11 +525,10 @@ | ||
| 555 | 525 | into this, [enable linger |
| 556 | 526 | mode](https://www.freedesktop.org/software/systemd/man/loginctl.html).) |
| 557 | 527 | so I was able to create a unit file called |
| 558 | 528 | `~/.local/share/systemd/user/[email protected]` with these contents: |
| 559 | 529 | |
| 560 | -``` | |
| 561 | 530 | [Unit] |
| 562 | 531 | Description=Fossil email alert sender for %I |
| 563 | 532 | |
| 564 | 533 | [Service] |
| 565 | 534 | WorkingDirectory=/home/fossil/museum |
| @@ -567,20 +536,17 @@ | ||
| 567 | 536 | Restart=always |
| 568 | 537 | RestartSec=3 |
| 569 | 538 | |
| 570 | 539 | [Install] |
| 571 | 540 | WantedBy=default.target |
| 572 | -``` | |
| 573 | 541 | |
| 574 | 542 | I was then able to enable email alert forwarding for select repositories |
| 575 | 543 | after configuring them per [the docs](./alerts.md) by saying: |
| 576 | 544 | |
| 577 | -``` | |
| 578 | 545 | $ systemctl --user daemon-reload |
| 579 | 546 | $ systemctl --user enable alert-sender@myproject |
| 580 | 547 | $ systemctl --user start alert-sender@myproject |
| 581 | -``` | |
| 582 | 548 | |
| 583 | 549 | Because this is a parameterized script and we’ve set our repository |
| 584 | 550 | paths predictably, you can do this for as many repositories as you need |
| 585 | 551 | to by passing their names after the “`@`” sign in the commands above. |
| 586 | 552 | |
| @@ -606,13 +572,11 @@ | ||
| 606 | 572 | For the sake of simple examples in this section, we’ll assume you’re |
| 607 | 573 | integrating Fossil into a larger web site, such as with our [Debian + |
| 608 | 574 | nginx + TLS][DNT] plan. This is why all of the examples below create |
| 609 | 575 | the container with this option: |
| 610 | 576 | |
| 611 | -``` | |
| 612 | - --publish 127.0.0.1:9999:8080 | |
| 613 | -``` | |
| 577 | + --publish 127.0.0.1:9999:8080 | |
| 614 | 578 | |
| 615 | 579 | The assumption is that there’s a reverse proxy running somewhere that |
| 616 | 580 | redirects public web hits to localhost port 9999, which in turn goes to |
| 617 | 581 | port 8080 inside the container. This use of port |
| 618 | 582 | publishing effectively replaces the use of the |
| @@ -678,14 +642,12 @@ | ||
| 678 | 642 | tenth the size of Docker Engine. |
| 679 | 643 | |
| 680 | 644 | For our purposes here, the only thing that changes relative to the |
| 681 | 645 | examples at the top of this document are the initial command: |
| 682 | 646 | |
| 683 | -``` | |
| 684 | - $ podman build -t fossil . | |
| 685 | - $ podman run --name fossil -p 9999:8080/tcp fossil | |
| 686 | -``` | |
| 647 | + $ podman build -t fossil . | |
| 648 | + $ podman run --name fossil -p 9999:8080/tcp fossil | |
| 687 | 649 | |
| 688 | 650 | Your Linux package repo may have a `podman-docker` package which |
| 689 | 651 | provides a “`docker`” script that calls “`podman`” for you, eliminating |
| 690 | 652 | even the command name difference. With that installed, the `make` |
| 691 | 653 | commands above will work with Podman as-is. |
| @@ -692,23 +654,21 @@ | ||
| 692 | 654 | |
| 693 | 655 | The only difference that matters here is that Podman doesn’t have the |
| 694 | 656 | same [default Linux kernel capability set](#caps) as Docker, which |
| 695 | 657 | affects the `--cap-drop` flags recommended above to: |
| 696 | 658 | |
| 697 | -``` | |
| 698 | - $ podman create \ | |
| 699 | - --name fossil \ | |
| 700 | - --cap-drop CHOWN \ | |
| 701 | - --cap-drop FSETID \ | |
| 702 | - --cap-drop KILL \ | |
| 703 | - --cap-drop NET_BIND_SERVICE \ | |
| 704 | - --cap-drop SETFCAP \ | |
| 705 | - --cap-drop SETPCAP \ | |
| 706 | - --publish 127.0.0.1:9999:8080 \ | |
| 707 | - localhost/fossil | |
| 708 | - $ podman start fossil | |
| 709 | -``` | |
| 659 | + $ podman create \ | |
| 660 | + --name fossil \ | |
| 661 | + --cap-drop CHOWN \ | |
| 662 | + --cap-drop FSETID \ | |
| 663 | + --cap-drop KILL \ | |
| 664 | + --cap-drop NET_BIND_SERVICE \ | |
| 665 | + --cap-drop SETFCAP \ | |
| 666 | + --cap-drop SETPCAP \ | |
| 667 | + --publish 127.0.0.1:9999:8080 \ | |
| 668 | + localhost/fossil | |
| 669 | + $ podman start fossil | |
| 710 | 670 | |
| 711 | 671 | [pmmac]: https://podman.io/getting-started/installation.html#macos |
| 712 | 672 | [pmwin]: https://github.com/containers/podman/blob/main/docs/tutorials/podman-for-windows.md |
| 713 | 673 | [Podman]: https://podman.io/ |
| 714 | 674 | [rl]: https://github.com/containers/podman/blob/main/docs/tutorials/rootless_tutorial.md |
| @@ -720,13 +680,11 @@ | ||
| 720 | 680 | If even the Podman stack is too big for you, the next-best option I’m |
| 721 | 681 | aware of is the `systemd-container` infrastructure on modern Linuxes, |
| 722 | 682 | available since version 239 or so. Its runtime tooling requires only |
| 723 | 683 | about 1.4 MiB of disk space: |
| 724 | 684 | |
| 725 | -``` | |
| 726 | - $ sudo apt install systemd-container btrfs-tools | |
| 727 | -``` | |
| 685 | + $ sudo apt install systemd-container btrfs-tools | |
| 728 | 686 | |
| 729 | 687 | That command assumes the primary test environment for |
| 730 | 688 | this guide, Ubuntu 22.04 LTS with `systemd` 249. For best |
| 731 | 689 | results, `/var/lib/machines` should be a btrfs volume, because |
| 732 | 690 | [`$REASONS`][mcfad]. For CentOS Stream 9 and other Red Hattish |
| @@ -742,60 +700,54 @@ | ||
| 742 | 700 | If you use [the stock `Dockerfile`][DF] to generate your |
| 743 | 701 | base image, `nspawn` won’t recognize it as containing an OS unless you |
| 744 | 702 | change the “`FROM scratch AS os`” line at the top of the second stage |
| 745 | 703 | to something like this: |
| 746 | 704 | |
| 747 | -``` | |
| 748 | - FROM gcr.io/distroless/static-debian11 AS os | |
| 749 | -``` | |
| 705 | + FROM gcr.io/distroless/static-debian11 AS os | |
| 750 | 706 | |
| 751 | 707 | Using that as a base image provides all the files `nspawn` checks for to |
| 752 | 708 | determine whether the container is sufficiently close to a Linux VM for |
| 753 | 709 | the following step to proceed: |
| 754 | 710 | |
| 755 | -``` | |
| 756 | - $ make container | |
| 757 | - $ docker container export $(make container-version) | | |
| 758 | - machinectl import-tar - myproject | |
| 759 | -``` | |
| 711 | + $ make container | |
| 712 | + $ docker container export $(make container-version) | | |
| 713 | + machinectl import-tar - myproject | |
| 760 | 714 | |
| 761 | 715 | Next, create `/etc/systemd/nspawn/myproject.nspawn`: |
| 762 | 716 | |
| 763 | 717 | ---- |
| 764 | 718 | |
| 765 | -``` | |
| 766 | -[Exec] | |
| 767 | -WorkingDirectory=/ | |
| 768 | -Parameters=bin/fossil server \ | |
| 769 | - --baseurl https://example.com/myproject \ | |
| 770 | - --create \ | |
| 771 | - --jsmode bundled \ | |
| 772 | - --localhost \ | |
| 773 | - --port 9000 \ | |
| 774 | - --scgi \ | |
| 775 | - --user admin \ | |
| 776 | - museum/repo.fossil | |
| 777 | -DropCapability= \ | |
| 778 | - CAP_AUDIT_WRITE \ | |
| 779 | - CAP_CHOWN \ | |
| 780 | - CAP_FSETID \ | |
| 781 | - CAP_KILL \ | |
| 782 | - CAP_MKNOD \ | |
| 783 | - CAP_NET_BIND_SERVICE \ | |
| 784 | - CAP_NET_RAW \ | |
| 785 | - CAP_SETFCAP \ | |
| 786 | - CAP_SETPCAP | |
| 787 | -ProcessTwo=yes | |
| 788 | -LinkJournal=no | |
| 789 | -Timezone=no | |
| 790 | - | |
| 791 | -[Files] | |
| 792 | -Bind=/home/fossil/museum/myproject:/museum | |
| 793 | - | |
| 794 | -[Network] | |
| 795 | -VirtualEthernet=no | |
| 796 | -``` | |
| 719 | + [Exec] | |
| 720 | + WorkingDirectory=/ | |
| 721 | + Parameters=bin/fossil server \ | |
| 722 | + --baseurl https://example.com/myproject \ | |
| 723 | + --create \ | |
| 724 | + --jsmode bundled \ | |
| 725 | + --localhost \ | |
| 726 | + --port 9000 \ | |
| 727 | + --scgi \ | |
| 728 | + --user admin \ | |
| 729 | + museum/repo.fossil | |
| 730 | + DropCapability= \ | |
| 731 | + CAP_AUDIT_WRITE \ | |
| 732 | + CAP_CHOWN \ | |
| 733 | + CAP_FSETID \ | |
| 734 | + CAP_KILL \ | |
| 735 | + CAP_MKNOD \ | |
| 736 | + CAP_NET_BIND_SERVICE \ | |
| 737 | + CAP_NET_RAW \ | |
| 738 | + CAP_SETFCAP \ | |
| 739 | + CAP_SETPCAP | |
| 740 | + ProcessTwo=yes | |
| 741 | + LinkJournal=no | |
| 742 | + Timezone=no | |
| 743 | + | |
| 744 | + [Files] | |
| 745 | + Bind=/home/fossil/museum/myproject:/museum | |
| 746 | + | |
| 747 | + [Network] | |
| 748 | + VirtualEthernet=no | |
| 797 | 749 | |
| 798 | 750 | ---- |
| 799 | 751 | |
| 800 | 752 | If you recognize most of that from the `Dockerfile` discussion above, |
| 801 | 753 | congratulations, you’ve been paying attention. The rest should also |
| @@ -819,22 +771,20 @@ | ||
| 819 | 771 | That being done, we also need a generic `systemd` unit file called |
| 820 | 772 | `/etc/systemd/system/[email protected]`, containing: |
| 821 | 773 | |
| 822 | 774 | ---- |
| 823 | 775 | |
| 824 | -``` | |
| 825 | -[Unit] | |
| 826 | -Description=Fossil %i Repo Service | |
| 827 | -[email protected] [email protected] | |
| 828 | -After=network.target systemd-resolved.service [email protected] [email protected] | |
| 829 | - | |
| 830 | -[Service] | |
| 831 | -ExecStart=systemd-nspawn --settings=override --read-only --machine=%i bin/fossil | |
| 832 | - | |
| 833 | -[Install] | |
| 834 | -WantedBy=multi-user.target | |
| 835 | -``` | |
| 776 | + [Unit] | |
| 777 | + Description=Fossil %i Repo Service | |
| 778 | + [email protected] [email protected] | |
| 779 | + After=network.target systemd-resolved.service [email protected] [email protected] | |
| 780 | + | |
| 781 | + [Service] | |
| 782 | + ExecStart=systemd-nspawn --settings=override --read-only --machine=%i bin/fossil | |
| 783 | + | |
| 784 | + [Install] | |
| 785 | + WantedBy=multi-user.target | |
| 836 | 786 | |
| 837 | 787 | ---- |
| 838 | 788 | |
| 839 | 789 | You shouldn’t have to change any of this because we’ve given the |
| 840 | 790 | `--setting=override` flag, meaning any setting in the nspawn file |
| @@ -843,42 +793,36 @@ | ||
| 843 | 793 | share the base configuration, varying on a per-repo level through |
| 844 | 794 | adjustments to their individual `*.nspawn` files. |
| 845 | 795 | |
| 846 | 796 | You may then start the service in the normal way: |
| 847 | 797 | |
| 848 | -``` | |
| 849 | - $ sudo systemctl enable fossil@myproject | |
| 850 | - $ sudo systemctl start fossil@myproject | |
| 851 | -``` | |
| 798 | + $ sudo systemctl enable fossil@myproject | |
| 799 | + $ sudo systemctl start fossil@myproject | |
| 852 | 800 | |
| 853 | 801 | You should then find it running on localhost port 9000 per the nspawn |
| 854 | 802 | configuration file above, suitable for proxying Fossil out to the |
| 855 | 803 | public using nginx via SCGI. If you aren’t using a front-end proxy |
| 856 | 804 | and want Fossil exposed to the world via HTTPS, you might say this instead in |
| 857 | 805 | the `*.nspawn` file: |
| 858 | 806 | |
| 859 | -``` | |
| 860 | -Parameters=bin/fossil server \ | |
| 861 | - --cert /path/to/cert.pem \ | |
| 862 | - --create \ | |
| 863 | - --jsmode bundled \ | |
| 864 | - --port 443 \ | |
| 865 | - --user admin \ | |
| 866 | - museum/repo.fossil | |
| 867 | -``` | |
| 807 | + Parameters=bin/fossil server \ | |
| 808 | + --cert /path/to/cert.pem \ | |
| 809 | + --create \ | |
| 810 | + --jsmode bundled \ | |
| 811 | + --port 443 \ | |
| 812 | + --user admin \ | |
| 813 | + museum/repo.fossil | |
| 868 | 814 | |
| 869 | 815 | You would also need to un-drop the `CAP_NET_BIND_SERVICE` capability |
| 870 | 816 | to allow Fossil to bind to this low-numbered port. |
| 871 | 817 | |
| 872 | 818 | We use the `systemd` template file feature to allow multiple Fossil |
| 873 | 819 | servers running on a single machine, each on a different TCP port, |
| 874 | 820 | as when proxying them out as subdirectories of a larger site. |
| 875 | 821 | To add another project, you must first clone the base “machine” layer: |
| 876 | 822 | |
| 877 | -``` | |
| 878 | - $ sudo machinectl clone myproject otherthing | |
| 879 | -``` | |
| 823 | + $ sudo machinectl clone myproject otherthing | |
| 880 | 824 | |
| 881 | 825 | That will not only create a clone of `/var/lib/machines/myproject` |
| 882 | 826 | as `../otherthing`, it will create a matching `otherthing.nspawn` file for you |
| 883 | 827 | as a copy of the first one. Adjust its contents to suit, then enable |
| 884 | 828 | and start it as above. |
| @@ -895,21 +839,17 @@ | ||
| 895 | 839 | |
| 896 | 840 | Fortunately, there are workarounds. |
| 897 | 841 | |
| 898 | 842 | First, the `apt install` command above becomes: |
| 899 | 843 | |
| 900 | -``` | |
| 901 | - $ sudo dnf install systemd-container | |
| 902 | -``` | |
| 844 | + $ sudo dnf install systemd-container | |
| 903 | 845 | |
| 904 | 846 | Second, you have to hack around the lack of `machinectl import-tar`: |
| 905 | 847 | |
| 906 | -``` | |
| 907 | - $ rootfs=/var/lib/machines/fossil | |
| 908 | - $ sudo mkdir -p $rootfs | |
| 909 | - $ docker container export fossil | sudo tar -xf -C $rootfs - | |
| 910 | -``` | |
| 848 | + $ rootfs=/var/lib/machines/fossil | |
| 849 | + $ sudo mkdir -p $rootfs | |
| 850 | + $ docker container export fossil | sudo tar -xf -C $rootfs - | |
| 911 | 851 | |
| 912 | 852 | The parent directory path in the `rootfs` variable is important, |
| 913 | 853 | because although we aren’t able to use `machinectl` on such systems, the |
| 914 | 854 | `systemd-nspawn` developers assume you’re using them together; when you give |
| 915 | 855 | `--machine`, it assumes the `machinectl` directory scheme. You could |
| 916 | 856 |
| --- www/containers.md | |
| +++ www/containers.md | |
| @@ -13,20 +13,16 @@ | |
| 13 | ## 1. Quick Start |
| 14 | |
| 15 | Fossil ships a `Dockerfile` at the top of its source tree, |
| 16 | [here][DF], which you can build like so: |
| 17 | |
| 18 | ``` |
| 19 | $ docker build -t fossil . |
| 20 | ``` |
| 21 | |
| 22 | If the image built successfully, you can create a container from it and |
| 23 | test that it runs: |
| 24 | |
| 25 | ``` |
| 26 | $ docker run --name fossil -p 9999:8080/tcp fossil |
| 27 | ``` |
| 28 | |
| 29 | This shows us remapping the internal TCP listening port as 9999 on the |
| 30 | host. This feature of OCI runtimes means there’s little point to using |
| 31 | the “`fossil server --port`” feature inside the container. We can let |
| 32 | Fossil default to 8080 internally, then remap it to wherever we want it |
| @@ -44,13 +40,11 @@ | |
| 44 | with the `DCFLAGS` variable. (DB is short for “`docker build`”, and DC |
| 45 | is short for “`docker create`”, a sub-step of the “run” target.) |
| 46 | To get the custom port setting as in |
| 47 | second command above, say: |
| 48 | |
| 49 | ``` |
| 50 | $ make container-run DCFLAGS='-p 9999:8080/tcp' |
| 51 | ``` |
| 52 | |
| 53 | Contrast the raw “`docker`” commands above, which create an |
| 54 | _unversioned_ image called `fossil:latest` and from that a container |
| 55 | simply called `fossil`. The unversioned names are more convenient for |
| 56 | interactive use, while the versioned ones are good for CI/CD type |
| @@ -81,15 +75,13 @@ | |
| 81 | ### <a id="repo-inside"></a> 2.1 Storing the Repo Inside the Container |
| 82 | |
| 83 | The simplest method is to stop the container if it was running, then |
| 84 | say: |
| 85 | |
| 86 | ``` |
| 87 | $ docker cp /path/to/my-project.fossil fossil:/museum/repo.fossil |
| 88 | $ docker start fossil |
| 89 | $ docker exec fossil chown -R 499 /museum |
| 90 | ``` |
| 91 | |
| 92 | That copies the local Fossil repo into the container where the server |
| 93 | expects to find it, so that the “start” command causes it to serve from |
| 94 | that copied-in file instead. Since it lives atop the immutable base |
| 95 | layers, it persists as part of the container proper, surviving restarts. |
| @@ -120,17 +112,15 @@ | |
| 120 | designed to be killed off at the slightest cause, rebuilt, and |
| 121 | redeployed. If you do that with the repo inside the container, it gets |
| 122 | destroyed, too. The solution is to replace the “run” command above with |
| 123 | the following: |
| 124 | |
| 125 | ``` |
| 126 | $ docker run \ |
| 127 | --publish 9999:8080 \ |
| 128 | --name fossil-bind-mount \ |
| 129 | --volume ~/museum:/museum \ |
| 130 | fossil |
| 131 | ``` |
| 132 | |
| 133 | Because this bind mount maps a host-side directory (`~/museum`) into the |
| 134 | container, you don’t need to `docker cp` the repo into the container at |
| 135 | all. It still expects to find the repository as `repo.fossil` under that |
| 136 | directory, but now both the host and the container can see that repo DB. |
| @@ -151,13 +141,11 @@ | |
| 151 | You might be aware that OCI containers allow mapping a single file into |
| 152 | the repository rather than a whole directory. Since Fossil repositories |
| 153 | are specially-formatted SQLite databases, you might be wondering why we |
| 154 | don’t say things like: |
| 155 | |
| 156 | ``` |
| 157 | --volume ~/museum/my-project.fossil:/museum/repo.fossil |
| 158 | ``` |
| 159 | |
| 160 | That lets us have a convenient file name for the project outside the |
| 161 | container while letting the configuration inside the container refer to |
| 162 | the generic “`/museum/repo.fossil`” name. Why should we have to name |
| 163 | the repo generically on the outside merely to placate the container? |
| @@ -292,21 +280,19 @@ | |
| 292 | |
| 293 | All together, we recommend adding the following options to your |
| 294 | “`docker run`” commands, as well as to any “`docker create`” command |
| 295 | that will be followed by “`docker start`”: |
| 296 | |
| 297 | ``` |
| 298 | --cap-drop AUDIT_WRITE \ |
| 299 | --cap-drop CHOWN \ |
| 300 | --cap-drop FSETID \ |
| 301 | --cap-drop KILL \ |
| 302 | --cap-drop MKNOD \ |
| 303 | --cap-drop NET_BIND_SERVICE \ |
| 304 | --cap-drop NET_RAW \ |
| 305 | --cap-drop SETFCAP \ |
| 306 | --cap-drop SETPCAP |
| 307 | ``` |
| 308 | |
| 309 | In the next section, we’ll show a case where you create a container |
| 310 | without ever running it, making these options pointless. |
| 311 | |
| 312 | [backoffice]: ./backoffice.md |
| @@ -326,16 +312,14 @@ | |
| 326 | modern Linux distros make this [surprisingly difficult][lsl], but Alpine’s |
| 327 | back-to-basics nature makes static builds work the way they used to, |
| 328 | back in the day. If that’s all you’re after, you can do so as easily as |
| 329 | this: |
| 330 | |
| 331 | ``` |
| 332 | $ docker build -t fossil . |
| 333 | $ docker create --name fossil-static-tmp fossil |
| 334 | $ docker cp fossil-static-tmp:/bin/fossil . |
| 335 | $ docker container rm fossil-static-tmp |
| 336 | ``` |
| 337 | |
| 338 | The result is six or seven megs, depending on the CPU architecture you |
| 339 | build for. It’s built stripped. |
| 340 | |
| 341 | [lsl]: https://stackoverflow.com/questions/3430400/linux-static-linking-is-dead |
| @@ -347,19 +331,15 @@ | |
| 347 | |
| 348 | The default version of Fossil fetched in the build is the version in the |
| 349 | checkout directory at the time you run it. You could override it to get |
| 350 | a release build like so: |
| 351 | |
| 352 | ``` |
| 353 | $ docker build -t fossil --build-arg FSLVER=version-2.20 . |
| 354 | ``` |
| 355 | |
| 356 | Or equivalently, using Fossil’s `Makefile` convenience target: |
| 357 | |
| 358 | ``` |
| 359 | $ make container-image DBFLAGS='--build-arg FSLVER=version-2.20' |
| 360 | ``` |
| 361 | |
| 362 | While you could instead use the generic |
| 363 | “`release`” tag here, it’s better to use a specific version number |
| 364 | since container builders cache downloaded files, hoping to |
| 365 | reuse them across builds. If you ask for “`release`” before a new |
| @@ -384,13 +364,11 @@ | |
| 384 | 500 and went *down* one instead to reduce the chance of a conflict to as |
| 385 | close to zero as we can manage. |
| 386 | |
| 387 | To change it to something else, say: |
| 388 | |
| 389 | ``` |
| 390 | $ make container-image DBFLAGS='--build-arg UID=501' |
| 391 | ``` |
| 392 | |
| 393 | This is particularly useful if you’re putting your repository on a |
| 394 | separate volume since the IDs “leak” out into the host environment via |
| 395 | file permissions. You may therefore wish them to mean something on both |
| 396 | sides of the container barrier rather than have “499” appear on the host |
| @@ -403,25 +381,21 @@ | |
| 403 | for use of any OCI container system that implements the same interfaces. |
| 404 | We go into more details about this [below](#light), but |
| 405 | for now, it suffices to point out that you can switch to Podman while |
| 406 | using our `Makefile` convenience targets unchanged by saying: |
| 407 | |
| 408 | ``` |
| 409 | $ make CENGINE=podman container-run |
| 410 | ``` |
| 411 | |
| 412 | |
| 413 | ### 5.4 <a id="config"></a>Fossil Configuration Options |
| 414 | |
| 415 | You can use this same mechanism to enable non-default Fossil |
| 416 | configuration options in your build. For instance, to turn on |
| 417 | the JSON API and the TH1 docs extension: |
| 418 | |
| 419 | ``` |
| 420 | $ make container-image \ |
| 421 | DBFLAGS='--build-arg FSLCFG="--json --with-th1-docs"' |
| 422 | ``` |
| 423 | |
| 424 | If you also wanted [the Tcl evaluation extension](./th1.md#tclEval), |
| 425 | that brings us to [the next point](#run). |
| 426 | |
| 427 | |
| @@ -429,20 +403,20 @@ | |
| 429 | |
| 430 | If you want a basic shell environment for temporary debugging of the |
| 431 | running container, that’s easily added. Simply change this line in the |
| 432 | `Dockerfile`… |
| 433 | |
| 434 | FROM scratch AS run |
| 435 | |
| 436 | …to this: |
| 437 | |
| 438 | FROM busybox AS run |
| 439 | |
| 440 | Rebuild and redeploy to give your Fossil container a [BusyBox]-based |
| 441 | shell environment that you can get into via: |
| 442 | |
| 443 | $ docker exec -it -u fossil $(make container-version) sh |
| 444 | |
| 445 | That command assumes you built it via “`make container`” and are |
| 446 | therefore using its versioning scheme. |
| 447 | |
| 448 | You will likely want to remove the `PATH` override in the “RUN” stage |
| @@ -463,11 +437,10 @@ | |
| 463 | most popular programming languages in the world, we have many options |
| 464 | for achieving this. For instance, there is a whole class of |
| 465 | “[distroless]” images that will do this efficiently by changing |
| 466 | “`STAGE 2`” in the `Dockefile` to this: |
| 467 | |
| 468 | ``` |
| 469 | ## --------------------------------------------------------------------- |
| 470 | ## STAGE 2: Pare that back to the bare essentials, plus Python. |
| 471 | ## --------------------------------------------------------------------- |
| 472 | FROM cgr.dev/chainguard/python:latest |
| 473 | USER root |
| @@ -478,24 +451,21 @@ | |
| 478 | RUN [ "/bin/busybox", "--install", "/bin" ] |
| 479 | RUN set -x \ |
| 480 | && echo "fossil:x:${UID}:${UID}:User:/museum:/false" >> /etc/passwd \ |
| 481 | && echo "fossil:x:${UID}:fossil" >> /etc/group \ |
| 482 | && install -d -m 700 -o fossil -g fossil log museum |
| 483 | ``` |
| 484 | |
| 485 | You will also have to add `busybox-static` to the APK package list in |
| 486 | STAGE 1 for the `RUN` script at the end of that stage to work, since the |
| 487 | [Chainguard Python image][cgimgs] lacks a shell, on purpose. The need to |
| 488 | install root-level binaries is why we change `USER` temporarily here. |
| 489 | |
| 490 | Build it and test that it works like so: |
| 491 | |
| 492 | ``` |
| 493 | $ make container-run && |
| 494 | docker exec -i $(make container-version) python --version |
| 495 | 3.11.2 |
| 496 | ``` |
| 497 | |
| 498 | The compensation for the hassle of using Chainguard over something more |
| 499 | general purpose like changing the `run` layer to Alpine and then adding |
| 500 | a “`apk add python`” command to the `Dockerfile` |
| 501 | is huge: we no longer leave a package manager sitting around inside the |
| @@ -555,11 +525,10 @@ | |
| 555 | into this, [enable linger |
| 556 | mode](https://www.freedesktop.org/software/systemd/man/loginctl.html).) |
| 557 | so I was able to create a unit file called |
| 558 | `~/.local/share/systemd/user/[email protected]` with these contents: |
| 559 | |
| 560 | ``` |
| 561 | [Unit] |
| 562 | Description=Fossil email alert sender for %I |
| 563 | |
| 564 | [Service] |
| 565 | WorkingDirectory=/home/fossil/museum |
| @@ -567,20 +536,17 @@ | |
| 567 | Restart=always |
| 568 | RestartSec=3 |
| 569 | |
| 570 | [Install] |
| 571 | WantedBy=default.target |
| 572 | ``` |
| 573 | |
| 574 | I was then able to enable email alert forwarding for select repositories |
| 575 | after configuring them per [the docs](./alerts.md) by saying: |
| 576 | |
| 577 | ``` |
| 578 | $ systemctl --user daemon-reload |
| 579 | $ systemctl --user enable alert-sender@myproject |
| 580 | $ systemctl --user start alert-sender@myproject |
| 581 | ``` |
| 582 | |
| 583 | Because this is a parameterized script and we’ve set our repository |
| 584 | paths predictably, you can do this for as many repositories as you need |
| 585 | to by passing their names after the “`@`” sign in the commands above. |
| 586 | |
| @@ -606,13 +572,11 @@ | |
| 606 | For the sake of simple examples in this section, we’ll assume you’re |
| 607 | integrating Fossil into a larger web site, such as with our [Debian + |
| 608 | nginx + TLS][DNT] plan. This is why all of the examples below create |
| 609 | the container with this option: |
| 610 | |
| 611 | ``` |
| 612 | --publish 127.0.0.1:9999:8080 |
| 613 | ``` |
| 614 | |
| 615 | The assumption is that there’s a reverse proxy running somewhere that |
| 616 | redirects public web hits to localhost port 9999, which in turn goes to |
| 617 | port 8080 inside the container. This use of port |
| 618 | publishing effectively replaces the use of the |
| @@ -678,14 +642,12 @@ | |
| 678 | tenth the size of Docker Engine. |
| 679 | |
| 680 | For our purposes here, the only thing that changes relative to the |
| 681 | examples at the top of this document are the initial command: |
| 682 | |
| 683 | ``` |
| 684 | $ podman build -t fossil . |
| 685 | $ podman run --name fossil -p 9999:8080/tcp fossil |
| 686 | ``` |
| 687 | |
| 688 | Your Linux package repo may have a `podman-docker` package which |
| 689 | provides a “`docker`” script that calls “`podman`” for you, eliminating |
| 690 | even the command name difference. With that installed, the `make` |
| 691 | commands above will work with Podman as-is. |
| @@ -692,23 +654,21 @@ | |
| 692 | |
| 693 | The only difference that matters here is that Podman doesn’t have the |
| 694 | same [default Linux kernel capability set](#caps) as Docker, which |
| 695 | affects the `--cap-drop` flags recommended above to: |
| 696 | |
| 697 | ``` |
| 698 | $ podman create \ |
| 699 | --name fossil \ |
| 700 | --cap-drop CHOWN \ |
| 701 | --cap-drop FSETID \ |
| 702 | --cap-drop KILL \ |
| 703 | --cap-drop NET_BIND_SERVICE \ |
| 704 | --cap-drop SETFCAP \ |
| 705 | --cap-drop SETPCAP \ |
| 706 | --publish 127.0.0.1:9999:8080 \ |
| 707 | localhost/fossil |
| 708 | $ podman start fossil |
| 709 | ``` |
| 710 | |
| 711 | [pmmac]: https://podman.io/getting-started/installation.html#macos |
| 712 | [pmwin]: https://github.com/containers/podman/blob/main/docs/tutorials/podman-for-windows.md |
| 713 | [Podman]: https://podman.io/ |
| 714 | [rl]: https://github.com/containers/podman/blob/main/docs/tutorials/rootless_tutorial.md |
| @@ -720,13 +680,11 @@ | |
| 720 | If even the Podman stack is too big for you, the next-best option I’m |
| 721 | aware of is the `systemd-container` infrastructure on modern Linuxes, |
| 722 | available since version 239 or so. Its runtime tooling requires only |
| 723 | about 1.4 MiB of disk space: |
| 724 | |
| 725 | ``` |
| 726 | $ sudo apt install systemd-container btrfs-tools |
| 727 | ``` |
| 728 | |
| 729 | That command assumes the primary test environment for |
| 730 | this guide, Ubuntu 22.04 LTS with `systemd` 249. For best |
| 731 | results, `/var/lib/machines` should be a btrfs volume, because |
| 732 | [`$REASONS`][mcfad]. For CentOS Stream 9 and other Red Hattish |
| @@ -742,60 +700,54 @@ | |
| 742 | If you use [the stock `Dockerfile`][DF] to generate your |
| 743 | base image, `nspawn` won’t recognize it as containing an OS unless you |
| 744 | change the “`FROM scratch AS os`” line at the top of the second stage |
| 745 | to something like this: |
| 746 | |
| 747 | ``` |
| 748 | FROM gcr.io/distroless/static-debian11 AS os |
| 749 | ``` |
| 750 | |
| 751 | Using that as a base image provides all the files `nspawn` checks for to |
| 752 | determine whether the container is sufficiently close to a Linux VM for |
| 753 | the following step to proceed: |
| 754 | |
| 755 | ``` |
| 756 | $ make container |
| 757 | $ docker container export $(make container-version) | |
| 758 | machinectl import-tar - myproject |
| 759 | ``` |
| 760 | |
| 761 | Next, create `/etc/systemd/nspawn/myproject.nspawn`: |
| 762 | |
| 763 | ---- |
| 764 | |
| 765 | ``` |
| 766 | [Exec] |
| 767 | WorkingDirectory=/ |
| 768 | Parameters=bin/fossil server \ |
| 769 | --baseurl https://example.com/myproject \ |
| 770 | --create \ |
| 771 | --jsmode bundled \ |
| 772 | --localhost \ |
| 773 | --port 9000 \ |
| 774 | --scgi \ |
| 775 | --user admin \ |
| 776 | museum/repo.fossil |
| 777 | DropCapability= \ |
| 778 | CAP_AUDIT_WRITE \ |
| 779 | CAP_CHOWN \ |
| 780 | CAP_FSETID \ |
| 781 | CAP_KILL \ |
| 782 | CAP_MKNOD \ |
| 783 | CAP_NET_BIND_SERVICE \ |
| 784 | CAP_NET_RAW \ |
| 785 | CAP_SETFCAP \ |
| 786 | CAP_SETPCAP |
| 787 | ProcessTwo=yes |
| 788 | LinkJournal=no |
| 789 | Timezone=no |
| 790 | |
| 791 | [Files] |
| 792 | Bind=/home/fossil/museum/myproject:/museum |
| 793 | |
| 794 | [Network] |
| 795 | VirtualEthernet=no |
| 796 | ``` |
| 797 | |
| 798 | ---- |
| 799 | |
| 800 | If you recognize most of that from the `Dockerfile` discussion above, |
| 801 | congratulations, you’ve been paying attention. The rest should also |
| @@ -819,22 +771,20 @@ | |
| 819 | That being done, we also need a generic `systemd` unit file called |
| 820 | `/etc/systemd/system/[email protected]`, containing: |
| 821 | |
| 822 | ---- |
| 823 | |
| 824 | ``` |
| 825 | [Unit] |
| 826 | Description=Fossil %i Repo Service |
| 827 | [email protected] [email protected] |
| 828 | After=network.target systemd-resolved.service [email protected] [email protected] |
| 829 | |
| 830 | [Service] |
| 831 | ExecStart=systemd-nspawn --settings=override --read-only --machine=%i bin/fossil |
| 832 | |
| 833 | [Install] |
| 834 | WantedBy=multi-user.target |
| 835 | ``` |
| 836 | |
| 837 | ---- |
| 838 | |
| 839 | You shouldn’t have to change any of this because we’ve given the |
| 840 | `--setting=override` flag, meaning any setting in the nspawn file |
| @@ -843,42 +793,36 @@ | |
| 843 | share the base configuration, varying on a per-repo level through |
| 844 | adjustments to their individual `*.nspawn` files. |
| 845 | |
| 846 | You may then start the service in the normal way: |
| 847 | |
| 848 | ``` |
| 849 | $ sudo systemctl enable fossil@myproject |
| 850 | $ sudo systemctl start fossil@myproject |
| 851 | ``` |
| 852 | |
| 853 | You should then find it running on localhost port 9000 per the nspawn |
| 854 | configuration file above, suitable for proxying Fossil out to the |
| 855 | public using nginx via SCGI. If you aren’t using a front-end proxy |
| 856 | and want Fossil exposed to the world via HTTPS, you might say this instead in |
| 857 | the `*.nspawn` file: |
| 858 | |
| 859 | ``` |
| 860 | Parameters=bin/fossil server \ |
| 861 | --cert /path/to/cert.pem \ |
| 862 | --create \ |
| 863 | --jsmode bundled \ |
| 864 | --port 443 \ |
| 865 | --user admin \ |
| 866 | museum/repo.fossil |
| 867 | ``` |
| 868 | |
| 869 | You would also need to un-drop the `CAP_NET_BIND_SERVICE` capability |
| 870 | to allow Fossil to bind to this low-numbered port. |
| 871 | |
| 872 | We use the `systemd` template file feature to allow multiple Fossil |
| 873 | servers running on a single machine, each on a different TCP port, |
| 874 | as when proxying them out as subdirectories of a larger site. |
| 875 | To add another project, you must first clone the base “machine” layer: |
| 876 | |
| 877 | ``` |
| 878 | $ sudo machinectl clone myproject otherthing |
| 879 | ``` |
| 880 | |
| 881 | That will not only create a clone of `/var/lib/machines/myproject` |
| 882 | as `../otherthing`, it will create a matching `otherthing.nspawn` file for you |
| 883 | as a copy of the first one. Adjust its contents to suit, then enable |
| 884 | and start it as above. |
| @@ -895,21 +839,17 @@ | |
| 895 | |
| 896 | Fortunately, there are workarounds. |
| 897 | |
| 898 | First, the `apt install` command above becomes: |
| 899 | |
| 900 | ``` |
| 901 | $ sudo dnf install systemd-container |
| 902 | ``` |
| 903 | |
| 904 | Second, you have to hack around the lack of `machinectl import-tar`: |
| 905 | |
| 906 | ``` |
| 907 | $ rootfs=/var/lib/machines/fossil |
| 908 | $ sudo mkdir -p $rootfs |
| 909 | $ docker container export fossil | sudo tar -xf -C $rootfs - |
| 910 | ``` |
| 911 | |
| 912 | The parent directory path in the `rootfs` variable is important, |
| 913 | because although we aren’t able to use `machinectl` on such systems, the |
| 914 | `systemd-nspawn` developers assume you’re using them together; when you give |
| 915 | `--machine`, it assumes the `machinectl` directory scheme. You could |
| 916 |
| --- www/containers.md | |
| +++ www/containers.md | |
| @@ -13,20 +13,16 @@ | |
| 13 | ## 1. Quick Start |
| 14 | |
| 15 | Fossil ships a `Dockerfile` at the top of its source tree, |
| 16 | [here][DF], which you can build like so: |
| 17 | |
| 18 | $ docker build -t fossil . |
| 19 | |
| 20 | If the image built successfully, you can create a container from it and |
| 21 | test that it runs: |
| 22 | |
| 23 | $ docker run --name fossil -p 9999:8080/tcp fossil |
| 24 | |
| 25 | This shows us remapping the internal TCP listening port as 9999 on the |
| 26 | host. This feature of OCI runtimes means there’s little point to using |
| 27 | the “`fossil server --port`” feature inside the container. We can let |
| 28 | Fossil default to 8080 internally, then remap it to wherever we want it |
| @@ -44,13 +40,11 @@ | |
| 40 | with the `DCFLAGS` variable. (DB is short for “`docker build`”, and DC |
| 41 | is short for “`docker create`”, a sub-step of the “run” target.) |
| 42 | To get the custom port setting as in |
| 43 | second command above, say: |
| 44 | |
| 45 | $ make container-run DCFLAGS='-p 9999:8080/tcp' |
| 46 | |
| 47 | Contrast the raw “`docker`” commands above, which create an |
| 48 | _unversioned_ image called `fossil:latest` and from that a container |
| 49 | simply called `fossil`. The unversioned names are more convenient for |
| 50 | interactive use, while the versioned ones are good for CI/CD type |
| @@ -81,15 +75,13 @@ | |
| 75 | ### <a id="repo-inside"></a> 2.1 Storing the Repo Inside the Container |
| 76 | |
| 77 | The simplest method is to stop the container if it was running, then |
| 78 | say: |
| 79 | |
| 80 | $ docker cp /path/to/my-project.fossil fossil:/museum/repo.fossil |
| 81 | $ docker start fossil |
| 82 | $ docker exec fossil chown -R 499 /museum |
| 83 | |
| 84 | That copies the local Fossil repo into the container where the server |
| 85 | expects to find it, so that the “start” command causes it to serve from |
| 86 | that copied-in file instead. Since it lives atop the immutable base |
| 87 | layers, it persists as part of the container proper, surviving restarts. |
| @@ -120,17 +112,15 @@ | |
| 112 | designed to be killed off at the slightest cause, rebuilt, and |
| 113 | redeployed. If you do that with the repo inside the container, it gets |
| 114 | destroyed, too. The solution is to replace the “run” command above with |
| 115 | the following: |
| 116 | |
| 117 | $ docker run \ |
| 118 | --publish 9999:8080 \ |
| 119 | --name fossil-bind-mount \ |
| 120 | --volume ~/museum:/museum \ |
| 121 | fossil |
| 122 | |
| 123 | Because this bind mount maps a host-side directory (`~/museum`) into the |
| 124 | container, you don’t need to `docker cp` the repo into the container at |
| 125 | all. It still expects to find the repository as `repo.fossil` under that |
| 126 | directory, but now both the host and the container can see that repo DB. |
| @@ -151,13 +141,11 @@ | |
| 141 | You might be aware that OCI containers allow mapping a single file into |
| 142 | the repository rather than a whole directory. Since Fossil repositories |
| 143 | are specially-formatted SQLite databases, you might be wondering why we |
| 144 | don’t say things like: |
| 145 | |
| 146 | --volume ~/museum/my-project.fossil:/museum/repo.fossil |
| 147 | |
| 148 | That lets us have a convenient file name for the project outside the |
| 149 | container while letting the configuration inside the container refer to |
| 150 | the generic “`/museum/repo.fossil`” name. Why should we have to name |
| 151 | the repo generically on the outside merely to placate the container? |
| @@ -292,21 +280,19 @@ | |
| 280 | |
| 281 | All together, we recommend adding the following options to your |
| 282 | “`docker run`” commands, as well as to any “`docker create`” command |
| 283 | that will be followed by “`docker start`”: |
| 284 | |
| 285 | --cap-drop AUDIT_WRITE \ |
| 286 | --cap-drop CHOWN \ |
| 287 | --cap-drop FSETID \ |
| 288 | --cap-drop KILL \ |
| 289 | --cap-drop MKNOD \ |
| 290 | --cap-drop NET_BIND_SERVICE \ |
| 291 | --cap-drop NET_RAW \ |
| 292 | --cap-drop SETFCAP \ |
| 293 | --cap-drop SETPCAP |
| 294 | |
| 295 | In the next section, we’ll show a case where you create a container |
| 296 | without ever running it, making these options pointless. |
| 297 | |
| 298 | [backoffice]: ./backoffice.md |
| @@ -326,16 +312,14 @@ | |
| 312 | modern Linux distros make this [surprisingly difficult][lsl], but Alpine’s |
| 313 | back-to-basics nature makes static builds work the way they used to, |
| 314 | back in the day. If that’s all you’re after, you can do so as easily as |
| 315 | this: |
| 316 | |
| 317 | $ docker build -t fossil . |
| 318 | $ docker create --name fossil-static-tmp fossil |
| 319 | $ docker cp fossil-static-tmp:/bin/fossil . |
| 320 | $ docker container rm fossil-static-tmp |
| 321 | |
| 322 | The result is six or seven megs, depending on the CPU architecture you |
| 323 | build for. It’s built stripped. |
| 324 | |
| 325 | [lsl]: https://stackoverflow.com/questions/3430400/linux-static-linking-is-dead |
| @@ -347,19 +331,15 @@ | |
| 331 | |
| 332 | The default version of Fossil fetched in the build is the version in the |
| 333 | checkout directory at the time you run it. You could override it to get |
| 334 | a release build like so: |
| 335 | |
| 336 | $ docker build -t fossil --build-arg FSLVER=version-2.20 . |
| 337 | |
| 338 | Or equivalently, using Fossil’s `Makefile` convenience target: |
| 339 | |
| 340 | $ make container-image DBFLAGS='--build-arg FSLVER=version-2.20' |
| 341 | |
| 342 | While you could instead use the generic |
| 343 | “`release`” tag here, it’s better to use a specific version number |
| 344 | since container builders cache downloaded files, hoping to |
| 345 | reuse them across builds. If you ask for “`release`” before a new |
| @@ -384,13 +364,11 @@ | |
| 364 | 500 and went *down* one instead to reduce the chance of a conflict to as |
| 365 | close to zero as we can manage. |
| 366 | |
| 367 | To change it to something else, say: |
| 368 | |
| 369 | $ make container-image DBFLAGS='--build-arg UID=501' |
| 370 | |
| 371 | This is particularly useful if you’re putting your repository on a |
| 372 | separate volume since the IDs “leak” out into the host environment via |
| 373 | file permissions. You may therefore wish them to mean something on both |
| 374 | sides of the container barrier rather than have “499” appear on the host |
| @@ -403,25 +381,21 @@ | |
| 381 | for use of any OCI container system that implements the same interfaces. |
| 382 | We go into more details about this [below](#light), but |
| 383 | for now, it suffices to point out that you can switch to Podman while |
| 384 | using our `Makefile` convenience targets unchanged by saying: |
| 385 | |
| 386 | $ make CENGINE=podman container-run |
| 387 | |
| 388 | |
| 389 | ### 5.4 <a id="config"></a>Fossil Configuration Options |
| 390 | |
| 391 | You can use this same mechanism to enable non-default Fossil |
| 392 | configuration options in your build. For instance, to turn on |
| 393 | the JSON API and the TH1 docs extension: |
| 394 | |
| 395 | $ make container-image \ |
| 396 | DBFLAGS='--build-arg FSLCFG="--json --with-th1-docs"' |
| 397 | |
| 398 | If you also wanted [the Tcl evaluation extension](./th1.md#tclEval), |
| 399 | that brings us to [the next point](#run). |
| 400 | |
| 401 | |
| @@ -429,20 +403,20 @@ | |
| 403 | |
| 404 | If you want a basic shell environment for temporary debugging of the |
| 405 | running container, that’s easily added. Simply change this line in the |
| 406 | `Dockerfile`… |
| 407 | |
| 408 | FROM scratch AS run |
| 409 | |
| 410 | …to this: |
| 411 | |
| 412 | FROM busybox AS run |
| 413 | |
| 414 | Rebuild and redeploy to give your Fossil container a [BusyBox]-based |
| 415 | shell environment that you can get into via: |
| 416 | |
| 417 | $ docker exec -it -u fossil $(make container-version) sh |
| 418 | |
| 419 | That command assumes you built it via “`make container`” and are |
| 420 | therefore using its versioning scheme. |
| 421 | |
| 422 | You will likely want to remove the `PATH` override in the “RUN” stage |
| @@ -463,11 +437,10 @@ | |
| 437 | most popular programming languages in the world, we have many options |
| 438 | for achieving this. For instance, there is a whole class of |
| 439 | “[distroless]” images that will do this efficiently by changing |
| 440 | “`STAGE 2`” in the `Dockefile` to this: |
| 441 | |
| 442 | ## --------------------------------------------------------------------- |
| 443 | ## STAGE 2: Pare that back to the bare essentials, plus Python. |
| 444 | ## --------------------------------------------------------------------- |
| 445 | FROM cgr.dev/chainguard/python:latest |
| 446 | USER root |
| @@ -478,24 +451,21 @@ | |
| 451 | RUN [ "/bin/busybox", "--install", "/bin" ] |
| 452 | RUN set -x \ |
| 453 | && echo "fossil:x:${UID}:${UID}:User:/museum:/false" >> /etc/passwd \ |
| 454 | && echo "fossil:x:${UID}:fossil" >> /etc/group \ |
| 455 | && install -d -m 700 -o fossil -g fossil log museum |
| 456 | |
| 457 | You will also have to add `busybox-static` to the APK package list in |
| 458 | STAGE 1 for the `RUN` script at the end of that stage to work, since the |
| 459 | [Chainguard Python image][cgimgs] lacks a shell, on purpose. The need to |
| 460 | install root-level binaries is why we change `USER` temporarily here. |
| 461 | |
| 462 | Build it and test that it works like so: |
| 463 | |
| 464 | $ make container-run && |
| 465 | docker exec -i $(make container-version) python --version |
| 466 | 3.11.2 |
| 467 | |
| 468 | The compensation for the hassle of using Chainguard over something more |
| 469 | general purpose like changing the `run` layer to Alpine and then adding |
| 470 | a “`apk add python`” command to the `Dockerfile` |
| 471 | is huge: we no longer leave a package manager sitting around inside the |
| @@ -555,11 +525,10 @@ | |
| 525 | into this, [enable linger |
| 526 | mode](https://www.freedesktop.org/software/systemd/man/loginctl.html).) |
| 527 | so I was able to create a unit file called |
| 528 | `~/.local/share/systemd/user/[email protected]` with these contents: |
| 529 | |
| 530 | [Unit] |
| 531 | Description=Fossil email alert sender for %I |
| 532 | |
| 533 | [Service] |
| 534 | WorkingDirectory=/home/fossil/museum |
| @@ -567,20 +536,17 @@ | |
| 536 | Restart=always |
| 537 | RestartSec=3 |
| 538 | |
| 539 | [Install] |
| 540 | WantedBy=default.target |
| 541 | |
| 542 | I was then able to enable email alert forwarding for select repositories |
| 543 | after configuring them per [the docs](./alerts.md) by saying: |
| 544 | |
| 545 | $ systemctl --user daemon-reload |
| 546 | $ systemctl --user enable alert-sender@myproject |
| 547 | $ systemctl --user start alert-sender@myproject |
| 548 | |
| 549 | Because this is a parameterized script and we’ve set our repository |
| 550 | paths predictably, you can do this for as many repositories as you need |
| 551 | to by passing their names after the “`@`” sign in the commands above. |
| 552 | |
| @@ -606,13 +572,11 @@ | |
| 572 | For the sake of simple examples in this section, we’ll assume you’re |
| 573 | integrating Fossil into a larger web site, such as with our [Debian + |
| 574 | nginx + TLS][DNT] plan. This is why all of the examples below create |
| 575 | the container with this option: |
| 576 | |
| 577 | --publish 127.0.0.1:9999:8080 |
| 578 | |
| 579 | The assumption is that there’s a reverse proxy running somewhere that |
| 580 | redirects public web hits to localhost port 9999, which in turn goes to |
| 581 | port 8080 inside the container. This use of port |
| 582 | publishing effectively replaces the use of the |
| @@ -678,14 +642,12 @@ | |
| 642 | tenth the size of Docker Engine. |
| 643 | |
| 644 | For our purposes here, the only thing that changes relative to the |
| 645 | examples at the top of this document are the initial command: |
| 646 | |
| 647 | $ podman build -t fossil . |
| 648 | $ podman run --name fossil -p 9999:8080/tcp fossil |
| 649 | |
| 650 | Your Linux package repo may have a `podman-docker` package which |
| 651 | provides a “`docker`” script that calls “`podman`” for you, eliminating |
| 652 | even the command name difference. With that installed, the `make` |
| 653 | commands above will work with Podman as-is. |
| @@ -692,23 +654,21 @@ | |
| 654 | |
| 655 | The only difference that matters here is that Podman doesn’t have the |
| 656 | same [default Linux kernel capability set](#caps) as Docker, which |
| 657 | affects the `--cap-drop` flags recommended above to: |
| 658 | |
| 659 | $ podman create \ |
| 660 | --name fossil \ |
| 661 | --cap-drop CHOWN \ |
| 662 | --cap-drop FSETID \ |
| 663 | --cap-drop KILL \ |
| 664 | --cap-drop NET_BIND_SERVICE \ |
| 665 | --cap-drop SETFCAP \ |
| 666 | --cap-drop SETPCAP \ |
| 667 | --publish 127.0.0.1:9999:8080 \ |
| 668 | localhost/fossil |
| 669 | $ podman start fossil |
| 670 | |
| 671 | [pmmac]: https://podman.io/getting-started/installation.html#macos |
| 672 | [pmwin]: https://github.com/containers/podman/blob/main/docs/tutorials/podman-for-windows.md |
| 673 | [Podman]: https://podman.io/ |
| 674 | [rl]: https://github.com/containers/podman/blob/main/docs/tutorials/rootless_tutorial.md |
| @@ -720,13 +680,11 @@ | |
| 680 | If even the Podman stack is too big for you, the next-best option I’m |
| 681 | aware of is the `systemd-container` infrastructure on modern Linuxes, |
| 682 | available since version 239 or so. Its runtime tooling requires only |
| 683 | about 1.4 MiB of disk space: |
| 684 | |
| 685 | $ sudo apt install systemd-container btrfs-tools |
| 686 | |
| 687 | That command assumes the primary test environment for |
| 688 | this guide, Ubuntu 22.04 LTS with `systemd` 249. For best |
| 689 | results, `/var/lib/machines` should be a btrfs volume, because |
| 690 | [`$REASONS`][mcfad]. For CentOS Stream 9 and other Red Hattish |
| @@ -742,60 +700,54 @@ | |
| 700 | If you use [the stock `Dockerfile`][DF] to generate your |
| 701 | base image, `nspawn` won’t recognize it as containing an OS unless you |
| 702 | change the “`FROM scratch AS os`” line at the top of the second stage |
| 703 | to something like this: |
| 704 | |
| 705 | FROM gcr.io/distroless/static-debian11 AS os |
| 706 | |
| 707 | Using that as a base image provides all the files `nspawn` checks for to |
| 708 | determine whether the container is sufficiently close to a Linux VM for |
| 709 | the following step to proceed: |
| 710 | |
| 711 | $ make container |
| 712 | $ docker container export $(make container-version) | |
| 713 | machinectl import-tar - myproject |
| 714 | |
| 715 | Next, create `/etc/systemd/nspawn/myproject.nspawn`: |
| 716 | |
| 717 | ---- |
| 718 | |
| 719 | [Exec] |
| 720 | WorkingDirectory=/ |
| 721 | Parameters=bin/fossil server \ |
| 722 | --baseurl https://example.com/myproject \ |
| 723 | --create \ |
| 724 | --jsmode bundled \ |
| 725 | --localhost \ |
| 726 | --port 9000 \ |
| 727 | --scgi \ |
| 728 | --user admin \ |
| 729 | museum/repo.fossil |
| 730 | DropCapability= \ |
| 731 | CAP_AUDIT_WRITE \ |
| 732 | CAP_CHOWN \ |
| 733 | CAP_FSETID \ |
| 734 | CAP_KILL \ |
| 735 | CAP_MKNOD \ |
| 736 | CAP_NET_BIND_SERVICE \ |
| 737 | CAP_NET_RAW \ |
| 738 | CAP_SETFCAP \ |
| 739 | CAP_SETPCAP |
| 740 | ProcessTwo=yes |
| 741 | LinkJournal=no |
| 742 | Timezone=no |
| 743 | |
| 744 | [Files] |
| 745 | Bind=/home/fossil/museum/myproject:/museum |
| 746 | |
| 747 | [Network] |
| 748 | VirtualEthernet=no |
| 749 | |
| 750 | ---- |
| 751 | |
| 752 | If you recognize most of that from the `Dockerfile` discussion above, |
| 753 | congratulations, you’ve been paying attention. The rest should also |
| @@ -819,22 +771,20 @@ | |
| 771 | That being done, we also need a generic `systemd` unit file called |
| 772 | `/etc/systemd/system/[email protected]`, containing: |
| 773 | |
| 774 | ---- |
| 775 | |
| 776 | [Unit] |
| 777 | Description=Fossil %i Repo Service |
| 778 | [email protected] [email protected] |
| 779 | After=network.target systemd-resolved.service [email protected] [email protected] |
| 780 | |
| 781 | [Service] |
| 782 | ExecStart=systemd-nspawn --settings=override --read-only --machine=%i bin/fossil |
| 783 | |
| 784 | [Install] |
| 785 | WantedBy=multi-user.target |
| 786 | |
| 787 | ---- |
| 788 | |
| 789 | You shouldn’t have to change any of this because we’ve given the |
| 790 | `--setting=override` flag, meaning any setting in the nspawn file |
| @@ -843,42 +793,36 @@ | |
| 793 | share the base configuration, varying on a per-repo level through |
| 794 | adjustments to their individual `*.nspawn` files. |
| 795 | |
| 796 | You may then start the service in the normal way: |
| 797 | |
| 798 | $ sudo systemctl enable fossil@myproject |
| 799 | $ sudo systemctl start fossil@myproject |
| 800 | |
| 801 | You should then find it running on localhost port 9000 per the nspawn |
| 802 | configuration file above, suitable for proxying Fossil out to the |
| 803 | public using nginx via SCGI. If you aren’t using a front-end proxy |
| 804 | and want Fossil exposed to the world via HTTPS, you might say this instead in |
| 805 | the `*.nspawn` file: |
| 806 | |
| 807 | Parameters=bin/fossil server \ |
| 808 | --cert /path/to/cert.pem \ |
| 809 | --create \ |
| 810 | --jsmode bundled \ |
| 811 | --port 443 \ |
| 812 | --user admin \ |
| 813 | museum/repo.fossil |
| 814 | |
| 815 | You would also need to un-drop the `CAP_NET_BIND_SERVICE` capability |
| 816 | to allow Fossil to bind to this low-numbered port. |
| 817 | |
| 818 | We use the `systemd` template file feature to allow multiple Fossil |
| 819 | servers running on a single machine, each on a different TCP port, |
| 820 | as when proxying them out as subdirectories of a larger site. |
| 821 | To add another project, you must first clone the base “machine” layer: |
| 822 | |
| 823 | $ sudo machinectl clone myproject otherthing |
| 824 | |
| 825 | That will not only create a clone of `/var/lib/machines/myproject` |
| 826 | as `../otherthing`, it will create a matching `otherthing.nspawn` file for you |
| 827 | as a copy of the first one. Adjust its contents to suit, then enable |
| 828 | and start it as above. |
| @@ -895,21 +839,17 @@ | |
| 839 | |
| 840 | Fortunately, there are workarounds. |
| 841 | |
| 842 | First, the `apt install` command above becomes: |
| 843 | |
| 844 | $ sudo dnf install systemd-container |
| 845 | |
| 846 | Second, you have to hack around the lack of `machinectl import-tar`: |
| 847 | |
| 848 | $ rootfs=/var/lib/machines/fossil |
| 849 | $ sudo mkdir -p $rootfs |
| 850 | $ docker container export fossil | sudo tar -xf -C $rootfs - |
| 851 | |
| 852 | The parent directory path in the `rootfs` variable is important, |
| 853 | because although we aren’t able to use `machinectl` on such systems, the |
| 854 | `systemd-nspawn` developers assume you’re using them together; when you give |
| 855 | `--machine`, it assumes the `machinectl` directory scheme. You could |
| 856 |
+60
-55
| --- www/custom_ticket.wiki | ||
| +++ www/custom_ticket.wiki | ||
| @@ -1,133 +1,140 @@ | ||
| 1 | 1 | <title>Customizing The Ticket System</title> |
| 2 | -<nowiki> | |
| 2 | + | |
| 3 | 3 | <h2>Introduction</h2> |
| 4 | 4 | |
| 5 | 5 | This guide will explain how to add the "assigned_to" and "submitted_by" fields |
| 6 | 6 | to the ticket system in Fossil, as well as making the system more useful. You |
| 7 | 7 | must have "admin" access to the repository to implement these instructions. |
| 8 | 8 | |
| 9 | 9 | <h2>First modify the TICKET table</h2> |
| 10 | 10 | |
| 11 | -<blockquote> | |
| 12 | 11 | Click on the "Admin" menu, then "Tickets", then "Table". After the other fields |
| 13 | 12 | and before the final ")", insert: |
| 14 | 13 | <pre> |
| 15 | 14 | , |
| 16 | 15 | assigned_to TEXT, |
| 17 | 16 | opened_by TEXT |
| 18 | 17 | </pre> |
| 18 | + | |
| 19 | 19 | And "Apply Changes". You have just added two more fields to the ticket |
| 20 | 20 | database! NOTE: I won't tell you to "Apply Changes" after each step from here |
| 21 | 21 | on out. Now, how do you use these fields? |
| 22 | -</blockquote> | |
| 23 | 22 | |
| 24 | 23 | <h2>Next add assignees</h2> |
| 25 | 24 | |
| 26 | -<blockquote> | |
| 27 | 25 | Back to the "Tickets" admin page, and click "Common". Add something like this: |
| 28 | 26 | <pre> |
| 29 | 27 | set assigned_choices { |
| 30 | 28 | unassigned |
| 31 | 29 | tom |
| 32 | 30 | dick |
| 33 | 31 | harriet |
| 34 | 32 | } |
| 35 | 33 | </pre> |
| 34 | + | |
| 36 | 35 | Obviously, choose names corresponding to the logins on your system. The |
| 37 | 36 | 'unassigned' entry is important, as it prevents you from having a NULL in that |
| 38 | 37 | field (which causes problems later when editing). |
| 39 | -</blockquote> | |
| 40 | 38 | |
| 41 | 39 | <h2>Now modify the 'new ticket' page</h2> |
| 42 | 40 | |
| 43 | -<blockquote> | |
| 44 | 41 | Back to the "Tickets" admin page, and click "New Ticket Page". This is a little |
| 45 | 42 | more tricky. Edit the top part: |
| 46 | -<pre> | |
| 47 | - if {[info exists submit]} { | |
| 48 | - set status Open | |
| 49 | - set opened_by $login | |
| 50 | - set assigned_to "unassigned" | |
| 51 | - submit_ticket | |
| 52 | - } | |
| 53 | -</pre> | |
| 43 | + | |
| 44 | +<verbatim> | |
| 45 | +if {[info exists submit]} { | |
| 46 | + set status Open | |
| 47 | + set opened_by $login | |
| 48 | + set assigned_to "unassigned" | |
| 49 | + submit_ticket | |
| 50 | +} | |
| 51 | +</verbatim> | |
| 52 | + | |
| 54 | 53 | Note the "set opened_by" bit -- that will automatically set the "opened_by" |
| 55 | 54 | field to the login name of the bug reporter. Now, skip to the part with "EMail" |
| 56 | 55 | and modify it like so: |
| 57 | -<pre> | |
| 58 | -<th1>enable_output [expr { "$login" eq "anonymous"}]</th1> | |
| 59 | -<tr> | |
| 60 | -<td align="right">EMail: | |
| 61 | -<input type="text" name="private_contact" value="$<private_contact>" size="30"> | |
| 62 | -</td> | |
| 63 | -<td><u>Not publicly visible</u>. Used by developers to contact you with | |
| 64 | -questions.</td> | |
| 65 | -</tr> | |
| 66 | -<th1>enable_output 1</th1> | |
| 67 | -</pre> | |
| 56 | + | |
| 57 | +<verbatim> | |
| 58 | +<th1>enable_output expr { "$login" eq "anonymous"}</th1> | |
| 59 | +<tr> | |
| 60 | +<td align="right"> | |
| 61 | + EMail: | |
| 62 | + <input type="text" name="private_contact" value="$<private_contact>" size="30"> | |
| 63 | +</td> | |
| 64 | +<td> | |
| 65 | + <u>Not publicly visible</u>. Used by developers to contact you with questions. | |
| 66 | +</td> | |
| 67 | +</tr> | |
| 68 | +<th1>enable_output 1</th1> | |
| 69 | +</verbatim> | |
| 70 | + | |
| 68 | 71 | This bit of code will get rid of the "email" field entry for logged-in users. |
| 69 | 72 | Since we know the user's information, we don't have to ask for it. NOTE: it |
| 70 | 73 | might be good to automatically scoop up the user's email and put it here. |
| 71 | 74 | |
| 72 | 75 | You might also want to enable people to actually assign the ticket to a specific |
| 73 | 76 | person during creation. For this to work, you need to add the code |
| 74 | 77 | for "assigned_to" as shown below under the heading "Modify the 'edit ticket' page". |
| 75 | 78 | This will give you an additional combobox where you can choose a person during |
| 76 | 79 | ticket creation. |
| 77 | -</blockquote> | |
| 78 | 80 | |
| 79 | 81 | <h2>Modify the 'view ticket' page</h2> |
| 80 | 82 | |
| 81 | -<blockquote> | |
| 82 | 83 | Look for the text "Contact:" (about halfway through). Then insert these lines |
| 83 | 84 | after the closing tr tag and before the "enable_output" line: |
| 84 | -<pre> | |
| 85 | -<tr> | |
| 86 | - <td align="right">Assigned to:</td><td bgcolor="#d0d0d0"> | |
| 87 | - $<assigned_to> | |
| 88 | - </td> | |
| 89 | - <td align="right">Opened by:</td><td bgcolor="#d0d0d0"> | |
| 90 | - $<opened_by> | |
| 91 | - </td> | |
| 92 | -</pre> | |
| 85 | + | |
| 86 | +<verbatim> | |
| 87 | +<td align="right">Assigned to:</td><td bgcolor="#d0d0d0"> | |
| 88 | + $<assigned_to> | |
| 89 | +</td> | |
| 90 | +<td align="right">Opened by:</td><td bgcolor="#d0d0d0"> | |
| 91 | + $<opened_by> | |
| 92 | +</td> | |
| 93 | +</verbatim> | |
| 94 | + | |
| 93 | 95 | This will add a row which displays these two fields, in the event the user has |
| 94 | 96 | <a href="./caps/ref.html#w">ticket "edit" capability</a>. |
| 95 | -</blockquote> | |
| 96 | 97 | |
| 97 | 98 | <h2>Modify the 'edit ticket' page</h2> |
| 98 | 99 | |
| 99 | -<blockquote> | |
| 100 | 100 | Before the "Severity:" line, add this: |
| 101 | -<pre> | |
| 102 | -<tr><td align="right">Assigned to:</td><td> | |
| 103 | -<th1>combobox assigned_to $assigned_choices 1</th1> | |
| 104 | -</td></tr> | |
| 105 | -</pre> | |
| 101 | + | |
| 102 | +<verbatim> | |
| 103 | +<tr> | |
| 104 | + <td align="right">Assigned to:</td> | |
| 105 | + <td> | |
| 106 | + <th1>combobox assigned_to $assigned_choices 1</th1> | |
| 107 | + </td> | |
| 108 | +</tr> | |
| 109 | +</verbatim> | |
| 110 | + | |
| 106 | 111 | That will give you a drop-down list of assignees. The first argument to the TH1 |
| 107 | 112 | command 'combobox' is the database field which the combobox is associated to. |
| 108 | 113 | The next argument is the list of choices you want to show in the combobox (and |
| 109 | 114 | that you specified in the second step above. The last argument should be 1 for a |
| 110 | 115 | true combobox (see the <a href="th1.md#combobox">TH1 documentation</a> for |
| 111 | 116 | details). |
| 112 | 117 | |
| 113 | 118 | Now, similar to the previous |
| 114 | 119 | section, look for "Contact:" and add this: |
| 115 | -<pre> | |
| 116 | - <tr><td align="right">Reported by:</td><td> | |
| 117 | - <input type="text" name="opened_by" size="40" | |
| 118 | - value="$<opened_by>"> | |
| 119 | - </td></tr> | |
| 120 | -</pre> | |
| 121 | -</blockquote> | |
| 120 | + | |
| 121 | +<verbatim> | |
| 122 | +<tr> | |
| 123 | + <td align="right">Reported by:</td> | |
| 124 | + <td> | |
| 125 | + <input type="text" name="opened_by" size="40" value="$<opened_by>"> | |
| 126 | + </td> | |
| 127 | +</tr> | |
| 128 | +</verbatim> | |
| 122 | 129 | |
| 123 | 130 | <h2>What next?</h2> |
| 124 | 131 | |
| 125 | -<blockquote> | |
| 126 | 132 | Now you can add custom reports which select based on the person to whom the |
| 127 | 133 | ticket is assigned. For example, an "Assigned to me" report could be: |
| 128 | -<pre> | |
| 134 | + | |
| 135 | +<verbatim> | |
| 129 | 136 | SELECT |
| 130 | 137 | CASE WHEN status IN ('Open','Verified') THEN '#f2dcdc' |
| 131 | 138 | WHEN status='Review' THEN '#e8e8e8' |
| 132 | 139 | WHEN status='Fixed' THEN '#cfe8bd' |
| 133 | 140 | WHEN status='Tested' THEN '#bde5d6' |
| @@ -139,8 +146,6 @@ | ||
| 139 | 146 | status, |
| 140 | 147 | subsystem, |
| 141 | 148 | title |
| 142 | 149 | FROM ticket |
| 143 | 150 | WHERE assigned_to=user() |
| 144 | -</pre> | |
| 145 | -</blockquote> | |
| 146 | -</nowiki> | |
| 151 | +</verbatim> | |
| 147 | 152 |
| --- www/custom_ticket.wiki | |
| +++ www/custom_ticket.wiki | |
| @@ -1,133 +1,140 @@ | |
| 1 | <title>Customizing The Ticket System</title> |
| 2 | <nowiki> |
| 3 | <h2>Introduction</h2> |
| 4 | |
| 5 | This guide will explain how to add the "assigned_to" and "submitted_by" fields |
| 6 | to the ticket system in Fossil, as well as making the system more useful. You |
| 7 | must have "admin" access to the repository to implement these instructions. |
| 8 | |
| 9 | <h2>First modify the TICKET table</h2> |
| 10 | |
| 11 | <blockquote> |
| 12 | Click on the "Admin" menu, then "Tickets", then "Table". After the other fields |
| 13 | and before the final ")", insert: |
| 14 | <pre> |
| 15 | , |
| 16 | assigned_to TEXT, |
| 17 | opened_by TEXT |
| 18 | </pre> |
| 19 | And "Apply Changes". You have just added two more fields to the ticket |
| 20 | database! NOTE: I won't tell you to "Apply Changes" after each step from here |
| 21 | on out. Now, how do you use these fields? |
| 22 | </blockquote> |
| 23 | |
| 24 | <h2>Next add assignees</h2> |
| 25 | |
| 26 | <blockquote> |
| 27 | Back to the "Tickets" admin page, and click "Common". Add something like this: |
| 28 | <pre> |
| 29 | set assigned_choices { |
| 30 | unassigned |
| 31 | tom |
| 32 | dick |
| 33 | harriet |
| 34 | } |
| 35 | </pre> |
| 36 | Obviously, choose names corresponding to the logins on your system. The |
| 37 | 'unassigned' entry is important, as it prevents you from having a NULL in that |
| 38 | field (which causes problems later when editing). |
| 39 | </blockquote> |
| 40 | |
| 41 | <h2>Now modify the 'new ticket' page</h2> |
| 42 | |
| 43 | <blockquote> |
| 44 | Back to the "Tickets" admin page, and click "New Ticket Page". This is a little |
| 45 | more tricky. Edit the top part: |
| 46 | <pre> |
| 47 | if {[info exists submit]} { |
| 48 | set status Open |
| 49 | set opened_by $login |
| 50 | set assigned_to "unassigned" |
| 51 | submit_ticket |
| 52 | } |
| 53 | </pre> |
| 54 | Note the "set opened_by" bit -- that will automatically set the "opened_by" |
| 55 | field to the login name of the bug reporter. Now, skip to the part with "EMail" |
| 56 | and modify it like so: |
| 57 | <pre> |
| 58 | <th1>enable_output [expr { "$login" eq "anonymous"}]</th1> |
| 59 | <tr> |
| 60 | <td align="right">EMail: |
| 61 | <input type="text" name="private_contact" value="$<private_contact>" size="30"> |
| 62 | </td> |
| 63 | <td><u>Not publicly visible</u>. Used by developers to contact you with |
| 64 | questions.</td> |
| 65 | </tr> |
| 66 | <th1>enable_output 1</th1> |
| 67 | </pre> |
| 68 | This bit of code will get rid of the "email" field entry for logged-in users. |
| 69 | Since we know the user's information, we don't have to ask for it. NOTE: it |
| 70 | might be good to automatically scoop up the user's email and put it here. |
| 71 | |
| 72 | You might also want to enable people to actually assign the ticket to a specific |
| 73 | person during creation. For this to work, you need to add the code |
| 74 | for "assigned_to" as shown below under the heading "Modify the 'edit ticket' page". |
| 75 | This will give you an additional combobox where you can choose a person during |
| 76 | ticket creation. |
| 77 | </blockquote> |
| 78 | |
| 79 | <h2>Modify the 'view ticket' page</h2> |
| 80 | |
| 81 | <blockquote> |
| 82 | Look for the text "Contact:" (about halfway through). Then insert these lines |
| 83 | after the closing tr tag and before the "enable_output" line: |
| 84 | <pre> |
| 85 | <tr> |
| 86 | <td align="right">Assigned to:</td><td bgcolor="#d0d0d0"> |
| 87 | $<assigned_to> |
| 88 | </td> |
| 89 | <td align="right">Opened by:</td><td bgcolor="#d0d0d0"> |
| 90 | $<opened_by> |
| 91 | </td> |
| 92 | </pre> |
| 93 | This will add a row which displays these two fields, in the event the user has |
| 94 | <a href="./caps/ref.html#w">ticket "edit" capability</a>. |
| 95 | </blockquote> |
| 96 | |
| 97 | <h2>Modify the 'edit ticket' page</h2> |
| 98 | |
| 99 | <blockquote> |
| 100 | Before the "Severity:" line, add this: |
| 101 | <pre> |
| 102 | <tr><td align="right">Assigned to:</td><td> |
| 103 | <th1>combobox assigned_to $assigned_choices 1</th1> |
| 104 | </td></tr> |
| 105 | </pre> |
| 106 | That will give you a drop-down list of assignees. The first argument to the TH1 |
| 107 | command 'combobox' is the database field which the combobox is associated to. |
| 108 | The next argument is the list of choices you want to show in the combobox (and |
| 109 | that you specified in the second step above. The last argument should be 1 for a |
| 110 | true combobox (see the <a href="th1.md#combobox">TH1 documentation</a> for |
| 111 | details). |
| 112 | |
| 113 | Now, similar to the previous |
| 114 | section, look for "Contact:" and add this: |
| 115 | <pre> |
| 116 | <tr><td align="right">Reported by:</td><td> |
| 117 | <input type="text" name="opened_by" size="40" |
| 118 | value="$<opened_by>"> |
| 119 | </td></tr> |
| 120 | </pre> |
| 121 | </blockquote> |
| 122 | |
| 123 | <h2>What next?</h2> |
| 124 | |
| 125 | <blockquote> |
| 126 | Now you can add custom reports which select based on the person to whom the |
| 127 | ticket is assigned. For example, an "Assigned to me" report could be: |
| 128 | <pre> |
| 129 | SELECT |
| 130 | CASE WHEN status IN ('Open','Verified') THEN '#f2dcdc' |
| 131 | WHEN status='Review' THEN '#e8e8e8' |
| 132 | WHEN status='Fixed' THEN '#cfe8bd' |
| 133 | WHEN status='Tested' THEN '#bde5d6' |
| @@ -139,8 +146,6 @@ | |
| 139 | status, |
| 140 | subsystem, |
| 141 | title |
| 142 | FROM ticket |
| 143 | WHERE assigned_to=user() |
| 144 | </pre> |
| 145 | </blockquote> |
| 146 | </nowiki> |
| 147 |
| --- www/custom_ticket.wiki | |
| +++ www/custom_ticket.wiki | |
| @@ -1,133 +1,140 @@ | |
| 1 | <title>Customizing The Ticket System</title> |
| 2 | |
| 3 | <h2>Introduction</h2> |
| 4 | |
| 5 | This guide will explain how to add the "assigned_to" and "submitted_by" fields |
| 6 | to the ticket system in Fossil, as well as making the system more useful. You |
| 7 | must have "admin" access to the repository to implement these instructions. |
| 8 | |
| 9 | <h2>First modify the TICKET table</h2> |
| 10 | |
| 11 | Click on the "Admin" menu, then "Tickets", then "Table". After the other fields |
| 12 | and before the final ")", insert: |
| 13 | <pre> |
| 14 | , |
| 15 | assigned_to TEXT, |
| 16 | opened_by TEXT |
| 17 | </pre> |
| 18 | |
| 19 | And "Apply Changes". You have just added two more fields to the ticket |
| 20 | database! NOTE: I won't tell you to "Apply Changes" after each step from here |
| 21 | on out. Now, how do you use these fields? |
| 22 | |
| 23 | <h2>Next add assignees</h2> |
| 24 | |
| 25 | Back to the "Tickets" admin page, and click "Common". Add something like this: |
| 26 | <pre> |
| 27 | set assigned_choices { |
| 28 | unassigned |
| 29 | tom |
| 30 | dick |
| 31 | harriet |
| 32 | } |
| 33 | </pre> |
| 34 | |
| 35 | Obviously, choose names corresponding to the logins on your system. The |
| 36 | 'unassigned' entry is important, as it prevents you from having a NULL in that |
| 37 | field (which causes problems later when editing). |
| 38 | |
| 39 | <h2>Now modify the 'new ticket' page</h2> |
| 40 | |
| 41 | Back to the "Tickets" admin page, and click "New Ticket Page". This is a little |
| 42 | more tricky. Edit the top part: |
| 43 | |
| 44 | <verbatim> |
| 45 | if {[info exists submit]} { |
| 46 | set status Open |
| 47 | set opened_by $login |
| 48 | set assigned_to "unassigned" |
| 49 | submit_ticket |
| 50 | } |
| 51 | </verbatim> |
| 52 | |
| 53 | Note the "set opened_by" bit -- that will automatically set the "opened_by" |
| 54 | field to the login name of the bug reporter. Now, skip to the part with "EMail" |
| 55 | and modify it like so: |
| 56 | |
| 57 | <verbatim> |
| 58 | <th1>enable_output expr { "$login" eq "anonymous"}</th1> |
| 59 | <tr> |
| 60 | <td align="right"> |
| 61 | EMail: |
| 62 | <input type="text" name="private_contact" value="$<private_contact>" size="30"> |
| 63 | </td> |
| 64 | <td> |
| 65 | <u>Not publicly visible</u>. Used by developers to contact you with questions. |
| 66 | </td> |
| 67 | </tr> |
| 68 | <th1>enable_output 1</th1> |
| 69 | </verbatim> |
| 70 | |
| 71 | This bit of code will get rid of the "email" field entry for logged-in users. |
| 72 | Since we know the user's information, we don't have to ask for it. NOTE: it |
| 73 | might be good to automatically scoop up the user's email and put it here. |
| 74 | |
| 75 | You might also want to enable people to actually assign the ticket to a specific |
| 76 | person during creation. For this to work, you need to add the code |
| 77 | for "assigned_to" as shown below under the heading "Modify the 'edit ticket' page". |
| 78 | This will give you an additional combobox where you can choose a person during |
| 79 | ticket creation. |
| 80 | |
| 81 | <h2>Modify the 'view ticket' page</h2> |
| 82 | |
| 83 | Look for the text "Contact:" (about halfway through). Then insert these lines |
| 84 | after the closing tr tag and before the "enable_output" line: |
| 85 | |
| 86 | <verbatim> |
| 87 | <td align="right">Assigned to:</td><td bgcolor="#d0d0d0"> |
| 88 | $<assigned_to> |
| 89 | </td> |
| 90 | <td align="right">Opened by:</td><td bgcolor="#d0d0d0"> |
| 91 | $<opened_by> |
| 92 | </td> |
| 93 | </verbatim> |
| 94 | |
| 95 | This will add a row which displays these two fields, in the event the user has |
| 96 | <a href="./caps/ref.html#w">ticket "edit" capability</a>. |
| 97 | |
| 98 | <h2>Modify the 'edit ticket' page</h2> |
| 99 | |
| 100 | Before the "Severity:" line, add this: |
| 101 | |
| 102 | <verbatim> |
| 103 | <tr> |
| 104 | <td align="right">Assigned to:</td> |
| 105 | <td> |
| 106 | <th1>combobox assigned_to $assigned_choices 1</th1> |
| 107 | </td> |
| 108 | </tr> |
| 109 | </verbatim> |
| 110 | |
| 111 | That will give you a drop-down list of assignees. The first argument to the TH1 |
| 112 | command 'combobox' is the database field which the combobox is associated to. |
| 113 | The next argument is the list of choices you want to show in the combobox (and |
| 114 | that you specified in the second step above. The last argument should be 1 for a |
| 115 | true combobox (see the <a href="th1.md#combobox">TH1 documentation</a> for |
| 116 | details). |
| 117 | |
| 118 | Now, similar to the previous |
| 119 | section, look for "Contact:" and add this: |
| 120 | |
| 121 | <verbatim> |
| 122 | <tr> |
| 123 | <td align="right">Reported by:</td> |
| 124 | <td> |
| 125 | <input type="text" name="opened_by" size="40" value="$<opened_by>"> |
| 126 | </td> |
| 127 | </tr> |
| 128 | </verbatim> |
| 129 | |
| 130 | <h2>What next?</h2> |
| 131 | |
| 132 | Now you can add custom reports which select based on the person to whom the |
| 133 | ticket is assigned. For example, an "Assigned to me" report could be: |
| 134 | |
| 135 | <verbatim> |
| 136 | SELECT |
| 137 | CASE WHEN status IN ('Open','Verified') THEN '#f2dcdc' |
| 138 | WHEN status='Review' THEN '#e8e8e8' |
| 139 | WHEN status='Fixed' THEN '#cfe8bd' |
| 140 | WHEN status='Tested' THEN '#bde5d6' |
| @@ -139,8 +146,6 @@ | |
| 146 | status, |
| 147 | subsystem, |
| 148 | title |
| 149 | FROM ticket |
| 150 | WHERE assigned_to=user() |
| 151 | </verbatim> |
| 152 |
+64
-69
| --- www/customskin.md | ||
| +++ www/customskin.md | ||
| @@ -57,87 +57,82 @@ | ||
| 57 | 57 | |
| 58 | 58 | # Structure Of A Fossil Web Page |
| 59 | 59 | |
| 60 | 60 | Every HTML page generated by Fossil has the same basic structure: |
| 61 | 61 | |
| 62 | -<blockquote><table border=1 cellpadding=10><tbody> | |
| 63 | -<tr><td style='background-color:lightgreen;text-align:center;'> | |
| 64 | -Fossil-Generated HTML Header</td></tr> | |
| 65 | -<tr><td style='background-color:lightblue;text-align:center;'>Content Header</td></tr> | |
| 66 | -<tr><td style='background-color:lightgreen;text-align:center;'> | |
| 67 | -Fossil-Generated Content</td></tr> | |
| 68 | -<tr><td style='background-color:lightblue;text-align:center;'>Content Footer</td></tr> | |
| 69 | -<tr><td style='background-color:lightgreen;text-align:center;'> | |
| 70 | -Fossil-Generated HTML Footer</td></tr> | |
| 71 | -</tbody></table></blockquote> | |
| 62 | +| Fossil-Generated HTML Header | | |
| 63 | +| Content Header | | |
| 64 | +| Fossil-Generated Content | | |
| 65 | +| Content Footer | | |
| 66 | +| Fossil-Generated HTML Footer | | |
| 72 | 67 | |
| 73 | 68 | The green parts are *usually* generated by Fossil. The blue parts |
| 74 | 69 | are things that you, the administrator, get to modify in order to |
| 75 | 70 | customize the skin. |
| 76 | 71 | |
| 77 | 72 | Fossil *usually* (but not always - [see below](#override)) |
| 78 | 73 | generates the initial HTML Header section of a page. The |
| 79 | 74 | generated HTML Header will look something like this: |
| 80 | 75 | |
| 81 | - <html> | |
| 82 | - <head> | |
| 83 | - <base href="..."> | |
| 84 | - <meta http-equiv="Content-Security-Policy" content="...."> | |
| 85 | - <meta name="viewport" content="width=device-width, initial-scale=1.0"> | |
| 86 | - <title>....</title> | |
| 87 | - <link rel="stylesheet" href="..." type="text/css"> | |
| 88 | - </head> | |
| 89 | - <body class="FEATURE"> | |
| 76 | + <html> | |
| 77 | + <head> | |
| 78 | + <base href="..."> | |
| 79 | + <meta http-equiv="Content-Security-Policy" content="...."> | |
| 80 | + <meta name="viewport" content="width=device-width, initial-scale=1.0"> | |
| 81 | + <title>....</title> | |
| 82 | + <link rel="stylesheet" href="..." type="text/css"> | |
| 83 | + </head> | |
| 84 | + <body class="FEATURE"> | |
| 90 | 85 | |
| 91 | 86 | …where `FEATURE` is either the top-level URL element (e.g. `doc`) or a |
| 92 | 87 | feature class that groups multiple URLs under a single name such as |
| 93 | 88 | `forum` to contain `/forummain`, `/forumpost`, `/forume2`, etc. This |
| 94 | 89 | allows per-feature CSS such as |
| 95 | 90 | |
| 96 | - body.forum div.markdown blockquote { | |
| 97 | - margin-left: 10px; | |
| 98 | - } | |
| 91 | + body.forum div.markdown blockquote { | |
| 92 | + margin-left: 10px; | |
| 93 | + } | |
| 99 | 94 | |
| 100 | 95 | That is, affect HTML `<blockquote>` tags specially only for forum posts |
| 101 | 96 | written in Markdown, leaving all other block quotes alone. |
| 102 | 97 | |
| 103 | 98 | In most cases, it is best to leave the Fossil-generated HTML Header |
| 104 | 99 | alone. (One exception is when the administrator needs to include links |
| 105 | 100 | to additional CSS files.) The configurable part of the skin begins |
| 106 | 101 | with the Content Header section which should follow this template: |
| 107 | 102 | |
| 108 | - <div class="header"> | |
| 109 | - ... top banner and menu bar ... | |
| 110 | - </div> | |
| 103 | + <div class="header"> | |
| 104 | + ... top banner and menu bar ... | |
| 105 | + </div> | |
| 111 | 106 | |
| 112 | 107 | Note that `<div class="header">` and `</div>` tags must be included in |
| 113 | 108 | the Content Header text of the skin. In other words, you, the |
| 114 | 109 | administrator, need to supply that text as part of your skin |
| 115 | 110 | customization. |
| 116 | 111 | |
| 117 | 112 | The Fossil-generated Content section immediately follows the Content Header. |
| 118 | 113 | The Content section will looks like this: |
| 119 | 114 | |
| 120 | - <div class="content"> | |
| 121 | - ... Fossil-generated content here ... | |
| 122 | - </div> | |
| 115 | + <div class="content"> | |
| 116 | + ... Fossil-generated content here ... | |
| 117 | + </div> | |
| 123 | 118 | |
| 124 | 119 | After the Content is the custom Content Footer section which should |
| 125 | 120 | follow this template: |
| 126 | 121 | |
| 127 | - <div class="footer"> | |
| 128 | - ... skin-specific stuff here ... | |
| 129 | - </div> | |
| 122 | + <div class="footer"> | |
| 123 | + ... skin-specific stuff here ... | |
| 124 | + </div> | |
| 130 | 125 | |
| 131 | 126 | As with the Content Header, the template elements of the Content Footer |
| 132 | 127 | should appear exactly as they are shown. |
| 133 | 128 | |
| 134 | 129 | Finally, Fossil always adds its own footer (unless overridden) |
| 135 | 130 | to close out the generated HTML: |
| 136 | 131 | |
| 137 | - </body> | |
| 138 | - </html> | |
| 132 | + </body> | |
| 133 | + </html> | |
| 139 | 134 | |
| 140 | 135 | ## <a id="mainmenu"></a>Changing the Main Menu Contents |
| 141 | 136 | |
| 142 | 137 | As of Fossil 2.15, the actual text content of the skin’s main menu is no |
| 143 | 138 | longer part of the skin proper if you’re using one of the stock skins. |
| @@ -179,11 +174,11 @@ | ||
| 179 | 174 | make incremental modifications, testing after each step, to obtain the |
| 180 | 175 | desired result. |
| 181 | 176 | |
| 182 | 177 | The skin is controlled by five files: |
| 183 | 178 | |
| 184 | -<blockquote><dl> | |
| 179 | +<dl> | |
| 185 | 180 | <dt><b>css.txt</b></dt> |
| 186 | 181 | |
| 187 | 182 | <dd>The css.txt file is the text of the CSS for Fossil. |
| 188 | 183 | Fossil might add additional CSS elements after |
| 189 | 184 | the css.txt file, if it sees that the css.txt omits some |
| @@ -194,20 +189,20 @@ | ||
| 194 | 189 | |
| 195 | 190 | <dd>The details.txt file is short list of settings that control |
| 196 | 191 | the look and feel, mostly of the timeline. The default |
| 197 | 192 | details.txt file looks like this: |
| 198 | 193 | |
| 199 | -<blockquote><pre> | |
| 194 | +<pre> | |
| 200 | 195 | pikchr-background: "" |
| 201 | 196 | pikchr-fontscale: "" |
| 202 | 197 | pikchr-foreground: "" |
| 203 | 198 | pikchr-scale: "" |
| 204 | 199 | timeline-arrowheads: 1 |
| 205 | 200 | timeline-circle-nodes: 1 |
| 206 | 201 | timeline-color-graph-lines: 1 |
| 207 | 202 | white-foreground: 0 |
| 208 | -</pre></blockquote> | |
| 203 | +</pre> | |
| 209 | 204 | |
| 210 | 205 | The three "timeline-" settings in details.txt control the appearance |
| 211 | 206 | of certain aspects of the timeline graph. The number on the |
| 212 | 207 | right is a boolean - "1" to activate the feature and "0" to |
| 213 | 208 | disable it. The "white-foreground:" setting should be set to |
| @@ -242,26 +237,26 @@ | ||
| 242 | 237 | <dd>The js.txt file is optional. It is intended to be javascript. |
| 243 | 238 | The complete text of this javascript might be inserted into |
| 244 | 239 | the Content Footer, after being processed using TH1, using |
| 245 | 240 | code like the following in the "footer.txt" file: |
| 246 | 241 | |
| 247 | -<blockquote><pre> | |
| 242 | +<pre> | |
| 248 | 243 | <script nonce="$nonce"> |
| 249 | 244 | <th1>styleScript</th1> |
| 250 | 245 | </script> |
| 251 | -</pre></blockquote> | |
| 246 | +</pre> | |
| 252 | 247 | |
| 253 | 248 | The js.txt file was originally used to insert javascript |
| 254 | 249 | that controls the hamburger menu in the default skin. More |
| 255 | 250 | recently, the javascript for the hamburger menu was moved into |
| 256 | 251 | a separate built-in file. Skins that use the hamburger menu |
| 257 | 252 | typically cause the javascript to be loaded by including the |
| 258 | 253 | following TH1 code in the "header.txt" file: |
| 259 | 254 | |
| 260 | -<blockquote><pre> | |
| 255 | +<pre> | |
| 261 | 256 | <th1>builtin_request_js hbmenu.js</th1> |
| 262 | -</pre></blockquote> | |
| 257 | +</pre> | |
| 263 | 258 | |
| 264 | 259 | The difference between styleScript and builtin_request_js |
| 265 | 260 | is that the styleScript command interprets the file |
| 266 | 261 | using TH1 and injects the content directly into the output |
| 267 | 262 | stream, whereas the builtin_request_js command inserts the |
| @@ -274,11 +269,11 @@ | ||
| 274 | 269 | |
| 275 | 270 | Note that the "js.txt" file is *not* automatically inserted into |
| 276 | 271 | the generate HTML for a page. You, the skin designer, must |
| 277 | 272 | cause the javascript to be inserted by issuing appropriate |
| 278 | 273 | TH1 commands in the "header.txt" or "footer.txt" files.</dd> |
| 279 | -</dl></blockquote> | |
| 274 | +</dl> | |
| 280 | 275 | |
| 281 | 276 | Developing a new skin is simply a matter of creating appropriate |
| 282 | 277 | versions of these five control files. |
| 283 | 278 | |
| 284 | 279 | ### Skin Development Using The Web Interface |
| @@ -334,17 +329,17 @@ | ||
| 334 | 329 | the value of the TH1 variable NAME. |
| 335 | 330 | |
| 336 | 331 | For example, first few lines of a typical Content Header will look |
| 337 | 332 | like this: |
| 338 | 333 | |
| 339 | - <div class="header"> | |
| 340 | - <div class="title"><h1>$<project_name></h1>$<title>/div> | |
| 334 | + <div class="header"> | |
| 335 | + <div class="title"><h1>$<project_name></h1>$<title>/div> | |
| 341 | 336 | |
| 342 | 337 | After variables are substituted by TH1, that will look more like this: |
| 343 | 338 | |
| 344 | - <div class="header"> | |
| 345 | - <div class="title"><h1>Project Name</h1>Page Title</div> | |
| 339 | + <div class="header"> | |
| 340 | + <div class="title"><h1>Project Name</h1>Page Title</div> | |
| 346 | 341 | |
| 347 | 342 | As you can see, two TH1 variable substitutions were done. |
| 348 | 343 | |
| 349 | 344 | The same TH1 interpreter is used for both the header and the footer |
| 350 | 345 | and for all scripts contained within them both. Hence, any global |
| @@ -360,12 +355,12 @@ | ||
| 360 | 355 | that are part of Fossil. |
| 361 | 356 | |
| 362 | 357 | The ≡ button for the hamburger menu is added to the menu bar by the following |
| 363 | 358 | TH1 commands in the `header.txt` file, right before the menu bar links: |
| 364 | 359 | |
| 365 | - html "<a id='hbbtn' href='$home/sitemap'>☰</a>" | |
| 366 | - builtin_request_js hbmenu.js | |
| 360 | + html "<a id='hbbtn' href='$home/sitemap'>☰</a>" | |
| 361 | + builtin_request_js hbmenu.js | |
| 367 | 362 | |
| 368 | 363 | The hamburger button can be repositioned between the other menu links (but the |
| 369 | 364 | drop-down menu is always left-aligned with the menu bar), or it can be removed |
| 370 | 365 | by deleting the above statements. The "html" statement inserts the appropriate |
| 371 | 366 | `<a>` for the hamburger menu button (some skins require something slightly |
| @@ -375,40 +370,40 @@ | ||
| 375 | 370 | |
| 376 | 371 | The hbmenu.js script requires |
| 377 | 372 | the following `<div>` element somewhere in your header, in which to build |
| 378 | 373 | the hamburger menu. |
| 379 | 374 | |
| 380 | - <div id='hbdrop'></div> | |
| 375 | + <div id='hbdrop'></div> | |
| 381 | 376 | |
| 382 | 377 | Out of the box, the contents of the panel is populated with the [Site |
| 383 | 378 | Map](/sitemap), but only if the panel does not already contain any HTML |
| 384 | 379 | elements (that is, not just comments, plain text or non-presentational white |
| 385 | 380 | space). So the hamburger menu can be customized by replacing the empty `<div |
| 386 | 381 | id='hbdrop'></div>` element with a menu structure knitted according to the |
| 387 | 382 | following template: |
| 388 | 383 | |
| 389 | - <div id="hbdrop" data-anim-ms="400"> | |
| 390 | - <ul class="columns" style="column-width: 20em; column-count: auto"> | |
| 391 | - <!-- NEW GROUP WITH HEADING LINK --> | |
| 392 | - <li> | |
| 393 | - <a href="$home$index_page">Link: Home</a> | |
| 394 | - <ul> | |
| 395 | - <li><a href="$home/timeline">Link: Timeline</a></li> | |
| 396 | - <li><a href="$home/dir?ci=tip">Link: File List</a></li> | |
| 397 | - </ul> | |
| 398 | - </li> | |
| 399 | - <!-- NEW GROUP WITH HEADING TEXT --> | |
| 400 | - <li> | |
| 401 | - Heading Text | |
| 402 | - <ul> | |
| 403 | - <li><a href="$home/doc/trunk/www/customskin.md">Link: Theming</a></li> | |
| 404 | - <li><a href="$home/doc/trunk/www/th1.md">Link: TH1 Scripts</a></li> | |
| 405 | - </ul> | |
| 406 | - </li> | |
| 407 | - <!-- NEXT GROUP GOES HERE --> | |
| 408 | - </ul> | |
| 409 | - </div> | |
| 384 | + <div id="hbdrop" data-anim-ms="400"> | |
| 385 | + <ul class="columns" style="column-width: 20em; column-count: auto"> | |
| 386 | + <!-- NEW GROUP WITH HEADING LINK --> | |
| 387 | + <li> | |
| 388 | + <a href="$home$index_page">Link: Home</a> | |
| 389 | + <ul> | |
| 390 | + <li><a href="$home/timeline">Link: Timeline</a></li> | |
| 391 | + <li><a href="$home/dir?ci=tip">Link: File List</a></li> | |
| 392 | + </ul> | |
| 393 | + </li> | |
| 394 | + <!-- NEW GROUP WITH HEADING TEXT --> | |
| 395 | + <li> | |
| 396 | + Heading Text | |
| 397 | + <ul> | |
| 398 | + <li><a href="$home/doc/trunk/www/customskin.md">Link: Theming</a></li> | |
| 399 | + <li><a href="$home/doc/trunk/www/th1.md">Link: TH1 Scripts</a></li> | |
| 400 | + </ul> | |
| 401 | + </li> | |
| 402 | + <!-- NEXT GROUP GOES HERE --> | |
| 403 | + </ul> | |
| 404 | + </div> | |
| 410 | 405 | |
| 411 | 406 | The custom `data-anim-ms` attribute can be added to the panel element to direct |
| 412 | 407 | the Javascript logic to override the default menu animation duration of 400 ms. |
| 413 | 408 | A faster animation duration of 80-200 ms may be preferred for smaller menus. The |
| 414 | 409 | animation is disabled by setting the attribute to `"0"`. |
| 415 | 410 |
| --- www/customskin.md | |
| +++ www/customskin.md | |
| @@ -57,87 +57,82 @@ | |
| 57 | |
| 58 | # Structure Of A Fossil Web Page |
| 59 | |
| 60 | Every HTML page generated by Fossil has the same basic structure: |
| 61 | |
| 62 | <blockquote><table border=1 cellpadding=10><tbody> |
| 63 | <tr><td style='background-color:lightgreen;text-align:center;'> |
| 64 | Fossil-Generated HTML Header</td></tr> |
| 65 | <tr><td style='background-color:lightblue;text-align:center;'>Content Header</td></tr> |
| 66 | <tr><td style='background-color:lightgreen;text-align:center;'> |
| 67 | Fossil-Generated Content</td></tr> |
| 68 | <tr><td style='background-color:lightblue;text-align:center;'>Content Footer</td></tr> |
| 69 | <tr><td style='background-color:lightgreen;text-align:center;'> |
| 70 | Fossil-Generated HTML Footer</td></tr> |
| 71 | </tbody></table></blockquote> |
| 72 | |
| 73 | The green parts are *usually* generated by Fossil. The blue parts |
| 74 | are things that you, the administrator, get to modify in order to |
| 75 | customize the skin. |
| 76 | |
| 77 | Fossil *usually* (but not always - [see below](#override)) |
| 78 | generates the initial HTML Header section of a page. The |
| 79 | generated HTML Header will look something like this: |
| 80 | |
| 81 | <html> |
| 82 | <head> |
| 83 | <base href="..."> |
| 84 | <meta http-equiv="Content-Security-Policy" content="...."> |
| 85 | <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| 86 | <title>....</title> |
| 87 | <link rel="stylesheet" href="..." type="text/css"> |
| 88 | </head> |
| 89 | <body class="FEATURE"> |
| 90 | |
| 91 | …where `FEATURE` is either the top-level URL element (e.g. `doc`) or a |
| 92 | feature class that groups multiple URLs under a single name such as |
| 93 | `forum` to contain `/forummain`, `/forumpost`, `/forume2`, etc. This |
| 94 | allows per-feature CSS such as |
| 95 | |
| 96 | body.forum div.markdown blockquote { |
| 97 | margin-left: 10px; |
| 98 | } |
| 99 | |
| 100 | That is, affect HTML `<blockquote>` tags specially only for forum posts |
| 101 | written in Markdown, leaving all other block quotes alone. |
| 102 | |
| 103 | In most cases, it is best to leave the Fossil-generated HTML Header |
| 104 | alone. (One exception is when the administrator needs to include links |
| 105 | to additional CSS files.) The configurable part of the skin begins |
| 106 | with the Content Header section which should follow this template: |
| 107 | |
| 108 | <div class="header"> |
| 109 | ... top banner and menu bar ... |
| 110 | </div> |
| 111 | |
| 112 | Note that `<div class="header">` and `</div>` tags must be included in |
| 113 | the Content Header text of the skin. In other words, you, the |
| 114 | administrator, need to supply that text as part of your skin |
| 115 | customization. |
| 116 | |
| 117 | The Fossil-generated Content section immediately follows the Content Header. |
| 118 | The Content section will looks like this: |
| 119 | |
| 120 | <div class="content"> |
| 121 | ... Fossil-generated content here ... |
| 122 | </div> |
| 123 | |
| 124 | After the Content is the custom Content Footer section which should |
| 125 | follow this template: |
| 126 | |
| 127 | <div class="footer"> |
| 128 | ... skin-specific stuff here ... |
| 129 | </div> |
| 130 | |
| 131 | As with the Content Header, the template elements of the Content Footer |
| 132 | should appear exactly as they are shown. |
| 133 | |
| 134 | Finally, Fossil always adds its own footer (unless overridden) |
| 135 | to close out the generated HTML: |
| 136 | |
| 137 | </body> |
| 138 | </html> |
| 139 | |
| 140 | ## <a id="mainmenu"></a>Changing the Main Menu Contents |
| 141 | |
| 142 | As of Fossil 2.15, the actual text content of the skin’s main menu is no |
| 143 | longer part of the skin proper if you’re using one of the stock skins. |
| @@ -179,11 +174,11 @@ | |
| 179 | make incremental modifications, testing after each step, to obtain the |
| 180 | desired result. |
| 181 | |
| 182 | The skin is controlled by five files: |
| 183 | |
| 184 | <blockquote><dl> |
| 185 | <dt><b>css.txt</b></dt> |
| 186 | |
| 187 | <dd>The css.txt file is the text of the CSS for Fossil. |
| 188 | Fossil might add additional CSS elements after |
| 189 | the css.txt file, if it sees that the css.txt omits some |
| @@ -194,20 +189,20 @@ | |
| 194 | |
| 195 | <dd>The details.txt file is short list of settings that control |
| 196 | the look and feel, mostly of the timeline. The default |
| 197 | details.txt file looks like this: |
| 198 | |
| 199 | <blockquote><pre> |
| 200 | pikchr-background: "" |
| 201 | pikchr-fontscale: "" |
| 202 | pikchr-foreground: "" |
| 203 | pikchr-scale: "" |
| 204 | timeline-arrowheads: 1 |
| 205 | timeline-circle-nodes: 1 |
| 206 | timeline-color-graph-lines: 1 |
| 207 | white-foreground: 0 |
| 208 | </pre></blockquote> |
| 209 | |
| 210 | The three "timeline-" settings in details.txt control the appearance |
| 211 | of certain aspects of the timeline graph. The number on the |
| 212 | right is a boolean - "1" to activate the feature and "0" to |
| 213 | disable it. The "white-foreground:" setting should be set to |
| @@ -242,26 +237,26 @@ | |
| 242 | <dd>The js.txt file is optional. It is intended to be javascript. |
| 243 | The complete text of this javascript might be inserted into |
| 244 | the Content Footer, after being processed using TH1, using |
| 245 | code like the following in the "footer.txt" file: |
| 246 | |
| 247 | <blockquote><pre> |
| 248 | <script nonce="$nonce"> |
| 249 | <th1>styleScript</th1> |
| 250 | </script> |
| 251 | </pre></blockquote> |
| 252 | |
| 253 | The js.txt file was originally used to insert javascript |
| 254 | that controls the hamburger menu in the default skin. More |
| 255 | recently, the javascript for the hamburger menu was moved into |
| 256 | a separate built-in file. Skins that use the hamburger menu |
| 257 | typically cause the javascript to be loaded by including the |
| 258 | following TH1 code in the "header.txt" file: |
| 259 | |
| 260 | <blockquote><pre> |
| 261 | <th1>builtin_request_js hbmenu.js</th1> |
| 262 | </pre></blockquote> |
| 263 | |
| 264 | The difference between styleScript and builtin_request_js |
| 265 | is that the styleScript command interprets the file |
| 266 | using TH1 and injects the content directly into the output |
| 267 | stream, whereas the builtin_request_js command inserts the |
| @@ -274,11 +269,11 @@ | |
| 274 | |
| 275 | Note that the "js.txt" file is *not* automatically inserted into |
| 276 | the generate HTML for a page. You, the skin designer, must |
| 277 | cause the javascript to be inserted by issuing appropriate |
| 278 | TH1 commands in the "header.txt" or "footer.txt" files.</dd> |
| 279 | </dl></blockquote> |
| 280 | |
| 281 | Developing a new skin is simply a matter of creating appropriate |
| 282 | versions of these five control files. |
| 283 | |
| 284 | ### Skin Development Using The Web Interface |
| @@ -334,17 +329,17 @@ | |
| 334 | the value of the TH1 variable NAME. |
| 335 | |
| 336 | For example, first few lines of a typical Content Header will look |
| 337 | like this: |
| 338 | |
| 339 | <div class="header"> |
| 340 | <div class="title"><h1>$<project_name></h1>$<title>/div> |
| 341 | |
| 342 | After variables are substituted by TH1, that will look more like this: |
| 343 | |
| 344 | <div class="header"> |
| 345 | <div class="title"><h1>Project Name</h1>Page Title</div> |
| 346 | |
| 347 | As you can see, two TH1 variable substitutions were done. |
| 348 | |
| 349 | The same TH1 interpreter is used for both the header and the footer |
| 350 | and for all scripts contained within them both. Hence, any global |
| @@ -360,12 +355,12 @@ | |
| 360 | that are part of Fossil. |
| 361 | |
| 362 | The ≡ button for the hamburger menu is added to the menu bar by the following |
| 363 | TH1 commands in the `header.txt` file, right before the menu bar links: |
| 364 | |
| 365 | html "<a id='hbbtn' href='$home/sitemap'>☰</a>" |
| 366 | builtin_request_js hbmenu.js |
| 367 | |
| 368 | The hamburger button can be repositioned between the other menu links (but the |
| 369 | drop-down menu is always left-aligned with the menu bar), or it can be removed |
| 370 | by deleting the above statements. The "html" statement inserts the appropriate |
| 371 | `<a>` for the hamburger menu button (some skins require something slightly |
| @@ -375,40 +370,40 @@ | |
| 375 | |
| 376 | The hbmenu.js script requires |
| 377 | the following `<div>` element somewhere in your header, in which to build |
| 378 | the hamburger menu. |
| 379 | |
| 380 | <div id='hbdrop'></div> |
| 381 | |
| 382 | Out of the box, the contents of the panel is populated with the [Site |
| 383 | Map](/sitemap), but only if the panel does not already contain any HTML |
| 384 | elements (that is, not just comments, plain text or non-presentational white |
| 385 | space). So the hamburger menu can be customized by replacing the empty `<div |
| 386 | id='hbdrop'></div>` element with a menu structure knitted according to the |
| 387 | following template: |
| 388 | |
| 389 | <div id="hbdrop" data-anim-ms="400"> |
| 390 | <ul class="columns" style="column-width: 20em; column-count: auto"> |
| 391 | <!-- NEW GROUP WITH HEADING LINK --> |
| 392 | <li> |
| 393 | <a href="$home$index_page">Link: Home</a> |
| 394 | <ul> |
| 395 | <li><a href="$home/timeline">Link: Timeline</a></li> |
| 396 | <li><a href="$home/dir?ci=tip">Link: File List</a></li> |
| 397 | </ul> |
| 398 | </li> |
| 399 | <!-- NEW GROUP WITH HEADING TEXT --> |
| 400 | <li> |
| 401 | Heading Text |
| 402 | <ul> |
| 403 | <li><a href="$home/doc/trunk/www/customskin.md">Link: Theming</a></li> |
| 404 | <li><a href="$home/doc/trunk/www/th1.md">Link: TH1 Scripts</a></li> |
| 405 | </ul> |
| 406 | </li> |
| 407 | <!-- NEXT GROUP GOES HERE --> |
| 408 | </ul> |
| 409 | </div> |
| 410 | |
| 411 | The custom `data-anim-ms` attribute can be added to the panel element to direct |
| 412 | the Javascript logic to override the default menu animation duration of 400 ms. |
| 413 | A faster animation duration of 80-200 ms may be preferred for smaller menus. The |
| 414 | animation is disabled by setting the attribute to `"0"`. |
| 415 |
| --- www/customskin.md | |
| +++ www/customskin.md | |
| @@ -57,87 +57,82 @@ | |
| 57 | |
| 58 | # Structure Of A Fossil Web Page |
| 59 | |
| 60 | Every HTML page generated by Fossil has the same basic structure: |
| 61 | |
| 62 | | Fossil-Generated HTML Header | |
| 63 | | Content Header | |
| 64 | | Fossil-Generated Content | |
| 65 | | Content Footer | |
| 66 | | Fossil-Generated HTML Footer | |
| 67 | |
| 68 | The green parts are *usually* generated by Fossil. The blue parts |
| 69 | are things that you, the administrator, get to modify in order to |
| 70 | customize the skin. |
| 71 | |
| 72 | Fossil *usually* (but not always - [see below](#override)) |
| 73 | generates the initial HTML Header section of a page. The |
| 74 | generated HTML Header will look something like this: |
| 75 | |
| 76 | <html> |
| 77 | <head> |
| 78 | <base href="..."> |
| 79 | <meta http-equiv="Content-Security-Policy" content="...."> |
| 80 | <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| 81 | <title>....</title> |
| 82 | <link rel="stylesheet" href="..." type="text/css"> |
| 83 | </head> |
| 84 | <body class="FEATURE"> |
| 85 | |
| 86 | …where `FEATURE` is either the top-level URL element (e.g. `doc`) or a |
| 87 | feature class that groups multiple URLs under a single name such as |
| 88 | `forum` to contain `/forummain`, `/forumpost`, `/forume2`, etc. This |
| 89 | allows per-feature CSS such as |
| 90 | |
| 91 | body.forum div.markdown blockquote { |
| 92 | margin-left: 10px; |
| 93 | } |
| 94 | |
| 95 | That is, affect HTML `<blockquote>` tags specially only for forum posts |
| 96 | written in Markdown, leaving all other block quotes alone. |
| 97 | |
| 98 | In most cases, it is best to leave the Fossil-generated HTML Header |
| 99 | alone. (One exception is when the administrator needs to include links |
| 100 | to additional CSS files.) The configurable part of the skin begins |
| 101 | with the Content Header section which should follow this template: |
| 102 | |
| 103 | <div class="header"> |
| 104 | ... top banner and menu bar ... |
| 105 | </div> |
| 106 | |
| 107 | Note that `<div class="header">` and `</div>` tags must be included in |
| 108 | the Content Header text of the skin. In other words, you, the |
| 109 | administrator, need to supply that text as part of your skin |
| 110 | customization. |
| 111 | |
| 112 | The Fossil-generated Content section immediately follows the Content Header. |
| 113 | The Content section will looks like this: |
| 114 | |
| 115 | <div class="content"> |
| 116 | ... Fossil-generated content here ... |
| 117 | </div> |
| 118 | |
| 119 | After the Content is the custom Content Footer section which should |
| 120 | follow this template: |
| 121 | |
| 122 | <div class="footer"> |
| 123 | ... skin-specific stuff here ... |
| 124 | </div> |
| 125 | |
| 126 | As with the Content Header, the template elements of the Content Footer |
| 127 | should appear exactly as they are shown. |
| 128 | |
| 129 | Finally, Fossil always adds its own footer (unless overridden) |
| 130 | to close out the generated HTML: |
| 131 | |
| 132 | </body> |
| 133 | </html> |
| 134 | |
| 135 | ## <a id="mainmenu"></a>Changing the Main Menu Contents |
| 136 | |
| 137 | As of Fossil 2.15, the actual text content of the skin’s main menu is no |
| 138 | longer part of the skin proper if you’re using one of the stock skins. |
| @@ -179,11 +174,11 @@ | |
| 174 | make incremental modifications, testing after each step, to obtain the |
| 175 | desired result. |
| 176 | |
| 177 | The skin is controlled by five files: |
| 178 | |
| 179 | <dl> |
| 180 | <dt><b>css.txt</b></dt> |
| 181 | |
| 182 | <dd>The css.txt file is the text of the CSS for Fossil. |
| 183 | Fossil might add additional CSS elements after |
| 184 | the css.txt file, if it sees that the css.txt omits some |
| @@ -194,20 +189,20 @@ | |
| 189 | |
| 190 | <dd>The details.txt file is short list of settings that control |
| 191 | the look and feel, mostly of the timeline. The default |
| 192 | details.txt file looks like this: |
| 193 | |
| 194 | <pre> |
| 195 | pikchr-background: "" |
| 196 | pikchr-fontscale: "" |
| 197 | pikchr-foreground: "" |
| 198 | pikchr-scale: "" |
| 199 | timeline-arrowheads: 1 |
| 200 | timeline-circle-nodes: 1 |
| 201 | timeline-color-graph-lines: 1 |
| 202 | white-foreground: 0 |
| 203 | </pre> |
| 204 | |
| 205 | The three "timeline-" settings in details.txt control the appearance |
| 206 | of certain aspects of the timeline graph. The number on the |
| 207 | right is a boolean - "1" to activate the feature and "0" to |
| 208 | disable it. The "white-foreground:" setting should be set to |
| @@ -242,26 +237,26 @@ | |
| 237 | <dd>The js.txt file is optional. It is intended to be javascript. |
| 238 | The complete text of this javascript might be inserted into |
| 239 | the Content Footer, after being processed using TH1, using |
| 240 | code like the following in the "footer.txt" file: |
| 241 | |
| 242 | <pre> |
| 243 | <script nonce="$nonce"> |
| 244 | <th1>styleScript</th1> |
| 245 | </script> |
| 246 | </pre> |
| 247 | |
| 248 | The js.txt file was originally used to insert javascript |
| 249 | that controls the hamburger menu in the default skin. More |
| 250 | recently, the javascript for the hamburger menu was moved into |
| 251 | a separate built-in file. Skins that use the hamburger menu |
| 252 | typically cause the javascript to be loaded by including the |
| 253 | following TH1 code in the "header.txt" file: |
| 254 | |
| 255 | <pre> |
| 256 | <th1>builtin_request_js hbmenu.js</th1> |
| 257 | </pre> |
| 258 | |
| 259 | The difference between styleScript and builtin_request_js |
| 260 | is that the styleScript command interprets the file |
| 261 | using TH1 and injects the content directly into the output |
| 262 | stream, whereas the builtin_request_js command inserts the |
| @@ -274,11 +269,11 @@ | |
| 269 | |
| 270 | Note that the "js.txt" file is *not* automatically inserted into |
| 271 | the generate HTML for a page. You, the skin designer, must |
| 272 | cause the javascript to be inserted by issuing appropriate |
| 273 | TH1 commands in the "header.txt" or "footer.txt" files.</dd> |
| 274 | </dl> |
| 275 | |
| 276 | Developing a new skin is simply a matter of creating appropriate |
| 277 | versions of these five control files. |
| 278 | |
| 279 | ### Skin Development Using The Web Interface |
| @@ -334,17 +329,17 @@ | |
| 329 | the value of the TH1 variable NAME. |
| 330 | |
| 331 | For example, first few lines of a typical Content Header will look |
| 332 | like this: |
| 333 | |
| 334 | <div class="header"> |
| 335 | <div class="title"><h1>$<project_name></h1>$<title>/div> |
| 336 | |
| 337 | After variables are substituted by TH1, that will look more like this: |
| 338 | |
| 339 | <div class="header"> |
| 340 | <div class="title"><h1>Project Name</h1>Page Title</div> |
| 341 | |
| 342 | As you can see, two TH1 variable substitutions were done. |
| 343 | |
| 344 | The same TH1 interpreter is used for both the header and the footer |
| 345 | and for all scripts contained within them both. Hence, any global |
| @@ -360,12 +355,12 @@ | |
| 355 | that are part of Fossil. |
| 356 | |
| 357 | The ≡ button for the hamburger menu is added to the menu bar by the following |
| 358 | TH1 commands in the `header.txt` file, right before the menu bar links: |
| 359 | |
| 360 | html "<a id='hbbtn' href='$home/sitemap'>☰</a>" |
| 361 | builtin_request_js hbmenu.js |
| 362 | |
| 363 | The hamburger button can be repositioned between the other menu links (but the |
| 364 | drop-down menu is always left-aligned with the menu bar), or it can be removed |
| 365 | by deleting the above statements. The "html" statement inserts the appropriate |
| 366 | `<a>` for the hamburger menu button (some skins require something slightly |
| @@ -375,40 +370,40 @@ | |
| 370 | |
| 371 | The hbmenu.js script requires |
| 372 | the following `<div>` element somewhere in your header, in which to build |
| 373 | the hamburger menu. |
| 374 | |
| 375 | <div id='hbdrop'></div> |
| 376 | |
| 377 | Out of the box, the contents of the panel is populated with the [Site |
| 378 | Map](/sitemap), but only if the panel does not already contain any HTML |
| 379 | elements (that is, not just comments, plain text or non-presentational white |
| 380 | space). So the hamburger menu can be customized by replacing the empty `<div |
| 381 | id='hbdrop'></div>` element with a menu structure knitted according to the |
| 382 | following template: |
| 383 | |
| 384 | <div id="hbdrop" data-anim-ms="400"> |
| 385 | <ul class="columns" style="column-width: 20em; column-count: auto"> |
| 386 | <!-- NEW GROUP WITH HEADING LINK --> |
| 387 | <li> |
| 388 | <a href="$home$index_page">Link: Home</a> |
| 389 | <ul> |
| 390 | <li><a href="$home/timeline">Link: Timeline</a></li> |
| 391 | <li><a href="$home/dir?ci=tip">Link: File List</a></li> |
| 392 | </ul> |
| 393 | </li> |
| 394 | <!-- NEW GROUP WITH HEADING TEXT --> |
| 395 | <li> |
| 396 | Heading Text |
| 397 | <ul> |
| 398 | <li><a href="$home/doc/trunk/www/customskin.md">Link: Theming</a></li> |
| 399 | <li><a href="$home/doc/trunk/www/th1.md">Link: TH1 Scripts</a></li> |
| 400 | </ul> |
| 401 | </li> |
| 402 | <!-- NEXT GROUP GOES HERE --> |
| 403 | </ul> |
| 404 | </div> |
| 405 | |
| 406 | The custom `data-anim-ms` attribute can be added to the panel element to direct |
| 407 | the Javascript logic to override the default menu animation duration of 400 ms. |
| 408 | A faster animation duration of 80-200 ms may be preferred for smaller menus. The |
| 409 | animation is disabled by setting the attribute to `"0"`. |
| 410 |
+13
-15
| --- www/defcsp.md | ||
| +++ www/defcsp.md | ||
| @@ -23,43 +23,41 @@ | ||
| 23 | 23 | ## The Default Restrictions |
| 24 | 24 | |
| 25 | 25 | The default CSP used by Fossil is as follows: |
| 26 | 26 | |
| 27 | 27 | <pre> |
| 28 | - default-src 'self' data:; | |
| 29 | - script-src 'self' 'nonce-$nonce'; | |
| 30 | - style-src 'self' 'unsafe-inline'; | |
| 31 | - img-src * data:; | |
| 28 | +default-src 'self' data:; | |
| 29 | +script-src 'self' 'nonce-$nonce'; | |
| 30 | +style-src 'self' 'unsafe-inline'; | |
| 31 | +img-src * data:; | |
| 32 | 32 | </pre> |
| 33 | 33 | |
| 34 | 34 | The default is recommended for most installations. However, |
| 35 | 35 | the site administrators can overwrite this default CSP using the |
| 36 | 36 | [default-csp setting](/help?cmd=default-csp). For example, |
| 37 | 37 | CSP restrictions can be completely disabled by setting the default-csp to: |
| 38 | 38 | |
| 39 | -<pre> | |
| 40 | - default-src *; | |
| 41 | -</pre> | |
| 39 | + default-src *; | |
| 42 | 40 | |
| 43 | 41 | The following sections detail the maining of the default CSP setting. |
| 44 | 42 | |
| 45 | 43 | ### <a id="base"></a> default-src 'self' data: |
| 46 | 44 | |
| 47 | 45 | This policy means mixed-origin content isn’t allowed, so you can’t refer |
| 48 | 46 | to resources on other web domains. Browsers will ignore a link like the |
| 49 | 47 | one in the following Markdown under our default CSP: |
| 50 | 48 | |
| 51 | -  | |
| 49 | +  | |
| 52 | 50 | |
| 53 | 51 | If you look in the browser’s developer console, you should see a CSP |
| 54 | 52 | error when attempting to render such a page. |
| 55 | 53 | |
| 56 | 54 | The default policy does allow inline `data:` URIs, which means you could |
| 57 | 55 | [data-encode][de] your image content and put it inline within the |
| 58 | 56 | document: |
| 59 | 57 | |
| 60 | -  | |
| 58 | +  | |
| 61 | 59 | |
| 62 | 60 | That method is best used for fairly small resources. Large `data:` URIs |
| 63 | 61 | are hard to read and edit. There are secondary problems as well: if you |
| 64 | 62 | put a large image into a Fossil forum post this way, anyone subscribed |
| 65 | 63 | to email alerts will get a copy of the raw URI text, which can amount to |
| @@ -67,11 +65,11 @@ | ||
| 67 | 65 | |
| 68 | 66 | For inline images within [embedded documentation][ed], it suffices to |
| 69 | 67 | store the referred-to files in the repo and then refer to them using |
| 70 | 68 | repo-relative URLs: |
| 71 | 69 | |
| 72 | -  | |
| 70 | +  | |
| 73 | 71 | |
| 74 | 72 | This avoids bloating the doc text with `data:` URI blobs: |
| 75 | 73 | |
| 76 | 74 | There are many other cases, [covered below](#serving). |
| 77 | 75 | |
| @@ -99,11 +97,11 @@ | ||
| 99 | 97 | `<style>` tags within the document text. |
| 100 | 98 | |
| 101 | 99 | The `'unsafe-inline'` declaration allows CSS within individual HTML |
| 102 | 100 | elements: |
| 103 | 101 | |
| 104 | - <p style="margin-left: 4em">Indented text.</p> | |
| 102 | + <p style="margin-left: 4em">Indented text.</p> | |
| 105 | 103 | |
| 106 | 104 | As the "`unsafe-`" prefix on the name implies, the `'unsafe-inline'` |
| 107 | 105 | feature is suboptimal for security. However, there are |
| 108 | 106 | a few places in the Fossil-generated HTML that benefit from this |
| 109 | 107 | flexibility and the work-arounds are verbose and difficult to maintain. |
| @@ -174,11 +172,11 @@ | ||
| 174 | 172 | scheme. Any one of those hundreds of repositories could trick you into |
| 175 | 173 | visiting their repository home page, set to [an HTML-formatted embedded |
| 176 | 174 | doc page][hfed] via Admin → Configuration → Index Page, with this |
| 177 | 175 | content: |
| 178 | 176 | |
| 179 | - <script src="/doc/trunk/bad.js"></script> | |
| 177 | + <script src="/doc/trunk/bad.js"></script> | |
| 180 | 178 | |
| 181 | 179 | That script can then do anything allowed in JavaScript to *any other* |
| 182 | 180 | Chisel repository your browser can access. The possibilities for mischief |
| 183 | 181 | are *vast*. For just one example, if you have login cookies on four |
| 184 | 182 | different Chisel repositories, your attacker could harvest the login |
| @@ -198,11 +196,11 @@ | ||
| 198 | 196 | willingly run any JavaScript code they’ve provided, blind, you **must |
| 199 | 197 | not** give the `--with-th1-docs` option when configuring Fossil, because |
| 200 | 198 | that allows substitution of the [pre-defined `$nonce` TH1 |
| 201 | 199 | variable](./th1.md#nonce) into [HTML-formatted embedded docs][hfed]: |
| 202 | 200 | |
| 203 | - <script src="/doc/trunk/bad.js" nonce="$nonce"></script> | |
| 201 | + <script src="/doc/trunk/bad.js" nonce="$nonce"></script> | |
| 204 | 202 | |
| 205 | 203 | Even with this feature enabled, you cannot put `<script>` tags into |
| 206 | 204 | Fossil Wiki or Markdown-formatted content, because our HTML generators |
| 207 | 205 | for those formats purposely strip or disable such tags in the output. |
| 208 | 206 | Therefore, if you trust those users with check-in rights to provide |
| @@ -331,11 +329,11 @@ | ||
| 331 | 329 | |
| 332 | 330 | Because a blank setting tells Fossil to use its hard-coded default CSP, |
| 333 | 331 | you have to say something like the following to get a repository without |
| 334 | 332 | content security policy restrictions: |
| 335 | 333 | |
| 336 | - $ fossil set -R /path/to/served/repo.fossil default-csp 'default-src *' | |
| 334 | + $ fossil set -R /path/to/served/repo.fossil default-csp 'default-src *' | |
| 337 | 335 | |
| 338 | 336 | We recommend that instead of using the command line to change this |
| 339 | 337 | setting that you do it via the repository’s web interface, in |
| 340 | 338 | Admin → Settings. Write your CSP rules in the edit box marked |
| 341 | 339 | "`default-csp`". Do not add hard newlines in that box: the setting needs |
| @@ -366,11 +364,11 @@ | ||
| 366 | 364 | |
| 367 | 365 | This means that another way you can override this value is to use |
| 368 | 366 | the [`th1-setup` hook script](./th1-hooks.md), which runs before TH1 |
| 369 | 367 | processing happens during skin processing: |
| 370 | 368 | |
| 371 | - $ fossil set th1-setup "set default_csp {default-src 'self'}" | |
| 369 | + $ fossil set th1-setup "set default_csp {default-src 'self'}" | |
| 372 | 370 | |
| 373 | 371 | After [the above](#admin-ui), this is the cleanest method. |
| 374 | 372 | |
| 375 | 373 | [thvar]: ./customskin.md#vars |
| 376 | 374 | |
| 377 | 375 |
| --- www/defcsp.md | |
| +++ www/defcsp.md | |
| @@ -23,43 +23,41 @@ | |
| 23 | ## The Default Restrictions |
| 24 | |
| 25 | The default CSP used by Fossil is as follows: |
| 26 | |
| 27 | <pre> |
| 28 | default-src 'self' data:; |
| 29 | script-src 'self' 'nonce-$nonce'; |
| 30 | style-src 'self' 'unsafe-inline'; |
| 31 | img-src * data:; |
| 32 | </pre> |
| 33 | |
| 34 | The default is recommended for most installations. However, |
| 35 | the site administrators can overwrite this default CSP using the |
| 36 | [default-csp setting](/help?cmd=default-csp). For example, |
| 37 | CSP restrictions can be completely disabled by setting the default-csp to: |
| 38 | |
| 39 | <pre> |
| 40 | default-src *; |
| 41 | </pre> |
| 42 | |
| 43 | The following sections detail the maining of the default CSP setting. |
| 44 | |
| 45 | ### <a id="base"></a> default-src 'self' data: |
| 46 | |
| 47 | This policy means mixed-origin content isn’t allowed, so you can’t refer |
| 48 | to resources on other web domains. Browsers will ignore a link like the |
| 49 | one in the following Markdown under our default CSP: |
| 50 | |
| 51 |  |
| 52 | |
| 53 | If you look in the browser’s developer console, you should see a CSP |
| 54 | error when attempting to render such a page. |
| 55 | |
| 56 | The default policy does allow inline `data:` URIs, which means you could |
| 57 | [data-encode][de] your image content and put it inline within the |
| 58 | document: |
| 59 | |
| 60 |  |
| 61 | |
| 62 | That method is best used for fairly small resources. Large `data:` URIs |
| 63 | are hard to read and edit. There are secondary problems as well: if you |
| 64 | put a large image into a Fossil forum post this way, anyone subscribed |
| 65 | to email alerts will get a copy of the raw URI text, which can amount to |
| @@ -67,11 +65,11 @@ | |
| 67 | |
| 68 | For inline images within [embedded documentation][ed], it suffices to |
| 69 | store the referred-to files in the repo and then refer to them using |
| 70 | repo-relative URLs: |
| 71 | |
| 72 |  |
| 73 | |
| 74 | This avoids bloating the doc text with `data:` URI blobs: |
| 75 | |
| 76 | There are many other cases, [covered below](#serving). |
| 77 | |
| @@ -99,11 +97,11 @@ | |
| 99 | `<style>` tags within the document text. |
| 100 | |
| 101 | The `'unsafe-inline'` declaration allows CSS within individual HTML |
| 102 | elements: |
| 103 | |
| 104 | <p style="margin-left: 4em">Indented text.</p> |
| 105 | |
| 106 | As the "`unsafe-`" prefix on the name implies, the `'unsafe-inline'` |
| 107 | feature is suboptimal for security. However, there are |
| 108 | a few places in the Fossil-generated HTML that benefit from this |
| 109 | flexibility and the work-arounds are verbose and difficult to maintain. |
| @@ -174,11 +172,11 @@ | |
| 174 | scheme. Any one of those hundreds of repositories could trick you into |
| 175 | visiting their repository home page, set to [an HTML-formatted embedded |
| 176 | doc page][hfed] via Admin → Configuration → Index Page, with this |
| 177 | content: |
| 178 | |
| 179 | <script src="/doc/trunk/bad.js"></script> |
| 180 | |
| 181 | That script can then do anything allowed in JavaScript to *any other* |
| 182 | Chisel repository your browser can access. The possibilities for mischief |
| 183 | are *vast*. For just one example, if you have login cookies on four |
| 184 | different Chisel repositories, your attacker could harvest the login |
| @@ -198,11 +196,11 @@ | |
| 198 | willingly run any JavaScript code they’ve provided, blind, you **must |
| 199 | not** give the `--with-th1-docs` option when configuring Fossil, because |
| 200 | that allows substitution of the [pre-defined `$nonce` TH1 |
| 201 | variable](./th1.md#nonce) into [HTML-formatted embedded docs][hfed]: |
| 202 | |
| 203 | <script src="/doc/trunk/bad.js" nonce="$nonce"></script> |
| 204 | |
| 205 | Even with this feature enabled, you cannot put `<script>` tags into |
| 206 | Fossil Wiki or Markdown-formatted content, because our HTML generators |
| 207 | for those formats purposely strip or disable such tags in the output. |
| 208 | Therefore, if you trust those users with check-in rights to provide |
| @@ -331,11 +329,11 @@ | |
| 331 | |
| 332 | Because a blank setting tells Fossil to use its hard-coded default CSP, |
| 333 | you have to say something like the following to get a repository without |
| 334 | content security policy restrictions: |
| 335 | |
| 336 | $ fossil set -R /path/to/served/repo.fossil default-csp 'default-src *' |
| 337 | |
| 338 | We recommend that instead of using the command line to change this |
| 339 | setting that you do it via the repository’s web interface, in |
| 340 | Admin → Settings. Write your CSP rules in the edit box marked |
| 341 | "`default-csp`". Do not add hard newlines in that box: the setting needs |
| @@ -366,11 +364,11 @@ | |
| 366 | |
| 367 | This means that another way you can override this value is to use |
| 368 | the [`th1-setup` hook script](./th1-hooks.md), which runs before TH1 |
| 369 | processing happens during skin processing: |
| 370 | |
| 371 | $ fossil set th1-setup "set default_csp {default-src 'self'}" |
| 372 | |
| 373 | After [the above](#admin-ui), this is the cleanest method. |
| 374 | |
| 375 | [thvar]: ./customskin.md#vars |
| 376 | |
| 377 |
| --- www/defcsp.md | |
| +++ www/defcsp.md | |
| @@ -23,43 +23,41 @@ | |
| 23 | ## The Default Restrictions |
| 24 | |
| 25 | The default CSP used by Fossil is as follows: |
| 26 | |
| 27 | <pre> |
| 28 | default-src 'self' data:; |
| 29 | script-src 'self' 'nonce-$nonce'; |
| 30 | style-src 'self' 'unsafe-inline'; |
| 31 | img-src * data:; |
| 32 | </pre> |
| 33 | |
| 34 | The default is recommended for most installations. However, |
| 35 | the site administrators can overwrite this default CSP using the |
| 36 | [default-csp setting](/help?cmd=default-csp). For example, |
| 37 | CSP restrictions can be completely disabled by setting the default-csp to: |
| 38 | |
| 39 | default-src *; |
| 40 | |
| 41 | The following sections detail the maining of the default CSP setting. |
| 42 | |
| 43 | ### <a id="base"></a> default-src 'self' data: |
| 44 | |
| 45 | This policy means mixed-origin content isn’t allowed, so you can’t refer |
| 46 | to resources on other web domains. Browsers will ignore a link like the |
| 47 | one in the following Markdown under our default CSP: |
| 48 | |
| 49 |  |
| 50 | |
| 51 | If you look in the browser’s developer console, you should see a CSP |
| 52 | error when attempting to render such a page. |
| 53 | |
| 54 | The default policy does allow inline `data:` URIs, which means you could |
| 55 | [data-encode][de] your image content and put it inline within the |
| 56 | document: |
| 57 | |
| 58 |  |
| 59 | |
| 60 | That method is best used for fairly small resources. Large `data:` URIs |
| 61 | are hard to read and edit. There are secondary problems as well: if you |
| 62 | put a large image into a Fossil forum post this way, anyone subscribed |
| 63 | to email alerts will get a copy of the raw URI text, which can amount to |
| @@ -67,11 +65,11 @@ | |
| 65 | |
| 66 | For inline images within [embedded documentation][ed], it suffices to |
| 67 | store the referred-to files in the repo and then refer to them using |
| 68 | repo-relative URLs: |
| 69 | |
| 70 |  |
| 71 | |
| 72 | This avoids bloating the doc text with `data:` URI blobs: |
| 73 | |
| 74 | There are many other cases, [covered below](#serving). |
| 75 | |
| @@ -99,11 +97,11 @@ | |
| 97 | `<style>` tags within the document text. |
| 98 | |
| 99 | The `'unsafe-inline'` declaration allows CSS within individual HTML |
| 100 | elements: |
| 101 | |
| 102 | <p style="margin-left: 4em">Indented text.</p> |
| 103 | |
| 104 | As the "`unsafe-`" prefix on the name implies, the `'unsafe-inline'` |
| 105 | feature is suboptimal for security. However, there are |
| 106 | a few places in the Fossil-generated HTML that benefit from this |
| 107 | flexibility and the work-arounds are verbose and difficult to maintain. |
| @@ -174,11 +172,11 @@ | |
| 172 | scheme. Any one of those hundreds of repositories could trick you into |
| 173 | visiting their repository home page, set to [an HTML-formatted embedded |
| 174 | doc page][hfed] via Admin → Configuration → Index Page, with this |
| 175 | content: |
| 176 | |
| 177 | <script src="/doc/trunk/bad.js"></script> |
| 178 | |
| 179 | That script can then do anything allowed in JavaScript to *any other* |
| 180 | Chisel repository your browser can access. The possibilities for mischief |
| 181 | are *vast*. For just one example, if you have login cookies on four |
| 182 | different Chisel repositories, your attacker could harvest the login |
| @@ -198,11 +196,11 @@ | |
| 196 | willingly run any JavaScript code they’ve provided, blind, you **must |
| 197 | not** give the `--with-th1-docs` option when configuring Fossil, because |
| 198 | that allows substitution of the [pre-defined `$nonce` TH1 |
| 199 | variable](./th1.md#nonce) into [HTML-formatted embedded docs][hfed]: |
| 200 | |
| 201 | <script src="/doc/trunk/bad.js" nonce="$nonce"></script> |
| 202 | |
| 203 | Even with this feature enabled, you cannot put `<script>` tags into |
| 204 | Fossil Wiki or Markdown-formatted content, because our HTML generators |
| 205 | for those formats purposely strip or disable such tags in the output. |
| 206 | Therefore, if you trust those users with check-in rights to provide |
| @@ -331,11 +329,11 @@ | |
| 329 | |
| 330 | Because a blank setting tells Fossil to use its hard-coded default CSP, |
| 331 | you have to say something like the following to get a repository without |
| 332 | content security policy restrictions: |
| 333 | |
| 334 | $ fossil set -R /path/to/served/repo.fossil default-csp 'default-src *' |
| 335 | |
| 336 | We recommend that instead of using the command line to change this |
| 337 | setting that you do it via the repository’s web interface, in |
| 338 | Admin → Settings. Write your CSP rules in the edit box marked |
| 339 | "`default-csp`". Do not add hard newlines in that box: the setting needs |
| @@ -366,11 +364,11 @@ | |
| 364 | |
| 365 | This means that another way you can override this value is to use |
| 366 | the [`th1-setup` hook script](./th1-hooks.md), which runs before TH1 |
| 367 | processing happens during skin processing: |
| 368 | |
| 369 | $ fossil set th1-setup "set default_csp {default-src 'self'}" |
| 370 | |
| 371 | After [the above](#admin-ui), this is the cleanest method. |
| 372 | |
| 373 | [thvar]: ./customskin.md#vars |
| 374 | |
| 375 |
+4
-6
| --- www/delta-manifests.md | ||
| +++ www/delta-manifests.md | ||
| @@ -1,6 +1,10 @@ | ||
| 1 | 1 | # Delta Manifests |
| 2 | + | |
| 3 | +<div class="sidebar">Do not confuse these with the core [Fossil delta | |
| 4 | +format](./delta_format.wiki). This document describes an optional | |
| 5 | +feature not enabled by default.</div> | |
| 2 | 6 | |
| 3 | 7 | This article describes "delta manifests," a special-case form of |
| 4 | 8 | checkin manifest which is intended to take up far less space than |
| 5 | 9 | a normal checkin manifest, in particular for repositories with |
| 6 | 10 | many files. We'll see, however, that the space savings, if indeed |
| @@ -9,16 +13,10 @@ | ||
| 9 | 13 | This article assumes that the reader is at least moderately familiar |
| 10 | 14 | with Fossil's [artifact file format](./fileformat.wiki), in particular |
| 11 | 15 | the structure of checkin manifests, and it won't make much sense to |
| 12 | 16 | readers unfamiliar with that topic. |
| 13 | 17 | |
| 14 | -Sidebar: delta manifests are not to be confused with the core [Fossil | |
| 15 | -delta format](./delta_format.wiki). The former is a special-case form | |
| 16 | -of delta which applies *only* to checkin manifests whereas the latter | |
| 17 | -is a general-purpose delta compression which can apply to any | |
| 18 | -Fossil-stored data (including delta manifests). | |
| 19 | - | |
| 20 | 18 | # Background and Motivation of Delta Manifests |
| 21 | 19 | |
| 22 | 20 | A checkin manifest includes a list of every file in that checkin. A |
| 23 | 21 | moderately-sized project can easily have a thousand files, and every |
| 24 | 22 | checkin manifest will include those thousand files. As of this writing |
| 25 | 23 |
| --- www/delta-manifests.md | |
| +++ www/delta-manifests.md | |
| @@ -1,6 +1,10 @@ | |
| 1 | # Delta Manifests |
| 2 | |
| 3 | This article describes "delta manifests," a special-case form of |
| 4 | checkin manifest which is intended to take up far less space than |
| 5 | a normal checkin manifest, in particular for repositories with |
| 6 | many files. We'll see, however, that the space savings, if indeed |
| @@ -9,16 +13,10 @@ | |
| 9 | This article assumes that the reader is at least moderately familiar |
| 10 | with Fossil's [artifact file format](./fileformat.wiki), in particular |
| 11 | the structure of checkin manifests, and it won't make much sense to |
| 12 | readers unfamiliar with that topic. |
| 13 | |
| 14 | Sidebar: delta manifests are not to be confused with the core [Fossil |
| 15 | delta format](./delta_format.wiki). The former is a special-case form |
| 16 | of delta which applies *only* to checkin manifests whereas the latter |
| 17 | is a general-purpose delta compression which can apply to any |
| 18 | Fossil-stored data (including delta manifests). |
| 19 | |
| 20 | # Background and Motivation of Delta Manifests |
| 21 | |
| 22 | A checkin manifest includes a list of every file in that checkin. A |
| 23 | moderately-sized project can easily have a thousand files, and every |
| 24 | checkin manifest will include those thousand files. As of this writing |
| 25 |
| --- www/delta-manifests.md | |
| +++ www/delta-manifests.md | |
| @@ -1,6 +1,10 @@ | |
| 1 | # Delta Manifests |
| 2 | |
| 3 | <div class="sidebar">Do not confuse these with the core [Fossil delta |
| 4 | format](./delta_format.wiki). This document describes an optional |
| 5 | feature not enabled by default.</div> |
| 6 | |
| 7 | This article describes "delta manifests," a special-case form of |
| 8 | checkin manifest which is intended to take up far less space than |
| 9 | a normal checkin manifest, in particular for repositories with |
| 10 | many files. We'll see, however, that the space savings, if indeed |
| @@ -9,16 +13,10 @@ | |
| 13 | This article assumes that the reader is at least moderately familiar |
| 14 | with Fossil's [artifact file format](./fileformat.wiki), in particular |
| 15 | the structure of checkin manifests, and it won't make much sense to |
| 16 | readers unfamiliar with that topic. |
| 17 | |
| 18 | # Background and Motivation of Delta Manifests |
| 19 | |
| 20 | A checkin manifest includes a list of every file in that checkin. A |
| 21 | moderately-sized project can easily have a thousand files, and every |
| 22 | checkin manifest will include those thousand files. As of this writing |
| 23 |
+8
-9
| --- www/delta_format.wiki | ||
| +++ www/delta_format.wiki | ||
| @@ -190,13 +190,13 @@ | ||
| 190 | 190 | "0"-characters, except if they are significant (i.e. 0 => "0"). |
| 191 | 191 | |
| 192 | 192 | The base-64 encoding uses one character for each 6 bits of |
| 193 | 193 | the integer to be encoded. The encoding characters are: |
| 194 | 194 | |
| 195 | -<blockquote><pre> | |
| 195 | +<pre> | |
| 196 | 196 | 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz~ |
| 197 | -</pre></blockquote> | |
| 197 | +</pre> | |
| 198 | 198 | |
| 199 | 199 | The least significant 6 bits of the integer are encoded by |
| 200 | 200 | the first character, followed by |
| 201 | 201 | the next 6 bits, and so on until all non-zero bits of the integer |
| 202 | 202 | are encoded. The minimum number of encoding characters is used. |
| @@ -205,11 +205,11 @@ | ||
| 205 | 205 | |
| 206 | 206 | <h1 id="examples">4.0 Examples</h1> |
| 207 | 207 | |
| 208 | 208 | <h2 id="examplesint">4.1 Integer encoding</h2> |
| 209 | 209 | |
| 210 | -<table border=1> | |
| 210 | +<table> | |
| 211 | 211 | <tr> |
| 212 | 212 | <th>Value</th> |
| 213 | 213 | <th>Encoding</th> |
| 214 | 214 | </tr> |
| 215 | 215 | <tr> |
| @@ -228,18 +228,18 @@ | ||
| 228 | 228 | |
| 229 | 229 | <h2 id="examplesdelta">4.2 Delta encoding</h2> |
| 230 | 230 | |
| 231 | 231 | An example of a delta using the specified encoding is: |
| 232 | 232 | |
| 233 | -<table border=1><tr><td><pre> | |
| 233 | +<pre> | |
| 234 | 234 | 1Xb |
| 235 | 235 | 4E@0,2:thFN@4C,6:scenda1B@Jd,6:scenda5x@Kt,6:pieces79@Qt,F: Example: eskil~E@Y0,2zMM3E;</pre> |
| 236 | -</td></tr></table> | |
| 236 | +</pre> | |
| 237 | 237 | |
| 238 | 238 | This can be taken apart into the following parts: |
| 239 | 239 | |
| 240 | -<table border=1> | |
| 240 | +<table> | |
| 241 | 241 | <tr><th>What </th> <th>Encoding </th><th>Meaning </th><th>Details</th></tr> |
| 242 | 242 | <tr><td>Header</td> <td>1Xb </td><td>Size </td><td> 6246 </td></tr> |
| 243 | 243 | <tr><td>S-List</td> <td>4E@0, </td><td>Copy </td><td> 270 @ 0 </td></tr> |
| 244 | 244 | <tr><td> </td> <td>2:th </td><td>Literal </td><td> 2 'th' </td></tr> |
| 245 | 245 | <tr><td> </td> <td>FN@4C, </td><td>Copy </td><td> 983 @ 268 </td></tr> |
| @@ -254,11 +254,11 @@ | ||
| 254 | 254 | <tr><td>Trailer</td><td>2zMM3E </td><td>Checksum</td><td> -1101438770 </td></tr> |
| 255 | 255 | </table> |
| 256 | 256 | |
| 257 | 257 | The unified diff behind the above delta is |
| 258 | 258 | |
| 259 | -<table border=1><tr><td><pre> | |
| 259 | +<verbatim> | |
| 260 | 260 | bluepeak:(761) ~/Projects/Tcl/Fossil/Devel/devel > diff -u ../DELTA/old ../DELTA/new |
| 261 | 261 | --- ../DELTA/old 2007-08-23 21:14:40.000000000 -0700 |
| 262 | 262 | +++ ../DELTA/new 2007-08-23 21:14:33.000000000 -0700 |
| 263 | 263 | @@ -5,7 +5,7 @@ |
| 264 | 264 | |
| @@ -295,12 +295,11 @@ | ||
| 295 | 295 | configuration options to replace tkdiff with some other |
| 296 | 296 | - visual differ of the users choice. |
| 297 | 297 | + visual differ of the users choice. Example: eskil. |
| 298 | 298 | |
| 299 | 299 | * Ticketing interface (expand this bullet) |
| 300 | - | |
| 301 | -</pre></td></tr></table> | |
| 300 | +</verbatim> | |
| 302 | 301 | |
| 303 | 302 | |
| 304 | 303 | |
| 305 | 304 | <h1 id="notes">Notes</h1> |
| 306 | 305 | |
| 307 | 306 |
| --- www/delta_format.wiki | |
| +++ www/delta_format.wiki | |
| @@ -190,13 +190,13 @@ | |
| 190 | "0"-characters, except if they are significant (i.e. 0 => "0"). |
| 191 | |
| 192 | The base-64 encoding uses one character for each 6 bits of |
| 193 | the integer to be encoded. The encoding characters are: |
| 194 | |
| 195 | <blockquote><pre> |
| 196 | 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz~ |
| 197 | </pre></blockquote> |
| 198 | |
| 199 | The least significant 6 bits of the integer are encoded by |
| 200 | the first character, followed by |
| 201 | the next 6 bits, and so on until all non-zero bits of the integer |
| 202 | are encoded. The minimum number of encoding characters is used. |
| @@ -205,11 +205,11 @@ | |
| 205 | |
| 206 | <h1 id="examples">4.0 Examples</h1> |
| 207 | |
| 208 | <h2 id="examplesint">4.1 Integer encoding</h2> |
| 209 | |
| 210 | <table border=1> |
| 211 | <tr> |
| 212 | <th>Value</th> |
| 213 | <th>Encoding</th> |
| 214 | </tr> |
| 215 | <tr> |
| @@ -228,18 +228,18 @@ | |
| 228 | |
| 229 | <h2 id="examplesdelta">4.2 Delta encoding</h2> |
| 230 | |
| 231 | An example of a delta using the specified encoding is: |
| 232 | |
| 233 | <table border=1><tr><td><pre> |
| 234 | 1Xb |
| 235 | 4E@0,2:thFN@4C,6:scenda1B@Jd,6:scenda5x@Kt,6:pieces79@Qt,F: Example: eskil~E@Y0,2zMM3E;</pre> |
| 236 | </td></tr></table> |
| 237 | |
| 238 | This can be taken apart into the following parts: |
| 239 | |
| 240 | <table border=1> |
| 241 | <tr><th>What </th> <th>Encoding </th><th>Meaning </th><th>Details</th></tr> |
| 242 | <tr><td>Header</td> <td>1Xb </td><td>Size </td><td> 6246 </td></tr> |
| 243 | <tr><td>S-List</td> <td>4E@0, </td><td>Copy </td><td> 270 @ 0 </td></tr> |
| 244 | <tr><td> </td> <td>2:th </td><td>Literal </td><td> 2 'th' </td></tr> |
| 245 | <tr><td> </td> <td>FN@4C, </td><td>Copy </td><td> 983 @ 268 </td></tr> |
| @@ -254,11 +254,11 @@ | |
| 254 | <tr><td>Trailer</td><td>2zMM3E </td><td>Checksum</td><td> -1101438770 </td></tr> |
| 255 | </table> |
| 256 | |
| 257 | The unified diff behind the above delta is |
| 258 | |
| 259 | <table border=1><tr><td><pre> |
| 260 | bluepeak:(761) ~/Projects/Tcl/Fossil/Devel/devel > diff -u ../DELTA/old ../DELTA/new |
| 261 | --- ../DELTA/old 2007-08-23 21:14:40.000000000 -0700 |
| 262 | +++ ../DELTA/new 2007-08-23 21:14:33.000000000 -0700 |
| 263 | @@ -5,7 +5,7 @@ |
| 264 | |
| @@ -295,12 +295,11 @@ | |
| 295 | configuration options to replace tkdiff with some other |
| 296 | - visual differ of the users choice. |
| 297 | + visual differ of the users choice. Example: eskil. |
| 298 | |
| 299 | * Ticketing interface (expand this bullet) |
| 300 | |
| 301 | </pre></td></tr></table> |
| 302 | |
| 303 | |
| 304 | |
| 305 | <h1 id="notes">Notes</h1> |
| 306 | |
| 307 |
| --- www/delta_format.wiki | |
| +++ www/delta_format.wiki | |
| @@ -190,13 +190,13 @@ | |
| 190 | "0"-characters, except if they are significant (i.e. 0 => "0"). |
| 191 | |
| 192 | The base-64 encoding uses one character for each 6 bits of |
| 193 | the integer to be encoded. The encoding characters are: |
| 194 | |
| 195 | <pre> |
| 196 | 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz~ |
| 197 | </pre> |
| 198 | |
| 199 | The least significant 6 bits of the integer are encoded by |
| 200 | the first character, followed by |
| 201 | the next 6 bits, and so on until all non-zero bits of the integer |
| 202 | are encoded. The minimum number of encoding characters is used. |
| @@ -205,11 +205,11 @@ | |
| 205 | |
| 206 | <h1 id="examples">4.0 Examples</h1> |
| 207 | |
| 208 | <h2 id="examplesint">4.1 Integer encoding</h2> |
| 209 | |
| 210 | <table> |
| 211 | <tr> |
| 212 | <th>Value</th> |
| 213 | <th>Encoding</th> |
| 214 | </tr> |
| 215 | <tr> |
| @@ -228,18 +228,18 @@ | |
| 228 | |
| 229 | <h2 id="examplesdelta">4.2 Delta encoding</h2> |
| 230 | |
| 231 | An example of a delta using the specified encoding is: |
| 232 | |
| 233 | <pre> |
| 234 | 1Xb |
| 235 | 4E@0,2:thFN@4C,6:scenda1B@Jd,6:scenda5x@Kt,6:pieces79@Qt,F: Example: eskil~E@Y0,2zMM3E;</pre> |
| 236 | </pre> |
| 237 | |
| 238 | This can be taken apart into the following parts: |
| 239 | |
| 240 | <table> |
| 241 | <tr><th>What </th> <th>Encoding </th><th>Meaning </th><th>Details</th></tr> |
| 242 | <tr><td>Header</td> <td>1Xb </td><td>Size </td><td> 6246 </td></tr> |
| 243 | <tr><td>S-List</td> <td>4E@0, </td><td>Copy </td><td> 270 @ 0 </td></tr> |
| 244 | <tr><td> </td> <td>2:th </td><td>Literal </td><td> 2 'th' </td></tr> |
| 245 | <tr><td> </td> <td>FN@4C, </td><td>Copy </td><td> 983 @ 268 </td></tr> |
| @@ -254,11 +254,11 @@ | |
| 254 | <tr><td>Trailer</td><td>2zMM3E </td><td>Checksum</td><td> -1101438770 </td></tr> |
| 255 | </table> |
| 256 | |
| 257 | The unified diff behind the above delta is |
| 258 | |
| 259 | <verbatim> |
| 260 | bluepeak:(761) ~/Projects/Tcl/Fossil/Devel/devel > diff -u ../DELTA/old ../DELTA/new |
| 261 | --- ../DELTA/old 2007-08-23 21:14:40.000000000 -0700 |
| 262 | +++ ../DELTA/new 2007-08-23 21:14:33.000000000 -0700 |
| 263 | @@ -5,7 +5,7 @@ |
| 264 | |
| @@ -295,12 +295,11 @@ | |
| 295 | configuration options to replace tkdiff with some other |
| 296 | - visual differ of the users choice. |
| 297 | + visual differ of the users choice. Example: eskil. |
| 298 | |
| 299 | * Ticketing interface (expand this bullet) |
| 300 | </verbatim> |
| 301 | |
| 302 | |
| 303 | |
| 304 | <h1 id="notes">Notes</h1> |
| 305 | |
| 306 |
+17
-21
| --- www/embeddeddoc.wiki | ||
| +++ www/embeddeddoc.wiki | ||
| @@ -1,7 +1,6 @@ | ||
| 1 | 1 | <title>Project Documentation</title> |
| 2 | -<h1 align="center">Project Documentation</h1> | |
| 3 | 2 | |
| 4 | 3 | Fossil provides a built-in <a href="wikitheory.wiki">wiki</a> |
| 5 | 4 | that can be used to store the |
| 6 | 5 | documentation for a project. This is sufficient for many projects. |
| 7 | 6 | If your project is well-served by wiki documentation, then you |
| @@ -30,13 +29,13 @@ | ||
| 30 | 29 | |
| 31 | 30 | The fossil web interface supports embedded documentation using |
| 32 | 31 | the "/doc" page. To access embedded documentation, one points |
| 33 | 32 | a web browser to a fossil URL of the following form: |
| 34 | 33 | |
| 35 | -<blockquote> | |
| 34 | +<pre> | |
| 36 | 35 | <i><baseurl></i><big><b>/doc/</b></big><i><version></i><big><b>/</b></big><i><filename></i> |
| 37 | -</blockquote> | |
| 36 | +</pre> | |
| 38 | 37 | |
| 39 | 38 | The <i><baseurl></i> is the main URL used to access the fossil web server. |
| 40 | 39 | For example, the <i><baseurl></i> for the fossil project itself is |
| 41 | 40 | [https://fossil-scm.org/home]. |
| 42 | 41 | If you launch the web server using the "[/help?cmd=ui|fossil ui]" command line, |
| @@ -139,21 +138,21 @@ | ||
| 139 | 138 | the root of the Fossil repository using the special text "$ROOT" |
| 140 | 139 | at the beginning of a URL. For example, a Markdown hyperlink to |
| 141 | 140 | the Markdown formatting rules might be |
| 142 | 141 | written in the embedded document like this: |
| 143 | 142 | |
| 144 | -<nowiki><pre> | |
| 145 | - [Markdown formatting rules]($ROOT/wiki_rules) | |
| 146 | -</pre></nowiki> | |
| 143 | +<verbatim> | |
| 144 | +[Markdown formatting rules]($ROOT/wiki_rules) | |
| 145 | +</verbatim> | |
| 147 | 146 | |
| 148 | 147 | Depending on how the how the Fossil server is configured, that hyperlink |
| 149 | 148 | might be renderer like one of the following: |
| 150 | 149 | |
| 151 | -<nowiki><pre> | |
| 152 | - <a href="/wiki_rules">Wiki formatting rules</a> | |
| 153 | - <a href="/cgi-bin/fossil/wiki_rules">Wiki formatting rules</a> | |
| 154 | -</pre></nowiki> | |
| 150 | +<verbatim> | |
| 151 | +<a href="/wiki_rules">Wiki formatting rule</a> | |
| 152 | +<a href="/cgi-bin/fossil/wiki_rules">Wiki formatting rules</a> | |
| 153 | +</verbatim> | |
| 155 | 154 | |
| 156 | 155 | So, in other words, the "$ROOT" text is converted into whatever |
| 157 | 156 | the "<baseurl>" is for the document. |
| 158 | 157 | |
| 159 | 158 | This substitution works for HTML and Markdown documents. |
| @@ -170,13 +169,13 @@ | ||
| 170 | 169 | |
| 171 | 170 | For example, if an embedded document documented wanted to reference |
| 172 | 171 | some other document in a separate file named "www/otherdoc.md", |
| 173 | 172 | it could use a URL like this: |
| 174 | 173 | |
| 175 | -<nowiki><pre> | |
| 176 | - [Other Document]($ROOT/doc/$CURRENT/www/otherdoc.md) | |
| 177 | -</pre></nowiki> | |
| 174 | +<verbatim> | |
| 175 | +[Other Document]($ROOT/doc/$CURRENT/www/otherdoc.md) | |
| 176 | +</verbatim> | |
| 178 | 177 | |
| 179 | 178 | As with "$ROOT", this substitution only works for Markdown and HTML |
| 180 | 179 | documents. For Wiki documents, you would need to use a relative URL. |
| 181 | 180 | |
| 182 | 181 | <h2 id="th1">2.3 TH1 Documents</h2> |
| @@ -201,24 +200,24 @@ | ||
| 201 | 200 | embedded documentation. The name of this file in the fossil |
| 202 | 201 | source tree is "<b>www/embeddeddoc.wiki</b>". |
| 203 | 202 | You are perhaps looking at this |
| 204 | 203 | file using the URL: |
| 205 | 204 | |
| 206 | - [https://fossil-scm.org/home/doc/trunk/www/embeddeddoc.wiki]. | |
| 205 | +<pre>[https://fossil-scm.org/home/doc/trunk/www/embeddeddoc.wiki]</pre> | |
| 207 | 206 | |
| 208 | 207 | The first part of this path, the "[https://fossil-scm.org/home]", |
| 209 | 208 | is the base URL. You might have originally typed: |
| 210 | 209 | [https://fossil-scm.org/]. The web server at the fossil-scm.org |
| 211 | 210 | site automatically redirects such links by appending "home". The |
| 212 | 211 | "home" file on fossil-scm.org is really a [./server/any/cgi.md|CGI script] |
| 213 | 212 | which runs the fossil web service in CGI mode. |
| 214 | 213 | The "home" CGI script looks like this: |
| 215 | 214 | |
| 216 | -<blockquote><pre> | |
| 215 | +<pre> | |
| 217 | 216 | #!/usr/bin/fossil |
| 218 | 217 | repository: /fossil/fossil.fossil |
| 219 | -</pre></blockquote> | |
| 218 | +</pre> | |
| 220 | 219 | |
| 221 | 220 | This is one of the many ways to set up a |
| 222 | 221 | <a href="./server/">Fossil server</a>. |
| 223 | 222 | |
| 224 | 223 | The "<b>/trunk/</b>" part of the URL tells fossil to use |
| @@ -242,15 +241,12 @@ | ||
| 242 | 241 | When the symbolic name is a date and time, fossil shows the version |
| 243 | 242 | of the document that was most recently checked in as of the date |
| 244 | 243 | and time specified. So, for example, to see what the fossil website |
| 245 | 244 | looked like at the beginning of 2010, enter: |
| 246 | 245 | |
| 247 | -<blockquote> | |
| 248 | -<a href="/doc/2010-01-01/www/index.wiki"> | |
| 249 | -https://fossil-scm.org/home/doc/<b>2010-01-01</b>/www/index.wiki | |
| 250 | -</a> | |
| 251 | -</blockquote> | |
| 246 | +<pre><a href="/doc/2010-01-01/www/index.wiki">https://fossil-scm.org/home/doc/<b>2010-01-01</b>/www/index.wiki | |
| 247 | +</a></pre> | |
| 252 | 248 | |
| 253 | 249 | The file that encodes this document is stored in the fossil source tree under |
| 254 | 250 | the name "<b>www/embeddeddoc.wiki</b>" and so that name forms the |
| 255 | 251 | last part of the URL for this document. |
| 256 | 252 | |
| 257 | 253 |
| --- www/embeddeddoc.wiki | |
| +++ www/embeddeddoc.wiki | |
| @@ -1,7 +1,6 @@ | |
| 1 | <title>Project Documentation</title> |
| 2 | <h1 align="center">Project Documentation</h1> |
| 3 | |
| 4 | Fossil provides a built-in <a href="wikitheory.wiki">wiki</a> |
| 5 | that can be used to store the |
| 6 | documentation for a project. This is sufficient for many projects. |
| 7 | If your project is well-served by wiki documentation, then you |
| @@ -30,13 +29,13 @@ | |
| 30 | |
| 31 | The fossil web interface supports embedded documentation using |
| 32 | the "/doc" page. To access embedded documentation, one points |
| 33 | a web browser to a fossil URL of the following form: |
| 34 | |
| 35 | <blockquote> |
| 36 | <i><baseurl></i><big><b>/doc/</b></big><i><version></i><big><b>/</b></big><i><filename></i> |
| 37 | </blockquote> |
| 38 | |
| 39 | The <i><baseurl></i> is the main URL used to access the fossil web server. |
| 40 | For example, the <i><baseurl></i> for the fossil project itself is |
| 41 | [https://fossil-scm.org/home]. |
| 42 | If you launch the web server using the "[/help?cmd=ui|fossil ui]" command line, |
| @@ -139,21 +138,21 @@ | |
| 139 | the root of the Fossil repository using the special text "$ROOT" |
| 140 | at the beginning of a URL. For example, a Markdown hyperlink to |
| 141 | the Markdown formatting rules might be |
| 142 | written in the embedded document like this: |
| 143 | |
| 144 | <nowiki><pre> |
| 145 | [Markdown formatting rules]($ROOT/wiki_rules) |
| 146 | </pre></nowiki> |
| 147 | |
| 148 | Depending on how the how the Fossil server is configured, that hyperlink |
| 149 | might be renderer like one of the following: |
| 150 | |
| 151 | <nowiki><pre> |
| 152 | <a href="/wiki_rules">Wiki formatting rules</a> |
| 153 | <a href="/cgi-bin/fossil/wiki_rules">Wiki formatting rules</a> |
| 154 | </pre></nowiki> |
| 155 | |
| 156 | So, in other words, the "$ROOT" text is converted into whatever |
| 157 | the "<baseurl>" is for the document. |
| 158 | |
| 159 | This substitution works for HTML and Markdown documents. |
| @@ -170,13 +169,13 @@ | |
| 170 | |
| 171 | For example, if an embedded document documented wanted to reference |
| 172 | some other document in a separate file named "www/otherdoc.md", |
| 173 | it could use a URL like this: |
| 174 | |
| 175 | <nowiki><pre> |
| 176 | [Other Document]($ROOT/doc/$CURRENT/www/otherdoc.md) |
| 177 | </pre></nowiki> |
| 178 | |
| 179 | As with "$ROOT", this substitution only works for Markdown and HTML |
| 180 | documents. For Wiki documents, you would need to use a relative URL. |
| 181 | |
| 182 | <h2 id="th1">2.3 TH1 Documents</h2> |
| @@ -201,24 +200,24 @@ | |
| 201 | embedded documentation. The name of this file in the fossil |
| 202 | source tree is "<b>www/embeddeddoc.wiki</b>". |
| 203 | You are perhaps looking at this |
| 204 | file using the URL: |
| 205 | |
| 206 | [https://fossil-scm.org/home/doc/trunk/www/embeddeddoc.wiki]. |
| 207 | |
| 208 | The first part of this path, the "[https://fossil-scm.org/home]", |
| 209 | is the base URL. You might have originally typed: |
| 210 | [https://fossil-scm.org/]. The web server at the fossil-scm.org |
| 211 | site automatically redirects such links by appending "home". The |
| 212 | "home" file on fossil-scm.org is really a [./server/any/cgi.md|CGI script] |
| 213 | which runs the fossil web service in CGI mode. |
| 214 | The "home" CGI script looks like this: |
| 215 | |
| 216 | <blockquote><pre> |
| 217 | #!/usr/bin/fossil |
| 218 | repository: /fossil/fossil.fossil |
| 219 | </pre></blockquote> |
| 220 | |
| 221 | This is one of the many ways to set up a |
| 222 | <a href="./server/">Fossil server</a>. |
| 223 | |
| 224 | The "<b>/trunk/</b>" part of the URL tells fossil to use |
| @@ -242,15 +241,12 @@ | |
| 242 | When the symbolic name is a date and time, fossil shows the version |
| 243 | of the document that was most recently checked in as of the date |
| 244 | and time specified. So, for example, to see what the fossil website |
| 245 | looked like at the beginning of 2010, enter: |
| 246 | |
| 247 | <blockquote> |
| 248 | <a href="/doc/2010-01-01/www/index.wiki"> |
| 249 | https://fossil-scm.org/home/doc/<b>2010-01-01</b>/www/index.wiki |
| 250 | </a> |
| 251 | </blockquote> |
| 252 | |
| 253 | The file that encodes this document is stored in the fossil source tree under |
| 254 | the name "<b>www/embeddeddoc.wiki</b>" and so that name forms the |
| 255 | last part of the URL for this document. |
| 256 | |
| 257 |
| --- www/embeddeddoc.wiki | |
| +++ www/embeddeddoc.wiki | |
| @@ -1,7 +1,6 @@ | |
| 1 | <title>Project Documentation</title> |
| 2 | |
| 3 | Fossil provides a built-in <a href="wikitheory.wiki">wiki</a> |
| 4 | that can be used to store the |
| 5 | documentation for a project. This is sufficient for many projects. |
| 6 | If your project is well-served by wiki documentation, then you |
| @@ -30,13 +29,13 @@ | |
| 29 | |
| 30 | The fossil web interface supports embedded documentation using |
| 31 | the "/doc" page. To access embedded documentation, one points |
| 32 | a web browser to a fossil URL of the following form: |
| 33 | |
| 34 | <pre> |
| 35 | <i><baseurl></i><big><b>/doc/</b></big><i><version></i><big><b>/</b></big><i><filename></i> |
| 36 | </pre> |
| 37 | |
| 38 | The <i><baseurl></i> is the main URL used to access the fossil web server. |
| 39 | For example, the <i><baseurl></i> for the fossil project itself is |
| 40 | [https://fossil-scm.org/home]. |
| 41 | If you launch the web server using the "[/help?cmd=ui|fossil ui]" command line, |
| @@ -139,21 +138,21 @@ | |
| 138 | the root of the Fossil repository using the special text "$ROOT" |
| 139 | at the beginning of a URL. For example, a Markdown hyperlink to |
| 140 | the Markdown formatting rules might be |
| 141 | written in the embedded document like this: |
| 142 | |
| 143 | <verbatim> |
| 144 | [Markdown formatting rules]($ROOT/wiki_rules) |
| 145 | </verbatim> |
| 146 | |
| 147 | Depending on how the how the Fossil server is configured, that hyperlink |
| 148 | might be renderer like one of the following: |
| 149 | |
| 150 | <verbatim> |
| 151 | <a href="/wiki_rules">Wiki formatting rule</a> |
| 152 | <a href="/cgi-bin/fossil/wiki_rules">Wiki formatting rules</a> |
| 153 | </verbatim> |
| 154 | |
| 155 | So, in other words, the "$ROOT" text is converted into whatever |
| 156 | the "<baseurl>" is for the document. |
| 157 | |
| 158 | This substitution works for HTML and Markdown documents. |
| @@ -170,13 +169,13 @@ | |
| 169 | |
| 170 | For example, if an embedded document documented wanted to reference |
| 171 | some other document in a separate file named "www/otherdoc.md", |
| 172 | it could use a URL like this: |
| 173 | |
| 174 | <verbatim> |
| 175 | [Other Document]($ROOT/doc/$CURRENT/www/otherdoc.md) |
| 176 | </verbatim> |
| 177 | |
| 178 | As with "$ROOT", this substitution only works for Markdown and HTML |
| 179 | documents. For Wiki documents, you would need to use a relative URL. |
| 180 | |
| 181 | <h2 id="th1">2.3 TH1 Documents</h2> |
| @@ -201,24 +200,24 @@ | |
| 200 | embedded documentation. The name of this file in the fossil |
| 201 | source tree is "<b>www/embeddeddoc.wiki</b>". |
| 202 | You are perhaps looking at this |
| 203 | file using the URL: |
| 204 | |
| 205 | <pre>[https://fossil-scm.org/home/doc/trunk/www/embeddeddoc.wiki]</pre> |
| 206 | |
| 207 | The first part of this path, the "[https://fossil-scm.org/home]", |
| 208 | is the base URL. You might have originally typed: |
| 209 | [https://fossil-scm.org/]. The web server at the fossil-scm.org |
| 210 | site automatically redirects such links by appending "home". The |
| 211 | "home" file on fossil-scm.org is really a [./server/any/cgi.md|CGI script] |
| 212 | which runs the fossil web service in CGI mode. |
| 213 | The "home" CGI script looks like this: |
| 214 | |
| 215 | <pre> |
| 216 | #!/usr/bin/fossil |
| 217 | repository: /fossil/fossil.fossil |
| 218 | </pre> |
| 219 | |
| 220 | This is one of the many ways to set up a |
| 221 | <a href="./server/">Fossil server</a>. |
| 222 | |
| 223 | The "<b>/trunk/</b>" part of the URL tells fossil to use |
| @@ -242,15 +241,12 @@ | |
| 241 | When the symbolic name is a date and time, fossil shows the version |
| 242 | of the document that was most recently checked in as of the date |
| 243 | and time specified. So, for example, to see what the fossil website |
| 244 | looked like at the beginning of 2010, enter: |
| 245 | |
| 246 | <pre><a href="/doc/2010-01-01/www/index.wiki">https://fossil-scm.org/home/doc/<b>2010-01-01</b>/www/index.wiki |
| 247 | </a></pre> |
| 248 | |
| 249 | The file that encodes this document is stored in the fossil source tree under |
| 250 | the name "<b>www/embeddeddoc.wiki</b>" and so that name forms the |
| 251 | last part of the URL for this document. |
| 252 | |
| 253 |
+30
-18
| --- www/encryptedrepos.wiki | ||
| +++ www/encryptedrepos.wiki | ||
| @@ -1,12 +1,15 @@ | ||
| 1 | 1 | <title>How To Use Encrypted Repositories</title> |
| 2 | -<h2>Introduction</h2><blockquote> | |
| 2 | + | |
| 3 | +<h2>Introduction</h2> | |
| 4 | + | |
| 3 | 5 | Fossil can be compiled so that it works with encrypted repositories using |
| 4 | 6 | the [https://www.sqlite.org/see/doc/trunk/www/readme.wiki|SQLite Encryption Extension]. |
| 5 | 7 | This technical note explains the process. |
| 6 | -</blockquote> | |
| 7 | -<h2>Building An Encryption-Enabled Fossil</h2><blockquote> | |
| 8 | + | |
| 9 | +<h2>Building An Encryption-Enabled Fossil</h2> | |
| 10 | + | |
| 8 | 11 | The SQLite Encryption Extension (SEE) is proprietary software and requires |
| 9 | 12 | [https://sqlite.org/purchase/see|purchasing a license]. |
| 10 | 13 | |
| 11 | 14 | Assuming you have an SEE license, the first step of compiling Fossil to |
| 12 | 15 | use SEE is to create an SEE-enabled version of the SQLite database source code. |
| @@ -16,21 +19,24 @@ | ||
| 16 | 19 | "shell.c" file, renamed as "shell-see.c", and place it in the extsrc/ subfolder |
| 17 | 20 | beside the original "shell.c". |
| 18 | 21 | |
| 19 | 22 | Add the --with-see command-line option to the configuration script to enable |
| 20 | 23 | the use of SEE on unix-like systems. |
| 21 | -<blockquote><pre> | |
| 24 | + | |
| 25 | +<pre> | |
| 22 | 26 | ./configure --with-see; make |
| 23 | -</pre></blockquote> | |
| 27 | +</pre> | |
| 24 | 28 | |
| 25 | 29 | To build for Windows using MSVC, add |
| 26 | 30 | the "USE_SEE=1" argument to the "nmake" command line. |
| 27 | -<blockquote><pre> | |
| 31 | + | |
| 32 | +<pre> | |
| 28 | 33 | nmake -f makefile.msc USE_SEE=1 |
| 29 | -</pre></blockquote> | |
| 30 | -</blockquote> | |
| 31 | -<h2>Using Encrypted Repositories</h2><blockquote> | |
| 34 | +</pre> | |
| 35 | + | |
| 36 | +<h2>Using Encrypted Repositories</h2> | |
| 37 | + | |
| 32 | 38 | Any Fossil repositories whose filename ends with ".efossil" is taken to be |
| 33 | 39 | an encrypted repository. Fossil will prompt for the encryption password and |
| 34 | 40 | attempt to open the repository database using that password. |
| 35 | 41 | |
| 36 | 42 | Every invocation of fossil on an encrypted repository requires retyping the |
| @@ -39,32 +45,38 @@ | ||
| 39 | 45 | command which prompts for the password just once, then reuses it for each |
| 40 | 46 | subsequent Fossil command entered at the prompt. |
| 41 | 47 | |
| 42 | 48 | On Windows, the "fossil server", "fossil ui", and "fossil shell" commands do not |
| 43 | 49 | (currently) work on an encrypted repository. |
| 44 | -</blockquote> | |
| 45 | -<h2>Additional Security</h2><blockquote> | |
| 50 | + | |
| 51 | +<h2>Additional Security</h2> | |
| 52 | + | |
| 46 | 53 | Use the FOSSIL_SECURITY_LEVEL environment for additional protection. |
| 47 | -<blockquote><pre> | |
| 54 | + | |
| 55 | +<pre> | |
| 48 | 56 | export FOSSIL_SECURITY_LEVEL=1 |
| 49 | -</pre></blockquote> | |
| 57 | +</pre> | |
| 58 | + | |
| 50 | 59 | A setting of 1 or greater |
| 51 | 60 | prevents fossil from trying to remember the previous sync password. |
| 52 | -<blockquote><pre> | |
| 61 | + | |
| 62 | +<pre> | |
| 53 | 63 | export FOSSIL_SECURITY_LEVEL=2 |
| 54 | -</pre></blockquote> | |
| 64 | +</pre> | |
| 65 | + | |
| 55 | 66 | A setting of 2 or greater |
| 56 | 67 | causes all password prompts to be preceded by a random translation matrix similar |
| 57 | 68 | to the following: |
| 58 | -<blockquote><pre> | |
| 69 | + | |
| 70 | +<pre> | |
| 59 | 71 | abcde fghij klmno pqrst uvwyz |
| 60 | 72 | qresw gjymu dpcoa fhkzv inlbt |
| 61 | -</pre></blockquote> | |
| 73 | +</pre> | |
| 74 | + | |
| 62 | 75 | When entering the password, the user must substitute the letter on the second |
| 63 | 76 | line that corresponds to the letter on the first line. Uppercase substitutes |
| 64 | 77 | for uppercase inputs, and lowercase substitutes for lowercase inputs. Letters |
| 65 | 78 | that are not in the translation matrix (digits, punctuation, and "x") are not |
| 66 | 79 | modified. For example, given the |
| 67 | 80 | translation matrix above, if the password is "pilot-9crazy-xube", then the user |
| 68 | 81 | must type "fmpav-9ekqtb-xirw". This simple substitution cypher helps prevent |
| 69 | 82 | password capture by keyloggers. |
| 70 | -</blockquote> | |
| 71 | 83 |
| --- www/encryptedrepos.wiki | |
| +++ www/encryptedrepos.wiki | |
| @@ -1,12 +1,15 @@ | |
| 1 | <title>How To Use Encrypted Repositories</title> |
| 2 | <h2>Introduction</h2><blockquote> |
| 3 | Fossil can be compiled so that it works with encrypted repositories using |
| 4 | the [https://www.sqlite.org/see/doc/trunk/www/readme.wiki|SQLite Encryption Extension]. |
| 5 | This technical note explains the process. |
| 6 | </blockquote> |
| 7 | <h2>Building An Encryption-Enabled Fossil</h2><blockquote> |
| 8 | The SQLite Encryption Extension (SEE) is proprietary software and requires |
| 9 | [https://sqlite.org/purchase/see|purchasing a license]. |
| 10 | |
| 11 | Assuming you have an SEE license, the first step of compiling Fossil to |
| 12 | use SEE is to create an SEE-enabled version of the SQLite database source code. |
| @@ -16,21 +19,24 @@ | |
| 16 | "shell.c" file, renamed as "shell-see.c", and place it in the extsrc/ subfolder |
| 17 | beside the original "shell.c". |
| 18 | |
| 19 | Add the --with-see command-line option to the configuration script to enable |
| 20 | the use of SEE on unix-like systems. |
| 21 | <blockquote><pre> |
| 22 | ./configure --with-see; make |
| 23 | </pre></blockquote> |
| 24 | |
| 25 | To build for Windows using MSVC, add |
| 26 | the "USE_SEE=1" argument to the "nmake" command line. |
| 27 | <blockquote><pre> |
| 28 | nmake -f makefile.msc USE_SEE=1 |
| 29 | </pre></blockquote> |
| 30 | </blockquote> |
| 31 | <h2>Using Encrypted Repositories</h2><blockquote> |
| 32 | Any Fossil repositories whose filename ends with ".efossil" is taken to be |
| 33 | an encrypted repository. Fossil will prompt for the encryption password and |
| 34 | attempt to open the repository database using that password. |
| 35 | |
| 36 | Every invocation of fossil on an encrypted repository requires retyping the |
| @@ -39,32 +45,38 @@ | |
| 39 | command which prompts for the password just once, then reuses it for each |
| 40 | subsequent Fossil command entered at the prompt. |
| 41 | |
| 42 | On Windows, the "fossil server", "fossil ui", and "fossil shell" commands do not |
| 43 | (currently) work on an encrypted repository. |
| 44 | </blockquote> |
| 45 | <h2>Additional Security</h2><blockquote> |
| 46 | Use the FOSSIL_SECURITY_LEVEL environment for additional protection. |
| 47 | <blockquote><pre> |
| 48 | export FOSSIL_SECURITY_LEVEL=1 |
| 49 | </pre></blockquote> |
| 50 | A setting of 1 or greater |
| 51 | prevents fossil from trying to remember the previous sync password. |
| 52 | <blockquote><pre> |
| 53 | export FOSSIL_SECURITY_LEVEL=2 |
| 54 | </pre></blockquote> |
| 55 | A setting of 2 or greater |
| 56 | causes all password prompts to be preceded by a random translation matrix similar |
| 57 | to the following: |
| 58 | <blockquote><pre> |
| 59 | abcde fghij klmno pqrst uvwyz |
| 60 | qresw gjymu dpcoa fhkzv inlbt |
| 61 | </pre></blockquote> |
| 62 | When entering the password, the user must substitute the letter on the second |
| 63 | line that corresponds to the letter on the first line. Uppercase substitutes |
| 64 | for uppercase inputs, and lowercase substitutes for lowercase inputs. Letters |
| 65 | that are not in the translation matrix (digits, punctuation, and "x") are not |
| 66 | modified. For example, given the |
| 67 | translation matrix above, if the password is "pilot-9crazy-xube", then the user |
| 68 | must type "fmpav-9ekqtb-xirw". This simple substitution cypher helps prevent |
| 69 | password capture by keyloggers. |
| 70 | </blockquote> |
| 71 |
| --- www/encryptedrepos.wiki | |
| +++ www/encryptedrepos.wiki | |
| @@ -1,12 +1,15 @@ | |
| 1 | <title>How To Use Encrypted Repositories</title> |
| 2 | |
| 3 | <h2>Introduction</h2> |
| 4 | |
| 5 | Fossil can be compiled so that it works with encrypted repositories using |
| 6 | the [https://www.sqlite.org/see/doc/trunk/www/readme.wiki|SQLite Encryption Extension]. |
| 7 | This technical note explains the process. |
| 8 | |
| 9 | <h2>Building An Encryption-Enabled Fossil</h2> |
| 10 | |
| 11 | The SQLite Encryption Extension (SEE) is proprietary software and requires |
| 12 | [https://sqlite.org/purchase/see|purchasing a license]. |
| 13 | |
| 14 | Assuming you have an SEE license, the first step of compiling Fossil to |
| 15 | use SEE is to create an SEE-enabled version of the SQLite database source code. |
| @@ -16,21 +19,24 @@ | |
| 19 | "shell.c" file, renamed as "shell-see.c", and place it in the extsrc/ subfolder |
| 20 | beside the original "shell.c". |
| 21 | |
| 22 | Add the --with-see command-line option to the configuration script to enable |
| 23 | the use of SEE on unix-like systems. |
| 24 | |
| 25 | <pre> |
| 26 | ./configure --with-see; make |
| 27 | </pre> |
| 28 | |
| 29 | To build for Windows using MSVC, add |
| 30 | the "USE_SEE=1" argument to the "nmake" command line. |
| 31 | |
| 32 | <pre> |
| 33 | nmake -f makefile.msc USE_SEE=1 |
| 34 | </pre> |
| 35 | |
| 36 | <h2>Using Encrypted Repositories</h2> |
| 37 | |
| 38 | Any Fossil repositories whose filename ends with ".efossil" is taken to be |
| 39 | an encrypted repository. Fossil will prompt for the encryption password and |
| 40 | attempt to open the repository database using that password. |
| 41 | |
| 42 | Every invocation of fossil on an encrypted repository requires retyping the |
| @@ -39,32 +45,38 @@ | |
| 45 | command which prompts for the password just once, then reuses it for each |
| 46 | subsequent Fossil command entered at the prompt. |
| 47 | |
| 48 | On Windows, the "fossil server", "fossil ui", and "fossil shell" commands do not |
| 49 | (currently) work on an encrypted repository. |
| 50 | |
| 51 | <h2>Additional Security</h2> |
| 52 | |
| 53 | Use the FOSSIL_SECURITY_LEVEL environment for additional protection. |
| 54 | |
| 55 | <pre> |
| 56 | export FOSSIL_SECURITY_LEVEL=1 |
| 57 | </pre> |
| 58 | |
| 59 | A setting of 1 or greater |
| 60 | prevents fossil from trying to remember the previous sync password. |
| 61 | |
| 62 | <pre> |
| 63 | export FOSSIL_SECURITY_LEVEL=2 |
| 64 | </pre> |
| 65 | |
| 66 | A setting of 2 or greater |
| 67 | causes all password prompts to be preceded by a random translation matrix similar |
| 68 | to the following: |
| 69 | |
| 70 | <pre> |
| 71 | abcde fghij klmno pqrst uvwyz |
| 72 | qresw gjymu dpcoa fhkzv inlbt |
| 73 | </pre> |
| 74 | |
| 75 | When entering the password, the user must substitute the letter on the second |
| 76 | line that corresponds to the letter on the first line. Uppercase substitutes |
| 77 | for uppercase inputs, and lowercase substitutes for lowercase inputs. Letters |
| 78 | that are not in the translation matrix (digits, punctuation, and "x") are not |
| 79 | modified. For example, given the |
| 80 | translation matrix above, if the password is "pilot-9crazy-xube", then the user |
| 81 | must type "fmpav-9ekqtb-xirw". This simple substitution cypher helps prevent |
| 82 | password capture by keyloggers. |
| 83 |
+12
-18
| --- www/event.wiki | ||
| +++ www/event.wiki | ||
| @@ -73,16 +73,14 @@ | ||
| 73 | 73 | new technotes. And there is a submenu hyperlink on technote displays for |
| 74 | 74 | editing existing technotes. |
| 75 | 75 | |
| 76 | 76 | Technotes can also be created using the <b>wiki create</b> command: |
| 77 | 77 | |
| 78 | -<blockquote> | |
| 79 | -<b> | |
| 80 | -fossil wiki create TestTechnote -t now --technote-bgcolor lightgreen technote.md<br> | |
| 81 | -<tt>Created new tech note 2021-03-15 13:05:56</tt><br> | |
| 82 | -</b> | |
| 83 | -</blockquote> | |
| 78 | +<verbatim> | |
| 79 | +fossil wiki create TestTechnote -t now --technote-bgcolor lightgreen technote.md | |
| 80 | +Created new tech note 2021-03-15 13:05:56 | |
| 81 | +</verbatim> | |
| 84 | 82 | |
| 85 | 83 | This command inserts a light green technote in the timeline at 2021-03-15 13:05:56, with |
| 86 | 84 | the contents of file <b>technote.md</b> and comment "TestTechnote". Specifying a different time using |
| 87 | 85 | <b>-t DATETIME</b> will insert the technote at the specified timestamp location in the timeline. |
| 88 | 86 | Different technotes can have the same timestamp. |
| @@ -90,30 +88,26 @@ | ||
| 90 | 88 | The first argument to create, <b>TECHNOTE-COMMENT</b>, is the title text for the technote |
| 91 | 89 | that appears in the timeline. |
| 92 | 90 | |
| 93 | 91 | To view all technotes, use the <b>wiki ls</b> command: |
| 94 | 92 | |
| 95 | -<blockquote> | |
| 96 | -<b> | |
| 97 | -fossil wiki ls --technote --show-technote-ids<br> | |
| 98 | -<tt>z739263a134bf0da1d28e939f4c4367f51ef4c51 2020-12-19 13:20:19</tt><br> | |
| 99 | -<tt>e15a918a8bed71c2ac091d74dc397b8d3340d5e1 2018-09-22 17:40:10</tt><br> | |
| 100 | -</b> | |
| 101 | -</blockquote> | |
| 93 | +<verbatim> | |
| 94 | +fossil wiki ls --technote --show-technote-ids | |
| 95 | +z739263a134bf0da1d28e939f4c4367f51ef4c51 2020-12-19 13:20:19 | |
| 96 | +e15a918a8bed71c2ac091d74dc397b8d3340d5e1 2018-09-22 17:40:10 | |
| 97 | +</verbatim> | |
| 102 | 98 | |
| 103 | 99 | A technote ID is the UUID of the technote. |
| 104 | 100 | |
| 105 | 101 | To view an individual technote, use the <b>wiki export</b> command: |
| 106 | 102 | |
| 107 | -<blockquote> | |
| 108 | -<b> | |
| 109 | -fossil wiki export --technote version-2.16<br> | |
| 103 | +<verbatim> | |
| 104 | +fossil wiki export --technote version-2.16 | |
| 110 | 105 | Release Notes 2021-07-02 |
| 111 | 106 | |
| 112 | 107 | This note describes changes in the Fossil snapshot for ... |
| 113 | -</b> | |
| 114 | -</blockquote> | |
| 108 | +</verbatim> | |
| 115 | 109 | |
| 116 | 110 | The <b>-t|--technote</b> option to the <b>export</b> subcommand takes one of |
| 117 | 111 | three identifiers: <b>DATETIME</b>; <b>TECHNOTE-ID</b>; and <b>TAG</b>. |
| 118 | 112 | See the [/help?cmd=wiki | wiki help] for specifics. |
| 119 | 113 | |
| 120 | 114 |
| --- www/event.wiki | |
| +++ www/event.wiki | |
| @@ -73,16 +73,14 @@ | |
| 73 | new technotes. And there is a submenu hyperlink on technote displays for |
| 74 | editing existing technotes. |
| 75 | |
| 76 | Technotes can also be created using the <b>wiki create</b> command: |
| 77 | |
| 78 | <blockquote> |
| 79 | <b> |
| 80 | fossil wiki create TestTechnote -t now --technote-bgcolor lightgreen technote.md<br> |
| 81 | <tt>Created new tech note 2021-03-15 13:05:56</tt><br> |
| 82 | </b> |
| 83 | </blockquote> |
| 84 | |
| 85 | This command inserts a light green technote in the timeline at 2021-03-15 13:05:56, with |
| 86 | the contents of file <b>technote.md</b> and comment "TestTechnote". Specifying a different time using |
| 87 | <b>-t DATETIME</b> will insert the technote at the specified timestamp location in the timeline. |
| 88 | Different technotes can have the same timestamp. |
| @@ -90,30 +88,26 @@ | |
| 90 | The first argument to create, <b>TECHNOTE-COMMENT</b>, is the title text for the technote |
| 91 | that appears in the timeline. |
| 92 | |
| 93 | To view all technotes, use the <b>wiki ls</b> command: |
| 94 | |
| 95 | <blockquote> |
| 96 | <b> |
| 97 | fossil wiki ls --technote --show-technote-ids<br> |
| 98 | <tt>z739263a134bf0da1d28e939f4c4367f51ef4c51 2020-12-19 13:20:19</tt><br> |
| 99 | <tt>e15a918a8bed71c2ac091d74dc397b8d3340d5e1 2018-09-22 17:40:10</tt><br> |
| 100 | </b> |
| 101 | </blockquote> |
| 102 | |
| 103 | A technote ID is the UUID of the technote. |
| 104 | |
| 105 | To view an individual technote, use the <b>wiki export</b> command: |
| 106 | |
| 107 | <blockquote> |
| 108 | <b> |
| 109 | fossil wiki export --technote version-2.16<br> |
| 110 | Release Notes 2021-07-02 |
| 111 | |
| 112 | This note describes changes in the Fossil snapshot for ... |
| 113 | </b> |
| 114 | </blockquote> |
| 115 | |
| 116 | The <b>-t|--technote</b> option to the <b>export</b> subcommand takes one of |
| 117 | three identifiers: <b>DATETIME</b>; <b>TECHNOTE-ID</b>; and <b>TAG</b>. |
| 118 | See the [/help?cmd=wiki | wiki help] for specifics. |
| 119 | |
| 120 |
| --- www/event.wiki | |
| +++ www/event.wiki | |
| @@ -73,16 +73,14 @@ | |
| 73 | new technotes. And there is a submenu hyperlink on technote displays for |
| 74 | editing existing technotes. |
| 75 | |
| 76 | Technotes can also be created using the <b>wiki create</b> command: |
| 77 | |
| 78 | <verbatim> |
| 79 | fossil wiki create TestTechnote -t now --technote-bgcolor lightgreen technote.md |
| 80 | Created new tech note 2021-03-15 13:05:56 |
| 81 | </verbatim> |
| 82 | |
| 83 | This command inserts a light green technote in the timeline at 2021-03-15 13:05:56, with |
| 84 | the contents of file <b>technote.md</b> and comment "TestTechnote". Specifying a different time using |
| 85 | <b>-t DATETIME</b> will insert the technote at the specified timestamp location in the timeline. |
| 86 | Different technotes can have the same timestamp. |
| @@ -90,30 +88,26 @@ | |
| 88 | The first argument to create, <b>TECHNOTE-COMMENT</b>, is the title text for the technote |
| 89 | that appears in the timeline. |
| 90 | |
| 91 | To view all technotes, use the <b>wiki ls</b> command: |
| 92 | |
| 93 | <verbatim> |
| 94 | fossil wiki ls --technote --show-technote-ids |
| 95 | z739263a134bf0da1d28e939f4c4367f51ef4c51 2020-12-19 13:20:19 |
| 96 | e15a918a8bed71c2ac091d74dc397b8d3340d5e1 2018-09-22 17:40:10 |
| 97 | </verbatim> |
| 98 | |
| 99 | A technote ID is the UUID of the technote. |
| 100 | |
| 101 | To view an individual technote, use the <b>wiki export</b> command: |
| 102 | |
| 103 | <verbatim> |
| 104 | fossil wiki export --technote version-2.16 |
| 105 | Release Notes 2021-07-02 |
| 106 | |
| 107 | This note describes changes in the Fossil snapshot for ... |
| 108 | </verbatim> |
| 109 | |
| 110 | The <b>-t|--technote</b> option to the <b>export</b> subcommand takes one of |
| 111 | three identifiers: <b>DATETIME</b>; <b>TECHNOTE-ID</b>; and <b>TAG</b>. |
| 112 | See the [/help?cmd=wiki | wiki help] for specifics. |
| 113 | |
| 114 |
+19
-15
| --- www/faq.tcl | ||
| +++ www/faq.tcl | ||
| @@ -12,13 +12,13 @@ | ||
| 12 | 12 | What GUIs are available for fossil? |
| 13 | 13 | } { |
| 14 | 14 | The fossil executable comes with a [./webui.wiki | web-based GUI] built in. |
| 15 | 15 | Just run: |
| 16 | 16 | |
| 17 | - <blockquote> | |
| 17 | + <pre> | |
| 18 | 18 | <b>fossil [/help/ui|ui]</b> <i>REPOSITORY-FILENAME</i> |
| 19 | - </blockquote> | |
| 19 | + </pre> | |
| 20 | 20 | |
| 21 | 21 | And your default web browser should pop up and automatically point to |
| 22 | 22 | the fossil interface. (Hint: You can omit the <i>REPOSITORY-FILENAME</i> |
| 23 | 23 | if you are within an open check-out.) |
| 24 | 24 | } |
| @@ -42,13 +42,13 @@ | ||
| 42 | 42 | make the new check-in be the first check-in for a new branch. |
| 43 | 43 | |
| 44 | 44 | If you want to create a new branch whose initial content is the |
| 45 | 45 | same as an existing check-in, use this command: |
| 46 | 46 | |
| 47 | - <blockquote> | |
| 47 | + <pre> | |
| 48 | 48 | <b>fossil [/help/branch|branch] new</b> <i>BRANCH-NAME BASIS</i> |
| 49 | - </blockquote> | |
| 49 | + </pre> | |
| 50 | 50 | |
| 51 | 51 | The <i>BRANCH-NAME</i> argument is the name of the new branch and the |
| 52 | 52 | <i>BASIS</i> argument is the name of the check-in that the branch splits |
| 53 | 53 | off from. |
| 54 | 54 | |
| @@ -75,13 +75,13 @@ | ||
| 75 | 75 | for example, it is common to give every released version a "release" tag. |
| 76 | 76 | |
| 77 | 77 | If you want add a tag to an existing check-in, you can use the |
| 78 | 78 | <b>[/help/tag|tag]</b> command. For example: |
| 79 | 79 | |
| 80 | - <blockquote> | |
| 80 | + <pre> | |
| 81 | 81 | <b>fossil [/help/branch|tag] add</b> <i>TAGNAME</i> <i>CHECK-IN</i> |
| 82 | - </blockquote> | |
| 82 | + </pre> | |
| 83 | 83 | |
| 84 | 84 | The CHECK-IN in the previous line can be any |
| 85 | 85 | [./checkin_names.wiki | valid check-in name format]. |
| 86 | 86 | |
| 87 | 87 | You can also add (and remove) tags from a check-in using the |
| @@ -127,25 +127,30 @@ | ||
| 127 | 127 | |
| 128 | 128 | faq { |
| 129 | 129 | How do I make a clone of the fossil self-hosting repository? |
| 130 | 130 | } { |
| 131 | 131 | Any of the following commands should work: |
| 132 | - <blockquote><pre> | |
| 132 | + | |
| 133 | + <pre> | |
| 133 | 134 | fossil [/help/clone|clone] https://fossil-scm.org/ fossil.fossil |
| 134 | 135 | fossil [/help/clone|clone] https://www2.fossil-scm.org/ fossil.fossil |
| 135 | 136 | fossil [/help/clone|clone] https://www3.fossil-scm.org/site.cgi fossil.fossil |
| 136 | - </pre></blockquote> | |
| 137 | + </pre> | |
| 138 | + | |
| 137 | 139 | Once you have the repository cloned, you can open a local check-out |
| 138 | 140 | as follows: |
| 139 | - <blockquote><pre> | |
| 141 | + | |
| 142 | + <pre> | |
| 140 | 143 | mkdir src; cd src; fossil [/help/open|open] ../fossil.fossil |
| 141 | - </pre></blockquote> | |
| 144 | + </pre> | |
| 145 | + | |
| 142 | 146 | Thereafter you should be able to keep your local check-out up to date |
| 143 | 147 | with the latest code in the public repository by typing: |
| 144 | - <blockquote><pre> | |
| 148 | + | |
| 149 | + <pre> | |
| 145 | 150 | fossil [/help/update|update] |
| 146 | - </pre></blockquote> | |
| 151 | + </pre> | |
| 147 | 152 | } |
| 148 | 153 | |
| 149 | 154 | faq { |
| 150 | 155 | How do I import or export content from and to other version control systems? |
| 151 | 156 | } { |
| @@ -155,12 +160,11 @@ | ||
| 155 | 160 | |
| 156 | 161 | |
| 157 | 162 | ############################################################################# |
| 158 | 163 | # Code to actually generate the FAQ |
| 159 | 164 | # |
| 160 | -puts "<title>Fossil FAQ</title>" | |
| 161 | -puts "<h1 align=\"center\">Frequently Asked Questions</h1>\n" | |
| 165 | +puts "<title>Fossil FAQ</title>\n" | |
| 162 | 166 | puts "Note: See also <a href=\"qandc.wiki\">Questions and Criticisms</a>.\n" |
| 163 | 167 | |
| 164 | 168 | puts {<ol>} |
| 165 | 169 | for {set i 1} {$i<$cnt} {incr i} { |
| 166 | 170 | puts "<li><a href=\"#q$i\">[lindex $faq($i) 0]</a></li>" |
| @@ -170,8 +174,8 @@ | ||
| 170 | 174 | |
| 171 | 175 | for {set i 1} {$i<$cnt} {incr i} { |
| 172 | 176 | puts "<p id=\"q$i\"><b>($i) [lindex $faq($i) 0]</b></p>\n" |
| 173 | 177 | set body [lindex $faq($i) 1] |
| 174 | 178 | regsub -all "\n *" [string trim $body] "\n" body |
| 175 | - puts "<blockquote>$body</blockquote></li>\n" | |
| 179 | + puts "$body</li>\n" | |
| 176 | 180 | } |
| 177 | 181 | puts {</ol>} |
| 178 | 182 |
| --- www/faq.tcl | |
| +++ www/faq.tcl | |
| @@ -12,13 +12,13 @@ | |
| 12 | What GUIs are available for fossil? |
| 13 | } { |
| 14 | The fossil executable comes with a [./webui.wiki | web-based GUI] built in. |
| 15 | Just run: |
| 16 | |
| 17 | <blockquote> |
| 18 | <b>fossil [/help/ui|ui]</b> <i>REPOSITORY-FILENAME</i> |
| 19 | </blockquote> |
| 20 | |
| 21 | And your default web browser should pop up and automatically point to |
| 22 | the fossil interface. (Hint: You can omit the <i>REPOSITORY-FILENAME</i> |
| 23 | if you are within an open check-out.) |
| 24 | } |
| @@ -42,13 +42,13 @@ | |
| 42 | make the new check-in be the first check-in for a new branch. |
| 43 | |
| 44 | If you want to create a new branch whose initial content is the |
| 45 | same as an existing check-in, use this command: |
| 46 | |
| 47 | <blockquote> |
| 48 | <b>fossil [/help/branch|branch] new</b> <i>BRANCH-NAME BASIS</i> |
| 49 | </blockquote> |
| 50 | |
| 51 | The <i>BRANCH-NAME</i> argument is the name of the new branch and the |
| 52 | <i>BASIS</i> argument is the name of the check-in that the branch splits |
| 53 | off from. |
| 54 | |
| @@ -75,13 +75,13 @@ | |
| 75 | for example, it is common to give every released version a "release" tag. |
| 76 | |
| 77 | If you want add a tag to an existing check-in, you can use the |
| 78 | <b>[/help/tag|tag]</b> command. For example: |
| 79 | |
| 80 | <blockquote> |
| 81 | <b>fossil [/help/branch|tag] add</b> <i>TAGNAME</i> <i>CHECK-IN</i> |
| 82 | </blockquote> |
| 83 | |
| 84 | The CHECK-IN in the previous line can be any |
| 85 | [./checkin_names.wiki | valid check-in name format]. |
| 86 | |
| 87 | You can also add (and remove) tags from a check-in using the |
| @@ -127,25 +127,30 @@ | |
| 127 | |
| 128 | faq { |
| 129 | How do I make a clone of the fossil self-hosting repository? |
| 130 | } { |
| 131 | Any of the following commands should work: |
| 132 | <blockquote><pre> |
| 133 | fossil [/help/clone|clone] https://fossil-scm.org/ fossil.fossil |
| 134 | fossil [/help/clone|clone] https://www2.fossil-scm.org/ fossil.fossil |
| 135 | fossil [/help/clone|clone] https://www3.fossil-scm.org/site.cgi fossil.fossil |
| 136 | </pre></blockquote> |
| 137 | Once you have the repository cloned, you can open a local check-out |
| 138 | as follows: |
| 139 | <blockquote><pre> |
| 140 | mkdir src; cd src; fossil [/help/open|open] ../fossil.fossil |
| 141 | </pre></blockquote> |
| 142 | Thereafter you should be able to keep your local check-out up to date |
| 143 | with the latest code in the public repository by typing: |
| 144 | <blockquote><pre> |
| 145 | fossil [/help/update|update] |
| 146 | </pre></blockquote> |
| 147 | } |
| 148 | |
| 149 | faq { |
| 150 | How do I import or export content from and to other version control systems? |
| 151 | } { |
| @@ -155,12 +160,11 @@ | |
| 155 | |
| 156 | |
| 157 | ############################################################################# |
| 158 | # Code to actually generate the FAQ |
| 159 | # |
| 160 | puts "<title>Fossil FAQ</title>" |
| 161 | puts "<h1 align=\"center\">Frequently Asked Questions</h1>\n" |
| 162 | puts "Note: See also <a href=\"qandc.wiki\">Questions and Criticisms</a>.\n" |
| 163 | |
| 164 | puts {<ol>} |
| 165 | for {set i 1} {$i<$cnt} {incr i} { |
| 166 | puts "<li><a href=\"#q$i\">[lindex $faq($i) 0]</a></li>" |
| @@ -170,8 +174,8 @@ | |
| 170 | |
| 171 | for {set i 1} {$i<$cnt} {incr i} { |
| 172 | puts "<p id=\"q$i\"><b>($i) [lindex $faq($i) 0]</b></p>\n" |
| 173 | set body [lindex $faq($i) 1] |
| 174 | regsub -all "\n *" [string trim $body] "\n" body |
| 175 | puts "<blockquote>$body</blockquote></li>\n" |
| 176 | } |
| 177 | puts {</ol>} |
| 178 |
| --- www/faq.tcl | |
| +++ www/faq.tcl | |
| @@ -12,13 +12,13 @@ | |
| 12 | What GUIs are available for fossil? |
| 13 | } { |
| 14 | The fossil executable comes with a [./webui.wiki | web-based GUI] built in. |
| 15 | Just run: |
| 16 | |
| 17 | <pre> |
| 18 | <b>fossil [/help/ui|ui]</b> <i>REPOSITORY-FILENAME</i> |
| 19 | </pre> |
| 20 | |
| 21 | And your default web browser should pop up and automatically point to |
| 22 | the fossil interface. (Hint: You can omit the <i>REPOSITORY-FILENAME</i> |
| 23 | if you are within an open check-out.) |
| 24 | } |
| @@ -42,13 +42,13 @@ | |
| 42 | make the new check-in be the first check-in for a new branch. |
| 43 | |
| 44 | If you want to create a new branch whose initial content is the |
| 45 | same as an existing check-in, use this command: |
| 46 | |
| 47 | <pre> |
| 48 | <b>fossil [/help/branch|branch] new</b> <i>BRANCH-NAME BASIS</i> |
| 49 | </pre> |
| 50 | |
| 51 | The <i>BRANCH-NAME</i> argument is the name of the new branch and the |
| 52 | <i>BASIS</i> argument is the name of the check-in that the branch splits |
| 53 | off from. |
| 54 | |
| @@ -75,13 +75,13 @@ | |
| 75 | for example, it is common to give every released version a "release" tag. |
| 76 | |
| 77 | If you want add a tag to an existing check-in, you can use the |
| 78 | <b>[/help/tag|tag]</b> command. For example: |
| 79 | |
| 80 | <pre> |
| 81 | <b>fossil [/help/branch|tag] add</b> <i>TAGNAME</i> <i>CHECK-IN</i> |
| 82 | </pre> |
| 83 | |
| 84 | The CHECK-IN in the previous line can be any |
| 85 | [./checkin_names.wiki | valid check-in name format]. |
| 86 | |
| 87 | You can also add (and remove) tags from a check-in using the |
| @@ -127,25 +127,30 @@ | |
| 127 | |
| 128 | faq { |
| 129 | How do I make a clone of the fossil self-hosting repository? |
| 130 | } { |
| 131 | Any of the following commands should work: |
| 132 | |
| 133 | <pre> |
| 134 | fossil [/help/clone|clone] https://fossil-scm.org/ fossil.fossil |
| 135 | fossil [/help/clone|clone] https://www2.fossil-scm.org/ fossil.fossil |
| 136 | fossil [/help/clone|clone] https://www3.fossil-scm.org/site.cgi fossil.fossil |
| 137 | </pre> |
| 138 | |
| 139 | Once you have the repository cloned, you can open a local check-out |
| 140 | as follows: |
| 141 | |
| 142 | <pre> |
| 143 | mkdir src; cd src; fossil [/help/open|open] ../fossil.fossil |
| 144 | </pre> |
| 145 | |
| 146 | Thereafter you should be able to keep your local check-out up to date |
| 147 | with the latest code in the public repository by typing: |
| 148 | |
| 149 | <pre> |
| 150 | fossil [/help/update|update] |
| 151 | </pre> |
| 152 | } |
| 153 | |
| 154 | faq { |
| 155 | How do I import or export content from and to other version control systems? |
| 156 | } { |
| @@ -155,12 +160,11 @@ | |
| 160 | |
| 161 | |
| 162 | ############################################################################# |
| 163 | # Code to actually generate the FAQ |
| 164 | # |
| 165 | puts "<title>Fossil FAQ</title>\n" |
| 166 | puts "Note: See also <a href=\"qandc.wiki\">Questions and Criticisms</a>.\n" |
| 167 | |
| 168 | puts {<ol>} |
| 169 | for {set i 1} {$i<$cnt} {incr i} { |
| 170 | puts "<li><a href=\"#q$i\">[lindex $faq($i) 0]</a></li>" |
| @@ -170,8 +174,8 @@ | |
| 174 | |
| 175 | for {set i 1} {$i<$cnt} {incr i} { |
| 176 | puts "<p id=\"q$i\"><b>($i) [lindex $faq($i) 0]</b></p>\n" |
| 177 | set body [lindex $faq($i) 1] |
| 178 | regsub -all "\n *" [string trim $body] "\n" body |
| 179 | puts "$body</li>\n" |
| 180 | } |
| 181 | puts {</ol>} |
| 182 |
+30
-26
| --- www/faq.wiki | ||
| +++ www/faq.wiki | ||
| @@ -1,7 +1,6 @@ | ||
| 1 | 1 | <title>Fossil FAQ</title> |
| 2 | -<h1 align="center">Frequently Asked Questions</h1> | |
| 3 | 2 | |
| 4 | 3 | Note: See also <a href="qandc.wiki">Questions and Criticisms</a>. |
| 5 | 4 | |
| 6 | 5 | <ol> |
| 7 | 6 | <li><a href="#q1">What GUIs are available for fossil?</a></li> |
| @@ -15,41 +14,41 @@ | ||
| 15 | 14 | <li><a href="#q8">How do I import or export content from and to other version control systems?</a></li> |
| 16 | 15 | </ol> |
| 17 | 16 | <hr> |
| 18 | 17 | <p id="q1"><b>(1) What GUIs are available for fossil?</b></p> |
| 19 | 18 | |
| 20 | -<blockquote>The fossil executable comes with a [./webui.wiki | web-based GUI] built in. | |
| 19 | +The fossil executable comes with a [./webui.wiki | web-based GUI] built in. | |
| 21 | 20 | Just run: |
| 22 | 21 | |
| 23 | -<blockquote> | |
| 22 | +<pre> | |
| 24 | 23 | <b>fossil [/help/ui|ui]</b> <i>REPOSITORY-FILENAME</i> |
| 25 | -</blockquote> | |
| 24 | +</pre> | |
| 26 | 25 | |
| 27 | 26 | And your default web browser should pop up and automatically point to |
| 28 | 27 | the fossil interface. (Hint: You can omit the <i>REPOSITORY-FILENAME</i> |
| 29 | -if you are within an open check-out.)</blockquote></li> | |
| 28 | +if you are within an open check-out.)</li> | |
| 30 | 29 | |
| 31 | 30 | <p id="q2"><b>(2) What is the difference between a "branch" and a "fork"?</b></p> |
| 32 | 31 | |
| 33 | -<blockquote>This is a big question - too big to answer in a FAQ. Please | |
| 32 | +This is a big question - too big to answer in a FAQ. Please | |
| 34 | 33 | read the <a href="branching.wiki">Branching, Forking, Merging, |
| 35 | -and Tagging</a> document.</blockquote></li> | |
| 34 | +and Tagging</a> document.</li> | |
| 36 | 35 | |
| 37 | 36 | <p id="q3"><b>(3) How do I create a new branch?</b></p> |
| 38 | 37 | |
| 39 | -<blockquote>There are lots of ways: | |
| 38 | +There are lots of ways: | |
| 40 | 39 | |
| 41 | 40 | When you are checking in a new change using the <b>[/help/commit|commit]</b> |
| 42 | 41 | command, you can add the option "--branch <i>BRANCH-NAME</i>" to |
| 43 | 42 | make the new check-in be the first check-in for a new branch. |
| 44 | 43 | |
| 45 | 44 | If you want to create a new branch whose initial content is the |
| 46 | 45 | same as an existing check-in, use this command: |
| 47 | 46 | |
| 48 | -<blockquote> | |
| 47 | +<pre> | |
| 49 | 48 | <b>fossil [/help/branch|branch] new</b> <i>BRANCH-NAME BASIS</i> |
| 50 | -</blockquote> | |
| 49 | +</pre> | |
| 51 | 50 | |
| 52 | 51 | The <i>BRANCH-NAME</i> argument is the name of the new branch and the |
| 53 | 52 | <i>BASIS</i> argument is the name of the check-in that the branch splits |
| 54 | 53 | off from. |
| 55 | 54 | |
| @@ -59,15 +58,15 @@ | ||
| 59 | 58 | the initial check-in of your branch on the timeline and click on its |
| 60 | 59 | link so that you are on the <b>ci</b> page. Then find the "<b>edit</b>" |
| 61 | 60 | link (near the "Commands:" label) and click on that. On the |
| 62 | 61 | "Edit Check-in" page, check the box beside "Branching:" and fill in |
| 63 | 62 | the name of your new branch to the right and press the "Apply Changes" |
| 64 | -button.</blockquote></li> | |
| 63 | +button.</li> | |
| 65 | 64 | |
| 66 | 65 | <p id="q4"><b>(4) How do I tag a check-in?</b></p> |
| 67 | 66 | |
| 68 | -<blockquote>There are several ways: | |
| 67 | +There are several ways: | |
| 69 | 68 | |
| 70 | 69 | When you are checking in a new change using the <b>[/help/commit|commit]</b> |
| 71 | 70 | command, you can add a tag to that check-in using the |
| 72 | 71 | "--tag <i>TAGNAME</i>" command-line option. You can repeat the --tag |
| 73 | 72 | option to give a check-in multiple tags. Tags need not be unique. So, |
| @@ -74,13 +73,13 @@ | ||
| 74 | 73 | for example, it is common to give every released version a "release" tag. |
| 75 | 74 | |
| 76 | 75 | If you want add a tag to an existing check-in, you can use the |
| 77 | 76 | <b>[/help/tag|tag]</b> command. For example: |
| 78 | 77 | |
| 79 | -<blockquote> | |
| 78 | +<pre> | |
| 80 | 79 | <b>fossil [/help/branch|tag] add</b> <i>TAGNAME</i> <i>CHECK-IN</i> |
| 81 | -</blockquote> | |
| 80 | +</pre> | |
| 82 | 81 | |
| 83 | 82 | The CHECK-IN in the previous line can be any |
| 84 | 83 | [./checkin_names.wiki | valid check-in name format]. |
| 85 | 84 | |
| 86 | 85 | You can also add (and remove) tags from a check-in using the |
| @@ -87,16 +86,16 @@ | ||
| 87 | 86 | [./webui.wiki | web interface]. First locate the check-in that you |
| 88 | 87 | what to tag on the timeline, then click on the link to go the detailed |
| 89 | 88 | information page for that check-in. Then find the "<b>edit</b>" |
| 90 | 89 | link (near the "Commands:" label) and click on that. There are |
| 91 | 90 | controls on the edit page that allow new tags to be added and existing |
| 92 | -tags to be removed.</blockquote></li> | |
| 91 | +tags to be removed.</li> | |
| 93 | 92 | |
| 94 | 93 | <p id="q5"><b>(5) How do I create a private branch that won't get pushed back to the |
| 95 | 94 | main repository.</b></p> |
| 96 | 95 | |
| 97 | -<blockquote>Use the <b>--private</b> command-line option on the | |
| 96 | +Use the <b>--private</b> command-line option on the | |
| 98 | 97 | <b>commit</b> command. The result will be a check-in which exists on |
| 99 | 98 | your local repository only and is never pushed to other repositories. |
| 100 | 99 | All descendants of a private check-in are also private. |
| 101 | 100 | |
| 102 | 101 | Unless you specify something different using the <b>--branch</b> and/or |
| @@ -111,35 +110,40 @@ | ||
| 111 | 110 | as if all the changes that occurred on your private branch occurred in |
| 112 | 111 | a single check-in. |
| 113 | 112 | Of course, you can also keep your branch private forever simply |
| 114 | 113 | by not merging the changes in the private branch back into the trunk. |
| 115 | 114 | |
| 116 | -[./private.wiki | Additional information]</blockquote></li> | |
| 115 | +[./private.wiki | Additional information]</li> | |
| 117 | 116 | |
| 118 | 117 | <p id="q6"><b>(6) How can I delete inappropriate content from my fossil repository?</b></p> |
| 119 | 118 | |
| 120 | -<blockquote>See the article on [./shunning.wiki | "shunning"] for details.</blockquote></li> | |
| 119 | +See the article on [./shunning.wiki | "shunning"] for details.</li> | |
| 121 | 120 | |
| 122 | 121 | <p id="q7"><b>(7) How do I make a clone of the fossil self-hosting repository?</b></p> |
| 123 | 122 | |
| 124 | -<blockquote>Any of the following commands should work: | |
| 125 | -<blockquote><pre> | |
| 123 | +Any of the following commands should work: | |
| 124 | + | |
| 125 | +<pre> | |
| 126 | 126 | fossil [/help/clone|clone] https://fossil-scm.org/ fossil.fossil |
| 127 | 127 | fossil [/help/clone|clone] https://www2.fossil-scm.org/ fossil.fossil |
| 128 | 128 | fossil [/help/clone|clone] https://www3.fossil-scm.org/site.cgi fossil.fossil |
| 129 | -</pre></blockquote> | |
| 129 | +</pre> | |
| 130 | + | |
| 130 | 131 | Once you have the repository cloned, you can open a local check-out |
| 131 | 132 | as follows: |
| 132 | -<blockquote><pre> | |
| 133 | + | |
| 134 | +<pre> | |
| 133 | 135 | mkdir src; cd src; fossil [/help/open|open] ../fossil.fossil |
| 134 | -</pre></blockquote> | |
| 136 | +</pre> | |
| 137 | + | |
| 135 | 138 | Thereafter you should be able to keep your local check-out up to date |
| 136 | 139 | with the latest code in the public repository by typing: |
| 137 | -<blockquote><pre> | |
| 140 | + | |
| 141 | +<pre> | |
| 138 | 142 | fossil [/help/update|update] |
| 139 | -</pre></blockquote></blockquote></li> | |
| 143 | +</pre></li> | |
| 140 | 144 | |
| 141 | 145 | <p id="q8"><b>(8) How do I import or export content from and to other version control systems?</b></p> |
| 142 | 146 | |
| 143 | -<blockquote>Please see [./inout.wiki | Import And Export]</blockquote></li> | |
| 147 | +Please see [./inout.wiki | Import And Export]</li> | |
| 144 | 148 | |
| 145 | 149 | </ol> |
| 146 | 150 |
| --- www/faq.wiki | |
| +++ www/faq.wiki | |
| @@ -1,7 +1,6 @@ | |
| 1 | <title>Fossil FAQ</title> |
| 2 | <h1 align="center">Frequently Asked Questions</h1> |
| 3 | |
| 4 | Note: See also <a href="qandc.wiki">Questions and Criticisms</a>. |
| 5 | |
| 6 | <ol> |
| 7 | <li><a href="#q1">What GUIs are available for fossil?</a></li> |
| @@ -15,41 +14,41 @@ | |
| 15 | <li><a href="#q8">How do I import or export content from and to other version control systems?</a></li> |
| 16 | </ol> |
| 17 | <hr> |
| 18 | <p id="q1"><b>(1) What GUIs are available for fossil?</b></p> |
| 19 | |
| 20 | <blockquote>The fossil executable comes with a [./webui.wiki | web-based GUI] built in. |
| 21 | Just run: |
| 22 | |
| 23 | <blockquote> |
| 24 | <b>fossil [/help/ui|ui]</b> <i>REPOSITORY-FILENAME</i> |
| 25 | </blockquote> |
| 26 | |
| 27 | And your default web browser should pop up and automatically point to |
| 28 | the fossil interface. (Hint: You can omit the <i>REPOSITORY-FILENAME</i> |
| 29 | if you are within an open check-out.)</blockquote></li> |
| 30 | |
| 31 | <p id="q2"><b>(2) What is the difference between a "branch" and a "fork"?</b></p> |
| 32 | |
| 33 | <blockquote>This is a big question - too big to answer in a FAQ. Please |
| 34 | read the <a href="branching.wiki">Branching, Forking, Merging, |
| 35 | and Tagging</a> document.</blockquote></li> |
| 36 | |
| 37 | <p id="q3"><b>(3) How do I create a new branch?</b></p> |
| 38 | |
| 39 | <blockquote>There are lots of ways: |
| 40 | |
| 41 | When you are checking in a new change using the <b>[/help/commit|commit]</b> |
| 42 | command, you can add the option "--branch <i>BRANCH-NAME</i>" to |
| 43 | make the new check-in be the first check-in for a new branch. |
| 44 | |
| 45 | If you want to create a new branch whose initial content is the |
| 46 | same as an existing check-in, use this command: |
| 47 | |
| 48 | <blockquote> |
| 49 | <b>fossil [/help/branch|branch] new</b> <i>BRANCH-NAME BASIS</i> |
| 50 | </blockquote> |
| 51 | |
| 52 | The <i>BRANCH-NAME</i> argument is the name of the new branch and the |
| 53 | <i>BASIS</i> argument is the name of the check-in that the branch splits |
| 54 | off from. |
| 55 | |
| @@ -59,15 +58,15 @@ | |
| 59 | the initial check-in of your branch on the timeline and click on its |
| 60 | link so that you are on the <b>ci</b> page. Then find the "<b>edit</b>" |
| 61 | link (near the "Commands:" label) and click on that. On the |
| 62 | "Edit Check-in" page, check the box beside "Branching:" and fill in |
| 63 | the name of your new branch to the right and press the "Apply Changes" |
| 64 | button.</blockquote></li> |
| 65 | |
| 66 | <p id="q4"><b>(4) How do I tag a check-in?</b></p> |
| 67 | |
| 68 | <blockquote>There are several ways: |
| 69 | |
| 70 | When you are checking in a new change using the <b>[/help/commit|commit]</b> |
| 71 | command, you can add a tag to that check-in using the |
| 72 | "--tag <i>TAGNAME</i>" command-line option. You can repeat the --tag |
| 73 | option to give a check-in multiple tags. Tags need not be unique. So, |
| @@ -74,13 +73,13 @@ | |
| 74 | for example, it is common to give every released version a "release" tag. |
| 75 | |
| 76 | If you want add a tag to an existing check-in, you can use the |
| 77 | <b>[/help/tag|tag]</b> command. For example: |
| 78 | |
| 79 | <blockquote> |
| 80 | <b>fossil [/help/branch|tag] add</b> <i>TAGNAME</i> <i>CHECK-IN</i> |
| 81 | </blockquote> |
| 82 | |
| 83 | The CHECK-IN in the previous line can be any |
| 84 | [./checkin_names.wiki | valid check-in name format]. |
| 85 | |
| 86 | You can also add (and remove) tags from a check-in using the |
| @@ -87,16 +86,16 @@ | |
| 87 | [./webui.wiki | web interface]. First locate the check-in that you |
| 88 | what to tag on the timeline, then click on the link to go the detailed |
| 89 | information page for that check-in. Then find the "<b>edit</b>" |
| 90 | link (near the "Commands:" label) and click on that. There are |
| 91 | controls on the edit page that allow new tags to be added and existing |
| 92 | tags to be removed.</blockquote></li> |
| 93 | |
| 94 | <p id="q5"><b>(5) How do I create a private branch that won't get pushed back to the |
| 95 | main repository.</b></p> |
| 96 | |
| 97 | <blockquote>Use the <b>--private</b> command-line option on the |
| 98 | <b>commit</b> command. The result will be a check-in which exists on |
| 99 | your local repository only and is never pushed to other repositories. |
| 100 | All descendants of a private check-in are also private. |
| 101 | |
| 102 | Unless you specify something different using the <b>--branch</b> and/or |
| @@ -111,35 +110,40 @@ | |
| 111 | as if all the changes that occurred on your private branch occurred in |
| 112 | a single check-in. |
| 113 | Of course, you can also keep your branch private forever simply |
| 114 | by not merging the changes in the private branch back into the trunk. |
| 115 | |
| 116 | [./private.wiki | Additional information]</blockquote></li> |
| 117 | |
| 118 | <p id="q6"><b>(6) How can I delete inappropriate content from my fossil repository?</b></p> |
| 119 | |
| 120 | <blockquote>See the article on [./shunning.wiki | "shunning"] for details.</blockquote></li> |
| 121 | |
| 122 | <p id="q7"><b>(7) How do I make a clone of the fossil self-hosting repository?</b></p> |
| 123 | |
| 124 | <blockquote>Any of the following commands should work: |
| 125 | <blockquote><pre> |
| 126 | fossil [/help/clone|clone] https://fossil-scm.org/ fossil.fossil |
| 127 | fossil [/help/clone|clone] https://www2.fossil-scm.org/ fossil.fossil |
| 128 | fossil [/help/clone|clone] https://www3.fossil-scm.org/site.cgi fossil.fossil |
| 129 | </pre></blockquote> |
| 130 | Once you have the repository cloned, you can open a local check-out |
| 131 | as follows: |
| 132 | <blockquote><pre> |
| 133 | mkdir src; cd src; fossil [/help/open|open] ../fossil.fossil |
| 134 | </pre></blockquote> |
| 135 | Thereafter you should be able to keep your local check-out up to date |
| 136 | with the latest code in the public repository by typing: |
| 137 | <blockquote><pre> |
| 138 | fossil [/help/update|update] |
| 139 | </pre></blockquote></blockquote></li> |
| 140 | |
| 141 | <p id="q8"><b>(8) How do I import or export content from and to other version control systems?</b></p> |
| 142 | |
| 143 | <blockquote>Please see [./inout.wiki | Import And Export]</blockquote></li> |
| 144 | |
| 145 | </ol> |
| 146 |
| --- www/faq.wiki | |
| +++ www/faq.wiki | |
| @@ -1,7 +1,6 @@ | |
| 1 | <title>Fossil FAQ</title> |
| 2 | |
| 3 | Note: See also <a href="qandc.wiki">Questions and Criticisms</a>. |
| 4 | |
| 5 | <ol> |
| 6 | <li><a href="#q1">What GUIs are available for fossil?</a></li> |
| @@ -15,41 +14,41 @@ | |
| 14 | <li><a href="#q8">How do I import or export content from and to other version control systems?</a></li> |
| 15 | </ol> |
| 16 | <hr> |
| 17 | <p id="q1"><b>(1) What GUIs are available for fossil?</b></p> |
| 18 | |
| 19 | The fossil executable comes with a [./webui.wiki | web-based GUI] built in. |
| 20 | Just run: |
| 21 | |
| 22 | <pre> |
| 23 | <b>fossil [/help/ui|ui]</b> <i>REPOSITORY-FILENAME</i> |
| 24 | </pre> |
| 25 | |
| 26 | And your default web browser should pop up and automatically point to |
| 27 | the fossil interface. (Hint: You can omit the <i>REPOSITORY-FILENAME</i> |
| 28 | if you are within an open check-out.)</li> |
| 29 | |
| 30 | <p id="q2"><b>(2) What is the difference between a "branch" and a "fork"?</b></p> |
| 31 | |
| 32 | This is a big question - too big to answer in a FAQ. Please |
| 33 | read the <a href="branching.wiki">Branching, Forking, Merging, |
| 34 | and Tagging</a> document.</li> |
| 35 | |
| 36 | <p id="q3"><b>(3) How do I create a new branch?</b></p> |
| 37 | |
| 38 | There are lots of ways: |
| 39 | |
| 40 | When you are checking in a new change using the <b>[/help/commit|commit]</b> |
| 41 | command, you can add the option "--branch <i>BRANCH-NAME</i>" to |
| 42 | make the new check-in be the first check-in for a new branch. |
| 43 | |
| 44 | If you want to create a new branch whose initial content is the |
| 45 | same as an existing check-in, use this command: |
| 46 | |
| 47 | <pre> |
| 48 | <b>fossil [/help/branch|branch] new</b> <i>BRANCH-NAME BASIS</i> |
| 49 | </pre> |
| 50 | |
| 51 | The <i>BRANCH-NAME</i> argument is the name of the new branch and the |
| 52 | <i>BASIS</i> argument is the name of the check-in that the branch splits |
| 53 | off from. |
| 54 | |
| @@ -59,15 +58,15 @@ | |
| 58 | the initial check-in of your branch on the timeline and click on its |
| 59 | link so that you are on the <b>ci</b> page. Then find the "<b>edit</b>" |
| 60 | link (near the "Commands:" label) and click on that. On the |
| 61 | "Edit Check-in" page, check the box beside "Branching:" and fill in |
| 62 | the name of your new branch to the right and press the "Apply Changes" |
| 63 | button.</li> |
| 64 | |
| 65 | <p id="q4"><b>(4) How do I tag a check-in?</b></p> |
| 66 | |
| 67 | There are several ways: |
| 68 | |
| 69 | When you are checking in a new change using the <b>[/help/commit|commit]</b> |
| 70 | command, you can add a tag to that check-in using the |
| 71 | "--tag <i>TAGNAME</i>" command-line option. You can repeat the --tag |
| 72 | option to give a check-in multiple tags. Tags need not be unique. So, |
| @@ -74,13 +73,13 @@ | |
| 73 | for example, it is common to give every released version a "release" tag. |
| 74 | |
| 75 | If you want add a tag to an existing check-in, you can use the |
| 76 | <b>[/help/tag|tag]</b> command. For example: |
| 77 | |
| 78 | <pre> |
| 79 | <b>fossil [/help/branch|tag] add</b> <i>TAGNAME</i> <i>CHECK-IN</i> |
| 80 | </pre> |
| 81 | |
| 82 | The CHECK-IN in the previous line can be any |
| 83 | [./checkin_names.wiki | valid check-in name format]. |
| 84 | |
| 85 | You can also add (and remove) tags from a check-in using the |
| @@ -87,16 +86,16 @@ | |
| 86 | [./webui.wiki | web interface]. First locate the check-in that you |
| 87 | what to tag on the timeline, then click on the link to go the detailed |
| 88 | information page for that check-in. Then find the "<b>edit</b>" |
| 89 | link (near the "Commands:" label) and click on that. There are |
| 90 | controls on the edit page that allow new tags to be added and existing |
| 91 | tags to be removed.</li> |
| 92 | |
| 93 | <p id="q5"><b>(5) How do I create a private branch that won't get pushed back to the |
| 94 | main repository.</b></p> |
| 95 | |
| 96 | Use the <b>--private</b> command-line option on the |
| 97 | <b>commit</b> command. The result will be a check-in which exists on |
| 98 | your local repository only and is never pushed to other repositories. |
| 99 | All descendants of a private check-in are also private. |
| 100 | |
| 101 | Unless you specify something different using the <b>--branch</b> and/or |
| @@ -111,35 +110,40 @@ | |
| 110 | as if all the changes that occurred on your private branch occurred in |
| 111 | a single check-in. |
| 112 | Of course, you can also keep your branch private forever simply |
| 113 | by not merging the changes in the private branch back into the trunk. |
| 114 | |
| 115 | [./private.wiki | Additional information]</li> |
| 116 | |
| 117 | <p id="q6"><b>(6) How can I delete inappropriate content from my fossil repository?</b></p> |
| 118 | |
| 119 | See the article on [./shunning.wiki | "shunning"] for details.</li> |
| 120 | |
| 121 | <p id="q7"><b>(7) How do I make a clone of the fossil self-hosting repository?</b></p> |
| 122 | |
| 123 | Any of the following commands should work: |
| 124 | |
| 125 | <pre> |
| 126 | fossil [/help/clone|clone] https://fossil-scm.org/ fossil.fossil |
| 127 | fossil [/help/clone|clone] https://www2.fossil-scm.org/ fossil.fossil |
| 128 | fossil [/help/clone|clone] https://www3.fossil-scm.org/site.cgi fossil.fossil |
| 129 | </pre> |
| 130 | |
| 131 | Once you have the repository cloned, you can open a local check-out |
| 132 | as follows: |
| 133 | |
| 134 | <pre> |
| 135 | mkdir src; cd src; fossil [/help/open|open] ../fossil.fossil |
| 136 | </pre> |
| 137 | |
| 138 | Thereafter you should be able to keep your local check-out up to date |
| 139 | with the latest code in the public repository by typing: |
| 140 | |
| 141 | <pre> |
| 142 | fossil [/help/update|update] |
| 143 | </pre></li> |
| 144 | |
| 145 | <p id="q8"><b>(8) How do I import or export content from and to other version control systems?</b></p> |
| 146 | |
| 147 | Please see [./inout.wiki | Import And Export]</li> |
| 148 | |
| 149 | </ol> |
| 150 |
+22
-28
| --- www/fileformat.wiki | ||
| +++ www/fileformat.wiki | ||
| @@ -1,9 +1,6 @@ | ||
| 1 | 1 | <title>Fossil File Formats</title> |
| 2 | -<h1 align="center"> | |
| 3 | -Fossil File Formats | |
| 4 | -</h1> | |
| 5 | 2 | |
| 6 | 3 | The global state of a fossil repository is kept simple so that it can |
| 7 | 4 | endure in useful form for decades or centuries. |
| 8 | 5 | A fossil repository is intended to be readable, |
| 9 | 6 | searchable, and extensible by people not yet born. |
| @@ -110,11 +107,11 @@ | ||
| 110 | 107 | the check-in was created, and any check-in comments associated |
| 111 | 108 | with the check-in. |
| 112 | 109 | |
| 113 | 110 | Allowed cards in the manifest are as follows: |
| 114 | 111 | |
| 115 | -<blockquote> | |
| 112 | +<p class="indent"> | |
| 116 | 113 | <b>B</b> <i>baseline-manifest</i><br> |
| 117 | 114 | <b>C</b> <i>checkin-comment</i><br> |
| 118 | 115 | <b>D</b> <i>time-and-date-stamp</i><br> |
| 119 | 116 | <b>F</b> <i>filename</i> ?<i>hash</i>? ?<i>permissions</i>? ?<i>old-name</i>?<br> |
| 120 | 117 | <b>N</b> <i>mimetype</i><br> |
| @@ -122,11 +119,11 @@ | ||
| 122 | 119 | <b>Q</b> (<b>+</b>|<b>-</b>)<i>artifact-hash</i> ?<i>artifact-hash</i>?<br> |
| 123 | 120 | <b>R</b> <i>repository-checksum</i><br> |
| 124 | 121 | <b>T</b> (<b>+</b>|<b>-</b>|<b>*</b>)<i>tag-name</i> <b>*</b> ?<i>value</i>?<br> |
| 125 | 122 | <b>U</b> <i>user-login</i><br> |
| 126 | 123 | <b>Z</b> <i>manifest-checksum</i> |
| 127 | -</blockquote> | |
| 124 | +</p> | |
| 128 | 125 | |
| 129 | 126 | A manifest may optionally have a single <b>B</b> card. The <b>B</b> card specifies |
| 130 | 127 | another manifest that serves as the "baseline" for this manifest. A |
| 131 | 128 | manifest that has a <b>B</b> card is called a delta-manifest and a manifest |
| 132 | 129 | that omits the <b>B</b> card is a baseline-manifest. The other manifest |
| @@ -148,14 +145,14 @@ | ||
| 148 | 145 | A manifest must have exactly one <b>D</b> card. The sole argument to |
| 149 | 146 | the <b>D</b> card is a date-time stamp in the ISO8601 format. The |
| 150 | 147 | date and time should be in coordinated universal time (UTC). |
| 151 | 148 | The format one of: |
| 152 | 149 | |
| 153 | -<blockquote> | |
| 150 | +<p class="indent"> | |
| 154 | 151 | <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> |
| 155 | 152 | <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> |
| 156 | -</blockquote> | |
| 153 | +</p> | |
| 157 | 154 | |
| 158 | 155 | A manifest has zero or more <b>F</b> cards. Each <b>F</b> card identifies a file |
| 159 | 156 | that is part of the check-in. There are one, two, three, or four |
| 160 | 157 | arguments. The first argument is the pathname of the file in the |
| 161 | 158 | check-in relative to the root of the project file hierarchy. No ".." |
| @@ -263,14 +260,14 @@ | ||
| 263 | 260 | may be removed from a repository without loss or damage to the |
| 264 | 261 | underlying project code. |
| 265 | 262 | |
| 266 | 263 | Allowed cards in the cluster are as follows: |
| 267 | 264 | |
| 268 | -<blockquote> | |
| 265 | +<p class="indent"> | |
| 269 | 266 | <b>M</b> <i>artifact-id</i><br /> |
| 270 | 267 | <b>Z</b> <i>checksum</i> |
| 271 | -</blockquote> | |
| 268 | +</p> | |
| 272 | 269 | |
| 273 | 270 | A cluster contains one or more <b>M</b> cards followed by a single <b>Z</b> card. |
| 274 | 271 | Each <b>M</b> card has a single argument which is the artifact ID of |
| 275 | 272 | another artifact in the repository. The <b>Z</b> card works exactly like |
| 276 | 273 | the <b>Z</b> card of a manifest. The argument to the <b>Z</b> card is the |
| @@ -284,16 +281,16 @@ | ||
| 284 | 281 | |
| 285 | 282 | Control artifacts are used to assign properties to other artifacts |
| 286 | 283 | within the repository. |
| 287 | 284 | Allowed cards in a control artifact are as follows: |
| 288 | 285 | |
| 289 | -<blockquote> | |
| 286 | +<p class="indent"> | |
| 290 | 287 | <b>D</b> <i>time-and-date-stamp</i><br /> |
| 291 | 288 | <b>T</b> (<b>+</b>|<b>-</b>|<b>*</b>)<i>tag-name</i> <i>artifact-id</i> ?<i>value</i>?<br /> |
| 292 | 289 | <b>U</b> <i>user-name</i><br /> |
| 293 | 290 | <b>Z</b> <i>checksum</i><br /> |
| 294 | -</blockquote> | |
| 291 | +</p> | |
| 295 | 292 | |
| 296 | 293 | A control artifact must have one <b>D</b> card, one <b>U</b> card, one <b>Z</b> card and |
| 297 | 294 | one or more <b>T</b> cards. No other cards or other text is |
| 298 | 295 | allowed in a control artifact. Control artifacts might be PGP |
| 299 | 296 | clearsigned. |
| @@ -338,20 +335,20 @@ | ||
| 338 | 335 | A wiki artifact defines a single version of a |
| 339 | 336 | single wiki page. |
| 340 | 337 | Wiki artifacts accept |
| 341 | 338 | the following card types: |
| 342 | 339 | |
| 343 | -<blockquote> | |
| 340 | +<p class="indent"> | |
| 344 | 341 | <b>C</b> <i>change-comment</i><br> |
| 345 | 342 | <b>D</b> <i>time-and-date-stamp</i><br /> |
| 346 | 343 | <b>L</b> <i>wiki-title</i><br /> |
| 347 | 344 | <b>N</b> <i>mimetype</i><br /> |
| 348 | 345 | <b>P</b> <i>parent-artifact-id</i>+<br /> |
| 349 | 346 | <b>U</b> <i>user-name</i><br /> |
| 350 | 347 | <b>W</b> <i>size</i> <b>\n</b> <i>text</i> <b>\n</b><br /> |
| 351 | 348 | <b>Z</b> <i>checksum</i> |
| 352 | -</blockquote> | |
| 349 | +</p> | |
| 353 | 350 | |
| 354 | 351 | The <b>D</b> card is the date and time when the wiki page was edited. |
| 355 | 352 | The <b>P</b> card specifies the parent wiki pages, if any. The <b>L</b> card |
| 356 | 353 | gives the name of the wiki page. The optional <b>N</b> card specifies |
| 357 | 354 | the mimetype of the wiki text. If the <b>N</b> card is omitted, the |
| @@ -379,17 +376,17 @@ | ||
| 379 | 376 | <h3 id="tktchng">2.5 Ticket Changes</h3> |
| 380 | 377 | |
| 381 | 378 | A ticket-change artifact represents a change to a trouble ticket. |
| 382 | 379 | The following cards are allowed on a ticket change artifact: |
| 383 | 380 | |
| 384 | -<blockquote> | |
| 381 | +<p class="indent"> | |
| 385 | 382 | <b>D</b> <i>time-and-date-stamp</i><br /> |
| 386 | 383 | <b>J</b> ?<b>+</b>?<i>name</i> ?<i>value</i>?<br /> |
| 387 | 384 | <b>K</b> <i>ticket-id</i><br /> |
| 388 | 385 | <b>U</b> <i>user-name</i><br /> |
| 389 | 386 | <b>Z</b> <i>checksum</i> |
| 390 | -</blockquote> | |
| 387 | +</p> | |
| 391 | 388 | |
| 392 | 389 | The <b>D</b> card is the usual date and time stamp and represents the point |
| 393 | 390 | in time when the change was entered. The <b>U</b> card is the login of the |
| 394 | 391 | programmer who entered this change. The <b>Z</b> card is the required checksum over |
| 395 | 392 | the entire artifact. |
| @@ -427,18 +424,18 @@ | ||
| 427 | 424 | attachment (the source artifact) with a ticket or wiki page or |
| 428 | 425 | technical note to which |
| 429 | 426 | the attachment is connected (the target artifact). |
| 430 | 427 | The following cards are allowed on an attachment artifact: |
| 431 | 428 | |
| 432 | -<blockquote> | |
| 429 | +<p class="indent"> | |
| 433 | 430 | <b>A</b> <i>filename target</i> ?<i>source</i>?<br /> |
| 434 | 431 | <b>C</b> <i>comment</i><br /> |
| 435 | 432 | <b>D</b> <i>time-and-date-stamp</i><br /> |
| 436 | 433 | <b>N</b> <i>mimetype</i><br /> |
| 437 | 434 | <b>U</b> <i>user-name</i><br /> |
| 438 | 435 | <b>Z</b> <i>checksum</i> |
| 439 | -</blockquote> | |
| 436 | +</p> | |
| 440 | 437 | |
| 441 | 438 | The <b>A</b> card specifies a filename for the attachment in its first argument. |
| 442 | 439 | The second argument to the <b>A</b> card is the name of the wiki page or |
| 443 | 440 | ticket or technical note to which the attachment is connected. The |
| 444 | 441 | third argument is either missing or else it is the lower-case artifact |
| @@ -469,21 +466,21 @@ | ||
| 469 | 466 | (similar to a wiki page) with a point in time. Technotes can be used |
| 470 | 467 | to record project milestones, release notes, blog entries, process |
| 471 | 468 | checkpoints, or news articles. |
| 472 | 469 | The following cards are allowed on an technote artifact: |
| 473 | 470 | |
| 474 | -<blockquote> | |
| 471 | +<p class="indent"> | |
| 475 | 472 | <b>C</b> <i>comment</i><br> |
| 476 | 473 | <b>D</b> <i>time-and-date-stamp</i><br /> |
| 477 | 474 | <b>E</b> <i>technote-time</i> <i>technote-id</i><br /> |
| 478 | 475 | <b>N</b> <i>mimetype</i><br /> |
| 479 | 476 | <b>P</b> <i>parent-artifact-id</i>+<br /> |
| 480 | 477 | <b>T</b> <b>+</b><i>tag-name</i> <b>*</b> ?<i>value</i>?<br /> |
| 481 | 478 | <b>U</b> <i>user-name</i><br /> |
| 482 | 479 | <b>W</b> <i>size</i> <b>\n</b> <i>text</i> <b>\n</b><br /> |
| 483 | 480 | <b>Z</b> <i>checksum</i> |
| 484 | -</blockquote> | |
| 481 | +</p> | |
| 485 | 482 | |
| 486 | 483 | The <b>C</b> card contains text that is displayed on the timeline for the |
| 487 | 484 | technote. The <b>C</b> card is optional, but there can only be one. |
| 488 | 485 | |
| 489 | 486 | A single <b>D</b> card is required to give the date and time when the |
| @@ -534,21 +531,21 @@ | ||
| 534 | 531 | Forum posts are intended as a mechanism for users and developers to |
| 535 | 532 | discuss a project. Forum posts are like messages on a mailing list. |
| 536 | 533 | |
| 537 | 534 | The following cards are allowed on an forum post artifact: |
| 538 | 535 | |
| 539 | -<blockquote> | |
| 536 | +<p class="indent"> | |
| 540 | 537 | <b>D</b> <i>time-and-date-stamp</i><br /> |
| 541 | 538 | <b>G</b> <i>thread-root</i><br /> |
| 542 | 539 | <b>H</b> <i>thread-title</i><br /> |
| 543 | 540 | <b>I</b> <i>in-reply-to</i><br /> |
| 544 | 541 | <b>N</b> <i>mimetype</i><br /> |
| 545 | 542 | <b>P</b> <i>parent-artifact-id</i><br /> |
| 546 | 543 | <b>U</b> <i>user-name</i><br /> |
| 547 | 544 | <b>W</b> <i>size</i> <b>\n</b> <i>text</i> <b>\n</b><br /> |
| 548 | 545 | <b>Z</b> <i>checksum</i> |
| 549 | -</blockquote> | |
| 546 | +</p> | |
| 550 | 547 | |
| 551 | 548 | Every forum post must have either one <b>I</b> card and one <b>G</b> card |
| 552 | 549 | or one <b>H</b> card. |
| 553 | 550 | Forum posts are organized into topic threads. The initial |
| 554 | 551 | post for a thread (the root post) has an <b>H</b> card giving the title or |
| @@ -610,16 +607,13 @@ | ||
| 610 | 607 | artifact is not legal. A number or range of numbers indicates the number |
| 611 | 608 | of times a card may (or must) appear in the corresponding artifact type. |
| 612 | 609 | e.g. a value of 1 indicates a required unique card and 1+ indicates that one |
| 613 | 610 | or more such cards are required. |
| 614 | 611 | |
| 615 | -<table border=1 width="100%"> | |
| 612 | +<table> | |
| 616 | 613 | <tr> |
| 617 | -<th rowspan=2 valign=bottom>Card Format</th> | |
| 618 | -<th colspan=8>Used By</th> | |
| 619 | -</tr> | |
| 620 | -<tr> | |
| 614 | +<th>⇩ Card Format / Used By ⇨</th> | |
| 621 | 615 | <th>Manifest</th> |
| 622 | 616 | <th>Cluster</th> |
| 623 | 617 | <th>Control</th> |
| 624 | 618 | <th>Wiki</th> |
| 625 | 619 | <th>Ticket</th> |
| @@ -909,15 +903,15 @@ | ||
| 909 | 903 | Both bugs have now been fixed. However, to prevent historical |
| 910 | 904 | Technical Note artifacts that were inserted by users in good faith |
| 911 | 905 | from being rejected by newer Fossil builds, the card ordering |
| 912 | 906 | requirement is relaxed slightly. The actual implementation is this: |
| 913 | 907 | |
| 914 | -<blockquote> | |
| 908 | +<p class=blockquote> | |
| 915 | 909 | "All cards must be in strict lexicographic order, except that the |
| 916 | 910 | N and P cards of a Technical Note artifact are allowed to be |
| 917 | 911 | interchanged." |
| 918 | -</blockquote> | |
| 912 | +</p> | |
| 919 | 913 | |
| 920 | 914 | Future versions of Fossil might strengthen this slightly to only allow |
| 921 | 915 | the out of order N and P cards for Technical Notes entered before |
| 922 | 916 | a certain date. |
| 923 | 917 | |
| 924 | 918 |
| --- www/fileformat.wiki | |
| +++ www/fileformat.wiki | |
| @@ -1,9 +1,6 @@ | |
| 1 | <title>Fossil File Formats</title> |
| 2 | <h1 align="center"> |
| 3 | Fossil File Formats |
| 4 | </h1> |
| 5 | |
| 6 | The global state of a fossil repository is kept simple so that it can |
| 7 | endure in useful form for decades or centuries. |
| 8 | A fossil repository is intended to be readable, |
| 9 | searchable, and extensible by people not yet born. |
| @@ -110,11 +107,11 @@ | |
| 110 | the check-in was created, and any check-in comments associated |
| 111 | with the check-in. |
| 112 | |
| 113 | Allowed cards in the manifest are as follows: |
| 114 | |
| 115 | <blockquote> |
| 116 | <b>B</b> <i>baseline-manifest</i><br> |
| 117 | <b>C</b> <i>checkin-comment</i><br> |
| 118 | <b>D</b> <i>time-and-date-stamp</i><br> |
| 119 | <b>F</b> <i>filename</i> ?<i>hash</i>? ?<i>permissions</i>? ?<i>old-name</i>?<br> |
| 120 | <b>N</b> <i>mimetype</i><br> |
| @@ -122,11 +119,11 @@ | |
| 122 | <b>Q</b> (<b>+</b>|<b>-</b>)<i>artifact-hash</i> ?<i>artifact-hash</i>?<br> |
| 123 | <b>R</b> <i>repository-checksum</i><br> |
| 124 | <b>T</b> (<b>+</b>|<b>-</b>|<b>*</b>)<i>tag-name</i> <b>*</b> ?<i>value</i>?<br> |
| 125 | <b>U</b> <i>user-login</i><br> |
| 126 | <b>Z</b> <i>manifest-checksum</i> |
| 127 | </blockquote> |
| 128 | |
| 129 | A manifest may optionally have a single <b>B</b> card. The <b>B</b> card specifies |
| 130 | another manifest that serves as the "baseline" for this manifest. A |
| 131 | manifest that has a <b>B</b> card is called a delta-manifest and a manifest |
| 132 | that omits the <b>B</b> card is a baseline-manifest. The other manifest |
| @@ -148,14 +145,14 @@ | |
| 148 | A manifest must have exactly one <b>D</b> card. The sole argument to |
| 149 | the <b>D</b> card is a date-time stamp in the ISO8601 format. The |
| 150 | date and time should be in coordinated universal time (UTC). |
| 151 | The format one of: |
| 152 | |
| 153 | <blockquote> |
| 154 | <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> |
| 155 | <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> |
| 156 | </blockquote> |
| 157 | |
| 158 | A manifest has zero or more <b>F</b> cards. Each <b>F</b> card identifies a file |
| 159 | that is part of the check-in. There are one, two, three, or four |
| 160 | arguments. The first argument is the pathname of the file in the |
| 161 | check-in relative to the root of the project file hierarchy. No ".." |
| @@ -263,14 +260,14 @@ | |
| 263 | may be removed from a repository without loss or damage to the |
| 264 | underlying project code. |
| 265 | |
| 266 | Allowed cards in the cluster are as follows: |
| 267 | |
| 268 | <blockquote> |
| 269 | <b>M</b> <i>artifact-id</i><br /> |
| 270 | <b>Z</b> <i>checksum</i> |
| 271 | </blockquote> |
| 272 | |
| 273 | A cluster contains one or more <b>M</b> cards followed by a single <b>Z</b> card. |
| 274 | Each <b>M</b> card has a single argument which is the artifact ID of |
| 275 | another artifact in the repository. The <b>Z</b> card works exactly like |
| 276 | the <b>Z</b> card of a manifest. The argument to the <b>Z</b> card is the |
| @@ -284,16 +281,16 @@ | |
| 284 | |
| 285 | Control artifacts are used to assign properties to other artifacts |
| 286 | within the repository. |
| 287 | Allowed cards in a control artifact are as follows: |
| 288 | |
| 289 | <blockquote> |
| 290 | <b>D</b> <i>time-and-date-stamp</i><br /> |
| 291 | <b>T</b> (<b>+</b>|<b>-</b>|<b>*</b>)<i>tag-name</i> <i>artifact-id</i> ?<i>value</i>?<br /> |
| 292 | <b>U</b> <i>user-name</i><br /> |
| 293 | <b>Z</b> <i>checksum</i><br /> |
| 294 | </blockquote> |
| 295 | |
| 296 | A control artifact must have one <b>D</b> card, one <b>U</b> card, one <b>Z</b> card and |
| 297 | one or more <b>T</b> cards. No other cards or other text is |
| 298 | allowed in a control artifact. Control artifacts might be PGP |
| 299 | clearsigned. |
| @@ -338,20 +335,20 @@ | |
| 338 | A wiki artifact defines a single version of a |
| 339 | single wiki page. |
| 340 | Wiki artifacts accept |
| 341 | the following card types: |
| 342 | |
| 343 | <blockquote> |
| 344 | <b>C</b> <i>change-comment</i><br> |
| 345 | <b>D</b> <i>time-and-date-stamp</i><br /> |
| 346 | <b>L</b> <i>wiki-title</i><br /> |
| 347 | <b>N</b> <i>mimetype</i><br /> |
| 348 | <b>P</b> <i>parent-artifact-id</i>+<br /> |
| 349 | <b>U</b> <i>user-name</i><br /> |
| 350 | <b>W</b> <i>size</i> <b>\n</b> <i>text</i> <b>\n</b><br /> |
| 351 | <b>Z</b> <i>checksum</i> |
| 352 | </blockquote> |
| 353 | |
| 354 | The <b>D</b> card is the date and time when the wiki page was edited. |
| 355 | The <b>P</b> card specifies the parent wiki pages, if any. The <b>L</b> card |
| 356 | gives the name of the wiki page. The optional <b>N</b> card specifies |
| 357 | the mimetype of the wiki text. If the <b>N</b> card is omitted, the |
| @@ -379,17 +376,17 @@ | |
| 379 | <h3 id="tktchng">2.5 Ticket Changes</h3> |
| 380 | |
| 381 | A ticket-change artifact represents a change to a trouble ticket. |
| 382 | The following cards are allowed on a ticket change artifact: |
| 383 | |
| 384 | <blockquote> |
| 385 | <b>D</b> <i>time-and-date-stamp</i><br /> |
| 386 | <b>J</b> ?<b>+</b>?<i>name</i> ?<i>value</i>?<br /> |
| 387 | <b>K</b> <i>ticket-id</i><br /> |
| 388 | <b>U</b> <i>user-name</i><br /> |
| 389 | <b>Z</b> <i>checksum</i> |
| 390 | </blockquote> |
| 391 | |
| 392 | The <b>D</b> card is the usual date and time stamp and represents the point |
| 393 | in time when the change was entered. The <b>U</b> card is the login of the |
| 394 | programmer who entered this change. The <b>Z</b> card is the required checksum over |
| 395 | the entire artifact. |
| @@ -427,18 +424,18 @@ | |
| 427 | attachment (the source artifact) with a ticket or wiki page or |
| 428 | technical note to which |
| 429 | the attachment is connected (the target artifact). |
| 430 | The following cards are allowed on an attachment artifact: |
| 431 | |
| 432 | <blockquote> |
| 433 | <b>A</b> <i>filename target</i> ?<i>source</i>?<br /> |
| 434 | <b>C</b> <i>comment</i><br /> |
| 435 | <b>D</b> <i>time-and-date-stamp</i><br /> |
| 436 | <b>N</b> <i>mimetype</i><br /> |
| 437 | <b>U</b> <i>user-name</i><br /> |
| 438 | <b>Z</b> <i>checksum</i> |
| 439 | </blockquote> |
| 440 | |
| 441 | The <b>A</b> card specifies a filename for the attachment in its first argument. |
| 442 | The second argument to the <b>A</b> card is the name of the wiki page or |
| 443 | ticket or technical note to which the attachment is connected. The |
| 444 | third argument is either missing or else it is the lower-case artifact |
| @@ -469,21 +466,21 @@ | |
| 469 | (similar to a wiki page) with a point in time. Technotes can be used |
| 470 | to record project milestones, release notes, blog entries, process |
| 471 | checkpoints, or news articles. |
| 472 | The following cards are allowed on an technote artifact: |
| 473 | |
| 474 | <blockquote> |
| 475 | <b>C</b> <i>comment</i><br> |
| 476 | <b>D</b> <i>time-and-date-stamp</i><br /> |
| 477 | <b>E</b> <i>technote-time</i> <i>technote-id</i><br /> |
| 478 | <b>N</b> <i>mimetype</i><br /> |
| 479 | <b>P</b> <i>parent-artifact-id</i>+<br /> |
| 480 | <b>T</b> <b>+</b><i>tag-name</i> <b>*</b> ?<i>value</i>?<br /> |
| 481 | <b>U</b> <i>user-name</i><br /> |
| 482 | <b>W</b> <i>size</i> <b>\n</b> <i>text</i> <b>\n</b><br /> |
| 483 | <b>Z</b> <i>checksum</i> |
| 484 | </blockquote> |
| 485 | |
| 486 | The <b>C</b> card contains text that is displayed on the timeline for the |
| 487 | technote. The <b>C</b> card is optional, but there can only be one. |
| 488 | |
| 489 | A single <b>D</b> card is required to give the date and time when the |
| @@ -534,21 +531,21 @@ | |
| 534 | Forum posts are intended as a mechanism for users and developers to |
| 535 | discuss a project. Forum posts are like messages on a mailing list. |
| 536 | |
| 537 | The following cards are allowed on an forum post artifact: |
| 538 | |
| 539 | <blockquote> |
| 540 | <b>D</b> <i>time-and-date-stamp</i><br /> |
| 541 | <b>G</b> <i>thread-root</i><br /> |
| 542 | <b>H</b> <i>thread-title</i><br /> |
| 543 | <b>I</b> <i>in-reply-to</i><br /> |
| 544 | <b>N</b> <i>mimetype</i><br /> |
| 545 | <b>P</b> <i>parent-artifact-id</i><br /> |
| 546 | <b>U</b> <i>user-name</i><br /> |
| 547 | <b>W</b> <i>size</i> <b>\n</b> <i>text</i> <b>\n</b><br /> |
| 548 | <b>Z</b> <i>checksum</i> |
| 549 | </blockquote> |
| 550 | |
| 551 | Every forum post must have either one <b>I</b> card and one <b>G</b> card |
| 552 | or one <b>H</b> card. |
| 553 | Forum posts are organized into topic threads. The initial |
| 554 | post for a thread (the root post) has an <b>H</b> card giving the title or |
| @@ -610,16 +607,13 @@ | |
| 610 | artifact is not legal. A number or range of numbers indicates the number |
| 611 | of times a card may (or must) appear in the corresponding artifact type. |
| 612 | e.g. a value of 1 indicates a required unique card and 1+ indicates that one |
| 613 | or more such cards are required. |
| 614 | |
| 615 | <table border=1 width="100%"> |
| 616 | <tr> |
| 617 | <th rowspan=2 valign=bottom>Card Format</th> |
| 618 | <th colspan=8>Used By</th> |
| 619 | </tr> |
| 620 | <tr> |
| 621 | <th>Manifest</th> |
| 622 | <th>Cluster</th> |
| 623 | <th>Control</th> |
| 624 | <th>Wiki</th> |
| 625 | <th>Ticket</th> |
| @@ -909,15 +903,15 @@ | |
| 909 | Both bugs have now been fixed. However, to prevent historical |
| 910 | Technical Note artifacts that were inserted by users in good faith |
| 911 | from being rejected by newer Fossil builds, the card ordering |
| 912 | requirement is relaxed slightly. The actual implementation is this: |
| 913 | |
| 914 | <blockquote> |
| 915 | "All cards must be in strict lexicographic order, except that the |
| 916 | N and P cards of a Technical Note artifact are allowed to be |
| 917 | interchanged." |
| 918 | </blockquote> |
| 919 | |
| 920 | Future versions of Fossil might strengthen this slightly to only allow |
| 921 | the out of order N and P cards for Technical Notes entered before |
| 922 | a certain date. |
| 923 | |
| 924 |
| --- www/fileformat.wiki | |
| +++ www/fileformat.wiki | |
| @@ -1,9 +1,6 @@ | |
| 1 | <title>Fossil File Formats</title> |
| 2 | |
| 3 | The global state of a fossil repository is kept simple so that it can |
| 4 | endure in useful form for decades or centuries. |
| 5 | A fossil repository is intended to be readable, |
| 6 | searchable, and extensible by people not yet born. |
| @@ -110,11 +107,11 @@ | |
| 107 | the check-in was created, and any check-in comments associated |
| 108 | with the check-in. |
| 109 | |
| 110 | Allowed cards in the manifest are as follows: |
| 111 | |
| 112 | <p class="indent"> |
| 113 | <b>B</b> <i>baseline-manifest</i><br> |
| 114 | <b>C</b> <i>checkin-comment</i><br> |
| 115 | <b>D</b> <i>time-and-date-stamp</i><br> |
| 116 | <b>F</b> <i>filename</i> ?<i>hash</i>? ?<i>permissions</i>? ?<i>old-name</i>?<br> |
| 117 | <b>N</b> <i>mimetype</i><br> |
| @@ -122,11 +119,11 @@ | |
| 119 | <b>Q</b> (<b>+</b>|<b>-</b>)<i>artifact-hash</i> ?<i>artifact-hash</i>?<br> |
| 120 | <b>R</b> <i>repository-checksum</i><br> |
| 121 | <b>T</b> (<b>+</b>|<b>-</b>|<b>*</b>)<i>tag-name</i> <b>*</b> ?<i>value</i>?<br> |
| 122 | <b>U</b> <i>user-login</i><br> |
| 123 | <b>Z</b> <i>manifest-checksum</i> |
| 124 | </p> |
| 125 | |
| 126 | A manifest may optionally have a single <b>B</b> card. The <b>B</b> card specifies |
| 127 | another manifest that serves as the "baseline" for this manifest. A |
| 128 | manifest that has a <b>B</b> card is called a delta-manifest and a manifest |
| 129 | that omits the <b>B</b> card is a baseline-manifest. The other manifest |
| @@ -148,14 +145,14 @@ | |
| 145 | A manifest must have exactly one <b>D</b> card. The sole argument to |
| 146 | the <b>D</b> card is a date-time stamp in the ISO8601 format. The |
| 147 | date and time should be in coordinated universal time (UTC). |
| 148 | The format one of: |
| 149 | |
| 150 | <p class="indent"> |
| 151 | <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> |
| 152 | <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> |
| 153 | </p> |
| 154 | |
| 155 | A manifest has zero or more <b>F</b> cards. Each <b>F</b> card identifies a file |
| 156 | that is part of the check-in. There are one, two, three, or four |
| 157 | arguments. The first argument is the pathname of the file in the |
| 158 | check-in relative to the root of the project file hierarchy. No ".." |
| @@ -263,14 +260,14 @@ | |
| 260 | may be removed from a repository without loss or damage to the |
| 261 | underlying project code. |
| 262 | |
| 263 | Allowed cards in the cluster are as follows: |
| 264 | |
| 265 | <p class="indent"> |
| 266 | <b>M</b> <i>artifact-id</i><br /> |
| 267 | <b>Z</b> <i>checksum</i> |
| 268 | </p> |
| 269 | |
| 270 | A cluster contains one or more <b>M</b> cards followed by a single <b>Z</b> card. |
| 271 | Each <b>M</b> card has a single argument which is the artifact ID of |
| 272 | another artifact in the repository. The <b>Z</b> card works exactly like |
| 273 | the <b>Z</b> card of a manifest. The argument to the <b>Z</b> card is the |
| @@ -284,16 +281,16 @@ | |
| 281 | |
| 282 | Control artifacts are used to assign properties to other artifacts |
| 283 | within the repository. |
| 284 | Allowed cards in a control artifact are as follows: |
| 285 | |
| 286 | <p class="indent"> |
| 287 | <b>D</b> <i>time-and-date-stamp</i><br /> |
| 288 | <b>T</b> (<b>+</b>|<b>-</b>|<b>*</b>)<i>tag-name</i> <i>artifact-id</i> ?<i>value</i>?<br /> |
| 289 | <b>U</b> <i>user-name</i><br /> |
| 290 | <b>Z</b> <i>checksum</i><br /> |
| 291 | </p> |
| 292 | |
| 293 | A control artifact must have one <b>D</b> card, one <b>U</b> card, one <b>Z</b> card and |
| 294 | one or more <b>T</b> cards. No other cards or other text is |
| 295 | allowed in a control artifact. Control artifacts might be PGP |
| 296 | clearsigned. |
| @@ -338,20 +335,20 @@ | |
| 335 | A wiki artifact defines a single version of a |
| 336 | single wiki page. |
| 337 | Wiki artifacts accept |
| 338 | the following card types: |
| 339 | |
| 340 | <p class="indent"> |
| 341 | <b>C</b> <i>change-comment</i><br> |
| 342 | <b>D</b> <i>time-and-date-stamp</i><br /> |
| 343 | <b>L</b> <i>wiki-title</i><br /> |
| 344 | <b>N</b> <i>mimetype</i><br /> |
| 345 | <b>P</b> <i>parent-artifact-id</i>+<br /> |
| 346 | <b>U</b> <i>user-name</i><br /> |
| 347 | <b>W</b> <i>size</i> <b>\n</b> <i>text</i> <b>\n</b><br /> |
| 348 | <b>Z</b> <i>checksum</i> |
| 349 | </p> |
| 350 | |
| 351 | The <b>D</b> card is the date and time when the wiki page was edited. |
| 352 | The <b>P</b> card specifies the parent wiki pages, if any. The <b>L</b> card |
| 353 | gives the name of the wiki page. The optional <b>N</b> card specifies |
| 354 | the mimetype of the wiki text. If the <b>N</b> card is omitted, the |
| @@ -379,17 +376,17 @@ | |
| 376 | <h3 id="tktchng">2.5 Ticket Changes</h3> |
| 377 | |
| 378 | A ticket-change artifact represents a change to a trouble ticket. |
| 379 | The following cards are allowed on a ticket change artifact: |
| 380 | |
| 381 | <p class="indent"> |
| 382 | <b>D</b> <i>time-and-date-stamp</i><br /> |
| 383 | <b>J</b> ?<b>+</b>?<i>name</i> ?<i>value</i>?<br /> |
| 384 | <b>K</b> <i>ticket-id</i><br /> |
| 385 | <b>U</b> <i>user-name</i><br /> |
| 386 | <b>Z</b> <i>checksum</i> |
| 387 | </p> |
| 388 | |
| 389 | The <b>D</b> card is the usual date and time stamp and represents the point |
| 390 | in time when the change was entered. The <b>U</b> card is the login of the |
| 391 | programmer who entered this change. The <b>Z</b> card is the required checksum over |
| 392 | the entire artifact. |
| @@ -427,18 +424,18 @@ | |
| 424 | attachment (the source artifact) with a ticket or wiki page or |
| 425 | technical note to which |
| 426 | the attachment is connected (the target artifact). |
| 427 | The following cards are allowed on an attachment artifact: |
| 428 | |
| 429 | <p class="indent"> |
| 430 | <b>A</b> <i>filename target</i> ?<i>source</i>?<br /> |
| 431 | <b>C</b> <i>comment</i><br /> |
| 432 | <b>D</b> <i>time-and-date-stamp</i><br /> |
| 433 | <b>N</b> <i>mimetype</i><br /> |
| 434 | <b>U</b> <i>user-name</i><br /> |
| 435 | <b>Z</b> <i>checksum</i> |
| 436 | </p> |
| 437 | |
| 438 | The <b>A</b> card specifies a filename for the attachment in its first argument. |
| 439 | The second argument to the <b>A</b> card is the name of the wiki page or |
| 440 | ticket or technical note to which the attachment is connected. The |
| 441 | third argument is either missing or else it is the lower-case artifact |
| @@ -469,21 +466,21 @@ | |
| 466 | (similar to a wiki page) with a point in time. Technotes can be used |
| 467 | to record project milestones, release notes, blog entries, process |
| 468 | checkpoints, or news articles. |
| 469 | The following cards are allowed on an technote artifact: |
| 470 | |
| 471 | <p class="indent"> |
| 472 | <b>C</b> <i>comment</i><br> |
| 473 | <b>D</b> <i>time-and-date-stamp</i><br /> |
| 474 | <b>E</b> <i>technote-time</i> <i>technote-id</i><br /> |
| 475 | <b>N</b> <i>mimetype</i><br /> |
| 476 | <b>P</b> <i>parent-artifact-id</i>+<br /> |
| 477 | <b>T</b> <b>+</b><i>tag-name</i> <b>*</b> ?<i>value</i>?<br /> |
| 478 | <b>U</b> <i>user-name</i><br /> |
| 479 | <b>W</b> <i>size</i> <b>\n</b> <i>text</i> <b>\n</b><br /> |
| 480 | <b>Z</b> <i>checksum</i> |
| 481 | </p> |
| 482 | |
| 483 | The <b>C</b> card contains text that is displayed on the timeline for the |
| 484 | technote. The <b>C</b> card is optional, but there can only be one. |
| 485 | |
| 486 | A single <b>D</b> card is required to give the date and time when the |
| @@ -534,21 +531,21 @@ | |
| 531 | Forum posts are intended as a mechanism for users and developers to |
| 532 | discuss a project. Forum posts are like messages on a mailing list. |
| 533 | |
| 534 | The following cards are allowed on an forum post artifact: |
| 535 | |
| 536 | <p class="indent"> |
| 537 | <b>D</b> <i>time-and-date-stamp</i><br /> |
| 538 | <b>G</b> <i>thread-root</i><br /> |
| 539 | <b>H</b> <i>thread-title</i><br /> |
| 540 | <b>I</b> <i>in-reply-to</i><br /> |
| 541 | <b>N</b> <i>mimetype</i><br /> |
| 542 | <b>P</b> <i>parent-artifact-id</i><br /> |
| 543 | <b>U</b> <i>user-name</i><br /> |
| 544 | <b>W</b> <i>size</i> <b>\n</b> <i>text</i> <b>\n</b><br /> |
| 545 | <b>Z</b> <i>checksum</i> |
| 546 | </p> |
| 547 | |
| 548 | Every forum post must have either one <b>I</b> card and one <b>G</b> card |
| 549 | or one <b>H</b> card. |
| 550 | Forum posts are organized into topic threads. The initial |
| 551 | post for a thread (the root post) has an <b>H</b> card giving the title or |
| @@ -610,16 +607,13 @@ | |
| 607 | artifact is not legal. A number or range of numbers indicates the number |
| 608 | of times a card may (or must) appear in the corresponding artifact type. |
| 609 | e.g. a value of 1 indicates a required unique card and 1+ indicates that one |
| 610 | or more such cards are required. |
| 611 | |
| 612 | <table> |
| 613 | <tr> |
| 614 | <th>⇩ Card Format / Used By ⇨</th> |
| 615 | <th>Manifest</th> |
| 616 | <th>Cluster</th> |
| 617 | <th>Control</th> |
| 618 | <th>Wiki</th> |
| 619 | <th>Ticket</th> |
| @@ -909,15 +903,15 @@ | |
| 903 | Both bugs have now been fixed. However, to prevent historical |
| 904 | Technical Note artifacts that were inserted by users in good faith |
| 905 | from being rejected by newer Fossil builds, the card ordering |
| 906 | requirement is relaxed slightly. The actual implementation is this: |
| 907 | |
| 908 | <p class=blockquote> |
| 909 | "All cards must be in strict lexicographic order, except that the |
| 910 | N and P cards of a Technical Note artifact are allowed to be |
| 911 | interchanged." |
| 912 | </p> |
| 913 | |
| 914 | Future versions of Fossil might strengthen this slightly to only allow |
| 915 | the out of order N and P cards for Technical Notes entered before |
| 916 | a certain date. |
| 917 | |
| 918 |
+13
-11
| --- www/fossil-v-git.wiki | ||
| +++ www/fossil-v-git.wiki | ||
| @@ -34,16 +34,18 @@ | ||
| 34 | 34 | <h2>2.0 Differences Between Fossil And Git</h2> |
| 35 | 35 | |
| 36 | 36 | Differences between Fossil and Git are summarized by the following table, |
| 37 | 37 | with further description in the text that follows. |
| 38 | 38 | |
| 39 | -<blockquote><table border=1 cellpadding=5 align=center> | |
| 40 | -<tr><th width="49%">GIT</th><th width="49%">FOSSIL</th><th width="2%">more</th></tr> | |
| 39 | +<table style="width: fit-content"> | |
| 40 | +<tr><th>GIT</th><th>FOSSIL</th><th>more</th></tr> | |
| 41 | 41 | <tr> |
| 42 | 42 | <td>File versioning only</td> |
| 43 | - <td>VCS, tickets, wiki, docs, notes, forum, chat, UI, | |
| 44 | - [https://en.wikipedia.org/wiki/Role-based_access_control|RBAC]</td> | |
| 43 | + <td> | |
| 44 | + VCS, tickets, wiki, docs, notes, forum, chat, UI, | |
| 45 | + [https://en.wikipedia.org/wiki/Role-based_access_control|RBAC] | |
| 46 | + </td> | |
| 45 | 47 | <td><a href="#features">2.1 ↓</a></td> |
| 46 | 48 | </tr> |
| 47 | 49 | <tr> |
| 48 | 50 | <td>A federation of many small programs</td> |
| 49 | 51 | <td>One self-contained, stand-alone executable</td> |
| @@ -97,11 +99,11 @@ | ||
| 97 | 99 | <tr> |
| 98 | 100 | <td>SHA-1 or SHA-2</td> |
| 99 | 101 | <td>SHA-1 and/or SHA-3, in the same repository</td> |
| 100 | 102 | <td><a href="#hash">2.9 ↓</a></td> |
| 101 | 103 | </tr> |
| 102 | -</table></blockquote> | |
| 104 | +</table> | |
| 103 | 105 | |
| 104 | 106 | <h3 id="features">2.1 Featureful</h3> |
| 105 | 107 | |
| 106 | 108 | Git provides file versioning services only, whereas Fossil adds |
| 107 | 109 | an integrated [./wikitheory.wiki | wiki], |
| @@ -797,21 +799,21 @@ | ||
| 797 | 799 | |
| 798 | 800 | Incidentally, this is a good example of Git's messy command design. |
| 799 | 801 | These three commands: |
| 800 | 802 | |
| 801 | 803 | <pre> |
| 802 | - $ git merge HASH | |
| 803 | - $ git cherry-pick HASH | |
| 804 | - $ git revert HASH | |
| 804 | +$ git merge HASH | |
| 805 | +$ git cherry-pick HASH | |
| 806 | +$ git revert HASH | |
| 805 | 807 | </pre> |
| 806 | 808 | |
| 807 | 809 | ...are all the same command in Fossil: |
| 808 | 810 | |
| 809 | 811 | <pre> |
| 810 | - $ fossil merge HASH | |
| 811 | - $ fossil merge --cherrypick HASH | |
| 812 | - $ fossil merge --backout HASH | |
| 812 | +$ fossil merge HASH | |
| 813 | +$ fossil merge --cherrypick HASH | |
| 814 | +$ fossil merge --backout HASH | |
| 813 | 815 | </pre> |
| 814 | 816 | |
| 815 | 817 | If you think about it, they're all the same function: apply work done on |
| 816 | 818 | one branch to another. All that changes between these commands is how |
| 817 | 819 | much work gets applied — just one check-in or a whole branch — and the |
| 818 | 820 |
| --- www/fossil-v-git.wiki | |
| +++ www/fossil-v-git.wiki | |
| @@ -34,16 +34,18 @@ | |
| 34 | <h2>2.0 Differences Between Fossil And Git</h2> |
| 35 | |
| 36 | Differences between Fossil and Git are summarized by the following table, |
| 37 | with further description in the text that follows. |
| 38 | |
| 39 | <blockquote><table border=1 cellpadding=5 align=center> |
| 40 | <tr><th width="49%">GIT</th><th width="49%">FOSSIL</th><th width="2%">more</th></tr> |
| 41 | <tr> |
| 42 | <td>File versioning only</td> |
| 43 | <td>VCS, tickets, wiki, docs, notes, forum, chat, UI, |
| 44 | [https://en.wikipedia.org/wiki/Role-based_access_control|RBAC]</td> |
| 45 | <td><a href="#features">2.1 ↓</a></td> |
| 46 | </tr> |
| 47 | <tr> |
| 48 | <td>A federation of many small programs</td> |
| 49 | <td>One self-contained, stand-alone executable</td> |
| @@ -97,11 +99,11 @@ | |
| 97 | <tr> |
| 98 | <td>SHA-1 or SHA-2</td> |
| 99 | <td>SHA-1 and/or SHA-3, in the same repository</td> |
| 100 | <td><a href="#hash">2.9 ↓</a></td> |
| 101 | </tr> |
| 102 | </table></blockquote> |
| 103 | |
| 104 | <h3 id="features">2.1 Featureful</h3> |
| 105 | |
| 106 | Git provides file versioning services only, whereas Fossil adds |
| 107 | an integrated [./wikitheory.wiki | wiki], |
| @@ -797,21 +799,21 @@ | |
| 797 | |
| 798 | Incidentally, this is a good example of Git's messy command design. |
| 799 | These three commands: |
| 800 | |
| 801 | <pre> |
| 802 | $ git merge HASH |
| 803 | $ git cherry-pick HASH |
| 804 | $ git revert HASH |
| 805 | </pre> |
| 806 | |
| 807 | ...are all the same command in Fossil: |
| 808 | |
| 809 | <pre> |
| 810 | $ fossil merge HASH |
| 811 | $ fossil merge --cherrypick HASH |
| 812 | $ fossil merge --backout HASH |
| 813 | </pre> |
| 814 | |
| 815 | If you think about it, they're all the same function: apply work done on |
| 816 | one branch to another. All that changes between these commands is how |
| 817 | much work gets applied — just one check-in or a whole branch — and the |
| 818 |
| --- www/fossil-v-git.wiki | |
| +++ www/fossil-v-git.wiki | |
| @@ -34,16 +34,18 @@ | |
| 34 | <h2>2.0 Differences Between Fossil And Git</h2> |
| 35 | |
| 36 | Differences between Fossil and Git are summarized by the following table, |
| 37 | with further description in the text that follows. |
| 38 | |
| 39 | <table style="width: fit-content"> |
| 40 | <tr><th>GIT</th><th>FOSSIL</th><th>more</th></tr> |
| 41 | <tr> |
| 42 | <td>File versioning only</td> |
| 43 | <td> |
| 44 | VCS, tickets, wiki, docs, notes, forum, chat, UI, |
| 45 | [https://en.wikipedia.org/wiki/Role-based_access_control|RBAC] |
| 46 | </td> |
| 47 | <td><a href="#features">2.1 ↓</a></td> |
| 48 | </tr> |
| 49 | <tr> |
| 50 | <td>A federation of many small programs</td> |
| 51 | <td>One self-contained, stand-alone executable</td> |
| @@ -97,11 +99,11 @@ | |
| 99 | <tr> |
| 100 | <td>SHA-1 or SHA-2</td> |
| 101 | <td>SHA-1 and/or SHA-3, in the same repository</td> |
| 102 | <td><a href="#hash">2.9 ↓</a></td> |
| 103 | </tr> |
| 104 | </table> |
| 105 | |
| 106 | <h3 id="features">2.1 Featureful</h3> |
| 107 | |
| 108 | Git provides file versioning services only, whereas Fossil adds |
| 109 | an integrated [./wikitheory.wiki | wiki], |
| @@ -797,21 +799,21 @@ | |
| 799 | |
| 800 | Incidentally, this is a good example of Git's messy command design. |
| 801 | These three commands: |
| 802 | |
| 803 | <pre> |
| 804 | $ git merge HASH |
| 805 | $ git cherry-pick HASH |
| 806 | $ git revert HASH |
| 807 | </pre> |
| 808 | |
| 809 | ...are all the same command in Fossil: |
| 810 | |
| 811 | <pre> |
| 812 | $ fossil merge HASH |
| 813 | $ fossil merge --cherrypick HASH |
| 814 | $ fossil merge --backout HASH |
| 815 | </pre> |
| 816 | |
| 817 | If you think about it, they're all the same function: apply work done on |
| 818 | one branch to another. All that changes between these commands is how |
| 819 | much work gets applied — just one check-in or a whole branch — and the |
| 820 |
+2
-3
| --- www/fossil_prompt.wiki | ||
| +++ www/fossil_prompt.wiki | ||
| @@ -1,7 +1,6 @@ | ||
| 1 | 1 | <title>Fossilized Bash Prompt</title> |
| 2 | -<h1>2013-02-21</h1> | |
| 3 | 2 | |
| 4 | 3 | Dan Kennedy has contributed a |
| 5 | 4 | [./fossil_prompt.sh?mimetype=text/plain | bash script] |
| 6 | 5 | that manipulates the bash prompt to show the status of |
| 7 | 6 | the Fossil repository that the user is currently visiting. |
| @@ -10,14 +9,14 @@ | ||
| 10 | 9 | red when there are uncommitted changes. |
| 11 | 10 | |
| 12 | 11 | To try out this script, simply download it from the link above, then |
| 13 | 12 | type: |
| 14 | 13 | |
| 15 | -<blockquote><pre> | |
| 14 | +<pre> | |
| 16 | 15 | . fossil_prompt.sh |
| 17 | -</pre></blockquote> | |
| 16 | +</pre> | |
| 18 | 17 | |
| 19 | 18 | For a permanent installation, you can graft the code into your |
| 20 | 19 | <tt>.bashrc</tt> file in your home directory. |
| 21 | 20 | |
| 22 | 21 | The code is very simple (only 32 non-comment lines, as of this writing) |
| 23 | 22 | and hence easy to customized. |
| 24 | 23 |
| --- www/fossil_prompt.wiki | |
| +++ www/fossil_prompt.wiki | |
| @@ -1,7 +1,6 @@ | |
| 1 | <title>Fossilized Bash Prompt</title> |
| 2 | <h1>2013-02-21</h1> |
| 3 | |
| 4 | Dan Kennedy has contributed a |
| 5 | [./fossil_prompt.sh?mimetype=text/plain | bash script] |
| 6 | that manipulates the bash prompt to show the status of |
| 7 | the Fossil repository that the user is currently visiting. |
| @@ -10,14 +9,14 @@ | |
| 10 | red when there are uncommitted changes. |
| 11 | |
| 12 | To try out this script, simply download it from the link above, then |
| 13 | type: |
| 14 | |
| 15 | <blockquote><pre> |
| 16 | . fossil_prompt.sh |
| 17 | </pre></blockquote> |
| 18 | |
| 19 | For a permanent installation, you can graft the code into your |
| 20 | <tt>.bashrc</tt> file in your home directory. |
| 21 | |
| 22 | The code is very simple (only 32 non-comment lines, as of this writing) |
| 23 | and hence easy to customized. |
| 24 |
| --- www/fossil_prompt.wiki | |
| +++ www/fossil_prompt.wiki | |
| @@ -1,7 +1,6 @@ | |
| 1 | <title>Fossilized Bash Prompt</title> |
| 2 | |
| 3 | Dan Kennedy has contributed a |
| 4 | [./fossil_prompt.sh?mimetype=text/plain | bash script] |
| 5 | that manipulates the bash prompt to show the status of |
| 6 | the Fossil repository that the user is currently visiting. |
| @@ -10,14 +9,14 @@ | |
| 9 | red when there are uncommitted changes. |
| 10 | |
| 11 | To try out this script, simply download it from the link above, then |
| 12 | type: |
| 13 | |
| 14 | <pre> |
| 15 | . fossil_prompt.sh |
| 16 | </pre> |
| 17 | |
| 18 | For a permanent installation, you can graft the code into your |
| 19 | <tt>.bashrc</tt> file in your home directory. |
| 20 | |
| 21 | The code is very simple (only 32 non-comment lines, as of this writing) |
| 22 | and hence easy to customized. |
| 23 |
+108
-108
| --- www/gitusers.md | ||
| +++ www/gitusers.md | ||
| @@ -73,15 +73,15 @@ | ||
| 73 | 73 | document][ckwf] to see the practical differences. |
| 74 | 74 | |
| 75 | 75 | There is one Git-specific detail we wish to add beyond what that |
| 76 | 76 | document already covers. This command: |
| 77 | 77 | |
| 78 | - git checkout some-branch | |
| 78 | + git checkout some-branch | |
| 79 | 79 | |
| 80 | 80 | …is best given as: |
| 81 | 81 | |
| 82 | - fossil update some-branch | |
| 82 | + fossil update some-branch | |
| 83 | 83 | |
| 84 | 84 | …in Fossil. There is a [`fossil checkout`][co] command, but it has |
| 85 | 85 | [several differences](./co-vs-up.md) that make it less broadly useful |
| 86 | 86 | than [`fossil update`][up] in everyday operation, so we recommend that |
| 87 | 87 | Git users moving to Fossil develop a habit of typing `fossil up` rather |
| @@ -109,11 +109,11 @@ | ||
| 109 | 109 | |
| 110 | 110 | The `fossil pull` command is simply the reverse of |
| 111 | 111 | `fossil push`, so that `fossil sync` [is functionally equivalent |
| 112 | 112 | to](./sync.wiki#sync): |
| 113 | 113 | |
| 114 | - fossil push ; fossil pull | |
| 114 | + fossil push ; fossil pull | |
| 115 | 115 | |
| 116 | 116 | There is no implicit “and update the local working directory” step in Fossil’s |
| 117 | 117 | push, pull, or sync commands, as there is with `git pull`. |
| 118 | 118 | |
| 119 | 119 | Someone coming from the Git perspective may perceive that `fossil up` |
| @@ -180,29 +180,29 @@ | ||
| 180 | 180 | check-out directories][mcw] with Git. |
| 181 | 181 | |
| 182 | 182 | The old way is to simply symlink the `.git` directory between working |
| 183 | 183 | trees: |
| 184 | 184 | |
| 185 | - mkdir ../foo-branch | |
| 186 | - ln -s ../actual-clone-dir/.git . | |
| 187 | - git checkout foo-branch | |
| 185 | + mkdir ../foo-branch | |
| 186 | + ln -s ../actual-clone-dir/.git . | |
| 187 | + git checkout foo-branch | |
| 188 | 188 | |
| 189 | 189 | The symlink trick has a number of problems, the largest being that |
| 190 | 190 | symlinks weren’t available on Windows until Vista, and until the Windows |
| 191 | 191 | 10 Creators Update was released in spring of 2017, you had to be an |
| 192 | 192 | Administrator to use the feature besides. ([Source][wsyml]) Git 2.5 solved |
| 193 | 193 | this problem back when Windows XP was Microsoft’s current offering |
| 194 | 194 | by adding the `git-worktree` command: |
| 195 | 195 | |
| 196 | - git worktree add ../foo-branch foo-branch | |
| 197 | - cd ../foo-branch | |
| 196 | + git worktree add ../foo-branch foo-branch | |
| 197 | + cd ../foo-branch | |
| 198 | 198 | |
| 199 | 199 | That is approximately equivalent to this in Fossil: |
| 200 | 200 | |
| 201 | - mkdir ../foo-branch | |
| 202 | - cd ../foo-branch | |
| 203 | - fossil open /path/to/repo.fossil foo-branch | |
| 201 | + mkdir ../foo-branch | |
| 202 | + cd ../foo-branch | |
| 203 | + fossil open /path/to/repo.fossil foo-branch | |
| 204 | 204 | |
| 205 | 205 | The Fossil alternative is wordier, but since this tends to be one-time setup, |
| 206 | 206 | not something you do everyday, the overhead is insignificant. This author keeps a “scratch” check-out |
| 207 | 207 | for cases where it’s inappropriate to reuse the “trunk” check-out, |
| 208 | 208 | isolating all of my expedient switch-in-place actions to that one |
| @@ -211,20 +211,20 @@ | ||
| 211 | 211 | up, I rarely pay the cost of these wordier commands. |
| 212 | 212 | |
| 213 | 213 | That then leads us to the closest equivalent in Git to [closing a Fossil |
| 214 | 214 | check-out](#close): |
| 215 | 215 | |
| 216 | - git worktree remove . | |
| 216 | + git worktree remove . | |
| 217 | 217 | |
| 218 | 218 | Note, however, that unlike `fossil close`, once the Git command |
| 219 | 219 | determines that there are no uncommitted changes, it blows away all of |
| 220 | 220 | the checked-out files! Fossil’s alternative is shorter, easier to |
| 221 | 221 | remember, and safer. |
| 222 | 222 | |
| 223 | 223 | There’s another way to get Fossil-like separate worktrees in Git: |
| 224 | 224 | |
| 225 | - git clone --separate-git-dir repo.git https://example.com/repo | |
| 225 | + git clone --separate-git-dir repo.git https://example.com/repo | |
| 226 | 226 | |
| 227 | 227 | This allows you to have your Git repository directory entirely separate |
| 228 | 228 | from your working tree, with `.git` in the check-out directory being a |
| 229 | 229 | file that points to `../repo.git`, in this example. |
| 230 | 230 | |
| @@ -238,22 +238,22 @@ | ||
| 238 | 238 | from working directory creates in practice, consider this common Git “init in place” |
| 239 | 239 | method for creating a new repository from an existing tree of files, |
| 240 | 240 | perhaps because you are placing that project under version control for |
| 241 | 241 | the first time: |
| 242 | 242 | |
| 243 | - cd long-established-project | |
| 244 | - git init | |
| 245 | - git add * | |
| 246 | - git commit -m "Initial commit of project." | |
| 243 | + cd long-established-project | |
| 244 | + git init | |
| 245 | + git add * | |
| 246 | + git commit -m "Initial commit of project." | |
| 247 | 247 | |
| 248 | 248 | The closest equivalent in Fossil is: |
| 249 | 249 | |
| 250 | - cd long-established-project | |
| 251 | - fossil init .fsl | |
| 252 | - fossil open --force .fsl | |
| 253 | - fossil add * | |
| 254 | - fossil ci -m "Initial commit of project." | |
| 250 | + cd long-established-project | |
| 251 | + fossil init .fsl | |
| 252 | + fossil open --force .fsl | |
| 253 | + fossil add * | |
| 254 | + fossil ci -m "Initial commit of project." | |
| 255 | 255 | |
| 256 | 256 | Note that unlike in Git, you can abbreviate the “`commit`” command in |
| 257 | 257 | Fossil as “`ci`” for compatibility with CVS, Subversion, etc. |
| 258 | 258 | |
| 259 | 259 | This creates a `.fsl` repo DB at the root of the project check-out to |
| @@ -316,19 +316,19 @@ | ||
| 316 | 316 | #### <a id="emu-log"></a> Emulating `git log` |
| 317 | 317 | |
| 318 | 318 | If you truly need a backwards-in-time-only view of history in Fossil to |
| 319 | 319 | emulate `git log`, this is as close as you can currently come: |
| 320 | 320 | |
| 321 | - fossil timeline parents current | |
| 321 | + fossil timeline parents current | |
| 322 | 322 | |
| 323 | 323 | Again, though, this isn’t restricted to a single branch, as `git log` |
| 324 | 324 | is. |
| 325 | 325 | |
| 326 | 326 | Another useful rough equivalent is: |
| 327 | 327 | |
| 328 | - git log --raw | |
| 329 | - fossil time -v | |
| 328 | + git log --raw | |
| 329 | + fossil time -v | |
| 330 | 330 | |
| 331 | 331 | This shows what changed in each version, though Fossil’s view is more a |
| 332 | 332 | summary than a list of raw changes. To dig deeper into single commits, |
| 333 | 333 | you can use Fossil’s [`info` command][infoc] or its [`/info` view][infow]. |
| 334 | 334 | |
| @@ -344,33 +344,33 @@ | ||
| 344 | 344 | Though there is no `fossil whatchanged` command, the same sort of |
| 345 | 345 | information is available. For example, to pull the current changes from |
| 346 | 346 | the remote repository and then inspect them before updating the local |
| 347 | 347 | working directory, you might say this in Git: |
| 348 | 348 | |
| 349 | - git fetch | |
| 350 | - git whatchanged ..@{u} | |
| 349 | + git fetch | |
| 350 | + git whatchanged ..@{u} | |
| 351 | 351 | |
| 352 | 352 | …which you can approximate in Fossil as: |
| 353 | 353 | |
| 354 | - fossil pull | |
| 355 | - fossil up -n | |
| 356 | - fossil diff --from tip | |
| 354 | + fossil pull | |
| 355 | + fossil up -n | |
| 356 | + fossil diff --from tip | |
| 357 | 357 | |
| 358 | 358 | To invert the `diff` to show a more natural patch, the command needs to |
| 359 | 359 | be a bit more complicated, since you can’t currently give `--to` |
| 360 | 360 | without `--from`. |
| 361 | 361 | |
| 362 | - fossil diff --from current --to tip | |
| 362 | + fossil diff --from current --to tip | |
| 363 | 363 | |
| 364 | 364 | Rather than use the “dry run” form of [the `update` command][up], you can |
| 365 | 365 | say: |
| 366 | 366 | |
| 367 | - fossil timeline after current | |
| 367 | + fossil timeline after current | |
| 368 | 368 | |
| 369 | 369 | …or if you want to restrict the output to the current branch: |
| 370 | 370 | |
| 371 | - fossil timeline descendants current | |
| 371 | + fossil timeline descendants current | |
| 372 | 372 | |
| 373 | 373 | |
| 374 | 374 | #### <a id="ckin-names"></a> Symbolic Check-In Names |
| 375 | 375 | |
| 376 | 376 | Note the use of [human-readable symbolic version names][scin] in Fossil |
| @@ -377,42 +377,42 @@ | ||
| 377 | 377 | rather than [Git’s cryptic notations][gcn]. |
| 378 | 378 | |
| 379 | 379 | For a more dramatic example of this, let us ask Git, “What changed since the |
| 380 | 380 | beginning of last month?” being October 2020 as I write this: |
| 381 | 381 | |
| 382 | - git log master@{2020-10-01}..HEAD | |
| 382 | + git log master@{2020-10-01}..HEAD | |
| 383 | 383 | |
| 384 | 384 | That’s rather obscure! Fossil answers the same question with a simpler |
| 385 | 385 | command: |
| 386 | 386 | |
| 387 | - fossil timeline after 2020-10-01 | |
| 387 | + fossil timeline after 2020-10-01 | |
| 388 | 388 | |
| 389 | 389 | You may need to add `-n 0` to bypass the default output limit of |
| 390 | 390 | `fossil timeline`, 20 entries. Without that, this command reads |
| 391 | 391 | almost like English. |
| 392 | 392 | |
| 393 | 393 | Some Git users like to write commands like the above so: |
| 394 | 394 | |
| 395 | - git log @{2020-10-01}..@ | |
| 395 | + git log @{2020-10-01}..@ | |
| 396 | 396 | |
| 397 | 397 | Is that better? “@” now means two different things: an at-time reference |
| 398 | 398 | and a shortcut for `HEAD`! |
| 399 | 399 | |
| 400 | 400 | If you are one of those that like short commands, Fossil’s method is |
| 401 | 401 | less cryptic: it lets you shorten words in most cases up to the point |
| 402 | 402 | that they become ambiguous. For example, you may abbreviate the last |
| 403 | 403 | `fossil` command in the prior section: |
| 404 | 404 | |
| 405 | - fossil tim d c | |
| 405 | + fossil tim d c | |
| 406 | 406 | |
| 407 | 407 | …beyond which the `timeline` command becomes ambiguous with `ticket`. |
| 408 | 408 | |
| 409 | 409 | Some Fossil users employ shell aliases, symlinks, or scripts to shorten |
| 410 | 410 | the command still further: |
| 411 | 411 | |
| 412 | - alias f=fossil | |
| 413 | - f tim d c | |
| 412 | + alias f=fossil | |
| 413 | + f tim d c | |
| 414 | 414 | |
| 415 | 415 | Granted, that’s rather obscure, but you you can also choose something |
| 416 | 416 | intermediate like “`f time desc curr`”, which is reasonably clear. |
| 417 | 417 | |
| 418 | 418 | [35pct]: https://www.sqlite.org/fasterthanfs.html |
| @@ -468,11 +468,11 @@ | ||
| 468 | 468 | automatically. There is no need for the "-a" option as with Git. |
| 469 | 469 | |
| 470 | 470 | If you only want to commit _some_ of the changes, list the names |
| 471 | 471 | of the files or directories you want to commit as arguments, like this: |
| 472 | 472 | |
| 473 | - fossil commit src/feature.c doc/feature.md examples/feature | |
| 473 | + fossil commit src/feature.c doc/feature.md examples/feature | |
| 474 | 474 | |
| 475 | 475 | Note that the last element is a directory name, meaning “any changed |
| 476 | 476 | file under the `examples/feature` directory.” |
| 477 | 477 | |
| 478 | 478 | Although there are currently no |
| @@ -482,12 +482,12 @@ | ||
| 482 | 482 | running it through [Patchouli]. |
| 483 | 483 | |
| 484 | 484 | Rather than use `fossil diff -i` to produce such a patch, a safer and |
| 485 | 485 | more idiomatic method would be: |
| 486 | 486 | |
| 487 | - fossil stash save -m 'my big ball-o-hackage' | |
| 488 | - fossil stash diff > my-changes.patch | |
| 487 | + fossil stash save -m 'my big ball-o-hackage' | |
| 488 | + fossil stash diff > my-changes.patch | |
| 489 | 489 | |
| 490 | 490 | That stores your changes in the stash, then lets you operate on a copy |
| 491 | 491 | of that patch. Each time you re-run the second command, it will take the |
| 492 | 492 | current state of the working directory into account to produce a |
| 493 | 493 | potentially different patch, likely smaller because it leaves out patch |
| @@ -526,30 +526,30 @@ | ||
| 526 | 526 | ## Create Branches at Point of Need, Rather Than Ahead of Need |
| 527 | 527 | |
| 528 | 528 | Fossil prefers that you create new branches as part of the first commit |
| 529 | 529 | on that branch: |
| 530 | 530 | |
| 531 | - fossil commit --branch my-branch | |
| 531 | + fossil commit --branch my-branch | |
| 532 | 532 | |
| 533 | 533 | If that commit is successful, your local check-out directory is then |
| 534 | 534 | switched to the tip of that branch, so subsequent commits don’t need the |
| 535 | 535 | “`--branch`” option. You simply say `fossil commit` again to continue |
| 536 | 536 | adding commits to the tip of that branch. |
| 537 | 537 | |
| 538 | 538 | To switch back to the parent branch, say something like: |
| 539 | 539 | |
| 540 | - fossil update trunk | |
| 540 | + fossil update trunk | |
| 541 | 541 | |
| 542 | 542 | (This is approximately equivalent to `git checkout master`.) |
| 543 | 543 | |
| 544 | 544 | Fossil does also support the Git style, creating the branch ahead of |
| 545 | 545 | need: |
| 546 | 546 | |
| 547 | - fossil branch new my-branch | |
| 548 | - fossil up my-branch | |
| 549 | - ...work on first commit... | |
| 550 | - fossil commit | |
| 547 | + fossil branch new my-branch | |
| 548 | + fossil up my-branch | |
| 549 | + ...work on first commit... | |
| 550 | + fossil commit | |
| 551 | 551 | |
| 552 | 552 | This is more verbose, giving the same overall effect though the initial |
| 553 | 553 | actions are inverted: create a new branch for the first commit, switch |
| 554 | 554 | the check-out directory to that branch, and make that first commit. As |
| 555 | 555 | above, subsequent commits are descendants of that initial branch commit. |
| @@ -558,11 +558,11 @@ | ||
| 558 | 558 | |
| 559 | 559 | Fossil also allows you to move a check-in to a different branch |
| 560 | 560 | *after* you commit it, using the "`fossil amend`" command. |
| 561 | 561 | For example: |
| 562 | 562 | |
| 563 | - fossil amend current --branch my-branch | |
| 563 | + fossil amend current --branch my-branch | |
| 564 | 564 | |
| 565 | 565 | This works by inserting a tag into the repository that causes the web UI |
| 566 | 566 | to relabel commits from that point forward with the new name. Like Git, |
| 567 | 567 | Fossil’s fundamental data structure is the interlinked DAG of commit |
| 568 | 568 | hashes; branch names are supplemental data for making it easier for the |
| @@ -591,15 +591,15 @@ | ||
| 591 | 591 | make them under this eventually-consistent design philosophy. |
| 592 | 592 | |
| 593 | 593 | Branch *names* sync automatically in Fossil, not just the |
| 594 | 594 | content of those branches. That means this common Git command: |
| 595 | 595 | |
| 596 | - git push origin master | |
| 596 | + git push origin master | |
| 597 | 597 | |
| 598 | 598 | …is simply this in Fossil: |
| 599 | 599 | |
| 600 | - fossil push | |
| 600 | + fossil push | |
| 601 | 601 | |
| 602 | 602 | Fossil doesn’t need to be told what to push or where to push it: it just |
| 603 | 603 | keeps using the same remote server URL you gave it last |
| 604 | 604 | until you [tell it to do something different][rem]. It pushes all |
| 605 | 605 | branches, not just one named local branch. |
| @@ -613,11 +613,11 @@ | ||
| 613 | 613 | |
| 614 | 614 | Fossil’s [autosync][wflow] feature, normally enabled, has no |
| 615 | 615 | equivalent in Git. If you want Fossil to behave like Git, you can turn |
| 616 | 616 | it off: |
| 617 | 617 | |
| 618 | - fossil set autosync 0 | |
| 618 | + fossil set autosync 0 | |
| 619 | 619 | |
| 620 | 620 | Let’s say that you have a typical server-and-workstations model with two |
| 621 | 621 | working clones on different machines, that you have disabled autosync, |
| 622 | 622 | and that this common sequence then occurs: |
| 623 | 623 | |
| @@ -692,16 +692,16 @@ | ||
| 692 | 692 | by a colon. The simplified example above is also liable to become |
| 693 | 693 | confused by whitespace in file names.) |
| 694 | 694 | |
| 695 | 695 | |
| 696 | 696 | ``` |
| 697 | - $ repo=$(fossil status | grep ^repo | cut -f2 -d:) | |
| 698 | - $ url=$(fossil remote) | |
| 699 | - $ fossil close # Stop here and think if it warns you! | |
| 700 | - $ mv $repo ${repo}.old | |
| 701 | - $ fossil clone $url $repo | |
| 702 | - $ fossil open --force $repo | |
| 697 | +$ repo=$(fossil status | grep ^repo | cut -f2 -d:) | |
| 698 | +$ url=$(fossil remote) | |
| 699 | +$ fossil close # Stop here and think if it warns you! | |
| 700 | +$ mv $repo ${repo}.old | |
| 701 | +$ fossil clone $url $repo | |
| 702 | +$ fossil open --force $repo | |
| 703 | 703 | ``` |
| 704 | 704 | |
| 705 | 705 | What, then, should you as a Git transplant do instead when you find |
| 706 | 706 | yourself reaching for “`git reset`”? |
| 707 | 707 | |
| @@ -717,13 +717,13 @@ | ||
| 717 | 717 | sort of thing is unnecessary. |
| 718 | 718 | |
| 719 | 719 | Instead, Bob can say something like this: |
| 720 | 720 | |
| 721 | 721 | ``` |
| 722 | - fossil amend --branch MISTAKE --hide --close -m "mea culpa" tip | |
| 723 | - fossil up trunk | |
| 724 | - fossil push | |
| 722 | +fossil amend --branch MISTAKE --hide --close -m "mea culpa" tip | |
| 723 | +fossil up trunk | |
| 724 | +fossil push | |
| 725 | 725 | ``` |
| 726 | 726 | |
| 727 | 727 | Unlike in Git, the “`amend`” command doesn’t modify prior committed |
| 728 | 728 | artifacts. Bob’s first command doesn’t delete anything, merely tells |
| 729 | 729 | Fossil to hide his mistake from timeline views by inserting a few new |
| @@ -750,14 +750,14 @@ | ||
| 750 | 750 | marked the branch as closed will prevent that from going thru, cluing |
| 751 | 751 | Alice into what she needs to do to remedy the situation, but that merely |
| 752 | 752 | shows why it’s a better workflow if Alice makes the amendment herself: |
| 753 | 753 | |
| 754 | 754 | ``` |
| 755 | - fossil amend --branch MISTAKE --hide --close \ | |
| 756 | - -m "shunt Bob’s erroneous commit off" tip | |
| 757 | - fossil up trunk | |
| 758 | - fossil push | |
| 755 | +fossil amend --branch MISTAKE --hide --close \ | |
| 756 | + -m "shunt Bob’s erroneous commit off" tip | |
| 757 | +fossil up trunk | |
| 758 | +fossil push | |
| 759 | 759 | ``` |
| 760 | 760 | |
| 761 | 761 | Then she can fire off an email listing Bob’s assorted failings and go |
| 762 | 762 | about her work. This asynchronous workflow solves the problem without |
| 763 | 763 | requiring explicit coordination with Bob. When he gets his email, he can |
| @@ -834,18 +834,18 @@ | ||
| 834 | 834 | Nevertheless, there are multiple ways to get colorized diff output from |
| 835 | 835 | Fossil: |
| 836 | 836 | |
| 837 | 837 | * The most direct method is to delegate diff behavior back to Git: |
| 838 | 838 | |
| 839 | - fossil set --global diff-command 'git diff --no-index' | |
| 839 | + fossil set --global diff-command 'git diff --no-index' | |
| 840 | 840 | |
| 841 | 841 | The flag permits it to diff files that aren’t inside a Git repository. |
| 842 | 842 | |
| 843 | 843 | * Another method is to install [`colordiff`][cdiff] — included in |
| 844 | 844 | [many package systems][cdpkg] — then say: |
| 845 | 845 | |
| 846 | - fossil set --global diff-command 'colordiff -wu' | |
| 846 | + fossil set --global diff-command 'colordiff -wu' | |
| 847 | 847 | |
| 848 | 848 | Because this is unconditional, unlike `git diff --color=auto`, you |
| 849 | 849 | will then have to remember to add the `-i` option to `fossil diff` |
| 850 | 850 | commands when you want color disabled, such as when producing |
| 851 | 851 | `patch(1)` files or piping diff output to another command that |
| @@ -876,15 +876,15 @@ | ||
| 876 | 876 | functionality is present in Fossil under other commands: |
| 877 | 877 | |
| 878 | 878 | |
| 879 | 879 | #### <a id="patch"></a> Show a Patch for a Commit |
| 880 | 880 | |
| 881 | - git show -p COMMIT_ID | |
| 881 | + git show -p COMMIT_ID | |
| 882 | 882 | |
| 883 | 883 | …gives much the same output as |
| 884 | 884 | |
| 885 | - fossil diff --checkin COMMIT_ID | |
| 885 | + fossil diff --checkin COMMIT_ID | |
| 886 | 886 | |
| 887 | 887 | …only without the patch email header. Git comes out of the [LKML] world, |
| 888 | 888 | where emailing a patch is a normal thing to do. Fossil is [designed for |
| 889 | 889 | cohesive teams][devorg] where drive-by patches are rarer. |
| 890 | 890 | |
| @@ -893,32 +893,32 @@ | ||
| 893 | 893 | “`VERSION`” or “`NAME`” where this is allowed, since the version string |
| 894 | 894 | or name might not refer to a commit ID, but instead to a forum post, a |
| 895 | 895 | wiki document, etc. For instance, the following command answers the question “What did |
| 896 | 896 | I just commit?” |
| 897 | 897 | |
| 898 | - fossil diff --checkin tip | |
| 898 | + fossil diff --checkin tip | |
| 899 | 899 | |
| 900 | 900 | …or equivalently using a different symbolic commit name: |
| 901 | 901 | |
| 902 | - fossil diff --from prev | |
| 902 | + fossil diff --from prev | |
| 903 | 903 | |
| 904 | 904 | [devorg]: ./fossil-v-git.wiki#devorg |
| 905 | 905 | [LKML]: https://lkml.org/ |
| 906 | 906 | |
| 907 | 907 | |
| 908 | 908 | #### <a id="cmsg"></a> Show a Specific Commit Message |
| 909 | 909 | |
| 910 | - git show -s COMMIT_ID | |
| 910 | + git show -s COMMIT_ID | |
| 911 | 911 | |
| 912 | 912 | |
| 913 | 913 | …is |
| 914 | 914 | |
| 915 | - fossil time -n 1 COMMIT_ID | |
| 915 | + fossil time -n 1 COMMIT_ID | |
| 916 | 916 | |
| 917 | 917 | …or with a shorter, more obvious command, though with more verbose output: |
| 918 | 918 | |
| 919 | - fossil info COMMIT_ID | |
| 919 | + fossil info COMMIT_ID | |
| 920 | 920 | |
| 921 | 921 | The `fossil info` command isn’t otherwise a good equivalent to |
| 922 | 922 | `git show`; it just overlaps its functionality in some areas. Much of |
| 923 | 923 | what’s missing is present in the corresponding [`/info` web |
| 924 | 924 | view][infow], though. |
| @@ -927,17 +927,17 @@ | ||
| 927 | 927 | #### <a id="dstat"></a> Diff Statistics |
| 928 | 928 | |
| 929 | 929 | Fossil’s closest internal equivalent to commands like |
| 930 | 930 | `git show --stat` is: |
| 931 | 931 | |
| 932 | - fossil diff -i --from 2020-04-01 --numstat | |
| 932 | + fossil diff -i --from 2020-04-01 --numstat | |
| 933 | 933 | |
| 934 | 934 | The `--numstat` output is a bit cryptic, so we recommend delegating |
| 935 | 935 | this task to [the widely-available `diffstat` tool][dst], which gives |
| 936 | 936 | a histogram in its default output mode rather than bare integers: |
| 937 | 937 | |
| 938 | - fossil diff -i -v --from 2020-04-01 | diffstat | |
| 938 | + fossil diff -i -v --from 2020-04-01 | diffstat | |
| 939 | 939 | |
| 940 | 940 | We gave the `-i` flag in both cases to force Fossil to use its internal |
| 941 | 941 | diff implementation, bypassing [your local `diff-command` setting][dcset]. |
| 942 | 942 | The `--numstat` option has no effect when you have an external diff |
| 943 | 943 | command set, and some diff command alternatives like |
| @@ -999,19 +999,19 @@ | ||
| 999 | 999 | default: they do not actually rename or delete the files in your |
| 1000 | 1000 | check-out. |
| 1001 | 1001 | |
| 1002 | 1002 | If you don’t like that default, you can change it globally: |
| 1003 | 1003 | |
| 1004 | - fossil setting --global mv-rm-files 1 | |
| 1004 | + fossil setting --global mv-rm-files 1 | |
| 1005 | 1005 | |
| 1006 | 1006 | Now these commands behave like in Git in any Fossil repository where |
| 1007 | 1007 | this setting hasn’t been overridden locally. |
| 1008 | 1008 | |
| 1009 | 1009 | If you want to keep Fossil’s soft `mv/rm` behavior most of the time, you |
| 1010 | 1010 | can cast it away on a per-command basis: |
| 1011 | 1011 | |
| 1012 | - fossil mv --hard old-name new-name | |
| 1012 | + fossil mv --hard old-name new-name | |
| 1013 | 1013 | |
| 1014 | 1014 | [mv]: /help?cmd=mv |
| 1015 | 1015 | [rm]: /help?cmd=rm |
| 1016 | 1016 | |
| 1017 | 1017 | |
| @@ -1032,11 +1032,11 @@ | ||
| 1032 | 1032 | |
| 1033 | 1033 | My search engine’s first result for “git checkout by date” is [this |
| 1034 | 1034 | highly-upvoted accepted Stack Overflow answer][gcod]. The first command |
| 1035 | 1035 | it gives is based on Git’s [`rev-parse` feature][grp]: |
| 1036 | 1036 | |
| 1037 | - git checkout master@{2020-03-17} | |
| 1037 | + git checkout master@{2020-03-17} | |
| 1038 | 1038 | |
| 1039 | 1039 | There are a number of weaknesses in this command. From least to most |
| 1040 | 1040 | critical: |
| 1041 | 1041 | |
| 1042 | 1042 | 1. It’s a bit cryptic. Leave off the refname or punctuation, and it |
| @@ -1072,11 +1072,11 @@ | ||
| 1072 | 1072 | best case. |
| 1073 | 1073 | |
| 1074 | 1074 | That same Stack Overflow answer therefore goes on to recommend an |
| 1075 | 1075 | entirely different command: |
| 1076 | 1076 | |
| 1077 | - git checkout $(git rev-list -n 1 --first-parent --before="2020-03-17" master) | |
| 1077 | + git checkout $(git rev-list -n 1 --first-parent --before="2020-03-17" master) | |
| 1078 | 1078 | |
| 1079 | 1079 | We believe you get such answers to Git help requests in part |
| 1080 | 1080 | because of its lack of an always-up-to-date [index into its log](#log) and in |
| 1081 | 1081 | part because of its “small tools loosely joined” design philosophy. This |
| 1082 | 1082 | sort of command is therefore composed piece by piece: |
| @@ -1084,36 +1084,36 @@ | ||
| 1084 | 1084 | <p style="text-align:center">◆ ◆ ◆</p> |
| 1085 | 1085 | |
| 1086 | 1086 | “Oh, I know, I’ll search the rev-list, which outputs commit IDs by |
| 1087 | 1087 | parsing the log backwards from `HEAD`! Easy!” |
| 1088 | 1088 | |
| 1089 | - git rev-list --before=2020-03-17 | |
| 1089 | + git rev-list --before=2020-03-17 | |
| 1090 | 1090 | |
| 1091 | 1091 | “Blast! Forgot the commit ID!” |
| 1092 | 1092 | |
| 1093 | - git rev-list --before=2020-03-17 master | |
| 1093 | + git rev-list --before=2020-03-17 master | |
| 1094 | 1094 | |
| 1095 | 1095 | “Double blast! It just spammed my terminal with revision IDs! I need to |
| 1096 | 1096 | limit it to the single closest match: |
| 1097 | 1097 | |
| 1098 | - git rev-list -n 1 --before=2020-03-17 master | |
| 1098 | + git rev-list -n 1 --before=2020-03-17 master | |
| 1099 | 1099 | |
| 1100 | 1100 | “Okay, it gives me a single revision ID now, but is it what I’m after? |
| 1101 | 1101 | Let’s take a look…” |
| 1102 | 1102 | |
| 1103 | - git show $(git rev-list -n 1 --before=2020-03-17 master) | |
| 1103 | + git show $(git rev-list -n 1 --before=2020-03-17 master) | |
| 1104 | 1104 | |
| 1105 | 1105 | “Oops, that’s giving me a merge commit, not what I want. |
| 1106 | 1106 | Off to search the web… Okay, it says I need to give either the |
| 1107 | 1107 | `--first-parent` or `--no-merges` flag to show only regular commits, |
| 1108 | 1108 | not merge-commits. Let’s try the first one:” |
| 1109 | 1109 | |
| 1110 | - git show $(git rev-list -n 1 --first-parent --before=2020-03-17 master) | |
| 1110 | + git show $(git rev-list -n 1 --first-parent --before=2020-03-17 master) | |
| 1111 | 1111 | |
| 1112 | 1112 | “Better. Let’s check it out:” |
| 1113 | 1113 | |
| 1114 | - git checkout $(git rev-list -n 1 --first-parent --before=2020-03-17 master) | |
| 1114 | + git checkout $(git rev-list -n 1 --first-parent --before=2020-03-17 master) | |
| 1115 | 1115 | |
| 1116 | 1116 | “Success, I guess?” |
| 1117 | 1117 | |
| 1118 | 1118 | <p style="text-align:center">◆ ◆ ◆</p> |
| 1119 | 1119 | |
| @@ -1132,11 +1132,11 @@ | ||
| 1132 | 1132 | 17th of March, 2020. |
| 1133 | 1133 | |
| 1134 | 1134 | You may be asking with an exasperated huff, “What is your *point*, man?” |
| 1135 | 1135 | The point is that the equivalent in Fossil is simply: |
| 1136 | 1136 | |
| 1137 | - fossil up 2020-03-17 | |
| 1137 | + fossil up 2020-03-17 | |
| 1138 | 1138 | |
| 1139 | 1139 | …which will *always* give the commit closest to midnight UTC on the 17th |
| 1140 | 1140 | of March, 2020, no matter whether you do it on a fresh clone or a stale |
| 1141 | 1141 | one. The answer won’t shift about from one clone to the next or from |
| 1142 | 1142 | one local time of day to the next. We owe this reliability and stability |
| @@ -1181,13 +1181,13 @@ | ||
| 1181 | 1181 | #### Git Method |
| 1182 | 1182 | |
| 1183 | 1183 | We first need to clone the work repo down to our laptop, so we can work on it |
| 1184 | 1184 | at home: |
| 1185 | 1185 | |
| 1186 | - git clone https://dev-server.example.com/repo | |
| 1187 | - cd repo | |
| 1188 | - git remote rename origin work | |
| 1186 | + git clone https://dev-server.example.com/repo | |
| 1187 | + cd repo | |
| 1188 | + git remote rename origin work | |
| 1189 | 1189 | |
| 1190 | 1190 | The last command is optional, strictly speaking. We could continue to |
| 1191 | 1191 | use Git’s default name for the work repo’s origin — sensibly enough |
| 1192 | 1192 | called “`origin`” — but it makes later commands harder to understand, so |
| 1193 | 1193 | we rename it here. This will also make the parallel with Fossil easier |
| @@ -1194,12 +1194,12 @@ | ||
| 1194 | 1194 | to draw. |
| 1195 | 1195 | |
| 1196 | 1196 | The first time we go home after this, we have to reverse-clone the work |
| 1197 | 1197 | repo up to the NAS: |
| 1198 | 1198 | |
| 1199 | - ssh my-nas.local 'git init --bare /SHARES/dayjob/repo.git' | |
| 1200 | - git push --all ssh://my-nas.local//SHARES/dayjob/repo.git | |
| 1199 | + ssh my-nas.local 'git init --bare /SHARES/dayjob/repo.git' | |
| 1200 | + git push --all ssh://my-nas.local//SHARES/dayjob/repo.git | |
| 1201 | 1201 | |
| 1202 | 1202 | Realize that this is carefully optimized down to these two long |
| 1203 | 1203 | commands. In practice, we’d expect a user typing these commands by hand from memory |
| 1204 | 1204 | to need to give four or more commands here instead. |
| 1205 | 1205 | Packing the “`git init`” call into the “`ssh`” call is something more |
| @@ -1213,31 +1213,31 @@ | ||
| 1213 | 1213 | |
| 1214 | 1214 | Having navigated that little minefield, |
| 1215 | 1215 | we can tell Git that there is a second origin, a “home” repo in |
| 1216 | 1216 | addition to the named “work” repo we set up earlier: |
| 1217 | 1217 | |
| 1218 | - git remote add home ssh://my-nas.local//SHARES/dayjob/repo.git | |
| 1219 | - git config master.remote home | |
| 1218 | + git remote add home ssh://my-nas.local//SHARES/dayjob/repo.git | |
| 1219 | + git config master.remote home | |
| 1220 | 1220 | |
| 1221 | 1221 | We don’t have to push or pull because the remote repo is a complete |
| 1222 | 1222 | clone of the repo on the laptop at this point, so we can just get to |
| 1223 | 1223 | work now, committing along the way to get our work safely off-machine |
| 1224 | 1224 | and onto our home NAS, like so: |
| 1225 | 1225 | |
| 1226 | - git add | |
| 1227 | - git commit | |
| 1228 | - git push | |
| 1226 | + git add | |
| 1227 | + git commit | |
| 1228 | + git push | |
| 1229 | 1229 | |
| 1230 | 1230 | We didn’t need to give a remote name on the push because we told it the |
| 1231 | 1231 | new upstream is the home NAS earlier. |
| 1232 | 1232 | |
| 1233 | 1233 | Now Friday comes along, and one of your office-mates needs a feature |
| 1234 | 1234 | you’re working on. You agree to come into the office later that |
| 1235 | 1235 | afternoon to sync up via the dev server: |
| 1236 | 1236 | |
| 1237 | - git push work master # send your changes from home up | |
| 1238 | - git pull work master # get your coworkers’ changes | |
| 1237 | + git push work master # send your changes from home up | |
| 1238 | + git pull work master # get your coworkers’ changes | |
| 1239 | 1239 | |
| 1240 | 1240 | Alternately, we could add “`--set-upstream/-u work`” to the first |
| 1241 | 1241 | command if we were coming into work long enough to do several Git-based things, not just pop in and sync. |
| 1242 | 1242 | That would allow the second to be just “`git pull`”, but the cost is |
| 1243 | 1243 | that when returning home, you’d have to manually reset the upstream |
| @@ -1254,13 +1254,13 @@ | ||
| 1254 | 1254 | Now we’re going to do the same thing using Fossil, with |
| 1255 | 1255 | the commands arranged in blocks corresponding to those above for comparison. |
| 1256 | 1256 | |
| 1257 | 1257 | We start the same way, cloning the work repo down to the laptop: |
| 1258 | 1258 | |
| 1259 | - fossil clone https://dev-server.example.com/repo | |
| 1260 | - cd repo | |
| 1261 | - fossil remote add work https://dev-server.example.com/repo | |
| 1259 | + fossil clone https://dev-server.example.com/repo | |
| 1260 | + cd repo | |
| 1261 | + fossil remote add work https://dev-server.example.com/repo | |
| 1262 | 1262 | |
| 1263 | 1263 | We’ve chosen the new “`fossil clone URI`” syntax added in Fossil 2.14 rather than separate |
| 1264 | 1264 | `clone` and `open` commands to make the parallel with Git clearer. [See |
| 1265 | 1265 | above](#mwd) for more on that topic. |
| 1266 | 1266 | |
| @@ -1278,11 +1278,11 @@ | ||
| 1278 | 1278 | below. |
| 1279 | 1279 | |
| 1280 | 1280 | On first beginning to work from home, we reverse-clone the Fossil repo |
| 1281 | 1281 | up to the NAS: |
| 1282 | 1282 | |
| 1283 | - rsync repo.fossil my-nas.local:/SHARES/dayjob/ | |
| 1283 | + rsync repo.fossil my-nas.local:/SHARES/dayjob/ | |
| 1284 | 1284 | |
| 1285 | 1285 | Now we’re beginning to see the advantage of Fossil’s simpler model, |
| 1286 | 1286 | relative to the tricky “`git init && git push`” sequence above. |
| 1287 | 1287 | Fossil’s alternative is almost impossible to get |
| 1288 | 1288 | wrong: copy this to that. *Done.* |
| @@ -1297,12 +1297,12 @@ | ||
| 1297 | 1297 | inherent in using `rsync` to clone a Git repo][grsync]. |
| 1298 | 1298 | |
| 1299 | 1299 | Now we set up the second remote, which is again simpler in the Fossil |
| 1300 | 1300 | case: |
| 1301 | 1301 | |
| 1302 | - fossil remote add home ssh://my-nas.local//SHARES/dayjob/repo.fossil | |
| 1303 | - fossil remote home | |
| 1302 | + fossil remote add home ssh://my-nas.local//SHARES/dayjob/repo.fossil | |
| 1303 | + fossil remote home | |
| 1304 | 1304 | |
| 1305 | 1305 | The first command is nearly identical to the Git version, but the second |
| 1306 | 1306 | is considerably simpler. And to be fair, you won’t find the |
| 1307 | 1307 | “`git config`” command above in all Git tutorials. The more common |
| 1308 | 1308 | alternative we found with web searches is even longer: |
| @@ -1309,21 +1309,21 @@ | ||
| 1309 | 1309 | “`git push --set-upstream home master`”. |
| 1310 | 1310 | |
| 1311 | 1311 | Where Fossil really wins is in the next step, making the initial commit |
| 1312 | 1312 | from home: |
| 1313 | 1313 | |
| 1314 | - fossil ci | |
| 1314 | + fossil ci | |
| 1315 | 1315 | |
| 1316 | 1316 | It’s one short command for Fossil instead of three for Git — or two if |
| 1317 | 1317 | you abbreviate it as “`git commit -a && git push`” — because of Fossil’s |
| 1318 | 1318 | [autosync] feature and deliberate omission of a |
| 1319 | 1319 | [staging feature](#staging). |
| 1320 | 1320 | |
| 1321 | 1321 | The “Friday afternoon sync-up” case is simpler, too: |
| 1322 | 1322 | |
| 1323 | - fossil remote work | |
| 1324 | - fossil sync | |
| 1323 | + fossil remote work | |
| 1324 | + fossil sync | |
| 1325 | 1325 | |
| 1326 | 1326 | Back at home, it’s simpler still: we may be able to do away with the second command, |
| 1327 | 1327 | saying just “`fossil remote home`” because the sync will happen as part |
| 1328 | 1328 | of the next commit, thanks once again to Fossil’s autosync feature. If |
| 1329 | 1329 | the working branch now has commits from other developers after syncing |
| 1330 | 1330 |
| --- www/gitusers.md | |
| +++ www/gitusers.md | |
| @@ -73,15 +73,15 @@ | |
| 73 | document][ckwf] to see the practical differences. |
| 74 | |
| 75 | There is one Git-specific detail we wish to add beyond what that |
| 76 | document already covers. This command: |
| 77 | |
| 78 | git checkout some-branch |
| 79 | |
| 80 | …is best given as: |
| 81 | |
| 82 | fossil update some-branch |
| 83 | |
| 84 | …in Fossil. There is a [`fossil checkout`][co] command, but it has |
| 85 | [several differences](./co-vs-up.md) that make it less broadly useful |
| 86 | than [`fossil update`][up] in everyday operation, so we recommend that |
| 87 | Git users moving to Fossil develop a habit of typing `fossil up` rather |
| @@ -109,11 +109,11 @@ | |
| 109 | |
| 110 | The `fossil pull` command is simply the reverse of |
| 111 | `fossil push`, so that `fossil sync` [is functionally equivalent |
| 112 | to](./sync.wiki#sync): |
| 113 | |
| 114 | fossil push ; fossil pull |
| 115 | |
| 116 | There is no implicit “and update the local working directory” step in Fossil’s |
| 117 | push, pull, or sync commands, as there is with `git pull`. |
| 118 | |
| 119 | Someone coming from the Git perspective may perceive that `fossil up` |
| @@ -180,29 +180,29 @@ | |
| 180 | check-out directories][mcw] with Git. |
| 181 | |
| 182 | The old way is to simply symlink the `.git` directory between working |
| 183 | trees: |
| 184 | |
| 185 | mkdir ../foo-branch |
| 186 | ln -s ../actual-clone-dir/.git . |
| 187 | git checkout foo-branch |
| 188 | |
| 189 | The symlink trick has a number of problems, the largest being that |
| 190 | symlinks weren’t available on Windows until Vista, and until the Windows |
| 191 | 10 Creators Update was released in spring of 2017, you had to be an |
| 192 | Administrator to use the feature besides. ([Source][wsyml]) Git 2.5 solved |
| 193 | this problem back when Windows XP was Microsoft’s current offering |
| 194 | by adding the `git-worktree` command: |
| 195 | |
| 196 | git worktree add ../foo-branch foo-branch |
| 197 | cd ../foo-branch |
| 198 | |
| 199 | That is approximately equivalent to this in Fossil: |
| 200 | |
| 201 | mkdir ../foo-branch |
| 202 | cd ../foo-branch |
| 203 | fossil open /path/to/repo.fossil foo-branch |
| 204 | |
| 205 | The Fossil alternative is wordier, but since this tends to be one-time setup, |
| 206 | not something you do everyday, the overhead is insignificant. This author keeps a “scratch” check-out |
| 207 | for cases where it’s inappropriate to reuse the “trunk” check-out, |
| 208 | isolating all of my expedient switch-in-place actions to that one |
| @@ -211,20 +211,20 @@ | |
| 211 | up, I rarely pay the cost of these wordier commands. |
| 212 | |
| 213 | That then leads us to the closest equivalent in Git to [closing a Fossil |
| 214 | check-out](#close): |
| 215 | |
| 216 | git worktree remove . |
| 217 | |
| 218 | Note, however, that unlike `fossil close`, once the Git command |
| 219 | determines that there are no uncommitted changes, it blows away all of |
| 220 | the checked-out files! Fossil’s alternative is shorter, easier to |
| 221 | remember, and safer. |
| 222 | |
| 223 | There’s another way to get Fossil-like separate worktrees in Git: |
| 224 | |
| 225 | git clone --separate-git-dir repo.git https://example.com/repo |
| 226 | |
| 227 | This allows you to have your Git repository directory entirely separate |
| 228 | from your working tree, with `.git` in the check-out directory being a |
| 229 | file that points to `../repo.git`, in this example. |
| 230 | |
| @@ -238,22 +238,22 @@ | |
| 238 | from working directory creates in practice, consider this common Git “init in place” |
| 239 | method for creating a new repository from an existing tree of files, |
| 240 | perhaps because you are placing that project under version control for |
| 241 | the first time: |
| 242 | |
| 243 | cd long-established-project |
| 244 | git init |
| 245 | git add * |
| 246 | git commit -m "Initial commit of project." |
| 247 | |
| 248 | The closest equivalent in Fossil is: |
| 249 | |
| 250 | cd long-established-project |
| 251 | fossil init .fsl |
| 252 | fossil open --force .fsl |
| 253 | fossil add * |
| 254 | fossil ci -m "Initial commit of project." |
| 255 | |
| 256 | Note that unlike in Git, you can abbreviate the “`commit`” command in |
| 257 | Fossil as “`ci`” for compatibility with CVS, Subversion, etc. |
| 258 | |
| 259 | This creates a `.fsl` repo DB at the root of the project check-out to |
| @@ -316,19 +316,19 @@ | |
| 316 | #### <a id="emu-log"></a> Emulating `git log` |
| 317 | |
| 318 | If you truly need a backwards-in-time-only view of history in Fossil to |
| 319 | emulate `git log`, this is as close as you can currently come: |
| 320 | |
| 321 | fossil timeline parents current |
| 322 | |
| 323 | Again, though, this isn’t restricted to a single branch, as `git log` |
| 324 | is. |
| 325 | |
| 326 | Another useful rough equivalent is: |
| 327 | |
| 328 | git log --raw |
| 329 | fossil time -v |
| 330 | |
| 331 | This shows what changed in each version, though Fossil’s view is more a |
| 332 | summary than a list of raw changes. To dig deeper into single commits, |
| 333 | you can use Fossil’s [`info` command][infoc] or its [`/info` view][infow]. |
| 334 | |
| @@ -344,33 +344,33 @@ | |
| 344 | Though there is no `fossil whatchanged` command, the same sort of |
| 345 | information is available. For example, to pull the current changes from |
| 346 | the remote repository and then inspect them before updating the local |
| 347 | working directory, you might say this in Git: |
| 348 | |
| 349 | git fetch |
| 350 | git whatchanged ..@{u} |
| 351 | |
| 352 | …which you can approximate in Fossil as: |
| 353 | |
| 354 | fossil pull |
| 355 | fossil up -n |
| 356 | fossil diff --from tip |
| 357 | |
| 358 | To invert the `diff` to show a more natural patch, the command needs to |
| 359 | be a bit more complicated, since you can’t currently give `--to` |
| 360 | without `--from`. |
| 361 | |
| 362 | fossil diff --from current --to tip |
| 363 | |
| 364 | Rather than use the “dry run” form of [the `update` command][up], you can |
| 365 | say: |
| 366 | |
| 367 | fossil timeline after current |
| 368 | |
| 369 | …or if you want to restrict the output to the current branch: |
| 370 | |
| 371 | fossil timeline descendants current |
| 372 | |
| 373 | |
| 374 | #### <a id="ckin-names"></a> Symbolic Check-In Names |
| 375 | |
| 376 | Note the use of [human-readable symbolic version names][scin] in Fossil |
| @@ -377,42 +377,42 @@ | |
| 377 | rather than [Git’s cryptic notations][gcn]. |
| 378 | |
| 379 | For a more dramatic example of this, let us ask Git, “What changed since the |
| 380 | beginning of last month?” being October 2020 as I write this: |
| 381 | |
| 382 | git log master@{2020-10-01}..HEAD |
| 383 | |
| 384 | That’s rather obscure! Fossil answers the same question with a simpler |
| 385 | command: |
| 386 | |
| 387 | fossil timeline after 2020-10-01 |
| 388 | |
| 389 | You may need to add `-n 0` to bypass the default output limit of |
| 390 | `fossil timeline`, 20 entries. Without that, this command reads |
| 391 | almost like English. |
| 392 | |
| 393 | Some Git users like to write commands like the above so: |
| 394 | |
| 395 | git log @{2020-10-01}..@ |
| 396 | |
| 397 | Is that better? “@” now means two different things: an at-time reference |
| 398 | and a shortcut for `HEAD`! |
| 399 | |
| 400 | If you are one of those that like short commands, Fossil’s method is |
| 401 | less cryptic: it lets you shorten words in most cases up to the point |
| 402 | that they become ambiguous. For example, you may abbreviate the last |
| 403 | `fossil` command in the prior section: |
| 404 | |
| 405 | fossil tim d c |
| 406 | |
| 407 | …beyond which the `timeline` command becomes ambiguous with `ticket`. |
| 408 | |
| 409 | Some Fossil users employ shell aliases, symlinks, or scripts to shorten |
| 410 | the command still further: |
| 411 | |
| 412 | alias f=fossil |
| 413 | f tim d c |
| 414 | |
| 415 | Granted, that’s rather obscure, but you you can also choose something |
| 416 | intermediate like “`f time desc curr`”, which is reasonably clear. |
| 417 | |
| 418 | [35pct]: https://www.sqlite.org/fasterthanfs.html |
| @@ -468,11 +468,11 @@ | |
| 468 | automatically. There is no need for the "-a" option as with Git. |
| 469 | |
| 470 | If you only want to commit _some_ of the changes, list the names |
| 471 | of the files or directories you want to commit as arguments, like this: |
| 472 | |
| 473 | fossil commit src/feature.c doc/feature.md examples/feature |
| 474 | |
| 475 | Note that the last element is a directory name, meaning “any changed |
| 476 | file under the `examples/feature` directory.” |
| 477 | |
| 478 | Although there are currently no |
| @@ -482,12 +482,12 @@ | |
| 482 | running it through [Patchouli]. |
| 483 | |
| 484 | Rather than use `fossil diff -i` to produce such a patch, a safer and |
| 485 | more idiomatic method would be: |
| 486 | |
| 487 | fossil stash save -m 'my big ball-o-hackage' |
| 488 | fossil stash diff > my-changes.patch |
| 489 | |
| 490 | That stores your changes in the stash, then lets you operate on a copy |
| 491 | of that patch. Each time you re-run the second command, it will take the |
| 492 | current state of the working directory into account to produce a |
| 493 | potentially different patch, likely smaller because it leaves out patch |
| @@ -526,30 +526,30 @@ | |
| 526 | ## Create Branches at Point of Need, Rather Than Ahead of Need |
| 527 | |
| 528 | Fossil prefers that you create new branches as part of the first commit |
| 529 | on that branch: |
| 530 | |
| 531 | fossil commit --branch my-branch |
| 532 | |
| 533 | If that commit is successful, your local check-out directory is then |
| 534 | switched to the tip of that branch, so subsequent commits don’t need the |
| 535 | “`--branch`” option. You simply say `fossil commit` again to continue |
| 536 | adding commits to the tip of that branch. |
| 537 | |
| 538 | To switch back to the parent branch, say something like: |
| 539 | |
| 540 | fossil update trunk |
| 541 | |
| 542 | (This is approximately equivalent to `git checkout master`.) |
| 543 | |
| 544 | Fossil does also support the Git style, creating the branch ahead of |
| 545 | need: |
| 546 | |
| 547 | fossil branch new my-branch |
| 548 | fossil up my-branch |
| 549 | ...work on first commit... |
| 550 | fossil commit |
| 551 | |
| 552 | This is more verbose, giving the same overall effect though the initial |
| 553 | actions are inverted: create a new branch for the first commit, switch |
| 554 | the check-out directory to that branch, and make that first commit. As |
| 555 | above, subsequent commits are descendants of that initial branch commit. |
| @@ -558,11 +558,11 @@ | |
| 558 | |
| 559 | Fossil also allows you to move a check-in to a different branch |
| 560 | *after* you commit it, using the "`fossil amend`" command. |
| 561 | For example: |
| 562 | |
| 563 | fossil amend current --branch my-branch |
| 564 | |
| 565 | This works by inserting a tag into the repository that causes the web UI |
| 566 | to relabel commits from that point forward with the new name. Like Git, |
| 567 | Fossil’s fundamental data structure is the interlinked DAG of commit |
| 568 | hashes; branch names are supplemental data for making it easier for the |
| @@ -591,15 +591,15 @@ | |
| 591 | make them under this eventually-consistent design philosophy. |
| 592 | |
| 593 | Branch *names* sync automatically in Fossil, not just the |
| 594 | content of those branches. That means this common Git command: |
| 595 | |
| 596 | git push origin master |
| 597 | |
| 598 | …is simply this in Fossil: |
| 599 | |
| 600 | fossil push |
| 601 | |
| 602 | Fossil doesn’t need to be told what to push or where to push it: it just |
| 603 | keeps using the same remote server URL you gave it last |
| 604 | until you [tell it to do something different][rem]. It pushes all |
| 605 | branches, not just one named local branch. |
| @@ -613,11 +613,11 @@ | |
| 613 | |
| 614 | Fossil’s [autosync][wflow] feature, normally enabled, has no |
| 615 | equivalent in Git. If you want Fossil to behave like Git, you can turn |
| 616 | it off: |
| 617 | |
| 618 | fossil set autosync 0 |
| 619 | |
| 620 | Let’s say that you have a typical server-and-workstations model with two |
| 621 | working clones on different machines, that you have disabled autosync, |
| 622 | and that this common sequence then occurs: |
| 623 | |
| @@ -692,16 +692,16 @@ | |
| 692 | by a colon. The simplified example above is also liable to become |
| 693 | confused by whitespace in file names.) |
| 694 | |
| 695 | |
| 696 | ``` |
| 697 | $ repo=$(fossil status | grep ^repo | cut -f2 -d:) |
| 698 | $ url=$(fossil remote) |
| 699 | $ fossil close # Stop here and think if it warns you! |
| 700 | $ mv $repo ${repo}.old |
| 701 | $ fossil clone $url $repo |
| 702 | $ fossil open --force $repo |
| 703 | ``` |
| 704 | |
| 705 | What, then, should you as a Git transplant do instead when you find |
| 706 | yourself reaching for “`git reset`”? |
| 707 | |
| @@ -717,13 +717,13 @@ | |
| 717 | sort of thing is unnecessary. |
| 718 | |
| 719 | Instead, Bob can say something like this: |
| 720 | |
| 721 | ``` |
| 722 | fossil amend --branch MISTAKE --hide --close -m "mea culpa" tip |
| 723 | fossil up trunk |
| 724 | fossil push |
| 725 | ``` |
| 726 | |
| 727 | Unlike in Git, the “`amend`” command doesn’t modify prior committed |
| 728 | artifacts. Bob’s first command doesn’t delete anything, merely tells |
| 729 | Fossil to hide his mistake from timeline views by inserting a few new |
| @@ -750,14 +750,14 @@ | |
| 750 | marked the branch as closed will prevent that from going thru, cluing |
| 751 | Alice into what she needs to do to remedy the situation, but that merely |
| 752 | shows why it’s a better workflow if Alice makes the amendment herself: |
| 753 | |
| 754 | ``` |
| 755 | fossil amend --branch MISTAKE --hide --close \ |
| 756 | -m "shunt Bob’s erroneous commit off" tip |
| 757 | fossil up trunk |
| 758 | fossil push |
| 759 | ``` |
| 760 | |
| 761 | Then she can fire off an email listing Bob’s assorted failings and go |
| 762 | about her work. This asynchronous workflow solves the problem without |
| 763 | requiring explicit coordination with Bob. When he gets his email, he can |
| @@ -834,18 +834,18 @@ | |
| 834 | Nevertheless, there are multiple ways to get colorized diff output from |
| 835 | Fossil: |
| 836 | |
| 837 | * The most direct method is to delegate diff behavior back to Git: |
| 838 | |
| 839 | fossil set --global diff-command 'git diff --no-index' |
| 840 | |
| 841 | The flag permits it to diff files that aren’t inside a Git repository. |
| 842 | |
| 843 | * Another method is to install [`colordiff`][cdiff] — included in |
| 844 | [many package systems][cdpkg] — then say: |
| 845 | |
| 846 | fossil set --global diff-command 'colordiff -wu' |
| 847 | |
| 848 | Because this is unconditional, unlike `git diff --color=auto`, you |
| 849 | will then have to remember to add the `-i` option to `fossil diff` |
| 850 | commands when you want color disabled, such as when producing |
| 851 | `patch(1)` files or piping diff output to another command that |
| @@ -876,15 +876,15 @@ | |
| 876 | functionality is present in Fossil under other commands: |
| 877 | |
| 878 | |
| 879 | #### <a id="patch"></a> Show a Patch for a Commit |
| 880 | |
| 881 | git show -p COMMIT_ID |
| 882 | |
| 883 | …gives much the same output as |
| 884 | |
| 885 | fossil diff --checkin COMMIT_ID |
| 886 | |
| 887 | …only without the patch email header. Git comes out of the [LKML] world, |
| 888 | where emailing a patch is a normal thing to do. Fossil is [designed for |
| 889 | cohesive teams][devorg] where drive-by patches are rarer. |
| 890 | |
| @@ -893,32 +893,32 @@ | |
| 893 | “`VERSION`” or “`NAME`” where this is allowed, since the version string |
| 894 | or name might not refer to a commit ID, but instead to a forum post, a |
| 895 | wiki document, etc. For instance, the following command answers the question “What did |
| 896 | I just commit?” |
| 897 | |
| 898 | fossil diff --checkin tip |
| 899 | |
| 900 | …or equivalently using a different symbolic commit name: |
| 901 | |
| 902 | fossil diff --from prev |
| 903 | |
| 904 | [devorg]: ./fossil-v-git.wiki#devorg |
| 905 | [LKML]: https://lkml.org/ |
| 906 | |
| 907 | |
| 908 | #### <a id="cmsg"></a> Show a Specific Commit Message |
| 909 | |
| 910 | git show -s COMMIT_ID |
| 911 | |
| 912 | |
| 913 | …is |
| 914 | |
| 915 | fossil time -n 1 COMMIT_ID |
| 916 | |
| 917 | …or with a shorter, more obvious command, though with more verbose output: |
| 918 | |
| 919 | fossil info COMMIT_ID |
| 920 | |
| 921 | The `fossil info` command isn’t otherwise a good equivalent to |
| 922 | `git show`; it just overlaps its functionality in some areas. Much of |
| 923 | what’s missing is present in the corresponding [`/info` web |
| 924 | view][infow], though. |
| @@ -927,17 +927,17 @@ | |
| 927 | #### <a id="dstat"></a> Diff Statistics |
| 928 | |
| 929 | Fossil’s closest internal equivalent to commands like |
| 930 | `git show --stat` is: |
| 931 | |
| 932 | fossil diff -i --from 2020-04-01 --numstat |
| 933 | |
| 934 | The `--numstat` output is a bit cryptic, so we recommend delegating |
| 935 | this task to [the widely-available `diffstat` tool][dst], which gives |
| 936 | a histogram in its default output mode rather than bare integers: |
| 937 | |
| 938 | fossil diff -i -v --from 2020-04-01 | diffstat |
| 939 | |
| 940 | We gave the `-i` flag in both cases to force Fossil to use its internal |
| 941 | diff implementation, bypassing [your local `diff-command` setting][dcset]. |
| 942 | The `--numstat` option has no effect when you have an external diff |
| 943 | command set, and some diff command alternatives like |
| @@ -999,19 +999,19 @@ | |
| 999 | default: they do not actually rename or delete the files in your |
| 1000 | check-out. |
| 1001 | |
| 1002 | If you don’t like that default, you can change it globally: |
| 1003 | |
| 1004 | fossil setting --global mv-rm-files 1 |
| 1005 | |
| 1006 | Now these commands behave like in Git in any Fossil repository where |
| 1007 | this setting hasn’t been overridden locally. |
| 1008 | |
| 1009 | If you want to keep Fossil’s soft `mv/rm` behavior most of the time, you |
| 1010 | can cast it away on a per-command basis: |
| 1011 | |
| 1012 | fossil mv --hard old-name new-name |
| 1013 | |
| 1014 | [mv]: /help?cmd=mv |
| 1015 | [rm]: /help?cmd=rm |
| 1016 | |
| 1017 | |
| @@ -1032,11 +1032,11 @@ | |
| 1032 | |
| 1033 | My search engine’s first result for “git checkout by date” is [this |
| 1034 | highly-upvoted accepted Stack Overflow answer][gcod]. The first command |
| 1035 | it gives is based on Git’s [`rev-parse` feature][grp]: |
| 1036 | |
| 1037 | git checkout master@{2020-03-17} |
| 1038 | |
| 1039 | There are a number of weaknesses in this command. From least to most |
| 1040 | critical: |
| 1041 | |
| 1042 | 1. It’s a bit cryptic. Leave off the refname or punctuation, and it |
| @@ -1072,11 +1072,11 @@ | |
| 1072 | best case. |
| 1073 | |
| 1074 | That same Stack Overflow answer therefore goes on to recommend an |
| 1075 | entirely different command: |
| 1076 | |
| 1077 | git checkout $(git rev-list -n 1 --first-parent --before="2020-03-17" master) |
| 1078 | |
| 1079 | We believe you get such answers to Git help requests in part |
| 1080 | because of its lack of an always-up-to-date [index into its log](#log) and in |
| 1081 | part because of its “small tools loosely joined” design philosophy. This |
| 1082 | sort of command is therefore composed piece by piece: |
| @@ -1084,36 +1084,36 @@ | |
| 1084 | <p style="text-align:center">◆ ◆ ◆</p> |
| 1085 | |
| 1086 | “Oh, I know, I’ll search the rev-list, which outputs commit IDs by |
| 1087 | parsing the log backwards from `HEAD`! Easy!” |
| 1088 | |
| 1089 | git rev-list --before=2020-03-17 |
| 1090 | |
| 1091 | “Blast! Forgot the commit ID!” |
| 1092 | |
| 1093 | git rev-list --before=2020-03-17 master |
| 1094 | |
| 1095 | “Double blast! It just spammed my terminal with revision IDs! I need to |
| 1096 | limit it to the single closest match: |
| 1097 | |
| 1098 | git rev-list -n 1 --before=2020-03-17 master |
| 1099 | |
| 1100 | “Okay, it gives me a single revision ID now, but is it what I’m after? |
| 1101 | Let’s take a look…” |
| 1102 | |
| 1103 | git show $(git rev-list -n 1 --before=2020-03-17 master) |
| 1104 | |
| 1105 | “Oops, that’s giving me a merge commit, not what I want. |
| 1106 | Off to search the web… Okay, it says I need to give either the |
| 1107 | `--first-parent` or `--no-merges` flag to show only regular commits, |
| 1108 | not merge-commits. Let’s try the first one:” |
| 1109 | |
| 1110 | git show $(git rev-list -n 1 --first-parent --before=2020-03-17 master) |
| 1111 | |
| 1112 | “Better. Let’s check it out:” |
| 1113 | |
| 1114 | git checkout $(git rev-list -n 1 --first-parent --before=2020-03-17 master) |
| 1115 | |
| 1116 | “Success, I guess?” |
| 1117 | |
| 1118 | <p style="text-align:center">◆ ◆ ◆</p> |
| 1119 | |
| @@ -1132,11 +1132,11 @@ | |
| 1132 | 17th of March, 2020. |
| 1133 | |
| 1134 | You may be asking with an exasperated huff, “What is your *point*, man?” |
| 1135 | The point is that the equivalent in Fossil is simply: |
| 1136 | |
| 1137 | fossil up 2020-03-17 |
| 1138 | |
| 1139 | …which will *always* give the commit closest to midnight UTC on the 17th |
| 1140 | of March, 2020, no matter whether you do it on a fresh clone or a stale |
| 1141 | one. The answer won’t shift about from one clone to the next or from |
| 1142 | one local time of day to the next. We owe this reliability and stability |
| @@ -1181,13 +1181,13 @@ | |
| 1181 | #### Git Method |
| 1182 | |
| 1183 | We first need to clone the work repo down to our laptop, so we can work on it |
| 1184 | at home: |
| 1185 | |
| 1186 | git clone https://dev-server.example.com/repo |
| 1187 | cd repo |
| 1188 | git remote rename origin work |
| 1189 | |
| 1190 | The last command is optional, strictly speaking. We could continue to |
| 1191 | use Git’s default name for the work repo’s origin — sensibly enough |
| 1192 | called “`origin`” — but it makes later commands harder to understand, so |
| 1193 | we rename it here. This will also make the parallel with Fossil easier |
| @@ -1194,12 +1194,12 @@ | |
| 1194 | to draw. |
| 1195 | |
| 1196 | The first time we go home after this, we have to reverse-clone the work |
| 1197 | repo up to the NAS: |
| 1198 | |
| 1199 | ssh my-nas.local 'git init --bare /SHARES/dayjob/repo.git' |
| 1200 | git push --all ssh://my-nas.local//SHARES/dayjob/repo.git |
| 1201 | |
| 1202 | Realize that this is carefully optimized down to these two long |
| 1203 | commands. In practice, we’d expect a user typing these commands by hand from memory |
| 1204 | to need to give four or more commands here instead. |
| 1205 | Packing the “`git init`” call into the “`ssh`” call is something more |
| @@ -1213,31 +1213,31 @@ | |
| 1213 | |
| 1214 | Having navigated that little minefield, |
| 1215 | we can tell Git that there is a second origin, a “home” repo in |
| 1216 | addition to the named “work” repo we set up earlier: |
| 1217 | |
| 1218 | git remote add home ssh://my-nas.local//SHARES/dayjob/repo.git |
| 1219 | git config master.remote home |
| 1220 | |
| 1221 | We don’t have to push or pull because the remote repo is a complete |
| 1222 | clone of the repo on the laptop at this point, so we can just get to |
| 1223 | work now, committing along the way to get our work safely off-machine |
| 1224 | and onto our home NAS, like so: |
| 1225 | |
| 1226 | git add |
| 1227 | git commit |
| 1228 | git push |
| 1229 | |
| 1230 | We didn’t need to give a remote name on the push because we told it the |
| 1231 | new upstream is the home NAS earlier. |
| 1232 | |
| 1233 | Now Friday comes along, and one of your office-mates needs a feature |
| 1234 | you’re working on. You agree to come into the office later that |
| 1235 | afternoon to sync up via the dev server: |
| 1236 | |
| 1237 | git push work master # send your changes from home up |
| 1238 | git pull work master # get your coworkers’ changes |
| 1239 | |
| 1240 | Alternately, we could add “`--set-upstream/-u work`” to the first |
| 1241 | command if we were coming into work long enough to do several Git-based things, not just pop in and sync. |
| 1242 | That would allow the second to be just “`git pull`”, but the cost is |
| 1243 | that when returning home, you’d have to manually reset the upstream |
| @@ -1254,13 +1254,13 @@ | |
| 1254 | Now we’re going to do the same thing using Fossil, with |
| 1255 | the commands arranged in blocks corresponding to those above for comparison. |
| 1256 | |
| 1257 | We start the same way, cloning the work repo down to the laptop: |
| 1258 | |
| 1259 | fossil clone https://dev-server.example.com/repo |
| 1260 | cd repo |
| 1261 | fossil remote add work https://dev-server.example.com/repo |
| 1262 | |
| 1263 | We’ve chosen the new “`fossil clone URI`” syntax added in Fossil 2.14 rather than separate |
| 1264 | `clone` and `open` commands to make the parallel with Git clearer. [See |
| 1265 | above](#mwd) for more on that topic. |
| 1266 | |
| @@ -1278,11 +1278,11 @@ | |
| 1278 | below. |
| 1279 | |
| 1280 | On first beginning to work from home, we reverse-clone the Fossil repo |
| 1281 | up to the NAS: |
| 1282 | |
| 1283 | rsync repo.fossil my-nas.local:/SHARES/dayjob/ |
| 1284 | |
| 1285 | Now we’re beginning to see the advantage of Fossil’s simpler model, |
| 1286 | relative to the tricky “`git init && git push`” sequence above. |
| 1287 | Fossil’s alternative is almost impossible to get |
| 1288 | wrong: copy this to that. *Done.* |
| @@ -1297,12 +1297,12 @@ | |
| 1297 | inherent in using `rsync` to clone a Git repo][grsync]. |
| 1298 | |
| 1299 | Now we set up the second remote, which is again simpler in the Fossil |
| 1300 | case: |
| 1301 | |
| 1302 | fossil remote add home ssh://my-nas.local//SHARES/dayjob/repo.fossil |
| 1303 | fossil remote home |
| 1304 | |
| 1305 | The first command is nearly identical to the Git version, but the second |
| 1306 | is considerably simpler. And to be fair, you won’t find the |
| 1307 | “`git config`” command above in all Git tutorials. The more common |
| 1308 | alternative we found with web searches is even longer: |
| @@ -1309,21 +1309,21 @@ | |
| 1309 | “`git push --set-upstream home master`”. |
| 1310 | |
| 1311 | Where Fossil really wins is in the next step, making the initial commit |
| 1312 | from home: |
| 1313 | |
| 1314 | fossil ci |
| 1315 | |
| 1316 | It’s one short command for Fossil instead of three for Git — or two if |
| 1317 | you abbreviate it as “`git commit -a && git push`” — because of Fossil’s |
| 1318 | [autosync] feature and deliberate omission of a |
| 1319 | [staging feature](#staging). |
| 1320 | |
| 1321 | The “Friday afternoon sync-up” case is simpler, too: |
| 1322 | |
| 1323 | fossil remote work |
| 1324 | fossil sync |
| 1325 | |
| 1326 | Back at home, it’s simpler still: we may be able to do away with the second command, |
| 1327 | saying just “`fossil remote home`” because the sync will happen as part |
| 1328 | of the next commit, thanks once again to Fossil’s autosync feature. If |
| 1329 | the working branch now has commits from other developers after syncing |
| 1330 |
| --- www/gitusers.md | |
| +++ www/gitusers.md | |
| @@ -73,15 +73,15 @@ | |
| 73 | document][ckwf] to see the practical differences. |
| 74 | |
| 75 | There is one Git-specific detail we wish to add beyond what that |
| 76 | document already covers. This command: |
| 77 | |
| 78 | git checkout some-branch |
| 79 | |
| 80 | …is best given as: |
| 81 | |
| 82 | fossil update some-branch |
| 83 | |
| 84 | …in Fossil. There is a [`fossil checkout`][co] command, but it has |
| 85 | [several differences](./co-vs-up.md) that make it less broadly useful |
| 86 | than [`fossil update`][up] in everyday operation, so we recommend that |
| 87 | Git users moving to Fossil develop a habit of typing `fossil up` rather |
| @@ -109,11 +109,11 @@ | |
| 109 | |
| 110 | The `fossil pull` command is simply the reverse of |
| 111 | `fossil push`, so that `fossil sync` [is functionally equivalent |
| 112 | to](./sync.wiki#sync): |
| 113 | |
| 114 | fossil push ; fossil pull |
| 115 | |
| 116 | There is no implicit “and update the local working directory” step in Fossil’s |
| 117 | push, pull, or sync commands, as there is with `git pull`. |
| 118 | |
| 119 | Someone coming from the Git perspective may perceive that `fossil up` |
| @@ -180,29 +180,29 @@ | |
| 180 | check-out directories][mcw] with Git. |
| 181 | |
| 182 | The old way is to simply symlink the `.git` directory between working |
| 183 | trees: |
| 184 | |
| 185 | mkdir ../foo-branch |
| 186 | ln -s ../actual-clone-dir/.git . |
| 187 | git checkout foo-branch |
| 188 | |
| 189 | The symlink trick has a number of problems, the largest being that |
| 190 | symlinks weren’t available on Windows until Vista, and until the Windows |
| 191 | 10 Creators Update was released in spring of 2017, you had to be an |
| 192 | Administrator to use the feature besides. ([Source][wsyml]) Git 2.5 solved |
| 193 | this problem back when Windows XP was Microsoft’s current offering |
| 194 | by adding the `git-worktree` command: |
| 195 | |
| 196 | git worktree add ../foo-branch foo-branch |
| 197 | cd ../foo-branch |
| 198 | |
| 199 | That is approximately equivalent to this in Fossil: |
| 200 | |
| 201 | mkdir ../foo-branch |
| 202 | cd ../foo-branch |
| 203 | fossil open /path/to/repo.fossil foo-branch |
| 204 | |
| 205 | The Fossil alternative is wordier, but since this tends to be one-time setup, |
| 206 | not something you do everyday, the overhead is insignificant. This author keeps a “scratch” check-out |
| 207 | for cases where it’s inappropriate to reuse the “trunk” check-out, |
| 208 | isolating all of my expedient switch-in-place actions to that one |
| @@ -211,20 +211,20 @@ | |
| 211 | up, I rarely pay the cost of these wordier commands. |
| 212 | |
| 213 | That then leads us to the closest equivalent in Git to [closing a Fossil |
| 214 | check-out](#close): |
| 215 | |
| 216 | git worktree remove . |
| 217 | |
| 218 | Note, however, that unlike `fossil close`, once the Git command |
| 219 | determines that there are no uncommitted changes, it blows away all of |
| 220 | the checked-out files! Fossil’s alternative is shorter, easier to |
| 221 | remember, and safer. |
| 222 | |
| 223 | There’s another way to get Fossil-like separate worktrees in Git: |
| 224 | |
| 225 | git clone --separate-git-dir repo.git https://example.com/repo |
| 226 | |
| 227 | This allows you to have your Git repository directory entirely separate |
| 228 | from your working tree, with `.git` in the check-out directory being a |
| 229 | file that points to `../repo.git`, in this example. |
| 230 | |
| @@ -238,22 +238,22 @@ | |
| 238 | from working directory creates in practice, consider this common Git “init in place” |
| 239 | method for creating a new repository from an existing tree of files, |
| 240 | perhaps because you are placing that project under version control for |
| 241 | the first time: |
| 242 | |
| 243 | cd long-established-project |
| 244 | git init |
| 245 | git add * |
| 246 | git commit -m "Initial commit of project." |
| 247 | |
| 248 | The closest equivalent in Fossil is: |
| 249 | |
| 250 | cd long-established-project |
| 251 | fossil init .fsl |
| 252 | fossil open --force .fsl |
| 253 | fossil add * |
| 254 | fossil ci -m "Initial commit of project." |
| 255 | |
| 256 | Note that unlike in Git, you can abbreviate the “`commit`” command in |
| 257 | Fossil as “`ci`” for compatibility with CVS, Subversion, etc. |
| 258 | |
| 259 | This creates a `.fsl` repo DB at the root of the project check-out to |
| @@ -316,19 +316,19 @@ | |
| 316 | #### <a id="emu-log"></a> Emulating `git log` |
| 317 | |
| 318 | If you truly need a backwards-in-time-only view of history in Fossil to |
| 319 | emulate `git log`, this is as close as you can currently come: |
| 320 | |
| 321 | fossil timeline parents current |
| 322 | |
| 323 | Again, though, this isn’t restricted to a single branch, as `git log` |
| 324 | is. |
| 325 | |
| 326 | Another useful rough equivalent is: |
| 327 | |
| 328 | git log --raw |
| 329 | fossil time -v |
| 330 | |
| 331 | This shows what changed in each version, though Fossil’s view is more a |
| 332 | summary than a list of raw changes. To dig deeper into single commits, |
| 333 | you can use Fossil’s [`info` command][infoc] or its [`/info` view][infow]. |
| 334 | |
| @@ -344,33 +344,33 @@ | |
| 344 | Though there is no `fossil whatchanged` command, the same sort of |
| 345 | information is available. For example, to pull the current changes from |
| 346 | the remote repository and then inspect them before updating the local |
| 347 | working directory, you might say this in Git: |
| 348 | |
| 349 | git fetch |
| 350 | git whatchanged ..@{u} |
| 351 | |
| 352 | …which you can approximate in Fossil as: |
| 353 | |
| 354 | fossil pull |
| 355 | fossil up -n |
| 356 | fossil diff --from tip |
| 357 | |
| 358 | To invert the `diff` to show a more natural patch, the command needs to |
| 359 | be a bit more complicated, since you can’t currently give `--to` |
| 360 | without `--from`. |
| 361 | |
| 362 | fossil diff --from current --to tip |
| 363 | |
| 364 | Rather than use the “dry run” form of [the `update` command][up], you can |
| 365 | say: |
| 366 | |
| 367 | fossil timeline after current |
| 368 | |
| 369 | …or if you want to restrict the output to the current branch: |
| 370 | |
| 371 | fossil timeline descendants current |
| 372 | |
| 373 | |
| 374 | #### <a id="ckin-names"></a> Symbolic Check-In Names |
| 375 | |
| 376 | Note the use of [human-readable symbolic version names][scin] in Fossil |
| @@ -377,42 +377,42 @@ | |
| 377 | rather than [Git’s cryptic notations][gcn]. |
| 378 | |
| 379 | For a more dramatic example of this, let us ask Git, “What changed since the |
| 380 | beginning of last month?” being October 2020 as I write this: |
| 381 | |
| 382 | git log master@{2020-10-01}..HEAD |
| 383 | |
| 384 | That’s rather obscure! Fossil answers the same question with a simpler |
| 385 | command: |
| 386 | |
| 387 | fossil timeline after 2020-10-01 |
| 388 | |
| 389 | You may need to add `-n 0` to bypass the default output limit of |
| 390 | `fossil timeline`, 20 entries. Without that, this command reads |
| 391 | almost like English. |
| 392 | |
| 393 | Some Git users like to write commands like the above so: |
| 394 | |
| 395 | git log @{2020-10-01}..@ |
| 396 | |
| 397 | Is that better? “@” now means two different things: an at-time reference |
| 398 | and a shortcut for `HEAD`! |
| 399 | |
| 400 | If you are one of those that like short commands, Fossil’s method is |
| 401 | less cryptic: it lets you shorten words in most cases up to the point |
| 402 | that they become ambiguous. For example, you may abbreviate the last |
| 403 | `fossil` command in the prior section: |
| 404 | |
| 405 | fossil tim d c |
| 406 | |
| 407 | …beyond which the `timeline` command becomes ambiguous with `ticket`. |
| 408 | |
| 409 | Some Fossil users employ shell aliases, symlinks, or scripts to shorten |
| 410 | the command still further: |
| 411 | |
| 412 | alias f=fossil |
| 413 | f tim d c |
| 414 | |
| 415 | Granted, that’s rather obscure, but you you can also choose something |
| 416 | intermediate like “`f time desc curr`”, which is reasonably clear. |
| 417 | |
| 418 | [35pct]: https://www.sqlite.org/fasterthanfs.html |
| @@ -468,11 +468,11 @@ | |
| 468 | automatically. There is no need for the "-a" option as with Git. |
| 469 | |
| 470 | If you only want to commit _some_ of the changes, list the names |
| 471 | of the files or directories you want to commit as arguments, like this: |
| 472 | |
| 473 | fossil commit src/feature.c doc/feature.md examples/feature |
| 474 | |
| 475 | Note that the last element is a directory name, meaning “any changed |
| 476 | file under the `examples/feature` directory.” |
| 477 | |
| 478 | Although there are currently no |
| @@ -482,12 +482,12 @@ | |
| 482 | running it through [Patchouli]. |
| 483 | |
| 484 | Rather than use `fossil diff -i` to produce such a patch, a safer and |
| 485 | more idiomatic method would be: |
| 486 | |
| 487 | fossil stash save -m 'my big ball-o-hackage' |
| 488 | fossil stash diff > my-changes.patch |
| 489 | |
| 490 | That stores your changes in the stash, then lets you operate on a copy |
| 491 | of that patch. Each time you re-run the second command, it will take the |
| 492 | current state of the working directory into account to produce a |
| 493 | potentially different patch, likely smaller because it leaves out patch |
| @@ -526,30 +526,30 @@ | |
| 526 | ## Create Branches at Point of Need, Rather Than Ahead of Need |
| 527 | |
| 528 | Fossil prefers that you create new branches as part of the first commit |
| 529 | on that branch: |
| 530 | |
| 531 | fossil commit --branch my-branch |
| 532 | |
| 533 | If that commit is successful, your local check-out directory is then |
| 534 | switched to the tip of that branch, so subsequent commits don’t need the |
| 535 | “`--branch`” option. You simply say `fossil commit` again to continue |
| 536 | adding commits to the tip of that branch. |
| 537 | |
| 538 | To switch back to the parent branch, say something like: |
| 539 | |
| 540 | fossil update trunk |
| 541 | |
| 542 | (This is approximately equivalent to `git checkout master`.) |
| 543 | |
| 544 | Fossil does also support the Git style, creating the branch ahead of |
| 545 | need: |
| 546 | |
| 547 | fossil branch new my-branch |
| 548 | fossil up my-branch |
| 549 | ...work on first commit... |
| 550 | fossil commit |
| 551 | |
| 552 | This is more verbose, giving the same overall effect though the initial |
| 553 | actions are inverted: create a new branch for the first commit, switch |
| 554 | the check-out directory to that branch, and make that first commit. As |
| 555 | above, subsequent commits are descendants of that initial branch commit. |
| @@ -558,11 +558,11 @@ | |
| 558 | |
| 559 | Fossil also allows you to move a check-in to a different branch |
| 560 | *after* you commit it, using the "`fossil amend`" command. |
| 561 | For example: |
| 562 | |
| 563 | fossil amend current --branch my-branch |
| 564 | |
| 565 | This works by inserting a tag into the repository that causes the web UI |
| 566 | to relabel commits from that point forward with the new name. Like Git, |
| 567 | Fossil’s fundamental data structure is the interlinked DAG of commit |
| 568 | hashes; branch names are supplemental data for making it easier for the |
| @@ -591,15 +591,15 @@ | |
| 591 | make them under this eventually-consistent design philosophy. |
| 592 | |
| 593 | Branch *names* sync automatically in Fossil, not just the |
| 594 | content of those branches. That means this common Git command: |
| 595 | |
| 596 | git push origin master |
| 597 | |
| 598 | …is simply this in Fossil: |
| 599 | |
| 600 | fossil push |
| 601 | |
| 602 | Fossil doesn’t need to be told what to push or where to push it: it just |
| 603 | keeps using the same remote server URL you gave it last |
| 604 | until you [tell it to do something different][rem]. It pushes all |
| 605 | branches, not just one named local branch. |
| @@ -613,11 +613,11 @@ | |
| 613 | |
| 614 | Fossil’s [autosync][wflow] feature, normally enabled, has no |
| 615 | equivalent in Git. If you want Fossil to behave like Git, you can turn |
| 616 | it off: |
| 617 | |
| 618 | fossil set autosync 0 |
| 619 | |
| 620 | Let’s say that you have a typical server-and-workstations model with two |
| 621 | working clones on different machines, that you have disabled autosync, |
| 622 | and that this common sequence then occurs: |
| 623 | |
| @@ -692,16 +692,16 @@ | |
| 692 | by a colon. The simplified example above is also liable to become |
| 693 | confused by whitespace in file names.) |
| 694 | |
| 695 | |
| 696 | ``` |
| 697 | $ repo=$(fossil status | grep ^repo | cut -f2 -d:) |
| 698 | $ url=$(fossil remote) |
| 699 | $ fossil close # Stop here and think if it warns you! |
| 700 | $ mv $repo ${repo}.old |
| 701 | $ fossil clone $url $repo |
| 702 | $ fossil open --force $repo |
| 703 | ``` |
| 704 | |
| 705 | What, then, should you as a Git transplant do instead when you find |
| 706 | yourself reaching for “`git reset`”? |
| 707 | |
| @@ -717,13 +717,13 @@ | |
| 717 | sort of thing is unnecessary. |
| 718 | |
| 719 | Instead, Bob can say something like this: |
| 720 | |
| 721 | ``` |
| 722 | fossil amend --branch MISTAKE --hide --close -m "mea culpa" tip |
| 723 | fossil up trunk |
| 724 | fossil push |
| 725 | ``` |
| 726 | |
| 727 | Unlike in Git, the “`amend`” command doesn’t modify prior committed |
| 728 | artifacts. Bob’s first command doesn’t delete anything, merely tells |
| 729 | Fossil to hide his mistake from timeline views by inserting a few new |
| @@ -750,14 +750,14 @@ | |
| 750 | marked the branch as closed will prevent that from going thru, cluing |
| 751 | Alice into what she needs to do to remedy the situation, but that merely |
| 752 | shows why it’s a better workflow if Alice makes the amendment herself: |
| 753 | |
| 754 | ``` |
| 755 | fossil amend --branch MISTAKE --hide --close \ |
| 756 | -m "shunt Bob’s erroneous commit off" tip |
| 757 | fossil up trunk |
| 758 | fossil push |
| 759 | ``` |
| 760 | |
| 761 | Then she can fire off an email listing Bob’s assorted failings and go |
| 762 | about her work. This asynchronous workflow solves the problem without |
| 763 | requiring explicit coordination with Bob. When he gets his email, he can |
| @@ -834,18 +834,18 @@ | |
| 834 | Nevertheless, there are multiple ways to get colorized diff output from |
| 835 | Fossil: |
| 836 | |
| 837 | * The most direct method is to delegate diff behavior back to Git: |
| 838 | |
| 839 | fossil set --global diff-command 'git diff --no-index' |
| 840 | |
| 841 | The flag permits it to diff files that aren’t inside a Git repository. |
| 842 | |
| 843 | * Another method is to install [`colordiff`][cdiff] — included in |
| 844 | [many package systems][cdpkg] — then say: |
| 845 | |
| 846 | fossil set --global diff-command 'colordiff -wu' |
| 847 | |
| 848 | Because this is unconditional, unlike `git diff --color=auto`, you |
| 849 | will then have to remember to add the `-i` option to `fossil diff` |
| 850 | commands when you want color disabled, such as when producing |
| 851 | `patch(1)` files or piping diff output to another command that |
| @@ -876,15 +876,15 @@ | |
| 876 | functionality is present in Fossil under other commands: |
| 877 | |
| 878 | |
| 879 | #### <a id="patch"></a> Show a Patch for a Commit |
| 880 | |
| 881 | git show -p COMMIT_ID |
| 882 | |
| 883 | …gives much the same output as |
| 884 | |
| 885 | fossil diff --checkin COMMIT_ID |
| 886 | |
| 887 | …only without the patch email header. Git comes out of the [LKML] world, |
| 888 | where emailing a patch is a normal thing to do. Fossil is [designed for |
| 889 | cohesive teams][devorg] where drive-by patches are rarer. |
| 890 | |
| @@ -893,32 +893,32 @@ | |
| 893 | “`VERSION`” or “`NAME`” where this is allowed, since the version string |
| 894 | or name might not refer to a commit ID, but instead to a forum post, a |
| 895 | wiki document, etc. For instance, the following command answers the question “What did |
| 896 | I just commit?” |
| 897 | |
| 898 | fossil diff --checkin tip |
| 899 | |
| 900 | …or equivalently using a different symbolic commit name: |
| 901 | |
| 902 | fossil diff --from prev |
| 903 | |
| 904 | [devorg]: ./fossil-v-git.wiki#devorg |
| 905 | [LKML]: https://lkml.org/ |
| 906 | |
| 907 | |
| 908 | #### <a id="cmsg"></a> Show a Specific Commit Message |
| 909 | |
| 910 | git show -s COMMIT_ID |
| 911 | |
| 912 | |
| 913 | …is |
| 914 | |
| 915 | fossil time -n 1 COMMIT_ID |
| 916 | |
| 917 | …or with a shorter, more obvious command, though with more verbose output: |
| 918 | |
| 919 | fossil info COMMIT_ID |
| 920 | |
| 921 | The `fossil info` command isn’t otherwise a good equivalent to |
| 922 | `git show`; it just overlaps its functionality in some areas. Much of |
| 923 | what’s missing is present in the corresponding [`/info` web |
| 924 | view][infow], though. |
| @@ -927,17 +927,17 @@ | |
| 927 | #### <a id="dstat"></a> Diff Statistics |
| 928 | |
| 929 | Fossil’s closest internal equivalent to commands like |
| 930 | `git show --stat` is: |
| 931 | |
| 932 | fossil diff -i --from 2020-04-01 --numstat |
| 933 | |
| 934 | The `--numstat` output is a bit cryptic, so we recommend delegating |
| 935 | this task to [the widely-available `diffstat` tool][dst], which gives |
| 936 | a histogram in its default output mode rather than bare integers: |
| 937 | |
| 938 | fossil diff -i -v --from 2020-04-01 | diffstat |
| 939 | |
| 940 | We gave the `-i` flag in both cases to force Fossil to use its internal |
| 941 | diff implementation, bypassing [your local `diff-command` setting][dcset]. |
| 942 | The `--numstat` option has no effect when you have an external diff |
| 943 | command set, and some diff command alternatives like |
| @@ -999,19 +999,19 @@ | |
| 999 | default: they do not actually rename or delete the files in your |
| 1000 | check-out. |
| 1001 | |
| 1002 | If you don’t like that default, you can change it globally: |
| 1003 | |
| 1004 | fossil setting --global mv-rm-files 1 |
| 1005 | |
| 1006 | Now these commands behave like in Git in any Fossil repository where |
| 1007 | this setting hasn’t been overridden locally. |
| 1008 | |
| 1009 | If you want to keep Fossil’s soft `mv/rm` behavior most of the time, you |
| 1010 | can cast it away on a per-command basis: |
| 1011 | |
| 1012 | fossil mv --hard old-name new-name |
| 1013 | |
| 1014 | [mv]: /help?cmd=mv |
| 1015 | [rm]: /help?cmd=rm |
| 1016 | |
| 1017 | |
| @@ -1032,11 +1032,11 @@ | |
| 1032 | |
| 1033 | My search engine’s first result for “git checkout by date” is [this |
| 1034 | highly-upvoted accepted Stack Overflow answer][gcod]. The first command |
| 1035 | it gives is based on Git’s [`rev-parse` feature][grp]: |
| 1036 | |
| 1037 | git checkout master@{2020-03-17} |
| 1038 | |
| 1039 | There are a number of weaknesses in this command. From least to most |
| 1040 | critical: |
| 1041 | |
| 1042 | 1. It’s a bit cryptic. Leave off the refname or punctuation, and it |
| @@ -1072,11 +1072,11 @@ | |
| 1072 | best case. |
| 1073 | |
| 1074 | That same Stack Overflow answer therefore goes on to recommend an |
| 1075 | entirely different command: |
| 1076 | |
| 1077 | git checkout $(git rev-list -n 1 --first-parent --before="2020-03-17" master) |
| 1078 | |
| 1079 | We believe you get such answers to Git help requests in part |
| 1080 | because of its lack of an always-up-to-date [index into its log](#log) and in |
| 1081 | part because of its “small tools loosely joined” design philosophy. This |
| 1082 | sort of command is therefore composed piece by piece: |
| @@ -1084,36 +1084,36 @@ | |
| 1084 | <p style="text-align:center">◆ ◆ ◆</p> |
| 1085 | |
| 1086 | “Oh, I know, I’ll search the rev-list, which outputs commit IDs by |
| 1087 | parsing the log backwards from `HEAD`! Easy!” |
| 1088 | |
| 1089 | git rev-list --before=2020-03-17 |
| 1090 | |
| 1091 | “Blast! Forgot the commit ID!” |
| 1092 | |
| 1093 | git rev-list --before=2020-03-17 master |
| 1094 | |
| 1095 | “Double blast! It just spammed my terminal with revision IDs! I need to |
| 1096 | limit it to the single closest match: |
| 1097 | |
| 1098 | git rev-list -n 1 --before=2020-03-17 master |
| 1099 | |
| 1100 | “Okay, it gives me a single revision ID now, but is it what I’m after? |
| 1101 | Let’s take a look…” |
| 1102 | |
| 1103 | git show $(git rev-list -n 1 --before=2020-03-17 master) |
| 1104 | |
| 1105 | “Oops, that’s giving me a merge commit, not what I want. |
| 1106 | Off to search the web… Okay, it says I need to give either the |
| 1107 | `--first-parent` or `--no-merges` flag to show only regular commits, |
| 1108 | not merge-commits. Let’s try the first one:” |
| 1109 | |
| 1110 | git show $(git rev-list -n 1 --first-parent --before=2020-03-17 master) |
| 1111 | |
| 1112 | “Better. Let’s check it out:” |
| 1113 | |
| 1114 | git checkout $(git rev-list -n 1 --first-parent --before=2020-03-17 master) |
| 1115 | |
| 1116 | “Success, I guess?” |
| 1117 | |
| 1118 | <p style="text-align:center">◆ ◆ ◆</p> |
| 1119 | |
| @@ -1132,11 +1132,11 @@ | |
| 1132 | 17th of March, 2020. |
| 1133 | |
| 1134 | You may be asking with an exasperated huff, “What is your *point*, man?” |
| 1135 | The point is that the equivalent in Fossil is simply: |
| 1136 | |
| 1137 | fossil up 2020-03-17 |
| 1138 | |
| 1139 | …which will *always* give the commit closest to midnight UTC on the 17th |
| 1140 | of March, 2020, no matter whether you do it on a fresh clone or a stale |
| 1141 | one. The answer won’t shift about from one clone to the next or from |
| 1142 | one local time of day to the next. We owe this reliability and stability |
| @@ -1181,13 +1181,13 @@ | |
| 1181 | #### Git Method |
| 1182 | |
| 1183 | We first need to clone the work repo down to our laptop, so we can work on it |
| 1184 | at home: |
| 1185 | |
| 1186 | git clone https://dev-server.example.com/repo |
| 1187 | cd repo |
| 1188 | git remote rename origin work |
| 1189 | |
| 1190 | The last command is optional, strictly speaking. We could continue to |
| 1191 | use Git’s default name for the work repo’s origin — sensibly enough |
| 1192 | called “`origin`” — but it makes later commands harder to understand, so |
| 1193 | we rename it here. This will also make the parallel with Fossil easier |
| @@ -1194,12 +1194,12 @@ | |
| 1194 | to draw. |
| 1195 | |
| 1196 | The first time we go home after this, we have to reverse-clone the work |
| 1197 | repo up to the NAS: |
| 1198 | |
| 1199 | ssh my-nas.local 'git init --bare /SHARES/dayjob/repo.git' |
| 1200 | git push --all ssh://my-nas.local//SHARES/dayjob/repo.git |
| 1201 | |
| 1202 | Realize that this is carefully optimized down to these two long |
| 1203 | commands. In practice, we’d expect a user typing these commands by hand from memory |
| 1204 | to need to give four or more commands here instead. |
| 1205 | Packing the “`git init`” call into the “`ssh`” call is something more |
| @@ -1213,31 +1213,31 @@ | |
| 1213 | |
| 1214 | Having navigated that little minefield, |
| 1215 | we can tell Git that there is a second origin, a “home” repo in |
| 1216 | addition to the named “work” repo we set up earlier: |
| 1217 | |
| 1218 | git remote add home ssh://my-nas.local//SHARES/dayjob/repo.git |
| 1219 | git config master.remote home |
| 1220 | |
| 1221 | We don’t have to push or pull because the remote repo is a complete |
| 1222 | clone of the repo on the laptop at this point, so we can just get to |
| 1223 | work now, committing along the way to get our work safely off-machine |
| 1224 | and onto our home NAS, like so: |
| 1225 | |
| 1226 | git add |
| 1227 | git commit |
| 1228 | git push |
| 1229 | |
| 1230 | We didn’t need to give a remote name on the push because we told it the |
| 1231 | new upstream is the home NAS earlier. |
| 1232 | |
| 1233 | Now Friday comes along, and one of your office-mates needs a feature |
| 1234 | you’re working on. You agree to come into the office later that |
| 1235 | afternoon to sync up via the dev server: |
| 1236 | |
| 1237 | git push work master # send your changes from home up |
| 1238 | git pull work master # get your coworkers’ changes |
| 1239 | |
| 1240 | Alternately, we could add “`--set-upstream/-u work`” to the first |
| 1241 | command if we were coming into work long enough to do several Git-based things, not just pop in and sync. |
| 1242 | That would allow the second to be just “`git pull`”, but the cost is |
| 1243 | that when returning home, you’d have to manually reset the upstream |
| @@ -1254,13 +1254,13 @@ | |
| 1254 | Now we’re going to do the same thing using Fossil, with |
| 1255 | the commands arranged in blocks corresponding to those above for comparison. |
| 1256 | |
| 1257 | We start the same way, cloning the work repo down to the laptop: |
| 1258 | |
| 1259 | fossil clone https://dev-server.example.com/repo |
| 1260 | cd repo |
| 1261 | fossil remote add work https://dev-server.example.com/repo |
| 1262 | |
| 1263 | We’ve chosen the new “`fossil clone URI`” syntax added in Fossil 2.14 rather than separate |
| 1264 | `clone` and `open` commands to make the parallel with Git clearer. [See |
| 1265 | above](#mwd) for more on that topic. |
| 1266 | |
| @@ -1278,11 +1278,11 @@ | |
| 1278 | below. |
| 1279 | |
| 1280 | On first beginning to work from home, we reverse-clone the Fossil repo |
| 1281 | up to the NAS: |
| 1282 | |
| 1283 | rsync repo.fossil my-nas.local:/SHARES/dayjob/ |
| 1284 | |
| 1285 | Now we’re beginning to see the advantage of Fossil’s simpler model, |
| 1286 | relative to the tricky “`git init && git push`” sequence above. |
| 1287 | Fossil’s alternative is almost impossible to get |
| 1288 | wrong: copy this to that. *Done.* |
| @@ -1297,12 +1297,12 @@ | |
| 1297 | inherent in using `rsync` to clone a Git repo][grsync]. |
| 1298 | |
| 1299 | Now we set up the second remote, which is again simpler in the Fossil |
| 1300 | case: |
| 1301 | |
| 1302 | fossil remote add home ssh://my-nas.local//SHARES/dayjob/repo.fossil |
| 1303 | fossil remote home |
| 1304 | |
| 1305 | The first command is nearly identical to the Git version, but the second |
| 1306 | is considerably simpler. And to be fair, you won’t find the |
| 1307 | “`git config`” command above in all Git tutorials. The more common |
| 1308 | alternative we found with web searches is even longer: |
| @@ -1309,21 +1309,21 @@ | |
| 1309 | “`git push --set-upstream home master`”. |
| 1310 | |
| 1311 | Where Fossil really wins is in the next step, making the initial commit |
| 1312 | from home: |
| 1313 | |
| 1314 | fossil ci |
| 1315 | |
| 1316 | It’s one short command for Fossil instead of three for Git — or two if |
| 1317 | you abbreviate it as “`git commit -a && git push`” — because of Fossil’s |
| 1318 | [autosync] feature and deliberate omission of a |
| 1319 | [staging feature](#staging). |
| 1320 | |
| 1321 | The “Friday afternoon sync-up” case is simpler, too: |
| 1322 | |
| 1323 | fossil remote work |
| 1324 | fossil sync |
| 1325 | |
| 1326 | Back at home, it’s simpler still: we may be able to do away with the second command, |
| 1327 | saying just “`fossil remote home`” because the sync will happen as part |
| 1328 | of the next commit, thanks once again to Fossil’s autosync feature. If |
| 1329 | the working branch now has commits from other developers after syncing |
| 1330 |
+2
-2
| --- www/hashpolicy.wiki | ||
| +++ www/hashpolicy.wiki | ||
| @@ -168,13 +168,13 @@ | ||
| 168 | 168 | |
| 169 | 169 | If you are still on Fossil 2.1 through 2.9 but you want Fossil to go |
| 170 | 170 | ahead and start using SHA3 hashes, change the hash policy to |
| 171 | 171 | "sha3" using a command like this: |
| 172 | 172 | |
| 173 | -<blockquote><verbatim> | |
| 173 | +<verbatim> | |
| 174 | 174 | fossil hash-policy sha3 |
| 175 | -</verbatim></blockquote> | |
| 175 | +</verbatim> | |
| 176 | 176 | |
| 177 | 177 | The next check-in will use a SHA3 hash, so that when that check-in is pushed |
| 178 | 178 | to colleagues, their clones will include the new SHA3-named artifact, so |
| 179 | 179 | their local Fossil instances will automatically convert their clones to |
| 180 | 180 | "sha3" mode as well. |
| 181 | 181 |
| --- www/hashpolicy.wiki | |
| +++ www/hashpolicy.wiki | |
| @@ -168,13 +168,13 @@ | |
| 168 | |
| 169 | If you are still on Fossil 2.1 through 2.9 but you want Fossil to go |
| 170 | ahead and start using SHA3 hashes, change the hash policy to |
| 171 | "sha3" using a command like this: |
| 172 | |
| 173 | <blockquote><verbatim> |
| 174 | fossil hash-policy sha3 |
| 175 | </verbatim></blockquote> |
| 176 | |
| 177 | The next check-in will use a SHA3 hash, so that when that check-in is pushed |
| 178 | to colleagues, their clones will include the new SHA3-named artifact, so |
| 179 | their local Fossil instances will automatically convert their clones to |
| 180 | "sha3" mode as well. |
| 181 |
| --- www/hashpolicy.wiki | |
| +++ www/hashpolicy.wiki | |
| @@ -168,13 +168,13 @@ | |
| 168 | |
| 169 | If you are still on Fossil 2.1 through 2.9 but you want Fossil to go |
| 170 | ahead and start using SHA3 hashes, change the hash policy to |
| 171 | "sha3" using a command like this: |
| 172 | |
| 173 | <verbatim> |
| 174 | fossil hash-policy sha3 |
| 175 | </verbatim> |
| 176 | |
| 177 | The next check-in will use a SHA3 hash, so that when that check-in is pushed |
| 178 | to colleagues, their clones will include the new SHA3-named artifact, so |
| 179 | their local Fossil instances will automatically convert their clones to |
| 180 | "sha3" mode as well. |
| 181 |
+29
-29
| --- www/image-format-vs-repo-size.md | ||
| +++ www/image-format-vs-repo-size.md | ||
| @@ -159,39 +159,39 @@ | ||
| 159 | 159 | uncompressed form, we want an automated method for producing the |
| 160 | 160 | uncompressed form to make Fossil happy while still having the compressed |
| 161 | 161 | form to keep our content creation applications happy. This `Makefile` |
| 162 | 162 | should[^makefile] do that for BMP, PNG, SVG, and XLSX files: |
| 163 | 163 | |
| 164 | - .SUFFIXES: .bmp .png .svg .svgz | |
| 165 | - | |
| 166 | - .svgz.svg: | |
| 167 | - gzip -dc < $< > $@ | |
| 168 | - | |
| 169 | - .svg.svgz: | |
| 170 | - gzip -9c < $< > $@ | |
| 171 | - | |
| 172 | - .bmp.png: | |
| 173 | - convert -quality 95 $< $@ | |
| 174 | - | |
| 175 | - .png.bmp: | |
| 176 | - convert $< $@ | |
| 177 | - | |
| 178 | - SS_FILES := $(wildcard spreadsheet/*) | |
| 179 | - | |
| 180 | - | |
| 181 | - all: $(SS_FILES) illus.svg image.bmp doc-big.pdf | |
| 182 | - | |
| 183 | - reconstitute: illus.svgz image.png | |
| 184 | - ( cd spreadsheet ; zip -9 ../spreadsheet.xlsx) * ) | |
| 185 | - qpdf doc-big.pdf doc-small.pdf | |
| 186 | - | |
| 187 | - | |
| 188 | - $(SS_FILES): spreadsheet.xlsx | |
| 189 | - unzip $@ -d $< | |
| 190 | - | |
| 191 | - doc-big.pdf: doc-small.pdf | |
| 192 | - qpdf --stream-data=uncompress $@ $< | |
| 164 | + .SUFFIXES: .bmp .png .svg .svgz | |
| 165 | + | |
| 166 | + .svgz.svg: | |
| 167 | + gzip -dc < $< > $@ | |
| 168 | + | |
| 169 | + .svg.svgz: | |
| 170 | + gzip -9c < $< > $@ | |
| 171 | + | |
| 172 | + .bmp.png: | |
| 173 | + convert -quality 95 $< $@ | |
| 174 | + | |
| 175 | + .png.bmp: | |
| 176 | + convert $< $@ | |
| 177 | + | |
| 178 | + SS_FILES := $(wildcard spreadsheet/*) | |
| 179 | + | |
| 180 | + | |
| 181 | + all: $(SS_FILES) illus.svg image.bmp doc-big.pdf | |
| 182 | + | |
| 183 | + reconstitute: illus.svgz image.png | |
| 184 | + ( cd spreadsheet ; zip -9 ../spreadsheet.xlsx) * ) | |
| 185 | + qpdf doc-big.pdf doc-small.pdf | |
| 186 | + | |
| 187 | + | |
| 188 | + $(SS_FILES): spreadsheet.xlsx | |
| 189 | + unzip $@ -d $< | |
| 190 | + | |
| 191 | + doc-big.pdf: doc-small.pdf | |
| 192 | + qpdf --stream-data=uncompress $@ $< | |
| 193 | 193 | |
| 194 | 194 | This `Makefile` allows you to treat the compressed version as the |
| 195 | 195 | process input, but to actually check in only the changes against the |
| 196 | 196 | uncompressed version by typing “`make`” before “`fossil ci`”. This is |
| 197 | 197 | not actually an extra step in practice, since if you’ve got a |
| 198 | 198 |
| --- www/image-format-vs-repo-size.md | |
| +++ www/image-format-vs-repo-size.md | |
| @@ -159,39 +159,39 @@ | |
| 159 | uncompressed form, we want an automated method for producing the |
| 160 | uncompressed form to make Fossil happy while still having the compressed |
| 161 | form to keep our content creation applications happy. This `Makefile` |
| 162 | should[^makefile] do that for BMP, PNG, SVG, and XLSX files: |
| 163 | |
| 164 | .SUFFIXES: .bmp .png .svg .svgz |
| 165 | |
| 166 | .svgz.svg: |
| 167 | gzip -dc < $< > $@ |
| 168 | |
| 169 | .svg.svgz: |
| 170 | gzip -9c < $< > $@ |
| 171 | |
| 172 | .bmp.png: |
| 173 | convert -quality 95 $< $@ |
| 174 | |
| 175 | .png.bmp: |
| 176 | convert $< $@ |
| 177 | |
| 178 | SS_FILES := $(wildcard spreadsheet/*) |
| 179 | |
| 180 | |
| 181 | all: $(SS_FILES) illus.svg image.bmp doc-big.pdf |
| 182 | |
| 183 | reconstitute: illus.svgz image.png |
| 184 | ( cd spreadsheet ; zip -9 ../spreadsheet.xlsx) * ) |
| 185 | qpdf doc-big.pdf doc-small.pdf |
| 186 | |
| 187 | |
| 188 | $(SS_FILES): spreadsheet.xlsx |
| 189 | unzip $@ -d $< |
| 190 | |
| 191 | doc-big.pdf: doc-small.pdf |
| 192 | qpdf --stream-data=uncompress $@ $< |
| 193 | |
| 194 | This `Makefile` allows you to treat the compressed version as the |
| 195 | process input, but to actually check in only the changes against the |
| 196 | uncompressed version by typing “`make`” before “`fossil ci`”. This is |
| 197 | not actually an extra step in practice, since if you’ve got a |
| 198 |
| --- www/image-format-vs-repo-size.md | |
| +++ www/image-format-vs-repo-size.md | |
| @@ -159,39 +159,39 @@ | |
| 159 | uncompressed form, we want an automated method for producing the |
| 160 | uncompressed form to make Fossil happy while still having the compressed |
| 161 | form to keep our content creation applications happy. This `Makefile` |
| 162 | should[^makefile] do that for BMP, PNG, SVG, and XLSX files: |
| 163 | |
| 164 | .SUFFIXES: .bmp .png .svg .svgz |
| 165 | |
| 166 | .svgz.svg: |
| 167 | gzip -dc < $< > $@ |
| 168 | |
| 169 | .svg.svgz: |
| 170 | gzip -9c < $< > $@ |
| 171 | |
| 172 | .bmp.png: |
| 173 | convert -quality 95 $< $@ |
| 174 | |
| 175 | .png.bmp: |
| 176 | convert $< $@ |
| 177 | |
| 178 | SS_FILES := $(wildcard spreadsheet/*) |
| 179 | |
| 180 | |
| 181 | all: $(SS_FILES) illus.svg image.bmp doc-big.pdf |
| 182 | |
| 183 | reconstitute: illus.svgz image.png |
| 184 | ( cd spreadsheet ; zip -9 ../spreadsheet.xlsx) * ) |
| 185 | qpdf doc-big.pdf doc-small.pdf |
| 186 | |
| 187 | |
| 188 | $(SS_FILES): spreadsheet.xlsx |
| 189 | unzip $@ -d $< |
| 190 | |
| 191 | doc-big.pdf: doc-small.pdf |
| 192 | qpdf --stream-data=uncompress $@ $< |
| 193 | |
| 194 | This `Makefile` allows you to treat the compressed version as the |
| 195 | process input, but to actually check in only the changes against the |
| 196 | uncompressed version by typing “`make`” before “`fossil ci`”. This is |
| 197 | not actually an extra step in practice, since if you’ve got a |
| 198 |
+2
-2
| --- www/index.wiki | ||
| +++ www/index.wiki | ||
| @@ -1,11 +1,11 @@ | ||
| 1 | 1 | <title>Home</title> |
| 2 | 2 | |
| 3 | 3 | <h3>What Is Fossil?</h3> |
| 4 | 4 | |
| 5 | -<div style='float:right;border:2px solid #446979;padding:0 15px 10px 0;margin:0 0 10px 10px;'> | |
| 6 | -<ul style='margin-left: -10px;'> | |
| 5 | +<div class="nomargins" style='float:right;border:2px solid #446979;padding:0 15px 10px 0;margin:0 50px 0 10px'> | |
| 6 | +<ul> | |
| 7 | 7 | <li> [/uv/download.html | Download] |
| 8 | 8 | <li> [./quickstart.wiki | Quick Start] |
| 9 | 9 | <li> [./build.wiki | Install] |
| 10 | 10 | <li> [https://fossil-scm.org/forum | Support/Forum ] |
| 11 | 11 | <li> [./hints.wiki | Tips & Hints] |
| 12 | 12 |
| --- www/index.wiki | |
| +++ www/index.wiki | |
| @@ -1,11 +1,11 @@ | |
| 1 | <title>Home</title> |
| 2 | |
| 3 | <h3>What Is Fossil?</h3> |
| 4 | |
| 5 | <div style='float:right;border:2px solid #446979;padding:0 15px 10px 0;margin:0 0 10px 10px;'> |
| 6 | <ul style='margin-left: -10px;'> |
| 7 | <li> [/uv/download.html | Download] |
| 8 | <li> [./quickstart.wiki | Quick Start] |
| 9 | <li> [./build.wiki | Install] |
| 10 | <li> [https://fossil-scm.org/forum | Support/Forum ] |
| 11 | <li> [./hints.wiki | Tips & Hints] |
| 12 |
| --- www/index.wiki | |
| +++ www/index.wiki | |
| @@ -1,11 +1,11 @@ | |
| 1 | <title>Home</title> |
| 2 | |
| 3 | <h3>What Is Fossil?</h3> |
| 4 | |
| 5 | <div class="nomargins" style='float:right;border:2px solid #446979;padding:0 15px 10px 0;margin:0 50px 0 10px'> |
| 6 | <ul> |
| 7 | <li> [/uv/download.html | Download] |
| 8 | <li> [./quickstart.wiki | Quick Start] |
| 9 | <li> [./build.wiki | Install] |
| 10 | <li> [https://fossil-scm.org/forum | Support/Forum ] |
| 11 | <li> [./hints.wiki | Tips & Hints] |
| 12 |
+10
-10
| --- www/inout.wiki | ||
| +++ www/inout.wiki | ||
| @@ -8,14 +8,14 @@ | ||
| 8 | 8 | |
| 9 | 9 | <h2>Git → Fossil</h2> |
| 10 | 10 | |
| 11 | 11 | To import a Git repository into Fossil, say something like: |
| 12 | 12 | |
| 13 | -<blockquote><pre> | |
| 13 | +<pre> | |
| 14 | 14 | cd git-repo |
| 15 | 15 | git fast-export --all | fossil import --git new-repo.fossil |
| 16 | -</pre></blockquote> | |
| 16 | +</pre> | |
| 17 | 17 | |
| 18 | 18 | The 3rd argument to the "fossil import" |
| 19 | 19 | command is the name of a new Fossil repository that is created to hold the Git |
| 20 | 20 | content. |
| 21 | 21 | |
| @@ -58,15 +58,15 @@ | ||
| 58 | 58 | <h2>Fossil → Git</h2> |
| 59 | 59 | |
| 60 | 60 | To convert a Fossil repository into a Git repository, run commands like |
| 61 | 61 | this: |
| 62 | 62 | |
| 63 | -<blockquote><pre> | |
| 63 | +<pre> | |
| 64 | 64 | git init new-repo |
| 65 | 65 | cd new-repo |
| 66 | 66 | fossil export --git ../repo.fossil | git fast-import |
| 67 | -</pre></blockquote> | |
| 67 | +</pre> | |
| 68 | 68 | |
| 69 | 69 | In other words, create a new Git repository, then pipe the output from the |
| 70 | 70 | "fossil export --git" command into the "git fast-import" command. |
| 71 | 71 | |
| 72 | 72 | Note that the "fossil export --git" command only exports the versioned files. |
| @@ -97,11 +97,11 @@ | ||
| 97 | 97 | |
| 98 | 98 | To illustrate, consider the example of a remote Fossil repository that a |
| 99 | 99 | user wants to import into a local Git repository. First, the user would clone |
| 100 | 100 | the remote repository and import it into a new Git repository: |
| 101 | 101 | |
| 102 | -<blockquote><pre> | |
| 102 | +<pre> | |
| 103 | 103 | fossil clone /path/to/remote/repo.fossil repo.fossil |
| 104 | 104 | mkdir repo |
| 105 | 105 | cd repo |
| 106 | 106 | fossil open ../repo.fossil |
| 107 | 107 | mkdir ../repo.git |
| @@ -108,33 +108,33 @@ | ||
| 108 | 108 | cd ../repo.git |
| 109 | 109 | git init . |
| 110 | 110 | fossil export --git --export-marks ../repo/fossil.marks \ |
| 111 | 111 | ../repo.fossil | git fast-import \ |
| 112 | 112 | --export-marks=../repo/git.marks |
| 113 | -</pre></blockquote> | |
| 113 | +</pre> | |
| 114 | 114 | |
| 115 | 115 | Once the import has completed, the user would need to <tt>git checkout |
| 116 | 116 | trunk</tt>. At any point after this, new changes can be imported from the |
| 117 | 117 | remote Fossil repository: |
| 118 | 118 | |
| 119 | -<blockquote><pre> | |
| 119 | +<pre> | |
| 120 | 120 | cd ../repo |
| 121 | 121 | fossil pull |
| 122 | 122 | cd ../repo.git |
| 123 | 123 | fossil export --git --import-marks ../repo/fossil.marks \ |
| 124 | 124 | --export-marks ../repo/fossil.marks \ |
| 125 | 125 | ../repo.fossil | git fast-import \ |
| 126 | 126 | --import-marks=../repo/git.marks \ |
| 127 | 127 | --export-marks=../repo/git.marks |
| 128 | -</pre></blockquote> | |
| 128 | +</pre> | |
| 129 | 129 | |
| 130 | 130 | Changes in the Git repository can be exported to the Fossil repository and then |
| 131 | 131 | pushed to the remote: |
| 132 | 132 | |
| 133 | -<blockquote><pre> | |
| 133 | +<pre> | |
| 134 | 134 | git fast-export --import-marks=../repo/git.marks \ |
| 135 | 135 | --export-marks=../repo/git.marks --all | fossil import --git \ |
| 136 | 136 | --incremental --import-marks ../repo/fossil.marks \ |
| 137 | 137 | --export-marks ../repo/fossil.marks ../repo.fossil |
| 138 | 138 | cd ../repo |
| 139 | 139 | fossil push |
| 140 | -</pre></blockquote> | |
| 140 | +</pre> | |
| 141 | 141 |
| --- www/inout.wiki | |
| +++ www/inout.wiki | |
| @@ -8,14 +8,14 @@ | |
| 8 | |
| 9 | <h2>Git → Fossil</h2> |
| 10 | |
| 11 | To import a Git repository into Fossil, say something like: |
| 12 | |
| 13 | <blockquote><pre> |
| 14 | cd git-repo |
| 15 | git fast-export --all | fossil import --git new-repo.fossil |
| 16 | </pre></blockquote> |
| 17 | |
| 18 | The 3rd argument to the "fossil import" |
| 19 | command is the name of a new Fossil repository that is created to hold the Git |
| 20 | content. |
| 21 | |
| @@ -58,15 +58,15 @@ | |
| 58 | <h2>Fossil → Git</h2> |
| 59 | |
| 60 | To convert a Fossil repository into a Git repository, run commands like |
| 61 | this: |
| 62 | |
| 63 | <blockquote><pre> |
| 64 | git init new-repo |
| 65 | cd new-repo |
| 66 | fossil export --git ../repo.fossil | git fast-import |
| 67 | </pre></blockquote> |
| 68 | |
| 69 | In other words, create a new Git repository, then pipe the output from the |
| 70 | "fossil export --git" command into the "git fast-import" command. |
| 71 | |
| 72 | Note that the "fossil export --git" command only exports the versioned files. |
| @@ -97,11 +97,11 @@ | |
| 97 | |
| 98 | To illustrate, consider the example of a remote Fossil repository that a |
| 99 | user wants to import into a local Git repository. First, the user would clone |
| 100 | the remote repository and import it into a new Git repository: |
| 101 | |
| 102 | <blockquote><pre> |
| 103 | fossil clone /path/to/remote/repo.fossil repo.fossil |
| 104 | mkdir repo |
| 105 | cd repo |
| 106 | fossil open ../repo.fossil |
| 107 | mkdir ../repo.git |
| @@ -108,33 +108,33 @@ | |
| 108 | cd ../repo.git |
| 109 | git init . |
| 110 | fossil export --git --export-marks ../repo/fossil.marks \ |
| 111 | ../repo.fossil | git fast-import \ |
| 112 | --export-marks=../repo/git.marks |
| 113 | </pre></blockquote> |
| 114 | |
| 115 | Once the import has completed, the user would need to <tt>git checkout |
| 116 | trunk</tt>. At any point after this, new changes can be imported from the |
| 117 | remote Fossil repository: |
| 118 | |
| 119 | <blockquote><pre> |
| 120 | cd ../repo |
| 121 | fossil pull |
| 122 | cd ../repo.git |
| 123 | fossil export --git --import-marks ../repo/fossil.marks \ |
| 124 | --export-marks ../repo/fossil.marks \ |
| 125 | ../repo.fossil | git fast-import \ |
| 126 | --import-marks=../repo/git.marks \ |
| 127 | --export-marks=../repo/git.marks |
| 128 | </pre></blockquote> |
| 129 | |
| 130 | Changes in the Git repository can be exported to the Fossil repository and then |
| 131 | pushed to the remote: |
| 132 | |
| 133 | <blockquote><pre> |
| 134 | git fast-export --import-marks=../repo/git.marks \ |
| 135 | --export-marks=../repo/git.marks --all | fossil import --git \ |
| 136 | --incremental --import-marks ../repo/fossil.marks \ |
| 137 | --export-marks ../repo/fossil.marks ../repo.fossil |
| 138 | cd ../repo |
| 139 | fossil push |
| 140 | </pre></blockquote> |
| 141 |
| --- www/inout.wiki | |
| +++ www/inout.wiki | |
| @@ -8,14 +8,14 @@ | |
| 8 | |
| 9 | <h2>Git → Fossil</h2> |
| 10 | |
| 11 | To import a Git repository into Fossil, say something like: |
| 12 | |
| 13 | <pre> |
| 14 | cd git-repo |
| 15 | git fast-export --all | fossil import --git new-repo.fossil |
| 16 | </pre> |
| 17 | |
| 18 | The 3rd argument to the "fossil import" |
| 19 | command is the name of a new Fossil repository that is created to hold the Git |
| 20 | content. |
| 21 | |
| @@ -58,15 +58,15 @@ | |
| 58 | <h2>Fossil → Git</h2> |
| 59 | |
| 60 | To convert a Fossil repository into a Git repository, run commands like |
| 61 | this: |
| 62 | |
| 63 | <pre> |
| 64 | git init new-repo |
| 65 | cd new-repo |
| 66 | fossil export --git ../repo.fossil | git fast-import |
| 67 | </pre> |
| 68 | |
| 69 | In other words, create a new Git repository, then pipe the output from the |
| 70 | "fossil export --git" command into the "git fast-import" command. |
| 71 | |
| 72 | Note that the "fossil export --git" command only exports the versioned files. |
| @@ -97,11 +97,11 @@ | |
| 97 | |
| 98 | To illustrate, consider the example of a remote Fossil repository that a |
| 99 | user wants to import into a local Git repository. First, the user would clone |
| 100 | the remote repository and import it into a new Git repository: |
| 101 | |
| 102 | <pre> |
| 103 | fossil clone /path/to/remote/repo.fossil repo.fossil |
| 104 | mkdir repo |
| 105 | cd repo |
| 106 | fossil open ../repo.fossil |
| 107 | mkdir ../repo.git |
| @@ -108,33 +108,33 @@ | |
| 108 | cd ../repo.git |
| 109 | git init . |
| 110 | fossil export --git --export-marks ../repo/fossil.marks \ |
| 111 | ../repo.fossil | git fast-import \ |
| 112 | --export-marks=../repo/git.marks |
| 113 | </pre> |
| 114 | |
| 115 | Once the import has completed, the user would need to <tt>git checkout |
| 116 | trunk</tt>. At any point after this, new changes can be imported from the |
| 117 | remote Fossil repository: |
| 118 | |
| 119 | <pre> |
| 120 | cd ../repo |
| 121 | fossil pull |
| 122 | cd ../repo.git |
| 123 | fossil export --git --import-marks ../repo/fossil.marks \ |
| 124 | --export-marks ../repo/fossil.marks \ |
| 125 | ../repo.fossil | git fast-import \ |
| 126 | --import-marks=../repo/git.marks \ |
| 127 | --export-marks=../repo/git.marks |
| 128 | </pre> |
| 129 | |
| 130 | Changes in the Git repository can be exported to the Fossil repository and then |
| 131 | pushed to the remote: |
| 132 | |
| 133 | <pre> |
| 134 | git fast-export --import-marks=../repo/git.marks \ |
| 135 | --export-marks=../repo/git.marks --all | fossil import --git \ |
| 136 | --incremental --import-marks ../repo/fossil.marks \ |
| 137 | --export-marks ../repo/fossil.marks ../repo.fossil |
| 138 | cd ../repo |
| 139 | fossil push |
| 140 | </pre> |
| 141 |
+15
-15
| --- www/javascript.md | ||
| +++ www/javascript.md | ||
| @@ -371,24 +371,24 @@ | ||
| 371 | 371 | maintain your repository’s wiki at all. Fossil’s [`wiki` command][fwc] |
| 372 | 372 | lets you manipulate wiki documents from the command line. For example, |
| 373 | 373 | consider this Vi based workflow: |
| 374 | 374 | |
| 375 | 375 | ```shell |
| 376 | - $ vi 'My Article.wiki' # begin work on new article | |
| 377 | - ...write, write, write... | |
| 378 | - :w # save changes to disk copy | |
| 379 | - :!fossil wiki create 'My Article' '%' # current file (%) to new article | |
| 380 | - ...write, write, write some more... | |
| 381 | - :w # save again | |
| 382 | - :!fossil wiki commit 'My Article' '%' # update article from disk | |
| 383 | - :q # done writing for today | |
| 384 | - | |
| 385 | - ....days later... | |
| 386 | - $ vi # work sans named file today | |
| 387 | - :r !fossil wiki export 'My Article' - # pull article text into vi buffer | |
| 388 | - ...write, write, write yet more... | |
| 389 | - :w !fossil wiki commit - # vi buffer updates article | |
| 376 | +$ vi 'My Article.wiki' # begin work on new article | |
| 377 | + ...write, write, write... | |
| 378 | +:w # save changes to disk copy | |
| 379 | +:!fossil wiki create 'My Article' '%' # current file (%) to new article | |
| 380 | + ...write, write, write some more... | |
| 381 | +:w # save again | |
| 382 | +:!fossil wiki commit 'My Article' '%' # update article from disk | |
| 383 | +:q # done writing for today | |
| 384 | + | |
| 385 | + ....days later... | |
| 386 | +$ vi # work sans named file today | |
| 387 | +:r !fossil wiki export 'My Article' - # pull article text into vi buffer | |
| 388 | + ...write, write, write yet more... | |
| 389 | +:w !fossil wiki commit - # vi buffer updates article | |
| 390 | 390 | ``` |
| 391 | 391 | |
| 392 | 392 | Extending this concept to other text editors is an exercise left to the |
| 393 | 393 | reader. |
| 394 | 394 | |
| @@ -576,11 +576,11 @@ | ||
| 576 | 576 | sufficiently motivated to build a Fossil chat gateway, connecting to |
| 577 | 577 | IRC, Jabber, etc. The messages are stored in the repository’s `chat` |
| 578 | 578 | table with monotonically increasing IDs, so a poller that did something |
| 579 | 579 | like |
| 580 | 580 | |
| 581 | - SELECT xfrom, xmsg FROM chat WHERE msgid > 1234; | |
| 581 | + SELECT xfrom, xmsg FROM chat WHERE msgid > 1234; | |
| 582 | 582 | |
| 583 | 583 | …would pull the messages submitted since the last poll. Making the |
| 584 | 584 | gateway bidirectional should be possible as well, as long as it properly |
| 585 | 585 | uses SQLite transactions. |
| 586 | 586 | |
| 587 | 587 |
| --- www/javascript.md | |
| +++ www/javascript.md | |
| @@ -371,24 +371,24 @@ | |
| 371 | maintain your repository’s wiki at all. Fossil’s [`wiki` command][fwc] |
| 372 | lets you manipulate wiki documents from the command line. For example, |
| 373 | consider this Vi based workflow: |
| 374 | |
| 375 | ```shell |
| 376 | $ vi 'My Article.wiki' # begin work on new article |
| 377 | ...write, write, write... |
| 378 | :w # save changes to disk copy |
| 379 | :!fossil wiki create 'My Article' '%' # current file (%) to new article |
| 380 | ...write, write, write some more... |
| 381 | :w # save again |
| 382 | :!fossil wiki commit 'My Article' '%' # update article from disk |
| 383 | :q # done writing for today |
| 384 | |
| 385 | ....days later... |
| 386 | $ vi # work sans named file today |
| 387 | :r !fossil wiki export 'My Article' - # pull article text into vi buffer |
| 388 | ...write, write, write yet more... |
| 389 | :w !fossil wiki commit - # vi buffer updates article |
| 390 | ``` |
| 391 | |
| 392 | Extending this concept to other text editors is an exercise left to the |
| 393 | reader. |
| 394 | |
| @@ -576,11 +576,11 @@ | |
| 576 | sufficiently motivated to build a Fossil chat gateway, connecting to |
| 577 | IRC, Jabber, etc. The messages are stored in the repository’s `chat` |
| 578 | table with monotonically increasing IDs, so a poller that did something |
| 579 | like |
| 580 | |
| 581 | SELECT xfrom, xmsg FROM chat WHERE msgid > 1234; |
| 582 | |
| 583 | …would pull the messages submitted since the last poll. Making the |
| 584 | gateway bidirectional should be possible as well, as long as it properly |
| 585 | uses SQLite transactions. |
| 586 | |
| 587 |
| --- www/javascript.md | |
| +++ www/javascript.md | |
| @@ -371,24 +371,24 @@ | |
| 371 | maintain your repository’s wiki at all. Fossil’s [`wiki` command][fwc] |
| 372 | lets you manipulate wiki documents from the command line. For example, |
| 373 | consider this Vi based workflow: |
| 374 | |
| 375 | ```shell |
| 376 | $ vi 'My Article.wiki' # begin work on new article |
| 377 | ...write, write, write... |
| 378 | :w # save changes to disk copy |
| 379 | :!fossil wiki create 'My Article' '%' # current file (%) to new article |
| 380 | ...write, write, write some more... |
| 381 | :w # save again |
| 382 | :!fossil wiki commit 'My Article' '%' # update article from disk |
| 383 | :q # done writing for today |
| 384 | |
| 385 | ....days later... |
| 386 | $ vi # work sans named file today |
| 387 | :r !fossil wiki export 'My Article' - # pull article text into vi buffer |
| 388 | ...write, write, write yet more... |
| 389 | :w !fossil wiki commit - # vi buffer updates article |
| 390 | ``` |
| 391 | |
| 392 | Extending this concept to other text editors is an exercise left to the |
| 393 | reader. |
| 394 | |
| @@ -576,11 +576,11 @@ | |
| 576 | sufficiently motivated to build a Fossil chat gateway, connecting to |
| 577 | IRC, Jabber, etc. The messages are stored in the repository’s `chat` |
| 578 | table with monotonically increasing IDs, so a poller that did something |
| 579 | like |
| 580 | |
| 581 | SELECT xfrom, xmsg FROM chat WHERE msgid > 1234; |
| 582 | |
| 583 | …would pull the messages submitted since the last poll. Making the |
| 584 | gateway bidirectional should be possible as well, as long as it properly |
| 585 | uses SQLite transactions. |
| 586 | |
| 587 |
+3
-3
| --- www/loadmgmt.md | ||
| +++ www/loadmgmt.md | ||
| @@ -52,12 +52,12 @@ | ||
| 52 | 52 | easily set it higher on a multi-core server. |
| 53 | 53 | |
| 54 | 54 | The maximum load average can also be set on the command line using |
| 55 | 55 | commands like this: |
| 56 | 56 | |
| 57 | - fossil set max-loadavg 1.5 | |
| 58 | - fossil all set max-loadavg 1.5 | |
| 57 | + fossil set max-loadavg 1.5 | |
| 58 | + fossil all set max-loadavg 1.5 | |
| 59 | 59 | |
| 60 | 60 | The second form is especially useful for changing the maximum load |
| 61 | 61 | average simultaneously on a large number of repositories. |
| 62 | 62 | |
| 63 | 63 | Note that this load-average limiting feature is only available on |
| @@ -71,11 +71,11 @@ | ||
| 71 | 71 | you are running a Fossil instance [inside a `chroot(2)` |
| 72 | 72 | jail](./chroot.md) and you have not mounted the `/proc` virtual file |
| 73 | 73 | system inside that jail. On the [self-hosting Fossil repositories][sh], |
| 74 | 74 | this was accomplished by adding a line to the `/etc/fstab` file: |
| 75 | 75 | |
| 76 | - chroot_jail_proc /home/www/proc proc ro 0 0 | |
| 76 | + chroot_jail_proc /home/www/proc proc ro 0 0 | |
| 77 | 77 | |
| 78 | 78 | The `/home/www/proc` pathname should be adjusted so that the `/proc` |
| 79 | 79 | component is at the root of the chroot jail, of course. |
| 80 | 80 | |
| 81 | 81 | To see if the load-average limiter is functional, visit the |
| 82 | 82 |
| --- www/loadmgmt.md | |
| +++ www/loadmgmt.md | |
| @@ -52,12 +52,12 @@ | |
| 52 | easily set it higher on a multi-core server. |
| 53 | |
| 54 | The maximum load average can also be set on the command line using |
| 55 | commands like this: |
| 56 | |
| 57 | fossil set max-loadavg 1.5 |
| 58 | fossil all set max-loadavg 1.5 |
| 59 | |
| 60 | The second form is especially useful for changing the maximum load |
| 61 | average simultaneously on a large number of repositories. |
| 62 | |
| 63 | Note that this load-average limiting feature is only available on |
| @@ -71,11 +71,11 @@ | |
| 71 | you are running a Fossil instance [inside a `chroot(2)` |
| 72 | jail](./chroot.md) and you have not mounted the `/proc` virtual file |
| 73 | system inside that jail. On the [self-hosting Fossil repositories][sh], |
| 74 | this was accomplished by adding a line to the `/etc/fstab` file: |
| 75 | |
| 76 | chroot_jail_proc /home/www/proc proc ro 0 0 |
| 77 | |
| 78 | The `/home/www/proc` pathname should be adjusted so that the `/proc` |
| 79 | component is at the root of the chroot jail, of course. |
| 80 | |
| 81 | To see if the load-average limiter is functional, visit the |
| 82 |
| --- www/loadmgmt.md | |
| +++ www/loadmgmt.md | |
| @@ -52,12 +52,12 @@ | |
| 52 | easily set it higher on a multi-core server. |
| 53 | |
| 54 | The maximum load average can also be set on the command line using |
| 55 | commands like this: |
| 56 | |
| 57 | fossil set max-loadavg 1.5 |
| 58 | fossil all set max-loadavg 1.5 |
| 59 | |
| 60 | The second form is especially useful for changing the maximum load |
| 61 | average simultaneously on a large number of repositories. |
| 62 | |
| 63 | Note that this load-average limiting feature is only available on |
| @@ -71,11 +71,11 @@ | |
| 71 | you are running a Fossil instance [inside a `chroot(2)` |
| 72 | jail](./chroot.md) and you have not mounted the `/proc` virtual file |
| 73 | system inside that jail. On the [self-hosting Fossil repositories][sh], |
| 74 | this was accomplished by adding a line to the `/etc/fstab` file: |
| 75 | |
| 76 | chroot_jail_proc /home/www/proc proc ro 0 0 |
| 77 | |
| 78 | The `/home/www/proc` pathname should be adjusted so that the `/proc` |
| 79 | component is at the root of the chroot jail, of course. |
| 80 | |
| 81 | To see if the load-average limiter is functional, visit the |
| 82 |
+14
-14
| --- www/makefile.wiki | ||
| +++ www/makefile.wiki | ||
| @@ -146,13 +146,13 @@ | ||
| 146 | 146 | a C program: tools/mkversion.c. |
| 147 | 147 | To run the VERSION.h generator, first compile the tools/mkversion.c |
| 148 | 148 | source file into a command-line program (named "mkversion.exe") |
| 149 | 149 | then run: |
| 150 | 150 | |
| 151 | -<blockquote><pre> | |
| 151 | +<pre> | |
| 152 | 152 | mkversion.exe manifest.uuid manifest VERSION >VERSION.h |
| 153 | -</pre></blockquote> | |
| 153 | +</pre> | |
| 154 | 154 | |
| 155 | 155 | The pathnames in the above command might need to be adjusted to get the |
| 156 | 156 | directories right. The point is that the manifest.uuid, manifest, and |
| 157 | 157 | VERSION files |
| 158 | 158 | in the root of the source tree are the three arguments and |
| @@ -161,13 +161,13 @@ | ||
| 161 | 161 | The builtin_data.h header file is generated by a C program: tools/mkbuiltin.c. |
| 162 | 162 | The builtin_data.h file contains C-language byte-array definitions for |
| 163 | 163 | the content of resource files used by Fossil. To generate the |
| 164 | 164 | builtin_data.h file, first compile the mkbuiltin.c program, then run: |
| 165 | 165 | |
| 166 | -<blockquote><pre> | |
| 166 | +<pre> | |
| 167 | 167 | mkbuiltin.exe diff.tcl <i>OtherFiles...</i> >builtin_data.h |
| 168 | -</pre></blockquote> | |
| 168 | +</pre> | |
| 169 | 169 | |
| 170 | 170 | At the time of this writing, the "diff.tcl" script (a Tcl/Tk script used |
| 171 | 171 | to generate implement --tk option on the diff command) is the only resource |
| 172 | 172 | file processed using mkbuiltin.exe. However, new resources will likely be |
| 173 | 173 | added using this facility in future versions of Fossil. |
| @@ -185,13 +185,13 @@ | ||
| 185 | 185 | web interface methods, and help text comments. The mkindex program |
| 186 | 186 | generates some C code that Fossil uses in order to dispatch commands and |
| 187 | 187 | HTTP requests and to show on-line help. Compile the mkindex program |
| 188 | 188 | from the mkindex.c source file. Then run: |
| 189 | 189 | |
| 190 | -<blockquote><pre> | |
| 190 | +<pre> | |
| 191 | 191 | ./mkindex src.c >page_index.h |
| 192 | -</pre></blockquote> | |
| 192 | +</pre> | |
| 193 | 193 | |
| 194 | 194 | Note that "src.c" in the above is a stand-in for the (79) regular source |
| 195 | 195 | files of Fossil - all source files except for the exceptions described in |
| 196 | 196 | section 2.0 above. |
| 197 | 197 | |
| @@ -205,13 +205,13 @@ | ||
| 205 | 205 | context) into special "printf" operations for generating the output of |
| 206 | 206 | an HTTP request. The translate preprocessor is a simple C program whose |
| 207 | 207 | sources are in the translate.c source file. The translate preprocess |
| 208 | 208 | is run on each of the other ordinary source files separately, like this: |
| 209 | 209 | |
| 210 | -<blockquote><pre> | |
| 210 | +<pre> | |
| 211 | 211 | ./translate src.c >src_.c |
| 212 | -</pre></blockquote> | |
| 212 | +</pre> | |
| 213 | 213 | |
| 214 | 214 | In this case, the "src.c" file represents any single source file from the |
| 215 | 215 | set of ordinary source files as described in section 2.0 above. Note that |
| 216 | 216 | each source file is translated separately. By convention, the names of |
| 217 | 217 | the translated source files are the names of the input sources with a |
| @@ -235,13 +235,13 @@ | ||
| 235 | 235 | source files are not scanned by makeheaders. Makeheaders only runs over |
| 236 | 236 | "ordinary" source files, not the exceptional source files. However, |
| 237 | 237 | makeheaders also uses some extra header files as input. The general format |
| 238 | 238 | is like this: |
| 239 | 239 | |
| 240 | -<blockquote><pre> | |
| 240 | +<pre> | |
| 241 | 241 | makeheaders src_.c:src.h sqlite3.h th.h VERSION.h |
| 242 | -</pre></blockquote> | |
| 242 | +</pre> | |
| 243 | 243 | |
| 244 | 244 | In the example above the "src_.c" and "src.h" names represent all of the |
| 245 | 245 | (79) ordinary C source files, each as a separate argument. |
| 246 | 246 | |
| 247 | 247 | <h1>5.0 Compilation</h1> |
| @@ -304,18 +304,18 @@ | ||
| 304 | 304 | Debug flags are consistently applied across the whole build process. For |
| 305 | 305 | example, use these Debug flags in addition to other flags passed to the |
| 306 | 306 | configure scripts: |
| 307 | 307 | |
| 308 | 308 | On Linux, *NIX and similar platforms: |
| 309 | -<blockquote><pre> | |
| 309 | +<pre> | |
| 310 | 310 | ./configure --fossil-debug |
| 311 | -</pre></blockquote> | |
| 311 | +</pre> | |
| 312 | 312 | |
| 313 | 313 | On Windows: |
| 314 | -<blockquote><pre> | |
| 314 | +<pre> | |
| 315 | 315 | win\buildmsvc.bat FOSSIL_DEBUG=1 |
| 316 | -</pre></blockquote> | |
| 316 | +</pre> | |
| 317 | 317 | |
| 318 | 318 | The resulting fossil binary could then be loaded into a platform-specific |
| 319 | 319 | debugger. Source files displayed in the debugger correspond to the ones |
| 320 | 320 | generated from the translation stage of the build process, that is what was |
| 321 | 321 | actually compiled into the object files. |
| 322 | 322 |
| --- www/makefile.wiki | |
| +++ www/makefile.wiki | |
| @@ -146,13 +146,13 @@ | |
| 146 | a C program: tools/mkversion.c. |
| 147 | To run the VERSION.h generator, first compile the tools/mkversion.c |
| 148 | source file into a command-line program (named "mkversion.exe") |
| 149 | then run: |
| 150 | |
| 151 | <blockquote><pre> |
| 152 | mkversion.exe manifest.uuid manifest VERSION >VERSION.h |
| 153 | </pre></blockquote> |
| 154 | |
| 155 | The pathnames in the above command might need to be adjusted to get the |
| 156 | directories right. The point is that the manifest.uuid, manifest, and |
| 157 | VERSION files |
| 158 | in the root of the source tree are the three arguments and |
| @@ -161,13 +161,13 @@ | |
| 161 | The builtin_data.h header file is generated by a C program: tools/mkbuiltin.c. |
| 162 | The builtin_data.h file contains C-language byte-array definitions for |
| 163 | the content of resource files used by Fossil. To generate the |
| 164 | builtin_data.h file, first compile the mkbuiltin.c program, then run: |
| 165 | |
| 166 | <blockquote><pre> |
| 167 | mkbuiltin.exe diff.tcl <i>OtherFiles...</i> >builtin_data.h |
| 168 | </pre></blockquote> |
| 169 | |
| 170 | At the time of this writing, the "diff.tcl" script (a Tcl/Tk script used |
| 171 | to generate implement --tk option on the diff command) is the only resource |
| 172 | file processed using mkbuiltin.exe. However, new resources will likely be |
| 173 | added using this facility in future versions of Fossil. |
| @@ -185,13 +185,13 @@ | |
| 185 | web interface methods, and help text comments. The mkindex program |
| 186 | generates some C code that Fossil uses in order to dispatch commands and |
| 187 | HTTP requests and to show on-line help. Compile the mkindex program |
| 188 | from the mkindex.c source file. Then run: |
| 189 | |
| 190 | <blockquote><pre> |
| 191 | ./mkindex src.c >page_index.h |
| 192 | </pre></blockquote> |
| 193 | |
| 194 | Note that "src.c" in the above is a stand-in for the (79) regular source |
| 195 | files of Fossil - all source files except for the exceptions described in |
| 196 | section 2.0 above. |
| 197 | |
| @@ -205,13 +205,13 @@ | |
| 205 | context) into special "printf" operations for generating the output of |
| 206 | an HTTP request. The translate preprocessor is a simple C program whose |
| 207 | sources are in the translate.c source file. The translate preprocess |
| 208 | is run on each of the other ordinary source files separately, like this: |
| 209 | |
| 210 | <blockquote><pre> |
| 211 | ./translate src.c >src_.c |
| 212 | </pre></blockquote> |
| 213 | |
| 214 | In this case, the "src.c" file represents any single source file from the |
| 215 | set of ordinary source files as described in section 2.0 above. Note that |
| 216 | each source file is translated separately. By convention, the names of |
| 217 | the translated source files are the names of the input sources with a |
| @@ -235,13 +235,13 @@ | |
| 235 | source files are not scanned by makeheaders. Makeheaders only runs over |
| 236 | "ordinary" source files, not the exceptional source files. However, |
| 237 | makeheaders also uses some extra header files as input. The general format |
| 238 | is like this: |
| 239 | |
| 240 | <blockquote><pre> |
| 241 | makeheaders src_.c:src.h sqlite3.h th.h VERSION.h |
| 242 | </pre></blockquote> |
| 243 | |
| 244 | In the example above the "src_.c" and "src.h" names represent all of the |
| 245 | (79) ordinary C source files, each as a separate argument. |
| 246 | |
| 247 | <h1>5.0 Compilation</h1> |
| @@ -304,18 +304,18 @@ | |
| 304 | Debug flags are consistently applied across the whole build process. For |
| 305 | example, use these Debug flags in addition to other flags passed to the |
| 306 | configure scripts: |
| 307 | |
| 308 | On Linux, *NIX and similar platforms: |
| 309 | <blockquote><pre> |
| 310 | ./configure --fossil-debug |
| 311 | </pre></blockquote> |
| 312 | |
| 313 | On Windows: |
| 314 | <blockquote><pre> |
| 315 | win\buildmsvc.bat FOSSIL_DEBUG=1 |
| 316 | </pre></blockquote> |
| 317 | |
| 318 | The resulting fossil binary could then be loaded into a platform-specific |
| 319 | debugger. Source files displayed in the debugger correspond to the ones |
| 320 | generated from the translation stage of the build process, that is what was |
| 321 | actually compiled into the object files. |
| 322 |
| --- www/makefile.wiki | |
| +++ www/makefile.wiki | |
| @@ -146,13 +146,13 @@ | |
| 146 | a C program: tools/mkversion.c. |
| 147 | To run the VERSION.h generator, first compile the tools/mkversion.c |
| 148 | source file into a command-line program (named "mkversion.exe") |
| 149 | then run: |
| 150 | |
| 151 | <pre> |
| 152 | mkversion.exe manifest.uuid manifest VERSION >VERSION.h |
| 153 | </pre> |
| 154 | |
| 155 | The pathnames in the above command might need to be adjusted to get the |
| 156 | directories right. The point is that the manifest.uuid, manifest, and |
| 157 | VERSION files |
| 158 | in the root of the source tree are the three arguments and |
| @@ -161,13 +161,13 @@ | |
| 161 | The builtin_data.h header file is generated by a C program: tools/mkbuiltin.c. |
| 162 | The builtin_data.h file contains C-language byte-array definitions for |
| 163 | the content of resource files used by Fossil. To generate the |
| 164 | builtin_data.h file, first compile the mkbuiltin.c program, then run: |
| 165 | |
| 166 | <pre> |
| 167 | mkbuiltin.exe diff.tcl <i>OtherFiles...</i> >builtin_data.h |
| 168 | </pre> |
| 169 | |
| 170 | At the time of this writing, the "diff.tcl" script (a Tcl/Tk script used |
| 171 | to generate implement --tk option on the diff command) is the only resource |
| 172 | file processed using mkbuiltin.exe. However, new resources will likely be |
| 173 | added using this facility in future versions of Fossil. |
| @@ -185,13 +185,13 @@ | |
| 185 | web interface methods, and help text comments. The mkindex program |
| 186 | generates some C code that Fossil uses in order to dispatch commands and |
| 187 | HTTP requests and to show on-line help. Compile the mkindex program |
| 188 | from the mkindex.c source file. Then run: |
| 189 | |
| 190 | <pre> |
| 191 | ./mkindex src.c >page_index.h |
| 192 | </pre> |
| 193 | |
| 194 | Note that "src.c" in the above is a stand-in for the (79) regular source |
| 195 | files of Fossil - all source files except for the exceptions described in |
| 196 | section 2.0 above. |
| 197 | |
| @@ -205,13 +205,13 @@ | |
| 205 | context) into special "printf" operations for generating the output of |
| 206 | an HTTP request. The translate preprocessor is a simple C program whose |
| 207 | sources are in the translate.c source file. The translate preprocess |
| 208 | is run on each of the other ordinary source files separately, like this: |
| 209 | |
| 210 | <pre> |
| 211 | ./translate src.c >src_.c |
| 212 | </pre> |
| 213 | |
| 214 | In this case, the "src.c" file represents any single source file from the |
| 215 | set of ordinary source files as described in section 2.0 above. Note that |
| 216 | each source file is translated separately. By convention, the names of |
| 217 | the translated source files are the names of the input sources with a |
| @@ -235,13 +235,13 @@ | |
| 235 | source files are not scanned by makeheaders. Makeheaders only runs over |
| 236 | "ordinary" source files, not the exceptional source files. However, |
| 237 | makeheaders also uses some extra header files as input. The general format |
| 238 | is like this: |
| 239 | |
| 240 | <pre> |
| 241 | makeheaders src_.c:src.h sqlite3.h th.h VERSION.h |
| 242 | </pre> |
| 243 | |
| 244 | In the example above the "src_.c" and "src.h" names represent all of the |
| 245 | (79) ordinary C source files, each as a separate argument. |
| 246 | |
| 247 | <h1>5.0 Compilation</h1> |
| @@ -304,18 +304,18 @@ | |
| 304 | Debug flags are consistently applied across the whole build process. For |
| 305 | example, use these Debug flags in addition to other flags passed to the |
| 306 | configure scripts: |
| 307 | |
| 308 | On Linux, *NIX and similar platforms: |
| 309 | <pre> |
| 310 | ./configure --fossil-debug |
| 311 | </pre> |
| 312 | |
| 313 | On Windows: |
| 314 | <pre> |
| 315 | win\buildmsvc.bat FOSSIL_DEBUG=1 |
| 316 | </pre> |
| 317 | |
| 318 | The resulting fossil binary could then be loaded into a platform-specific |
| 319 | debugger. Source files displayed in the debugger correspond to the ones |
| 320 | generated from the translation stage of the build process, that is what was |
| 321 | actually compiled into the object files. |
| 322 |
+7
-10
| --- www/mirrortogithub.md | ||
| +++ www/mirrortogithub.md | ||
| @@ -11,19 +11,19 @@ | ||
| 11 | 11 | your project with various things like a README file. Answer "no" to |
| 12 | 12 | everything. You want a completely blank project. GitHub will then |
| 13 | 13 | supply you with a URL for your project that will look something |
| 14 | 14 | like this: |
| 15 | 15 | |
| 16 | - https://github.com/username/project.git | |
| 16 | + https://github.com/username/project.git | |
| 17 | 17 | |
| 18 | 18 | 3. Back on your workstation, move to a checkout for your Fossil |
| 19 | 19 | project and type: |
| 20 | 20 | |
| 21 | 21 | <blockquote> |
| 22 | 22 | <pre> |
| 23 | - $ fossil git export /path/to/git/repo --autopush \ | |
| 24 | - https://<font color="orange">username</font>:<font color="red">password</font>@github.com/username/project.git | |
| 23 | + $ fossil git export /path/to/git/repo --autopush \ | |
| 24 | + https://<font color="orange">username</font>:<font color="red">password</font>@github.com/username/project.git | |
| 25 | 25 | </pre> |
| 26 | 26 | </blockquote> |
| 27 | 27 | |
| 28 | 28 | In place of the <code>/path/to...</code> argument above, put in |
| 29 | 29 | some directory name that is <i>outside</i> of your Fossil checkout. If |
| @@ -58,20 +58,20 @@ | ||
| 58 | 58 | mirrored on GitHub. |
| 59 | 59 | |
| 60 | 60 | 6. Whenever you update your project, simply run this command to update |
| 61 | 61 | the mirror: |
| 62 | 62 | |
| 63 | - $ fossil git export | |
| 63 | + $ fossil git export | |
| 64 | 64 | |
| 65 | 65 | Unlike with the first time you ran that command, you don’t need |
| 66 | 66 | the remaining arguments, because Fossil remembers those things. |
| 67 | 67 | Subsequent mirror updates should usually happen in a fraction of |
| 68 | 68 | a second. |
| 69 | 69 | |
| 70 | 70 | 7. To see the status of your mirror, run: |
| 71 | 71 | |
| 72 | - $ fossil git status | |
| 72 | + $ fossil git status | |
| 73 | 73 | |
| 74 | 74 | ## Notes: |
| 75 | 75 | |
| 76 | 76 | * Unless you specify --force, the mirroring only happens if the Fossil |
| 77 | 77 | repo has changed, with Fossil reporting "no changes", because Fossil |
| @@ -142,29 +142,26 @@ | ||
| 142 | 142 | ## <a id='ex1'></a>Example GitHub Mirrors |
| 143 | 143 | |
| 144 | 144 | As of this writing (2019-03-16) Fossil’s own repository is mirrored |
| 145 | 145 | on GitHub at: |
| 146 | 146 | |
| 147 | -> | |
| 148 | -<https://github.com/drhsqlite/fossil-mirror> | |
| 147 | +> <https://github.com/drhsqlite/fossil-mirror> | |
| 149 | 148 | |
| 150 | 149 | In addition, an official Git mirror of SQLite is available: |
| 151 | 150 | |
| 152 | -> | |
| 153 | -<https://github.com/sqlite/sqlite> | |
| 151 | +> <https://github.com/sqlite/sqlite> | |
| 154 | 152 | |
| 155 | 153 | The Fossil source repositories for these mirrors are at |
| 156 | 154 | <https://www2.fossil-scm.org/fossil> and <https://www2.sqlite.org/src>, |
| 157 | 155 | respectively. Both repositories are hosted on the same VM at |
| 158 | 156 | [Linode](https://www.linode.com). On that machine, there is a |
| 159 | 157 | [cron job](https://linux.die.net/man/8/cron) |
| 160 | 158 | that runs at 17 minutes after the hour, every hour that does: |
| 161 | 159 | |
| 162 | -> | |
| 163 | 160 | /usr/bin/fossil sync -u -R /home/www/fossil/fossil.fossil |
| 164 | 161 | /usr/bin/fossil sync -R /home/www/fossil/sqlite.fossil |
| 165 | 162 | /usr/bin/fossil git export -R /home/www/fossil/fossil.fossil |
| 166 | 163 | /usr/bin/fossil git export -R /home/www/fossil/sqlite.fossil |
| 167 | 164 | |
| 168 | 165 | The initial two "sync" commands pull in changes from the primary |
| 169 | 166 | Fossil repositories for Fossil and SQLite. The last two lines |
| 170 | 167 | export the changes to Git and push the results up to GitHub. |
| 171 | 168 |
| --- www/mirrortogithub.md | |
| +++ www/mirrortogithub.md | |
| @@ -11,19 +11,19 @@ | |
| 11 | your project with various things like a README file. Answer "no" to |
| 12 | everything. You want a completely blank project. GitHub will then |
| 13 | supply you with a URL for your project that will look something |
| 14 | like this: |
| 15 | |
| 16 | https://github.com/username/project.git |
| 17 | |
| 18 | 3. Back on your workstation, move to a checkout for your Fossil |
| 19 | project and type: |
| 20 | |
| 21 | <blockquote> |
| 22 | <pre> |
| 23 | $ fossil git export /path/to/git/repo --autopush \ |
| 24 | https://<font color="orange">username</font>:<font color="red">password</font>@github.com/username/project.git |
| 25 | </pre> |
| 26 | </blockquote> |
| 27 | |
| 28 | In place of the <code>/path/to...</code> argument above, put in |
| 29 | some directory name that is <i>outside</i> of your Fossil checkout. If |
| @@ -58,20 +58,20 @@ | |
| 58 | mirrored on GitHub. |
| 59 | |
| 60 | 6. Whenever you update your project, simply run this command to update |
| 61 | the mirror: |
| 62 | |
| 63 | $ fossil git export |
| 64 | |
| 65 | Unlike with the first time you ran that command, you don’t need |
| 66 | the remaining arguments, because Fossil remembers those things. |
| 67 | Subsequent mirror updates should usually happen in a fraction of |
| 68 | a second. |
| 69 | |
| 70 | 7. To see the status of your mirror, run: |
| 71 | |
| 72 | $ fossil git status |
| 73 | |
| 74 | ## Notes: |
| 75 | |
| 76 | * Unless you specify --force, the mirroring only happens if the Fossil |
| 77 | repo has changed, with Fossil reporting "no changes", because Fossil |
| @@ -142,29 +142,26 @@ | |
| 142 | ## <a id='ex1'></a>Example GitHub Mirrors |
| 143 | |
| 144 | As of this writing (2019-03-16) Fossil’s own repository is mirrored |
| 145 | on GitHub at: |
| 146 | |
| 147 | > |
| 148 | <https://github.com/drhsqlite/fossil-mirror> |
| 149 | |
| 150 | In addition, an official Git mirror of SQLite is available: |
| 151 | |
| 152 | > |
| 153 | <https://github.com/sqlite/sqlite> |
| 154 | |
| 155 | The Fossil source repositories for these mirrors are at |
| 156 | <https://www2.fossil-scm.org/fossil> and <https://www2.sqlite.org/src>, |
| 157 | respectively. Both repositories are hosted on the same VM at |
| 158 | [Linode](https://www.linode.com). On that machine, there is a |
| 159 | [cron job](https://linux.die.net/man/8/cron) |
| 160 | that runs at 17 minutes after the hour, every hour that does: |
| 161 | |
| 162 | > |
| 163 | /usr/bin/fossil sync -u -R /home/www/fossil/fossil.fossil |
| 164 | /usr/bin/fossil sync -R /home/www/fossil/sqlite.fossil |
| 165 | /usr/bin/fossil git export -R /home/www/fossil/fossil.fossil |
| 166 | /usr/bin/fossil git export -R /home/www/fossil/sqlite.fossil |
| 167 | |
| 168 | The initial two "sync" commands pull in changes from the primary |
| 169 | Fossil repositories for Fossil and SQLite. The last two lines |
| 170 | export the changes to Git and push the results up to GitHub. |
| 171 |
| --- www/mirrortogithub.md | |
| +++ www/mirrortogithub.md | |
| @@ -11,19 +11,19 @@ | |
| 11 | your project with various things like a README file. Answer "no" to |
| 12 | everything. You want a completely blank project. GitHub will then |
| 13 | supply you with a URL for your project that will look something |
| 14 | like this: |
| 15 | |
| 16 | https://github.com/username/project.git |
| 17 | |
| 18 | 3. Back on your workstation, move to a checkout for your Fossil |
| 19 | project and type: |
| 20 | |
| 21 | <blockquote> |
| 22 | <pre> |
| 23 | $ fossil git export /path/to/git/repo --autopush \ |
| 24 | https://<font color="orange">username</font>:<font color="red">password</font>@github.com/username/project.git |
| 25 | </pre> |
| 26 | </blockquote> |
| 27 | |
| 28 | In place of the <code>/path/to...</code> argument above, put in |
| 29 | some directory name that is <i>outside</i> of your Fossil checkout. If |
| @@ -58,20 +58,20 @@ | |
| 58 | mirrored on GitHub. |
| 59 | |
| 60 | 6. Whenever you update your project, simply run this command to update |
| 61 | the mirror: |
| 62 | |
| 63 | $ fossil git export |
| 64 | |
| 65 | Unlike with the first time you ran that command, you don’t need |
| 66 | the remaining arguments, because Fossil remembers those things. |
| 67 | Subsequent mirror updates should usually happen in a fraction of |
| 68 | a second. |
| 69 | |
| 70 | 7. To see the status of your mirror, run: |
| 71 | |
| 72 | $ fossil git status |
| 73 | |
| 74 | ## Notes: |
| 75 | |
| 76 | * Unless you specify --force, the mirroring only happens if the Fossil |
| 77 | repo has changed, with Fossil reporting "no changes", because Fossil |
| @@ -142,29 +142,26 @@ | |
| 142 | ## <a id='ex1'></a>Example GitHub Mirrors |
| 143 | |
| 144 | As of this writing (2019-03-16) Fossil’s own repository is mirrored |
| 145 | on GitHub at: |
| 146 | |
| 147 | > <https://github.com/drhsqlite/fossil-mirror> |
| 148 | |
| 149 | In addition, an official Git mirror of SQLite is available: |
| 150 | |
| 151 | > <https://github.com/sqlite/sqlite> |
| 152 | |
| 153 | The Fossil source repositories for these mirrors are at |
| 154 | <https://www2.fossil-scm.org/fossil> and <https://www2.sqlite.org/src>, |
| 155 | respectively. Both repositories are hosted on the same VM at |
| 156 | [Linode](https://www.linode.com). On that machine, there is a |
| 157 | [cron job](https://linux.die.net/man/8/cron) |
| 158 | that runs at 17 minutes after the hour, every hour that does: |
| 159 | |
| 160 | /usr/bin/fossil sync -u -R /home/www/fossil/fossil.fossil |
| 161 | /usr/bin/fossil sync -R /home/www/fossil/sqlite.fossil |
| 162 | /usr/bin/fossil git export -R /home/www/fossil/fossil.fossil |
| 163 | /usr/bin/fossil git export -R /home/www/fossil/sqlite.fossil |
| 164 | |
| 165 | The initial two "sync" commands pull in changes from the primary |
| 166 | Fossil repositories for Fossil and SQLite. The last two lines |
| 167 | export the changes to Git and push the results up to GitHub. |
| 168 |
+2
-2
| --- www/mkindex.tcl | ||
| +++ www/mkindex.tcl | ||
| @@ -166,12 +166,12 @@ | ||
| 166 | 166 | <li> <a href='history.md'>Purpose and History of Fossil</a> |
| 167 | 167 | <li> <a href='build.wiki'>Compiling and installing Fossil</a> |
| 168 | 168 | <li> <a href='../COPYRIGHT-BSD2.txt'>License</a> |
| 169 | 169 | <li> <a href='userlinks.wiki'>Miscellaneous Docs for Fossil Users</a> |
| 170 | 170 | <li> <a href='hacker-howto.wiki'>Fossil Developer's Guide</a> |
| 171 | - <ul><li><a href='$ROOT/wiki?name=Release Build How-To'>Release Build How-To</a>, a.k.a. | |
| 172 | - how deliverables are built</li></ul> | |
| 171 | +<li><a href='$ROOT/wiki?name=Release Build How-To'>Release Build How-To</a>, | |
| 172 | +a.k.a. how deliverables are built</li> | |
| 173 | 173 | </li> |
| 174 | 174 | <li> <a href='$ROOT/wiki?name=To+Do+List'>To Do List (Wiki)</a> |
| 175 | 175 | <li> <a href='https://fossil-scm.org/fossil-book/'>Fossil book</a> |
| 176 | 176 | </ul> |
| 177 | 177 | <h2 id="pindex">Other Documents:</h2> |
| 178 | 178 |
| --- www/mkindex.tcl | |
| +++ www/mkindex.tcl | |
| @@ -166,12 +166,12 @@ | |
| 166 | <li> <a href='history.md'>Purpose and History of Fossil</a> |
| 167 | <li> <a href='build.wiki'>Compiling and installing Fossil</a> |
| 168 | <li> <a href='../COPYRIGHT-BSD2.txt'>License</a> |
| 169 | <li> <a href='userlinks.wiki'>Miscellaneous Docs for Fossil Users</a> |
| 170 | <li> <a href='hacker-howto.wiki'>Fossil Developer's Guide</a> |
| 171 | <ul><li><a href='$ROOT/wiki?name=Release Build How-To'>Release Build How-To</a>, a.k.a. |
| 172 | how deliverables are built</li></ul> |
| 173 | </li> |
| 174 | <li> <a href='$ROOT/wiki?name=To+Do+List'>To Do List (Wiki)</a> |
| 175 | <li> <a href='https://fossil-scm.org/fossil-book/'>Fossil book</a> |
| 176 | </ul> |
| 177 | <h2 id="pindex">Other Documents:</h2> |
| 178 |
| --- www/mkindex.tcl | |
| +++ www/mkindex.tcl | |
| @@ -166,12 +166,12 @@ | |
| 166 | <li> <a href='history.md'>Purpose and History of Fossil</a> |
| 167 | <li> <a href='build.wiki'>Compiling and installing Fossil</a> |
| 168 | <li> <a href='../COPYRIGHT-BSD2.txt'>License</a> |
| 169 | <li> <a href='userlinks.wiki'>Miscellaneous Docs for Fossil Users</a> |
| 170 | <li> <a href='hacker-howto.wiki'>Fossil Developer's Guide</a> |
| 171 | <li><a href='$ROOT/wiki?name=Release Build How-To'>Release Build How-To</a>, |
| 172 | a.k.a. how deliverables are built</li> |
| 173 | </li> |
| 174 | <li> <a href='$ROOT/wiki?name=To+Do+List'>To Do List (Wiki)</a> |
| 175 | <li> <a href='https://fossil-scm.org/fossil-book/'>Fossil book</a> |
| 176 | </ul> |
| 177 | <h2 id="pindex">Other Documents:</h2> |
| 178 |
+3
-3
| --- www/newrepo.wiki | ||
| +++ www/newrepo.wiki | ||
| @@ -38,17 +38,17 @@ | ||
| 38 | 38 | but that's personal preference.) |
| 39 | 39 | |
| 40 | 40 | Once you are done, kill the fossil server (with Ctrl-C or equivalent) |
| 41 | 41 | and close the browser window. |
| 42 | 42 | |
| 43 | -<blockquote> | |
| 44 | -Tip: it is not strictly required to configure a repository | |
| 43 | +<div class="sidebar"> | |
| 44 | +It is not strictly required to configure a repository | |
| 45 | 45 | this way, but if you are going to share a repo over the net then it |
| 46 | 46 | is highly recommended. If you are only going to work with the repo |
| 47 | 47 | locally, you can skip the configuration step and do it later if |
| 48 | 48 | you decide you want to share your repo. |
| 49 | -</blockquote> | |
| 49 | +</div> | |
| 50 | 50 | |
| 51 | 51 | The next thing we need to do is <em>open</em> the repository. To do so |
| 52 | 52 | we create a working directory and then <tt>cd</tt> to it: |
| 53 | 53 | |
| 54 | 54 | <verbatim> |
| 55 | 55 |
| --- www/newrepo.wiki | |
| +++ www/newrepo.wiki | |
| @@ -38,17 +38,17 @@ | |
| 38 | but that's personal preference.) |
| 39 | |
| 40 | Once you are done, kill the fossil server (with Ctrl-C or equivalent) |
| 41 | and close the browser window. |
| 42 | |
| 43 | <blockquote> |
| 44 | Tip: it is not strictly required to configure a repository |
| 45 | this way, but if you are going to share a repo over the net then it |
| 46 | is highly recommended. If you are only going to work with the repo |
| 47 | locally, you can skip the configuration step and do it later if |
| 48 | you decide you want to share your repo. |
| 49 | </blockquote> |
| 50 | |
| 51 | The next thing we need to do is <em>open</em> the repository. To do so |
| 52 | we create a working directory and then <tt>cd</tt> to it: |
| 53 | |
| 54 | <verbatim> |
| 55 |
| --- www/newrepo.wiki | |
| +++ www/newrepo.wiki | |
| @@ -38,17 +38,17 @@ | |
| 38 | but that's personal preference.) |
| 39 | |
| 40 | Once you are done, kill the fossil server (with Ctrl-C or equivalent) |
| 41 | and close the browser window. |
| 42 | |
| 43 | <div class="sidebar"> |
| 44 | It is not strictly required to configure a repository |
| 45 | this way, but if you are going to share a repo over the net then it |
| 46 | is highly recommended. If you are only going to work with the repo |
| 47 | locally, you can skip the configuration step and do it later if |
| 48 | you decide you want to share your repo. |
| 49 | </div> |
| 50 | |
| 51 | The next thing we need to do is <em>open</em> the repository. To do so |
| 52 | we create a working directory and then <tt>cd</tt> to it: |
| 53 | |
| 54 | <verbatim> |
| 55 |
+10
-11
| --- www/password.wiki | ||
| +++ www/password.wiki | ||
| @@ -1,7 +1,6 @@ | ||
| 1 | 1 | <title>Fossil Password Management</title> |
| 2 | -<h1 align="center">Password Management</h1> | |
| 3 | 2 | |
| 4 | 3 | Fossil handles user authentication using passwords. |
| 5 | 4 | Passwords are unique to each repository. Passwords are not part of the |
| 6 | 5 | persistent state of a project. Passwords are not versioned and |
| 7 | 6 | are not transmitted from one repository to another during a sync. |
| @@ -22,13 +21,13 @@ | ||
| 22 | 21 | the project-code, the user login, and the user cleartext password. |
| 23 | 22 | Suppose user "alice" with password "asdfg" had an account on the |
| 24 | 23 | Fossil self-hosting repository. Then the value of USER.PW |
| 25 | 24 | for alice would be the SHA1 hash of |
| 26 | 25 | |
| 27 | -<blockquote> | |
| 26 | +<pre> | |
| 28 | 27 | CE59BB9F186226D80E49D1FA2DB29F935CCA0333/alice/asdfg |
| 29 | -</blockquote> | |
| 28 | +</pre> | |
| 30 | 29 | |
| 31 | 30 | Note that by including the project-code and the login as part of the |
| 32 | 31 | hash, a different USER.PW value results even if two or more users on |
| 33 | 32 | the repository select the same "asdfg" password or if user alice |
| 34 | 33 | reuses the same password on multiple projects. |
| @@ -37,23 +36,23 @@ | ||
| 37 | 36 | "user" command-line method, the new password is stored using the SHA1 |
| 38 | 37 | encoding. Thus, cleartext passwords will gradually migrate to become |
| 39 | 38 | SHA1 passwords. All remaining cleartext passwords can be converted to |
| 40 | 39 | SHA1 passwords using the following command: |
| 41 | 40 | |
| 42 | -<blockquote><pre> | |
| 41 | +<pre> | |
| 43 | 42 | fossil test-hash-passwords <i>REPOSITORY-NAME</i> |
| 44 | -</pre></blockquote> | |
| 43 | +</pre> | |
| 45 | 44 | |
| 46 | 45 | Remember that converting from cleartext to SHA1 passwords is an |
| 47 | 46 | irreversible operation. |
| 48 | 47 | |
| 49 | 48 | The only way to insert a new cleartext password into the USER table |
| 50 | 49 | is to do so manually using SQL commands. For example: |
| 51 | 50 | |
| 52 | -<blockquote><pre> | |
| 51 | +<pre> | |
| 53 | 52 | UPDATE user SET pw='asdfg' WHERE login='alice'; |
| 54 | -</pre></blockquote> | |
| 53 | +</pre> | |
| 55 | 54 | |
| 56 | 55 | Note that an password that is an empty string or NULL will disable |
| 57 | 56 | all login for that user. Thus, to lock a user out of the system, |
| 58 | 57 | one has only to set their password to an empty string, using either |
| 59 | 58 | the web interface or direct SQL manipulation of the USER table. |
| @@ -117,24 +116,24 @@ | ||
| 117 | 116 | only holds the SHA1 hash of the password, then only newer clients will be |
| 118 | 117 | able to authenticate to the server. |
| 119 | 118 | |
| 120 | 119 | The client normally gets the login and password from the "remote URL". |
| 121 | 120 | |
| 122 | -<blockquote><pre> | |
| 121 | +<pre> | |
| 123 | 122 | http://<span style="color:blue">login:password</span>@servername.org/path |
| 124 | -</pre></blockquote> | |
| 123 | +</pre> | |
| 125 | 124 | |
| 126 | 125 | For older clients, the password is used for the shared secret as stated |
| 127 | 126 | in the URL and with no encoding. |
| 128 | 127 | For newer clients, the shared secret is derived from the password |
| 129 | 128 | by transformed the password using the SHA1 hash encoding |
| 130 | 129 | described above. However, if the first character of the password is |
| 131 | 130 | "*" (ASCII 0x2a) then the "*" is skipped and the rest of the password |
| 132 | 131 | is used directly as the share secret without the SHA1 encoding. |
| 133 | 132 | |
| 134 | -<blockquote><pre> | |
| 133 | +<pre> | |
| 135 | 134 | http://<span style="color:blue">login:*password</span>@servername.org/path |
| 136 | -</pre></blockquote> | |
| 135 | +</pre> | |
| 137 | 136 | |
| 138 | 137 | This *-before-the-password trick can be used by newer clients to |
| 139 | 138 | sync against a legacy server that does not understand the new SHA1 |
| 140 | 139 | password encoding. |
| 141 | 140 |
| --- www/password.wiki | |
| +++ www/password.wiki | |
| @@ -1,7 +1,6 @@ | |
| 1 | <title>Fossil Password Management</title> |
| 2 | <h1 align="center">Password Management</h1> |
| 3 | |
| 4 | Fossil handles user authentication using passwords. |
| 5 | Passwords are unique to each repository. Passwords are not part of the |
| 6 | persistent state of a project. Passwords are not versioned and |
| 7 | are not transmitted from one repository to another during a sync. |
| @@ -22,13 +21,13 @@ | |
| 22 | the project-code, the user login, and the user cleartext password. |
| 23 | Suppose user "alice" with password "asdfg" had an account on the |
| 24 | Fossil self-hosting repository. Then the value of USER.PW |
| 25 | for alice would be the SHA1 hash of |
| 26 | |
| 27 | <blockquote> |
| 28 | CE59BB9F186226D80E49D1FA2DB29F935CCA0333/alice/asdfg |
| 29 | </blockquote> |
| 30 | |
| 31 | Note that by including the project-code and the login as part of the |
| 32 | hash, a different USER.PW value results even if two or more users on |
| 33 | the repository select the same "asdfg" password or if user alice |
| 34 | reuses the same password on multiple projects. |
| @@ -37,23 +36,23 @@ | |
| 37 | "user" command-line method, the new password is stored using the SHA1 |
| 38 | encoding. Thus, cleartext passwords will gradually migrate to become |
| 39 | SHA1 passwords. All remaining cleartext passwords can be converted to |
| 40 | SHA1 passwords using the following command: |
| 41 | |
| 42 | <blockquote><pre> |
| 43 | fossil test-hash-passwords <i>REPOSITORY-NAME</i> |
| 44 | </pre></blockquote> |
| 45 | |
| 46 | Remember that converting from cleartext to SHA1 passwords is an |
| 47 | irreversible operation. |
| 48 | |
| 49 | The only way to insert a new cleartext password into the USER table |
| 50 | is to do so manually using SQL commands. For example: |
| 51 | |
| 52 | <blockquote><pre> |
| 53 | UPDATE user SET pw='asdfg' WHERE login='alice'; |
| 54 | </pre></blockquote> |
| 55 | |
| 56 | Note that an password that is an empty string or NULL will disable |
| 57 | all login for that user. Thus, to lock a user out of the system, |
| 58 | one has only to set their password to an empty string, using either |
| 59 | the web interface or direct SQL manipulation of the USER table. |
| @@ -117,24 +116,24 @@ | |
| 117 | only holds the SHA1 hash of the password, then only newer clients will be |
| 118 | able to authenticate to the server. |
| 119 | |
| 120 | The client normally gets the login and password from the "remote URL". |
| 121 | |
| 122 | <blockquote><pre> |
| 123 | http://<span style="color:blue">login:password</span>@servername.org/path |
| 124 | </pre></blockquote> |
| 125 | |
| 126 | For older clients, the password is used for the shared secret as stated |
| 127 | in the URL and with no encoding. |
| 128 | For newer clients, the shared secret is derived from the password |
| 129 | by transformed the password using the SHA1 hash encoding |
| 130 | described above. However, if the first character of the password is |
| 131 | "*" (ASCII 0x2a) then the "*" is skipped and the rest of the password |
| 132 | is used directly as the share secret without the SHA1 encoding. |
| 133 | |
| 134 | <blockquote><pre> |
| 135 | http://<span style="color:blue">login:*password</span>@servername.org/path |
| 136 | </pre></blockquote> |
| 137 | |
| 138 | This *-before-the-password trick can be used by newer clients to |
| 139 | sync against a legacy server that does not understand the new SHA1 |
| 140 | password encoding. |
| 141 |
| --- www/password.wiki | |
| +++ www/password.wiki | |
| @@ -1,7 +1,6 @@ | |
| 1 | <title>Fossil Password Management</title> |
| 2 | |
| 3 | Fossil handles user authentication using passwords. |
| 4 | Passwords are unique to each repository. Passwords are not part of the |
| 5 | persistent state of a project. Passwords are not versioned and |
| 6 | are not transmitted from one repository to another during a sync. |
| @@ -22,13 +21,13 @@ | |
| 21 | the project-code, the user login, and the user cleartext password. |
| 22 | Suppose user "alice" with password "asdfg" had an account on the |
| 23 | Fossil self-hosting repository. Then the value of USER.PW |
| 24 | for alice would be the SHA1 hash of |
| 25 | |
| 26 | <pre> |
| 27 | CE59BB9F186226D80E49D1FA2DB29F935CCA0333/alice/asdfg |
| 28 | </pre> |
| 29 | |
| 30 | Note that by including the project-code and the login as part of the |
| 31 | hash, a different USER.PW value results even if two or more users on |
| 32 | the repository select the same "asdfg" password or if user alice |
| 33 | reuses the same password on multiple projects. |
| @@ -37,23 +36,23 @@ | |
| 36 | "user" command-line method, the new password is stored using the SHA1 |
| 37 | encoding. Thus, cleartext passwords will gradually migrate to become |
| 38 | SHA1 passwords. All remaining cleartext passwords can be converted to |
| 39 | SHA1 passwords using the following command: |
| 40 | |
| 41 | <pre> |
| 42 | fossil test-hash-passwords <i>REPOSITORY-NAME</i> |
| 43 | </pre> |
| 44 | |
| 45 | Remember that converting from cleartext to SHA1 passwords is an |
| 46 | irreversible operation. |
| 47 | |
| 48 | The only way to insert a new cleartext password into the USER table |
| 49 | is to do so manually using SQL commands. For example: |
| 50 | |
| 51 | <pre> |
| 52 | UPDATE user SET pw='asdfg' WHERE login='alice'; |
| 53 | </pre> |
| 54 | |
| 55 | Note that an password that is an empty string or NULL will disable |
| 56 | all login for that user. Thus, to lock a user out of the system, |
| 57 | one has only to set their password to an empty string, using either |
| 58 | the web interface or direct SQL manipulation of the USER table. |
| @@ -117,24 +116,24 @@ | |
| 116 | only holds the SHA1 hash of the password, then only newer clients will be |
| 117 | able to authenticate to the server. |
| 118 | |
| 119 | The client normally gets the login and password from the "remote URL". |
| 120 | |
| 121 | <pre> |
| 122 | http://<span style="color:blue">login:password</span>@servername.org/path |
| 123 | </pre> |
| 124 | |
| 125 | For older clients, the password is used for the shared secret as stated |
| 126 | in the URL and with no encoding. |
| 127 | For newer clients, the shared secret is derived from the password |
| 128 | by transformed the password using the SHA1 hash encoding |
| 129 | described above. However, if the first character of the password is |
| 130 | "*" (ASCII 0x2a) then the "*" is skipped and the rest of the password |
| 131 | is used directly as the share secret without the SHA1 encoding. |
| 132 | |
| 133 | <pre> |
| 134 | http://<span style="color:blue">login:*password</span>@servername.org/path |
| 135 | </pre> |
| 136 | |
| 137 | This *-before-the-password trick can be used by newer clients to |
| 138 | sync against a legacy server that does not understand the new SHA1 |
| 139 | password encoding. |
| 140 |
+2
-2
| --- www/permutedindex.html | ||
| +++ www/permutedindex.html | ||
| @@ -11,12 +11,12 @@ | ||
| 11 | 11 | <li> <a href='history.md'>Purpose and History of Fossil</a> |
| 12 | 12 | <li> <a href='build.wiki'>Compiling and installing Fossil</a> |
| 13 | 13 | <li> <a href='../COPYRIGHT-BSD2.txt'>License</a> |
| 14 | 14 | <li> <a href='userlinks.wiki'>Miscellaneous Docs for Fossil Users</a> |
| 15 | 15 | <li> <a href='hacker-howto.wiki'>Fossil Developer's Guide</a> |
| 16 | - <ul><li><a href='$ROOT/wiki?name=Release Build How-To'>Release Build How-To</a>, a.k.a. | |
| 17 | - how deliverables are built</li></ul> | |
| 16 | +<li><a href='$ROOT/wiki?name=Release Build How-To'>Release Build How-To</a>, | |
| 17 | +a.k.a. how deliverables are built</li> | |
| 18 | 18 | </li> |
| 19 | 19 | <li> <a href='$ROOT/wiki?name=To+Do+List'>To Do List (Wiki)</a> |
| 20 | 20 | <li> <a href='https://fossil-scm.org/fossil-book/'>Fossil book</a> |
| 21 | 21 | </ul> |
| 22 | 22 | <h2 id="pindex">Other Documents:</h2> |
| 23 | 23 |
| --- www/permutedindex.html | |
| +++ www/permutedindex.html | |
| @@ -11,12 +11,12 @@ | |
| 11 | <li> <a href='history.md'>Purpose and History of Fossil</a> |
| 12 | <li> <a href='build.wiki'>Compiling and installing Fossil</a> |
| 13 | <li> <a href='../COPYRIGHT-BSD2.txt'>License</a> |
| 14 | <li> <a href='userlinks.wiki'>Miscellaneous Docs for Fossil Users</a> |
| 15 | <li> <a href='hacker-howto.wiki'>Fossil Developer's Guide</a> |
| 16 | <ul><li><a href='$ROOT/wiki?name=Release Build How-To'>Release Build How-To</a>, a.k.a. |
| 17 | how deliverables are built</li></ul> |
| 18 | </li> |
| 19 | <li> <a href='$ROOT/wiki?name=To+Do+List'>To Do List (Wiki)</a> |
| 20 | <li> <a href='https://fossil-scm.org/fossil-book/'>Fossil book</a> |
| 21 | </ul> |
| 22 | <h2 id="pindex">Other Documents:</h2> |
| 23 |
| --- www/permutedindex.html | |
| +++ www/permutedindex.html | |
| @@ -11,12 +11,12 @@ | |
| 11 | <li> <a href='history.md'>Purpose and History of Fossil</a> |
| 12 | <li> <a href='build.wiki'>Compiling and installing Fossil</a> |
| 13 | <li> <a href='../COPYRIGHT-BSD2.txt'>License</a> |
| 14 | <li> <a href='userlinks.wiki'>Miscellaneous Docs for Fossil Users</a> |
| 15 | <li> <a href='hacker-howto.wiki'>Fossil Developer's Guide</a> |
| 16 | <li><a href='$ROOT/wiki?name=Release Build How-To'>Release Build How-To</a>, |
| 17 | a.k.a. how deliverables are built</li> |
| 18 | </li> |
| 19 | <li> <a href='$ROOT/wiki?name=To+Do+List'>To Do List (Wiki)</a> |
| 20 | <li> <a href='https://fossil-scm.org/fossil-book/'>Fossil book</a> |
| 21 | </ul> |
| 22 | <h2 id="pindex">Other Documents:</h2> |
| 23 |
-1
| --- www/pop.wiki | ||
| +++ www/pop.wiki | ||
| @@ -1,7 +1,6 @@ | ||
| 1 | 1 | <title>Principles Of Operation</title> |
| 2 | -<h1 align="center">Principles Of Operation</h1> | |
| 3 | 2 | |
| 4 | 3 | This page attempts to define the foundational principals upon |
| 5 | 4 | which Fossil is built. |
| 6 | 5 | |
| 7 | 6 | * A project consists of source files, wiki pages, and |
| 8 | 7 |
| --- www/pop.wiki | |
| +++ www/pop.wiki | |
| @@ -1,7 +1,6 @@ | |
| 1 | <title>Principles Of Operation</title> |
| 2 | <h1 align="center">Principles Of Operation</h1> |
| 3 | |
| 4 | This page attempts to define the foundational principals upon |
| 5 | which Fossil is built. |
| 6 | |
| 7 | * A project consists of source files, wiki pages, and |
| 8 |
| --- www/pop.wiki | |
| +++ www/pop.wiki | |
| @@ -1,7 +1,6 @@ | |
| 1 | <title>Principles Of Operation</title> |
| 2 | |
| 3 | This page attempts to define the foundational principals upon |
| 4 | which Fossil is built. |
| 5 | |
| 6 | * A project consists of source files, wiki pages, and |
| 7 |
+21
-21
| --- www/private.wiki | ||
| +++ www/private.wiki | ||
| @@ -8,13 +8,13 @@ | ||
| 8 | 8 | shared with others. This might be a preliminary or experimental change |
| 9 | 9 | that needs further refinement before it is shared and which might never |
| 10 | 10 | be shared at all. To do this in Fossil, simply commit the change with |
| 11 | 11 | the --private command-line option: |
| 12 | 12 | |
| 13 | -<blockquote><pre> | |
| 13 | +<pre> | |
| 14 | 14 | fossil commit --private |
| 15 | -</pre></blockquote> | |
| 15 | +</pre> | |
| 16 | 16 | |
| 17 | 17 | The --private option causes Fossil to put the check-in in a new branch |
| 18 | 18 | named "private". That branch will not participate in subsequent clone, |
| 19 | 19 | sync, push, or pull operations. The branch will remain on the one local |
| 20 | 20 | repository where it was created. Note that you only use the --private |
| @@ -25,15 +25,15 @@ | ||
| 25 | 25 | |
| 26 | 26 | After additional work, one might desire to publish the changes associated |
| 27 | 27 | with a private branch. The usual way to do this is to merge those |
| 28 | 28 | changes into a public branch. For example: |
| 29 | 29 | |
| 30 | -<blockquote><pre> | |
| 30 | +<pre> | |
| 31 | 31 | fossil update trunk |
| 32 | 32 | fossil merge private |
| 33 | 33 | fossil commit |
| 34 | -</pre></blockquote> | |
| 34 | +</pre> | |
| 35 | 35 | |
| 36 | 36 | The private branch remains private and is not recorded as a parent |
| 37 | 37 | in the merge manifest's P-card, but all of the changes associated with |
| 38 | 38 | the private branch are now folded into the public branch and are hence |
| 39 | 39 | visible to other users of the project. |
| @@ -40,10 +40,23 @@ | ||
| 40 | 40 | |
| 41 | 41 | A private branch created with Fossil version 1.30 or newer can also be |
| 42 | 42 | converted into a public branch using the <code>fossil publish</code> |
| 43 | 43 | command. However, there is no way to convert a private branch created with |
| 44 | 44 | older versions of Fossil into a public branch. |
| 45 | + | |
| 46 | +<div class="sidebar"> | |
| 47 | +To avoid generating a missing artifact | |
| 48 | +reference on peer repositories without the private branch, the merge parent | |
| 49 | +is not recorded when merging the private branch into a public branch. As a | |
| 50 | +consequence, the web UI timeline does not draw a merge line from the private | |
| 51 | +merge parent to the public merge child. Moreover, repeat private-to-public | |
| 52 | +merge operations (without the [/help?cmd=merge | --force option]) with files | |
| 53 | +added on the private branch may only work once, but later abort with | |
| 54 | +"WARNING: no common ancestor for FILE", as the parent-child relationship is | |
| 55 | +not recorded. (See the [/doc/trunk/www/branching.wiki | Branching, Forking, | |
| 56 | +Merging, and Tagging] document for more information.) | |
| 57 | +</div> | |
| 45 | 58 | |
| 46 | 59 | The <code>--integrate</code> option of <code>fossil merge</code> (to close |
| 47 | 60 | the merged branch when committing) is ignored for a private branch -- or the |
| 48 | 61 | check-in manifest of the resulting merge child would include a |
| 49 | 62 | <code>+close</code> tag referring to the leaf check-in on the private branch, |
| @@ -50,23 +63,10 @@ | ||
| 50 | 63 | and generate a missing artifact reference on repository clones without that |
| 51 | 64 | private branch. It's still possible to close the leaf of the private branch |
| 52 | 65 | (after committing the merge child) with the <code>fossil amend --close</code> |
| 53 | 66 | command. |
| 54 | 67 | |
| 55 | -<blockquote><small> | |
| 56 | -Side note: For the same reason, i.e. so as not to generate a missing artifact | |
| 57 | -reference on peer repositories without the private branch, the merge parent | |
| 58 | -is not recorded when merging the private branch into a public branch. As a | |
| 59 | -consequence, the web UI timeline does not draw a merge line from the private | |
| 60 | -merge parent to the public merge child. Moreover, repeat private-to-public | |
| 61 | -merge operations (without the [/help?cmd=merge | --force option]) with files | |
| 62 | -added on the private branch may only work once, but later abort with | |
| 63 | -"WARNING: no common ancestor for FILE", as the parent-child relationship is | |
| 64 | -not recorded (see the [/doc/trunk/www/branching.wiki | Branching, Forking, | |
| 65 | -Merging, and Tagging] document for more information). | |
| 66 | -</small></blockquote> | |
| 67 | - | |
| 68 | 68 | <h2>Syncing Private Branches</h2> |
| 69 | 69 | |
| 70 | 70 | A private branch normally stays on the one repository where it was |
| 71 | 71 | originally created. But sometimes you want to share private branches |
| 72 | 72 | with another repository. For example, you might be building a cross-platform |
| @@ -75,13 +75,13 @@ | ||
| 75 | 75 | between these machines by using the --private option on the "sync", |
| 76 | 76 | "push", "pull", and "clone" commands. For example, if you are running |
| 77 | 77 | "fossil server" on your Linux box and you want to clone that repository |
| 78 | 78 | to your Mac, including all private branches, use: |
| 79 | 79 | |
| 80 | -<blockquote><pre> | |
| 80 | +<verbatim> | |
| 81 | 81 | fossil clone --private http://[email protected]:8080/ mac-clone.fossil |
| 82 | -</pre></blockquote> | |
| 82 | +</verbatim> | |
| 83 | 83 | |
| 84 | 84 | You'll have to supply a username and password in order for this to work. |
| 85 | 85 | Fossil will not clone (or sync) private branches anonymously. |
| 86 | 86 | |
| 87 | 87 | By default, there are no users that can do private branch syncing. You |
| @@ -101,13 +101,13 @@ | ||
| 101 | 101 | |
| 102 | 102 | <h2>Purging Private Branches</h2> |
| 103 | 103 | |
| 104 | 104 | You can remove all private branches from a repository using this command: |
| 105 | 105 | |
| 106 | -<blockquote><pre> | |
| 106 | +<pre> | |
| 107 | 107 | fossil scrub --private |
| 108 | -</pre></blockquote> | |
| 108 | +</pre> | |
| 109 | 109 | |
| 110 | 110 | Note that the above is a permanent and irreversible change. You will |
| 111 | 111 | be asked to confirm before continuing. Once the private branches are |
| 112 | 112 | removed, they cannot be retrieved (unless you have synced them to another |
| 113 | 113 | repository.) So be careful with the command. |
| 114 | 114 |
| --- www/private.wiki | |
| +++ www/private.wiki | |
| @@ -8,13 +8,13 @@ | |
| 8 | shared with others. This might be a preliminary or experimental change |
| 9 | that needs further refinement before it is shared and which might never |
| 10 | be shared at all. To do this in Fossil, simply commit the change with |
| 11 | the --private command-line option: |
| 12 | |
| 13 | <blockquote><pre> |
| 14 | fossil commit --private |
| 15 | </pre></blockquote> |
| 16 | |
| 17 | The --private option causes Fossil to put the check-in in a new branch |
| 18 | named "private". That branch will not participate in subsequent clone, |
| 19 | sync, push, or pull operations. The branch will remain on the one local |
| 20 | repository where it was created. Note that you only use the --private |
| @@ -25,15 +25,15 @@ | |
| 25 | |
| 26 | After additional work, one might desire to publish the changes associated |
| 27 | with a private branch. The usual way to do this is to merge those |
| 28 | changes into a public branch. For example: |
| 29 | |
| 30 | <blockquote><pre> |
| 31 | fossil update trunk |
| 32 | fossil merge private |
| 33 | fossil commit |
| 34 | </pre></blockquote> |
| 35 | |
| 36 | The private branch remains private and is not recorded as a parent |
| 37 | in the merge manifest's P-card, but all of the changes associated with |
| 38 | the private branch are now folded into the public branch and are hence |
| 39 | visible to other users of the project. |
| @@ -40,10 +40,23 @@ | |
| 40 | |
| 41 | A private branch created with Fossil version 1.30 or newer can also be |
| 42 | converted into a public branch using the <code>fossil publish</code> |
| 43 | command. However, there is no way to convert a private branch created with |
| 44 | older versions of Fossil into a public branch. |
| 45 | |
| 46 | The <code>--integrate</code> option of <code>fossil merge</code> (to close |
| 47 | the merged branch when committing) is ignored for a private branch -- or the |
| 48 | check-in manifest of the resulting merge child would include a |
| 49 | <code>+close</code> tag referring to the leaf check-in on the private branch, |
| @@ -50,23 +63,10 @@ | |
| 50 | and generate a missing artifact reference on repository clones without that |
| 51 | private branch. It's still possible to close the leaf of the private branch |
| 52 | (after committing the merge child) with the <code>fossil amend --close</code> |
| 53 | command. |
| 54 | |
| 55 | <blockquote><small> |
| 56 | Side note: For the same reason, i.e. so as not to generate a missing artifact |
| 57 | reference on peer repositories without the private branch, the merge parent |
| 58 | is not recorded when merging the private branch into a public branch. As a |
| 59 | consequence, the web UI timeline does not draw a merge line from the private |
| 60 | merge parent to the public merge child. Moreover, repeat private-to-public |
| 61 | merge operations (without the [/help?cmd=merge | --force option]) with files |
| 62 | added on the private branch may only work once, but later abort with |
| 63 | "WARNING: no common ancestor for FILE", as the parent-child relationship is |
| 64 | not recorded (see the [/doc/trunk/www/branching.wiki | Branching, Forking, |
| 65 | Merging, and Tagging] document for more information). |
| 66 | </small></blockquote> |
| 67 | |
| 68 | <h2>Syncing Private Branches</h2> |
| 69 | |
| 70 | A private branch normally stays on the one repository where it was |
| 71 | originally created. But sometimes you want to share private branches |
| 72 | with another repository. For example, you might be building a cross-platform |
| @@ -75,13 +75,13 @@ | |
| 75 | between these machines by using the --private option on the "sync", |
| 76 | "push", "pull", and "clone" commands. For example, if you are running |
| 77 | "fossil server" on your Linux box and you want to clone that repository |
| 78 | to your Mac, including all private branches, use: |
| 79 | |
| 80 | <blockquote><pre> |
| 81 | fossil clone --private http://[email protected]:8080/ mac-clone.fossil |
| 82 | </pre></blockquote> |
| 83 | |
| 84 | You'll have to supply a username and password in order for this to work. |
| 85 | Fossil will not clone (or sync) private branches anonymously. |
| 86 | |
| 87 | By default, there are no users that can do private branch syncing. You |
| @@ -101,13 +101,13 @@ | |
| 101 | |
| 102 | <h2>Purging Private Branches</h2> |
| 103 | |
| 104 | You can remove all private branches from a repository using this command: |
| 105 | |
| 106 | <blockquote><pre> |
| 107 | fossil scrub --private |
| 108 | </pre></blockquote> |
| 109 | |
| 110 | Note that the above is a permanent and irreversible change. You will |
| 111 | be asked to confirm before continuing. Once the private branches are |
| 112 | removed, they cannot be retrieved (unless you have synced them to another |
| 113 | repository.) So be careful with the command. |
| 114 |
| --- www/private.wiki | |
| +++ www/private.wiki | |
| @@ -8,13 +8,13 @@ | |
| 8 | shared with others. This might be a preliminary or experimental change |
| 9 | that needs further refinement before it is shared and which might never |
| 10 | be shared at all. To do this in Fossil, simply commit the change with |
| 11 | the --private command-line option: |
| 12 | |
| 13 | <pre> |
| 14 | fossil commit --private |
| 15 | </pre> |
| 16 | |
| 17 | The --private option causes Fossil to put the check-in in a new branch |
| 18 | named "private". That branch will not participate in subsequent clone, |
| 19 | sync, push, or pull operations. The branch will remain on the one local |
| 20 | repository where it was created. Note that you only use the --private |
| @@ -25,15 +25,15 @@ | |
| 25 | |
| 26 | After additional work, one might desire to publish the changes associated |
| 27 | with a private branch. The usual way to do this is to merge those |
| 28 | changes into a public branch. For example: |
| 29 | |
| 30 | <pre> |
| 31 | fossil update trunk |
| 32 | fossil merge private |
| 33 | fossil commit |
| 34 | </pre> |
| 35 | |
| 36 | The private branch remains private and is not recorded as a parent |
| 37 | in the merge manifest's P-card, but all of the changes associated with |
| 38 | the private branch are now folded into the public branch and are hence |
| 39 | visible to other users of the project. |
| @@ -40,10 +40,23 @@ | |
| 40 | |
| 41 | A private branch created with Fossil version 1.30 or newer can also be |
| 42 | converted into a public branch using the <code>fossil publish</code> |
| 43 | command. However, there is no way to convert a private branch created with |
| 44 | older versions of Fossil into a public branch. |
| 45 | |
| 46 | <div class="sidebar"> |
| 47 | To avoid generating a missing artifact |
| 48 | reference on peer repositories without the private branch, the merge parent |
| 49 | is not recorded when merging the private branch into a public branch. As a |
| 50 | consequence, the web UI timeline does not draw a merge line from the private |
| 51 | merge parent to the public merge child. Moreover, repeat private-to-public |
| 52 | merge operations (without the [/help?cmd=merge | --force option]) with files |
| 53 | added on the private branch may only work once, but later abort with |
| 54 | "WARNING: no common ancestor for FILE", as the parent-child relationship is |
| 55 | not recorded. (See the [/doc/trunk/www/branching.wiki | Branching, Forking, |
| 56 | Merging, and Tagging] document for more information.) |
| 57 | </div> |
| 58 | |
| 59 | The <code>--integrate</code> option of <code>fossil merge</code> (to close |
| 60 | the merged branch when committing) is ignored for a private branch -- or the |
| 61 | check-in manifest of the resulting merge child would include a |
| 62 | <code>+close</code> tag referring to the leaf check-in on the private branch, |
| @@ -50,23 +63,10 @@ | |
| 63 | and generate a missing artifact reference on repository clones without that |
| 64 | private branch. It's still possible to close the leaf of the private branch |
| 65 | (after committing the merge child) with the <code>fossil amend --close</code> |
| 66 | command. |
| 67 | |
| 68 | <h2>Syncing Private Branches</h2> |
| 69 | |
| 70 | A private branch normally stays on the one repository where it was |
| 71 | originally created. But sometimes you want to share private branches |
| 72 | with another repository. For example, you might be building a cross-platform |
| @@ -75,13 +75,13 @@ | |
| 75 | between these machines by using the --private option on the "sync", |
| 76 | "push", "pull", and "clone" commands. For example, if you are running |
| 77 | "fossil server" on your Linux box and you want to clone that repository |
| 78 | to your Mac, including all private branches, use: |
| 79 | |
| 80 | <verbatim> |
| 81 | fossil clone --private http://[email protected]:8080/ mac-clone.fossil |
| 82 | </verbatim> |
| 83 | |
| 84 | You'll have to supply a username and password in order for this to work. |
| 85 | Fossil will not clone (or sync) private branches anonymously. |
| 86 | |
| 87 | By default, there are no users that can do private branch syncing. You |
| @@ -101,13 +101,13 @@ | |
| 101 | |
| 102 | <h2>Purging Private Branches</h2> |
| 103 | |
| 104 | You can remove all private branches from a repository using this command: |
| 105 | |
| 106 | <pre> |
| 107 | fossil scrub --private |
| 108 | </pre> |
| 109 | |
| 110 | Note that the above is a permanent and irreversible change. You will |
| 111 | be asked to confirm before continuing. Once the private branches are |
| 112 | removed, they cannot be retrieved (unless you have synced them to another |
| 113 | repository.) So be careful with the command. |
| 114 |
+17
-22
| --- www/qandc.wiki | ||
| +++ www/qandc.wiki | ||
| @@ -1,18 +1,16 @@ | ||
| 1 | 1 | <title>Questions And Criticisms</title> |
| 2 | -<nowiki> | |
| 3 | -<h1 align="center">Questions And Criticisms</h1> | |
| 4 | 2 | |
| 5 | 3 | This page is a collection of real questions and criticisms that were |
| 6 | 4 | raised against Fossil early in its history (circa 2008). |
| 7 | 5 | This page is old and has not been kept up-to-date. See the |
| 8 | -</nowiki>[/finfo?name=www/qandc.wiki|change history of this page]<nowiki>. | |
| 6 | +[/finfo?name=www/qandc.wiki|change history of this page]. | |
| 9 | 7 | |
| 10 | 8 | <b>Fossil sounds like a lot of reinvention of the wheel. |
| 11 | 9 | Why create your own DVCS when you could have reused mercurial?</b> |
| 12 | 10 | |
| 13 | -<blockquote> | |
| 11 | +<div class="indent"> | |
| 14 | 12 | I wrote fossil because none of the |
| 15 | 13 | other available DVCSes met my needs. If the other DVCSes do |
| 16 | 14 | meet your needs, then you might not need fossil. But they |
| 17 | 15 | don't meet mine, and so fossil is necessary for me. |
| 18 | 16 | |
| @@ -27,15 +25,15 @@ | ||
| 27 | 25 | a <a href="http://en.wikipedia.org/wiki/Chroot">chroot jail</a> </li> |
| 28 | 26 | <li> Simple, well-defined, |
| 29 | 27 | <a href="fileformat.wiki">enduring file format</a> </li> |
| 30 | 28 | <li> Integrated <a href="webui.wiki">web interface</a> </li> |
| 31 | 29 | </ol> |
| 32 | -</blockquote> | |
| 30 | +</div> | |
| 33 | 31 | |
| 34 | 32 | <b>Why should I use this rather than Trac?</b> |
| 35 | 33 | |
| 36 | -<blockquote> | |
| 34 | +<div class="indent"> | |
| 37 | 35 | <ol> |
| 38 | 36 | <li> Fossil is distributed. You can view and/or edit tickets, wiki, and |
| 39 | 37 | code while off network, then sync your changes later. With Trac, you |
| 40 | 38 | can only view and edit tickets and wiki while you are connected to |
| 41 | 39 | the server. </li> |
| @@ -44,15 +42,15 @@ | ||
| 44 | 42 | administrator.</li> |
| 45 | 43 | <li> Fossil integrates code versioning into the same repository with |
| 46 | 44 | wiki and tickets. There is nothing extra to add or install. |
| 47 | 45 | Fossil is an all-in-one turnkey solution. </li> |
| 48 | 46 | </ol> |
| 49 | -</blockquote> | |
| 47 | +</div> | |
| 50 | 48 | |
| 51 | 49 | <b>Love the concept here. Anyone using this for real work yet?</b> |
| 52 | 50 | |
| 53 | -<blockquote> | |
| 51 | +<div class="indent"> | |
| 54 | 52 | Fossil is <a href="https://fossil-scm.org/">self-hosting</a>. |
| 55 | 53 | In fact, this page was probably delivered |
| 56 | 54 | to your web-browser via a working fossil instance. The same virtual |
| 57 | 55 | machine that hosts https://fossil-scm.org/ |
| 58 | 56 | (a <a href="http://www.linode.com/">Linode 720</a>) |
| @@ -61,32 +59,32 @@ | ||
| 61 | 59 | <a href="http://www.sqlite.org/">SQLite</a> are hosted in a |
| 62 | 60 | fossil repository <a href="http://www.sqlite.org/docsrc/">here</a>, |
| 63 | 61 | for example. |
| 64 | 62 | Other projects are also adopting fossil. But fossil does not yet have |
| 65 | 63 | the massive user base of git or mercurial. |
| 66 | -</blockquote> | |
| 64 | +</div> | |
| 67 | 65 | |
| 68 | 66 | <b>Fossil looks like the bug tracker that would be in your |
| 69 | 67 | Linksys Router's administration screen.</b> |
| 70 | 68 | |
| 71 | -<blockquote> | |
| 69 | +<div class="indent"> | |
| 72 | 70 | I take a pragmatic approach to software: form follows function. |
| 73 | 71 | To me, it is more important to have a reliable, fast, efficient, |
| 74 | 72 | enduring, and simple DVCS than one that looks pretty. |
| 75 | 73 | |
| 76 | 74 | On the other hand, if you have patches that improve the appearance |
| 77 | 75 | of Fossil without seriously compromising its reliability, performance, |
| 78 | 76 | and/or maintainability, I will be happy to accept them. Fossil is |
| 79 | 77 | self-hosting. Send email to request a password that will let |
| 80 | 78 | you push to the main fossil repository. |
| 81 | -</blockquote> | |
| 79 | +</div> | |
| 82 | 80 | |
| 83 | 81 | <b>It would be useful to have a separate application that |
| 84 | 82 | keeps the bug-tracking database in a versioned file. That file can |
| 85 | 83 | then be pushed and pulled along with the rest repository.</b> |
| 86 | 84 | |
| 87 | -<blockquote> | |
| 85 | +<div class="indent"> | |
| 88 | 86 | Fossil already <u>does</u> push and pull bugs along with the files |
| 89 | 87 | in your repository. |
| 90 | 88 | But fossil does <u>not</u> track bugs as files in the source tree. |
| 91 | 89 | That approach to bug tracking was rejected for three reasons: |
| 92 | 90 | |
| @@ -107,39 +105,39 @@ | ||
| 107 | 105 | be permitted to create tickets. |
| 108 | 106 | </ol> |
| 109 | 107 | |
| 110 | 108 | These points are reiterated in the opening paragraphs of |
| 111 | 109 | the <a href="bugtheory.wiki">Bug-Tracking In Fossil</a> document. |
| 112 | -</blockquote> | |
| 110 | +</div> | |
| 113 | 111 | |
| 114 | 112 | <b>Fossil is already the name of a plan9 versioned |
| 115 | 113 | append-only filesystem.</b> |
| 116 | 114 | |
| 117 | -<blockquote> | |
| 115 | +<div class="indent"> | |
| 118 | 116 | I did not know that. Perhaps they selected the name for the same reason that |
| 119 | 117 | I did: because a repository with immutable artifacts preserves |
| 120 | 118 | an excellent fossil record of a long-running project. |
| 121 | -</blockquote> | |
| 119 | +</div> | |
| 122 | 120 | |
| 123 | 121 | <b>The idea of storing a repository in a binary blob like an |
| 124 | 122 | SQLite database terrifies me.</b> |
| 125 | 123 | |
| 126 | -<blockquote> | |
| 124 | +<div class="indent"> | |
| 127 | 125 | The use of SQLite to store the database is likely more stable and secure |
| 128 | 126 | than any other approach, due to the fact that SQLite is transactional. |
| 129 | 127 | Fossil also implements several internal |
| 130 | 128 | <a href="selfcheck.wiki">self-checks</a> to insure that no information |
| 131 | 129 | is ever lost. |
| 132 | -</blockquote> | |
| 130 | +</div> | |
| 133 | 131 | |
| 134 | 132 | |
| 135 | 133 | <b>I am dubious of the benefits of including wikis and bug trackers |
| 136 | 134 | directly in the VCS - either they are under-featured compared to full |
| 137 | 135 | software like Trac, or the VCS is massively bloated compared to |
| 138 | 136 | Subversion or Bazaar.</b> |
| 139 | 137 | |
| 140 | -<blockquote> | |
| 138 | +<div class="indent"> | |
| 141 | 139 | I have no doubt that Trac has many features that fossil lacks. But that |
| 142 | 140 | is not the point. Fossil has several key features that Trac lacks and that |
| 143 | 141 | I need: most notably the fact that |
| 144 | 142 | fossil supports disconnected operation. |
| 145 | 143 | |
| @@ -151,9 +149,6 @@ | ||
| 151 | 149 | by itself. And the self-contained fossil |
| 152 | 150 | executable is much less than 1MB in size. (Update 2015-01-12: Fossil has |
| 153 | 151 | grown in the years since the previous sentence was written but is still |
| 154 | 152 | much less than 2MB according to "size" when compiled using -Os on x64 Linux.) |
| 155 | 153 | Fossil is the very opposite of bloat. |
| 156 | -</blockquote> | |
| 157 | - | |
| 158 | - | |
| 159 | -</nowiki> | |
| 154 | +</div> | |
| 160 | 155 |
| --- www/qandc.wiki | |
| +++ www/qandc.wiki | |
| @@ -1,18 +1,16 @@ | |
| 1 | <title>Questions And Criticisms</title> |
| 2 | <nowiki> |
| 3 | <h1 align="center">Questions And Criticisms</h1> |
| 4 | |
| 5 | This page is a collection of real questions and criticisms that were |
| 6 | raised against Fossil early in its history (circa 2008). |
| 7 | This page is old and has not been kept up-to-date. See the |
| 8 | </nowiki>[/finfo?name=www/qandc.wiki|change history of this page]<nowiki>. |
| 9 | |
| 10 | <b>Fossil sounds like a lot of reinvention of the wheel. |
| 11 | Why create your own DVCS when you could have reused mercurial?</b> |
| 12 | |
| 13 | <blockquote> |
| 14 | I wrote fossil because none of the |
| 15 | other available DVCSes met my needs. If the other DVCSes do |
| 16 | meet your needs, then you might not need fossil. But they |
| 17 | don't meet mine, and so fossil is necessary for me. |
| 18 | |
| @@ -27,15 +25,15 @@ | |
| 27 | a <a href="http://en.wikipedia.org/wiki/Chroot">chroot jail</a> </li> |
| 28 | <li> Simple, well-defined, |
| 29 | <a href="fileformat.wiki">enduring file format</a> </li> |
| 30 | <li> Integrated <a href="webui.wiki">web interface</a> </li> |
| 31 | </ol> |
| 32 | </blockquote> |
| 33 | |
| 34 | <b>Why should I use this rather than Trac?</b> |
| 35 | |
| 36 | <blockquote> |
| 37 | <ol> |
| 38 | <li> Fossil is distributed. You can view and/or edit tickets, wiki, and |
| 39 | code while off network, then sync your changes later. With Trac, you |
| 40 | can only view and edit tickets and wiki while you are connected to |
| 41 | the server. </li> |
| @@ -44,15 +42,15 @@ | |
| 44 | administrator.</li> |
| 45 | <li> Fossil integrates code versioning into the same repository with |
| 46 | wiki and tickets. There is nothing extra to add or install. |
| 47 | Fossil is an all-in-one turnkey solution. </li> |
| 48 | </ol> |
| 49 | </blockquote> |
| 50 | |
| 51 | <b>Love the concept here. Anyone using this for real work yet?</b> |
| 52 | |
| 53 | <blockquote> |
| 54 | Fossil is <a href="https://fossil-scm.org/">self-hosting</a>. |
| 55 | In fact, this page was probably delivered |
| 56 | to your web-browser via a working fossil instance. The same virtual |
| 57 | machine that hosts https://fossil-scm.org/ |
| 58 | (a <a href="http://www.linode.com/">Linode 720</a>) |
| @@ -61,32 +59,32 @@ | |
| 61 | <a href="http://www.sqlite.org/">SQLite</a> are hosted in a |
| 62 | fossil repository <a href="http://www.sqlite.org/docsrc/">here</a>, |
| 63 | for example. |
| 64 | Other projects are also adopting fossil. But fossil does not yet have |
| 65 | the massive user base of git or mercurial. |
| 66 | </blockquote> |
| 67 | |
| 68 | <b>Fossil looks like the bug tracker that would be in your |
| 69 | Linksys Router's administration screen.</b> |
| 70 | |
| 71 | <blockquote> |
| 72 | I take a pragmatic approach to software: form follows function. |
| 73 | To me, it is more important to have a reliable, fast, efficient, |
| 74 | enduring, and simple DVCS than one that looks pretty. |
| 75 | |
| 76 | On the other hand, if you have patches that improve the appearance |
| 77 | of Fossil without seriously compromising its reliability, performance, |
| 78 | and/or maintainability, I will be happy to accept them. Fossil is |
| 79 | self-hosting. Send email to request a password that will let |
| 80 | you push to the main fossil repository. |
| 81 | </blockquote> |
| 82 | |
| 83 | <b>It would be useful to have a separate application that |
| 84 | keeps the bug-tracking database in a versioned file. That file can |
| 85 | then be pushed and pulled along with the rest repository.</b> |
| 86 | |
| 87 | <blockquote> |
| 88 | Fossil already <u>does</u> push and pull bugs along with the files |
| 89 | in your repository. |
| 90 | But fossil does <u>not</u> track bugs as files in the source tree. |
| 91 | That approach to bug tracking was rejected for three reasons: |
| 92 | |
| @@ -107,39 +105,39 @@ | |
| 107 | be permitted to create tickets. |
| 108 | </ol> |
| 109 | |
| 110 | These points are reiterated in the opening paragraphs of |
| 111 | the <a href="bugtheory.wiki">Bug-Tracking In Fossil</a> document. |
| 112 | </blockquote> |
| 113 | |
| 114 | <b>Fossil is already the name of a plan9 versioned |
| 115 | append-only filesystem.</b> |
| 116 | |
| 117 | <blockquote> |
| 118 | I did not know that. Perhaps they selected the name for the same reason that |
| 119 | I did: because a repository with immutable artifacts preserves |
| 120 | an excellent fossil record of a long-running project. |
| 121 | </blockquote> |
| 122 | |
| 123 | <b>The idea of storing a repository in a binary blob like an |
| 124 | SQLite database terrifies me.</b> |
| 125 | |
| 126 | <blockquote> |
| 127 | The use of SQLite to store the database is likely more stable and secure |
| 128 | than any other approach, due to the fact that SQLite is transactional. |
| 129 | Fossil also implements several internal |
| 130 | <a href="selfcheck.wiki">self-checks</a> to insure that no information |
| 131 | is ever lost. |
| 132 | </blockquote> |
| 133 | |
| 134 | |
| 135 | <b>I am dubious of the benefits of including wikis and bug trackers |
| 136 | directly in the VCS - either they are under-featured compared to full |
| 137 | software like Trac, or the VCS is massively bloated compared to |
| 138 | Subversion or Bazaar.</b> |
| 139 | |
| 140 | <blockquote> |
| 141 | I have no doubt that Trac has many features that fossil lacks. But that |
| 142 | is not the point. Fossil has several key features that Trac lacks and that |
| 143 | I need: most notably the fact that |
| 144 | fossil supports disconnected operation. |
| 145 | |
| @@ -151,9 +149,6 @@ | |
| 151 | by itself. And the self-contained fossil |
| 152 | executable is much less than 1MB in size. (Update 2015-01-12: Fossil has |
| 153 | grown in the years since the previous sentence was written but is still |
| 154 | much less than 2MB according to "size" when compiled using -Os on x64 Linux.) |
| 155 | Fossil is the very opposite of bloat. |
| 156 | </blockquote> |
| 157 | |
| 158 | |
| 159 | </nowiki> |
| 160 |
| --- www/qandc.wiki | |
| +++ www/qandc.wiki | |
| @@ -1,18 +1,16 @@ | |
| 1 | <title>Questions And Criticisms</title> |
| 2 | |
| 3 | This page is a collection of real questions and criticisms that were |
| 4 | raised against Fossil early in its history (circa 2008). |
| 5 | This page is old and has not been kept up-to-date. See the |
| 6 | [/finfo?name=www/qandc.wiki|change history of this page]. |
| 7 | |
| 8 | <b>Fossil sounds like a lot of reinvention of the wheel. |
| 9 | Why create your own DVCS when you could have reused mercurial?</b> |
| 10 | |
| 11 | <div class="indent"> |
| 12 | I wrote fossil because none of the |
| 13 | other available DVCSes met my needs. If the other DVCSes do |
| 14 | meet your needs, then you might not need fossil. But they |
| 15 | don't meet mine, and so fossil is necessary for me. |
| 16 | |
| @@ -27,15 +25,15 @@ | |
| 25 | a <a href="http://en.wikipedia.org/wiki/Chroot">chroot jail</a> </li> |
| 26 | <li> Simple, well-defined, |
| 27 | <a href="fileformat.wiki">enduring file format</a> </li> |
| 28 | <li> Integrated <a href="webui.wiki">web interface</a> </li> |
| 29 | </ol> |
| 30 | </div> |
| 31 | |
| 32 | <b>Why should I use this rather than Trac?</b> |
| 33 | |
| 34 | <div class="indent"> |
| 35 | <ol> |
| 36 | <li> Fossil is distributed. You can view and/or edit tickets, wiki, and |
| 37 | code while off network, then sync your changes later. With Trac, you |
| 38 | can only view and edit tickets and wiki while you are connected to |
| 39 | the server. </li> |
| @@ -44,15 +42,15 @@ | |
| 42 | administrator.</li> |
| 43 | <li> Fossil integrates code versioning into the same repository with |
| 44 | wiki and tickets. There is nothing extra to add or install. |
| 45 | Fossil is an all-in-one turnkey solution. </li> |
| 46 | </ol> |
| 47 | </div> |
| 48 | |
| 49 | <b>Love the concept here. Anyone using this for real work yet?</b> |
| 50 | |
| 51 | <div class="indent"> |
| 52 | Fossil is <a href="https://fossil-scm.org/">self-hosting</a>. |
| 53 | In fact, this page was probably delivered |
| 54 | to your web-browser via a working fossil instance. The same virtual |
| 55 | machine that hosts https://fossil-scm.org/ |
| 56 | (a <a href="http://www.linode.com/">Linode 720</a>) |
| @@ -61,32 +59,32 @@ | |
| 59 | <a href="http://www.sqlite.org/">SQLite</a> are hosted in a |
| 60 | fossil repository <a href="http://www.sqlite.org/docsrc/">here</a>, |
| 61 | for example. |
| 62 | Other projects are also adopting fossil. But fossil does not yet have |
| 63 | the massive user base of git or mercurial. |
| 64 | </div> |
| 65 | |
| 66 | <b>Fossil looks like the bug tracker that would be in your |
| 67 | Linksys Router's administration screen.</b> |
| 68 | |
| 69 | <div class="indent"> |
| 70 | I take a pragmatic approach to software: form follows function. |
| 71 | To me, it is more important to have a reliable, fast, efficient, |
| 72 | enduring, and simple DVCS than one that looks pretty. |
| 73 | |
| 74 | On the other hand, if you have patches that improve the appearance |
| 75 | of Fossil without seriously compromising its reliability, performance, |
| 76 | and/or maintainability, I will be happy to accept them. Fossil is |
| 77 | self-hosting. Send email to request a password that will let |
| 78 | you push to the main fossil repository. |
| 79 | </div> |
| 80 | |
| 81 | <b>It would be useful to have a separate application that |
| 82 | keeps the bug-tracking database in a versioned file. That file can |
| 83 | then be pushed and pulled along with the rest repository.</b> |
| 84 | |
| 85 | <div class="indent"> |
| 86 | Fossil already <u>does</u> push and pull bugs along with the files |
| 87 | in your repository. |
| 88 | But fossil does <u>not</u> track bugs as files in the source tree. |
| 89 | That approach to bug tracking was rejected for three reasons: |
| 90 | |
| @@ -107,39 +105,39 @@ | |
| 105 | be permitted to create tickets. |
| 106 | </ol> |
| 107 | |
| 108 | These points are reiterated in the opening paragraphs of |
| 109 | the <a href="bugtheory.wiki">Bug-Tracking In Fossil</a> document. |
| 110 | </div> |
| 111 | |
| 112 | <b>Fossil is already the name of a plan9 versioned |
| 113 | append-only filesystem.</b> |
| 114 | |
| 115 | <div class="indent"> |
| 116 | I did not know that. Perhaps they selected the name for the same reason that |
| 117 | I did: because a repository with immutable artifacts preserves |
| 118 | an excellent fossil record of a long-running project. |
| 119 | </div> |
| 120 | |
| 121 | <b>The idea of storing a repository in a binary blob like an |
| 122 | SQLite database terrifies me.</b> |
| 123 | |
| 124 | <div class="indent"> |
| 125 | The use of SQLite to store the database is likely more stable and secure |
| 126 | than any other approach, due to the fact that SQLite is transactional. |
| 127 | Fossil also implements several internal |
| 128 | <a href="selfcheck.wiki">self-checks</a> to insure that no information |
| 129 | is ever lost. |
| 130 | </div> |
| 131 | |
| 132 | |
| 133 | <b>I am dubious of the benefits of including wikis and bug trackers |
| 134 | directly in the VCS - either they are under-featured compared to full |
| 135 | software like Trac, or the VCS is massively bloated compared to |
| 136 | Subversion or Bazaar.</b> |
| 137 | |
| 138 | <div class="indent"> |
| 139 | I have no doubt that Trac has many features that fossil lacks. But that |
| 140 | is not the point. Fossil has several key features that Trac lacks and that |
| 141 | I need: most notably the fact that |
| 142 | fossil supports disconnected operation. |
| 143 | |
| @@ -151,9 +149,6 @@ | |
| 149 | by itself. And the self-contained fossil |
| 150 | executable is much less than 1MB in size. (Update 2015-01-12: Fossil has |
| 151 | grown in the years since the previous sentence was written but is still |
| 152 | much less than 2MB according to "size" when compiled using -Os on x64 Linux.) |
| 153 | Fossil is the very opposite of bloat. |
| 154 | </div> |
| 155 |
+119
-152
| --- www/quickstart.wiki | ||
| +++ www/quickstart.wiki | ||
| @@ -1,7 +1,6 @@ | ||
| 1 | 1 | <title>Fossil Quick Start Guide</title> |
| 2 | -<h1 align="center">Fossil Quick Start</h1> | |
| 3 | 2 | |
| 4 | 3 | 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 |
| 5 | 4 | and painlessly. |
| 6 | 5 | |
| 7 | 6 | <h2 id="install">Installing</h2> |
| @@ -14,16 +13,13 @@ | ||
| 14 | 13 | Install Fossil by putting the fossil binary |
| 15 | 14 | someplace on your $PATH. |
| 16 | 15 | |
| 17 | 16 | You can test that Fossil is present and working like this: |
| 18 | 17 | |
| 19 | -<blockquote> | |
| 20 | -<b> | |
| 21 | -fossil version<br> | |
| 22 | -<tt>This is fossil version 2.13 [309af345ab] 2020-09-28 04:02:55 UTC</tt><br> | |
| 23 | -</b> | |
| 24 | -</blockquote> | |
| 18 | +<pre><b>fossil version | |
| 19 | +This is fossil version 2.13 [309af345ab] 2020-09-28 04:02:55 UTC | |
| 20 | +</b></pre> | |
| 25 | 21 | |
| 26 | 22 | <h2 id="workflow" name="fslclone">General Work Flow</h2> |
| 27 | 23 | |
| 28 | 24 | Fossil works with repository files (a database in a single file with the project's |
| 29 | 25 | complete history) and with checked-out local trees (the working directory |
| @@ -48,13 +44,12 @@ | ||
| 48 | 44 | <h2 id="new">Starting A New Project</h2> |
| 49 | 45 | |
| 50 | 46 | To start a new project with fossil create a new empty repository |
| 51 | 47 | this way: ([/help/init | more info]) |
| 52 | 48 | |
| 53 | -<blockquote> | |
| 54 | -<b>fossil init </b><i> repository-filename</i> | |
| 55 | -</blockquote> | |
| 49 | +<pre><b>fossil init</b> <i>repository-filename</i> | |
| 50 | +</pre> | |
| 56 | 51 | |
| 57 | 52 | You can name the database anything you like, and you can place it anywhere in the filesystem. |
| 58 | 53 | The <tt>.fossil</tt> extension is traditional but only required if you are going to use the |
| 59 | 54 | <tt>[/help/server | fossil server DIRECTORY]</tt> feature.” |
| 60 | 55 | |
| @@ -66,45 +61,37 @@ | ||
| 66 | 61 | repository. Making a local copy of a remote repository is called |
| 67 | 62 | "cloning". |
| 68 | 63 | |
| 69 | 64 | Clone a remote repository as follows: ([/help/clone | more info]) |
| 70 | 65 | |
| 71 | -<blockquote> | |
| 72 | -<b>fossil clone</b> <i>URL repository-filename</i> | |
| 73 | -</blockquote> | |
| 66 | +<pre><b>fossil clone</b> <i>URL repository-filename</i> | |
| 67 | +</pre> | |
| 74 | 68 | |
| 75 | 69 | The <i>URL</i> specifies the fossil repository |
| 76 | 70 | you want to clone. The <i>repository-filename</i> is the new local |
| 77 | 71 | filename into which the cloned repository will be written. For |
| 78 | 72 | example, to clone the source code of Fossil itself: |
| 79 | 73 | |
| 80 | -<blockquote> | |
| 81 | -<b>fossil clone https://fossil-scm.org/ myclone.fossil</b> | |
| 82 | -</blockquote> | |
| 74 | +<pre><b>fossil clone https://fossil-scm.org/ myclone.fossil</b></pre> | |
| 83 | 75 | |
| 84 | 76 | If your logged-in username is 'exampleuser', you should see output something like this: |
| 85 | 77 | |
| 86 | -<blockquote> | |
| 87 | -<b><tt> | |
| 88 | - Round-trips: 8 Artifacts sent: 0 received: 39421<br> | |
| 89 | - Clone done, sent: 2424 received: 42965725 ip: 10.10.10.0<br> | |
| 90 | - Rebuilding repository meta-data...<br> | |
| 91 | - 100% complete...<br> | |
| 92 | - Extra delta compression... <br> | |
| 93 | - Vacuuming the database... <br> | |
| 94 | - project-id: 94259BB9F186226D80E49D1FA2DB29F935CCA0333<br> | |
| 95 | - server-id: 016595e9043054038a9ea9bc526d7f33f7ac0e42<br> | |
| 96 | - admin-user: exampleuser (password is "yoWgDR42iv")><br> | |
| 97 | -</tt></b> | |
| 98 | -</blockquote> | |
| 78 | +<pre><b>Round-trips: 8 Artifacts sent: 0 received: 39421 | |
| 79 | +Clone done, sent: 2424 received: 42965725 ip: 10.10.10.0 | |
| 80 | +Rebuilding repository meta-data... | |
| 81 | +100% complete... | |
| 82 | +Extra delta compression... | |
| 83 | +Vacuuming the database... | |
| 84 | +project-id: 94259BB9F186226D80E49D1FA2DB29F935CCA0333 | |
| 85 | +server-id: 016595e9043054038a9ea9bc526d7f33f7ac0e42 | |
| 86 | +admin-user: exampleuser (password is "yoWgDR42iv")> | |
| 87 | +</b></pre> | |
| 99 | 88 | |
| 100 | 89 | If the remote repository requires a login, include a |
| 101 | 90 | userid in the URL like this: |
| 102 | 91 | |
| 103 | -<blockquote> | |
| 104 | -<b>fossil clone https://</b><i>remoteuserid</i><b>@www.example.org/ myclone.fossil</b> | |
| 105 | -</blockquote> | |
| 92 | +<pre><b>fossil clone https://</b><i>remoteuserid</i><b>@www.example.org/ myclone.fossil</b></pre> | |
| 106 | 93 | |
| 107 | 94 | You will be prompted separately for the password. |
| 108 | 95 | Use [https://en.wikipedia.org/wiki/Percent-encoding#Percent-encoding_reserved_characters|"%HH"] escapes for special characters in the userid. |
| 109 | 96 | For example "/" would be replaced by "%2F" meaning that a userid of "Projects/Budget" would become "Projects%2FBudget") |
| 110 | 97 | |
| @@ -143,43 +130,38 @@ | ||
| 143 | 130 | To work on a project in fossil, you need to check out a local |
| 144 | 131 | copy of the source tree. Create the directory you want to be |
| 145 | 132 | the root of your tree and cd into that directory. Then |
| 146 | 133 | do this: ([/help/open | more info]) |
| 147 | 134 | |
| 148 | -<blockquote> | |
| 149 | -<b>fossil open </b><i> repository-filename</i> | |
| 150 | -</blockquote> | |
| 135 | +<pre><b>fossil open</b> <i>repository-filename</i></pre> | |
| 151 | 136 | |
| 152 | 137 | for example: |
| 153 | 138 | |
| 154 | -<blockquote> | |
| 155 | -<b><tt> | |
| 156 | - fossil open ../myclone.fossil<br> | |
| 157 | - BUILD.txt<br> | |
| 158 | - COPYRIGHT-BSD2.txt<br> | |
| 159 | - README.md<br> | |
| 160 | - ︙<br> | |
| 161 | -</tt></b> | |
| 162 | -</blockquote> | |
| 139 | +<pre><b>fossil open ../myclone.fossil | |
| 140 | + BUILD.txt | |
| 141 | + COPYRIGHT-BSD2.txt | |
| 142 | + README.md | |
| 143 | + ︙ | |
| 144 | +</tt></b></pre> | |
| 163 | 145 | |
| 164 | 146 | (or "fossil open ..\myclone.fossil" on Windows). |
| 165 | 147 | |
| 166 | 148 | This leaves you with the newest version of the tree |
| 167 | 149 | checked out. |
| 168 | 150 | From anywhere underneath the root of your local tree, you |
| 169 | 151 | can type commands like the following to find out the status of |
| 170 | 152 | your local tree: |
| 171 | 153 | |
| 172 | -<blockquote> | |
| 173 | -<b>[/help/info | fossil info]</b><br> | |
| 174 | -<b>[/help/status | fossil status]</b><br> | |
| 175 | -<b>[/help/changes | fossil changes]</b><br> | |
| 176 | -<b>[/help/diff | fossil diff]</b><br> | |
| 177 | -<b>[/help/timeline | fossil timeline]</b><br> | |
| 178 | -<b>[/help/ls | fossil ls]</b><br> | |
| 179 | -<b>[/help/branch | fossil branch]</b><br> | |
| 180 | -</blockquote> | |
| 154 | +<pre> | |
| 155 | +<b>[/help/info | fossil info]</b> | |
| 156 | +<b>[/help/status | fossil status]</b> | |
| 157 | +<b>[/help/changes | fossil changes]</b> | |
| 158 | +<b>[/help/diff | fossil diff]</b> | |
| 159 | +<b>[/help/timeline | fossil timeline]</b> | |
| 160 | +<b>[/help/ls | fossil ls]</b> | |
| 161 | +<b>[/help/branch | fossil branch]</b> | |
| 162 | +</pre> | |
| 181 | 163 | |
| 182 | 164 | If you created a new repository using "fossil init" some commands will not |
| 183 | 165 | produce much output. |
| 184 | 166 | |
| 185 | 167 | Note that Fossil allows you to make multiple check-outs in |
| @@ -188,14 +170,14 @@ | ||
| 188 | 170 | the same time without having to generate extra clones. |
| 189 | 171 | |
| 190 | 172 | To switch a checkout between different versions and branches, |
| 191 | 173 | use:< |
| 192 | 174 | |
| 193 | -<blockquote> | |
| 194 | -<b>[/help/update | fossil update]</b><br> | |
| 195 | -<b>[/help/checkout | fossil checkout]</b><br> | |
| 196 | -</blockquote> | |
| 175 | +<pre> | |
| 176 | +<b>[/help/update | fossil update]</b> | |
| 177 | +<b>[/help/checkout | fossil checkout]</b> | |
| 178 | +</pre> | |
| 197 | 179 | |
| 198 | 180 | [/help/update | update] honors the "autosync" option and |
| 199 | 181 | does a "soft" switch, merging any local changes into the target |
| 200 | 182 | version, whereas [/help/checkout | checkout] does not |
| 201 | 183 | automatically sync and does a "hard" switch, overwriting local |
| @@ -204,48 +186,39 @@ | ||
| 204 | 186 | <h2 id="changes">Making and Committing Changes</h2> |
| 205 | 187 | |
| 206 | 188 | To add new files to your project or remove existing ones, use these |
| 207 | 189 | commands: |
| 208 | 190 | |
| 209 | -<blockquote> | |
| 210 | -<b>[/help/add | fossil add]</b> <i>file...</i><br> | |
| 211 | -<b>[/help/rm | fossil rm]</b> <i>file...</i><br> | |
| 212 | -<b>[/help/addremove | fossil addremove]</b> <i>file...</i><br> | |
| 213 | -</blockquote> | |
| 191 | +<pre> | |
| 192 | +<b>[/help/add | fossil add]</b> <i>file...</i> | |
| 193 | +<b>[/help/rm | fossil rm]</b> <i>file...</i> | |
| 194 | +<b>[/help/addremove | fossil addremove]</b> <i>file...</i> | |
| 195 | +</pre> | |
| 214 | 196 | |
| 215 | 197 | The command: |
| 216 | 198 | |
| 217 | -<blockquote> | |
| 218 | -<b> | |
| 219 | - [/help/changes | fossil changes]</b> | |
| 220 | -</blockquote> | |
| 199 | +<pre><b>[/help/changes | fossil changes]</b></pre> | |
| 221 | 200 | |
| 222 | 201 | lists files that have changed since the last commit to the repository. For |
| 223 | 202 | example, if you edit the file "README.md": |
| 224 | 203 | |
| 225 | -<blockquote> | |
| 226 | -<b> | |
| 227 | - fossil changes<br> | |
| 228 | - EDITED README.md | |
| 229 | -</b> | |
| 230 | -</blockquote> | |
| 204 | +<pre><b>fossil changes | |
| 205 | +EDITED README.md | |
| 206 | +</b></pre> | |
| 231 | 207 | |
| 232 | 208 | To see exactly what change was made you can use the command |
| 233 | 209 | <b>[/help/diff | fossil diff]</b>: |
| 234 | 210 | |
| 235 | -<blockquote> | |
| 236 | -<b> | |
| 237 | - fossil diff <br><tt> | |
| 238 | - Index: README.md<br> | |
| 239 | - ============================================================<br> | |
| 240 | - --- README.md<br> | |
| 241 | - +++ README.md<br> | |
| 242 | - @@ -1,5 +1,6 @@<br> | |
| 243 | - +Made some changes to the project<br> | |
| 244 | - # Original text<br> | |
| 245 | - </tt></b> | |
| 246 | -</blockquote> | |
| 211 | +<pre><b>fossil diff | |
| 212 | +Index: README.md | |
| 213 | +============================================================ | |
| 214 | +--- README.md | |
| ++++ README.md | ||
| 215 | +@@ -1,5 +1,6 @@ | |
| 216 | ++Made some changes to the project | |
| 217 | +# Original text | |
| 218 | +</b></pre> | |
| 247 | 219 | |
| 248 | 220 | "fossil diff" shows the difference between your tree on disk now and as |
| 249 | 221 | the tree was when you last committed changes. If you haven't committed |
| 250 | 222 | yet, then it shows the difference relative to the tip-of-trunk commit in |
| 251 | 223 | the repository, being what you get when you "fossil open" a repository |
| @@ -252,47 +225,43 @@ | ||
| 252 | 225 | without specifying a version, populating the working directory. |
| 253 | 226 | |
| 254 | 227 | To see the most recent changes made to the repository by other users, use "fossil timeline" to |
| 255 | 228 | find out the most recent commit, and then "fossil diff" between that commit and the |
| 256 | 229 | current tree: |
| 257 | -<blockquote> | |
| 258 | -<b> | |
| 259 | - fossil timeline <br><tt> | |
| 260 | - === 2021-03-28 === <br> | |
| 261 | - 03:18:54 [ad75dfa4a0] *CURRENT* Added details to frobnicate command (user: user-one tags: trunk) <br> | |
| 262 | - === 2021-03-27 === <br> | |
| 263 | - 23:58:05 [ab975c6632] Update README.md. (user: user-two tags: trunk) <br> | |
| 264 | - ⋮ <br> | |
| 265 | - </tt><br> | |
| 266 | - fossil diff --from current --to ab975c6632 <br><tt> | |
| 267 | - Index: frobnicate.c<br> | |
| 268 | - ============================================================<br> | |
| 269 | - --- frobnicate.c<br> | |
| 270 | - +++ frobnicate.c<br> | |
| 271 | - @@ -1,10 +1,11 @@<br> | |
| 272 | - +/* made a change to the source file */<br> | |
| 273 | - # Original text<br> | |
| 274 | -</tt></b> | |
| 275 | -</blockquote> | |
| 230 | + | |
| 231 | +<pre><b>fossil timeline | |
| 232 | +=== 2021-03-28 === | |
| 233 | +03:18:54 [ad75dfa4a0] *CURRENT* Added details to frobnicate command (user: user-one tags: trunk) | |
| 234 | +=== 2021-03-27 === | |
| 235 | +23:58:05 [ab975c6632] Update README.md. (user: user-two tags: trunk) | |
| 236 | + ⋮ | |
| 237 | + | |
| 238 | +fossil diff --from current --to ab975c6632 | |
| 239 | +Index: frobnicate.c | |
| 240 | +============================================================ | |
| 241 | +--- frobnicate.c | |
| ++++ frobnicate.c | ||
| 242 | +@@ -1,10 +1,11 @@ | |
| 243 | ++/* made a change to the source file */ | |
| 244 | +# Original text | |
| 245 | +</b></pre> | |
| 276 | 246 | |
| 277 | 247 | "current" is an alias for the checkout version, so the command |
| 278 | 248 | "fossil diff --from ad75dfa4a0 --to ab975c6632" gives identical results. |
| 279 | 249 | |
| 280 | 250 | To commit your changes to a local-only repository: |
| 281 | -<blockquote> | |
| 282 | -<b> | |
| 283 | -fossil commit </b><i>(... Fossil will start your editor, if defined)</i><b><br><tt> | |
| 284 | -# Enter a commit message for this check-in. Lines beginning with # are ignored.<br> | |
| 285 | -#<br> | |
| 286 | -# user: exampleuser<br> | |
| 287 | -# tags: trunk<br> | |
| 288 | -#<br> | |
| 289 | -# EDITED README.md<br> | |
| 290 | -Edited file to add description of code changes<br> | |
| 291 | -New_Version: 7b9a416ced4a69a60589dde1aedd1a30fde8eec3528d265dbeed5135530440ab<br> | |
| 292 | -</tt></b> | |
| 293 | -</blockquote> | |
| 251 | + | |
| 252 | +<pre><b>fossil commit</b> <i>(... Fossil will start your editor, if defined)</i><b> | |
| 253 | +# Enter a commit message for this check-in. Lines beginning with # are ignored. | |
| 254 | +# | |
| 255 | +# user: exampleuser | |
| 256 | +# tags: trunk | |
| 257 | +# | |
| 258 | +# EDITED README.md | |
| 259 | +Edited file to add description of code changes | |
| 260 | +New_Version: 7b9a416ced4a69a60589dde1aedd1a30fde8eec3528d265dbeed5135530440ab | |
| 261 | +</b></pre> | |
| 294 | 262 | |
| 295 | 263 | You will be prompted for check-in comments using whatever editor |
| 296 | 264 | is specified by your VISUAL or EDITOR environment variable. If none is |
| 297 | 265 | specified Fossil uses line-editing in the terminal. |
| 298 | 266 | |
| @@ -333,13 +302,13 @@ | ||
| 333 | 302 | project or create a new project of your own, you usually want to do some |
| 334 | 303 | local configuration. This is easily accomplished using the web-server |
| 335 | 304 | that is built into fossil. Start the fossil web server like this: |
| 336 | 305 | ([/help/ui | more info]) |
| 337 | 306 | |
| 338 | -<blockquote> | |
| 339 | -<b>fossil ui </b><i> repository-filename</i> | |
| 340 | -</blockquote> | |
| 307 | +<pre> | |
| 308 | +<b>fossil ui</b> <i>repository-filename</i> | |
| 309 | +</pre> | |
| 341 | 310 | |
| 342 | 311 | You can omit the <i>repository-filename</i> from the command above |
| 343 | 312 | if you are inside a checked-out local tree. |
| 344 | 313 | |
| 345 | 314 | This starts a web server then automatically launches your |
| @@ -346,13 +315,13 @@ | ||
| 346 | 315 | web browser and makes it point to this web server. If your system |
| 347 | 316 | has an unusual configuration, fossil might not be able to figure out |
| 348 | 317 | how to start your web browser. In that case, first tell fossil |
| 349 | 318 | where to find your web browser using a command like this: |
| 350 | 319 | |
| 351 | -<blockquote> | |
| 352 | -<b>fossil setting web-browser </b><i> path-to-web-browser</i> | |
| 353 | -</blockquote> | |
| 320 | +<pre> | |
| 321 | +<b>fossil setting web-browser</b> <i>path-to-web-browser</i> | |
| 322 | +</pre> | |
| 354 | 323 | |
| 355 | 324 | By default, fossil does not require a login for HTTP connections |
| 356 | 325 | coming in from the IP loopback address 127.0.0.1. You can, and perhaps |
| 357 | 326 | should, change this after you create a few users. |
| 358 | 327 | |
| @@ -364,34 +333,34 @@ | ||
| 364 | 333 | When [./concepts.wiki#workflow|autosync] is turned off, |
| 365 | 334 | the changes you [/help/commit | commit] are only |
| 366 | 335 | on your local repository. |
| 367 | 336 | To share those changes with other repositories, do: |
| 368 | 337 | |
| 369 | -<blockquote> | |
| 338 | +<pre> | |
| 370 | 339 | <b>[/help/push | fossil push]</b> <i>URL</i> |
| 371 | -</blockquote> | |
| 340 | +</pre> | |
| 372 | 341 | |
| 373 | 342 | Where <i>URL</i> is the http: URL of the server repository you |
| 374 | 343 | want to share your changes with. If you omit the <i>URL</i> argument, |
| 375 | 344 | fossil will use whatever server you most recently synced with. |
| 376 | 345 | |
| 377 | 346 | The [/help/push | push] command only sends your changes to others. To |
| 378 | 347 | Receive changes from others, use [/help/pull | pull]. Or go both ways at |
| 379 | 348 | once using [/help/sync | sync]: |
| 380 | 349 | |
| 381 | -<blockquote> | |
| 382 | -<b>[/help/pull | fossil pull]</b> <i>URL</i><br> | |
| 350 | +<pre> | |
| 351 | +<b>[/help/pull | fossil pull]</b> <i>URL</i> | |
| 383 | 352 | <b>[/help/sync | fossil sync]</b> <i>URL</i> |
| 384 | -</blockquote> | |
| 353 | +</pre> | |
| 385 | 354 | |
| 386 | 355 | When you pull in changes from others, they go into your repository, |
| 387 | 356 | not into your checked-out local tree. To get the changes into your |
| 388 | 357 | local tree, use [/help/update | update]: |
| 389 | 358 | |
| 390 | -<blockquote> | |
| 359 | +<pre> | |
| 391 | 360 | <b>[/help/update | fossil update]</b> <i>VERSION</i> |
| 392 | -</blockquote> | |
| 361 | +</pre> | |
| 393 | 362 | |
| 394 | 363 | The <i>VERSION</i> can be the name of a branch or tag or any |
| 395 | 364 | abbreviation to the 40-character |
| 396 | 365 | artifact identifier for a particular check-in, or it can be a |
| 397 | 366 | date/time stamp. ([./checkin_names.wiki | more info]) |
| @@ -404,13 +373,13 @@ | ||
| 404 | 373 | when you run [/help/update|update] and a [/help/push|push] happens |
| 405 | 374 | automatically after you [/help/commit|commit]. So in normal practice, |
| 406 | 375 | the push, pull, and sync commands are rarely used. But it is important |
| 407 | 376 | to know about them, all the same. |
| 408 | 377 | |
| 409 | -<blockquote> | |
| 378 | +<pre> | |
| 410 | 379 | <b>[/help/checkout | fossil checkout]</b> <i>VERSION</i> |
| 411 | -</blockquote> | |
| 380 | +</pre> | |
| 412 | 381 | |
| 413 | 382 | Is similar to update except that it does not honor the autosync |
| 414 | 383 | setting, nor does it merge in local changes - it prefers to overwrite |
| 415 | 384 | them and fails if local changes exist unless the <tt>--force</tt> |
| 416 | 385 | flag is used. |
| @@ -428,16 +397,16 @@ | ||
| 428 | 397 | [/help/update | update] to the branch you want to merge into. |
| 429 | 398 | Then do a [/help/merge|merge] of the other branch that you want to incorporate |
| 430 | 399 | the changes from. For example, to merge "featureX" changes into "trunk" |
| 431 | 400 | do this: |
| 432 | 401 | |
| 433 | -<blockquote> | |
| 434 | -<b>fossil [/help/update|update] trunk</b><br> | |
| 435 | -<b>fossil [/help/merge|merge] featureX</b><br> | |
| 436 | -<i># make sure the merge didn't break anything...</i><br> | |
| 402 | +<pre> | |
| 403 | +<b>fossil [/help/update|update] trunk</b> | |
| 404 | +<b>fossil [/help/merge|merge] featureX</b> | |
| 405 | +<i># make sure the merge didn't break anything...</i> | |
| 437 | 406 | <b>fossil [/help/commit|commit] |
| 438 | -</blockquote> | |
| 407 | +</pre> | |
| 439 | 408 | |
| 440 | 409 | The argument to the [/help/merge|merge] command can be any of the |
| 441 | 410 | version identifier forms that work for [/help/update|update]. |
| 442 | 411 | ([./checkin_names.wiki|more info].) |
| 443 | 412 | The merge command has options to cherry-pick individual |
| @@ -460,13 +429,13 @@ | ||
| 460 | 429 | merge. |
| 461 | 430 | |
| 462 | 431 | If a merge or update doesn't work out (perhaps something breaks or |
| 463 | 432 | there are many merge conflicts) then you back up using: |
| 464 | 433 | |
| 465 | -<blockquote> | |
| 434 | +<pre> | |
| 466 | 435 | <b>[/help/undo | fossil undo]</b> |
| 467 | -</blockquote> | |
| 436 | +</pre> | |
| 468 | 437 | |
| 469 | 438 | This will back out the changes that the merge or update made to the |
| 470 | 439 | working checkout. There is also a [/help/redo|redo] command if you undo by |
| 471 | 440 | mistake. Undo and redo only work for changes that have |
| 472 | 441 | not yet been checked in using commit and there is only a single |
| @@ -476,14 +445,14 @@ | ||
| 476 | 445 | <h2 id="server">Setting Up A Server</h2> |
| 477 | 446 | |
| 478 | 447 | Fossil can act as a stand-alone web server using one of these |
| 479 | 448 | commands: |
| 480 | 449 | |
| 481 | -<blockquote> | |
| 482 | -<b>[/help/server | fossil server]</b> <i>repository-filename</i><br> | |
| 450 | +<pre> | |
| 451 | +<b>[/help/server | fossil server]</b> <i>repository-filename</i> | |
| 483 | 452 | <b>[/help/ui | fossil ui]</b> <i>repository-filename</i> |
| 484 | -</blockquote> | |
| 453 | +</pre> | |
| 485 | 454 | |
| 486 | 455 | The <i>repository-filename</i> can be omitted when these commands |
| 487 | 456 | are run from within an open check-out, which is a particularly useful |
| 488 | 457 | shortcut with the <b>fossil ui</b> command. |
| 489 | 458 | |
| @@ -527,44 +496,44 @@ | ||
| 527 | 496 | an HTTP proxy to reach the internet, then you can configure the proxy |
| 528 | 497 | in three different ways. You can tell fossil about your proxy using |
| 529 | 498 | a command-line option on commands that use the network, |
| 530 | 499 | <b>sync</b>, <b>clone</b>, <b>push</b>, and <b>pull</b>. |
| 531 | 500 | |
| 532 | -<blockquote> | |
| 533 | -<b>fossil clone </b><i>URL</i> <b>--proxy</b> <i>Proxy-URL</i> | |
| 534 | -</blockquote> | |
| 501 | +<pre> | |
| 502 | +<b>fossil clone </b><i>URL</i> <b>--proxy</b> <i>Proxy-URL</i> | |
| 503 | +</pre> | |
| 535 | 504 | |
| 536 | 505 | It is annoying to have to type in the proxy URL every time you |
| 537 | 506 | sync your project, though, so you can make the proxy configuration |
| 538 | 507 | persistent using the [/help/setting | setting] command: |
| 539 | 508 | |
| 540 | -<blockquote> | |
| 509 | +<pre> | |
| 541 | 510 | <b>fossil setting proxy </b><i>Proxy-URL</i> |
| 542 | -</blockquote> | |
| 511 | +</pre> | |
| 543 | 512 | |
| 544 | 513 | Or, you can set the "<b>http_proxy</b>" environment variable: |
| 545 | 514 | |
| 546 | -<blockquote> | |
| 515 | +<pre> | |
| 547 | 516 | <b>export http_proxy=</b><i>Proxy-URL</i> |
| 548 | -</blockquote> | |
| 517 | +</pre> | |
| 549 | 518 | |
| 550 | 519 | To stop using the proxy, do: |
| 551 | 520 | |
| 552 | -<blockquote> | |
| 521 | +<pre> | |
| 553 | 522 | <b>fossil setting proxy off</b> |
| 554 | -</blockquote> | |
| 523 | +</pre> | |
| 555 | 524 | |
| 556 | 525 | Or unset the environment variable. The fossil setting for the |
| 557 | 526 | HTTP proxy takes precedence over the environment variable and the |
| 558 | 527 | command-line option overrides both. If you have a persistent |
| 559 | 528 | proxy setting that you want to override for a one-time sync, that |
| 560 | 529 | is easily done on the command-line. For example, to sync with |
| 561 | 530 | a co-worker's repository on your LAN, you might type: |
| 562 | 531 | |
| 563 | -<blockquote> | |
| 532 | +<pre> | |
| 564 | 533 | <b>fossil sync http://192.168.1.36:8080/ --proxy off</b> |
| 565 | -</blockquote> | |
| 534 | +</pre> | |
| 566 | 535 | |
| 567 | 536 | <h2 id="links">Other Resources</h2> |
| 568 | 537 | |
| 569 | 538 | <ul> |
| 570 | 539 | <li> <a href="./gitusers.md">Hints For Users With Prior Git Experience</a> |
| 571 | 540 |
| --- www/quickstart.wiki | |
| +++ www/quickstart.wiki | |
| @@ -1,7 +1,6 @@ | |
| 1 | <title>Fossil Quick Start Guide</title> |
| 2 | <h1 align="center">Fossil Quick Start</h1> |
| 3 | |
| 4 | 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 |
| 5 | and painlessly. |
| 6 | |
| 7 | <h2 id="install">Installing</h2> |
| @@ -14,16 +13,13 @@ | |
| 14 | Install Fossil by putting the fossil binary |
| 15 | someplace on your $PATH. |
| 16 | |
| 17 | You can test that Fossil is present and working like this: |
| 18 | |
| 19 | <blockquote> |
| 20 | <b> |
| 21 | fossil version<br> |
| 22 | <tt>This is fossil version 2.13 [309af345ab] 2020-09-28 04:02:55 UTC</tt><br> |
| 23 | </b> |
| 24 | </blockquote> |
| 25 | |
| 26 | <h2 id="workflow" name="fslclone">General Work Flow</h2> |
| 27 | |
| 28 | Fossil works with repository files (a database in a single file with the project's |
| 29 | complete history) and with checked-out local trees (the working directory |
| @@ -48,13 +44,12 @@ | |
| 48 | <h2 id="new">Starting A New Project</h2> |
| 49 | |
| 50 | To start a new project with fossil create a new empty repository |
| 51 | this way: ([/help/init | more info]) |
| 52 | |
| 53 | <blockquote> |
| 54 | <b>fossil init </b><i> repository-filename</i> |
| 55 | </blockquote> |
| 56 | |
| 57 | You can name the database anything you like, and you can place it anywhere in the filesystem. |
| 58 | The <tt>.fossil</tt> extension is traditional but only required if you are going to use the |
| 59 | <tt>[/help/server | fossil server DIRECTORY]</tt> feature.” |
| 60 | |
| @@ -66,45 +61,37 @@ | |
| 66 | repository. Making a local copy of a remote repository is called |
| 67 | "cloning". |
| 68 | |
| 69 | Clone a remote repository as follows: ([/help/clone | more info]) |
| 70 | |
| 71 | <blockquote> |
| 72 | <b>fossil clone</b> <i>URL repository-filename</i> |
| 73 | </blockquote> |
| 74 | |
| 75 | The <i>URL</i> specifies the fossil repository |
| 76 | you want to clone. The <i>repository-filename</i> is the new local |
| 77 | filename into which the cloned repository will be written. For |
| 78 | example, to clone the source code of Fossil itself: |
| 79 | |
| 80 | <blockquote> |
| 81 | <b>fossil clone https://fossil-scm.org/ myclone.fossil</b> |
| 82 | </blockquote> |
| 83 | |
| 84 | If your logged-in username is 'exampleuser', you should see output something like this: |
| 85 | |
| 86 | <blockquote> |
| 87 | <b><tt> |
| 88 | Round-trips: 8 Artifacts sent: 0 received: 39421<br> |
| 89 | Clone done, sent: 2424 received: 42965725 ip: 10.10.10.0<br> |
| 90 | Rebuilding repository meta-data...<br> |
| 91 | 100% complete...<br> |
| 92 | Extra delta compression... <br> |
| 93 | Vacuuming the database... <br> |
| 94 | project-id: 94259BB9F186226D80E49D1FA2DB29F935CCA0333<br> |
| 95 | server-id: 016595e9043054038a9ea9bc526d7f33f7ac0e42<br> |
| 96 | admin-user: exampleuser (password is "yoWgDR42iv")><br> |
| 97 | </tt></b> |
| 98 | </blockquote> |
| 99 | |
| 100 | If the remote repository requires a login, include a |
| 101 | userid in the URL like this: |
| 102 | |
| 103 | <blockquote> |
| 104 | <b>fossil clone https://</b><i>remoteuserid</i><b>@www.example.org/ myclone.fossil</b> |
| 105 | </blockquote> |
| 106 | |
| 107 | You will be prompted separately for the password. |
| 108 | Use [https://en.wikipedia.org/wiki/Percent-encoding#Percent-encoding_reserved_characters|"%HH"] escapes for special characters in the userid. |
| 109 | For example "/" would be replaced by "%2F" meaning that a userid of "Projects/Budget" would become "Projects%2FBudget") |
| 110 | |
| @@ -143,43 +130,38 @@ | |
| 143 | To work on a project in fossil, you need to check out a local |
| 144 | copy of the source tree. Create the directory you want to be |
| 145 | the root of your tree and cd into that directory. Then |
| 146 | do this: ([/help/open | more info]) |
| 147 | |
| 148 | <blockquote> |
| 149 | <b>fossil open </b><i> repository-filename</i> |
| 150 | </blockquote> |
| 151 | |
| 152 | for example: |
| 153 | |
| 154 | <blockquote> |
| 155 | <b><tt> |
| 156 | fossil open ../myclone.fossil<br> |
| 157 | BUILD.txt<br> |
| 158 | COPYRIGHT-BSD2.txt<br> |
| 159 | README.md<br> |
| 160 | ︙<br> |
| 161 | </tt></b> |
| 162 | </blockquote> |
| 163 | |
| 164 | (or "fossil open ..\myclone.fossil" on Windows). |
| 165 | |
| 166 | This leaves you with the newest version of the tree |
| 167 | checked out. |
| 168 | From anywhere underneath the root of your local tree, you |
| 169 | can type commands like the following to find out the status of |
| 170 | your local tree: |
| 171 | |
| 172 | <blockquote> |
| 173 | <b>[/help/info | fossil info]</b><br> |
| 174 | <b>[/help/status | fossil status]</b><br> |
| 175 | <b>[/help/changes | fossil changes]</b><br> |
| 176 | <b>[/help/diff | fossil diff]</b><br> |
| 177 | <b>[/help/timeline | fossil timeline]</b><br> |
| 178 | <b>[/help/ls | fossil ls]</b><br> |
| 179 | <b>[/help/branch | fossil branch]</b><br> |
| 180 | </blockquote> |
| 181 | |
| 182 | If you created a new repository using "fossil init" some commands will not |
| 183 | produce much output. |
| 184 | |
| 185 | Note that Fossil allows you to make multiple check-outs in |
| @@ -188,14 +170,14 @@ | |
| 188 | the same time without having to generate extra clones. |
| 189 | |
| 190 | To switch a checkout between different versions and branches, |
| 191 | use:< |
| 192 | |
| 193 | <blockquote> |
| 194 | <b>[/help/update | fossil update]</b><br> |
| 195 | <b>[/help/checkout | fossil checkout]</b><br> |
| 196 | </blockquote> |
| 197 | |
| 198 | [/help/update | update] honors the "autosync" option and |
| 199 | does a "soft" switch, merging any local changes into the target |
| 200 | version, whereas [/help/checkout | checkout] does not |
| 201 | automatically sync and does a "hard" switch, overwriting local |
| @@ -204,48 +186,39 @@ | |
| 204 | <h2 id="changes">Making and Committing Changes</h2> |
| 205 | |
| 206 | To add new files to your project or remove existing ones, use these |
| 207 | commands: |
| 208 | |
| 209 | <blockquote> |
| 210 | <b>[/help/add | fossil add]</b> <i>file...</i><br> |
| 211 | <b>[/help/rm | fossil rm]</b> <i>file...</i><br> |
| 212 | <b>[/help/addremove | fossil addremove]</b> <i>file...</i><br> |
| 213 | </blockquote> |
| 214 | |
| 215 | The command: |
| 216 | |
| 217 | <blockquote> |
| 218 | <b> |
| 219 | [/help/changes | fossil changes]</b> |
| 220 | </blockquote> |
| 221 | |
| 222 | lists files that have changed since the last commit to the repository. For |
| 223 | example, if you edit the file "README.md": |
| 224 | |
| 225 | <blockquote> |
| 226 | <b> |
| 227 | fossil changes<br> |
| 228 | EDITED README.md |
| 229 | </b> |
| 230 | </blockquote> |
| 231 | |
| 232 | To see exactly what change was made you can use the command |
| 233 | <b>[/help/diff | fossil diff]</b>: |
| 234 | |
| 235 | <blockquote> |
| 236 | <b> |
| 237 | fossil diff <br><tt> |
| 238 | Index: README.md<br> |
| 239 | ============================================================<br> |
| 240 | --- README.md<br> |
| 241 | +++ README.md<br> |
| 242 | @@ -1,5 +1,6 @@<br> |
| 243 | +Made some changes to the project<br> |
| 244 | # Original text<br> |
| 245 | </tt></b> |
| 246 | </blockquote> |
| ++++ README.md | |
| 247 | |
| 248 | "fossil diff" shows the difference between your tree on disk now and as |
| 249 | the tree was when you last committed changes. If you haven't committed |
| 250 | yet, then it shows the difference relative to the tip-of-trunk commit in |
| 251 | the repository, being what you get when you "fossil open" a repository |
| @@ -252,47 +225,43 @@ | |
| 252 | without specifying a version, populating the working directory. |
| 253 | |
| 254 | To see the most recent changes made to the repository by other users, use "fossil timeline" to |
| 255 | find out the most recent commit, and then "fossil diff" between that commit and the |
| 256 | current tree: |
| 257 | <blockquote> |
| 258 | <b> |
| 259 | fossil timeline <br><tt> |
| 260 | === 2021-03-28 === <br> |
| 261 | 03:18:54 [ad75dfa4a0] *CURRENT* Added details to frobnicate command (user: user-one tags: trunk) <br> |
| 262 | === 2021-03-27 === <br> |
| 263 | 23:58:05 [ab975c6632] Update README.md. (user: user-two tags: trunk) <br> |
| 264 | ⋮ <br> |
| 265 | </tt><br> |
| 266 | fossil diff --from current --to ab975c6632 <br><tt> |
| 267 | Index: frobnicate.c<br> |
| 268 | ============================================================<br> |
| 269 | --- frobnicate.c<br> |
| 270 | +++ frobnicate.c<br> |
| 271 | @@ -1,10 +1,11 @@<br> |
| 272 | +/* made a change to the source file */<br> |
| 273 | # Original text<br> |
| 274 | </tt></b> |
| 275 | </blockquote> |
| ++++ frobnicate.c | |
| 276 | |
| 277 | "current" is an alias for the checkout version, so the command |
| 278 | "fossil diff --from ad75dfa4a0 --to ab975c6632" gives identical results. |
| 279 | |
| 280 | To commit your changes to a local-only repository: |
| 281 | <blockquote> |
| 282 | <b> |
| 283 | fossil commit </b><i>(... Fossil will start your editor, if defined)</i><b><br><tt> |
| 284 | # Enter a commit message for this check-in. Lines beginning with # are ignored.<br> |
| 285 | #<br> |
| 286 | # user: exampleuser<br> |
| 287 | # tags: trunk<br> |
| 288 | #<br> |
| 289 | # EDITED README.md<br> |
| 290 | Edited file to add description of code changes<br> |
| 291 | New_Version: 7b9a416ced4a69a60589dde1aedd1a30fde8eec3528d265dbeed5135530440ab<br> |
| 292 | </tt></b> |
| 293 | </blockquote> |
| 294 | |
| 295 | You will be prompted for check-in comments using whatever editor |
| 296 | is specified by your VISUAL or EDITOR environment variable. If none is |
| 297 | specified Fossil uses line-editing in the terminal. |
| 298 | |
| @@ -333,13 +302,13 @@ | |
| 333 | project or create a new project of your own, you usually want to do some |
| 334 | local configuration. This is easily accomplished using the web-server |
| 335 | that is built into fossil. Start the fossil web server like this: |
| 336 | ([/help/ui | more info]) |
| 337 | |
| 338 | <blockquote> |
| 339 | <b>fossil ui </b><i> repository-filename</i> |
| 340 | </blockquote> |
| 341 | |
| 342 | You can omit the <i>repository-filename</i> from the command above |
| 343 | if you are inside a checked-out local tree. |
| 344 | |
| 345 | This starts a web server then automatically launches your |
| @@ -346,13 +315,13 @@ | |
| 346 | web browser and makes it point to this web server. If your system |
| 347 | has an unusual configuration, fossil might not be able to figure out |
| 348 | how to start your web browser. In that case, first tell fossil |
| 349 | where to find your web browser using a command like this: |
| 350 | |
| 351 | <blockquote> |
| 352 | <b>fossil setting web-browser </b><i> path-to-web-browser</i> |
| 353 | </blockquote> |
| 354 | |
| 355 | By default, fossil does not require a login for HTTP connections |
| 356 | coming in from the IP loopback address 127.0.0.1. You can, and perhaps |
| 357 | should, change this after you create a few users. |
| 358 | |
| @@ -364,34 +333,34 @@ | |
| 364 | When [./concepts.wiki#workflow|autosync] is turned off, |
| 365 | the changes you [/help/commit | commit] are only |
| 366 | on your local repository. |
| 367 | To share those changes with other repositories, do: |
| 368 | |
| 369 | <blockquote> |
| 370 | <b>[/help/push | fossil push]</b> <i>URL</i> |
| 371 | </blockquote> |
| 372 | |
| 373 | Where <i>URL</i> is the http: URL of the server repository you |
| 374 | want to share your changes with. If you omit the <i>URL</i> argument, |
| 375 | fossil will use whatever server you most recently synced with. |
| 376 | |
| 377 | The [/help/push | push] command only sends your changes to others. To |
| 378 | Receive changes from others, use [/help/pull | pull]. Or go both ways at |
| 379 | once using [/help/sync | sync]: |
| 380 | |
| 381 | <blockquote> |
| 382 | <b>[/help/pull | fossil pull]</b> <i>URL</i><br> |
| 383 | <b>[/help/sync | fossil sync]</b> <i>URL</i> |
| 384 | </blockquote> |
| 385 | |
| 386 | When you pull in changes from others, they go into your repository, |
| 387 | not into your checked-out local tree. To get the changes into your |
| 388 | local tree, use [/help/update | update]: |
| 389 | |
| 390 | <blockquote> |
| 391 | <b>[/help/update | fossil update]</b> <i>VERSION</i> |
| 392 | </blockquote> |
| 393 | |
| 394 | The <i>VERSION</i> can be the name of a branch or tag or any |
| 395 | abbreviation to the 40-character |
| 396 | artifact identifier for a particular check-in, or it can be a |
| 397 | date/time stamp. ([./checkin_names.wiki | more info]) |
| @@ -404,13 +373,13 @@ | |
| 404 | when you run [/help/update|update] and a [/help/push|push] happens |
| 405 | automatically after you [/help/commit|commit]. So in normal practice, |
| 406 | the push, pull, and sync commands are rarely used. But it is important |
| 407 | to know about them, all the same. |
| 408 | |
| 409 | <blockquote> |
| 410 | <b>[/help/checkout | fossil checkout]</b> <i>VERSION</i> |
| 411 | </blockquote> |
| 412 | |
| 413 | Is similar to update except that it does not honor the autosync |
| 414 | setting, nor does it merge in local changes - it prefers to overwrite |
| 415 | them and fails if local changes exist unless the <tt>--force</tt> |
| 416 | flag is used. |
| @@ -428,16 +397,16 @@ | |
| 428 | [/help/update | update] to the branch you want to merge into. |
| 429 | Then do a [/help/merge|merge] of the other branch that you want to incorporate |
| 430 | the changes from. For example, to merge "featureX" changes into "trunk" |
| 431 | do this: |
| 432 | |
| 433 | <blockquote> |
| 434 | <b>fossil [/help/update|update] trunk</b><br> |
| 435 | <b>fossil [/help/merge|merge] featureX</b><br> |
| 436 | <i># make sure the merge didn't break anything...</i><br> |
| 437 | <b>fossil [/help/commit|commit] |
| 438 | </blockquote> |
| 439 | |
| 440 | The argument to the [/help/merge|merge] command can be any of the |
| 441 | version identifier forms that work for [/help/update|update]. |
| 442 | ([./checkin_names.wiki|more info].) |
| 443 | The merge command has options to cherry-pick individual |
| @@ -460,13 +429,13 @@ | |
| 460 | merge. |
| 461 | |
| 462 | If a merge or update doesn't work out (perhaps something breaks or |
| 463 | there are many merge conflicts) then you back up using: |
| 464 | |
| 465 | <blockquote> |
| 466 | <b>[/help/undo | fossil undo]</b> |
| 467 | </blockquote> |
| 468 | |
| 469 | This will back out the changes that the merge or update made to the |
| 470 | working checkout. There is also a [/help/redo|redo] command if you undo by |
| 471 | mistake. Undo and redo only work for changes that have |
| 472 | not yet been checked in using commit and there is only a single |
| @@ -476,14 +445,14 @@ | |
| 476 | <h2 id="server">Setting Up A Server</h2> |
| 477 | |
| 478 | Fossil can act as a stand-alone web server using one of these |
| 479 | commands: |
| 480 | |
| 481 | <blockquote> |
| 482 | <b>[/help/server | fossil server]</b> <i>repository-filename</i><br> |
| 483 | <b>[/help/ui | fossil ui]</b> <i>repository-filename</i> |
| 484 | </blockquote> |
| 485 | |
| 486 | The <i>repository-filename</i> can be omitted when these commands |
| 487 | are run from within an open check-out, which is a particularly useful |
| 488 | shortcut with the <b>fossil ui</b> command. |
| 489 | |
| @@ -527,44 +496,44 @@ | |
| 527 | an HTTP proxy to reach the internet, then you can configure the proxy |
| 528 | in three different ways. You can tell fossil about your proxy using |
| 529 | a command-line option on commands that use the network, |
| 530 | <b>sync</b>, <b>clone</b>, <b>push</b>, and <b>pull</b>. |
| 531 | |
| 532 | <blockquote> |
| 533 | <b>fossil clone </b><i>URL</i> <b>--proxy</b> <i>Proxy-URL</i> |
| 534 | </blockquote> |
| 535 | |
| 536 | It is annoying to have to type in the proxy URL every time you |
| 537 | sync your project, though, so you can make the proxy configuration |
| 538 | persistent using the [/help/setting | setting] command: |
| 539 | |
| 540 | <blockquote> |
| 541 | <b>fossil setting proxy </b><i>Proxy-URL</i> |
| 542 | </blockquote> |
| 543 | |
| 544 | Or, you can set the "<b>http_proxy</b>" environment variable: |
| 545 | |
| 546 | <blockquote> |
| 547 | <b>export http_proxy=</b><i>Proxy-URL</i> |
| 548 | </blockquote> |
| 549 | |
| 550 | To stop using the proxy, do: |
| 551 | |
| 552 | <blockquote> |
| 553 | <b>fossil setting proxy off</b> |
| 554 | </blockquote> |
| 555 | |
| 556 | Or unset the environment variable. The fossil setting for the |
| 557 | HTTP proxy takes precedence over the environment variable and the |
| 558 | command-line option overrides both. If you have a persistent |
| 559 | proxy setting that you want to override for a one-time sync, that |
| 560 | is easily done on the command-line. For example, to sync with |
| 561 | a co-worker's repository on your LAN, you might type: |
| 562 | |
| 563 | <blockquote> |
| 564 | <b>fossil sync http://192.168.1.36:8080/ --proxy off</b> |
| 565 | </blockquote> |
| 566 | |
| 567 | <h2 id="links">Other Resources</h2> |
| 568 | |
| 569 | <ul> |
| 570 | <li> <a href="./gitusers.md">Hints For Users With Prior Git Experience</a> |
| 571 |
| --- www/quickstart.wiki | |
| +++ www/quickstart.wiki | |
| @@ -1,7 +1,6 @@ | |
| 1 | <title>Fossil Quick Start Guide</title> |
| 2 | |
| 3 | 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 |
| 4 | and painlessly. |
| 5 | |
| 6 | <h2 id="install">Installing</h2> |
| @@ -14,16 +13,13 @@ | |
| 13 | Install Fossil by putting the fossil binary |
| 14 | someplace on your $PATH. |
| 15 | |
| 16 | You can test that Fossil is present and working like this: |
| 17 | |
| 18 | <pre><b>fossil version |
| 19 | This is fossil version 2.13 [309af345ab] 2020-09-28 04:02:55 UTC |
| 20 | </b></pre> |
| 21 | |
| 22 | <h2 id="workflow" name="fslclone">General Work Flow</h2> |
| 23 | |
| 24 | Fossil works with repository files (a database in a single file with the project's |
| 25 | complete history) and with checked-out local trees (the working directory |
| @@ -48,13 +44,12 @@ | |
| 44 | <h2 id="new">Starting A New Project</h2> |
| 45 | |
| 46 | To start a new project with fossil create a new empty repository |
| 47 | this way: ([/help/init | more info]) |
| 48 | |
| 49 | <pre><b>fossil init</b> <i>repository-filename</i> |
| 50 | </pre> |
| 51 | |
| 52 | You can name the database anything you like, and you can place it anywhere in the filesystem. |
| 53 | The <tt>.fossil</tt> extension is traditional but only required if you are going to use the |
| 54 | <tt>[/help/server | fossil server DIRECTORY]</tt> feature.” |
| 55 | |
| @@ -66,45 +61,37 @@ | |
| 61 | repository. Making a local copy of a remote repository is called |
| 62 | "cloning". |
| 63 | |
| 64 | Clone a remote repository as follows: ([/help/clone | more info]) |
| 65 | |
| 66 | <pre><b>fossil clone</b> <i>URL repository-filename</i> |
| 67 | </pre> |
| 68 | |
| 69 | The <i>URL</i> specifies the fossil repository |
| 70 | you want to clone. The <i>repository-filename</i> is the new local |
| 71 | filename into which the cloned repository will be written. For |
| 72 | example, to clone the source code of Fossil itself: |
| 73 | |
| 74 | <pre><b>fossil clone https://fossil-scm.org/ myclone.fossil</b></pre> |
| 75 | |
| 76 | If your logged-in username is 'exampleuser', you should see output something like this: |
| 77 | |
| 78 | <pre><b>Round-trips: 8 Artifacts sent: 0 received: 39421 |
| 79 | Clone done, sent: 2424 received: 42965725 ip: 10.10.10.0 |
| 80 | Rebuilding repository meta-data... |
| 81 | 100% complete... |
| 82 | Extra delta compression... |
| 83 | Vacuuming the database... |
| 84 | project-id: 94259BB9F186226D80E49D1FA2DB29F935CCA0333 |
| 85 | server-id: 016595e9043054038a9ea9bc526d7f33f7ac0e42 |
| 86 | admin-user: exampleuser (password is "yoWgDR42iv")> |
| 87 | </b></pre> |
| 88 | |
| 89 | If the remote repository requires a login, include a |
| 90 | userid in the URL like this: |
| 91 | |
| 92 | <pre><b>fossil clone https://</b><i>remoteuserid</i><b>@www.example.org/ myclone.fossil</b></pre> |
| 93 | |
| 94 | You will be prompted separately for the password. |
| 95 | Use [https://en.wikipedia.org/wiki/Percent-encoding#Percent-encoding_reserved_characters|"%HH"] escapes for special characters in the userid. |
| 96 | For example "/" would be replaced by "%2F" meaning that a userid of "Projects/Budget" would become "Projects%2FBudget") |
| 97 | |
| @@ -143,43 +130,38 @@ | |
| 130 | To work on a project in fossil, you need to check out a local |
| 131 | copy of the source tree. Create the directory you want to be |
| 132 | the root of your tree and cd into that directory. Then |
| 133 | do this: ([/help/open | more info]) |
| 134 | |
| 135 | <pre><b>fossil open</b> <i>repository-filename</i></pre> |
| 136 | |
| 137 | for example: |
| 138 | |
| 139 | <pre><b>fossil open ../myclone.fossil |
| 140 | BUILD.txt |
| 141 | COPYRIGHT-BSD2.txt |
| 142 | README.md |
| 143 | ︙ |
| 144 | </tt></b></pre> |
| 145 | |
| 146 | (or "fossil open ..\myclone.fossil" on Windows). |
| 147 | |
| 148 | This leaves you with the newest version of the tree |
| 149 | checked out. |
| 150 | From anywhere underneath the root of your local tree, you |
| 151 | can type commands like the following to find out the status of |
| 152 | your local tree: |
| 153 | |
| 154 | <pre> |
| 155 | <b>[/help/info | fossil info]</b> |
| 156 | <b>[/help/status | fossil status]</b> |
| 157 | <b>[/help/changes | fossil changes]</b> |
| 158 | <b>[/help/diff | fossil diff]</b> |
| 159 | <b>[/help/timeline | fossil timeline]</b> |
| 160 | <b>[/help/ls | fossil ls]</b> |
| 161 | <b>[/help/branch | fossil branch]</b> |
| 162 | </pre> |
| 163 | |
| 164 | If you created a new repository using "fossil init" some commands will not |
| 165 | produce much output. |
| 166 | |
| 167 | Note that Fossil allows you to make multiple check-outs in |
| @@ -188,14 +170,14 @@ | |
| 170 | the same time without having to generate extra clones. |
| 171 | |
| 172 | To switch a checkout between different versions and branches, |
| 173 | use:< |
| 174 | |
| 175 | <pre> |
| 176 | <b>[/help/update | fossil update]</b> |
| 177 | <b>[/help/checkout | fossil checkout]</b> |
| 178 | </pre> |
| 179 | |
| 180 | [/help/update | update] honors the "autosync" option and |
| 181 | does a "soft" switch, merging any local changes into the target |
| 182 | version, whereas [/help/checkout | checkout] does not |
| 183 | automatically sync and does a "hard" switch, overwriting local |
| @@ -204,48 +186,39 @@ | |
| 186 | <h2 id="changes">Making and Committing Changes</h2> |
| 187 | |
| 188 | To add new files to your project or remove existing ones, use these |
| 189 | commands: |
| 190 | |
| 191 | <pre> |
| 192 | <b>[/help/add | fossil add]</b> <i>file...</i> |
| 193 | <b>[/help/rm | fossil rm]</b> <i>file...</i> |
| 194 | <b>[/help/addremove | fossil addremove]</b> <i>file...</i> |
| 195 | </pre> |
| 196 | |
| 197 | The command: |
| 198 | |
| 199 | <pre><b>[/help/changes | fossil changes]</b></pre> |
| 200 | |
| 201 | lists files that have changed since the last commit to the repository. For |
| 202 | example, if you edit the file "README.md": |
| 203 | |
| 204 | <pre><b>fossil changes |
| 205 | EDITED README.md |
| 206 | </b></pre> |
| 207 | |
| 208 | To see exactly what change was made you can use the command |
| 209 | <b>[/help/diff | fossil diff]</b>: |
| 210 | |
| 211 | <pre><b>fossil diff |
| 212 | Index: README.md |
| 213 | ============================================================ |
| 214 | --- README.md |
| ++++ README.md | |
| 215 | @@ -1,5 +1,6 @@ |
| 216 | +Made some changes to the project |
| 217 | # Original text |
| 218 | </b></pre> |
| 219 | |
| 220 | "fossil diff" shows the difference between your tree on disk now and as |
| 221 | the tree was when you last committed changes. If you haven't committed |
| 222 | yet, then it shows the difference relative to the tip-of-trunk commit in |
| 223 | the repository, being what you get when you "fossil open" a repository |
| @@ -252,47 +225,43 @@ | |
| 225 | without specifying a version, populating the working directory. |
| 226 | |
| 227 | To see the most recent changes made to the repository by other users, use "fossil timeline" to |
| 228 | find out the most recent commit, and then "fossil diff" between that commit and the |
| 229 | current tree: |
| 230 | |
| 231 | <pre><b>fossil timeline |
| 232 | === 2021-03-28 === |
| 233 | 03:18:54 [ad75dfa4a0] *CURRENT* Added details to frobnicate command (user: user-one tags: trunk) |
| 234 | === 2021-03-27 === |
| 235 | 23:58:05 [ab975c6632] Update README.md. (user: user-two tags: trunk) |
| 236 | ⋮ |
| 237 | |
| 238 | fossil diff --from current --to ab975c6632 |
| 239 | Index: frobnicate.c |
| 240 | ============================================================ |
| 241 | --- frobnicate.c |
| ++++ frobnicate.c | |
| 242 | @@ -1,10 +1,11 @@ |
| 243 | +/* made a change to the source file */ |
| 244 | # Original text |
| 245 | </b></pre> |
| 246 | |
| 247 | "current" is an alias for the checkout version, so the command |
| 248 | "fossil diff --from ad75dfa4a0 --to ab975c6632" gives identical results. |
| 249 | |
| 250 | To commit your changes to a local-only repository: |
| 251 | |
| 252 | <pre><b>fossil commit</b> <i>(... Fossil will start your editor, if defined)</i><b> |
| 253 | # Enter a commit message for this check-in. Lines beginning with # are ignored. |
| 254 | # |
| 255 | # user: exampleuser |
| 256 | # tags: trunk |
| 257 | # |
| 258 | # EDITED README.md |
| 259 | Edited file to add description of code changes |
| 260 | New_Version: 7b9a416ced4a69a60589dde1aedd1a30fde8eec3528d265dbeed5135530440ab |
| 261 | </b></pre> |
| 262 | |
| 263 | You will be prompted for check-in comments using whatever editor |
| 264 | is specified by your VISUAL or EDITOR environment variable. If none is |
| 265 | specified Fossil uses line-editing in the terminal. |
| 266 | |
| @@ -333,13 +302,13 @@ | |
| 302 | project or create a new project of your own, you usually want to do some |
| 303 | local configuration. This is easily accomplished using the web-server |
| 304 | that is built into fossil. Start the fossil web server like this: |
| 305 | ([/help/ui | more info]) |
| 306 | |
| 307 | <pre> |
| 308 | <b>fossil ui</b> <i>repository-filename</i> |
| 309 | </pre> |
| 310 | |
| 311 | You can omit the <i>repository-filename</i> from the command above |
| 312 | if you are inside a checked-out local tree. |
| 313 | |
| 314 | This starts a web server then automatically launches your |
| @@ -346,13 +315,13 @@ | |
| 315 | web browser and makes it point to this web server. If your system |
| 316 | has an unusual configuration, fossil might not be able to figure out |
| 317 | how to start your web browser. In that case, first tell fossil |
| 318 | where to find your web browser using a command like this: |
| 319 | |
| 320 | <pre> |
| 321 | <b>fossil setting web-browser</b> <i>path-to-web-browser</i> |
| 322 | </pre> |
| 323 | |
| 324 | By default, fossil does not require a login for HTTP connections |
| 325 | coming in from the IP loopback address 127.0.0.1. You can, and perhaps |
| 326 | should, change this after you create a few users. |
| 327 | |
| @@ -364,34 +333,34 @@ | |
| 333 | When [./concepts.wiki#workflow|autosync] is turned off, |
| 334 | the changes you [/help/commit | commit] are only |
| 335 | on your local repository. |
| 336 | To share those changes with other repositories, do: |
| 337 | |
| 338 | <pre> |
| 339 | <b>[/help/push | fossil push]</b> <i>URL</i> |
| 340 | </pre> |
| 341 | |
| 342 | Where <i>URL</i> is the http: URL of the server repository you |
| 343 | want to share your changes with. If you omit the <i>URL</i> argument, |
| 344 | fossil will use whatever server you most recently synced with. |
| 345 | |
| 346 | The [/help/push | push] command only sends your changes to others. To |
| 347 | Receive changes from others, use [/help/pull | pull]. Or go both ways at |
| 348 | once using [/help/sync | sync]: |
| 349 | |
| 350 | <pre> |
| 351 | <b>[/help/pull | fossil pull]</b> <i>URL</i> |
| 352 | <b>[/help/sync | fossil sync]</b> <i>URL</i> |
| 353 | </pre> |
| 354 | |
| 355 | When you pull in changes from others, they go into your repository, |
| 356 | not into your checked-out local tree. To get the changes into your |
| 357 | local tree, use [/help/update | update]: |
| 358 | |
| 359 | <pre> |
| 360 | <b>[/help/update | fossil update]</b> <i>VERSION</i> |
| 361 | </pre> |
| 362 | |
| 363 | The <i>VERSION</i> can be the name of a branch or tag or any |
| 364 | abbreviation to the 40-character |
| 365 | artifact identifier for a particular check-in, or it can be a |
| 366 | date/time stamp. ([./checkin_names.wiki | more info]) |
| @@ -404,13 +373,13 @@ | |
| 373 | when you run [/help/update|update] and a [/help/push|push] happens |
| 374 | automatically after you [/help/commit|commit]. So in normal practice, |
| 375 | the push, pull, and sync commands are rarely used. But it is important |
| 376 | to know about them, all the same. |
| 377 | |
| 378 | <pre> |
| 379 | <b>[/help/checkout | fossil checkout]</b> <i>VERSION</i> |
| 380 | </pre> |
| 381 | |
| 382 | Is similar to update except that it does not honor the autosync |
| 383 | setting, nor does it merge in local changes - it prefers to overwrite |
| 384 | them and fails if local changes exist unless the <tt>--force</tt> |
| 385 | flag is used. |
| @@ -428,16 +397,16 @@ | |
| 397 | [/help/update | update] to the branch you want to merge into. |
| 398 | Then do a [/help/merge|merge] of the other branch that you want to incorporate |
| 399 | the changes from. For example, to merge "featureX" changes into "trunk" |
| 400 | do this: |
| 401 | |
| 402 | <pre> |
| 403 | <b>fossil [/help/update|update] trunk</b> |
| 404 | <b>fossil [/help/merge|merge] featureX</b> |
| 405 | <i># make sure the merge didn't break anything...</i> |
| 406 | <b>fossil [/help/commit|commit] |
| 407 | </pre> |
| 408 | |
| 409 | The argument to the [/help/merge|merge] command can be any of the |
| 410 | version identifier forms that work for [/help/update|update]. |
| 411 | ([./checkin_names.wiki|more info].) |
| 412 | The merge command has options to cherry-pick individual |
| @@ -460,13 +429,13 @@ | |
| 429 | merge. |
| 430 | |
| 431 | If a merge or update doesn't work out (perhaps something breaks or |
| 432 | there are many merge conflicts) then you back up using: |
| 433 | |
| 434 | <pre> |
| 435 | <b>[/help/undo | fossil undo]</b> |
| 436 | </pre> |
| 437 | |
| 438 | This will back out the changes that the merge or update made to the |
| 439 | working checkout. There is also a [/help/redo|redo] command if you undo by |
| 440 | mistake. Undo and redo only work for changes that have |
| 441 | not yet been checked in using commit and there is only a single |
| @@ -476,14 +445,14 @@ | |
| 445 | <h2 id="server">Setting Up A Server</h2> |
| 446 | |
| 447 | Fossil can act as a stand-alone web server using one of these |
| 448 | commands: |
| 449 | |
| 450 | <pre> |
| 451 | <b>[/help/server | fossil server]</b> <i>repository-filename</i> |
| 452 | <b>[/help/ui | fossil ui]</b> <i>repository-filename</i> |
| 453 | </pre> |
| 454 | |
| 455 | The <i>repository-filename</i> can be omitted when these commands |
| 456 | are run from within an open check-out, which is a particularly useful |
| 457 | shortcut with the <b>fossil ui</b> command. |
| 458 | |
| @@ -527,44 +496,44 @@ | |
| 496 | an HTTP proxy to reach the internet, then you can configure the proxy |
| 497 | in three different ways. You can tell fossil about your proxy using |
| 498 | a command-line option on commands that use the network, |
| 499 | <b>sync</b>, <b>clone</b>, <b>push</b>, and <b>pull</b>. |
| 500 | |
| 501 | <pre> |
| 502 | <b>fossil clone </b><i>URL</i> <b>--proxy</b> <i>Proxy-URL</i> |
| 503 | </pre> |
| 504 | |
| 505 | It is annoying to have to type in the proxy URL every time you |
| 506 | sync your project, though, so you can make the proxy configuration |
| 507 | persistent using the [/help/setting | setting] command: |
| 508 | |
| 509 | <pre> |
| 510 | <b>fossil setting proxy </b><i>Proxy-URL</i> |
| 511 | </pre> |
| 512 | |
| 513 | Or, you can set the "<b>http_proxy</b>" environment variable: |
| 514 | |
| 515 | <pre> |
| 516 | <b>export http_proxy=</b><i>Proxy-URL</i> |
| 517 | </pre> |
| 518 | |
| 519 | To stop using the proxy, do: |
| 520 | |
| 521 | <pre> |
| 522 | <b>fossil setting proxy off</b> |
| 523 | </pre> |
| 524 | |
| 525 | Or unset the environment variable. The fossil setting for the |
| 526 | HTTP proxy takes precedence over the environment variable and the |
| 527 | command-line option overrides both. If you have a persistent |
| 528 | proxy setting that you want to override for a one-time sync, that |
| 529 | is easily done on the command-line. For example, to sync with |
| 530 | a co-worker's repository on your LAN, you might type: |
| 531 | |
| 532 | <pre> |
| 533 | <b>fossil sync http://192.168.1.36:8080/ --proxy off</b> |
| 534 | </pre> |
| 535 | |
| 536 | <h2 id="links">Other Resources</h2> |
| 537 | |
| 538 | <ul> |
| 539 | <li> <a href="./gitusers.md">Hints For Users With Prior Git Experience</a> |
| 540 |
+37
-37
| --- www/quotes.wiki | ||
| +++ www/quotes.wiki | ||
| @@ -2,115 +2,115 @@ | ||
| 2 | 2 | |
| 3 | 3 | The following are collected quotes from various forums and blogs about |
| 4 | 4 | Fossil, Git, and DVCSes in general. This collection is put together |
| 5 | 5 | by the creator of Fossil, so of course there is selection bias... |
| 6 | 6 | |
| 7 | -<h2>On The Usability Of Git:</h2> | |
| 7 | +<h2>On The Usability Of Git</h2> | |
| 8 | 8 | |
| 9 | 9 | <ol> |
| 10 | 10 | <li>Git approaches the usability of iptables, which is to say, utterly |
| 11 | 11 | unusable unless you have the manpage tattooed on you arm. |
| 12 | 12 | |
| 13 | -<blockquote> | |
| 13 | +<p class="local-indent"> | |
| 14 | 14 | <i>by mml at [http://news.ycombinator.com/item?id=1433387]</i> |
| 15 | -</blockquote> | |
| 15 | +</p> | |
| 16 | 16 | |
| 17 | 17 | <li><nowiki>It's simplest to think of the state of your [git] repository |
| 18 | 18 | as a point in a high-dimensional "code-space", in which branches are |
| 19 | 19 | represented as n-dimensional membranes, mapping the spatial loci of |
| 20 | 20 | successive commits onto the projected manifold of each cloned |
| 21 | 21 | repository.</nowiki> |
| 22 | 22 | |
| 23 | -<blockquote> | |
| 23 | +<p class="local-indent"> | |
| 24 | 24 | <i>by Jonathan Hartley at |
| 25 | 25 | [https://www.tartley.com/posts/a-guide-to-git-using-spatial-analogies]; |
| 26 | 26 | <br>Quoted here: [https://lwn.net/Articles/420152/].</i> |
| 27 | -</blockquote> | |
| 27 | +</p> | |
| 28 | 28 | |
| 29 | 29 | <li>Git is not a Prius. Git is a Model T. |
| 30 | 30 | Its plumbing and wiring sticks out all over the place. |
| 31 | 31 | You have to be a mechanic to operate it successfully or you'll be |
| 32 | 32 | stuck on the side of the road when it breaks down. |
| 33 | 33 | And it <b>will</b> break down. |
| 34 | 34 | |
| 35 | -<blockquote> | |
| 35 | +<p class="local-indent"> | |
| 36 | 36 | <i>Nick Farina at [http://nfarina.com/post/9868516270/git-is-simpler]</i> |
| 37 | -</blockquote> | |
| 37 | +</p> | |
| 38 | 38 | |
| 39 | 39 | <li>Initial revision of "git", The information manager from hell |
| 40 | 40 | |
| 41 | -<blockquote> | |
| 41 | +<p class="local-indent"> | |
| 42 | 42 | <i>Linus Torvalds - 2005-04-07 22:13:13<br> |
| 43 | 43 | Commit comment on the very first source-code check-in for git |
| 44 | -</blockquote> | |
| 44 | +</p> | |
| 45 | 45 | |
| 46 | 46 | <li>I've been experimenting a lot with git at work. |
| 47 | 47 | Damn, it's complicated. |
| 48 | 48 | It has things to trip you up with that sane people just wouldn't ever both with |
| 49 | 49 | including the ability to allow you to commit stuff in such a way that you can't find |
| 50 | 50 | it again afterwards (!!!) |
| 51 | 51 | Demented workflow complexity on acid? |
| 52 | 52 | <p>* dkf really wishes he could use fossil instead</p> |
| 53 | -<blockquote> | |
| 53 | +<p class="local-indent"> | |
| 54 | 54 | <i>by Donal K. Fellow (dkf) on the Tcl/Tk chatroom, 2013-04-09.</i> |
| 55 | -</blockquote> | |
| 55 | +</p> | |
| 56 | 56 | |
| 57 | 57 | <li>[G]it is <i>designed</i> to forget things. |
| 58 | 58 | |
| 59 | -<blockquote> | |
| 59 | +<p class="local-indent"> | |
| 60 | 60 | <i>[http://www.cs.cmu.edu/~davide/howto/git_lose.html] |
| 61 | -</blockquote> | |
| 61 | +</p> | |
| 62 | 62 | |
| 63 | 63 | <li>[I]n nearly 31 years of using a computer i have, in total, lost more data to git |
| 64 | 64 | (while following the instructions!!!) than any other single piece of software. |
| 65 | 65 | |
| 66 | -<blockquote> | |
| 66 | +<p class="local-indent"> | |
| 67 | 67 | <i>Stephan Beal on the [http://www.mail-archive.com/[email protected]/msg17181.html|Fossil mailing list] |
| 68 | 68 | 2014-09-01.</i> |
| 69 | -</blockquote> | |
| 69 | +</p> | |
| 70 | 70 | |
| 71 | 71 | <li>If programmers _really_ wanted to help scientists, they'd build a version control |
| 72 | 72 | system that was more usable than Git. |
| 73 | 73 | |
| 74 | -<blockquote> | |
| 74 | +<p class="local-indent"> | |
| 75 | 75 | <i>Tweet by Greg Wilson @gvwilson on 2015-02-22 17:47</i> |
| 76 | -</blockquote> | |
| 76 | +</p> | |
| 77 | 77 | |
| 78 | 78 | <li><img src='xkcd-git.gif' align='top'> |
| 79 | 79 | |
| 80 | -<blockquote><i>Randall Munroe. [http://xkcd.com/1597/]</i></blockquote> | |
| 80 | +<p class="local-indent"><i>Randall Munroe. [http://xkcd.com/1597/]</i><p> | |
| 81 | 81 | |
| 82 | 82 | </ol> |
| 83 | 83 | |
| 84 | -<h2>On The Usability Of Fossil:</h2> | |
| 84 | +<h2>On The Usability Of Fossil</h2> | |
| 85 | 85 | |
| 86 | 86 | <ol> |
| 87 | 87 | <li value=11> |
| 88 | 88 | Fossil mesmerizes me with simplicity especially after I struggled to |
| 89 | 89 | get a bug-tracking system to work with mercurial. |
| 90 | 90 | |
| 91 | -<blockquote> | |
| 91 | +<p class="local-indent"> | |
| 92 | 92 | <i>rawjeev at [https://stackoverflow.com/a/2100469/142454]</i> |
| 93 | -</blockquote> | |
| 93 | +</p> | |
| 94 | 94 | |
| 95 | 95 | <li>Fossil is the best thing to happen |
| 96 | 96 | to my development workflow this year, as I am pretty sure that using |
| 97 | 97 | Git has resulted in the premature death of too many of my brain cells. |
| 98 | 98 | I'm glad to be able to replace Git in every place that I possibly can |
| 99 | 99 | with Fossil. |
| 100 | 100 | |
| 101 | -<blockquote> | |
| 101 | +<p class="local-indent"> | |
| 102 | 102 | <i>Joe Prostko at [http://www.mail-archive.com/[email protected]/msg16716.html] |
| 103 | -</blockquote> | |
| 103 | +</p> | |
| 104 | 104 | |
| 105 | 105 | <li>This is my favourite VCS. I can carry it on a USB. And it's a complete system, with it's own |
| 106 | 106 | server, ticketing system, Wiki pages, and a very, very helpful timeline visualization. And |
| 107 | 107 | the entire program in a single file! |
| 108 | 108 | |
| 109 | -<blockquote> | |
| 109 | +<p class="local-indent"> | |
| 110 | 110 | <i>thunderbong commenting on hacker news: [https://news.ycombinator.com/item?id=9131619]</i> |
| 111 | -</blockquote> | |
| 111 | +</p> | |
| 112 | 112 | |
| 113 | 113 | |
| 114 | 114 | </ol> |
| 115 | 115 | |
| 116 | 116 | |
| @@ -118,33 +118,33 @@ | ||
| 118 | 118 | |
| 119 | 119 | <ol> |
| 120 | 120 | <li value=14> |
| 121 | 121 | After prolonged exposure to fossil, i tend to get the jitters when I work with git... |
| 122 | 122 | |
| 123 | -<blockquote> | |
| 123 | +<p class="local-indent"> | |
| 124 | 124 | <i>sriku - at [https://news.ycombinator.com/item?id=16104427]</i> |
| 125 | -</blockquote> | |
| 125 | +</p> | |
| 126 | 126 | |
| 127 | 127 | |
| 128 | 128 | <li> |
| 129 | 129 | Just want to say thanks for fossil making my life easier.... |
| 130 | 130 | Also <nowiki>[for]</nowiki> not having a misanthropic command line interface. |
| 131 | 131 | |
| 132 | -<blockquote> | |
| 132 | +<p class="local-indent"> | |
| 133 | 133 | <i>Joshua Paine at [http://www.mail-archive.com/[email protected]/msg02736.html]</i> |
| 134 | -</blockquote> | |
| 134 | +</p> | |
| 135 | 135 | |
| 136 | 136 | <li>We use it at a large university to manage code that small teams write. |
| 137 | 137 | The runs everywhere, ease of installation and portability is something that |
| 138 | 138 | seems to be a good fit with the environment we have (highly ditrobuted, |
| 139 | 139 | sometimes very restrictive firewalls, OSX/Win/Linux). We are happy with it |
| 140 | 140 | and teaching a Msc/Phd student (read complete novice) fossil has just |
| 141 | 141 | been a smoother ride than Git was. |
| 142 | 142 | |
| 143 | -<blockquote> | |
| 143 | +<p class="local-indent"> | |
| 144 | 144 | <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> |
| 145 | -</blockquote> | |
| 145 | +</p> | |
| 146 | 146 | |
| 147 | 147 | <li>In the fossil community - and hence in fossil itself - development history |
| 148 | 148 | is pretty much sacrosanct. The very name "fossil" was to chosen to |
| 149 | 149 | reflect the unchanging nature of things in that history. |
| 150 | 150 | <br><br> |
| @@ -151,21 +151,21 @@ | ||
| 151 | 151 | In git (or rather, the git community), the development history is part of |
| 152 | 152 | the published aspect of the project, so it provides tools for rearranging |
| 153 | 153 | that history so you can present what you "should" have done rather |
| 154 | 154 | than what you actually did. |
| 155 | 155 | |
| 156 | -<blockquote> | |
| 156 | +<p class="local-indent"> | |
| 157 | 157 | <i>Mike Meyer on the Fossil mailing list, 2011-10-04</i> |
| 158 | -</blockquote> | |
| 158 | +</p> | |
| 159 | 159 | |
| 160 | 160 | <li>github is such a pale shadow of what fossil does. |
| 161 | 161 | |
| 162 | -<blockquote> | |
| 162 | +<p class="local-indent"> | |
| 163 | 163 | <i>dkf on the Tcl chatroom, 2013-12-06</i> |
| 164 | -</blockquote> | |
| 164 | +</p> | |
| 165 | 165 | |
| 166 | 166 | <li>[With fossil] I actually enjoy keeping track of source files again. |
| 167 | 167 | |
| 168 | -<blockquote> | |
| 168 | +<p class="local-indent"> | |
| 169 | 169 | <a href="https://wholesomedonut.prose.sh/using-fossil-not-git">https://wholesomedonut.prose.sh/using-fossil-not-git</a> |
| 170 | -</blockquote> | |
| 170 | +</p> | |
| 171 | 171 | </ol> |
| 172 | 172 |
| --- www/quotes.wiki | |
| +++ www/quotes.wiki | |
| @@ -2,115 +2,115 @@ | |
| 2 | |
| 3 | The following are collected quotes from various forums and blogs about |
| 4 | Fossil, Git, and DVCSes in general. This collection is put together |
| 5 | by the creator of Fossil, so of course there is selection bias... |
| 6 | |
| 7 | <h2>On The Usability Of Git:</h2> |
| 8 | |
| 9 | <ol> |
| 10 | <li>Git approaches the usability of iptables, which is to say, utterly |
| 11 | unusable unless you have the manpage tattooed on you arm. |
| 12 | |
| 13 | <blockquote> |
| 14 | <i>by mml at [http://news.ycombinator.com/item?id=1433387]</i> |
| 15 | </blockquote> |
| 16 | |
| 17 | <li><nowiki>It's simplest to think of the state of your [git] repository |
| 18 | as a point in a high-dimensional "code-space", in which branches are |
| 19 | represented as n-dimensional membranes, mapping the spatial loci of |
| 20 | successive commits onto the projected manifold of each cloned |
| 21 | repository.</nowiki> |
| 22 | |
| 23 | <blockquote> |
| 24 | <i>by Jonathan Hartley at |
| 25 | [https://www.tartley.com/posts/a-guide-to-git-using-spatial-analogies]; |
| 26 | <br>Quoted here: [https://lwn.net/Articles/420152/].</i> |
| 27 | </blockquote> |
| 28 | |
| 29 | <li>Git is not a Prius. Git is a Model T. |
| 30 | Its plumbing and wiring sticks out all over the place. |
| 31 | You have to be a mechanic to operate it successfully or you'll be |
| 32 | stuck on the side of the road when it breaks down. |
| 33 | And it <b>will</b> break down. |
| 34 | |
| 35 | <blockquote> |
| 36 | <i>Nick Farina at [http://nfarina.com/post/9868516270/git-is-simpler]</i> |
| 37 | </blockquote> |
| 38 | |
| 39 | <li>Initial revision of "git", The information manager from hell |
| 40 | |
| 41 | <blockquote> |
| 42 | <i>Linus Torvalds - 2005-04-07 22:13:13<br> |
| 43 | Commit comment on the very first source-code check-in for git |
| 44 | </blockquote> |
| 45 | |
| 46 | <li>I've been experimenting a lot with git at work. |
| 47 | Damn, it's complicated. |
| 48 | It has things to trip you up with that sane people just wouldn't ever both with |
| 49 | including the ability to allow you to commit stuff in such a way that you can't find |
| 50 | it again afterwards (!!!) |
| 51 | Demented workflow complexity on acid? |
| 52 | <p>* dkf really wishes he could use fossil instead</p> |
| 53 | <blockquote> |
| 54 | <i>by Donal K. Fellow (dkf) on the Tcl/Tk chatroom, 2013-04-09.</i> |
| 55 | </blockquote> |
| 56 | |
| 57 | <li>[G]it is <i>designed</i> to forget things. |
| 58 | |
| 59 | <blockquote> |
| 60 | <i>[http://www.cs.cmu.edu/~davide/howto/git_lose.html] |
| 61 | </blockquote> |
| 62 | |
| 63 | <li>[I]n nearly 31 years of using a computer i have, in total, lost more data to git |
| 64 | (while following the instructions!!!) than any other single piece of software. |
| 65 | |
| 66 | <blockquote> |
| 67 | <i>Stephan Beal on the [http://www.mail-archive.com/[email protected]/msg17181.html|Fossil mailing list] |
| 68 | 2014-09-01.</i> |
| 69 | </blockquote> |
| 70 | |
| 71 | <li>If programmers _really_ wanted to help scientists, they'd build a version control |
| 72 | system that was more usable than Git. |
| 73 | |
| 74 | <blockquote> |
| 75 | <i>Tweet by Greg Wilson @gvwilson on 2015-02-22 17:47</i> |
| 76 | </blockquote> |
| 77 | |
| 78 | <li><img src='xkcd-git.gif' align='top'> |
| 79 | |
| 80 | <blockquote><i>Randall Munroe. [http://xkcd.com/1597/]</i></blockquote> |
| 81 | |
| 82 | </ol> |
| 83 | |
| 84 | <h2>On The Usability Of Fossil:</h2> |
| 85 | |
| 86 | <ol> |
| 87 | <li value=11> |
| 88 | Fossil mesmerizes me with simplicity especially after I struggled to |
| 89 | get a bug-tracking system to work with mercurial. |
| 90 | |
| 91 | <blockquote> |
| 92 | <i>rawjeev at [https://stackoverflow.com/a/2100469/142454]</i> |
| 93 | </blockquote> |
| 94 | |
| 95 | <li>Fossil is the best thing to happen |
| 96 | to my development workflow this year, as I am pretty sure that using |
| 97 | Git has resulted in the premature death of too many of my brain cells. |
| 98 | I'm glad to be able to replace Git in every place that I possibly can |
| 99 | with Fossil. |
| 100 | |
| 101 | <blockquote> |
| 102 | <i>Joe Prostko at [http://www.mail-archive.com/[email protected]/msg16716.html] |
| 103 | </blockquote> |
| 104 | |
| 105 | <li>This is my favourite VCS. I can carry it on a USB. And it's a complete system, with it's own |
| 106 | server, ticketing system, Wiki pages, and a very, very helpful timeline visualization. And |
| 107 | the entire program in a single file! |
| 108 | |
| 109 | <blockquote> |
| 110 | <i>thunderbong commenting on hacker news: [https://news.ycombinator.com/item?id=9131619]</i> |
| 111 | </blockquote> |
| 112 | |
| 113 | |
| 114 | </ol> |
| 115 | |
| 116 | |
| @@ -118,33 +118,33 @@ | |
| 118 | |
| 119 | <ol> |
| 120 | <li value=14> |
| 121 | After prolonged exposure to fossil, i tend to get the jitters when I work with git... |
| 122 | |
| 123 | <blockquote> |
| 124 | <i>sriku - at [https://news.ycombinator.com/item?id=16104427]</i> |
| 125 | </blockquote> |
| 126 | |
| 127 | |
| 128 | <li> |
| 129 | Just want to say thanks for fossil making my life easier.... |
| 130 | Also <nowiki>[for]</nowiki> not having a misanthropic command line interface. |
| 131 | |
| 132 | <blockquote> |
| 133 | <i>Joshua Paine at [http://www.mail-archive.com/[email protected]/msg02736.html]</i> |
| 134 | </blockquote> |
| 135 | |
| 136 | <li>We use it at a large university to manage code that small teams write. |
| 137 | The runs everywhere, ease of installation and portability is something that |
| 138 | seems to be a good fit with the environment we have (highly ditrobuted, |
| 139 | sometimes very restrictive firewalls, OSX/Win/Linux). We are happy with it |
| 140 | and teaching a Msc/Phd student (read complete novice) fossil has just |
| 141 | been a smoother ride than Git was. |
| 142 | |
| 143 | <blockquote> |
| 144 | <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> |
| 145 | </blockquote> |
| 146 | |
| 147 | <li>In the fossil community - and hence in fossil itself - development history |
| 148 | is pretty much sacrosanct. The very name "fossil" was to chosen to |
| 149 | reflect the unchanging nature of things in that history. |
| 150 | <br><br> |
| @@ -151,21 +151,21 @@ | |
| 151 | In git (or rather, the git community), the development history is part of |
| 152 | the published aspect of the project, so it provides tools for rearranging |
| 153 | that history so you can present what you "should" have done rather |
| 154 | than what you actually did. |
| 155 | |
| 156 | <blockquote> |
| 157 | <i>Mike Meyer on the Fossil mailing list, 2011-10-04</i> |
| 158 | </blockquote> |
| 159 | |
| 160 | <li>github is such a pale shadow of what fossil does. |
| 161 | |
| 162 | <blockquote> |
| 163 | <i>dkf on the Tcl chatroom, 2013-12-06</i> |
| 164 | </blockquote> |
| 165 | |
| 166 | <li>[With fossil] I actually enjoy keeping track of source files again. |
| 167 | |
| 168 | <blockquote> |
| 169 | <a href="https://wholesomedonut.prose.sh/using-fossil-not-git">https://wholesomedonut.prose.sh/using-fossil-not-git</a> |
| 170 | </blockquote> |
| 171 | </ol> |
| 172 |
| --- www/quotes.wiki | |
| +++ www/quotes.wiki | |
| @@ -2,115 +2,115 @@ | |
| 2 | |
| 3 | The following are collected quotes from various forums and blogs about |
| 4 | Fossil, Git, and DVCSes in general. This collection is put together |
| 5 | by the creator of Fossil, so of course there is selection bias... |
| 6 | |
| 7 | <h2>On The Usability Of Git</h2> |
| 8 | |
| 9 | <ol> |
| 10 | <li>Git approaches the usability of iptables, which is to say, utterly |
| 11 | unusable unless you have the manpage tattooed on you arm. |
| 12 | |
| 13 | <p class="local-indent"> |
| 14 | <i>by mml at [http://news.ycombinator.com/item?id=1433387]</i> |
| 15 | </p> |
| 16 | |
| 17 | <li><nowiki>It's simplest to think of the state of your [git] repository |
| 18 | as a point in a high-dimensional "code-space", in which branches are |
| 19 | represented as n-dimensional membranes, mapping the spatial loci of |
| 20 | successive commits onto the projected manifold of each cloned |
| 21 | repository.</nowiki> |
| 22 | |
| 23 | <p class="local-indent"> |
| 24 | <i>by Jonathan Hartley at |
| 25 | [https://www.tartley.com/posts/a-guide-to-git-using-spatial-analogies]; |
| 26 | <br>Quoted here: [https://lwn.net/Articles/420152/].</i> |
| 27 | </p> |
| 28 | |
| 29 | <li>Git is not a Prius. Git is a Model T. |
| 30 | Its plumbing and wiring sticks out all over the place. |
| 31 | You have to be a mechanic to operate it successfully or you'll be |
| 32 | stuck on the side of the road when it breaks down. |
| 33 | And it <b>will</b> break down. |
| 34 | |
| 35 | <p class="local-indent"> |
| 36 | <i>Nick Farina at [http://nfarina.com/post/9868516270/git-is-simpler]</i> |
| 37 | </p> |
| 38 | |
| 39 | <li>Initial revision of "git", The information manager from hell |
| 40 | |
| 41 | <p class="local-indent"> |
| 42 | <i>Linus Torvalds - 2005-04-07 22:13:13<br> |
| 43 | Commit comment on the very first source-code check-in for git |
| 44 | </p> |
| 45 | |
| 46 | <li>I've been experimenting a lot with git at work. |
| 47 | Damn, it's complicated. |
| 48 | It has things to trip you up with that sane people just wouldn't ever both with |
| 49 | including the ability to allow you to commit stuff in such a way that you can't find |
| 50 | it again afterwards (!!!) |
| 51 | Demented workflow complexity on acid? |
| 52 | <p>* dkf really wishes he could use fossil instead</p> |
| 53 | <p class="local-indent"> |
| 54 | <i>by Donal K. Fellow (dkf) on the Tcl/Tk chatroom, 2013-04-09.</i> |
| 55 | </p> |
| 56 | |
| 57 | <li>[G]it is <i>designed</i> to forget things. |
| 58 | |
| 59 | <p class="local-indent"> |
| 60 | <i>[http://www.cs.cmu.edu/~davide/howto/git_lose.html] |
| 61 | </p> |
| 62 | |
| 63 | <li>[I]n nearly 31 years of using a computer i have, in total, lost more data to git |
| 64 | (while following the instructions!!!) than any other single piece of software. |
| 65 | |
| 66 | <p class="local-indent"> |
| 67 | <i>Stephan Beal on the [http://www.mail-archive.com/[email protected]/msg17181.html|Fossil mailing list] |
| 68 | 2014-09-01.</i> |
| 69 | </p> |
| 70 | |
| 71 | <li>If programmers _really_ wanted to help scientists, they'd build a version control |
| 72 | system that was more usable than Git. |
| 73 | |
| 74 | <p class="local-indent"> |
| 75 | <i>Tweet by Greg Wilson @gvwilson on 2015-02-22 17:47</i> |
| 76 | </p> |
| 77 | |
| 78 | <li><img src='xkcd-git.gif' align='top'> |
| 79 | |
| 80 | <p class="local-indent"><i>Randall Munroe. [http://xkcd.com/1597/]</i><p> |
| 81 | |
| 82 | </ol> |
| 83 | |
| 84 | <h2>On The Usability Of Fossil</h2> |
| 85 | |
| 86 | <ol> |
| 87 | <li value=11> |
| 88 | Fossil mesmerizes me with simplicity especially after I struggled to |
| 89 | get a bug-tracking system to work with mercurial. |
| 90 | |
| 91 | <p class="local-indent"> |
| 92 | <i>rawjeev at [https://stackoverflow.com/a/2100469/142454]</i> |
| 93 | </p> |
| 94 | |
| 95 | <li>Fossil is the best thing to happen |
| 96 | to my development workflow this year, as I am pretty sure that using |
| 97 | Git has resulted in the premature death of too many of my brain cells. |
| 98 | I'm glad to be able to replace Git in every place that I possibly can |
| 99 | with Fossil. |
| 100 | |
| 101 | <p class="local-indent"> |
| 102 | <i>Joe Prostko at [http://www.mail-archive.com/[email protected]/msg16716.html] |
| 103 | </p> |
| 104 | |
| 105 | <li>This is my favourite VCS. I can carry it on a USB. And it's a complete system, with it's own |
| 106 | server, ticketing system, Wiki pages, and a very, very helpful timeline visualization. And |
| 107 | the entire program in a single file! |
| 108 | |
| 109 | <p class="local-indent"> |
| 110 | <i>thunderbong commenting on hacker news: [https://news.ycombinator.com/item?id=9131619]</i> |
| 111 | </p> |
| 112 | |
| 113 | |
| 114 | </ol> |
| 115 | |
| 116 | |
| @@ -118,33 +118,33 @@ | |
| 118 | |
| 119 | <ol> |
| 120 | <li value=14> |
| 121 | After prolonged exposure to fossil, i tend to get the jitters when I work with git... |
| 122 | |
| 123 | <p class="local-indent"> |
| 124 | <i>sriku - at [https://news.ycombinator.com/item?id=16104427]</i> |
| 125 | </p> |
| 126 | |
| 127 | |
| 128 | <li> |
| 129 | Just want to say thanks for fossil making my life easier.... |
| 130 | Also <nowiki>[for]</nowiki> not having a misanthropic command line interface. |
| 131 | |
| 132 | <p class="local-indent"> |
| 133 | <i>Joshua Paine at [http://www.mail-archive.com/[email protected]/msg02736.html]</i> |
| 134 | </p> |
| 135 | |
| 136 | <li>We use it at a large university to manage code that small teams write. |
| 137 | The runs everywhere, ease of installation and portability is something that |
| 138 | seems to be a good fit with the environment we have (highly ditrobuted, |
| 139 | sometimes very restrictive firewalls, OSX/Win/Linux). We are happy with it |
| 140 | and teaching a Msc/Phd student (read complete novice) fossil has just |
| 141 | been a smoother ride than Git was. |
| 142 | |
| 143 | <p class="local-indent"> |
| 144 | <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> |
| 145 | </p> |
| 146 | |
| 147 | <li>In the fossil community - and hence in fossil itself - development history |
| 148 | is pretty much sacrosanct. The very name "fossil" was to chosen to |
| 149 | reflect the unchanging nature of things in that history. |
| 150 | <br><br> |
| @@ -151,21 +151,21 @@ | |
| 151 | In git (or rather, the git community), the development history is part of |
| 152 | the published aspect of the project, so it provides tools for rearranging |
| 153 | that history so you can present what you "should" have done rather |
| 154 | than what you actually did. |
| 155 | |
| 156 | <p class="local-indent"> |
| 157 | <i>Mike Meyer on the Fossil mailing list, 2011-10-04</i> |
| 158 | </p> |
| 159 | |
| 160 | <li>github is such a pale shadow of what fossil does. |
| 161 | |
| 162 | <p class="local-indent"> |
| 163 | <i>dkf on the Tcl chatroom, 2013-12-06</i> |
| 164 | </p> |
| 165 | |
| 166 | <li>[With fossil] I actually enjoy keeping track of source files again. |
| 167 | |
| 168 | <p class="local-indent"> |
| 169 | <a href="https://wholesomedonut.prose.sh/using-fossil-not-git">https://wholesomedonut.prose.sh/using-fossil-not-git</a> |
| 170 | </p> |
| 171 | </ol> |
| 172 |
+6
-6
| --- www/reviews.wiki | ||
| +++ www/reviews.wiki | ||
| @@ -8,21 +8,21 @@ | ||
| 8 | 8 | |
| 9 | 9 | * [./quotes.wiki | Short Quotes on Fossil, Git, And DVCSes] |
| 10 | 10 | |
| 11 | 11 | <b>Daniel writes on 2009-01-06:</b> |
| 12 | 12 | |
| 13 | -<blockquote> | |
| 13 | +<div class="indent"> | |
| 14 | 14 | The reasons I use fossil are that it's the only version control I |
| 15 | 15 | have found that I can get working through the VERY annoying MS |
| 16 | 16 | firewalls at work.. (albeit through an ntlm proxy) and I just love |
| 17 | 17 | single .exe applications! |
| 18 | -</blockquote> | |
| 18 | +</div> | |
| 19 | 19 | |
| 20 | 20 | |
| 21 | 21 | <b>Joshua Paine on 2010-10-22:</b> |
| 22 | 22 | |
| 23 | -<blockquote> | |
| 23 | +<div class="indent"> | |
| 24 | 24 | With one of my several hats on, I'm in a small team using git. Another |
| 25 | 25 | team member just checked some stuff into trunk that should have been on |
| 26 | 26 | a branch. Nothing else had happened since, so in fossil I would have |
| 27 | 27 | just edited that commit and put it on a new branch. In git that can't |
| 28 | 28 | actually be done without danger once other people have pulled, so I had |
| @@ -30,15 +30,15 @@ | ||
| 30 | 30 | pick the earlier changes, then figure out how to make my new branch |
| 31 | 31 | shared instead of private. Just want to say thanks for fossil making my |
| 32 | 32 | life easier on most of my projects, and being able to move commits to |
| 33 | 33 | another branch after the fact and shared-by-default branches are good |
| 34 | 34 | features. Also not having a misanthropic command line interface. |
| 35 | -</blockquote> | |
| 35 | +</div> | |
| 36 | 36 | |
| 37 | 37 | <b>Stephan Beal writes on 2009-01-11:</b> |
| 38 | 38 | |
| 39 | -<blockquote> | |
| 39 | +<div class="indent"> | |
| 40 | 40 | Sometime in late 2007 I came across a link to fossil on |
| 41 | 41 | <a href="http://www.sqlite.org/">sqlite.org</a>. It |
| 42 | 42 | was a good thing I bookmarked it, because I was never able to find the |
| 43 | 43 | link again (it might have been in a bug report or something). The |
| 44 | 44 | reasons I first took a close look at it were (A) it stemmed from the |
| @@ -135,6 +135,6 @@ | ||
| 135 | 135 | sitting on our hard drives but which don't justify the hassle of |
| 136 | 136 | version control)." A year of daily use in over 15 source trees has |
| 137 | 137 | confirmed that, and I continue to heartily recommend fossil to other |
| 138 | 138 | developers I know who also have their own collection of "unhosted" pet |
| 139 | 139 | projects. |
| 140 | -</blockquote> | |
| 140 | +</div> | |
| 141 | 141 |
| --- www/reviews.wiki | |
| +++ www/reviews.wiki | |
| @@ -8,21 +8,21 @@ | |
| 8 | |
| 9 | * [./quotes.wiki | Short Quotes on Fossil, Git, And DVCSes] |
| 10 | |
| 11 | <b>Daniel writes on 2009-01-06:</b> |
| 12 | |
| 13 | <blockquote> |
| 14 | The reasons I use fossil are that it's the only version control I |
| 15 | have found that I can get working through the VERY annoying MS |
| 16 | firewalls at work.. (albeit through an ntlm proxy) and I just love |
| 17 | single .exe applications! |
| 18 | </blockquote> |
| 19 | |
| 20 | |
| 21 | <b>Joshua Paine on 2010-10-22:</b> |
| 22 | |
| 23 | <blockquote> |
| 24 | With one of my several hats on, I'm in a small team using git. Another |
| 25 | team member just checked some stuff into trunk that should have been on |
| 26 | a branch. Nothing else had happened since, so in fossil I would have |
| 27 | just edited that commit and put it on a new branch. In git that can't |
| 28 | actually be done without danger once other people have pulled, so I had |
| @@ -30,15 +30,15 @@ | |
| 30 | pick the earlier changes, then figure out how to make my new branch |
| 31 | shared instead of private. Just want to say thanks for fossil making my |
| 32 | life easier on most of my projects, and being able to move commits to |
| 33 | another branch after the fact and shared-by-default branches are good |
| 34 | features. Also not having a misanthropic command line interface. |
| 35 | </blockquote> |
| 36 | |
| 37 | <b>Stephan Beal writes on 2009-01-11:</b> |
| 38 | |
| 39 | <blockquote> |
| 40 | Sometime in late 2007 I came across a link to fossil on |
| 41 | <a href="http://www.sqlite.org/">sqlite.org</a>. It |
| 42 | was a good thing I bookmarked it, because I was never able to find the |
| 43 | link again (it might have been in a bug report or something). The |
| 44 | reasons I first took a close look at it were (A) it stemmed from the |
| @@ -135,6 +135,6 @@ | |
| 135 | sitting on our hard drives but which don't justify the hassle of |
| 136 | version control)." A year of daily use in over 15 source trees has |
| 137 | confirmed that, and I continue to heartily recommend fossil to other |
| 138 | developers I know who also have their own collection of "unhosted" pet |
| 139 | projects. |
| 140 | </blockquote> |
| 141 |
| --- www/reviews.wiki | |
| +++ www/reviews.wiki | |
| @@ -8,21 +8,21 @@ | |
| 8 | |
| 9 | * [./quotes.wiki | Short Quotes on Fossil, Git, And DVCSes] |
| 10 | |
| 11 | <b>Daniel writes on 2009-01-06:</b> |
| 12 | |
| 13 | <div class="indent"> |
| 14 | The reasons I use fossil are that it's the only version control I |
| 15 | have found that I can get working through the VERY annoying MS |
| 16 | firewalls at work.. (albeit through an ntlm proxy) and I just love |
| 17 | single .exe applications! |
| 18 | </div> |
| 19 | |
| 20 | |
| 21 | <b>Joshua Paine on 2010-10-22:</b> |
| 22 | |
| 23 | <div class="indent"> |
| 24 | With one of my several hats on, I'm in a small team using git. Another |
| 25 | team member just checked some stuff into trunk that should have been on |
| 26 | a branch. Nothing else had happened since, so in fossil I would have |
| 27 | just edited that commit and put it on a new branch. In git that can't |
| 28 | actually be done without danger once other people have pulled, so I had |
| @@ -30,15 +30,15 @@ | |
| 30 | pick the earlier changes, then figure out how to make my new branch |
| 31 | shared instead of private. Just want to say thanks for fossil making my |
| 32 | life easier on most of my projects, and being able to move commits to |
| 33 | another branch after the fact and shared-by-default branches are good |
| 34 | features. Also not having a misanthropic command line interface. |
| 35 | </div> |
| 36 | |
| 37 | <b>Stephan Beal writes on 2009-01-11:</b> |
| 38 | |
| 39 | <div class="indent"> |
| 40 | Sometime in late 2007 I came across a link to fossil on |
| 41 | <a href="http://www.sqlite.org/">sqlite.org</a>. It |
| 42 | was a good thing I bookmarked it, because I was never able to find the |
| 43 | link again (it might have been in a bug report or something). The |
| 44 | reasons I first took a close look at it were (A) it stemmed from the |
| @@ -135,6 +135,6 @@ | |
| 135 | sitting on our hard drives but which don't justify the hassle of |
| 136 | version control)." A year of daily use in over 15 source trees has |
| 137 | confirmed that, and I continue to heartily recommend fossil to other |
| 138 | developers I know who also have their own collection of "unhosted" pet |
| 139 | projects. |
| 140 | </div> |
| 141 |
+4
-4
| --- www/scgi.wiki | ||
| +++ www/scgi.wiki | ||
| @@ -2,26 +2,26 @@ | ||
| 2 | 2 | |
| 3 | 3 | To run Fossil using SCGI, start the [/help/server|fossil server] command |
| 4 | 4 | with the --scgi command-line option. You will probably also want to |
| 5 | 5 | specific an alternative TCP/IP port using --port. For example: |
| 6 | 6 | |
| 7 | -<blockquote><pre> | |
| 7 | +<pre> | |
| 8 | 8 | fossil server $REPOSITORY --port 9000 --scgi |
| 9 | -</pre></blockquote> | |
| 9 | +</pre> | |
| 10 | 10 | |
| 11 | 11 | Then configure your SCGI-aware web-server to send SCGI requests to port |
| 12 | 12 | 9000 on the machine where Fossil is running. A typical configuration for |
| 13 | 13 | this in Nginx is: |
| 14 | 14 | |
| 15 | -<blockquote><pre> | |
| 15 | +<pre> | |
| 16 | 16 | location ~ ^/demo_project/ { |
| 17 | 17 | include scgi_params; |
| 18 | 18 | scgi_pass localhost:9000; |
| 19 | 19 | scgi_param SCRIPT_NAME "/demo_project"; |
| 20 | 20 | scgi_param HTTPS "on"; |
| 21 | 21 | } |
| 22 | -</pre></blockquote> | |
| 22 | +</pre> | |
| 23 | 23 | |
| 24 | 24 | Note that Nginx does not normally send either the PATH_INFO or SCRIPT_NAME |
| 25 | 25 | variables via SCGI, but Fossil needs one or the other. So the configuration |
| 26 | 26 | above needs to add SCRIPT_NAME. If you do not do this, Fossil returns an |
| 27 | 27 | error. |
| 28 | 28 |
| --- www/scgi.wiki | |
| +++ www/scgi.wiki | |
| @@ -2,26 +2,26 @@ | |
| 2 | |
| 3 | To run Fossil using SCGI, start the [/help/server|fossil server] command |
| 4 | with the --scgi command-line option. You will probably also want to |
| 5 | specific an alternative TCP/IP port using --port. For example: |
| 6 | |
| 7 | <blockquote><pre> |
| 8 | fossil server $REPOSITORY --port 9000 --scgi |
| 9 | </pre></blockquote> |
| 10 | |
| 11 | Then configure your SCGI-aware web-server to send SCGI requests to port |
| 12 | 9000 on the machine where Fossil is running. A typical configuration for |
| 13 | this in Nginx is: |
| 14 | |
| 15 | <blockquote><pre> |
| 16 | location ~ ^/demo_project/ { |
| 17 | include scgi_params; |
| 18 | scgi_pass localhost:9000; |
| 19 | scgi_param SCRIPT_NAME "/demo_project"; |
| 20 | scgi_param HTTPS "on"; |
| 21 | } |
| 22 | </pre></blockquote> |
| 23 | |
| 24 | Note that Nginx does not normally send either the PATH_INFO or SCRIPT_NAME |
| 25 | variables via SCGI, but Fossil needs one or the other. So the configuration |
| 26 | above needs to add SCRIPT_NAME. If you do not do this, Fossil returns an |
| 27 | error. |
| 28 |
| --- www/scgi.wiki | |
| +++ www/scgi.wiki | |
| @@ -2,26 +2,26 @@ | |
| 2 | |
| 3 | To run Fossil using SCGI, start the [/help/server|fossil server] command |
| 4 | with the --scgi command-line option. You will probably also want to |
| 5 | specific an alternative TCP/IP port using --port. For example: |
| 6 | |
| 7 | <pre> |
| 8 | fossil server $REPOSITORY --port 9000 --scgi |
| 9 | </pre> |
| 10 | |
| 11 | Then configure your SCGI-aware web-server to send SCGI requests to port |
| 12 | 9000 on the machine where Fossil is running. A typical configuration for |
| 13 | this in Nginx is: |
| 14 | |
| 15 | <pre> |
| 16 | location ~ ^/demo_project/ { |
| 17 | include scgi_params; |
| 18 | scgi_pass localhost:9000; |
| 19 | scgi_param SCRIPT_NAME "/demo_project"; |
| 20 | scgi_param HTTPS "on"; |
| 21 | } |
| 22 | </pre> |
| 23 | |
| 24 | Note that Nginx does not normally send either the PATH_INFO or SCRIPT_NAME |
| 25 | variables via SCGI, but Fossil needs one or the other. So the configuration |
| 26 | above needs to add SCRIPT_NAME. If you do not do this, Fossil returns an |
| 27 | error. |
| 28 |
-2
| --- www/selfcheck.wiki | ||
| +++ www/selfcheck.wiki | ||
| @@ -1,9 +1,7 @@ | ||
| 1 | 1 | <title>Fossil Repository Integrity Self-Checks</title> |
| 2 | 2 | |
| 3 | -<h1 align="center">Fossil Repository Integrity Self-Checks</h1> | |
| 4 | - | |
| 5 | 3 | Fossil is designed with features to give it a high level |
| 6 | 4 | of integrity so that users can have confidence that content will |
| 7 | 5 | never be mangled or lost by Fossil. |
| 8 | 6 | This note describes the defensive measures that |
| 9 | 7 | Fossil uses to help prevent information loss due to bugs. |
| 10 | 8 |
| --- www/selfcheck.wiki | |
| +++ www/selfcheck.wiki | |
| @@ -1,9 +1,7 @@ | |
| 1 | <title>Fossil Repository Integrity Self-Checks</title> |
| 2 | |
| 3 | <h1 align="center">Fossil Repository Integrity Self-Checks</h1> |
| 4 | |
| 5 | Fossil is designed with features to give it a high level |
| 6 | of integrity so that users can have confidence that content will |
| 7 | never be mangled or lost by Fossil. |
| 8 | This note describes the defensive measures that |
| 9 | Fossil uses to help prevent information loss due to bugs. |
| 10 |
| --- www/selfcheck.wiki | |
| +++ www/selfcheck.wiki | |
| @@ -1,9 +1,7 @@ | |
| 1 | <title>Fossil Repository Integrity Self-Checks</title> |
| 2 | |
| 3 | Fossil is designed with features to give it a high level |
| 4 | of integrity so that users can have confidence that content will |
| 5 | never be mangled or lost by Fossil. |
| 6 | This note describes the defensive measures that |
| 7 | Fossil uses to help prevent information loss due to bugs. |
| 8 |
+6
-6
| --- www/selfhost.wiki | ||
| +++ www/selfhost.wiki | ||
| @@ -30,14 +30,14 @@ | ||
| 30 | 30 | Multiple fossil-based projects can easily be hosted on the same machine, |
| 31 | 31 | even if that machine is itself one of several dozen virtual machines on |
| 32 | 32 | single physical box. The CGI script that runs the canonical Fossil |
| 33 | 33 | self-hosting repository is as follows: |
| 34 | 34 | |
| 35 | -<blockquote><pre> | |
| 35 | +<pre> | |
| 36 | 36 | #!/usr/bin/fossil |
| 37 | 37 | repository: /fossil/fossil.fossil |
| 38 | -</pre></blockquote> | |
| 38 | +</pre> | |
| 39 | 39 | |
| 40 | 40 | Server (3) ran for 10 years as a CGI script on a shared hosting account at |
| 41 | 41 | <a href="http://www.he.net/">Hurricane Electric</a> in Fremont, CA. |
| 42 | 42 | This server demonstrated the ability of |
| 43 | 43 | Fossil to run on an economical shared-host web account with no |
| @@ -48,14 +48,14 @@ | ||
| 48 | 48 | that can run in |
| 49 | 49 | such a restricted environment. The CGI script that ran on the |
| 50 | 50 | Hurricane Electric server was the same as the CGI script shown above, |
| 51 | 51 | except that the pathnames are modified to suit the environment: |
| 52 | 52 | |
| 53 | -<blockquote><pre> | |
| 53 | +<pre> | |
| 54 | 54 | #!/home/hwaci/bin/fossil |
| 55 | 55 | repository: /home/hwaci/fossil/fossil.fossil |
| 56 | -</pre></blockquote> | |
| 56 | +</pre> | |
| 57 | 57 | |
| 58 | 58 | In recent years, virtual private servers have become a more flexible and |
| 59 | 59 | less expensive hosting option compared to shared hosting accounts. |
| 60 | 60 | So on 2017-07-25, server (3) was moved |
| 61 | 61 | onto a $5/month "droplet" [https://en.wikipedia.org/wiki/Virtual_private_server|VPS] |
| @@ -63,15 +63,15 @@ | ||
| 63 | 63 | located in San Francisco. |
| 64 | 64 | |
| 65 | 65 | Server (3) is synchronized with the canonical server (1) by running |
| 66 | 66 | a command similar to the following via cron: |
| 67 | 67 | |
| 68 | -<blockquote><pre> | |
| 68 | +<pre> | |
| 69 | 69 | /usr/local/bin/fossil all sync -u |
| 70 | -</pre></blockquote> | |
| 70 | +</pre> | |
| 71 | 71 | |
| 72 | 72 | Server (2) is a |
| 73 | 73 | <a href="http://www.linode.com/">Linode 4096</a> located in Newark, NJ |
| 74 | 74 | and set up just like the canonical server (1) with the addition of a |
| 75 | 75 | cron job for synchronization. The same cron job also runs the |
| 76 | 76 | [/help?cmd=git|fossil git export] command after each sync in order to |
| 77 | 77 | [./mirrortogithub.md#ex1|mirror all changes to GitHub]. |
| 78 | 78 |
| --- www/selfhost.wiki | |
| +++ www/selfhost.wiki | |
| @@ -30,14 +30,14 @@ | |
| 30 | Multiple fossil-based projects can easily be hosted on the same machine, |
| 31 | even if that machine is itself one of several dozen virtual machines on |
| 32 | single physical box. The CGI script that runs the canonical Fossil |
| 33 | self-hosting repository is as follows: |
| 34 | |
| 35 | <blockquote><pre> |
| 36 | #!/usr/bin/fossil |
| 37 | repository: /fossil/fossil.fossil |
| 38 | </pre></blockquote> |
| 39 | |
| 40 | Server (3) ran for 10 years as a CGI script on a shared hosting account at |
| 41 | <a href="http://www.he.net/">Hurricane Electric</a> in Fremont, CA. |
| 42 | This server demonstrated the ability of |
| 43 | Fossil to run on an economical shared-host web account with no |
| @@ -48,14 +48,14 @@ | |
| 48 | that can run in |
| 49 | such a restricted environment. The CGI script that ran on the |
| 50 | Hurricane Electric server was the same as the CGI script shown above, |
| 51 | except that the pathnames are modified to suit the environment: |
| 52 | |
| 53 | <blockquote><pre> |
| 54 | #!/home/hwaci/bin/fossil |
| 55 | repository: /home/hwaci/fossil/fossil.fossil |
| 56 | </pre></blockquote> |
| 57 | |
| 58 | In recent years, virtual private servers have become a more flexible and |
| 59 | less expensive hosting option compared to shared hosting accounts. |
| 60 | So on 2017-07-25, server (3) was moved |
| 61 | onto a $5/month "droplet" [https://en.wikipedia.org/wiki/Virtual_private_server|VPS] |
| @@ -63,15 +63,15 @@ | |
| 63 | located in San Francisco. |
| 64 | |
| 65 | Server (3) is synchronized with the canonical server (1) by running |
| 66 | a command similar to the following via cron: |
| 67 | |
| 68 | <blockquote><pre> |
| 69 | /usr/local/bin/fossil all sync -u |
| 70 | </pre></blockquote> |
| 71 | |
| 72 | Server (2) is a |
| 73 | <a href="http://www.linode.com/">Linode 4096</a> located in Newark, NJ |
| 74 | and set up just like the canonical server (1) with the addition of a |
| 75 | cron job for synchronization. The same cron job also runs the |
| 76 | [/help?cmd=git|fossil git export] command after each sync in order to |
| 77 | [./mirrortogithub.md#ex1|mirror all changes to GitHub]. |
| 78 |
| --- www/selfhost.wiki | |
| +++ www/selfhost.wiki | |
| @@ -30,14 +30,14 @@ | |
| 30 | Multiple fossil-based projects can easily be hosted on the same machine, |
| 31 | even if that machine is itself one of several dozen virtual machines on |
| 32 | single physical box. The CGI script that runs the canonical Fossil |
| 33 | self-hosting repository is as follows: |
| 34 | |
| 35 | <pre> |
| 36 | #!/usr/bin/fossil |
| 37 | repository: /fossil/fossil.fossil |
| 38 | </pre> |
| 39 | |
| 40 | Server (3) ran for 10 years as a CGI script on a shared hosting account at |
| 41 | <a href="http://www.he.net/">Hurricane Electric</a> in Fremont, CA. |
| 42 | This server demonstrated the ability of |
| 43 | Fossil to run on an economical shared-host web account with no |
| @@ -48,14 +48,14 @@ | |
| 48 | that can run in |
| 49 | such a restricted environment. The CGI script that ran on the |
| 50 | Hurricane Electric server was the same as the CGI script shown above, |
| 51 | except that the pathnames are modified to suit the environment: |
| 52 | |
| 53 | <pre> |
| 54 | #!/home/hwaci/bin/fossil |
| 55 | repository: /home/hwaci/fossil/fossil.fossil |
| 56 | </pre> |
| 57 | |
| 58 | In recent years, virtual private servers have become a more flexible and |
| 59 | less expensive hosting option compared to shared hosting accounts. |
| 60 | So on 2017-07-25, server (3) was moved |
| 61 | onto a $5/month "droplet" [https://en.wikipedia.org/wiki/Virtual_private_server|VPS] |
| @@ -63,15 +63,15 @@ | |
| 63 | located in San Francisco. |
| 64 | |
| 65 | Server (3) is synchronized with the canonical server (1) by running |
| 66 | a command similar to the following via cron: |
| 67 | |
| 68 | <pre> |
| 69 | /usr/local/bin/fossil all sync -u |
| 70 | </pre> |
| 71 | |
| 72 | Server (2) is a |
| 73 | <a href="http://www.linode.com/">Linode 4096</a> located in Newark, NJ |
| 74 | and set up just like the canonical server (1) with the addition of a |
| 75 | cron job for synchronization. The same cron job also runs the |
| 76 | [/help?cmd=git|fossil git export] command after each sync in order to |
| 77 | [./mirrortogithub.md#ex1|mirror all changes to GitHub]. |
| 78 |
+9
-9
| --- www/server/any/cgi.md | ||
| +++ www/server/any/cgi.md | ||
| @@ -8,12 +8,12 @@ | ||
| 8 | 8 | on the CGI protocol. |
| 9 | 9 | |
| 10 | 10 | To run Fossil as CGI, create a CGI script (here called "repo") in the |
| 11 | 11 | CGI directory of your web server with content like this: |
| 12 | 12 | |
| 13 | - #!/usr/bin/fossil | |
| 14 | - repository: /home/fossil/repo.fossil | |
| 13 | + #!/usr/bin/fossil | |
| 14 | + repository: /home/fossil/repo.fossil | |
| 15 | 15 | |
| 16 | 16 | Adjust the paths appropriately. It may be necessary to set certain |
| 17 | 17 | permissions on this file or to modify an `.htaccess` file or make other |
| 18 | 18 | server-specific changes. Consult the documentation for your particular |
| 19 | 19 | web server. The following permissions are *normally* required, but, |
| @@ -57,13 +57,13 @@ | ||
| 57 | 57 | To serve multiple repositories from a directory using CGI, use the |
| 58 | 58 | "directory:" tag in the CGI script rather than "repository:". You |
| 59 | 59 | might also want to add a "notfound:" tag to tell where to redirect if |
| 60 | 60 | the particular repository requested by the URL is not found: |
| 61 | 61 | |
| 62 | - #!/usr/bin/fossil | |
| 63 | - directory: /home/fossil/repos | |
| 64 | - notfound: http://url-to-go-to-if-repo-not-found/ | |
| 62 | + #!/usr/bin/fossil | |
| 63 | + directory: /home/fossil/repos | |
| 64 | + notfound: http://url-to-go-to-if-repo-not-found/ | |
| 65 | 65 | |
| 66 | 66 | Once deployed, a URL like: <b>http://mydomain.org/cgi-bin/repo/XYZ</b> |
| 67 | 67 | will serve up the repository `/home/fossil/repos/XYZ.fossil` if it |
| 68 | 68 | exists. |
| 69 | 69 | |
| @@ -79,14 +79,14 @@ | ||
| 79 | 79 | However, Fossil in CGI mode needs it in order to generate the correct links. |
| 80 | 80 | |
| 81 | 81 | Apache can be instructed to pass this parameter further to the CGI scripts for |
| 82 | 82 | TLS connections with a stanza like |
| 83 | 83 | |
| 84 | - SetEnvIf X-Forwarded-Proto "https" HTTPS=on | |
| 85 | - | |
| 84 | + SetEnvIf X-Forwarded-Proto "https" HTTPS=on | |
| 85 | + | |
| 86 | 86 | in its config file section for CGI, provided that |
| 87 | 87 | |
| 88 | - proxy_set_header X-Forwarded-Proto $scheme; | |
| 89 | - | |
| 88 | + proxy_set_header X-Forwarded-Proto $scheme; | |
| 89 | + | |
| 90 | 90 | has been be added in the relevant proxying section of the Nginx config file. |
| 91 | 91 | |
| 92 | 92 | *[Return to the top-level Fossil server article.](../)* |
| 93 | 93 |
| --- www/server/any/cgi.md | |
| +++ www/server/any/cgi.md | |
| @@ -8,12 +8,12 @@ | |
| 8 | on the CGI protocol. |
| 9 | |
| 10 | To run Fossil as CGI, create a CGI script (here called "repo") in the |
| 11 | CGI directory of your web server with content like this: |
| 12 | |
| 13 | #!/usr/bin/fossil |
| 14 | repository: /home/fossil/repo.fossil |
| 15 | |
| 16 | Adjust the paths appropriately. It may be necessary to set certain |
| 17 | permissions on this file or to modify an `.htaccess` file or make other |
| 18 | server-specific changes. Consult the documentation for your particular |
| 19 | web server. The following permissions are *normally* required, but, |
| @@ -57,13 +57,13 @@ | |
| 57 | To serve multiple repositories from a directory using CGI, use the |
| 58 | "directory:" tag in the CGI script rather than "repository:". You |
| 59 | might also want to add a "notfound:" tag to tell where to redirect if |
| 60 | the particular repository requested by the URL is not found: |
| 61 | |
| 62 | #!/usr/bin/fossil |
| 63 | directory: /home/fossil/repos |
| 64 | notfound: http://url-to-go-to-if-repo-not-found/ |
| 65 | |
| 66 | Once deployed, a URL like: <b>http://mydomain.org/cgi-bin/repo/XYZ</b> |
| 67 | will serve up the repository `/home/fossil/repos/XYZ.fossil` if it |
| 68 | exists. |
| 69 | |
| @@ -79,14 +79,14 @@ | |
| 79 | However, Fossil in CGI mode needs it in order to generate the correct links. |
| 80 | |
| 81 | Apache can be instructed to pass this parameter further to the CGI scripts for |
| 82 | TLS connections with a stanza like |
| 83 | |
| 84 | SetEnvIf X-Forwarded-Proto "https" HTTPS=on |
| 85 | |
| 86 | in its config file section for CGI, provided that |
| 87 | |
| 88 | proxy_set_header X-Forwarded-Proto $scheme; |
| 89 | |
| 90 | has been be added in the relevant proxying section of the Nginx config file. |
| 91 | |
| 92 | *[Return to the top-level Fossil server article.](../)* |
| 93 |
| --- www/server/any/cgi.md | |
| +++ www/server/any/cgi.md | |
| @@ -8,12 +8,12 @@ | |
| 8 | on the CGI protocol. |
| 9 | |
| 10 | To run Fossil as CGI, create a CGI script (here called "repo") in the |
| 11 | CGI directory of your web server with content like this: |
| 12 | |
| 13 | #!/usr/bin/fossil |
| 14 | repository: /home/fossil/repo.fossil |
| 15 | |
| 16 | Adjust the paths appropriately. It may be necessary to set certain |
| 17 | permissions on this file or to modify an `.htaccess` file or make other |
| 18 | server-specific changes. Consult the documentation for your particular |
| 19 | web server. The following permissions are *normally* required, but, |
| @@ -57,13 +57,13 @@ | |
| 57 | To serve multiple repositories from a directory using CGI, use the |
| 58 | "directory:" tag in the CGI script rather than "repository:". You |
| 59 | might also want to add a "notfound:" tag to tell where to redirect if |
| 60 | the particular repository requested by the URL is not found: |
| 61 | |
| 62 | #!/usr/bin/fossil |
| 63 | directory: /home/fossil/repos |
| 64 | notfound: http://url-to-go-to-if-repo-not-found/ |
| 65 | |
| 66 | Once deployed, a URL like: <b>http://mydomain.org/cgi-bin/repo/XYZ</b> |
| 67 | will serve up the repository `/home/fossil/repos/XYZ.fossil` if it |
| 68 | exists. |
| 69 | |
| @@ -79,14 +79,14 @@ | |
| 79 | However, Fossil in CGI mode needs it in order to generate the correct links. |
| 80 | |
| 81 | Apache can be instructed to pass this parameter further to the CGI scripts for |
| 82 | TLS connections with a stanza like |
| 83 | |
| 84 | SetEnvIf X-Forwarded-Proto "https" HTTPS=on |
| 85 | |
| 86 | in its config file section for CGI, provided that |
| 87 | |
| 88 | proxy_set_header X-Forwarded-Proto $scheme; |
| 89 | |
| 90 | has been be added in the relevant proxying section of the Nginx config file. |
| 91 | |
| 92 | *[Return to the top-level Fossil server article.](../)* |
| 93 |
+26
-26
| --- www/server/any/http-over-ssh.md | ||
| +++ www/server/any/http-over-ssh.md | ||
| @@ -15,15 +15,15 @@ | ||
| 15 | 15 | |
| 16 | 16 | Put something like the following into the `sshd_config` file on the |
| 17 | 17 | Fossil repository server: |
| 18 | 18 | |
| 19 | 19 | ``` ssh-config |
| 20 | - Match Group fossil | |
| 21 | - X11Forwarding no | |
| 22 | - AllowTcpForwarding no | |
| 23 | - AllowAgentForwarding no | |
| 24 | - ForceCommand /home/fossil/bin/wrapper | |
| 20 | +Match Group fossil | |
| 21 | + X11Forwarding no | |
| 22 | + AllowTcpForwarding no | |
| 23 | + AllowAgentForwarding no | |
| 24 | + ForceCommand /home/fossil/bin/wrapper | |
| 25 | 25 | ``` |
| 26 | 26 | |
| 27 | 27 | This file is usually found in `/etc/ssh`, but some OSes put it |
| 28 | 28 | elsewhere. |
| 29 | 29 | |
| @@ -30,11 +30,11 @@ | ||
| 30 | 30 | The first line presumes that we will put all users who need to use our |
| 31 | 31 | Fossil repositories into the `fossil` group, as we will do |
| 32 | 32 | [below](#perms). You could instead say something like: |
| 33 | 33 | |
| 34 | 34 | ``` ssh-config |
| 35 | - Match User alice,bob,carol,dave | |
| 35 | +Match User alice,bob,carol,dave | |
| 36 | 36 | ``` |
| 37 | 37 | |
| 38 | 38 | You have to list the users allowed to use Fossil in this case because |
| 39 | 39 | your system likely has a system administrator that uses SSH for remote |
| 40 | 40 | shell access, so you want to *exclude* that user from the list. For the |
| @@ -42,11 +42,11 @@ | ||
| 42 | 42 | a `Match` block of some sort. |
| 43 | 43 | |
| 44 | 44 | You could instead list the exceptions: |
| 45 | 45 | |
| 46 | 46 | ``` ssh-config |
| 47 | - Match User !evi | |
| 47 | +Match User !evi | |
| 48 | 48 | ``` |
| 49 | 49 | |
| 50 | 50 | This would permit only [Evi the System Administrator][evi] to bypass this |
| 51 | 51 | mechanism. |
| 52 | 52 | |
| @@ -68,16 +68,16 @@ | ||
| 68 | 68 | and rewrite other parts to make this work. |
| 69 | 69 | |
| 70 | 70 | Here is a simpler variant of Andy’s original wrapper script: |
| 71 | 71 | |
| 72 | 72 | ``` sh |
| 73 | - #!/bin/bash | |
| 74 | - set -- $SSH_ORIGINAL_COMMAND | |
| 75 | - while [ $# -gt 1 ] ; do shift ; done | |
| 76 | - export REMOTE_USER="$USER" | |
| 77 | - ROOT=/home/fossil | |
| 78 | - exec "$ROOT/bin/fossil" http "$ROOT/museum/$(/bin/basename "$1")" | |
| 73 | +#!/bin/bash | |
| 74 | +set -- $SSH_ORIGINAL_COMMAND | |
| 75 | +while [ $# -gt 1 ] ; do shift ; done | |
| 76 | +export REMOTE_USER="$USER" | |
| 77 | +ROOT=/home/fossil | |
| 78 | +exec "$ROOT/bin/fossil" http "$ROOT/museum/$(/bin/basename "$1")" | |
| 79 | 79 | ``` |
| 80 | 80 | |
| 81 | 81 | The substantive changes are: |
| 82 | 82 | |
| 83 | 83 | 1. Move the command rewriting bits to the start. |
| @@ -104,11 +104,11 @@ | ||
| 104 | 104 | check the absolute paths for local correctness: is `/bin/basename` |
| 105 | 105 | installed on your system, for example? |
| 106 | 106 | |
| 107 | 107 | Under this scheme, you clone with a command like: |
| 108 | 108 | |
| 109 | - $ fossil clone ssh://HOST/repo.fossil | |
| 109 | + $ fossil clone ssh://HOST/repo.fossil | |
| 110 | 110 | |
| 111 | 111 | This will clone the remote `/home/fossil/museum/repo.fossil` repository |
| 112 | 112 | to your local machine under the same name and open it into a “`repo/`” |
| 113 | 113 | subdirectory. Notice that we didn’t have to give the `museum/` part of |
| 114 | 114 | the path: it’s implicit per point #3 above. |
| @@ -129,20 +129,20 @@ | ||
| 129 | 129 | repositories are stored. |
| 130 | 130 | |
| 131 | 131 | You can achieve all of this on a Linux box with: |
| 132 | 132 | |
| 133 | 133 | ``` shell |
| 134 | - sudo adduser fossil | |
| 135 | - for u in alice bob carol dave ; do | |
| 136 | - sudo adduser $u | |
| 137 | - sudo gpasswd -a fossil $u | |
| 138 | - done | |
| 139 | - sudo -i -u fossil | |
| 140 | - chmod 710 . | |
| 141 | - mkdir -m 750 bin | |
| 142 | - mkdir -m 770 museum | |
| 143 | - ln -s /usr/local/bin/fossil bin | |
| 134 | +sudo adduser fossil | |
| 135 | +for u in alice bob carol dave ; do | |
| 136 | + sudo adduser $u | |
| 137 | + sudo gpasswd -a fossil $u | |
| 138 | +done | |
| 139 | +sudo -i -u fossil | |
| 140 | +chmod 710 . | |
| 141 | +mkdir -m 750 bin | |
| 142 | +mkdir -m 770 museum | |
| 143 | +ln -s /usr/local/bin/fossil bin | |
| 144 | 144 | ``` |
| 145 | 145 | |
| 146 | 146 | You then need to copy the Fossil repositories into `~fossil/museum` and |
| 147 | 147 | make them readable and writable by group `fossil`. These repositories |
| 148 | 148 | presumably already have Fossil users configured, with the necessary |
| @@ -153,12 +153,12 @@ | ||
| 153 | 153 | Fossil only pays attention to this environment variable in certain |
| 154 | 154 | contexts, of which “`fossil http`” is not one. Run this command against |
| 155 | 155 | each repo to allow that: |
| 156 | 156 | |
| 157 | 157 | ``` shell |
| 158 | - echo "INSERT OR REPLACE INTO config VALUES ('remote_user_ok',1,strftime('%s','now'));" | | |
| 159 | - fossil sql -R museum/repo.fossil | |
| 158 | +echo "INSERT OR REPLACE INTO config VALUES ('remote_user_ok',1,strftime('%s','now'));" | | |
| 159 | +fossil sql -R museum/repo.fossil | |
| 160 | 160 | ``` |
| 161 | 161 | |
| 162 | 162 | Now you can configure SSH authentication for each user. Since Fossil’s |
| 163 | 163 | password-saving feature doesn’t work in this case, I suggest setting up |
| 164 | 164 | SSH keys via `~USER/.ssh/authorized_keys` since the SSH authentication |
| 165 | 165 |
| --- www/server/any/http-over-ssh.md | |
| +++ www/server/any/http-over-ssh.md | |
| @@ -15,15 +15,15 @@ | |
| 15 | |
| 16 | Put something like the following into the `sshd_config` file on the |
| 17 | Fossil repository server: |
| 18 | |
| 19 | ``` ssh-config |
| 20 | Match Group fossil |
| 21 | X11Forwarding no |
| 22 | AllowTcpForwarding no |
| 23 | AllowAgentForwarding no |
| 24 | ForceCommand /home/fossil/bin/wrapper |
| 25 | ``` |
| 26 | |
| 27 | This file is usually found in `/etc/ssh`, but some OSes put it |
| 28 | elsewhere. |
| 29 | |
| @@ -30,11 +30,11 @@ | |
| 30 | The first line presumes that we will put all users who need to use our |
| 31 | Fossil repositories into the `fossil` group, as we will do |
| 32 | [below](#perms). You could instead say something like: |
| 33 | |
| 34 | ``` ssh-config |
| 35 | Match User alice,bob,carol,dave |
| 36 | ``` |
| 37 | |
| 38 | You have to list the users allowed to use Fossil in this case because |
| 39 | your system likely has a system administrator that uses SSH for remote |
| 40 | shell access, so you want to *exclude* that user from the list. For the |
| @@ -42,11 +42,11 @@ | |
| 42 | a `Match` block of some sort. |
| 43 | |
| 44 | You could instead list the exceptions: |
| 45 | |
| 46 | ``` ssh-config |
| 47 | Match User !evi |
| 48 | ``` |
| 49 | |
| 50 | This would permit only [Evi the System Administrator][evi] to bypass this |
| 51 | mechanism. |
| 52 | |
| @@ -68,16 +68,16 @@ | |
| 68 | and rewrite other parts to make this work. |
| 69 | |
| 70 | Here is a simpler variant of Andy’s original wrapper script: |
| 71 | |
| 72 | ``` sh |
| 73 | #!/bin/bash |
| 74 | set -- $SSH_ORIGINAL_COMMAND |
| 75 | while [ $# -gt 1 ] ; do shift ; done |
| 76 | export REMOTE_USER="$USER" |
| 77 | ROOT=/home/fossil |
| 78 | exec "$ROOT/bin/fossil" http "$ROOT/museum/$(/bin/basename "$1")" |
| 79 | ``` |
| 80 | |
| 81 | The substantive changes are: |
| 82 | |
| 83 | 1. Move the command rewriting bits to the start. |
| @@ -104,11 +104,11 @@ | |
| 104 | check the absolute paths for local correctness: is `/bin/basename` |
| 105 | installed on your system, for example? |
| 106 | |
| 107 | Under this scheme, you clone with a command like: |
| 108 | |
| 109 | $ fossil clone ssh://HOST/repo.fossil |
| 110 | |
| 111 | This will clone the remote `/home/fossil/museum/repo.fossil` repository |
| 112 | to your local machine under the same name and open it into a “`repo/`” |
| 113 | subdirectory. Notice that we didn’t have to give the `museum/` part of |
| 114 | the path: it’s implicit per point #3 above. |
| @@ -129,20 +129,20 @@ | |
| 129 | repositories are stored. |
| 130 | |
| 131 | You can achieve all of this on a Linux box with: |
| 132 | |
| 133 | ``` shell |
| 134 | sudo adduser fossil |
| 135 | for u in alice bob carol dave ; do |
| 136 | sudo adduser $u |
| 137 | sudo gpasswd -a fossil $u |
| 138 | done |
| 139 | sudo -i -u fossil |
| 140 | chmod 710 . |
| 141 | mkdir -m 750 bin |
| 142 | mkdir -m 770 museum |
| 143 | ln -s /usr/local/bin/fossil bin |
| 144 | ``` |
| 145 | |
| 146 | You then need to copy the Fossil repositories into `~fossil/museum` and |
| 147 | make them readable and writable by group `fossil`. These repositories |
| 148 | presumably already have Fossil users configured, with the necessary |
| @@ -153,12 +153,12 @@ | |
| 153 | Fossil only pays attention to this environment variable in certain |
| 154 | contexts, of which “`fossil http`” is not one. Run this command against |
| 155 | each repo to allow that: |
| 156 | |
| 157 | ``` shell |
| 158 | echo "INSERT OR REPLACE INTO config VALUES ('remote_user_ok',1,strftime('%s','now'));" | |
| 159 | fossil sql -R museum/repo.fossil |
| 160 | ``` |
| 161 | |
| 162 | Now you can configure SSH authentication for each user. Since Fossil’s |
| 163 | password-saving feature doesn’t work in this case, I suggest setting up |
| 164 | SSH keys via `~USER/.ssh/authorized_keys` since the SSH authentication |
| 165 |
| --- www/server/any/http-over-ssh.md | |
| +++ www/server/any/http-over-ssh.md | |
| @@ -15,15 +15,15 @@ | |
| 15 | |
| 16 | Put something like the following into the `sshd_config` file on the |
| 17 | Fossil repository server: |
| 18 | |
| 19 | ``` ssh-config |
| 20 | Match Group fossil |
| 21 | X11Forwarding no |
| 22 | AllowTcpForwarding no |
| 23 | AllowAgentForwarding no |
| 24 | ForceCommand /home/fossil/bin/wrapper |
| 25 | ``` |
| 26 | |
| 27 | This file is usually found in `/etc/ssh`, but some OSes put it |
| 28 | elsewhere. |
| 29 | |
| @@ -30,11 +30,11 @@ | |
| 30 | The first line presumes that we will put all users who need to use our |
| 31 | Fossil repositories into the `fossil` group, as we will do |
| 32 | [below](#perms). You could instead say something like: |
| 33 | |
| 34 | ``` ssh-config |
| 35 | Match User alice,bob,carol,dave |
| 36 | ``` |
| 37 | |
| 38 | You have to list the users allowed to use Fossil in this case because |
| 39 | your system likely has a system administrator that uses SSH for remote |
| 40 | shell access, so you want to *exclude* that user from the list. For the |
| @@ -42,11 +42,11 @@ | |
| 42 | a `Match` block of some sort. |
| 43 | |
| 44 | You could instead list the exceptions: |
| 45 | |
| 46 | ``` ssh-config |
| 47 | Match User !evi |
| 48 | ``` |
| 49 | |
| 50 | This would permit only [Evi the System Administrator][evi] to bypass this |
| 51 | mechanism. |
| 52 | |
| @@ -68,16 +68,16 @@ | |
| 68 | and rewrite other parts to make this work. |
| 69 | |
| 70 | Here is a simpler variant of Andy’s original wrapper script: |
| 71 | |
| 72 | ``` sh |
| 73 | #!/bin/bash |
| 74 | set -- $SSH_ORIGINAL_COMMAND |
| 75 | while [ $# -gt 1 ] ; do shift ; done |
| 76 | export REMOTE_USER="$USER" |
| 77 | ROOT=/home/fossil |
| 78 | exec "$ROOT/bin/fossil" http "$ROOT/museum/$(/bin/basename "$1")" |
| 79 | ``` |
| 80 | |
| 81 | The substantive changes are: |
| 82 | |
| 83 | 1. Move the command rewriting bits to the start. |
| @@ -104,11 +104,11 @@ | |
| 104 | check the absolute paths for local correctness: is `/bin/basename` |
| 105 | installed on your system, for example? |
| 106 | |
| 107 | Under this scheme, you clone with a command like: |
| 108 | |
| 109 | $ fossil clone ssh://HOST/repo.fossil |
| 110 | |
| 111 | This will clone the remote `/home/fossil/museum/repo.fossil` repository |
| 112 | to your local machine under the same name and open it into a “`repo/`” |
| 113 | subdirectory. Notice that we didn’t have to give the `museum/` part of |
| 114 | the path: it’s implicit per point #3 above. |
| @@ -129,20 +129,20 @@ | |
| 129 | repositories are stored. |
| 130 | |
| 131 | You can achieve all of this on a Linux box with: |
| 132 | |
| 133 | ``` shell |
| 134 | sudo adduser fossil |
| 135 | for u in alice bob carol dave ; do |
| 136 | sudo adduser $u |
| 137 | sudo gpasswd -a fossil $u |
| 138 | done |
| 139 | sudo -i -u fossil |
| 140 | chmod 710 . |
| 141 | mkdir -m 750 bin |
| 142 | mkdir -m 770 museum |
| 143 | ln -s /usr/local/bin/fossil bin |
| 144 | ``` |
| 145 | |
| 146 | You then need to copy the Fossil repositories into `~fossil/museum` and |
| 147 | make them readable and writable by group `fossil`. These repositories |
| 148 | presumably already have Fossil users configured, with the necessary |
| @@ -153,12 +153,12 @@ | |
| 153 | Fossil only pays attention to this environment variable in certain |
| 154 | contexts, of which “`fossil http`” is not one. Run this command against |
| 155 | each repo to allow that: |
| 156 | |
| 157 | ``` shell |
| 158 | echo "INSERT OR REPLACE INTO config VALUES ('remote_user_ok',1,strftime('%s','now'));" | |
| 159 | fossil sql -R museum/repo.fossil |
| 160 | ``` |
| 161 | |
| 162 | Now you can configure SSH authentication for each user. Since Fossil’s |
| 163 | password-saving feature doesn’t work in this case, I suggest setting up |
| 164 | SSH keys via `~USER/.ssh/authorized_keys` since the SSH authentication |
| 165 |
+2
-2
| --- www/server/any/inetd.md | ||
| +++ www/server/any/inetd.md | ||
| @@ -2,11 +2,11 @@ | ||
| 2 | 2 | |
| 3 | 3 | A Fossil server can be launched on-demand by `inetd` by using the |
| 4 | 4 | [`fossil http`](/help/http) command. To do so, add a line like the |
| 5 | 5 | following to its configuration file, typically `/etc/inetd.conf`: |
| 6 | 6 | |
| 7 | - 80 stream tcp nowait.1000 root /usr/bin/fossil /usr/bin/fossil http /home/fossil/repo.fossil | |
| 7 | + 80 stream tcp nowait.1000 root /usr/bin/fossil /usr/bin/fossil http /home/fossil/repo.fossil | |
| 8 | 8 | |
| 9 | 9 | In this example, you are telling `inetd` that when an incoming |
| 10 | 10 | connection appears on TCP port 80 that it should launch the program |
| 11 | 11 | `/usr/bin/fossil` with the arguments shown. Obviously you will need to |
| 12 | 12 | modify the pathnames for your particular setup. The final argument is |
| @@ -17,11 +17,11 @@ | ||
| 17 | 17 | specification must be a symbolic name and cannot be numeric, add the |
| 18 | 18 | desired name and port to `/etc/services`. For example, if you want your |
| 19 | 19 | Fossil server running on TCP port 12345 instead of 80, you will need to |
| 20 | 20 | add: |
| 21 | 21 | |
| 22 | - fossil 12345/tcp # fossil server | |
| 22 | + fossil 12345/tcp # fossil server | |
| 23 | 23 | |
| 24 | 24 | and use the symbolic name “`fossil`” instead of the numeric TCP port |
| 25 | 25 | number (“12345” in the above example) in `inetd.conf`. |
| 26 | 26 | |
| 27 | 27 | Notice that we configured `inetd` to launch Fossil as root. See the |
| 28 | 28 |
| --- www/server/any/inetd.md | |
| +++ www/server/any/inetd.md | |
| @@ -2,11 +2,11 @@ | |
| 2 | |
| 3 | A Fossil server can be launched on-demand by `inetd` by using the |
| 4 | [`fossil http`](/help/http) command. To do so, add a line like the |
| 5 | following to its configuration file, typically `/etc/inetd.conf`: |
| 6 | |
| 7 | 80 stream tcp nowait.1000 root /usr/bin/fossil /usr/bin/fossil http /home/fossil/repo.fossil |
| 8 | |
| 9 | In this example, you are telling `inetd` that when an incoming |
| 10 | connection appears on TCP port 80 that it should launch the program |
| 11 | `/usr/bin/fossil` with the arguments shown. Obviously you will need to |
| 12 | modify the pathnames for your particular setup. The final argument is |
| @@ -17,11 +17,11 @@ | |
| 17 | specification must be a symbolic name and cannot be numeric, add the |
| 18 | desired name and port to `/etc/services`. For example, if you want your |
| 19 | Fossil server running on TCP port 12345 instead of 80, you will need to |
| 20 | add: |
| 21 | |
| 22 | fossil 12345/tcp # fossil server |
| 23 | |
| 24 | and use the symbolic name “`fossil`” instead of the numeric TCP port |
| 25 | number (“12345” in the above example) in `inetd.conf`. |
| 26 | |
| 27 | Notice that we configured `inetd` to launch Fossil as root. See the |
| 28 |
| --- www/server/any/inetd.md | |
| +++ www/server/any/inetd.md | |
| @@ -2,11 +2,11 @@ | |
| 2 | |
| 3 | A Fossil server can be launched on-demand by `inetd` by using the |
| 4 | [`fossil http`](/help/http) command. To do so, add a line like the |
| 5 | following to its configuration file, typically `/etc/inetd.conf`: |
| 6 | |
| 7 | 80 stream tcp nowait.1000 root /usr/bin/fossil /usr/bin/fossil http /home/fossil/repo.fossil |
| 8 | |
| 9 | In this example, you are telling `inetd` that when an incoming |
| 10 | connection appears on TCP port 80 that it should launch the program |
| 11 | `/usr/bin/fossil` with the arguments shown. Obviously you will need to |
| 12 | modify the pathnames for your particular setup. The final argument is |
| @@ -17,11 +17,11 @@ | |
| 17 | specification must be a symbolic name and cannot be numeric, add the |
| 18 | desired name and port to `/etc/services`. For example, if you want your |
| 19 | Fossil server running on TCP port 12345 instead of 80, you will need to |
| 20 | add: |
| 21 | |
| 22 | fossil 12345/tcp # fossil server |
| 23 | |
| 24 | and use the symbolic name “`fossil`” instead of the numeric TCP port |
| 25 | number (“12345” in the above example) in `inetd.conf`. |
| 26 | |
| 27 | Notice that we configured `inetd` to launch Fossil as root. See the |
| 28 |
+3
-3
| --- www/server/any/none.md | ||
| +++ www/server/any/none.md | ||
| @@ -28,19 +28,19 @@ | ||
| 28 | 28 | |
| 29 | 29 | You can omit the _REPOSITORY_ argument if you run one of the above |
| 30 | 30 | commands from within a Fossil checkout directory to serve that |
| 31 | 31 | repository: |
| 32 | 32 | |
| 33 | - $ fossil ui # or... | |
| 34 | - $ fossil server | |
| 33 | + $ fossil ui # or... | |
| 34 | + $ fossil server | |
| 35 | 35 | |
| 36 | 36 | You can abbreviate Fossil sub-commands as long as they are unambiguous. |
| 37 | 37 | “`server`” can currently be as short as “`ser`”. |
| 38 | 38 | |
| 39 | 39 | You can serve a directory containing multiple `*.fossil` files like so: |
| 40 | 40 | |
| 41 | - $ fossil server --port 9000 --repolist /path/to/repo/dir | |
| 41 | + $ fossil server --port 9000 --repolist /path/to/repo/dir | |
| 42 | 42 | |
| 43 | 43 | There is an [example script](/file/tools/fslsrv) in the Fossil |
| 44 | 44 | distribution that wraps `fossil server` to produce more complicated |
| 45 | 45 | effects. Feel free to take it, study it, and modify it to suit your |
| 46 | 46 | local needs. |
| 47 | 47 |
| --- www/server/any/none.md | |
| +++ www/server/any/none.md | |
| @@ -28,19 +28,19 @@ | |
| 28 | |
| 29 | You can omit the _REPOSITORY_ argument if you run one of the above |
| 30 | commands from within a Fossil checkout directory to serve that |
| 31 | repository: |
| 32 | |
| 33 | $ fossil ui # or... |
| 34 | $ fossil server |
| 35 | |
| 36 | You can abbreviate Fossil sub-commands as long as they are unambiguous. |
| 37 | “`server`” can currently be as short as “`ser`”. |
| 38 | |
| 39 | You can serve a directory containing multiple `*.fossil` files like so: |
| 40 | |
| 41 | $ fossil server --port 9000 --repolist /path/to/repo/dir |
| 42 | |
| 43 | There is an [example script](/file/tools/fslsrv) in the Fossil |
| 44 | distribution that wraps `fossil server` to produce more complicated |
| 45 | effects. Feel free to take it, study it, and modify it to suit your |
| 46 | local needs. |
| 47 |
| --- www/server/any/none.md | |
| +++ www/server/any/none.md | |
| @@ -28,19 +28,19 @@ | |
| 28 | |
| 29 | You can omit the _REPOSITORY_ argument if you run one of the above |
| 30 | commands from within a Fossil checkout directory to serve that |
| 31 | repository: |
| 32 | |
| 33 | $ fossil ui # or... |
| 34 | $ fossil server |
| 35 | |
| 36 | You can abbreviate Fossil sub-commands as long as they are unambiguous. |
| 37 | “`server`” can currently be as short as “`ser`”. |
| 38 | |
| 39 | You can serve a directory containing multiple `*.fossil` files like so: |
| 40 | |
| 41 | $ fossil server --port 9000 --repolist /path/to/repo/dir |
| 42 | |
| 43 | There is an [example script](/file/tools/fslsrv) in the Fossil |
| 44 | distribution that wraps `fossil server` to produce more complicated |
| 45 | effects. Feel free to take it, study it, and modify it to suit your |
| 46 | local needs. |
| 47 |
+6
-6
| --- www/server/any/scgi.md | ||
| +++ www/server/any/scgi.md | ||
| @@ -9,15 +9,15 @@ | ||
| 9 | 9 | This can be used with a web server such as [nginx](http://nginx.org) |
| 10 | 10 | which does not support [Fossil’s CGI mode](./cgi.md). |
| 11 | 11 | |
| 12 | 12 | A basic nginx configuration to support SCGI with Fossil looks like this: |
| 13 | 13 | |
| 14 | - location /code/ { | |
| 15 | - include scgi_params; | |
| 16 | - scgi_param SCRIPT_NAME "/code"; | |
| 17 | - scgi_pass localhost:9000; | |
| 18 | - } | |
| 14 | + location /code/ { | |
| 15 | + include scgi_params; | |
| 16 | + scgi_param SCRIPT_NAME "/code"; | |
| 17 | + scgi_pass localhost:9000; | |
| 18 | + } | |
| 19 | 19 | |
| 20 | 20 | The `scgi_params` file comes with nginx, and it simply translates nginx |
| 21 | 21 | internal variables to `scgi_param` directives to create SCGI environment |
| 22 | 22 | variables for the proxied program; in this case, Fossil. Our explicit |
| 23 | 23 | `scgi_param` call to define `SCRIPT_NAME` adds one more variable to this |
| @@ -28,11 +28,11 @@ | ||
| 28 | 28 | |
| 29 | 29 | The final directive simply tells nginx to proxy all calls to URLs under |
| 30 | 30 | `/code` down to an SCGI program on TCP port 9000. We can temporarily |
| 31 | 31 | set Fossil up as a server on that port like so: |
| 32 | 32 | |
| 33 | - $ fossil server /path/to/repo.fossil --scgi --localhost --port 9000 & | |
| 33 | + $ fossil server /path/to/repo.fossil --scgi --localhost --port 9000 & | |
| 34 | 34 | |
| 35 | 35 | The `--scgi` option switches Fossil into SCGI mode from its default, |
| 36 | 36 | which is [stand-alone HTTP server mode](./none.md). All of the other |
| 37 | 37 | options discussed in that linked document — such as the ability to serve |
| 38 | 38 | a directory full of Fossil repositories rather than just a single |
| 39 | 39 |
| --- www/server/any/scgi.md | |
| +++ www/server/any/scgi.md | |
| @@ -9,15 +9,15 @@ | |
| 9 | This can be used with a web server such as [nginx](http://nginx.org) |
| 10 | which does not support [Fossil’s CGI mode](./cgi.md). |
| 11 | |
| 12 | A basic nginx configuration to support SCGI with Fossil looks like this: |
| 13 | |
| 14 | location /code/ { |
| 15 | include scgi_params; |
| 16 | scgi_param SCRIPT_NAME "/code"; |
| 17 | scgi_pass localhost:9000; |
| 18 | } |
| 19 | |
| 20 | The `scgi_params` file comes with nginx, and it simply translates nginx |
| 21 | internal variables to `scgi_param` directives to create SCGI environment |
| 22 | variables for the proxied program; in this case, Fossil. Our explicit |
| 23 | `scgi_param` call to define `SCRIPT_NAME` adds one more variable to this |
| @@ -28,11 +28,11 @@ | |
| 28 | |
| 29 | The final directive simply tells nginx to proxy all calls to URLs under |
| 30 | `/code` down to an SCGI program on TCP port 9000. We can temporarily |
| 31 | set Fossil up as a server on that port like so: |
| 32 | |
| 33 | $ fossil server /path/to/repo.fossil --scgi --localhost --port 9000 & |
| 34 | |
| 35 | The `--scgi` option switches Fossil into SCGI mode from its default, |
| 36 | which is [stand-alone HTTP server mode](./none.md). All of the other |
| 37 | options discussed in that linked document — such as the ability to serve |
| 38 | a directory full of Fossil repositories rather than just a single |
| 39 |
| --- www/server/any/scgi.md | |
| +++ www/server/any/scgi.md | |
| @@ -9,15 +9,15 @@ | |
| 9 | This can be used with a web server such as [nginx](http://nginx.org) |
| 10 | which does not support [Fossil’s CGI mode](./cgi.md). |
| 11 | |
| 12 | A basic nginx configuration to support SCGI with Fossil looks like this: |
| 13 | |
| 14 | location /code/ { |
| 15 | include scgi_params; |
| 16 | scgi_param SCRIPT_NAME "/code"; |
| 17 | scgi_pass localhost:9000; |
| 18 | } |
| 19 | |
| 20 | The `scgi_params` file comes with nginx, and it simply translates nginx |
| 21 | internal variables to `scgi_param` directives to create SCGI environment |
| 22 | variables for the proxied program; in this case, Fossil. Our explicit |
| 23 | `scgi_param` call to define `SCRIPT_NAME` adds one more variable to this |
| @@ -28,11 +28,11 @@ | |
| 28 | |
| 29 | The final directive simply tells nginx to proxy all calls to URLs under |
| 30 | `/code` down to an SCGI program on TCP port 9000. We can temporarily |
| 31 | set Fossil up as a server on that port like so: |
| 32 | |
| 33 | $ fossil server /path/to/repo.fossil --scgi --localhost --port 9000 & |
| 34 | |
| 35 | The `--scgi` option switches Fossil into SCGI mode from its default, |
| 36 | which is [stand-alone HTTP server mode](./none.md). All of the other |
| 37 | options discussed in that linked document — such as the ability to serve |
| 38 | a directory full of Fossil repositories rather than just a single |
| 39 |
+9
-9
| --- www/server/any/xinetd.md | ||
| +++ www/server/any/xinetd.md | ||
| @@ -6,19 +6,19 @@ | ||
| 6 | 6 | |
| 7 | 7 | The typical configuration file is either `/etc/xinetd.conf` or a subfile |
| 8 | 8 | in the `/etc/xinetd.d` directory. You need a configuration something |
| 9 | 9 | like this for Fossil: |
| 10 | 10 | |
| 11 | - service http | |
| 12 | - { | |
| 13 | - port = 80 | |
| 14 | - socket_type = stream | |
| 15 | - wait = no | |
| 16 | - user = root | |
| 17 | - server = /usr/bin/fossil | |
| 18 | - server_args = http /home/fossil/repos/ | |
| 19 | - } | |
| 11 | + service http | |
| 12 | + { | |
| 13 | + port = 80 | |
| 14 | + socket_type = stream | |
| 15 | + wait = no | |
| 16 | + user = root | |
| 17 | + server = /usr/bin/fossil | |
| 18 | + server_args = http /home/fossil/repos/ | |
| 19 | + } | |
| 20 | 20 | |
| 21 | 21 | This example configures Fossil to serve multiple repositories under the |
| 22 | 22 | `/home/fossil/repos/` directory. |
| 23 | 23 | |
| 24 | 24 | Beyond this, see the general commentary in our article on [the `inetd` |
| 25 | 25 |
| --- www/server/any/xinetd.md | |
| +++ www/server/any/xinetd.md | |
| @@ -6,19 +6,19 @@ | |
| 6 | |
| 7 | The typical configuration file is either `/etc/xinetd.conf` or a subfile |
| 8 | in the `/etc/xinetd.d` directory. You need a configuration something |
| 9 | like this for Fossil: |
| 10 | |
| 11 | service http |
| 12 | { |
| 13 | port = 80 |
| 14 | socket_type = stream |
| 15 | wait = no |
| 16 | user = root |
| 17 | server = /usr/bin/fossil |
| 18 | server_args = http /home/fossil/repos/ |
| 19 | } |
| 20 | |
| 21 | This example configures Fossil to serve multiple repositories under the |
| 22 | `/home/fossil/repos/` directory. |
| 23 | |
| 24 | Beyond this, see the general commentary in our article on [the `inetd` |
| 25 |
| --- www/server/any/xinetd.md | |
| +++ www/server/any/xinetd.md | |
| @@ -6,19 +6,19 @@ | |
| 6 | |
| 7 | The typical configuration file is either `/etc/xinetd.conf` or a subfile |
| 8 | in the `/etc/xinetd.d` directory. You need a configuration something |
| 9 | like this for Fossil: |
| 10 | |
| 11 | service http |
| 12 | { |
| 13 | port = 80 |
| 14 | socket_type = stream |
| 15 | wait = no |
| 16 | user = root |
| 17 | server = /usr/bin/fossil |
| 18 | server_args = http /home/fossil/repos/ |
| 19 | } |
| 20 | |
| 21 | This example configures Fossil to serve multiple repositories under the |
| 22 | `/home/fossil/repos/` directory. |
| 23 | |
| 24 | Beyond this, see the general commentary in our article on [the `inetd` |
| 25 |
+46
-48
| --- www/server/debian/nginx.md | ||
| +++ www/server/debian/nginx.md | ||
| @@ -101,11 +101,11 @@ | ||
| 101 | 101 | ## <a id="deps"></a>Installing the Dependencies |
| 102 | 102 | |
| 103 | 103 | The first step is to install some non-default packages we’ll need. SSH into |
| 104 | 104 | your server, then say: |
| 105 | 105 | |
| 106 | - $ sudo apt install fossil nginx | |
| 106 | + $ sudo apt install fossil nginx | |
| 107 | 107 | |
| 108 | 108 | You can leave “`fossil`” out of that if you’re building Fossil from |
| 109 | 109 | source to get a more up-to-date version than is shipped with the host |
| 110 | 110 | OS. |
| 111 | 111 | |
| @@ -131,12 +131,12 @@ | ||
| 131 | 131 | On Debian and Ubuntu systems the primary user-level configuration file |
| 132 | 132 | for nginx is `/etc/nginx/sites-enabled/default`. I recommend that this |
| 133 | 133 | file contain only a list of include statements, one for each site that |
| 134 | 134 | server hosts: |
| 135 | 135 | |
| 136 | - include local/example.com | |
| 137 | - include local/foo.net | |
| 136 | + include local/example.com | |
| 137 | + include local/foo.net | |
| 138 | 138 | |
| 139 | 139 | Those files then each define one domain’s configuration. Here, |
| 140 | 140 | `/etc/nginx/local/example.com` contains the configuration for |
| 141 | 141 | `*.example.com` and its alias `*.example.net`; and `local/foo.net` |
| 142 | 142 | contains the configuration for `*.foo.net`. |
| @@ -197,13 +197,13 @@ | ||
| 197 | 197 | configuration for SCGI][scgii], showing off a few ideas you might want to |
| 198 | 198 | try on your own site, such as static asset proxying. |
| 199 | 199 | |
| 200 | 200 | You also need a `local/code` file containing: |
| 201 | 201 | |
| 202 | - include scgi_params; | |
| 203 | - scgi_pass 127.0.0.1:12345; | |
| 204 | - scgi_param SCRIPT_NAME "/code"; | |
| 202 | + include scgi_params; | |
| 203 | + scgi_pass 127.0.0.1:12345; | |
| 204 | + scgi_param SCRIPT_NAME "/code"; | |
| 205 | 205 | |
| 206 | 206 | We separate that out because nginx refuses to inherit certain settings |
| 207 | 207 | between nested location blocks, so rather than repeat them, we extract |
| 208 | 208 | them to this separate file and include it from both locations where it’s |
| 209 | 209 | needed. You see this above where we set far-future expiration dates on |
| @@ -213,16 +213,16 @@ | ||
| 213 | 213 | Fossil-based site considerably faster. |
| 214 | 214 | |
| 215 | 215 | Similarly, the `local/generic` file referenced above helps us reduce unnecessary |
| 216 | 216 | repetition among the multiple sites this configuration hosts: |
| 217 | 217 | |
| 218 | - root /var/www/$host; | |
| 218 | + root /var/www/$host; | |
| 219 | 219 | |
| 220 | - listen 80; | |
| 221 | - listen [::]:80; | |
| 220 | + listen 80; | |
| 221 | + listen [::]:80; | |
| 222 | 222 | |
| 223 | - charset utf-8; | |
| 223 | + charset utf-8; | |
| 224 | 224 | |
| 225 | 225 | There are some configuration directives that nginx refuses to substitute |
| 226 | 226 | variables into, citing performance considerations, so there is a limit |
| 227 | 227 | to how much repetition you can squeeze out this way. One such example |
| 228 | 228 | are the `access_log` and `error_log` directives, which follow an obvious |
| @@ -246,14 +246,14 @@ | ||
| 246 | 246 | |
| 247 | 247 | However, it is still worth showing the proper method of proxying |
| 248 | 248 | Fossil’s HTTP server through nginx if only to make reading nginx |
| 249 | 249 | documentation on other sites easier: |
| 250 | 250 | |
| 251 | - location /code { | |
| 252 | - rewrite ^/code(/.*) $1 break; | |
| 253 | - proxy_pass http://127.0.0.1:12345; | |
| 254 | - } | |
| 251 | + location /code { | |
| 252 | + rewrite ^/code(/.*) $1 break; | |
| 253 | + proxy_pass http://127.0.0.1:12345; | |
| 254 | + } | |
| 255 | 255 | |
| 256 | 256 | The most common thing people get wrong when hand-rolling a configuration |
| 257 | 257 | like this is to get the slashes wrong. Fossil is sensitive to this. For |
| 258 | 258 | instance, Fossil will not collapse double slashes down to a single |
| 259 | 259 | slash, as some other HTTP servers will. |
| @@ -267,12 +267,12 @@ | ||
| 267 | 267 | a problem, but when sending [unversioned content][uv], it uses a single |
| 268 | 268 | message for the entire file. Therefore, if you will be storing files |
| 269 | 269 | larger than this limit as unversioned content, you need to raise the |
| 270 | 270 | limit. Within the `location` block: |
| 271 | 271 | |
| 272 | - # Allow large unversioned file uploads, such as PDFs | |
| 273 | - client_max_body_size 20M; | |
| 272 | + # Allow large unversioned file uploads, such as PDFs | |
| 273 | + client_max_body_size 20M; | |
| 274 | 274 | |
| 275 | 275 | [uv]: ../../unvers.wiki |
| 276 | 276 | |
| 277 | 277 | |
| 278 | 278 | ## <a id="fail2ban"></a> Integrating `fail2ban` |
| @@ -285,32 +285,32 @@ | ||
| 285 | 285 | Fossil behind an nginx proxy, we convert these failures to log file |
| 286 | 286 | form, which `fail2ban` is designed to handle. |
| 287 | 287 | |
| 288 | 288 | First, install `fail2ban`, if you haven’t already: |
| 289 | 289 | |
| 290 | - sudo apt install fail2ban | |
| 290 | + sudo apt install fail2ban | |
| 291 | 291 | |
| 292 | 292 | We’d like `fail2ban` to react to Fossil `/login` failures. The stock |
| 293 | 293 | configuration of `fail2ban` only detects a few common sorts of SSH |
| 294 | 294 | attacks by default, and its included (but disabled) nginx attack |
| 295 | 295 | detectors don’t include one that knows how to detect an attack on |
| 296 | 296 | Fossil. We have to teach it by putting the following into |
| 297 | 297 | `/etc/fail2ban/filter.d/nginx-fossil-login.conf`: |
| 298 | 298 | |
| 299 | - [Definition] | |
| 300 | - failregex = ^<HOST> - .*POST .*/login HTTP/..." 401 | |
| 299 | + [Definition] | |
| 300 | + failregex = ^<HOST> - .*POST .*/login HTTP/..." 401 | |
| 301 | 301 | |
| 302 | 302 | That teaches `fail2ban` how to recognize the errors logged by Fossil |
| 303 | 303 | [as of 2.14](/info/39d7eb0e22). (Earlier versions of Fossil returned |
| 304 | 304 | HTTP status code 200 for this, so you couldn’t distinguish a successful |
| 305 | 305 | login from a failure.) |
| 306 | 306 | |
| 307 | 307 | Then in `/etc/fail2ban/jail.local`, add this section: |
| 308 | 308 | |
| 309 | - [nginx-fossil-login] | |
| 310 | - enabled = true | |
| 311 | - logpath = /var/log/nginx/*-https-access.log | |
| 309 | + [nginx-fossil-login] | |
| 310 | + enabled = true | |
| 311 | + logpath = /var/log/nginx/*-https-access.log | |
| 312 | 312 | |
| 313 | 313 | The last line is the key: it tells `fail2ban` where we’ve put all of our |
| 314 | 314 | per-repo access logs in the nginx config above. |
| 315 | 315 | |
| 316 | 316 | There’s a [lot more you can do][dof2b], but that gets us out of scope of |
| @@ -338,44 +338,42 @@ | ||
| 338 | 338 | |
| 339 | 339 | You may wish to include something like this from each `server { }` |
| 340 | 340 | block in your configuration to enable TLS in a common, secure way: |
| 341 | 341 | |
| 342 | 342 | ``` |
| 343 | - # Tell nginx to accept TLS-encrypted HTTPS on the standard TCP port. | |
| 344 | - listen 443 ssl; | |
| 345 | - listen [::]:443 ssl; | |
| 346 | - | |
| 347 | - # Reference the TLS cert files produced by Certbot. | |
| 348 | - ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; | |
| 349 | - ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem; | |
| 350 | - | |
| 351 | - # Load the Let's Encrypt Diffie-Hellman parameters generated for | |
| 352 | - # this server. Without this, the server is vulnerable to Logjam. | |
| 353 | - ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; | |
| 354 | - | |
| 355 | - # Tighten things down further, per Qualys’ and Certbot’s advice. | |
| 356 | - ssl_session_cache shared:le_nginx_SSL:1m; | |
| 357 | - ssl_protocols TLSv1.2 TLSv1.3; | |
| 358 | - ssl_prefer_server_ciphers on; | |
| 359 | - ssl_session_timeout 1440m; | |
| 360 | - | |
| 361 | - # Offer OCSP certificate stapling. | |
| 362 | - ssl_stapling on; | |
| 363 | - ssl_stapling_verify on; | |
| 364 | - | |
| 365 | - # Enable HSTS. | |
| 366 | - include local/enable-hsts; | |
| 343 | +# Tell nginx to accept TLS-encrypted HTTPS on the standard TCP port. | |
| 344 | +listen 443 ssl; | |
| 345 | +listen [::]:443 ssl; | |
| 346 | + | |
| 347 | +# Reference the TLS cert files produced by Certbot. | |
| 348 | +ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; | |
| 349 | +ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem; | |
| 350 | + | |
| 351 | +# Load the Let's Encrypt Diffie-Hellman parameters generated for | |
| 352 | +# this server. Without this, the server is vulnerable to Logjam. | |
| 353 | +ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; | |
| 354 | + | |
| 355 | +# Tighten things down further, per Qualys’ and Certbot’s advice. | |
| 356 | +ssl_session_cache shared:le_nginx_SSL:1m; | |
| 357 | +ssl_protocols TLSv1.2 TLSv1.3; | |
| 358 | +ssl_prefer_server_ciphers on; | |
| 359 | +ssl_session_timeout 1440m; | |
| 360 | + | |
| 361 | +# Offer OCSP certificate stapling. | |
| 362 | +ssl_stapling on; | |
| 363 | +ssl_stapling_verify on; | |
| 364 | + | |
| 365 | +# Enable HSTS. | |
| 366 | +include local/enable-hsts; | |
| 367 | 367 | ``` |
| 368 | 368 | |
| 369 | 369 | The [HSTS] step is optional and should be applied only after due |
| 370 | 370 | consideration, since it has the potential to lock users out of your |
| 371 | 371 | site if you later change your mind on the TLS configuration. |
| 372 | 372 | The `local/enable-hsts` file it references is simply: |
| 373 | 373 | |
| 374 | -``` | |
| 375 | 374 | add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always; |
| 376 | -``` | |
| 377 | 375 | |
| 378 | 376 | It’s a separate file because nginx requires that headers like this be |
| 379 | 377 | applied separately for each `location { }` block. We’ve therefore |
| 380 | 378 | factored this out so you can `include` it everywhere you need it. |
| 381 | 379 | |
| 382 | 380 |
| --- www/server/debian/nginx.md | |
| +++ www/server/debian/nginx.md | |
| @@ -101,11 +101,11 @@ | |
| 101 | ## <a id="deps"></a>Installing the Dependencies |
| 102 | |
| 103 | The first step is to install some non-default packages we’ll need. SSH into |
| 104 | your server, then say: |
| 105 | |
| 106 | $ sudo apt install fossil nginx |
| 107 | |
| 108 | You can leave “`fossil`” out of that if you’re building Fossil from |
| 109 | source to get a more up-to-date version than is shipped with the host |
| 110 | OS. |
| 111 | |
| @@ -131,12 +131,12 @@ | |
| 131 | On Debian and Ubuntu systems the primary user-level configuration file |
| 132 | for nginx is `/etc/nginx/sites-enabled/default`. I recommend that this |
| 133 | file contain only a list of include statements, one for each site that |
| 134 | server hosts: |
| 135 | |
| 136 | include local/example.com |
| 137 | include local/foo.net |
| 138 | |
| 139 | Those files then each define one domain’s configuration. Here, |
| 140 | `/etc/nginx/local/example.com` contains the configuration for |
| 141 | `*.example.com` and its alias `*.example.net`; and `local/foo.net` |
| 142 | contains the configuration for `*.foo.net`. |
| @@ -197,13 +197,13 @@ | |
| 197 | configuration for SCGI][scgii], showing off a few ideas you might want to |
| 198 | try on your own site, such as static asset proxying. |
| 199 | |
| 200 | You also need a `local/code` file containing: |
| 201 | |
| 202 | include scgi_params; |
| 203 | scgi_pass 127.0.0.1:12345; |
| 204 | scgi_param SCRIPT_NAME "/code"; |
| 205 | |
| 206 | We separate that out because nginx refuses to inherit certain settings |
| 207 | between nested location blocks, so rather than repeat them, we extract |
| 208 | them to this separate file and include it from both locations where it’s |
| 209 | needed. You see this above where we set far-future expiration dates on |
| @@ -213,16 +213,16 @@ | |
| 213 | Fossil-based site considerably faster. |
| 214 | |
| 215 | Similarly, the `local/generic` file referenced above helps us reduce unnecessary |
| 216 | repetition among the multiple sites this configuration hosts: |
| 217 | |
| 218 | root /var/www/$host; |
| 219 | |
| 220 | listen 80; |
| 221 | listen [::]:80; |
| 222 | |
| 223 | charset utf-8; |
| 224 | |
| 225 | There are some configuration directives that nginx refuses to substitute |
| 226 | variables into, citing performance considerations, so there is a limit |
| 227 | to how much repetition you can squeeze out this way. One such example |
| 228 | are the `access_log` and `error_log` directives, which follow an obvious |
| @@ -246,14 +246,14 @@ | |
| 246 | |
| 247 | However, it is still worth showing the proper method of proxying |
| 248 | Fossil’s HTTP server through nginx if only to make reading nginx |
| 249 | documentation on other sites easier: |
| 250 | |
| 251 | location /code { |
| 252 | rewrite ^/code(/.*) $1 break; |
| 253 | proxy_pass http://127.0.0.1:12345; |
| 254 | } |
| 255 | |
| 256 | The most common thing people get wrong when hand-rolling a configuration |
| 257 | like this is to get the slashes wrong. Fossil is sensitive to this. For |
| 258 | instance, Fossil will not collapse double slashes down to a single |
| 259 | slash, as some other HTTP servers will. |
| @@ -267,12 +267,12 @@ | |
| 267 | a problem, but when sending [unversioned content][uv], it uses a single |
| 268 | message for the entire file. Therefore, if you will be storing files |
| 269 | larger than this limit as unversioned content, you need to raise the |
| 270 | limit. Within the `location` block: |
| 271 | |
| 272 | # Allow large unversioned file uploads, such as PDFs |
| 273 | client_max_body_size 20M; |
| 274 | |
| 275 | [uv]: ../../unvers.wiki |
| 276 | |
| 277 | |
| 278 | ## <a id="fail2ban"></a> Integrating `fail2ban` |
| @@ -285,32 +285,32 @@ | |
| 285 | Fossil behind an nginx proxy, we convert these failures to log file |
| 286 | form, which `fail2ban` is designed to handle. |
| 287 | |
| 288 | First, install `fail2ban`, if you haven’t already: |
| 289 | |
| 290 | sudo apt install fail2ban |
| 291 | |
| 292 | We’d like `fail2ban` to react to Fossil `/login` failures. The stock |
| 293 | configuration of `fail2ban` only detects a few common sorts of SSH |
| 294 | attacks by default, and its included (but disabled) nginx attack |
| 295 | detectors don’t include one that knows how to detect an attack on |
| 296 | Fossil. We have to teach it by putting the following into |
| 297 | `/etc/fail2ban/filter.d/nginx-fossil-login.conf`: |
| 298 | |
| 299 | [Definition] |
| 300 | failregex = ^<HOST> - .*POST .*/login HTTP/..." 401 |
| 301 | |
| 302 | That teaches `fail2ban` how to recognize the errors logged by Fossil |
| 303 | [as of 2.14](/info/39d7eb0e22). (Earlier versions of Fossil returned |
| 304 | HTTP status code 200 for this, so you couldn’t distinguish a successful |
| 305 | login from a failure.) |
| 306 | |
| 307 | Then in `/etc/fail2ban/jail.local`, add this section: |
| 308 | |
| 309 | [nginx-fossil-login] |
| 310 | enabled = true |
| 311 | logpath = /var/log/nginx/*-https-access.log |
| 312 | |
| 313 | The last line is the key: it tells `fail2ban` where we’ve put all of our |
| 314 | per-repo access logs in the nginx config above. |
| 315 | |
| 316 | There’s a [lot more you can do][dof2b], but that gets us out of scope of |
| @@ -338,44 +338,42 @@ | |
| 338 | |
| 339 | You may wish to include something like this from each `server { }` |
| 340 | block in your configuration to enable TLS in a common, secure way: |
| 341 | |
| 342 | ``` |
| 343 | # Tell nginx to accept TLS-encrypted HTTPS on the standard TCP port. |
| 344 | listen 443 ssl; |
| 345 | listen [::]:443 ssl; |
| 346 | |
| 347 | # Reference the TLS cert files produced by Certbot. |
| 348 | ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; |
| 349 | ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem; |
| 350 | |
| 351 | # Load the Let's Encrypt Diffie-Hellman parameters generated for |
| 352 | # this server. Without this, the server is vulnerable to Logjam. |
| 353 | ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; |
| 354 | |
| 355 | # Tighten things down further, per Qualys’ and Certbot’s advice. |
| 356 | ssl_session_cache shared:le_nginx_SSL:1m; |
| 357 | ssl_protocols TLSv1.2 TLSv1.3; |
| 358 | ssl_prefer_server_ciphers on; |
| 359 | ssl_session_timeout 1440m; |
| 360 | |
| 361 | # Offer OCSP certificate stapling. |
| 362 | ssl_stapling on; |
| 363 | ssl_stapling_verify on; |
| 364 | |
| 365 | # Enable HSTS. |
| 366 | include local/enable-hsts; |
| 367 | ``` |
| 368 | |
| 369 | The [HSTS] step is optional and should be applied only after due |
| 370 | consideration, since it has the potential to lock users out of your |
| 371 | site if you later change your mind on the TLS configuration. |
| 372 | The `local/enable-hsts` file it references is simply: |
| 373 | |
| 374 | ``` |
| 375 | add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always; |
| 376 | ``` |
| 377 | |
| 378 | It’s a separate file because nginx requires that headers like this be |
| 379 | applied separately for each `location { }` block. We’ve therefore |
| 380 | factored this out so you can `include` it everywhere you need it. |
| 381 | |
| 382 |
| --- www/server/debian/nginx.md | |
| +++ www/server/debian/nginx.md | |
| @@ -101,11 +101,11 @@ | |
| 101 | ## <a id="deps"></a>Installing the Dependencies |
| 102 | |
| 103 | The first step is to install some non-default packages we’ll need. SSH into |
| 104 | your server, then say: |
| 105 | |
| 106 | $ sudo apt install fossil nginx |
| 107 | |
| 108 | You can leave “`fossil`” out of that if you’re building Fossil from |
| 109 | source to get a more up-to-date version than is shipped with the host |
| 110 | OS. |
| 111 | |
| @@ -131,12 +131,12 @@ | |
| 131 | On Debian and Ubuntu systems the primary user-level configuration file |
| 132 | for nginx is `/etc/nginx/sites-enabled/default`. I recommend that this |
| 133 | file contain only a list of include statements, one for each site that |
| 134 | server hosts: |
| 135 | |
| 136 | include local/example.com |
| 137 | include local/foo.net |
| 138 | |
| 139 | Those files then each define one domain’s configuration. Here, |
| 140 | `/etc/nginx/local/example.com` contains the configuration for |
| 141 | `*.example.com` and its alias `*.example.net`; and `local/foo.net` |
| 142 | contains the configuration for `*.foo.net`. |
| @@ -197,13 +197,13 @@ | |
| 197 | configuration for SCGI][scgii], showing off a few ideas you might want to |
| 198 | try on your own site, such as static asset proxying. |
| 199 | |
| 200 | You also need a `local/code` file containing: |
| 201 | |
| 202 | include scgi_params; |
| 203 | scgi_pass 127.0.0.1:12345; |
| 204 | scgi_param SCRIPT_NAME "/code"; |
| 205 | |
| 206 | We separate that out because nginx refuses to inherit certain settings |
| 207 | between nested location blocks, so rather than repeat them, we extract |
| 208 | them to this separate file and include it from both locations where it’s |
| 209 | needed. You see this above where we set far-future expiration dates on |
| @@ -213,16 +213,16 @@ | |
| 213 | Fossil-based site considerably faster. |
| 214 | |
| 215 | Similarly, the `local/generic` file referenced above helps us reduce unnecessary |
| 216 | repetition among the multiple sites this configuration hosts: |
| 217 | |
| 218 | root /var/www/$host; |
| 219 | |
| 220 | listen 80; |
| 221 | listen [::]:80; |
| 222 | |
| 223 | charset utf-8; |
| 224 | |
| 225 | There are some configuration directives that nginx refuses to substitute |
| 226 | variables into, citing performance considerations, so there is a limit |
| 227 | to how much repetition you can squeeze out this way. One such example |
| 228 | are the `access_log` and `error_log` directives, which follow an obvious |
| @@ -246,14 +246,14 @@ | |
| 246 | |
| 247 | However, it is still worth showing the proper method of proxying |
| 248 | Fossil’s HTTP server through nginx if only to make reading nginx |
| 249 | documentation on other sites easier: |
| 250 | |
| 251 | location /code { |
| 252 | rewrite ^/code(/.*) $1 break; |
| 253 | proxy_pass http://127.0.0.1:12345; |
| 254 | } |
| 255 | |
| 256 | The most common thing people get wrong when hand-rolling a configuration |
| 257 | like this is to get the slashes wrong. Fossil is sensitive to this. For |
| 258 | instance, Fossil will not collapse double slashes down to a single |
| 259 | slash, as some other HTTP servers will. |
| @@ -267,12 +267,12 @@ | |
| 267 | a problem, but when sending [unversioned content][uv], it uses a single |
| 268 | message for the entire file. Therefore, if you will be storing files |
| 269 | larger than this limit as unversioned content, you need to raise the |
| 270 | limit. Within the `location` block: |
| 271 | |
| 272 | # Allow large unversioned file uploads, such as PDFs |
| 273 | client_max_body_size 20M; |
| 274 | |
| 275 | [uv]: ../../unvers.wiki |
| 276 | |
| 277 | |
| 278 | ## <a id="fail2ban"></a> Integrating `fail2ban` |
| @@ -285,32 +285,32 @@ | |
| 285 | Fossil behind an nginx proxy, we convert these failures to log file |
| 286 | form, which `fail2ban` is designed to handle. |
| 287 | |
| 288 | First, install `fail2ban`, if you haven’t already: |
| 289 | |
| 290 | sudo apt install fail2ban |
| 291 | |
| 292 | We’d like `fail2ban` to react to Fossil `/login` failures. The stock |
| 293 | configuration of `fail2ban` only detects a few common sorts of SSH |
| 294 | attacks by default, and its included (but disabled) nginx attack |
| 295 | detectors don’t include one that knows how to detect an attack on |
| 296 | Fossil. We have to teach it by putting the following into |
| 297 | `/etc/fail2ban/filter.d/nginx-fossil-login.conf`: |
| 298 | |
| 299 | [Definition] |
| 300 | failregex = ^<HOST> - .*POST .*/login HTTP/..." 401 |
| 301 | |
| 302 | That teaches `fail2ban` how to recognize the errors logged by Fossil |
| 303 | [as of 2.14](/info/39d7eb0e22). (Earlier versions of Fossil returned |
| 304 | HTTP status code 200 for this, so you couldn’t distinguish a successful |
| 305 | login from a failure.) |
| 306 | |
| 307 | Then in `/etc/fail2ban/jail.local`, add this section: |
| 308 | |
| 309 | [nginx-fossil-login] |
| 310 | enabled = true |
| 311 | logpath = /var/log/nginx/*-https-access.log |
| 312 | |
| 313 | The last line is the key: it tells `fail2ban` where we’ve put all of our |
| 314 | per-repo access logs in the nginx config above. |
| 315 | |
| 316 | There’s a [lot more you can do][dof2b], but that gets us out of scope of |
| @@ -338,44 +338,42 @@ | |
| 338 | |
| 339 | You may wish to include something like this from each `server { }` |
| 340 | block in your configuration to enable TLS in a common, secure way: |
| 341 | |
| 342 | ``` |
| 343 | # Tell nginx to accept TLS-encrypted HTTPS on the standard TCP port. |
| 344 | listen 443 ssl; |
| 345 | listen [::]:443 ssl; |
| 346 | |
| 347 | # Reference the TLS cert files produced by Certbot. |
| 348 | ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; |
| 349 | ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem; |
| 350 | |
| 351 | # Load the Let's Encrypt Diffie-Hellman parameters generated for |
| 352 | # this server. Without this, the server is vulnerable to Logjam. |
| 353 | ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; |
| 354 | |
| 355 | # Tighten things down further, per Qualys’ and Certbot’s advice. |
| 356 | ssl_session_cache shared:le_nginx_SSL:1m; |
| 357 | ssl_protocols TLSv1.2 TLSv1.3; |
| 358 | ssl_prefer_server_ciphers on; |
| 359 | ssl_session_timeout 1440m; |
| 360 | |
| 361 | # Offer OCSP certificate stapling. |
| 362 | ssl_stapling on; |
| 363 | ssl_stapling_verify on; |
| 364 | |
| 365 | # Enable HSTS. |
| 366 | include local/enable-hsts; |
| 367 | ``` |
| 368 | |
| 369 | The [HSTS] step is optional and should be applied only after due |
| 370 | consideration, since it has the potential to lock users out of your |
| 371 | site if you later change your mind on the TLS configuration. |
| 372 | The `local/enable-hsts` file it references is simply: |
| 373 | |
| 374 | add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always; |
| 375 | |
| 376 | It’s a separate file because nginx requires that headers like this be |
| 377 | applied separately for each `location { }` block. We’ve therefore |
| 378 | factored this out so you can `include` it everywhere you need it. |
| 379 | |
| 380 |
+46
-46
| --- www/server/debian/service.md | ||
| +++ www/server/debian/service.md | ||
| @@ -53,22 +53,22 @@ | ||
| 53 | 53 | |
| 54 | 54 | To do this, write the following in |
| 55 | 55 | `~/.local/share/systemd/user/fossil.service`: |
| 56 | 56 | |
| 57 | 57 | ```dosini |
| 58 | - [Unit] | |
| 59 | - Description=Fossil user server | |
| 60 | - After=network-online.target | |
| 61 | - | |
| 62 | - [Service] | |
| 63 | - WorkingDirectory=/home/fossil/museum | |
| 64 | - ExecStart=/home/fossil/bin/fossil server --port 9000 repo.fossil | |
| 65 | - Restart=always | |
| 66 | - RestartSec=3 | |
| 67 | - | |
| 68 | - [Install] | |
| 69 | - WantedBy=multi-user.target | |
| 58 | +[Unit] | |
| 59 | +Description=Fossil user server | |
| 60 | +After=network-online.target | |
| 61 | + | |
| 62 | +[Service] | |
| 63 | +WorkingDirectory=/home/fossil/museum | |
| 64 | +ExecStart=/home/fossil/bin/fossil server --port 9000 repo.fossil | |
| 65 | +Restart=always | |
| 66 | +RestartSec=3 | |
| 67 | + | |
| 68 | +[Install] | |
| 69 | +WantedBy=multi-user.target | |
| 70 | 70 | ``` |
| 71 | 71 | |
| 72 | 72 | Unlike with `inetd` and `xinetd`, we don’t need to tell `systemd` which |
| 73 | 73 | user and group to run this service as, because we’ve installed it |
| 74 | 74 | under the account we’re logged into, which `systemd` will use as the |
| @@ -90,15 +90,15 @@ | ||
| 90 | 90 | |
| 91 | 91 | Because we’ve set this up as a user service, the commands you give to |
| 92 | 92 | manipulate the service vary somewhat from the sort you’re more likely to |
| 93 | 93 | find online: |
| 94 | 94 | |
| 95 | - $ systemctl --user daemon-reload | |
| 96 | - $ systemctl --user enable fossil | |
| 97 | - $ systemctl --user start fossil | |
| 98 | - $ systemctl --user status fossil -l | |
| 99 | - $ systemctl --user stop fossil | |
| 95 | + $ systemctl --user daemon-reload | |
| 96 | + $ systemctl --user enable fossil | |
| 97 | + $ systemctl --user start fossil | |
| 98 | + $ systemctl --user status fossil -l | |
| 99 | + $ systemctl --user stop fossil | |
| 100 | 100 | |
| 101 | 101 | That is, we don’t need to talk to `systemd` with `sudo` privileges, but |
| 102 | 102 | we do need to tell it to look at the user configuration rather than the |
| 103 | 103 | system-level configuration. |
| 104 | 104 | |
| @@ -109,11 +109,11 @@ | ||
| 109 | 109 | On some `systemd` based OSes, user services only run while that user is |
| 110 | 110 | logged in interactively. This is common on systems aiming to provide |
| 111 | 111 | desktop environments, where this is the behavior you often want. To |
| 112 | 112 | allow background services to continue to run after logout, say: |
| 113 | 113 | |
| 114 | - $ sudo loginctl enable-linger $USER | |
| 114 | + $ sudo loginctl enable-linger $USER | |
| 115 | 115 | |
| 116 | 116 | You can paste the command just like that into your terminal, since |
| 117 | 117 | `$USER` will expand to your login name. |
| 118 | 118 | |
| 119 | 119 | [scgi]: ../any/scgi.md |
| @@ -165,20 +165,20 @@ | ||
| 165 | 165 | |
| 166 | 166 | We first need to define the privileged socket listener by writing |
| 167 | 167 | `/etc/systemd/system/fossil.socket`: |
| 168 | 168 | |
| 169 | 169 | ```dosini |
| 170 | - [Unit] | |
| 171 | - Description=Fossil socket | |
| 172 | - | |
| 173 | - [Socket] | |
| 174 | - Accept=yes | |
| 175 | - ListenStream=80 | |
| 176 | - NoDelay=true | |
| 177 | - | |
| 178 | - [Install] | |
| 179 | - WantedBy=sockets.target | |
| 170 | +[Unit] | |
| 171 | +Description=Fossil socket | |
| 172 | + | |
| 173 | +[Socket] | |
| 174 | +Accept=yes | |
| 175 | +ListenStream=80 | |
| 176 | +NoDelay=true | |
| 177 | + | |
| 178 | +[Install] | |
| 179 | +WantedBy=sockets.target | |
| 180 | 180 | ``` |
| 181 | 181 | |
| 182 | 182 | Note the change of configuration directory from the `~/.local` directory |
| 183 | 183 | to the system level. We need to start this socket listener at the root |
| 184 | 184 | level because of the low-numbered TCP port restriction we brought up |
| @@ -190,21 +190,21 @@ | ||
| 190 | 190 | |
| 191 | 191 | Next, create the service definition file in that same directory as |
| 192 | 192 | `[email protected]`: |
| 193 | 193 | |
| 194 | 194 | ```dosini |
| 195 | - [Unit] | |
| 196 | - Description=Fossil socket server | |
| 197 | - After=network-online.target | |
| 198 | - | |
| 199 | - [Service] | |
| 200 | - WorkingDirectory=/home/fossil/museum | |
| 201 | - ExecStart=/home/fossil/bin/fossil http repo.fossil | |
| 202 | - StandardInput=socket | |
| 203 | - | |
| 204 | - [Install] | |
| 205 | - WantedBy=multi-user.target | |
| 195 | +[Unit] | |
| 196 | +Description=Fossil socket server | |
| 197 | +After=network-online.target | |
| 198 | + | |
| 199 | +[Service] | |
| 200 | +WorkingDirectory=/home/fossil/museum | |
| 201 | +ExecStart=/home/fossil/bin/fossil http repo.fossil | |
| 202 | +StandardInput=socket | |
| 203 | + | |
| 204 | +[Install] | |
| 205 | +WantedBy=multi-user.target | |
| 206 | 206 | ``` |
| 207 | 207 | |
| 208 | 208 | Notice that we haven’t told `systemd` which user and group to run Fossil |
| 209 | 209 | under. Since this is a system-level service definition, that means it |
| 210 | 210 | will run as root, which then causes Fossil to [automatically drop into a |
| @@ -217,34 +217,34 @@ | ||
| 217 | 217 | handles that single client’s request and then immediately shuts down. |
| 218 | 218 | |
| 219 | 219 | Next, you need to tell `systemd` to reload its system-level |
| 220 | 220 | configuration files and enable the listening socket: |
| 221 | 221 | |
| 222 | - $ sudo systemctl daemon-reload | |
| 223 | - $ sudo systemctl enable fossil.socket | |
| 222 | + $ sudo systemctl daemon-reload | |
| 223 | + $ sudo systemctl enable fossil.socket | |
| 224 | 224 | |
| 225 | 225 | And now you can manipulate the socket listener: |
| 226 | 226 | |
| 227 | - $ sudo systemctl start fossil.socket | |
| 228 | - $ sudo systemctl status -l fossil.socket | |
| 229 | - $ sudo systemctl stop fossil.socket | |
| 227 | + $ sudo systemctl start fossil.socket | |
| 228 | + $ sudo systemctl status -l fossil.socket | |
| 229 | + $ sudo systemctl stop fossil.socket | |
| 230 | 230 | |
| 231 | 231 | Notice that we’re working with the *socket*, not the *service*. The fact |
| 232 | 232 | that we’ve given them the same base name and marked the service as an |
| 233 | 233 | instantiated service with the “`@`” notation allows `systemd` to |
| 234 | 234 | automatically start an instance of the service each time a hit comes in |
| 235 | 235 | on the socket that `systemd` is monitoring on Fossil’s behalf. To see |
| 236 | 236 | this service instantiation at work, visit a long-running Fossil page |
| 237 | 237 | (e.g. `/tarball`) and then give a command like this: |
| 238 | 238 | |
| 239 | - $ sudo systemctl --full | grep fossil | |
| 239 | + $ sudo systemctl --full | grep fossil | |
| 240 | 240 | |
| 241 | 241 | This will show information about the `fossil` socket and service |
| 242 | 242 | instances, which should show your `/tarball` hit handler, if it’s still |
| 243 | 243 | running: |
| 244 | 244 | |
| 245 | - [email protected]:80-127.0.0.1:38304.service | |
| 245 | + [email protected]:80-127.0.0.1:38304.service | |
| 246 | 246 | |
| 247 | 247 | You can feed that service instance description to a `systemctl kill` |
| 248 | 248 | command to stop that single instance without restarting the whole |
| 249 | 249 | `fossil` service, for example. |
| 250 | 250 | |
| 251 | 251 |
| --- www/server/debian/service.md | |
| +++ www/server/debian/service.md | |
| @@ -53,22 +53,22 @@ | |
| 53 | |
| 54 | To do this, write the following in |
| 55 | `~/.local/share/systemd/user/fossil.service`: |
| 56 | |
| 57 | ```dosini |
| 58 | [Unit] |
| 59 | Description=Fossil user server |
| 60 | After=network-online.target |
| 61 | |
| 62 | [Service] |
| 63 | WorkingDirectory=/home/fossil/museum |
| 64 | ExecStart=/home/fossil/bin/fossil server --port 9000 repo.fossil |
| 65 | Restart=always |
| 66 | RestartSec=3 |
| 67 | |
| 68 | [Install] |
| 69 | WantedBy=multi-user.target |
| 70 | ``` |
| 71 | |
| 72 | Unlike with `inetd` and `xinetd`, we don’t need to tell `systemd` which |
| 73 | user and group to run this service as, because we’ve installed it |
| 74 | under the account we’re logged into, which `systemd` will use as the |
| @@ -90,15 +90,15 @@ | |
| 90 | |
| 91 | Because we’ve set this up as a user service, the commands you give to |
| 92 | manipulate the service vary somewhat from the sort you’re more likely to |
| 93 | find online: |
| 94 | |
| 95 | $ systemctl --user daemon-reload |
| 96 | $ systemctl --user enable fossil |
| 97 | $ systemctl --user start fossil |
| 98 | $ systemctl --user status fossil -l |
| 99 | $ systemctl --user stop fossil |
| 100 | |
| 101 | That is, we don’t need to talk to `systemd` with `sudo` privileges, but |
| 102 | we do need to tell it to look at the user configuration rather than the |
| 103 | system-level configuration. |
| 104 | |
| @@ -109,11 +109,11 @@ | |
| 109 | On some `systemd` based OSes, user services only run while that user is |
| 110 | logged in interactively. This is common on systems aiming to provide |
| 111 | desktop environments, where this is the behavior you often want. To |
| 112 | allow background services to continue to run after logout, say: |
| 113 | |
| 114 | $ sudo loginctl enable-linger $USER |
| 115 | |
| 116 | You can paste the command just like that into your terminal, since |
| 117 | `$USER` will expand to your login name. |
| 118 | |
| 119 | [scgi]: ../any/scgi.md |
| @@ -165,20 +165,20 @@ | |
| 165 | |
| 166 | We first need to define the privileged socket listener by writing |
| 167 | `/etc/systemd/system/fossil.socket`: |
| 168 | |
| 169 | ```dosini |
| 170 | [Unit] |
| 171 | Description=Fossil socket |
| 172 | |
| 173 | [Socket] |
| 174 | Accept=yes |
| 175 | ListenStream=80 |
| 176 | NoDelay=true |
| 177 | |
| 178 | [Install] |
| 179 | WantedBy=sockets.target |
| 180 | ``` |
| 181 | |
| 182 | Note the change of configuration directory from the `~/.local` directory |
| 183 | to the system level. We need to start this socket listener at the root |
| 184 | level because of the low-numbered TCP port restriction we brought up |
| @@ -190,21 +190,21 @@ | |
| 190 | |
| 191 | Next, create the service definition file in that same directory as |
| 192 | `[email protected]`: |
| 193 | |
| 194 | ```dosini |
| 195 | [Unit] |
| 196 | Description=Fossil socket server |
| 197 | After=network-online.target |
| 198 | |
| 199 | [Service] |
| 200 | WorkingDirectory=/home/fossil/museum |
| 201 | ExecStart=/home/fossil/bin/fossil http repo.fossil |
| 202 | StandardInput=socket |
| 203 | |
| 204 | [Install] |
| 205 | WantedBy=multi-user.target |
| 206 | ``` |
| 207 | |
| 208 | Notice that we haven’t told `systemd` which user and group to run Fossil |
| 209 | under. Since this is a system-level service definition, that means it |
| 210 | will run as root, which then causes Fossil to [automatically drop into a |
| @@ -217,34 +217,34 @@ | |
| 217 | handles that single client’s request and then immediately shuts down. |
| 218 | |
| 219 | Next, you need to tell `systemd` to reload its system-level |
| 220 | configuration files and enable the listening socket: |
| 221 | |
| 222 | $ sudo systemctl daemon-reload |
| 223 | $ sudo systemctl enable fossil.socket |
| 224 | |
| 225 | And now you can manipulate the socket listener: |
| 226 | |
| 227 | $ sudo systemctl start fossil.socket |
| 228 | $ sudo systemctl status -l fossil.socket |
| 229 | $ sudo systemctl stop fossil.socket |
| 230 | |
| 231 | Notice that we’re working with the *socket*, not the *service*. The fact |
| 232 | that we’ve given them the same base name and marked the service as an |
| 233 | instantiated service with the “`@`” notation allows `systemd` to |
| 234 | automatically start an instance of the service each time a hit comes in |
| 235 | on the socket that `systemd` is monitoring on Fossil’s behalf. To see |
| 236 | this service instantiation at work, visit a long-running Fossil page |
| 237 | (e.g. `/tarball`) and then give a command like this: |
| 238 | |
| 239 | $ sudo systemctl --full | grep fossil |
| 240 | |
| 241 | This will show information about the `fossil` socket and service |
| 242 | instances, which should show your `/tarball` hit handler, if it’s still |
| 243 | running: |
| 244 | |
| 245 | [email protected]:80-127.0.0.1:38304.service |
| 246 | |
| 247 | You can feed that service instance description to a `systemctl kill` |
| 248 | command to stop that single instance without restarting the whole |
| 249 | `fossil` service, for example. |
| 250 | |
| 251 |
| --- www/server/debian/service.md | |
| +++ www/server/debian/service.md | |
| @@ -53,22 +53,22 @@ | |
| 53 | |
| 54 | To do this, write the following in |
| 55 | `~/.local/share/systemd/user/fossil.service`: |
| 56 | |
| 57 | ```dosini |
| 58 | [Unit] |
| 59 | Description=Fossil user server |
| 60 | After=network-online.target |
| 61 | |
| 62 | [Service] |
| 63 | WorkingDirectory=/home/fossil/museum |
| 64 | ExecStart=/home/fossil/bin/fossil server --port 9000 repo.fossil |
| 65 | Restart=always |
| 66 | RestartSec=3 |
| 67 | |
| 68 | [Install] |
| 69 | WantedBy=multi-user.target |
| 70 | ``` |
| 71 | |
| 72 | Unlike with `inetd` and `xinetd`, we don’t need to tell `systemd` which |
| 73 | user and group to run this service as, because we’ve installed it |
| 74 | under the account we’re logged into, which `systemd` will use as the |
| @@ -90,15 +90,15 @@ | |
| 90 | |
| 91 | Because we’ve set this up as a user service, the commands you give to |
| 92 | manipulate the service vary somewhat from the sort you’re more likely to |
| 93 | find online: |
| 94 | |
| 95 | $ systemctl --user daemon-reload |
| 96 | $ systemctl --user enable fossil |
| 97 | $ systemctl --user start fossil |
| 98 | $ systemctl --user status fossil -l |
| 99 | $ systemctl --user stop fossil |
| 100 | |
| 101 | That is, we don’t need to talk to `systemd` with `sudo` privileges, but |
| 102 | we do need to tell it to look at the user configuration rather than the |
| 103 | system-level configuration. |
| 104 | |
| @@ -109,11 +109,11 @@ | |
| 109 | On some `systemd` based OSes, user services only run while that user is |
| 110 | logged in interactively. This is common on systems aiming to provide |
| 111 | desktop environments, where this is the behavior you often want. To |
| 112 | allow background services to continue to run after logout, say: |
| 113 | |
| 114 | $ sudo loginctl enable-linger $USER |
| 115 | |
| 116 | You can paste the command just like that into your terminal, since |
| 117 | `$USER` will expand to your login name. |
| 118 | |
| 119 | [scgi]: ../any/scgi.md |
| @@ -165,20 +165,20 @@ | |
| 165 | |
| 166 | We first need to define the privileged socket listener by writing |
| 167 | `/etc/systemd/system/fossil.socket`: |
| 168 | |
| 169 | ```dosini |
| 170 | [Unit] |
| 171 | Description=Fossil socket |
| 172 | |
| 173 | [Socket] |
| 174 | Accept=yes |
| 175 | ListenStream=80 |
| 176 | NoDelay=true |
| 177 | |
| 178 | [Install] |
| 179 | WantedBy=sockets.target |
| 180 | ``` |
| 181 | |
| 182 | Note the change of configuration directory from the `~/.local` directory |
| 183 | to the system level. We need to start this socket listener at the root |
| 184 | level because of the low-numbered TCP port restriction we brought up |
| @@ -190,21 +190,21 @@ | |
| 190 | |
| 191 | Next, create the service definition file in that same directory as |
| 192 | `[email protected]`: |
| 193 | |
| 194 | ```dosini |
| 195 | [Unit] |
| 196 | Description=Fossil socket server |
| 197 | After=network-online.target |
| 198 | |
| 199 | [Service] |
| 200 | WorkingDirectory=/home/fossil/museum |
| 201 | ExecStart=/home/fossil/bin/fossil http repo.fossil |
| 202 | StandardInput=socket |
| 203 | |
| 204 | [Install] |
| 205 | WantedBy=multi-user.target |
| 206 | ``` |
| 207 | |
| 208 | Notice that we haven’t told `systemd` which user and group to run Fossil |
| 209 | under. Since this is a system-level service definition, that means it |
| 210 | will run as root, which then causes Fossil to [automatically drop into a |
| @@ -217,34 +217,34 @@ | |
| 217 | handles that single client’s request and then immediately shuts down. |
| 218 | |
| 219 | Next, you need to tell `systemd` to reload its system-level |
| 220 | configuration files and enable the listening socket: |
| 221 | |
| 222 | $ sudo systemctl daemon-reload |
| 223 | $ sudo systemctl enable fossil.socket |
| 224 | |
| 225 | And now you can manipulate the socket listener: |
| 226 | |
| 227 | $ sudo systemctl start fossil.socket |
| 228 | $ sudo systemctl status -l fossil.socket |
| 229 | $ sudo systemctl stop fossil.socket |
| 230 | |
| 231 | Notice that we’re working with the *socket*, not the *service*. The fact |
| 232 | that we’ve given them the same base name and marked the service as an |
| 233 | instantiated service with the “`@`” notation allows `systemd` to |
| 234 | automatically start an instance of the service each time a hit comes in |
| 235 | on the socket that `systemd` is monitoring on Fossil’s behalf. To see |
| 236 | this service instantiation at work, visit a long-running Fossil page |
| 237 | (e.g. `/tarball`) and then give a command like this: |
| 238 | |
| 239 | $ sudo systemctl --full | grep fossil |
| 240 | |
| 241 | This will show information about the `fossil` socket and service |
| 242 | instances, which should show your `/tarball` hit handler, if it’s still |
| 243 | running: |
| 244 | |
| 245 | [email protected]:80-127.0.0.1:38304.service |
| 246 | |
| 247 | You can feed that service instance description to a `systemctl kill` |
| 248 | command to stop that single instance without restarting the whole |
| 249 | `fossil` service, for example. |
| 250 | |
| 251 |
+5
-44
| --- www/server/index.html | ||
| +++ www/server/index.html | ||
| @@ -1,61 +1,24 @@ | ||
| 1 | 1 | <div class='fossil-doc' data-title="How To Configure A Fossil Server"> |
| 2 | 2 | |
| 3 | 3 | <style type="text/css"> |
| 4 | - p { | |
| 5 | - margin-left: 4em; | |
| 6 | - margin-right: 3em; | |
| 7 | - } | |
| 8 | - | |
| 9 | - li p { | |
| 10 | - margin-left: 0; | |
| 11 | - } | |
| 12 | - | |
| 13 | - h2 { | |
| 14 | - margin-left: 1em; | |
| 15 | - } | |
| 16 | - | |
| 17 | - h3 { | |
| 18 | - margin-left: 3em; | |
| 19 | - } | |
| 20 | - | |
| 21 | - ol, ul { | |
| 22 | - margin-left: 3em; | |
| 23 | - } | |
| 24 | - | |
| 25 | - a#all { | |
| 26 | - font-size: 90%; | |
| 27 | - margin-left: 1em; | |
| 28 | - } | |
| 29 | - | |
| 30 | - div#tutpick.show { | |
| 31 | - max-height: 99em; | |
| 32 | - transition: max-height 1000ms ease-in; | |
| 33 | - } | |
| 34 | - div#tutpick { | |
| 35 | - max-height: 0; | |
| 36 | - overflow: hidden; | |
| 37 | - } | |
| 38 | - | |
| 39 | - th.fep { | |
| 40 | - background-color: #e8e8e8; | |
| 4 | + .doc > .content th.fep { | |
| 41 | 5 | font-family: "Helvetica Neue", "Arial Narrow", "Myriad Pro", "Avenir Next Condensed"; |
| 42 | 6 | font-stretch: condensed; |
| 43 | 7 | min-width: 3em; |
| 44 | 8 | padding: 0.4em; |
| 45 | 9 | white-space: nowrap; |
| 46 | 10 | } |
| 47 | 11 | |
| 48 | - th.host { | |
| 49 | - background-color: #e8e8e8; | |
| 12 | + .doc > .content th.host { | |
| 50 | 13 | font-family: "Helvetica Neue", "Arial Narrow", "Myriad Pro", "Avenir Next Condensed"; |
| 51 | 14 | font-stretch: condensed; |
| 52 | 15 | padding: 0.4em; |
| 53 | 16 | text-align: right; |
| 54 | 17 | } |
| 55 | 18 | |
| 56 | - td.doc { | |
| 19 | + .doc > .content td.doc { | |
| 57 | 20 | text-align: center; |
| 58 | 21 | } |
| 59 | 22 | </style> |
| 60 | 23 | |
| 61 | 24 | |
| @@ -200,13 +163,11 @@ | ||
| 200 | 163 | |
| 201 | 164 | <p>We've broken the configuration for each method out into a series of |
| 202 | 165 | sub-articles. Some of these are generic, while others depend on |
| 203 | 166 | particular operating systems or front-end software:</p> |
| 204 | 167 | |
| 205 | -<div id="tutpick" class="show"></div> | |
| 206 | - | |
| 207 | -<table style="margin-left: 6em;"> | |
| 168 | +<div class="indent"><table> | |
| 208 | 169 | <tr> |
| 209 | 170 | <th class="host">⇩ OS / Method ⇨</th> |
| 210 | 171 | <th class="fep">direct</th> |
| 211 | 172 | <th class="fep">inetd</th> |
| 212 | 173 | <th class="fep">stunnel</th> |
| @@ -280,11 +241,11 @@ | ||
| 280 | 241 | <td class="doc">❌</td> |
| 281 | 242 | <td class="doc">❌</td> |
| 282 | 243 | <td class="doc"><a href="windows/iis.md">✅</a></td> |
| 283 | 244 | <td class="doc"><a href="windows/service.md">✅</a></td> |
| 284 | 245 | </tr> |
| 285 | -</table> | |
| 246 | +</table></div> | |
| 286 | 247 | |
| 287 | 248 | <p>Where there is a check mark in the "<b>Any</b>" row, the method for that is |
| 288 | 249 | generic enough that it works across OSes that Fossil is known to work |
| 289 | 250 | on. The check marks below that usually just link to this generic |
| 290 | 251 | documentation.</p> |
| 291 | 252 |
| --- www/server/index.html | |
| +++ www/server/index.html | |
| @@ -1,61 +1,24 @@ | |
| 1 | <div class='fossil-doc' data-title="How To Configure A Fossil Server"> |
| 2 | |
| 3 | <style type="text/css"> |
| 4 | p { |
| 5 | margin-left: 4em; |
| 6 | margin-right: 3em; |
| 7 | } |
| 8 | |
| 9 | li p { |
| 10 | margin-left: 0; |
| 11 | } |
| 12 | |
| 13 | h2 { |
| 14 | margin-left: 1em; |
| 15 | } |
| 16 | |
| 17 | h3 { |
| 18 | margin-left: 3em; |
| 19 | } |
| 20 | |
| 21 | ol, ul { |
| 22 | margin-left: 3em; |
| 23 | } |
| 24 | |
| 25 | a#all { |
| 26 | font-size: 90%; |
| 27 | margin-left: 1em; |
| 28 | } |
| 29 | |
| 30 | div#tutpick.show { |
| 31 | max-height: 99em; |
| 32 | transition: max-height 1000ms ease-in; |
| 33 | } |
| 34 | div#tutpick { |
| 35 | max-height: 0; |
| 36 | overflow: hidden; |
| 37 | } |
| 38 | |
| 39 | th.fep { |
| 40 | background-color: #e8e8e8; |
| 41 | font-family: "Helvetica Neue", "Arial Narrow", "Myriad Pro", "Avenir Next Condensed"; |
| 42 | font-stretch: condensed; |
| 43 | min-width: 3em; |
| 44 | padding: 0.4em; |
| 45 | white-space: nowrap; |
| 46 | } |
| 47 | |
| 48 | th.host { |
| 49 | background-color: #e8e8e8; |
| 50 | font-family: "Helvetica Neue", "Arial Narrow", "Myriad Pro", "Avenir Next Condensed"; |
| 51 | font-stretch: condensed; |
| 52 | padding: 0.4em; |
| 53 | text-align: right; |
| 54 | } |
| 55 | |
| 56 | td.doc { |
| 57 | text-align: center; |
| 58 | } |
| 59 | </style> |
| 60 | |
| 61 | |
| @@ -200,13 +163,11 @@ | |
| 200 | |
| 201 | <p>We've broken the configuration for each method out into a series of |
| 202 | sub-articles. Some of these are generic, while others depend on |
| 203 | particular operating systems or front-end software:</p> |
| 204 | |
| 205 | <div id="tutpick" class="show"></div> |
| 206 | |
| 207 | <table style="margin-left: 6em;"> |
| 208 | <tr> |
| 209 | <th class="host">⇩ OS / Method ⇨</th> |
| 210 | <th class="fep">direct</th> |
| 211 | <th class="fep">inetd</th> |
| 212 | <th class="fep">stunnel</th> |
| @@ -280,11 +241,11 @@ | |
| 280 | <td class="doc">❌</td> |
| 281 | <td class="doc">❌</td> |
| 282 | <td class="doc"><a href="windows/iis.md">✅</a></td> |
| 283 | <td class="doc"><a href="windows/service.md">✅</a></td> |
| 284 | </tr> |
| 285 | </table> |
| 286 | |
| 287 | <p>Where there is a check mark in the "<b>Any</b>" row, the method for that is |
| 288 | generic enough that it works across OSes that Fossil is known to work |
| 289 | on. The check marks below that usually just link to this generic |
| 290 | documentation.</p> |
| 291 |
| --- www/server/index.html | |
| +++ www/server/index.html | |
| @@ -1,61 +1,24 @@ | |
| 1 | <div class='fossil-doc' data-title="How To Configure A Fossil Server"> |
| 2 | |
| 3 | <style type="text/css"> |
| 4 | .doc > .content th.fep { |
| 5 | font-family: "Helvetica Neue", "Arial Narrow", "Myriad Pro", "Avenir Next Condensed"; |
| 6 | font-stretch: condensed; |
| 7 | min-width: 3em; |
| 8 | padding: 0.4em; |
| 9 | white-space: nowrap; |
| 10 | } |
| 11 | |
| 12 | .doc > .content th.host { |
| 13 | font-family: "Helvetica Neue", "Arial Narrow", "Myriad Pro", "Avenir Next Condensed"; |
| 14 | font-stretch: condensed; |
| 15 | padding: 0.4em; |
| 16 | text-align: right; |
| 17 | } |
| 18 | |
| 19 | .doc > .content td.doc { |
| 20 | text-align: center; |
| 21 | } |
| 22 | </style> |
| 23 | |
| 24 | |
| @@ -200,13 +163,11 @@ | |
| 163 | |
| 164 | <p>We've broken the configuration for each method out into a series of |
| 165 | sub-articles. Some of these are generic, while others depend on |
| 166 | particular operating systems or front-end software:</p> |
| 167 | |
| 168 | <div class="indent"><table> |
| 169 | <tr> |
| 170 | <th class="host">⇩ OS / Method ⇨</th> |
| 171 | <th class="fep">direct</th> |
| 172 | <th class="fep">inetd</th> |
| 173 | <th class="fep">stunnel</th> |
| @@ -280,11 +241,11 @@ | |
| 241 | <td class="doc">❌</td> |
| 242 | <td class="doc">❌</td> |
| 243 | <td class="doc"><a href="windows/iis.md">✅</a></td> |
| 244 | <td class="doc"><a href="windows/service.md">✅</a></td> |
| 245 | </tr> |
| 246 | </table></div> |
| 247 | |
| 248 | <p>Where there is a check mark in the "<b>Any</b>" row, the method for that is |
| 249 | generic enough that it works across OSes that Fossil is known to work |
| 250 | on. The check marks below that usually just link to this generic |
| 251 | documentation.</p> |
| 252 |
+40
-38
| --- www/server/macos/service.md | ||
| +++ www/server/macos/service.md | ||
| @@ -18,11 +18,11 @@ | ||
| 18 | 18 | socket activation. |
| 19 | 19 | |
| 20 | 20 | For more information on `launchd`, the single best resource we’ve found |
| 21 | 21 | is [launchd.info](https://launchd.info). The next best is: |
| 22 | 22 | |
| 23 | - $ man launchd.plist | |
| 23 | + $ man launchd.plist | |
| 24 | 24 | |
| 25 | 25 | [la]: http://www.grivet-tools.com/blog/2014/launchdaemons-vs-launchagents/ |
| 26 | 26 | [ldhome]: https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html |
| 27 | 27 | [wpa]: https://en.wikipedia.org/wiki/Launchd |
| 28 | 28 | |
| @@ -32,42 +32,43 @@ | ||
| 32 | 32 | |
| 33 | 33 | To configure `launchd` to start Fossil as a standalone HTTP server, |
| 34 | 34 | write the following as `com.example.dev.FossilHTTP.plist`: |
| 35 | 35 | |
| 36 | 36 | ```xml |
| 37 | - <?xml version="1.0" encoding="UTF-8"?> | |
| 38 | - <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> | |
| 39 | - <plist version="1.0"> | |
| 40 | - <dict> | |
| 41 | - <key>Label</key> | |
| 42 | - <string>com.example.dev.FossilHTTP</string> | |
| 43 | - <key>ProgramArguments</key> | |
| 44 | - <array> | |
| 45 | - <string>/usr/local/bin/fossil</string> | |
| 46 | - <string>server</string> | |
| 47 | - <string>--port</string> | |
| 48 | - <string>9000</string> | |
| 49 | - <string>repo.fossil</string> | |
| 50 | - </array> | |
| 51 | - <key>WorkingDirectory</key> | |
| 52 | - <string>/Users/you/museum</string> | |
| 53 | - <key>KeepAlive</key> | |
| 54 | - <true/> | |
| 55 | - <key>RunAtLoad</key> | |
| 56 | - <true/> | |
| 57 | - <key>StandardErrorPath</key> | |
| 58 | - <string>/tmp/fossil-error.log</string> | |
| 59 | - <key>StandardOutPath</key> | |
| 60 | - <string>/tmp/fossil-info.log</string> | |
| 61 | - <key>UserName</key> | |
| 62 | - <string>you</string> | |
| 63 | - <key>GroupName</key> | |
| 64 | - <string>staff</string> | |
| 65 | - <key>InitGroups</key> | |
| 66 | - <true/> | |
| 67 | - </dict> | |
| 68 | - </plist> | |
| 37 | +<?xml version="1.0" encoding="UTF-8"?> | |
| 38 | +<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" | |
| 39 | + "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> | |
| 40 | +<plist version="1.0"> | |
| 41 | +<dict> | |
| 42 | + <key>Label</key> | |
| 43 | + <string>com.example.dev.FossilHTTP</string> | |
| 44 | + <key>ProgramArguments</key> | |
| 45 | + <array> | |
| 46 | + <string>/usr/local/bin/fossil</string> | |
| 47 | + <string>server</string> | |
| 48 | + <string>--port</string> | |
| 49 | + <string>9000</string> | |
| 50 | + <string>repo.fossil</string> | |
| 51 | + </array> | |
| 52 | + <key>WorkingDirectory</key> | |
| 53 | + <string>/Users/you/museum</string> | |
| 54 | + <key>KeepAlive</key> | |
| 55 | + <true/> | |
| 56 | + <key>RunAtLoad</key> | |
| 57 | + <true/> | |
| 58 | + <key>StandardErrorPath</key> | |
| 59 | + <string>/tmp/fossil-error.log</string> | |
| 60 | + <key>StandardOutPath</key> | |
| 61 | + <string>/tmp/fossil-info.log</string> | |
| 62 | + <key>UserName</key> | |
| 63 | + <string>you</string> | |
| 64 | + <key>GroupName</key> | |
| 65 | + <string>staff</string> | |
| 66 | + <key>InitGroups</key> | |
| 67 | + <true/> | |
| 68 | +</dict> | |
| 69 | +</plist> | |
| 69 | 70 | ``` |
| 70 | 71 | |
| 71 | 72 | In this example, we’re assuming your development organization uses the |
| 72 | 73 | domain name “`dev.example.org`”, that your short macOS login name is |
| 73 | 74 | “`you`”, and that you store your Fossils in “`~/museum`”. Adjust these |
| @@ -81,29 +82,30 @@ | ||
| 81 | 82 | if you leave the user and group configuration at the tail end of that |
| 82 | 83 | plist file out, Fossil will remain running as root! |
| 83 | 84 | |
| 84 | 85 | Install that file and set it to start with: |
| 85 | 86 | |
| 86 | - $ sudo install -o root -g wheel -m 644 com.example.dev.FossilHTTP.plist \ | |
| 87 | - /Library/LaunchDaemons/ | |
| 88 | - $ sudo launchctl load -w /Library/LaunchDaemons/com.example.dev.FossilHTTP.plist | |
| 87 | + $ sudo install -o root -g wheel -m 644 com.example.dev.FossilHTTP.plist \ | |
| 88 | + /Library/LaunchDaemons/ | |
| 89 | + $ sudo launchctl load -w /Library/LaunchDaemons/com.example.dev.FossilHTTP.plist | |
| 89 | 90 | |
| 90 | 91 | Because we set the `RunAtLoad` key, this will also launch the daemon. |
| 91 | 92 | |
| 92 | 93 | Stop the daemon with: |
| 93 | 94 | |
| 94 | - $ sudo launchctl unload -w /Library/LaunchDaemons/com.example.dev.FossilHTTP.plist | |
| 95 | + $ sudo launchctl unload -w /Library/LaunchDaemons/com.example.dev.FossilHTTP.plist | |
| 95 | 96 | |
| 96 | 97 | |
| 97 | 98 | ## Socket Listener |
| 98 | 99 | |
| 99 | 100 | Another useful method to serve a Fossil repo via `launchd` is by setting |
| 100 | 101 | up a socket listener: |
| 101 | 102 | |
| 102 | 103 | ```xml |
| 103 | 104 | <?xml version="1.0" encoding="UTF-8"?> |
| 104 | -<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> | |
| 105 | +<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" | |
| 106 | + "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> | |
| 105 | 107 | <plist version="1.0"> |
| 106 | 108 | <dict> |
| 107 | 109 | <key>Label</key> |
| 108 | 110 | <string>com.example.dev.FossilSocket</string> |
| 109 | 111 | <key>ProgramArguments</key> |
| 110 | 112 |
| --- www/server/macos/service.md | |
| +++ www/server/macos/service.md | |
| @@ -18,11 +18,11 @@ | |
| 18 | socket activation. |
| 19 | |
| 20 | For more information on `launchd`, the single best resource we’ve found |
| 21 | is [launchd.info](https://launchd.info). The next best is: |
| 22 | |
| 23 | $ man launchd.plist |
| 24 | |
| 25 | [la]: http://www.grivet-tools.com/blog/2014/launchdaemons-vs-launchagents/ |
| 26 | [ldhome]: https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html |
| 27 | [wpa]: https://en.wikipedia.org/wiki/Launchd |
| 28 | |
| @@ -32,42 +32,43 @@ | |
| 32 | |
| 33 | To configure `launchd` to start Fossil as a standalone HTTP server, |
| 34 | write the following as `com.example.dev.FossilHTTP.plist`: |
| 35 | |
| 36 | ```xml |
| 37 | <?xml version="1.0" encoding="UTF-8"?> |
| 38 | <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> |
| 39 | <plist version="1.0"> |
| 40 | <dict> |
| 41 | <key>Label</key> |
| 42 | <string>com.example.dev.FossilHTTP</string> |
| 43 | <key>ProgramArguments</key> |
| 44 | <array> |
| 45 | <string>/usr/local/bin/fossil</string> |
| 46 | <string>server</string> |
| 47 | <string>--port</string> |
| 48 | <string>9000</string> |
| 49 | <string>repo.fossil</string> |
| 50 | </array> |
| 51 | <key>WorkingDirectory</key> |
| 52 | <string>/Users/you/museum</string> |
| 53 | <key>KeepAlive</key> |
| 54 | <true/> |
| 55 | <key>RunAtLoad</key> |
| 56 | <true/> |
| 57 | <key>StandardErrorPath</key> |
| 58 | <string>/tmp/fossil-error.log</string> |
| 59 | <key>StandardOutPath</key> |
| 60 | <string>/tmp/fossil-info.log</string> |
| 61 | <key>UserName</key> |
| 62 | <string>you</string> |
| 63 | <key>GroupName</key> |
| 64 | <string>staff</string> |
| 65 | <key>InitGroups</key> |
| 66 | <true/> |
| 67 | </dict> |
| 68 | </plist> |
| 69 | ``` |
| 70 | |
| 71 | In this example, we’re assuming your development organization uses the |
| 72 | domain name “`dev.example.org`”, that your short macOS login name is |
| 73 | “`you`”, and that you store your Fossils in “`~/museum`”. Adjust these |
| @@ -81,29 +82,30 @@ | |
| 81 | if you leave the user and group configuration at the tail end of that |
| 82 | plist file out, Fossil will remain running as root! |
| 83 | |
| 84 | Install that file and set it to start with: |
| 85 | |
| 86 | $ sudo install -o root -g wheel -m 644 com.example.dev.FossilHTTP.plist \ |
| 87 | /Library/LaunchDaemons/ |
| 88 | $ sudo launchctl load -w /Library/LaunchDaemons/com.example.dev.FossilHTTP.plist |
| 89 | |
| 90 | Because we set the `RunAtLoad` key, this will also launch the daemon. |
| 91 | |
| 92 | Stop the daemon with: |
| 93 | |
| 94 | $ sudo launchctl unload -w /Library/LaunchDaemons/com.example.dev.FossilHTTP.plist |
| 95 | |
| 96 | |
| 97 | ## Socket Listener |
| 98 | |
| 99 | Another useful method to serve a Fossil repo via `launchd` is by setting |
| 100 | up a socket listener: |
| 101 | |
| 102 | ```xml |
| 103 | <?xml version="1.0" encoding="UTF-8"?> |
| 104 | <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> |
| 105 | <plist version="1.0"> |
| 106 | <dict> |
| 107 | <key>Label</key> |
| 108 | <string>com.example.dev.FossilSocket</string> |
| 109 | <key>ProgramArguments</key> |
| 110 |
| --- www/server/macos/service.md | |
| +++ www/server/macos/service.md | |
| @@ -18,11 +18,11 @@ | |
| 18 | socket activation. |
| 19 | |
| 20 | For more information on `launchd`, the single best resource we’ve found |
| 21 | is [launchd.info](https://launchd.info). The next best is: |
| 22 | |
| 23 | $ man launchd.plist |
| 24 | |
| 25 | [la]: http://www.grivet-tools.com/blog/2014/launchdaemons-vs-launchagents/ |
| 26 | [ldhome]: https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html |
| 27 | [wpa]: https://en.wikipedia.org/wiki/Launchd |
| 28 | |
| @@ -32,42 +32,43 @@ | |
| 32 | |
| 33 | To configure `launchd` to start Fossil as a standalone HTTP server, |
| 34 | write the following as `com.example.dev.FossilHTTP.plist`: |
| 35 | |
| 36 | ```xml |
| 37 | <?xml version="1.0" encoding="UTF-8"?> |
| 38 | <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" |
| 39 | "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> |
| 40 | <plist version="1.0"> |
| 41 | <dict> |
| 42 | <key>Label</key> |
| 43 | <string>com.example.dev.FossilHTTP</string> |
| 44 | <key>ProgramArguments</key> |
| 45 | <array> |
| 46 | <string>/usr/local/bin/fossil</string> |
| 47 | <string>server</string> |
| 48 | <string>--port</string> |
| 49 | <string>9000</string> |
| 50 | <string>repo.fossil</string> |
| 51 | </array> |
| 52 | <key>WorkingDirectory</key> |
| 53 | <string>/Users/you/museum</string> |
| 54 | <key>KeepAlive</key> |
| 55 | <true/> |
| 56 | <key>RunAtLoad</key> |
| 57 | <true/> |
| 58 | <key>StandardErrorPath</key> |
| 59 | <string>/tmp/fossil-error.log</string> |
| 60 | <key>StandardOutPath</key> |
| 61 | <string>/tmp/fossil-info.log</string> |
| 62 | <key>UserName</key> |
| 63 | <string>you</string> |
| 64 | <key>GroupName</key> |
| 65 | <string>staff</string> |
| 66 | <key>InitGroups</key> |
| 67 | <true/> |
| 68 | </dict> |
| 69 | </plist> |
| 70 | ``` |
| 71 | |
| 72 | In this example, we’re assuming your development organization uses the |
| 73 | domain name “`dev.example.org`”, that your short macOS login name is |
| 74 | “`you`”, and that you store your Fossils in “`~/museum`”. Adjust these |
| @@ -81,29 +82,30 @@ | |
| 82 | if you leave the user and group configuration at the tail end of that |
| 83 | plist file out, Fossil will remain running as root! |
| 84 | |
| 85 | Install that file and set it to start with: |
| 86 | |
| 87 | $ sudo install -o root -g wheel -m 644 com.example.dev.FossilHTTP.plist \ |
| 88 | /Library/LaunchDaemons/ |
| 89 | $ sudo launchctl load -w /Library/LaunchDaemons/com.example.dev.FossilHTTP.plist |
| 90 | |
| 91 | Because we set the `RunAtLoad` key, this will also launch the daemon. |
| 92 | |
| 93 | Stop the daemon with: |
| 94 | |
| 95 | $ sudo launchctl unload -w /Library/LaunchDaemons/com.example.dev.FossilHTTP.plist |
| 96 | |
| 97 | |
| 98 | ## Socket Listener |
| 99 | |
| 100 | Another useful method to serve a Fossil repo via `launchd` is by setting |
| 101 | up a socket listener: |
| 102 | |
| 103 | ```xml |
| 104 | <?xml version="1.0" encoding="UTF-8"?> |
| 105 | <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" |
| 106 | "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> |
| 107 | <plist version="1.0"> |
| 108 | <dict> |
| 109 | <key>Label</key> |
| 110 | <string>com.example.dev.FossilSocket</string> |
| 111 | <key>ProgramArguments</key> |
| 112 |
+119
-119
| --- www/server/openbsd/fastcgi.md | ||
| +++ www/server/openbsd/fastcgi.md | ||
| @@ -18,52 +18,52 @@ | ||
| 18 | 18 | |
| 19 | 19 | Use the OpenBSD package manager `pkg_add` to install Fossil, making sure |
| 20 | 20 | to select the statically linked binary. |
| 21 | 21 | |
| 22 | 22 | ```console |
| 23 | - $ doas pkg_add fossil | |
| 24 | - quirks-3.325 signed on 2020-06-12T06:24:53Z | |
| 25 | - Ambiguous: choose package for fossil | |
| 26 | - 0: <None> | |
| 27 | - 1: fossil-2.10v0 | |
| 28 | - 2: fossil-2.10v0-static | |
| 29 | - Your choice: 2 | |
| 30 | - fossil-2.10v0-static: ok | |
| 23 | +$ doas pkg_add fossil | |
| 24 | +quirks-3.325 signed on 2020-06-12T06:24:53Z | |
| 25 | +Ambiguous: choose package for fossil | |
| 26 | + 0: <None> | |
| 27 | + 1: fossil-2.10v0 | |
| 28 | + 2: fossil-2.10v0-static | |
| 29 | +Your choice: 2 | |
| 30 | +fossil-2.10v0-static: ok | |
| 31 | 31 | ``` |
| 32 | 32 | |
| 33 | 33 | This installs Fossil into the chroot. To facilitate local use, create a |
| 34 | 34 | symbolic link of the fossil executable into `/usr/local/bin`. |
| 35 | 35 | |
| 36 | 36 | ```console |
| 37 | - $ doas ln -s /var/www/bin/fossil /usr/local/bin/fossil | |
| 37 | +$ doas ln -s /var/www/bin/fossil /usr/local/bin/fossil | |
| 38 | 38 | ``` |
| 39 | 39 | |
| 40 | 40 | As a privileged user, create the file `/var/www/cgi-bin/scm` with the |
| 41 | 41 | following contents to make the CGI script that `httpd` will execute in |
| 42 | 42 | response to `fsl.domain.tld` requests; all paths are relative to the |
| 43 | 43 | `/var/www` chroot. |
| 44 | 44 | |
| 45 | 45 | ```sh |
| 46 | - #!/bin/fossil | |
| 47 | - directory: /htdocs/fsl.domain.tld | |
| 48 | - notfound: https://domain.tld | |
| 49 | - repolist | |
| 50 | - errorlog: /logs/fossil.log | |
| 46 | +#!/bin/fossil | |
| 47 | +directory: /htdocs/fsl.domain.tld | |
| 48 | +notfound: https://domain.tld | |
| 49 | +repolist | |
| 50 | +errorlog: /logs/fossil.log | |
| 51 | 51 | ``` |
| 52 | 52 | |
| 53 | 53 | The `directory` directive instructs Fossil to serve all repositories |
| 54 | 54 | found in `/var/www/htdocs/fsl.domain.tld`, while `errorlog` sets logging |
| 55 | 55 | to be saved to `/var/www/logs/fossil.log`; create the repository |
| 56 | 56 | directory and log file—making the latter owned by the `www` user, and |
| 57 | 57 | the script executable. |
| 58 | 58 | |
| 59 | 59 | ```console |
| 60 | - $ doas mkdir /var/www/htdocs/fsl.domain.tld | |
| 61 | - $ doas touch /var/www/logs/fossil.log | |
| 62 | - $ doas chown www /var/www/logs/fossil.log | |
| 63 | - $ doas chmod 660 /var/www/logs/fossil.log | |
| 64 | - $ doas chmod 755 /var/www/cgi-bin/scm | |
| 60 | +$ doas mkdir /var/www/htdocs/fsl.domain.tld | |
| 61 | +$ doas touch /var/www/logs/fossil.log | |
| 62 | +$ doas chown www /var/www/logs/fossil.log | |
| 63 | +$ doas chmod 660 /var/www/logs/fossil.log | |
| 64 | +$ doas chmod 755 /var/www/cgi-bin/scm | |
| 65 | 65 | ``` |
| 66 | 66 | |
| 67 | 67 | ## <a id="chroot"></a>Setup chroot |
| 68 | 68 | |
| 69 | 69 | Fossil needs both `/dev/random` and `/dev/null`, which aren't accessible |
| @@ -75,41 +75,41 @@ | ||
| 75 | 75 | startup script to recreate the device files at boot, create a template |
| 76 | 76 | of the needed ``/dev`` tree to automatically populate the memory |
| 77 | 77 | filesystem. |
| 78 | 78 | |
| 79 | 79 | ```console |
| 80 | - $ doas mkdir /var/www/dev | |
| 81 | - $ doas install -d -g daemon /template/dev | |
| 82 | - $ cd /template/dev | |
| 83 | - $ doas /dev/MAKEDEV urandom | |
| 84 | - $ doas mknod -m 666 null c 2 2 | |
| 85 | - $ doas mount_mfs -s 1M -P /template/dev /dev/sd0b /var/www/dev | |
| 86 | - $ ls -l | |
| 87 | - total 0 | |
| 88 | - crw-rw-rw- 1 root daemon 2, 2 Jun 20 08:56 null | |
| 89 | - lrwxr-xr-x 1 root daemon 7 Jun 18 06:30 random@ -> urandom | |
| 90 | - crw-r--r-- 1 root wheel 45, 0 Jun 18 06:30 urandom | |
| 80 | +$ doas mkdir /var/www/dev | |
| 81 | +$ doas install -d -g daemon /template/dev | |
| 82 | +$ cd /template/dev | |
| 83 | +$ doas /dev/MAKEDEV urandom | |
| 84 | +$ doas mknod -m 666 null c 2 2 | |
| 85 | +$ doas mount_mfs -s 1M -P /template/dev /dev/sd0b /var/www/dev | |
| 86 | +$ ls -l | |
| 87 | +total 0 | |
| 88 | +crw-rw-rw- 1 root daemon 2, 2 Jun 20 08:56 null | |
| 89 | +lrwxr-xr-x 1 root daemon 7 Jun 18 06:30 random@ -> urandom | |
| 90 | +crw-r--r-- 1 root wheel 45, 0 Jun 18 06:30 urandom | |
| 91 | 91 | ``` |
| 92 | 92 | |
| 93 | 93 | [mfs]: https://man.openbsd.org/mount_mfs.8 |
| 94 | 94 | |
| 95 | 95 | To make the mountable memory filesystem permanent, open `/etc/fstab` as |
| 96 | 96 | a privileged user and add the following line to automate creation of the |
| 97 | 97 | filesystem at startup: |
| 98 | 98 | |
| 99 | 99 | ```console |
| 100 | - swap /var/www/dev mfs rw,-s=1048576,-P=/template/dev 0 0 | |
| 100 | +swap /var/www/dev mfs rw,-s=1048576,-P=/template/dev 0 0 | |
| 101 | 101 | ``` |
| 102 | 102 | |
| 103 | 103 | The same user that executes the fossil binary must have writable access |
| 104 | 104 | to the repository directory that resides within the chroot; on OpenBSD |
| 105 | 105 | this is `www`. In addition, grant repository directory ownership to the |
| 106 | 106 | user who will push to, pull from, and create repositories. |
| 107 | 107 | |
| 108 | 108 | ```console |
| 109 | - $ doas chown -R user:www /var/www/htdocs/fsl.domain.tld | |
| 110 | - $ doas chmod 770 /var/www/htdocs/fsl.domain.tld | |
| 109 | +$ doas chown -R user:www /var/www/htdocs/fsl.domain.tld | |
| 110 | +$ doas chmod 770 /var/www/htdocs/fsl.domain.tld | |
| 111 | 111 | ``` |
| 112 | 112 | |
| 113 | 113 | ## <a id="httpdconfig"></a>Configure httpd |
| 114 | 114 | |
| 115 | 115 | On OpenBSD, [httpd.conf(5)][httpd] is the configuration file for |
| @@ -123,46 +123,46 @@ | ||
| 123 | 123 | [LE]: https://letsencrypt.org |
| 124 | 124 | [acme]: https://man.openbsd.org/acme-client.1 |
| 125 | 125 | [httpd.conf(5)]: https://man.openbsd.org/httpd.conf.5 |
| 126 | 126 | |
| 127 | 127 | ```apache |
| 128 | - server "fsl.domain.tld" { | |
| 129 | - listen on * port http | |
| 130 | - root "/htdocs/fsl.domain.tld" | |
| 131 | - location "/.well-known/acme-challenge/*" { | |
| 132 | - root "/acme" | |
| 133 | - request strip 2 | |
| 134 | - } | |
| 135 | - location * { | |
| 136 | - block return 301 "https://$HTTP_HOST$REQUEST_URI" | |
| 137 | - } | |
| 138 | - location "/*" { | |
| 139 | - fastcgi { param SCRIPT_FILENAME "/cgi-bin/scm" } | |
| 140 | - } | |
| 141 | - } | |
| 142 | - | |
| 143 | - server "fsl.domain.tld" { | |
| 144 | - listen on * tls port https | |
| 145 | - root "/htdocs/fsl.domain.tld" | |
| 146 | - tls { | |
| 147 | - certificate "/etc/ssl/domain.tld.fullchain.pem" | |
| 148 | - key "/etc/ssl/private/domain.tld.key" | |
| 149 | - } | |
| 150 | - hsts { | |
| 151 | - max-age 15768000 | |
| 152 | - preload | |
| 153 | - subdomains | |
| 154 | - } | |
| 155 | - connection max request body 104857600 | |
| 156 | - location "/*" { | |
| 157 | - fastcgi { param SCRIPT_FILENAME "/cgi-bin/scm" } | |
| 158 | - } | |
| 159 | - location "/.well-known/acme-challenge/*" { | |
| 160 | - root "/acme" | |
| 161 | - request strip 2 | |
| 162 | - } | |
| 163 | - } | |
| 128 | +server "fsl.domain.tld" { | |
| 129 | + listen on * port http | |
| 130 | + root "/htdocs/fsl.domain.tld" | |
| 131 | + location "/.well-known/acme-challenge/*" { | |
| 132 | + root "/acme" | |
| 133 | + request strip 2 | |
| 134 | + } | |
| 135 | + location * { | |
| 136 | + block return 301 "https://$HTTP_HOST$REQUEST_URI" | |
| 137 | + } | |
| 138 | + location "/*" { | |
| 139 | + fastcgi { param SCRIPT_FILENAME "/cgi-bin/scm" } | |
| 140 | + } | |
| 141 | +} | |
| 142 | + | |
| 143 | +server "fsl.domain.tld" { | |
| 144 | + listen on * tls port https | |
| 145 | + root "/htdocs/fsl.domain.tld" | |
| 146 | + tls { | |
| 147 | + certificate "/etc/ssl/domain.tld.fullchain.pem" | |
| 148 | + key "/etc/ssl/private/domain.tld.key" | |
| 149 | + } | |
| 150 | + hsts { | |
| 151 | + max-age 15768000 | |
| 152 | + preload | |
| 153 | + subdomains | |
| 154 | + } | |
| 155 | + connection max request body 104857600 | |
| 156 | + location "/*" { | |
| 157 | + fastcgi { param SCRIPT_FILENAME "/cgi-bin/scm" } | |
| 158 | + } | |
| 159 | + location "/.well-known/acme-challenge/*" { | |
| 160 | + root "/acme" | |
| 161 | + request strip 2 | |
| 162 | + } | |
| 163 | +} | |
| 164 | 164 | ``` |
| 165 | 165 | |
| 166 | 166 | [The default limit][dlim] for HTTP messages in OpenBSD’s `httpd` server |
| 167 | 167 | is 1 MiB. Fossil chunks its sync protocol such that this is not |
| 168 | 168 | normally a problem, but when sending [unversioned content][uv], it uses |
| @@ -187,57 +187,57 @@ | ||
| 187 | 187 | ensure you have a zone record for the subdomain with your registrar or |
| 188 | 188 | nameserver. Then open `/etc/acme-client.conf` as a privileged user to |
| 189 | 189 | configure the request. |
| 190 | 190 | |
| 191 | 191 | ```dosini |
| 192 | - authority letsencrypt { | |
| 193 | - api url "https://acme-v02.api.letsencrypt.org/directory" | |
| 194 | - account key "/etc/acme/letsencrypt-privkey.pem" | |
| 195 | - } | |
| 196 | - | |
| 197 | - authority letsencrypt-staging { | |
| 198 | - api url "https://acme-staging.api.letsencrypt.org/directory" | |
| 199 | - account key "/etc/acme/letsencrypt-staging-privkey.pem" | |
| 200 | - } | |
| 201 | - | |
| 202 | - domain domain.tld { | |
| 203 | - alternative names { www.domain.tld fsl.domain.tld } | |
| 204 | - domain key "/etc/ssl/private/domain.tld.key" | |
| 205 | - domain certificate "/etc/ssl/domain.tld.crt" | |
| 206 | - domain full chain certificate "/etc/ssl/domain.tld.fullchain.pem" | |
| 207 | - sign with letsencrypt | |
| 208 | - } | |
| 192 | +authority letsencrypt { | |
| 193 | + api url "https://acme-v02.api.letsencrypt.org/directory" | |
| 194 | + account key "/etc/acme/letsencrypt-privkey.pem" | |
| 195 | +} | |
| 196 | + | |
| 197 | +authority letsencrypt-staging { | |
| 198 | + api url "https://acme-staging.api.letsencrypt.org/directory" | |
| 199 | + account key "/etc/acme/letsencrypt-staging-privkey.pem" | |
| 200 | +} | |
| 201 | + | |
| 202 | +domain domain.tld { | |
| 203 | + alternative names { www.domain.tld fsl.domain.tld } | |
| 204 | + domain key "/etc/ssl/private/domain.tld.key" | |
| 205 | + domain certificate "/etc/ssl/domain.tld.crt" | |
| 206 | + domain full chain certificate "/etc/ssl/domain.tld.fullchain.pem" | |
| 207 | + sign with letsencrypt | |
| 208 | +} | |
| 209 | 209 | ``` |
| 210 | 210 | |
| 211 | 211 | Start `httpd` with the new configuration file, and issue the certificate |
| 212 | 212 | request. |
| 213 | 213 | |
| 214 | 214 | ```console |
| 215 | - $ doas rcctl start httpd | |
| 216 | - $ doas acme-client -vv domain.tld | |
| 217 | - acme-client: /etc/acme/letsencrypt-privkey.pem: account key exists (not creating) | |
| 218 | - acme-client: /etc/acme/letsencrypt-privkey.pem: loaded RSA account key | |
| 219 | - acme-client: /etc/ssl/private/domain.tld.key: generated RSA domain key | |
| 220 | - acme-client: https://acme-v01.api.letsencrypt.org/directory: directories | |
| 221 | - acme-client: acme-v01.api.letsencrypt.org: DNS: 172.65.32.248 | |
| 222 | - ... | |
| 223 | - N(Q????Z???j?j?>W#????b???? H????eb??T??*? DNosz(???n{L}???D???4[?B] (1174 bytes) | |
| 224 | - acme-client: /etc/ssl/domain.tld.crt: created | |
| 225 | - acme-client: /etc/ssl/domain.tld.fullchain.pem: created | |
| 215 | +$ doas rcctl start httpd | |
| 216 | +$ doas acme-client -vv domain.tld | |
| 217 | +acme-client: /etc/acme/letsencrypt-privkey.pem: account key exists (not creating) | |
| 218 | +acme-client: /etc/acme/letsencrypt-privkey.pem: loaded RSA account key | |
| 219 | +acme-client: /etc/ssl/private/domain.tld.key: generated RSA domain key | |
| 220 | +acme-client: https://acme-v01.api.letsencrypt.org/directory: directories | |
| 221 | +acme-client: acme-v01.api.letsencrypt.org: DNS: 172.65.32.248 | |
| 222 | +... | |
| 223 | +N(Q????Z???j?j?>W#????b???? H????eb??T??*? DNosz(???n{L}???D???4[?B] (1174 bytes) | |
| 224 | +acme-client: /etc/ssl/domain.tld.crt: created | |
| 225 | +acme-client: /etc/ssl/domain.tld.fullchain.pem: created | |
| 226 | 226 | ``` |
| 227 | 227 | |
| 228 | 228 | A successful result will output the public certificate, full chain of |
| 229 | 229 | trust, and private key into the `/etc/ssl` directory as specified in |
| 230 | 230 | `acme-client.conf`. |
| 231 | 231 | |
| 232 | 232 | ```console |
| 233 | - $ doas ls -lR /etc/ssl | |
| 234 | - -r--r--r-- 1 root wheel 2.3K Mar 2 01:31:03 2018 domain.tld.crt | |
| 235 | - -r--r--r-- 1 root wheel 3.9K Mar 2 01:31:03 2018 domain.tld.fullchain.pem | |
| 233 | +$ doas ls -lR /etc/ssl | |
| 234 | +-r--r--r-- 1 root wheel 2.3K Mar 2 01:31:03 2018 domain.tld.crt | |
| 235 | +-r--r--r-- 1 root wheel 3.9K Mar 2 01:31:03 2018 domain.tld.fullchain.pem | |
| 236 | 236 | |
| 237 | - /etc/ssl/private: | |
| 238 | - -r-------- 1 root wheel 3.2K Mar 2 01:31:03 2018 domain.tld.key | |
| 237 | +/etc/ssl/private: | |
| 238 | +-r-------- 1 root wheel 3.2K Mar 2 01:31:03 2018 domain.tld.key | |
| 239 | 239 | ``` |
| 240 | 240 | |
| 241 | 241 | Make sure to reopen `/etc/httpd.conf` to uncomment the second server |
| 242 | 242 | block responsible for serving HTTPS requests before proceeding. |
| 243 | 243 | |
| @@ -249,36 +249,36 @@ | ||
| 249 | 249 | execute the above Fossil CGI script—before checking that the syntax of |
| 250 | 250 | the `httpd.conf` configuration file is correct, and (re)starting the |
| 251 | 251 | server (if still running from requesting a Let's Encrypt certificate). |
| 252 | 252 | |
| 253 | 253 | ```console |
| 254 | - $ doas rcctl enable slowcgi | |
| 255 | - $ doas rcctl start slowcgi | |
| 256 | - slowcgi(ok) | |
| 257 | - $ doas httpd -vnf /etc/httpd.conf | |
| 258 | - configuration OK | |
| 259 | - $ doas rcctl start httpd | |
| 260 | - httpd(ok) | |
| 254 | +$ doas rcctl enable slowcgi | |
| 255 | +$ doas rcctl start slowcgi | |
| 256 | +slowcgi(ok) | |
| 257 | +$ doas httpd -vnf /etc/httpd.conf | |
| 258 | +configuration OK | |
| 259 | +$ doas rcctl start httpd | |
| 260 | +httpd(ok) | |
| 261 | 261 | ``` |
| 262 | 262 | |
| 263 | 263 | ## <a id="clientconfig"></a>Configure Client |
| 264 | 264 | |
| 265 | 265 | To facilitate creating new repositories and pushing them to the server, |
| 266 | 266 | add the following function to your `~/.cshrc` or `~/.zprofile` or the |
| 267 | 267 | config file for whichever shell you are using on your development box. |
| 268 | 268 | |
| 269 | 269 | ```sh |
| 270 | - finit() { | |
| 271 | - fossil init $1.fossil && \ | |
| 272 | - chmod 664 $1.fossil && \ | |
| 273 | - fossil open $1.fossil && \ | |
| 274 | - fossil user password $USER $PASSWD && \ | |
| 275 | - fossil remote-url https://$USER:[email protected]/$1 && \ | |
| 276 | - rsync --perms $1.fossil [email protected]:/var/www/htdocs/fsl.domain.tld/ >/dev/null && \ | |
| 277 | - chmod 644 $1.fossil && \ | |
| 278 | - fossil ui | |
| 279 | - } | |
| 270 | +finit() { | |
| 271 | + fossil init $1.fossil && \ | |
| 272 | + chmod 664 $1.fossil && \ | |
| 273 | + fossil open $1.fossil && \ | |
| 274 | + fossil user password $USER $PASSWD && \ | |
| 275 | + fossil remote-url https://$USER:[email protected]/$1 && \ | |
| 276 | + rsync --perms $1.fossil [email protected]:/var/www/htdocs/fsl.domain.tld/ >/dev/null && \ | |
| 277 | + chmod 644 $1.fossil && \ | |
| 278 | + fossil ui | |
| 279 | +} | |
| 280 | 280 | ``` |
| 281 | 281 | |
| 282 | 282 | This enables a new repository to be made with `finit repo`, which will |
| 283 | 283 | create the fossil repository file `repo.fossil` in the current working |
| 284 | 284 | directory; by default, the repository user is set to the environment |
| 285 | 285 |
| --- www/server/openbsd/fastcgi.md | |
| +++ www/server/openbsd/fastcgi.md | |
| @@ -18,52 +18,52 @@ | |
| 18 | |
| 19 | Use the OpenBSD package manager `pkg_add` to install Fossil, making sure |
| 20 | to select the statically linked binary. |
| 21 | |
| 22 | ```console |
| 23 | $ doas pkg_add fossil |
| 24 | quirks-3.325 signed on 2020-06-12T06:24:53Z |
| 25 | Ambiguous: choose package for fossil |
| 26 | 0: <None> |
| 27 | 1: fossil-2.10v0 |
| 28 | 2: fossil-2.10v0-static |
| 29 | Your choice: 2 |
| 30 | fossil-2.10v0-static: ok |
| 31 | ``` |
| 32 | |
| 33 | This installs Fossil into the chroot. To facilitate local use, create a |
| 34 | symbolic link of the fossil executable into `/usr/local/bin`. |
| 35 | |
| 36 | ```console |
| 37 | $ doas ln -s /var/www/bin/fossil /usr/local/bin/fossil |
| 38 | ``` |
| 39 | |
| 40 | As a privileged user, create the file `/var/www/cgi-bin/scm` with the |
| 41 | following contents to make the CGI script that `httpd` will execute in |
| 42 | response to `fsl.domain.tld` requests; all paths are relative to the |
| 43 | `/var/www` chroot. |
| 44 | |
| 45 | ```sh |
| 46 | #!/bin/fossil |
| 47 | directory: /htdocs/fsl.domain.tld |
| 48 | notfound: https://domain.tld |
| 49 | repolist |
| 50 | errorlog: /logs/fossil.log |
| 51 | ``` |
| 52 | |
| 53 | The `directory` directive instructs Fossil to serve all repositories |
| 54 | found in `/var/www/htdocs/fsl.domain.tld`, while `errorlog` sets logging |
| 55 | to be saved to `/var/www/logs/fossil.log`; create the repository |
| 56 | directory and log file—making the latter owned by the `www` user, and |
| 57 | the script executable. |
| 58 | |
| 59 | ```console |
| 60 | $ doas mkdir /var/www/htdocs/fsl.domain.tld |
| 61 | $ doas touch /var/www/logs/fossil.log |
| 62 | $ doas chown www /var/www/logs/fossil.log |
| 63 | $ doas chmod 660 /var/www/logs/fossil.log |
| 64 | $ doas chmod 755 /var/www/cgi-bin/scm |
| 65 | ``` |
| 66 | |
| 67 | ## <a id="chroot"></a>Setup chroot |
| 68 | |
| 69 | Fossil needs both `/dev/random` and `/dev/null`, which aren't accessible |
| @@ -75,41 +75,41 @@ | |
| 75 | startup script to recreate the device files at boot, create a template |
| 76 | of the needed ``/dev`` tree to automatically populate the memory |
| 77 | filesystem. |
| 78 | |
| 79 | ```console |
| 80 | $ doas mkdir /var/www/dev |
| 81 | $ doas install -d -g daemon /template/dev |
| 82 | $ cd /template/dev |
| 83 | $ doas /dev/MAKEDEV urandom |
| 84 | $ doas mknod -m 666 null c 2 2 |
| 85 | $ doas mount_mfs -s 1M -P /template/dev /dev/sd0b /var/www/dev |
| 86 | $ ls -l |
| 87 | total 0 |
| 88 | crw-rw-rw- 1 root daemon 2, 2 Jun 20 08:56 null |
| 89 | lrwxr-xr-x 1 root daemon 7 Jun 18 06:30 random@ -> urandom |
| 90 | crw-r--r-- 1 root wheel 45, 0 Jun 18 06:30 urandom |
| 91 | ``` |
| 92 | |
| 93 | [mfs]: https://man.openbsd.org/mount_mfs.8 |
| 94 | |
| 95 | To make the mountable memory filesystem permanent, open `/etc/fstab` as |
| 96 | a privileged user and add the following line to automate creation of the |
| 97 | filesystem at startup: |
| 98 | |
| 99 | ```console |
| 100 | swap /var/www/dev mfs rw,-s=1048576,-P=/template/dev 0 0 |
| 101 | ``` |
| 102 | |
| 103 | The same user that executes the fossil binary must have writable access |
| 104 | to the repository directory that resides within the chroot; on OpenBSD |
| 105 | this is `www`. In addition, grant repository directory ownership to the |
| 106 | user who will push to, pull from, and create repositories. |
| 107 | |
| 108 | ```console |
| 109 | $ doas chown -R user:www /var/www/htdocs/fsl.domain.tld |
| 110 | $ doas chmod 770 /var/www/htdocs/fsl.domain.tld |
| 111 | ``` |
| 112 | |
| 113 | ## <a id="httpdconfig"></a>Configure httpd |
| 114 | |
| 115 | On OpenBSD, [httpd.conf(5)][httpd] is the configuration file for |
| @@ -123,46 +123,46 @@ | |
| 123 | [LE]: https://letsencrypt.org |
| 124 | [acme]: https://man.openbsd.org/acme-client.1 |
| 125 | [httpd.conf(5)]: https://man.openbsd.org/httpd.conf.5 |
| 126 | |
| 127 | ```apache |
| 128 | server "fsl.domain.tld" { |
| 129 | listen on * port http |
| 130 | root "/htdocs/fsl.domain.tld" |
| 131 | location "/.well-known/acme-challenge/*" { |
| 132 | root "/acme" |
| 133 | request strip 2 |
| 134 | } |
| 135 | location * { |
| 136 | block return 301 "https://$HTTP_HOST$REQUEST_URI" |
| 137 | } |
| 138 | location "/*" { |
| 139 | fastcgi { param SCRIPT_FILENAME "/cgi-bin/scm" } |
| 140 | } |
| 141 | } |
| 142 | |
| 143 | server "fsl.domain.tld" { |
| 144 | listen on * tls port https |
| 145 | root "/htdocs/fsl.domain.tld" |
| 146 | tls { |
| 147 | certificate "/etc/ssl/domain.tld.fullchain.pem" |
| 148 | key "/etc/ssl/private/domain.tld.key" |
| 149 | } |
| 150 | hsts { |
| 151 | max-age 15768000 |
| 152 | preload |
| 153 | subdomains |
| 154 | } |
| 155 | connection max request body 104857600 |
| 156 | location "/*" { |
| 157 | fastcgi { param SCRIPT_FILENAME "/cgi-bin/scm" } |
| 158 | } |
| 159 | location "/.well-known/acme-challenge/*" { |
| 160 | root "/acme" |
| 161 | request strip 2 |
| 162 | } |
| 163 | } |
| 164 | ``` |
| 165 | |
| 166 | [The default limit][dlim] for HTTP messages in OpenBSD’s `httpd` server |
| 167 | is 1 MiB. Fossil chunks its sync protocol such that this is not |
| 168 | normally a problem, but when sending [unversioned content][uv], it uses |
| @@ -187,57 +187,57 @@ | |
| 187 | ensure you have a zone record for the subdomain with your registrar or |
| 188 | nameserver. Then open `/etc/acme-client.conf` as a privileged user to |
| 189 | configure the request. |
| 190 | |
| 191 | ```dosini |
| 192 | authority letsencrypt { |
| 193 | api url "https://acme-v02.api.letsencrypt.org/directory" |
| 194 | account key "/etc/acme/letsencrypt-privkey.pem" |
| 195 | } |
| 196 | |
| 197 | authority letsencrypt-staging { |
| 198 | api url "https://acme-staging.api.letsencrypt.org/directory" |
| 199 | account key "/etc/acme/letsencrypt-staging-privkey.pem" |
| 200 | } |
| 201 | |
| 202 | domain domain.tld { |
| 203 | alternative names { www.domain.tld fsl.domain.tld } |
| 204 | domain key "/etc/ssl/private/domain.tld.key" |
| 205 | domain certificate "/etc/ssl/domain.tld.crt" |
| 206 | domain full chain certificate "/etc/ssl/domain.tld.fullchain.pem" |
| 207 | sign with letsencrypt |
| 208 | } |
| 209 | ``` |
| 210 | |
| 211 | Start `httpd` with the new configuration file, and issue the certificate |
| 212 | request. |
| 213 | |
| 214 | ```console |
| 215 | $ doas rcctl start httpd |
| 216 | $ doas acme-client -vv domain.tld |
| 217 | acme-client: /etc/acme/letsencrypt-privkey.pem: account key exists (not creating) |
| 218 | acme-client: /etc/acme/letsencrypt-privkey.pem: loaded RSA account key |
| 219 | acme-client: /etc/ssl/private/domain.tld.key: generated RSA domain key |
| 220 | acme-client: https://acme-v01.api.letsencrypt.org/directory: directories |
| 221 | acme-client: acme-v01.api.letsencrypt.org: DNS: 172.65.32.248 |
| 222 | ... |
| 223 | N(Q????Z???j?j?>W#????b???? H????eb??T??*? DNosz(???n{L}???D???4[?B] (1174 bytes) |
| 224 | acme-client: /etc/ssl/domain.tld.crt: created |
| 225 | acme-client: /etc/ssl/domain.tld.fullchain.pem: created |
| 226 | ``` |
| 227 | |
| 228 | A successful result will output the public certificate, full chain of |
| 229 | trust, and private key into the `/etc/ssl` directory as specified in |
| 230 | `acme-client.conf`. |
| 231 | |
| 232 | ```console |
| 233 | $ doas ls -lR /etc/ssl |
| 234 | -r--r--r-- 1 root wheel 2.3K Mar 2 01:31:03 2018 domain.tld.crt |
| 235 | -r--r--r-- 1 root wheel 3.9K Mar 2 01:31:03 2018 domain.tld.fullchain.pem |
| 236 | |
| 237 | /etc/ssl/private: |
| 238 | -r-------- 1 root wheel 3.2K Mar 2 01:31:03 2018 domain.tld.key |
| 239 | ``` |
| 240 | |
| 241 | Make sure to reopen `/etc/httpd.conf` to uncomment the second server |
| 242 | block responsible for serving HTTPS requests before proceeding. |
| 243 | |
| @@ -249,36 +249,36 @@ | |
| 249 | execute the above Fossil CGI script—before checking that the syntax of |
| 250 | the `httpd.conf` configuration file is correct, and (re)starting the |
| 251 | server (if still running from requesting a Let's Encrypt certificate). |
| 252 | |
| 253 | ```console |
| 254 | $ doas rcctl enable slowcgi |
| 255 | $ doas rcctl start slowcgi |
| 256 | slowcgi(ok) |
| 257 | $ doas httpd -vnf /etc/httpd.conf |
| 258 | configuration OK |
| 259 | $ doas rcctl start httpd |
| 260 | httpd(ok) |
| 261 | ``` |
| 262 | |
| 263 | ## <a id="clientconfig"></a>Configure Client |
| 264 | |
| 265 | To facilitate creating new repositories and pushing them to the server, |
| 266 | add the following function to your `~/.cshrc` or `~/.zprofile` or the |
| 267 | config file for whichever shell you are using on your development box. |
| 268 | |
| 269 | ```sh |
| 270 | finit() { |
| 271 | fossil init $1.fossil && \ |
| 272 | chmod 664 $1.fossil && \ |
| 273 | fossil open $1.fossil && \ |
| 274 | fossil user password $USER $PASSWD && \ |
| 275 | fossil remote-url https://$USER:[email protected]/$1 && \ |
| 276 | rsync --perms $1.fossil [email protected]:/var/www/htdocs/fsl.domain.tld/ >/dev/null && \ |
| 277 | chmod 644 $1.fossil && \ |
| 278 | fossil ui |
| 279 | } |
| 280 | ``` |
| 281 | |
| 282 | This enables a new repository to be made with `finit repo`, which will |
| 283 | create the fossil repository file `repo.fossil` in the current working |
| 284 | directory; by default, the repository user is set to the environment |
| 285 |
| --- www/server/openbsd/fastcgi.md | |
| +++ www/server/openbsd/fastcgi.md | |
| @@ -18,52 +18,52 @@ | |
| 18 | |
| 19 | Use the OpenBSD package manager `pkg_add` to install Fossil, making sure |
| 20 | to select the statically linked binary. |
| 21 | |
| 22 | ```console |
| 23 | $ doas pkg_add fossil |
| 24 | quirks-3.325 signed on 2020-06-12T06:24:53Z |
| 25 | Ambiguous: choose package for fossil |
| 26 | 0: <None> |
| 27 | 1: fossil-2.10v0 |
| 28 | 2: fossil-2.10v0-static |
| 29 | Your choice: 2 |
| 30 | fossil-2.10v0-static: ok |
| 31 | ``` |
| 32 | |
| 33 | This installs Fossil into the chroot. To facilitate local use, create a |
| 34 | symbolic link of the fossil executable into `/usr/local/bin`. |
| 35 | |
| 36 | ```console |
| 37 | $ doas ln -s /var/www/bin/fossil /usr/local/bin/fossil |
| 38 | ``` |
| 39 | |
| 40 | As a privileged user, create the file `/var/www/cgi-bin/scm` with the |
| 41 | following contents to make the CGI script that `httpd` will execute in |
| 42 | response to `fsl.domain.tld` requests; all paths are relative to the |
| 43 | `/var/www` chroot. |
| 44 | |
| 45 | ```sh |
| 46 | #!/bin/fossil |
| 47 | directory: /htdocs/fsl.domain.tld |
| 48 | notfound: https://domain.tld |
| 49 | repolist |
| 50 | errorlog: /logs/fossil.log |
| 51 | ``` |
| 52 | |
| 53 | The `directory` directive instructs Fossil to serve all repositories |
| 54 | found in `/var/www/htdocs/fsl.domain.tld`, while `errorlog` sets logging |
| 55 | to be saved to `/var/www/logs/fossil.log`; create the repository |
| 56 | directory and log file—making the latter owned by the `www` user, and |
| 57 | the script executable. |
| 58 | |
| 59 | ```console |
| 60 | $ doas mkdir /var/www/htdocs/fsl.domain.tld |
| 61 | $ doas touch /var/www/logs/fossil.log |
| 62 | $ doas chown www /var/www/logs/fossil.log |
| 63 | $ doas chmod 660 /var/www/logs/fossil.log |
| 64 | $ doas chmod 755 /var/www/cgi-bin/scm |
| 65 | ``` |
| 66 | |
| 67 | ## <a id="chroot"></a>Setup chroot |
| 68 | |
| 69 | Fossil needs both `/dev/random` and `/dev/null`, which aren't accessible |
| @@ -75,41 +75,41 @@ | |
| 75 | startup script to recreate the device files at boot, create a template |
| 76 | of the needed ``/dev`` tree to automatically populate the memory |
| 77 | filesystem. |
| 78 | |
| 79 | ```console |
| 80 | $ doas mkdir /var/www/dev |
| 81 | $ doas install -d -g daemon /template/dev |
| 82 | $ cd /template/dev |
| 83 | $ doas /dev/MAKEDEV urandom |
| 84 | $ doas mknod -m 666 null c 2 2 |
| 85 | $ doas mount_mfs -s 1M -P /template/dev /dev/sd0b /var/www/dev |
| 86 | $ ls -l |
| 87 | total 0 |
| 88 | crw-rw-rw- 1 root daemon 2, 2 Jun 20 08:56 null |
| 89 | lrwxr-xr-x 1 root daemon 7 Jun 18 06:30 random@ -> urandom |
| 90 | crw-r--r-- 1 root wheel 45, 0 Jun 18 06:30 urandom |
| 91 | ``` |
| 92 | |
| 93 | [mfs]: https://man.openbsd.org/mount_mfs.8 |
| 94 | |
| 95 | To make the mountable memory filesystem permanent, open `/etc/fstab` as |
| 96 | a privileged user and add the following line to automate creation of the |
| 97 | filesystem at startup: |
| 98 | |
| 99 | ```console |
| 100 | swap /var/www/dev mfs rw,-s=1048576,-P=/template/dev 0 0 |
| 101 | ``` |
| 102 | |
| 103 | The same user that executes the fossil binary must have writable access |
| 104 | to the repository directory that resides within the chroot; on OpenBSD |
| 105 | this is `www`. In addition, grant repository directory ownership to the |
| 106 | user who will push to, pull from, and create repositories. |
| 107 | |
| 108 | ```console |
| 109 | $ doas chown -R user:www /var/www/htdocs/fsl.domain.tld |
| 110 | $ doas chmod 770 /var/www/htdocs/fsl.domain.tld |
| 111 | ``` |
| 112 | |
| 113 | ## <a id="httpdconfig"></a>Configure httpd |
| 114 | |
| 115 | On OpenBSD, [httpd.conf(5)][httpd] is the configuration file for |
| @@ -123,46 +123,46 @@ | |
| 123 | [LE]: https://letsencrypt.org |
| 124 | [acme]: https://man.openbsd.org/acme-client.1 |
| 125 | [httpd.conf(5)]: https://man.openbsd.org/httpd.conf.5 |
| 126 | |
| 127 | ```apache |
| 128 | server "fsl.domain.tld" { |
| 129 | listen on * port http |
| 130 | root "/htdocs/fsl.domain.tld" |
| 131 | location "/.well-known/acme-challenge/*" { |
| 132 | root "/acme" |
| 133 | request strip 2 |
| 134 | } |
| 135 | location * { |
| 136 | block return 301 "https://$HTTP_HOST$REQUEST_URI" |
| 137 | } |
| 138 | location "/*" { |
| 139 | fastcgi { param SCRIPT_FILENAME "/cgi-bin/scm" } |
| 140 | } |
| 141 | } |
| 142 | |
| 143 | server "fsl.domain.tld" { |
| 144 | listen on * tls port https |
| 145 | root "/htdocs/fsl.domain.tld" |
| 146 | tls { |
| 147 | certificate "/etc/ssl/domain.tld.fullchain.pem" |
| 148 | key "/etc/ssl/private/domain.tld.key" |
| 149 | } |
| 150 | hsts { |
| 151 | max-age 15768000 |
| 152 | preload |
| 153 | subdomains |
| 154 | } |
| 155 | connection max request body 104857600 |
| 156 | location "/*" { |
| 157 | fastcgi { param SCRIPT_FILENAME "/cgi-bin/scm" } |
| 158 | } |
| 159 | location "/.well-known/acme-challenge/*" { |
| 160 | root "/acme" |
| 161 | request strip 2 |
| 162 | } |
| 163 | } |
| 164 | ``` |
| 165 | |
| 166 | [The default limit][dlim] for HTTP messages in OpenBSD’s `httpd` server |
| 167 | is 1 MiB. Fossil chunks its sync protocol such that this is not |
| 168 | normally a problem, but when sending [unversioned content][uv], it uses |
| @@ -187,57 +187,57 @@ | |
| 187 | ensure you have a zone record for the subdomain with your registrar or |
| 188 | nameserver. Then open `/etc/acme-client.conf` as a privileged user to |
| 189 | configure the request. |
| 190 | |
| 191 | ```dosini |
| 192 | authority letsencrypt { |
| 193 | api url "https://acme-v02.api.letsencrypt.org/directory" |
| 194 | account key "/etc/acme/letsencrypt-privkey.pem" |
| 195 | } |
| 196 | |
| 197 | authority letsencrypt-staging { |
| 198 | api url "https://acme-staging.api.letsencrypt.org/directory" |
| 199 | account key "/etc/acme/letsencrypt-staging-privkey.pem" |
| 200 | } |
| 201 | |
| 202 | domain domain.tld { |
| 203 | alternative names { www.domain.tld fsl.domain.tld } |
| 204 | domain key "/etc/ssl/private/domain.tld.key" |
| 205 | domain certificate "/etc/ssl/domain.tld.crt" |
| 206 | domain full chain certificate "/etc/ssl/domain.tld.fullchain.pem" |
| 207 | sign with letsencrypt |
| 208 | } |
| 209 | ``` |
| 210 | |
| 211 | Start `httpd` with the new configuration file, and issue the certificate |
| 212 | request. |
| 213 | |
| 214 | ```console |
| 215 | $ doas rcctl start httpd |
| 216 | $ doas acme-client -vv domain.tld |
| 217 | acme-client: /etc/acme/letsencrypt-privkey.pem: account key exists (not creating) |
| 218 | acme-client: /etc/acme/letsencrypt-privkey.pem: loaded RSA account key |
| 219 | acme-client: /etc/ssl/private/domain.tld.key: generated RSA domain key |
| 220 | acme-client: https://acme-v01.api.letsencrypt.org/directory: directories |
| 221 | acme-client: acme-v01.api.letsencrypt.org: DNS: 172.65.32.248 |
| 222 | ... |
| 223 | N(Q????Z???j?j?>W#????b???? H????eb??T??*? DNosz(???n{L}???D???4[?B] (1174 bytes) |
| 224 | acme-client: /etc/ssl/domain.tld.crt: created |
| 225 | acme-client: /etc/ssl/domain.tld.fullchain.pem: created |
| 226 | ``` |
| 227 | |
| 228 | A successful result will output the public certificate, full chain of |
| 229 | trust, and private key into the `/etc/ssl` directory as specified in |
| 230 | `acme-client.conf`. |
| 231 | |
| 232 | ```console |
| 233 | $ doas ls -lR /etc/ssl |
| 234 | -r--r--r-- 1 root wheel 2.3K Mar 2 01:31:03 2018 domain.tld.crt |
| 235 | -r--r--r-- 1 root wheel 3.9K Mar 2 01:31:03 2018 domain.tld.fullchain.pem |
| 236 | |
| 237 | /etc/ssl/private: |
| 238 | -r-------- 1 root wheel 3.2K Mar 2 01:31:03 2018 domain.tld.key |
| 239 | ``` |
| 240 | |
| 241 | Make sure to reopen `/etc/httpd.conf` to uncomment the second server |
| 242 | block responsible for serving HTTPS requests before proceeding. |
| 243 | |
| @@ -249,36 +249,36 @@ | |
| 249 | execute the above Fossil CGI script—before checking that the syntax of |
| 250 | the `httpd.conf` configuration file is correct, and (re)starting the |
| 251 | server (if still running from requesting a Let's Encrypt certificate). |
| 252 | |
| 253 | ```console |
| 254 | $ doas rcctl enable slowcgi |
| 255 | $ doas rcctl start slowcgi |
| 256 | slowcgi(ok) |
| 257 | $ doas httpd -vnf /etc/httpd.conf |
| 258 | configuration OK |
| 259 | $ doas rcctl start httpd |
| 260 | httpd(ok) |
| 261 | ``` |
| 262 | |
| 263 | ## <a id="clientconfig"></a>Configure Client |
| 264 | |
| 265 | To facilitate creating new repositories and pushing them to the server, |
| 266 | add the following function to your `~/.cshrc` or `~/.zprofile` or the |
| 267 | config file for whichever shell you are using on your development box. |
| 268 | |
| 269 | ```sh |
| 270 | finit() { |
| 271 | fossil init $1.fossil && \ |
| 272 | chmod 664 $1.fossil && \ |
| 273 | fossil open $1.fossil && \ |
| 274 | fossil user password $USER $PASSWD && \ |
| 275 | fossil remote-url https://$USER:[email protected]/$1 && \ |
| 276 | rsync --perms $1.fossil [email protected]:/var/www/htdocs/fsl.domain.tld/ >/dev/null && \ |
| 277 | chmod 644 $1.fossil && \ |
| 278 | fossil ui |
| 279 | } |
| 280 | ``` |
| 281 | |
| 282 | This enables a new repository to be made with `finit repo`, which will |
| 283 | create the fossil repository file `repo.fossil` in the current working |
| 284 | directory; by default, the repository user is set to the environment |
| 285 |
+22
-16
| --- www/server/openbsd/service.wiki | ||
| +++ www/server/openbsd/service.wiki | ||
| @@ -2,13 +2,14 @@ | ||
| 2 | 2 | |
| 3 | 3 | OpenBSD provides [https://man.openbsd.org/rc.subr.8|rc.subr(8)], |
| 4 | 4 | a framework for writing [https://man.openbsd.org/rc.8|rc(8)] scripts. |
| 5 | 5 | |
| 6 | 6 | <h2>Creating the daemon</h2> |
| 7 | + | |
| 7 | 8 | Create the file /etc/rc.d/fossil with contents like the following. |
| 8 | 9 | |
| 9 | -<blockquote><pre> | |
| 10 | +<pre> | |
| 10 | 11 | #!/bin/ksh |
| 11 | 12 | daemon="/usr/local/bin/fossil" # fossil executable |
| 12 | 13 | daemon_user="_fossil" # user to run fossil as |
| 13 | 14 | daemon_flags="server /home/_fossil/example --repolist --port 8888" # fossil command |
| 14 | 15 | |
| @@ -15,56 +16,59 @@ | ||
| 15 | 16 | . /etc/rc.d/rc.subr |
| 16 | 17 | # pexp="$daemon server .*" # See below. |
| 17 | 18 | rc_reload=NO # Unsupported by Fossil; 'rcctl reload fossil' kills the process. |
| 18 | 19 | rc_bg=YES # Run in the background, since fossil serve does not daemonize itself |
| 19 | 20 | rc_cmd $1 |
| 20 | -</pre></blockquote> | |
| 21 | +</pre> | |
| 21 | 22 | |
| 22 | 23 | <h3>pexp</h3> |
| 24 | + | |
| 23 | 25 | You may need to uncomment the "pexp=". rc.subr typically |
| 24 | 26 | finds the daemon process based by matching the process name and argument list. |
| 25 | 27 | Without the "pexp=" line, rc.subr would look for this exact command: |
| 26 | 28 | |
| 27 | -<blockquote><pre> | |
| 29 | +<pre> | |
| 28 | 30 | /usr/local/bin/fossil server /home/_fossil/example --repolist --port 8888 |
| 29 | -</pre></blockquote> | |
| 31 | +</pre> | |
| 30 | 32 | |
| 31 | 33 | Depending on the arguments and their order, fossil may rewrite the arguments |
| 32 | 34 | for display in the process listing ([https://man.openbsd.org/ps.1|ps(1)]), |
| 33 | 35 | so rc.subr may fail to find the process through the default match. The example |
| 34 | 36 | above does not get rewritten, but the same commands in a different order can |
| 35 | 37 | be rewritten. |
| 36 | 38 | For example, when I switch the order of the arguments in "daemon_flags", |
| 37 | 39 | |
| 38 | -<blockquote><pre> | |
| 40 | +<pre> | |
| 39 | 41 | /usr/local/bin/fossil server --repolist --port 8888 /home/_fossil/example |
| 40 | -</pre></blockquote> | |
| 42 | +</pre> | |
| 41 | 43 | |
| 42 | 44 | the process command is changed to this. |
| 43 | 45 | |
| 44 | -<blockquote><pre> | |
| 46 | +<pre> | |
| 45 | 47 | /usr/local/bin/fossil server /home/_fossil/example /home/_fossil/example 8888 /home/_fossil/example |
| 46 | -</pre></blockquote> | |
| 48 | +</pre> | |
| 47 | 49 | |
| 48 | 50 | The commented "pexp=" line instructs rc.subr to choose the process whose |
| 49 | 51 | command and arguments text starts with this: |
| 50 | 52 | |
| 51 | -<blockquote><pre> | |
| 53 | +<pre> | |
| 52 | 54 | /usr/local/bin/fossil server |
| 53 | -</pre></blockquote> | |
| 55 | +</pre> | |
| 54 | 56 | |
| 55 | 57 | <h2>Enabling the daemon</h2> |
| 58 | + | |
| 56 | 59 | Once you have created /etc/rc.d/fossil, run these commands. |
| 57 | 60 | |
| 58 | -<blockquote><pre> | |
| 61 | +<pre> | |
| 59 | 62 | rcctl enable fossil # add fossil to pkg_scripts in /etc/rc.conf.local |
| 60 | 63 | rcctl start fossil # start the daemon now |
| 61 | -</pre></blockquote> | |
| 64 | +</pre> | |
| 62 | 65 | |
| 63 | 66 | The daemon should now be running and set to start at boot. |
| 64 | 67 | |
| 65 | 68 | <h2>Multiple daemons</h2> |
| 69 | + | |
| 66 | 70 | You may want to serve multiple fossil instances with different options. |
| 67 | 71 | For example, |
| 68 | 72 | |
| 69 | 73 | * If different users own different repositories, you may want different users |
| 70 | 74 | to serve different repositories. |
| @@ -75,38 +79,40 @@ | ||
| 75 | 79 | To run multiple fossil daemons, create multiple files in /etc/rc.d, and |
| 76 | 80 | enable each of them. Here are two approaches for creating |
| 77 | 81 | the files in /etc/rc.d: Symbolic links and copies. |
| 78 | 82 | |
| 79 | 83 | <h3>Symbolic links</h3> |
| 84 | + | |
| 80 | 85 | Suppose you want to run one fossil daemon as user "user1" on port 8881 |
| 81 | 86 | and another as user "user2" on port 8882. Create the files with |
| 82 | 87 | [https://man.openbsd.org/ln.1|ln(1)], and configure them to run different |
| 83 | 88 | fossil commands. |
| 84 | 89 | |
| 85 | -<blockquote><pre> | |
| 90 | +<pre> | |
| 86 | 91 | cd /etc/rc.d |
| 87 | 92 | ln -s fossil fossil1 |
| 88 | 93 | ln -s fossil fossil2 |
| 89 | 94 | rcctl enable fossil1 fossil2 |
| 90 | 95 | rcctl set fossil1 user user1 |
| 91 | 96 | rcctl set fossil2 user user2 |
| 92 | 97 | rcctl set fossil1 flags 'server /home/user1/repo1.fossil --port 8881' |
| 93 | 98 | rcctl set fossil2 flags 'server /home/user2/repo2.fossil --port 8882' |
| 94 | 99 | rcctl start fossil1 fossil2 |
| 95 | -</pre></blockquote> | |
| 100 | +</pre> | |
| 96 | 101 | |
| 97 | 102 | <h3>Copies</h3> |
| 103 | + | |
| 98 | 104 | You may want to run fossil daemons that are too different to configure |
| 99 | 105 | just with [https://man.openbsd.org/rcctl.8|rcctl(8)]. |
| 100 | 106 | In particular, you can't change the "pexp" with rcctl. |
| 101 | 107 | |
| 102 | 108 | If you want to run fossil commands that are more different, |
| 103 | 109 | you may prefer to create separate files in /etc/rc.d. |
| 104 | 110 | Replace "ln -s" above with "cp" to accomplish this. |
| 105 | 111 | |
| 106 | -<blockquote><pre> | |
| 112 | +<pre> | |
| 107 | 113 | cp /etc/rc.d/fossil /etc/rc.d/fossil-user1 |
| 108 | 114 | cp /etc/rc.d/fossil /etc/rc.d/fossil-user2 |
| 109 | -</pre></blockquote> | |
| 115 | +</pre> | |
| 110 | 116 | |
| 111 | 117 | You can still use commands like "rcctl set fossil-user1 flags", but you |
| 112 | 118 | can also edit the "/etc/rc.d/fossil-user1" file. |
| 113 | 119 |
| --- www/server/openbsd/service.wiki | |
| +++ www/server/openbsd/service.wiki | |
| @@ -2,13 +2,14 @@ | |
| 2 | |
| 3 | OpenBSD provides [https://man.openbsd.org/rc.subr.8|rc.subr(8)], |
| 4 | a framework for writing [https://man.openbsd.org/rc.8|rc(8)] scripts. |
| 5 | |
| 6 | <h2>Creating the daemon</h2> |
| 7 | Create the file /etc/rc.d/fossil with contents like the following. |
| 8 | |
| 9 | <blockquote><pre> |
| 10 | #!/bin/ksh |
| 11 | daemon="/usr/local/bin/fossil" # fossil executable |
| 12 | daemon_user="_fossil" # user to run fossil as |
| 13 | daemon_flags="server /home/_fossil/example --repolist --port 8888" # fossil command |
| 14 | |
| @@ -15,56 +16,59 @@ | |
| 15 | . /etc/rc.d/rc.subr |
| 16 | # pexp="$daemon server .*" # See below. |
| 17 | rc_reload=NO # Unsupported by Fossil; 'rcctl reload fossil' kills the process. |
| 18 | rc_bg=YES # Run in the background, since fossil serve does not daemonize itself |
| 19 | rc_cmd $1 |
| 20 | </pre></blockquote> |
| 21 | |
| 22 | <h3>pexp</h3> |
| 23 | You may need to uncomment the "pexp=". rc.subr typically |
| 24 | finds the daemon process based by matching the process name and argument list. |
| 25 | Without the "pexp=" line, rc.subr would look for this exact command: |
| 26 | |
| 27 | <blockquote><pre> |
| 28 | /usr/local/bin/fossil server /home/_fossil/example --repolist --port 8888 |
| 29 | </pre></blockquote> |
| 30 | |
| 31 | Depending on the arguments and their order, fossil may rewrite the arguments |
| 32 | for display in the process listing ([https://man.openbsd.org/ps.1|ps(1)]), |
| 33 | so rc.subr may fail to find the process through the default match. The example |
| 34 | above does not get rewritten, but the same commands in a different order can |
| 35 | be rewritten. |
| 36 | For example, when I switch the order of the arguments in "daemon_flags", |
| 37 | |
| 38 | <blockquote><pre> |
| 39 | /usr/local/bin/fossil server --repolist --port 8888 /home/_fossil/example |
| 40 | </pre></blockquote> |
| 41 | |
| 42 | the process command is changed to this. |
| 43 | |
| 44 | <blockquote><pre> |
| 45 | /usr/local/bin/fossil server /home/_fossil/example /home/_fossil/example 8888 /home/_fossil/example |
| 46 | </pre></blockquote> |
| 47 | |
| 48 | The commented "pexp=" line instructs rc.subr to choose the process whose |
| 49 | command and arguments text starts with this: |
| 50 | |
| 51 | <blockquote><pre> |
| 52 | /usr/local/bin/fossil server |
| 53 | </pre></blockquote> |
| 54 | |
| 55 | <h2>Enabling the daemon</h2> |
| 56 | Once you have created /etc/rc.d/fossil, run these commands. |
| 57 | |
| 58 | <blockquote><pre> |
| 59 | rcctl enable fossil # add fossil to pkg_scripts in /etc/rc.conf.local |
| 60 | rcctl start fossil # start the daemon now |
| 61 | </pre></blockquote> |
| 62 | |
| 63 | The daemon should now be running and set to start at boot. |
| 64 | |
| 65 | <h2>Multiple daemons</h2> |
| 66 | You may want to serve multiple fossil instances with different options. |
| 67 | For example, |
| 68 | |
| 69 | * If different users own different repositories, you may want different users |
| 70 | to serve different repositories. |
| @@ -75,38 +79,40 @@ | |
| 75 | To run multiple fossil daemons, create multiple files in /etc/rc.d, and |
| 76 | enable each of them. Here are two approaches for creating |
| 77 | the files in /etc/rc.d: Symbolic links and copies. |
| 78 | |
| 79 | <h3>Symbolic links</h3> |
| 80 | Suppose you want to run one fossil daemon as user "user1" on port 8881 |
| 81 | and another as user "user2" on port 8882. Create the files with |
| 82 | [https://man.openbsd.org/ln.1|ln(1)], and configure them to run different |
| 83 | fossil commands. |
| 84 | |
| 85 | <blockquote><pre> |
| 86 | cd /etc/rc.d |
| 87 | ln -s fossil fossil1 |
| 88 | ln -s fossil fossil2 |
| 89 | rcctl enable fossil1 fossil2 |
| 90 | rcctl set fossil1 user user1 |
| 91 | rcctl set fossil2 user user2 |
| 92 | rcctl set fossil1 flags 'server /home/user1/repo1.fossil --port 8881' |
| 93 | rcctl set fossil2 flags 'server /home/user2/repo2.fossil --port 8882' |
| 94 | rcctl start fossil1 fossil2 |
| 95 | </pre></blockquote> |
| 96 | |
| 97 | <h3>Copies</h3> |
| 98 | You may want to run fossil daemons that are too different to configure |
| 99 | just with [https://man.openbsd.org/rcctl.8|rcctl(8)]. |
| 100 | In particular, you can't change the "pexp" with rcctl. |
| 101 | |
| 102 | If you want to run fossil commands that are more different, |
| 103 | you may prefer to create separate files in /etc/rc.d. |
| 104 | Replace "ln -s" above with "cp" to accomplish this. |
| 105 | |
| 106 | <blockquote><pre> |
| 107 | cp /etc/rc.d/fossil /etc/rc.d/fossil-user1 |
| 108 | cp /etc/rc.d/fossil /etc/rc.d/fossil-user2 |
| 109 | </pre></blockquote> |
| 110 | |
| 111 | You can still use commands like "rcctl set fossil-user1 flags", but you |
| 112 | can also edit the "/etc/rc.d/fossil-user1" file. |
| 113 |
| --- www/server/openbsd/service.wiki | |
| +++ www/server/openbsd/service.wiki | |
| @@ -2,13 +2,14 @@ | |
| 2 | |
| 3 | OpenBSD provides [https://man.openbsd.org/rc.subr.8|rc.subr(8)], |
| 4 | a framework for writing [https://man.openbsd.org/rc.8|rc(8)] scripts. |
| 5 | |
| 6 | <h2>Creating the daemon</h2> |
| 7 | |
| 8 | Create the file /etc/rc.d/fossil with contents like the following. |
| 9 | |
| 10 | <pre> |
| 11 | #!/bin/ksh |
| 12 | daemon="/usr/local/bin/fossil" # fossil executable |
| 13 | daemon_user="_fossil" # user to run fossil as |
| 14 | daemon_flags="server /home/_fossil/example --repolist --port 8888" # fossil command |
| 15 | |
| @@ -15,56 +16,59 @@ | |
| 16 | . /etc/rc.d/rc.subr |
| 17 | # pexp="$daemon server .*" # See below. |
| 18 | rc_reload=NO # Unsupported by Fossil; 'rcctl reload fossil' kills the process. |
| 19 | rc_bg=YES # Run in the background, since fossil serve does not daemonize itself |
| 20 | rc_cmd $1 |
| 21 | </pre> |
| 22 | |
| 23 | <h3>pexp</h3> |
| 24 | |
| 25 | You may need to uncomment the "pexp=". rc.subr typically |
| 26 | finds the daemon process based by matching the process name and argument list. |
| 27 | Without the "pexp=" line, rc.subr would look for this exact command: |
| 28 | |
| 29 | <pre> |
| 30 | /usr/local/bin/fossil server /home/_fossil/example --repolist --port 8888 |
| 31 | </pre> |
| 32 | |
| 33 | Depending on the arguments and their order, fossil may rewrite the arguments |
| 34 | for display in the process listing ([https://man.openbsd.org/ps.1|ps(1)]), |
| 35 | so rc.subr may fail to find the process through the default match. The example |
| 36 | above does not get rewritten, but the same commands in a different order can |
| 37 | be rewritten. |
| 38 | For example, when I switch the order of the arguments in "daemon_flags", |
| 39 | |
| 40 | <pre> |
| 41 | /usr/local/bin/fossil server --repolist --port 8888 /home/_fossil/example |
| 42 | </pre> |
| 43 | |
| 44 | the process command is changed to this. |
| 45 | |
| 46 | <pre> |
| 47 | /usr/local/bin/fossil server /home/_fossil/example /home/_fossil/example 8888 /home/_fossil/example |
| 48 | </pre> |
| 49 | |
| 50 | The commented "pexp=" line instructs rc.subr to choose the process whose |
| 51 | command and arguments text starts with this: |
| 52 | |
| 53 | <pre> |
| 54 | /usr/local/bin/fossil server |
| 55 | </pre> |
| 56 | |
| 57 | <h2>Enabling the daemon</h2> |
| 58 | |
| 59 | Once you have created /etc/rc.d/fossil, run these commands. |
| 60 | |
| 61 | <pre> |
| 62 | rcctl enable fossil # add fossil to pkg_scripts in /etc/rc.conf.local |
| 63 | rcctl start fossil # start the daemon now |
| 64 | </pre> |
| 65 | |
| 66 | The daemon should now be running and set to start at boot. |
| 67 | |
| 68 | <h2>Multiple daemons</h2> |
| 69 | |
| 70 | You may want to serve multiple fossil instances with different options. |
| 71 | For example, |
| 72 | |
| 73 | * If different users own different repositories, you may want different users |
| 74 | to serve different repositories. |
| @@ -75,38 +79,40 @@ | |
| 79 | To run multiple fossil daemons, create multiple files in /etc/rc.d, and |
| 80 | enable each of them. Here are two approaches for creating |
| 81 | the files in /etc/rc.d: Symbolic links and copies. |
| 82 | |
| 83 | <h3>Symbolic links</h3> |
| 84 | |
| 85 | Suppose you want to run one fossil daemon as user "user1" on port 8881 |
| 86 | and another as user "user2" on port 8882. Create the files with |
| 87 | [https://man.openbsd.org/ln.1|ln(1)], and configure them to run different |
| 88 | fossil commands. |
| 89 | |
| 90 | <pre> |
| 91 | cd /etc/rc.d |
| 92 | ln -s fossil fossil1 |
| 93 | ln -s fossil fossil2 |
| 94 | rcctl enable fossil1 fossil2 |
| 95 | rcctl set fossil1 user user1 |
| 96 | rcctl set fossil2 user user2 |
| 97 | rcctl set fossil1 flags 'server /home/user1/repo1.fossil --port 8881' |
| 98 | rcctl set fossil2 flags 'server /home/user2/repo2.fossil --port 8882' |
| 99 | rcctl start fossil1 fossil2 |
| 100 | </pre> |
| 101 | |
| 102 | <h3>Copies</h3> |
| 103 | |
| 104 | You may want to run fossil daemons that are too different to configure |
| 105 | just with [https://man.openbsd.org/rcctl.8|rcctl(8)]. |
| 106 | In particular, you can't change the "pexp" with rcctl. |
| 107 | |
| 108 | If you want to run fossil commands that are more different, |
| 109 | you may prefer to create separate files in /etc/rc.d. |
| 110 | Replace "ln -s" above with "cp" to accomplish this. |
| 111 | |
| 112 | <pre> |
| 113 | cp /etc/rc.d/fossil /etc/rc.d/fossil-user1 |
| 114 | cp /etc/rc.d/fossil /etc/rc.d/fossil-user2 |
| 115 | </pre> |
| 116 | |
| 117 | You can still use commands like "rcctl set fossil-user1 flags", but you |
| 118 | can also edit the "/etc/rc.d/fossil-user1" file. |
| 119 |
+1
-1
| --- www/server/windows/iis.md | ||
| +++ www/server/windows/iis.md | ||
| @@ -32,11 +32,11 @@ | ||
| 32 | 32 | You will need to have the Fossil HTTP server running in the background, |
| 33 | 33 | serving some local repository, bound to localhost on a fixed |
| 34 | 34 | high-numbered TCP port. For the purposes of testing, simply start it by |
| 35 | 35 | hand in your command shell of choice: |
| 36 | 36 | |
| 37 | - fossil serve --port 9000 --localhost repo.fossil | |
| 37 | + fossil serve --port 9000 --localhost repo.fossil | |
| 38 | 38 | |
| 39 | 39 | That command assumes you’ve got `fossil.exe` in your `%PATH%` and you’re |
| 40 | 40 | in a directory holding `repo.fossil`. See [the platform-independent |
| 41 | 41 | instructions](../any/none.md) for further details. |
| 42 | 42 | |
| 43 | 43 |
| --- www/server/windows/iis.md | |
| +++ www/server/windows/iis.md | |
| @@ -32,11 +32,11 @@ | |
| 32 | You will need to have the Fossil HTTP server running in the background, |
| 33 | serving some local repository, bound to localhost on a fixed |
| 34 | high-numbered TCP port. For the purposes of testing, simply start it by |
| 35 | hand in your command shell of choice: |
| 36 | |
| 37 | fossil serve --port 9000 --localhost repo.fossil |
| 38 | |
| 39 | That command assumes you’ve got `fossil.exe` in your `%PATH%` and you’re |
| 40 | in a directory holding `repo.fossil`. See [the platform-independent |
| 41 | instructions](../any/none.md) for further details. |
| 42 | |
| 43 |
| --- www/server/windows/iis.md | |
| +++ www/server/windows/iis.md | |
| @@ -32,11 +32,11 @@ | |
| 32 | You will need to have the Fossil HTTP server running in the background, |
| 33 | serving some local repository, bound to localhost on a fixed |
| 34 | high-numbered TCP port. For the purposes of testing, simply start it by |
| 35 | hand in your command shell of choice: |
| 36 | |
| 37 | fossil serve --port 9000 --localhost repo.fossil |
| 38 | |
| 39 | That command assumes you’ve got `fossil.exe` in your `%PATH%` and you’re |
| 40 | in a directory holding `repo.fossil`. See [the platform-independent |
| 41 | instructions](../any/none.md) for further details. |
| 42 | |
| 43 |
+14
-14
| --- www/serverext.wiki | ||
| +++ www/serverext.wiki | ||
| @@ -31,13 +31,13 @@ | ||
| 31 | 31 | [./server/index.html|server setup]. |
| 32 | 32 | If the Fossil server is itself run as |
| 33 | 33 | [./server/any/cgi.md|CGI], then add a line to the |
| 34 | 34 | [./cgi.wiki#extroot|CGI script file] that says: |
| 35 | 35 | |
| 36 | -<blockquote><pre> | |
| 36 | +<pre> | |
| 37 | 37 | extroot: <i>DIRECTORY</i> |
| 38 | -</pre></blockquote> | |
| 38 | +</pre> | |
| 39 | 39 | |
| 40 | 40 | Or, if the Fossil server is being run using the |
| 41 | 41 | "[./server/any/none.md|fossil server]" or |
| 42 | 42 | "[./server/any/none.md|fossil ui]" or |
| 43 | 43 | "[./server/any/inetd.md|fossil http]" commands, then add an extra |
| @@ -44,13 +44,13 @@ | ||
| 44 | 44 | "--extroot <i>DIRECTORY</i>" option to that command. |
| 45 | 45 | |
| 46 | 46 | The <i>DIRECTORY</i> is the DOCUMENT_ROOT for the CGI. |
| 47 | 47 | Files in the DOCUMENT_ROOT are accessed via URLs like this: |
| 48 | 48 | |
| 49 | -<blockquote> | |
| 49 | +<pre> | |
| 50 | 50 | https://example-project.org/ext/<i>FILENAME</i> |
| 51 | -</blockquote> | |
| 51 | +</pre> | |
| 52 | 52 | |
| 53 | 53 | In other words, access files in DOCUMENT_ROOT by appending the filename |
| 54 | 54 | relative to DOCUMENT_ROOT to the [/help?cmd=/ext|/ext] |
| 55 | 55 | page of the Fossil server. |
| 56 | 56 | Files that are readable but not executable are returned as static |
| @@ -60,16 +60,16 @@ | ||
| 60 | 60 | |
| 61 | 61 | The source code repository for SQLite is a Fossil server that is run |
| 62 | 62 | as CGI. The URL for the source code repository is [https://sqlite.org/src]. |
| 63 | 63 | The CGI script looks like this: |
| 64 | 64 | |
| 65 | -<blockquote><verbatim> | |
| 65 | +<verbatim> | |
| 66 | 66 | #!/usr/bin/fossil |
| 67 | 67 | repository: /fossil/sqlite.fossil |
| 68 | 68 | errorlog: /logs/errors.txt |
| 69 | 69 | extroot: /sqlite-src-ext |
| 70 | -</verbatim></blockquote> | |
| 70 | +</verbatim> | |
| 71 | 71 | |
| 72 | 72 | The "extroot: /sqlite-src-ext" line tells Fossil that it should look for |
| 73 | 73 | extension CGIs in the /sqlite-src-ext directory. (All of this is happening |
| 74 | 74 | inside of a chroot jail, so putting the document root in a top-level |
| 75 | 75 | directory is a reasonable thing to do.) |
| @@ -101,16 +101,16 @@ | ||
| 101 | 101 | <h3>2.2 Example #2</h3> |
| 102 | 102 | |
| 103 | 103 | The [https://fossil-scm.org/home|Fossil self-hosting repository] is also |
| 104 | 104 | a CGI that looks like this: |
| 105 | 105 | |
| 106 | -<blockquote><verbatim> | |
| 106 | +<verbatim> | |
| 107 | 107 | #!/usr/bin/fossil |
| 108 | 108 | repository: /fossil/fossil.fossil |
| 109 | 109 | errorlog: /logs/errors.txt |
| 110 | 110 | extroot: /fossil-extroot |
| 111 | -</verbatim></blockquote> | |
| 111 | +</verbatim> | |
| 112 | 112 | |
| 113 | 113 | The extroot for this Fossil server is /fossil-extroot and in that directory |
| 114 | 114 | is an executable file named "fileup1" - another [https://wapp.tcl.tk|Wapp] |
| 115 | 115 | script. (The extension mechanism is not required to use Wapp. You can use |
| 116 | 116 | any kind of program you like. But the creator of SQLite and Fossil is fond |
| @@ -201,13 +201,13 @@ | ||
| 201 | 201 | the webpage. Any <script>...</script> elements within the |
| 202 | 202 | CGI output must include a nonce or else they will be suppressed by the |
| 203 | 203 | web browser. The FOSSIL_NONCE variable contains the value of that nonce. |
| 204 | 204 | So, in other words, to get javascript to work, it must be enclosed in: |
| 205 | 205 | |
| 206 | -<blockquote><verbatim> | |
| 206 | +<verbatim> | |
| 207 | 207 | <script nonce='$FOSSIL_NONCE'>...</script> |
| 208 | -</verbatim></blockquote> | |
| 208 | +</verbatim> | |
| 209 | 209 | |
| 210 | 210 | Except, of course, the $FOSSIL_NONCE is replaced by the value of the |
| 211 | 211 | FOSSIL_NONCE environment variable. |
| 212 | 212 | |
| 213 | 213 | <h3>3.1 Input Content</h3> |
| @@ -223,14 +223,14 @@ | ||
| 223 | 223 | few lines of output are parameters intended for the web server that invoked |
| 224 | 224 | the CGI. These are followed by a blank line and then the content. |
| 225 | 225 | |
| 226 | 226 | Typical parameter output looks like this: |
| 227 | 227 | |
| 228 | -<blockquote><verbatim> | |
| 228 | +<verbatim> | |
| 229 | 229 | Status: 200 OK |
| 230 | 230 | Content-Type: text/html |
| 231 | -</verbatim></blockquote> | |
| 231 | +</verbatim> | |
| 232 | 232 | |
| 233 | 233 | CGI programs can return any content type they want - they are not restricted |
| 234 | 234 | to text replies. It is OK for a CGI program to return (for example) |
| 235 | 235 | image/png. |
| 236 | 236 | |
| @@ -244,15 +244,15 @@ | ||
| 244 | 244 | [/md_rules|Markdown] into HTML, adding its |
| 245 | 245 | own header and footer text according to the repository skin. Content |
| 246 | 246 | of type "text/html" is normally passed straight through |
| 247 | 247 | unchanged. However, if the text/html content is of the form: |
| 248 | 248 | |
| 249 | -<blockquote><verbatim> | |
| 249 | +<verbatim> | |
| 250 | 250 | <div class='fossil-doc' data-title='DOCUMENT TITLE'> |
| 251 | 251 | ... HTML content there ... |
| 252 | 252 | </div> |
| 253 | -</verbatim></blockquote> | |
| 253 | +</verbatim> | |
| 254 | 254 | |
| 255 | 255 | In other words, if the outer-most markup of the HTML is a <div> |
| 256 | 256 | element with a single class of "fossil-doc", |
| 257 | 257 | then Fossil will adds its own header and footer to the HTML. The |
| 258 | 258 | page title contained in the added header will be extracted from the |
| 259 | 259 |
| --- www/serverext.wiki | |
| +++ www/serverext.wiki | |
| @@ -31,13 +31,13 @@ | |
| 31 | [./server/index.html|server setup]. |
| 32 | If the Fossil server is itself run as |
| 33 | [./server/any/cgi.md|CGI], then add a line to the |
| 34 | [./cgi.wiki#extroot|CGI script file] that says: |
| 35 | |
| 36 | <blockquote><pre> |
| 37 | extroot: <i>DIRECTORY</i> |
| 38 | </pre></blockquote> |
| 39 | |
| 40 | Or, if the Fossil server is being run using the |
| 41 | "[./server/any/none.md|fossil server]" or |
| 42 | "[./server/any/none.md|fossil ui]" or |
| 43 | "[./server/any/inetd.md|fossil http]" commands, then add an extra |
| @@ -44,13 +44,13 @@ | |
| 44 | "--extroot <i>DIRECTORY</i>" option to that command. |
| 45 | |
| 46 | The <i>DIRECTORY</i> is the DOCUMENT_ROOT for the CGI. |
| 47 | Files in the DOCUMENT_ROOT are accessed via URLs like this: |
| 48 | |
| 49 | <blockquote> |
| 50 | https://example-project.org/ext/<i>FILENAME</i> |
| 51 | </blockquote> |
| 52 | |
| 53 | In other words, access files in DOCUMENT_ROOT by appending the filename |
| 54 | relative to DOCUMENT_ROOT to the [/help?cmd=/ext|/ext] |
| 55 | page of the Fossil server. |
| 56 | Files that are readable but not executable are returned as static |
| @@ -60,16 +60,16 @@ | |
| 60 | |
| 61 | The source code repository for SQLite is a Fossil server that is run |
| 62 | as CGI. The URL for the source code repository is [https://sqlite.org/src]. |
| 63 | The CGI script looks like this: |
| 64 | |
| 65 | <blockquote><verbatim> |
| 66 | #!/usr/bin/fossil |
| 67 | repository: /fossil/sqlite.fossil |
| 68 | errorlog: /logs/errors.txt |
| 69 | extroot: /sqlite-src-ext |
| 70 | </verbatim></blockquote> |
| 71 | |
| 72 | The "extroot: /sqlite-src-ext" line tells Fossil that it should look for |
| 73 | extension CGIs in the /sqlite-src-ext directory. (All of this is happening |
| 74 | inside of a chroot jail, so putting the document root in a top-level |
| 75 | directory is a reasonable thing to do.) |
| @@ -101,16 +101,16 @@ | |
| 101 | <h3>2.2 Example #2</h3> |
| 102 | |
| 103 | The [https://fossil-scm.org/home|Fossil self-hosting repository] is also |
| 104 | a CGI that looks like this: |
| 105 | |
| 106 | <blockquote><verbatim> |
| 107 | #!/usr/bin/fossil |
| 108 | repository: /fossil/fossil.fossil |
| 109 | errorlog: /logs/errors.txt |
| 110 | extroot: /fossil-extroot |
| 111 | </verbatim></blockquote> |
| 112 | |
| 113 | The extroot for this Fossil server is /fossil-extroot and in that directory |
| 114 | is an executable file named "fileup1" - another [https://wapp.tcl.tk|Wapp] |
| 115 | script. (The extension mechanism is not required to use Wapp. You can use |
| 116 | any kind of program you like. But the creator of SQLite and Fossil is fond |
| @@ -201,13 +201,13 @@ | |
| 201 | the webpage. Any <script>...</script> elements within the |
| 202 | CGI output must include a nonce or else they will be suppressed by the |
| 203 | web browser. The FOSSIL_NONCE variable contains the value of that nonce. |
| 204 | So, in other words, to get javascript to work, it must be enclosed in: |
| 205 | |
| 206 | <blockquote><verbatim> |
| 207 | <script nonce='$FOSSIL_NONCE'>...</script> |
| 208 | </verbatim></blockquote> |
| 209 | |
| 210 | Except, of course, the $FOSSIL_NONCE is replaced by the value of the |
| 211 | FOSSIL_NONCE environment variable. |
| 212 | |
| 213 | <h3>3.1 Input Content</h3> |
| @@ -223,14 +223,14 @@ | |
| 223 | few lines of output are parameters intended for the web server that invoked |
| 224 | the CGI. These are followed by a blank line and then the content. |
| 225 | |
| 226 | Typical parameter output looks like this: |
| 227 | |
| 228 | <blockquote><verbatim> |
| 229 | Status: 200 OK |
| 230 | Content-Type: text/html |
| 231 | </verbatim></blockquote> |
| 232 | |
| 233 | CGI programs can return any content type they want - they are not restricted |
| 234 | to text replies. It is OK for a CGI program to return (for example) |
| 235 | image/png. |
| 236 | |
| @@ -244,15 +244,15 @@ | |
| 244 | [/md_rules|Markdown] into HTML, adding its |
| 245 | own header and footer text according to the repository skin. Content |
| 246 | of type "text/html" is normally passed straight through |
| 247 | unchanged. However, if the text/html content is of the form: |
| 248 | |
| 249 | <blockquote><verbatim> |
| 250 | <div class='fossil-doc' data-title='DOCUMENT TITLE'> |
| 251 | ... HTML content there ... |
| 252 | </div> |
| 253 | </verbatim></blockquote> |
| 254 | |
| 255 | In other words, if the outer-most markup of the HTML is a <div> |
| 256 | element with a single class of "fossil-doc", |
| 257 | then Fossil will adds its own header and footer to the HTML. The |
| 258 | page title contained in the added header will be extracted from the |
| 259 |
| --- www/serverext.wiki | |
| +++ www/serverext.wiki | |
| @@ -31,13 +31,13 @@ | |
| 31 | [./server/index.html|server setup]. |
| 32 | If the Fossil server is itself run as |
| 33 | [./server/any/cgi.md|CGI], then add a line to the |
| 34 | [./cgi.wiki#extroot|CGI script file] that says: |
| 35 | |
| 36 | <pre> |
| 37 | extroot: <i>DIRECTORY</i> |
| 38 | </pre> |
| 39 | |
| 40 | Or, if the Fossil server is being run using the |
| 41 | "[./server/any/none.md|fossil server]" or |
| 42 | "[./server/any/none.md|fossil ui]" or |
| 43 | "[./server/any/inetd.md|fossil http]" commands, then add an extra |
| @@ -44,13 +44,13 @@ | |
| 44 | "--extroot <i>DIRECTORY</i>" option to that command. |
| 45 | |
| 46 | The <i>DIRECTORY</i> is the DOCUMENT_ROOT for the CGI. |
| 47 | Files in the DOCUMENT_ROOT are accessed via URLs like this: |
| 48 | |
| 49 | <pre> |
| 50 | https://example-project.org/ext/<i>FILENAME</i> |
| 51 | </pre> |
| 52 | |
| 53 | In other words, access files in DOCUMENT_ROOT by appending the filename |
| 54 | relative to DOCUMENT_ROOT to the [/help?cmd=/ext|/ext] |
| 55 | page of the Fossil server. |
| 56 | Files that are readable but not executable are returned as static |
| @@ -60,16 +60,16 @@ | |
| 60 | |
| 61 | The source code repository for SQLite is a Fossil server that is run |
| 62 | as CGI. The URL for the source code repository is [https://sqlite.org/src]. |
| 63 | The CGI script looks like this: |
| 64 | |
| 65 | <verbatim> |
| 66 | #!/usr/bin/fossil |
| 67 | repository: /fossil/sqlite.fossil |
| 68 | errorlog: /logs/errors.txt |
| 69 | extroot: /sqlite-src-ext |
| 70 | </verbatim> |
| 71 | |
| 72 | The "extroot: /sqlite-src-ext" line tells Fossil that it should look for |
| 73 | extension CGIs in the /sqlite-src-ext directory. (All of this is happening |
| 74 | inside of a chroot jail, so putting the document root in a top-level |
| 75 | directory is a reasonable thing to do.) |
| @@ -101,16 +101,16 @@ | |
| 101 | <h3>2.2 Example #2</h3> |
| 102 | |
| 103 | The [https://fossil-scm.org/home|Fossil self-hosting repository] is also |
| 104 | a CGI that looks like this: |
| 105 | |
| 106 | <verbatim> |
| 107 | #!/usr/bin/fossil |
| 108 | repository: /fossil/fossil.fossil |
| 109 | errorlog: /logs/errors.txt |
| 110 | extroot: /fossil-extroot |
| 111 | </verbatim> |
| 112 | |
| 113 | The extroot for this Fossil server is /fossil-extroot and in that directory |
| 114 | is an executable file named "fileup1" - another [https://wapp.tcl.tk|Wapp] |
| 115 | script. (The extension mechanism is not required to use Wapp. You can use |
| 116 | any kind of program you like. But the creator of SQLite and Fossil is fond |
| @@ -201,13 +201,13 @@ | |
| 201 | the webpage. Any <script>...</script> elements within the |
| 202 | CGI output must include a nonce or else they will be suppressed by the |
| 203 | web browser. The FOSSIL_NONCE variable contains the value of that nonce. |
| 204 | So, in other words, to get javascript to work, it must be enclosed in: |
| 205 | |
| 206 | <verbatim> |
| 207 | <script nonce='$FOSSIL_NONCE'>...</script> |
| 208 | </verbatim> |
| 209 | |
| 210 | Except, of course, the $FOSSIL_NONCE is replaced by the value of the |
| 211 | FOSSIL_NONCE environment variable. |
| 212 | |
| 213 | <h3>3.1 Input Content</h3> |
| @@ -223,14 +223,14 @@ | |
| 223 | few lines of output are parameters intended for the web server that invoked |
| 224 | the CGI. These are followed by a blank line and then the content. |
| 225 | |
| 226 | Typical parameter output looks like this: |
| 227 | |
| 228 | <verbatim> |
| 229 | Status: 200 OK |
| 230 | Content-Type: text/html |
| 231 | </verbatim> |
| 232 | |
| 233 | CGI programs can return any content type they want - they are not restricted |
| 234 | to text replies. It is OK for a CGI program to return (for example) |
| 235 | image/png. |
| 236 | |
| @@ -244,15 +244,15 @@ | |
| 244 | [/md_rules|Markdown] into HTML, adding its |
| 245 | own header and footer text according to the repository skin. Content |
| 246 | of type "text/html" is normally passed straight through |
| 247 | unchanged. However, if the text/html content is of the form: |
| 248 | |
| 249 | <verbatim> |
| 250 | <div class='fossil-doc' data-title='DOCUMENT TITLE'> |
| 251 | ... HTML content there ... |
| 252 | </div> |
| 253 | </verbatim> |
| 254 | |
| 255 | In other words, if the outer-most markup of the HTML is a <div> |
| 256 | element with a single class of "fossil-doc", |
| 257 | then Fossil will adds its own header and footer to the HTML. The |
| 258 | page title contained in the added header will be extracted from the |
| 259 |
+1
-2
| --- www/stats.wiki | ||
| +++ www/stats.wiki | ||
| @@ -1,7 +1,6 @@ | ||
| 1 | 1 | <title>Fossil Performance</title> |
| 2 | -<h1 align="center">Performance Statistics</h1> | |
| 3 | 2 | |
| 4 | 3 | The questions will inevitably arise: How does Fossil perform? |
| 5 | 4 | Does it use a lot of disk space or bandwidth? Is it scalable? |
| 6 | 5 | |
| 7 | 6 | In an attempt to answers these questions, this report looks at several |
| @@ -8,11 +7,11 @@ | ||
| 8 | 7 | projects that use fossil for configuration management and examines how |
| 9 | 8 | well they are working. The following table is a summary of the results. |
| 10 | 9 | (Last updated on 2018-06-04.) |
| 11 | 10 | Explanation and analysis follows the table. |
| 12 | 11 | |
| 13 | -<table border=1> | |
| 12 | +<table> | |
| 14 | 13 | <tr> |
| 15 | 14 | <th>Project</th> |
| 16 | 15 | <th>Number Of Artifacts</th> |
| 17 | 16 | <th>Number Of Check-ins</th> |
| 18 | 17 | <th>Project Duration<br>(as of 2018-06-04)</th> |
| 19 | 18 |
| --- www/stats.wiki | |
| +++ www/stats.wiki | |
| @@ -1,7 +1,6 @@ | |
| 1 | <title>Fossil Performance</title> |
| 2 | <h1 align="center">Performance Statistics</h1> |
| 3 | |
| 4 | The questions will inevitably arise: How does Fossil perform? |
| 5 | Does it use a lot of disk space or bandwidth? Is it scalable? |
| 6 | |
| 7 | In an attempt to answers these questions, this report looks at several |
| @@ -8,11 +7,11 @@ | |
| 8 | projects that use fossil for configuration management and examines how |
| 9 | well they are working. The following table is a summary of the results. |
| 10 | (Last updated on 2018-06-04.) |
| 11 | Explanation and analysis follows the table. |
| 12 | |
| 13 | <table border=1> |
| 14 | <tr> |
| 15 | <th>Project</th> |
| 16 | <th>Number Of Artifacts</th> |
| 17 | <th>Number Of Check-ins</th> |
| 18 | <th>Project Duration<br>(as of 2018-06-04)</th> |
| 19 |
| --- www/stats.wiki | |
| +++ www/stats.wiki | |
| @@ -1,7 +1,6 @@ | |
| 1 | <title>Fossil Performance</title> |
| 2 | |
| 3 | The questions will inevitably arise: How does Fossil perform? |
| 4 | Does it use a lot of disk space or bandwidth? Is it scalable? |
| 5 | |
| 6 | In an attempt to answers these questions, this report looks at several |
| @@ -8,11 +7,11 @@ | |
| 7 | projects that use fossil for configuration management and examines how |
| 8 | well they are working. The following table is a summary of the results. |
| 9 | (Last updated on 2018-06-04.) |
| 10 | Explanation and analysis follows the table. |
| 11 | |
| 12 | <table> |
| 13 | <tr> |
| 14 | <th>Project</th> |
| 15 | <th>Number Of Artifacts</th> |
| 16 | <th>Number Of Check-ins</th> |
| 17 | <th>Project Duration<br>(as of 2018-06-04)</th> |
| 18 |
+47
-57
| --- www/sync.wiki | ||
| +++ www/sync.wiki | ||
| @@ -130,34 +130,30 @@ | ||
| 130 | 130 | |
| 131 | 131 | The client modifies the URL by appending the method name "<b>/xfer</b>" |
| 132 | 132 | to the end. For example, if the URL specified on the client command |
| 133 | 133 | line is |
| 134 | 134 | |
| 135 | -<blockquote> | |
| 136 | -https://fossil-scm.org/fossil | |
| 137 | -</blockquote> | |
| 135 | +<pre>https://fossil-scm.org/fossil</pre> | |
| 138 | 136 | |
| 139 | 137 | Then the URL that is really used to do the synchronization will |
| 140 | 138 | be: |
| 141 | 139 | |
| 142 | -<blockquote> | |
| 143 | -https://fossil-scm.org/fossil/xfer | |
| 144 | -</blockquote> | |
| 140 | +<pre>https://fossil-scm.org/fossil/xfer</pre> | |
| 145 | 141 | |
| 146 | 142 | <h3>2.2 HTTP Request Format</h3> |
| 147 | 143 | |
| 148 | 144 | The client always sends a POST request to the server. The |
| 149 | 145 | general format of the POST request is as follows: |
| 150 | 146 | |
| 151 | -<blockquote><pre> | |
| 147 | +<pre> | |
| 152 | 148 | POST /fossil/xfer HTTP/1.0 |
| 153 | 149 | Host: fossil-scm.hwaci.com:80 |
| 154 | 150 | Content-Type: application/x-fossil |
| 155 | 151 | Content-Length: 4216 |
| 152 | +</pre> | |
| 156 | 153 | |
| 157 | -<i>content...</i> | |
| 158 | -</pre></blockquote> | |
| 154 | +<i><pre>content...</pre></i> | |
| 159 | 155 | |
| 160 | 156 | In the example above, the pathname given after the POST keyword |
| 161 | 157 | on the first line is a copy of the URL pathname. The Host: parameter |
| 162 | 158 | is also taken from the URL. The content type is always either |
| 163 | 159 | "application/x-fossil" or "application/x-fossil-debug". The "x-fossil" |
| @@ -165,20 +161,20 @@ | ||
| 165 | 161 | content is compressed using zlib whereas "x-fossil-debug" is sent |
| 166 | 162 | uncompressed. |
| 167 | 163 | |
| 168 | 164 | A typical reply from the server might look something like this: |
| 169 | 165 | |
| 170 | -<blockquote><pre> | |
| 166 | +<pre> | |
| 171 | 167 | HTTP/1.0 200 OK |
| 172 | 168 | Date: Mon, 10 Sep 2007 12:21:01 GMT |
| 173 | 169 | Connection: close |
| 174 | 170 | Cache-control: private |
| 175 | 171 | Content-Type: application/x-fossil; charset=US-ASCII |
| 176 | 172 | Content-Length: 265 |
| 173 | +</pre> | |
| 177 | 174 | |
| 178 | -<i>content...</i> | |
| 179 | -</pre></blockquote> | |
| 175 | +<i><pre>content...</pre></i> | |
| 180 | 176 | |
| 181 | 177 | The content type of the reply is always the same as the content type |
| 182 | 178 | of the request. |
| 183 | 179 | |
| 184 | 180 | <h2>3.0 Fossil Synchronization Content</h2> |
| @@ -202,13 +198,11 @@ | ||
| 202 | 198 | <h3>3.2 Login Cards</h3> |
| 203 | 199 | |
| 204 | 200 | Every message from client to server begins with one or more login |
| 205 | 201 | cards. Each login card has the following format: |
| 206 | 202 | |
| 207 | -<blockquote> | |
| 208 | -<b>login</b> <i>userid nonce signature</i> | |
| 209 | -</blockquote> | |
| 203 | +<pre><b>login</b> <i>userid nonce signature</i></pre> | |
| 210 | 204 | |
| 211 | 205 | The userid is the name of the user that is requesting service |
| 212 | 206 | from the server. The nonce is the SHA1 hash of the remainder of |
| 213 | 207 | the message - all text that follows the newline character that |
| 214 | 208 | terminates the login card. The signature is the SHA1 hash of |
| @@ -241,14 +235,14 @@ | ||
| 241 | 235 | cards. File cards come in two different formats depending |
| 242 | 236 | on whether the artifact is sent directly or as a |
| 243 | 237 | [./delta_format.wiki|delta] from some |
| 244 | 238 | other artifact. |
| 245 | 239 | |
| 246 | -<blockquote> | |
| 247 | -<b>file</b> <i>artifact-id size</i> <b>\n</b> <i>content</i><br> | |
| 240 | +<pre> | |
| 241 | +<b>file</b> <i>artifact-id size</i> <b>\n</b> <i>content</i> | |
| 248 | 242 | <b>file</b> <i>artifact-id delta-artifact-id size</i> <b>\n</b> <i>content</i> |
| 249 | -</blockquote> | |
| 243 | +</pre> | |
| 250 | 244 | |
| 251 | 245 | File cards are followed by in-line "payload" data. |
| 252 | 246 | The content of the artifact |
| 253 | 247 | or the artifact delta is the first <i>size</i> bytes of the |
| 254 | 248 | x-fossil content that immediately follow the newline that |
| @@ -282,14 +276,14 @@ | ||
| 282 | 276 | in-line "payload" data characteristics and also the same treatment of |
| 283 | 277 | direct content or delta content. Cfile cards come in two different formats |
| 284 | 278 | depending on whether the artifact is sent directly or as a delta from |
| 285 | 279 | some other artifact. |
| 286 | 280 | |
| 287 | -<blockquote> | |
| 288 | -<b>cfile</b> <i>artifact-id usize csize</i> <b>\n</b> <i>content</i><br> | |
| 289 | -<b>cfile</b> <i>artifact-id delta-artifact-id usize csize</i> <b>\n</b> <i>content</i><br> | |
| 290 | -</blockquote> | |
| 281 | +<pre> | |
| 282 | +<b>cfile</b> <i>artifact-id usize csize</i> <b>\n</b> <i>content</i> | |
| 283 | +<b>cfile</b> <i>artifact-id delta-artifact-id usize csize</i> <b>\n</b> <i>content</i> | |
| 284 | +</pre> | |
| 291 | 285 | |
| 292 | 286 | The first argument of the cfile card is the ID of the artifact that |
| 293 | 287 | is being transferred. The artifact ID is the lower-case hexadecimal |
| 294 | 288 | representation of the name hash for the artifact. The second argument of |
| 295 | 289 | the cfile card is the original size in bytes of the artifact. The last |
| @@ -311,25 +305,21 @@ | ||
| 311 | 305 | the [/help?cmd=sync|fossil sync] command includes the "--private" option. |
| 312 | 306 | |
| 313 | 307 | |
| 314 | 308 | Private content is marked by a "private" card: |
| 315 | 309 | |
| 316 | -<blockquote> | |
| 317 | -<b>private</b> | |
| 318 | -</blockquote> | |
| 310 | +<pre><b>private</b></pre> | |
| 319 | 311 | |
| 320 | 312 | The private card has no arguments and must directly precede a |
| 321 | 313 | file card that contains the private content. |
| 322 | 314 | |
| 323 | 315 | <h4>3.3.4 Unversioned File Cards</h4> |
| 324 | 316 | |
| 325 | 317 | Unversioned content is sent in both directions (client to server and |
| 326 | 318 | server to client) using "uvfile" cards in the following format: |
| 327 | 319 | |
| 328 | -<blockquote> | |
| 329 | -<b>uvfile</b> <i>name mtime hash size flags</i> <b>\n</b> <i>content</i> | |
| 330 | -</blockquote> | |
| 320 | +<pre><b>uvfile</b> <i>name mtime hash size flags</i> <b>\n</b> <i>content</i></pre> | |
| 331 | 321 | |
| 332 | 322 | The <i>name</i> field is the name of the unversioned file. The |
| 333 | 323 | <i>mtime</i> is the last modification time of the file in seconds |
| 334 | 324 | since 1970. The <i>hash</i> field is the hash of the content |
| 335 | 325 | for the unversioned file, or "<b>-</b>" for deleted content. |
| @@ -360,14 +350,14 @@ | ||
| 360 | 350 | the push and pull cards. The push card tells the server that |
| 361 | 351 | the client is pushing content. The pull card tells the server |
| 362 | 352 | that the client wants to pull content. In the event of a sync, |
| 363 | 353 | both cards are sent. The format is as follows: |
| 364 | 354 | |
| 365 | -<blockquote> | |
| 366 | -<b>push</b> <i>servercode projectcode</i><br> | |
| 355 | +<pre> | |
| 356 | +<b>push</b> <i>servercode projectcode</i> | |
| 367 | 357 | <b>pull</b> <i>servercode projectcode</i> |
| 368 | -</blockquote> | |
| 358 | +</pre> | |
| 369 | 359 | |
| 370 | 360 | The <i>servercode</i> argument is the repository ID for the |
| 371 | 361 | client. The <i>projectcode</i> is the identifier |
| 372 | 362 | of the software project that the client repository contains. |
| 373 | 363 | The projectcode for the client and server must match in order |
| @@ -385,14 +375,14 @@ | ||
| 385 | 375 | client to server in order to tell the server that the client |
| 386 | 376 | wants to pull content. The clone card comes in two formats. Older |
| 387 | 377 | clients use the no-argument format and newer clients use the |
| 388 | 378 | two-argument format. |
| 389 | 379 | |
| 390 | -<blockquote> | |
| 391 | -<b>clone</b><br> | |
| 380 | +<pre> | |
| 381 | +<b>clone</b> | |
| 392 | 382 | <b>clone</b> <i>protocol-version sequence-number</i> |
| 393 | -</blockquote> | |
| 383 | +</pre> | |
| 394 | 384 | |
| 395 | 385 | <h4>3.5.1 Protocol 3</h4> |
| 396 | 386 | |
| 397 | 387 | The latest clients send a two-argument clone message with a |
| 398 | 388 | protocol version of "3". (Future versions of Fossil might use larger |
| @@ -409,13 +399,13 @@ | ||
| 409 | 399 | cards for some number of artifacts up to the maximum message size. |
| 410 | 400 | |
| 411 | 401 | The server will also send a single "clone_seqno" card to the client |
| 412 | 402 | so that the client can know where the server left off. |
| 413 | 403 | |
| 414 | -<blockquote> | |
| 404 | +<pre> | |
| 415 | 405 | <b>clone_seqno</b> <i>sequence-number</i> |
| 416 | -</blockquote> | |
| 406 | +</pre> | |
| 417 | 407 | |
| 418 | 408 | The clone message in subsequent HTTP requests for the same clone |
| 419 | 409 | operation will use the sequence-number from the |
| 420 | 410 | clone_seqno of the previous reply. |
| 421 | 411 | |
| @@ -440,13 +430,13 @@ | ||
| 440 | 430 | |
| 441 | 431 | An igot card can be sent from either client to server or from |
| 442 | 432 | server to client in order to indicate that the sender holds a copy |
| 443 | 433 | of a particular artifact. The format is: |
| 444 | 434 | |
| 445 | -<blockquote> | |
| 435 | +<pre> | |
| 446 | 436 | <b>igot</b> <i>artifact-id</i> ?<i>flag</i>? |
| 447 | -</blockquote> | |
| 437 | +</pre> | |
| 448 | 438 | |
| 449 | 439 | The first argument of the igot card is the ID of the artifact that |
| 450 | 440 | the sender possesses. |
| 451 | 441 | The receiver of an igot card will typically check to see if |
| 452 | 442 | it also holds the same artifact and if not it will request the artifact |
| @@ -463,13 +453,13 @@ | ||
| 463 | 453 | |
| 464 | 454 | Zero or more "uvigot" cards are sent from server to client when |
| 465 | 455 | synchronizing unversioned content. The format of a uvigot card is |
| 466 | 456 | as follows: |
| 467 | 457 | |
| 468 | -<blockquote> | |
| 458 | +<pre> | |
| 469 | 459 | <b>uvigot</b> <i>name mtime hash size</i> |
| 470 | -</blockquote> | |
| 460 | +</pre> | |
| 471 | 461 | |
| 472 | 462 | The <i>name</i> argument is the name of an unversioned file. |
| 473 | 463 | The <i>mtime</i> is the last modification time of the unversioned file |
| 474 | 464 | in seconds since 1970. |
| 475 | 465 | The <i>hash</i> is the SHA1 or SHA3-256 hash of the unversioned file |
| @@ -495,13 +485,13 @@ | ||
| 495 | 485 | |
| 496 | 486 | A gimme card is sent from either client to server or from server |
| 497 | 487 | to client. The gimme card asks the receiver to send a particular |
| 498 | 488 | artifact back to the sender. The format of a gimme card is this: |
| 499 | 489 | |
| 500 | -<blockquote> | |
| 490 | +<pre> | |
| 501 | 491 | <b>gimme</b> <i>artifact-id</i> |
| 502 | -</blockquote> | |
| 492 | +</pre> | |
| 503 | 493 | |
| 504 | 494 | The argument to the gimme card is the ID of the artifact that |
| 505 | 495 | the sender wants. The receiver will typically respond to a |
| 506 | 496 | gimme card by sending a file card in its reply or in the next |
| 507 | 497 | message. |
| @@ -515,13 +505,13 @@ | ||
| 515 | 505 | Sync synchronizing unversioned content, the client may send "uvgimme" |
| 516 | 506 | cards to the server. A uvgimme card requests that the server send |
| 517 | 507 | unversioned content to the client. The format of a uvgimme card is |
| 518 | 508 | as follows: |
| 519 | 509 | |
| 520 | -<blockquote> | |
| 510 | +<pre> | |
| 521 | 511 | <b>uvgimme</b> <i>name</i> |
| 522 | -</blockquote> | |
| 512 | +</pre> | |
| 523 | 513 | |
| 524 | 514 | The <i>name</i> is the name of the unversioned file found on the |
| 525 | 515 | server that the client would like to have. When a server sees a |
| 526 | 516 | uvgimme card, it normally responses with a uvfile card, though it might |
| 527 | 517 | also send another uvigot card if the HTTP reply is already oversized. |
| @@ -532,13 +522,13 @@ | ||
| 532 | 522 | of state information on a client. The server sends a cookie to the |
| 533 | 523 | client. The client sends the same cookie back to the server on |
| 534 | 524 | its next request. The cookie card has a single argument which |
| 535 | 525 | is its payload. |
| 536 | 526 | |
| 537 | -<blockquote> | |
| 527 | +<pre> | |
| 538 | 528 | <b>cookie</b> <i>payload</i> |
| 539 | -</blockquote> | |
| 529 | +</pre> | |
| 540 | 530 | |
| 541 | 531 | The client is not required to return the cookie to the server on |
| 542 | 532 | its next request. Or the client might send a cookie from a different |
| 543 | 533 | server on the next request. So the server must not depend on the |
| 544 | 534 | cookie and the server must structure the cookie payload in such |
| @@ -558,13 +548,13 @@ | ||
| 558 | 548 | data elements. |
| 559 | 549 | |
| 560 | 550 | The reqconfig card is normally sent in response to the |
| 561 | 551 | "fossil configuration pull" command. The format is as follows: |
| 562 | 552 | |
| 563 | -<blockquote> | |
| 553 | +<pre> | |
| 564 | 554 | <b>reqconfig</b> <i>configuration-name</i> |
| 565 | -</blockquote> | |
| 555 | +</pre> | |
| 566 | 556 | |
| 567 | 557 | As of 2018-06-04, the configuration-name must be one of the |
| 568 | 558 | following values: |
| 569 | 559 | |
| 570 | 560 | <table border=0 align="center"> |
| @@ -603,11 +593,11 @@ | ||
| 603 | 593 | <li> crlf-glob |
| 604 | 594 | <ul></td><td valign="top"><ul> |
| 605 | 595 | <li> crnl-glob |
| 606 | 596 | <li> encoding-glob |
| 607 | 597 | <li> empty-dirs |
| 608 | -<li> <s>allow-symlinks</s> (removed 2020-08, version 2.12.1) | |
| 598 | +<li> <s title="removed 2020-08, version 2.12.1">allow-symlinks</s> | |
| 609 | 599 | <li> dotfiles |
| 610 | 600 | <li> parent-project-code |
| 611 | 601 | <li> parent-projet-name |
| 612 | 602 | <li> hash-policy |
| 613 | 603 | <li> mv-rm-files |
| @@ -660,13 +650,13 @@ | ||
| 660 | 650 | A "config" card is used to send configuration information from client |
| 661 | 651 | to server (in response to a "fossil configuration push" command) or |
| 662 | 652 | from server to client (in response to a "fossil configuration pull" or |
| 663 | 653 | "fossil clone" command). The format is as follows: |
| 664 | 654 | |
| 665 | -<blockquote> | |
| 655 | +<pre> | |
| 666 | 656 | <b>config</b> <i>configuration-name size</i> <b>\n</b> <i>content</i> |
| 667 | -</blockquote> | |
| 657 | +</pre> | |
| 668 | 658 | |
| 669 | 659 | The server will only accept a config card if the user has |
| 670 | 660 | "Admin" privilege. A client will only accept a config card if |
| 671 | 661 | it had sent a corresponding reqconfig card in its request. |
| 672 | 662 | |
| @@ -676,13 +666,13 @@ | ||
| 676 | 666 | <h3>3.11 Pragma Cards</h3> |
| 677 | 667 | |
| 678 | 668 | The client may try to influence the behavior of the server by |
| 679 | 669 | issuing a pragma card: |
| 680 | 670 | |
| 681 | -<blockquote> | |
| 671 | +<pre> | |
| 682 | 672 | <b>pragma</i> <i>name value...</i> |
| 683 | -</blockquote> | |
| 673 | +</pre> | |
| 684 | 674 | |
| 685 | 675 | The "pragma" card has at least one argument which is the pragma name. |
| 686 | 676 | The pragma name defines what the pragma does. |
| 687 | 677 | A pragma might have zero or more "value" arguments |
| 688 | 678 | depending on the pragma name. |
| @@ -775,13 +765,13 @@ | ||
| 775 | 765 | If the server discovers anything wrong with a request, it generates |
| 776 | 766 | an error card in its reply. When the client sees the error card, |
| 777 | 767 | it displays an error message to the user and aborts the sync |
| 778 | 768 | operation. An error card looks like this: |
| 779 | 769 | |
| 780 | -<blockquote> | |
| 770 | +<pre> | |
| 781 | 771 | <b>error</b> <i>error-message</i> |
| 782 | -</blockquote> | |
| 772 | +</pre> | |
| 783 | 773 | |
| 784 | 774 | The error message is English text that is encoded in order to |
| 785 | 775 | be a single token. |
| 786 | 776 | A space (ASCII 0x20) is represented as "\s" (ASCII 0x5C, 0x73). A |
| 787 | 777 | newline (ASCII 0x0a) is "\n" (ASCII 0x6C, x6E). A backslash |
| @@ -791,13 +781,13 @@ | ||
| 791 | 781 | the error message. |
| 792 | 782 | |
| 793 | 783 | The server can also send a message card that also prints a |
| 794 | 784 | message on the client console, but which is not an error: |
| 795 | 785 | |
| 796 | -<blockquote> | |
| 786 | +<pre> | |
| 797 | 787 | <b>message</b> <i>message-text</i> |
| 798 | -</blockquote> | |
| 788 | +</pre> | |
| 799 | 789 | |
| 800 | 790 | The message-text uses the same format as an error message. |
| 801 | 791 | |
| 802 | 792 | <h3>3.14 Unknown Cards</h3> |
| 803 | 793 | |
| 804 | 794 |
| --- www/sync.wiki | |
| +++ www/sync.wiki | |
| @@ -130,34 +130,30 @@ | |
| 130 | |
| 131 | The client modifies the URL by appending the method name "<b>/xfer</b>" |
| 132 | to the end. For example, if the URL specified on the client command |
| 133 | line is |
| 134 | |
| 135 | <blockquote> |
| 136 | https://fossil-scm.org/fossil |
| 137 | </blockquote> |
| 138 | |
| 139 | Then the URL that is really used to do the synchronization will |
| 140 | be: |
| 141 | |
| 142 | <blockquote> |
| 143 | https://fossil-scm.org/fossil/xfer |
| 144 | </blockquote> |
| 145 | |
| 146 | <h3>2.2 HTTP Request Format</h3> |
| 147 | |
| 148 | The client always sends a POST request to the server. The |
| 149 | general format of the POST request is as follows: |
| 150 | |
| 151 | <blockquote><pre> |
| 152 | POST /fossil/xfer HTTP/1.0 |
| 153 | Host: fossil-scm.hwaci.com:80 |
| 154 | Content-Type: application/x-fossil |
| 155 | Content-Length: 4216 |
| 156 | |
| 157 | <i>content...</i> |
| 158 | </pre></blockquote> |
| 159 | |
| 160 | In the example above, the pathname given after the POST keyword |
| 161 | on the first line is a copy of the URL pathname. The Host: parameter |
| 162 | is also taken from the URL. The content type is always either |
| 163 | "application/x-fossil" or "application/x-fossil-debug". The "x-fossil" |
| @@ -165,20 +161,20 @@ | |
| 165 | content is compressed using zlib whereas "x-fossil-debug" is sent |
| 166 | uncompressed. |
| 167 | |
| 168 | A typical reply from the server might look something like this: |
| 169 | |
| 170 | <blockquote><pre> |
| 171 | HTTP/1.0 200 OK |
| 172 | Date: Mon, 10 Sep 2007 12:21:01 GMT |
| 173 | Connection: close |
| 174 | Cache-control: private |
| 175 | Content-Type: application/x-fossil; charset=US-ASCII |
| 176 | Content-Length: 265 |
| 177 | |
| 178 | <i>content...</i> |
| 179 | </pre></blockquote> |
| 180 | |
| 181 | The content type of the reply is always the same as the content type |
| 182 | of the request. |
| 183 | |
| 184 | <h2>3.0 Fossil Synchronization Content</h2> |
| @@ -202,13 +198,11 @@ | |
| 202 | <h3>3.2 Login Cards</h3> |
| 203 | |
| 204 | Every message from client to server begins with one or more login |
| 205 | cards. Each login card has the following format: |
| 206 | |
| 207 | <blockquote> |
| 208 | <b>login</b> <i>userid nonce signature</i> |
| 209 | </blockquote> |
| 210 | |
| 211 | The userid is the name of the user that is requesting service |
| 212 | from the server. The nonce is the SHA1 hash of the remainder of |
| 213 | the message - all text that follows the newline character that |
| 214 | terminates the login card. The signature is the SHA1 hash of |
| @@ -241,14 +235,14 @@ | |
| 241 | cards. File cards come in two different formats depending |
| 242 | on whether the artifact is sent directly or as a |
| 243 | [./delta_format.wiki|delta] from some |
| 244 | other artifact. |
| 245 | |
| 246 | <blockquote> |
| 247 | <b>file</b> <i>artifact-id size</i> <b>\n</b> <i>content</i><br> |
| 248 | <b>file</b> <i>artifact-id delta-artifact-id size</i> <b>\n</b> <i>content</i> |
| 249 | </blockquote> |
| 250 | |
| 251 | File cards are followed by in-line "payload" data. |
| 252 | The content of the artifact |
| 253 | or the artifact delta is the first <i>size</i> bytes of the |
| 254 | x-fossil content that immediately follow the newline that |
| @@ -282,14 +276,14 @@ | |
| 282 | in-line "payload" data characteristics and also the same treatment of |
| 283 | direct content or delta content. Cfile cards come in two different formats |
| 284 | depending on whether the artifact is sent directly or as a delta from |
| 285 | some other artifact. |
| 286 | |
| 287 | <blockquote> |
| 288 | <b>cfile</b> <i>artifact-id usize csize</i> <b>\n</b> <i>content</i><br> |
| 289 | <b>cfile</b> <i>artifact-id delta-artifact-id usize csize</i> <b>\n</b> <i>content</i><br> |
| 290 | </blockquote> |
| 291 | |
| 292 | The first argument of the cfile card is the ID of the artifact that |
| 293 | is being transferred. The artifact ID is the lower-case hexadecimal |
| 294 | representation of the name hash for the artifact. The second argument of |
| 295 | the cfile card is the original size in bytes of the artifact. The last |
| @@ -311,25 +305,21 @@ | |
| 311 | the [/help?cmd=sync|fossil sync] command includes the "--private" option. |
| 312 | |
| 313 | |
| 314 | Private content is marked by a "private" card: |
| 315 | |
| 316 | <blockquote> |
| 317 | <b>private</b> |
| 318 | </blockquote> |
| 319 | |
| 320 | The private card has no arguments and must directly precede a |
| 321 | file card that contains the private content. |
| 322 | |
| 323 | <h4>3.3.4 Unversioned File Cards</h4> |
| 324 | |
| 325 | Unversioned content is sent in both directions (client to server and |
| 326 | server to client) using "uvfile" cards in the following format: |
| 327 | |
| 328 | <blockquote> |
| 329 | <b>uvfile</b> <i>name mtime hash size flags</i> <b>\n</b> <i>content</i> |
| 330 | </blockquote> |
| 331 | |
| 332 | The <i>name</i> field is the name of the unversioned file. The |
| 333 | <i>mtime</i> is the last modification time of the file in seconds |
| 334 | since 1970. The <i>hash</i> field is the hash of the content |
| 335 | for the unversioned file, or "<b>-</b>" for deleted content. |
| @@ -360,14 +350,14 @@ | |
| 360 | the push and pull cards. The push card tells the server that |
| 361 | the client is pushing content. The pull card tells the server |
| 362 | that the client wants to pull content. In the event of a sync, |
| 363 | both cards are sent. The format is as follows: |
| 364 | |
| 365 | <blockquote> |
| 366 | <b>push</b> <i>servercode projectcode</i><br> |
| 367 | <b>pull</b> <i>servercode projectcode</i> |
| 368 | </blockquote> |
| 369 | |
| 370 | The <i>servercode</i> argument is the repository ID for the |
| 371 | client. The <i>projectcode</i> is the identifier |
| 372 | of the software project that the client repository contains. |
| 373 | The projectcode for the client and server must match in order |
| @@ -385,14 +375,14 @@ | |
| 385 | client to server in order to tell the server that the client |
| 386 | wants to pull content. The clone card comes in two formats. Older |
| 387 | clients use the no-argument format and newer clients use the |
| 388 | two-argument format. |
| 389 | |
| 390 | <blockquote> |
| 391 | <b>clone</b><br> |
| 392 | <b>clone</b> <i>protocol-version sequence-number</i> |
| 393 | </blockquote> |
| 394 | |
| 395 | <h4>3.5.1 Protocol 3</h4> |
| 396 | |
| 397 | The latest clients send a two-argument clone message with a |
| 398 | protocol version of "3". (Future versions of Fossil might use larger |
| @@ -409,13 +399,13 @@ | |
| 409 | cards for some number of artifacts up to the maximum message size. |
| 410 | |
| 411 | The server will also send a single "clone_seqno" card to the client |
| 412 | so that the client can know where the server left off. |
| 413 | |
| 414 | <blockquote> |
| 415 | <b>clone_seqno</b> <i>sequence-number</i> |
| 416 | </blockquote> |
| 417 | |
| 418 | The clone message in subsequent HTTP requests for the same clone |
| 419 | operation will use the sequence-number from the |
| 420 | clone_seqno of the previous reply. |
| 421 | |
| @@ -440,13 +430,13 @@ | |
| 440 | |
| 441 | An igot card can be sent from either client to server or from |
| 442 | server to client in order to indicate that the sender holds a copy |
| 443 | of a particular artifact. The format is: |
| 444 | |
| 445 | <blockquote> |
| 446 | <b>igot</b> <i>artifact-id</i> ?<i>flag</i>? |
| 447 | </blockquote> |
| 448 | |
| 449 | The first argument of the igot card is the ID of the artifact that |
| 450 | the sender possesses. |
| 451 | The receiver of an igot card will typically check to see if |
| 452 | it also holds the same artifact and if not it will request the artifact |
| @@ -463,13 +453,13 @@ | |
| 463 | |
| 464 | Zero or more "uvigot" cards are sent from server to client when |
| 465 | synchronizing unversioned content. The format of a uvigot card is |
| 466 | as follows: |
| 467 | |
| 468 | <blockquote> |
| 469 | <b>uvigot</b> <i>name mtime hash size</i> |
| 470 | </blockquote> |
| 471 | |
| 472 | The <i>name</i> argument is the name of an unversioned file. |
| 473 | The <i>mtime</i> is the last modification time of the unversioned file |
| 474 | in seconds since 1970. |
| 475 | The <i>hash</i> is the SHA1 or SHA3-256 hash of the unversioned file |
| @@ -495,13 +485,13 @@ | |
| 495 | |
| 496 | A gimme card is sent from either client to server or from server |
| 497 | to client. The gimme card asks the receiver to send a particular |
| 498 | artifact back to the sender. The format of a gimme card is this: |
| 499 | |
| 500 | <blockquote> |
| 501 | <b>gimme</b> <i>artifact-id</i> |
| 502 | </blockquote> |
| 503 | |
| 504 | The argument to the gimme card is the ID of the artifact that |
| 505 | the sender wants. The receiver will typically respond to a |
| 506 | gimme card by sending a file card in its reply or in the next |
| 507 | message. |
| @@ -515,13 +505,13 @@ | |
| 515 | Sync synchronizing unversioned content, the client may send "uvgimme" |
| 516 | cards to the server. A uvgimme card requests that the server send |
| 517 | unversioned content to the client. The format of a uvgimme card is |
| 518 | as follows: |
| 519 | |
| 520 | <blockquote> |
| 521 | <b>uvgimme</b> <i>name</i> |
| 522 | </blockquote> |
| 523 | |
| 524 | The <i>name</i> is the name of the unversioned file found on the |
| 525 | server that the client would like to have. When a server sees a |
| 526 | uvgimme card, it normally responses with a uvfile card, though it might |
| 527 | also send another uvigot card if the HTTP reply is already oversized. |
| @@ -532,13 +522,13 @@ | |
| 532 | of state information on a client. The server sends a cookie to the |
| 533 | client. The client sends the same cookie back to the server on |
| 534 | its next request. The cookie card has a single argument which |
| 535 | is its payload. |
| 536 | |
| 537 | <blockquote> |
| 538 | <b>cookie</b> <i>payload</i> |
| 539 | </blockquote> |
| 540 | |
| 541 | The client is not required to return the cookie to the server on |
| 542 | its next request. Or the client might send a cookie from a different |
| 543 | server on the next request. So the server must not depend on the |
| 544 | cookie and the server must structure the cookie payload in such |
| @@ -558,13 +548,13 @@ | |
| 558 | data elements. |
| 559 | |
| 560 | The reqconfig card is normally sent in response to the |
| 561 | "fossil configuration pull" command. The format is as follows: |
| 562 | |
| 563 | <blockquote> |
| 564 | <b>reqconfig</b> <i>configuration-name</i> |
| 565 | </blockquote> |
| 566 | |
| 567 | As of 2018-06-04, the configuration-name must be one of the |
| 568 | following values: |
| 569 | |
| 570 | <table border=0 align="center"> |
| @@ -603,11 +593,11 @@ | |
| 603 | <li> crlf-glob |
| 604 | <ul></td><td valign="top"><ul> |
| 605 | <li> crnl-glob |
| 606 | <li> encoding-glob |
| 607 | <li> empty-dirs |
| 608 | <li> <s>allow-symlinks</s> (removed 2020-08, version 2.12.1) |
| 609 | <li> dotfiles |
| 610 | <li> parent-project-code |
| 611 | <li> parent-projet-name |
| 612 | <li> hash-policy |
| 613 | <li> mv-rm-files |
| @@ -660,13 +650,13 @@ | |
| 660 | A "config" card is used to send configuration information from client |
| 661 | to server (in response to a "fossil configuration push" command) or |
| 662 | from server to client (in response to a "fossil configuration pull" or |
| 663 | "fossil clone" command). The format is as follows: |
| 664 | |
| 665 | <blockquote> |
| 666 | <b>config</b> <i>configuration-name size</i> <b>\n</b> <i>content</i> |
| 667 | </blockquote> |
| 668 | |
| 669 | The server will only accept a config card if the user has |
| 670 | "Admin" privilege. A client will only accept a config card if |
| 671 | it had sent a corresponding reqconfig card in its request. |
| 672 | |
| @@ -676,13 +666,13 @@ | |
| 676 | <h3>3.11 Pragma Cards</h3> |
| 677 | |
| 678 | The client may try to influence the behavior of the server by |
| 679 | issuing a pragma card: |
| 680 | |
| 681 | <blockquote> |
| 682 | <b>pragma</i> <i>name value...</i> |
| 683 | </blockquote> |
| 684 | |
| 685 | The "pragma" card has at least one argument which is the pragma name. |
| 686 | The pragma name defines what the pragma does. |
| 687 | A pragma might have zero or more "value" arguments |
| 688 | depending on the pragma name. |
| @@ -775,13 +765,13 @@ | |
| 775 | If the server discovers anything wrong with a request, it generates |
| 776 | an error card in its reply. When the client sees the error card, |
| 777 | it displays an error message to the user and aborts the sync |
| 778 | operation. An error card looks like this: |
| 779 | |
| 780 | <blockquote> |
| 781 | <b>error</b> <i>error-message</i> |
| 782 | </blockquote> |
| 783 | |
| 784 | The error message is English text that is encoded in order to |
| 785 | be a single token. |
| 786 | A space (ASCII 0x20) is represented as "\s" (ASCII 0x5C, 0x73). A |
| 787 | newline (ASCII 0x0a) is "\n" (ASCII 0x6C, x6E). A backslash |
| @@ -791,13 +781,13 @@ | |
| 791 | the error message. |
| 792 | |
| 793 | The server can also send a message card that also prints a |
| 794 | message on the client console, but which is not an error: |
| 795 | |
| 796 | <blockquote> |
| 797 | <b>message</b> <i>message-text</i> |
| 798 | </blockquote> |
| 799 | |
| 800 | The message-text uses the same format as an error message. |
| 801 | |
| 802 | <h3>3.14 Unknown Cards</h3> |
| 803 | |
| 804 |
| --- www/sync.wiki | |
| +++ www/sync.wiki | |
| @@ -130,34 +130,30 @@ | |
| 130 | |
| 131 | The client modifies the URL by appending the method name "<b>/xfer</b>" |
| 132 | to the end. For example, if the URL specified on the client command |
| 133 | line is |
| 134 | |
| 135 | <pre>https://fossil-scm.org/fossil</pre> |
| 136 | |
| 137 | Then the URL that is really used to do the synchronization will |
| 138 | be: |
| 139 | |
| 140 | <pre>https://fossil-scm.org/fossil/xfer</pre> |
| 141 | |
| 142 | <h3>2.2 HTTP Request Format</h3> |
| 143 | |
| 144 | The client always sends a POST request to the server. The |
| 145 | general format of the POST request is as follows: |
| 146 | |
| 147 | <pre> |
| 148 | POST /fossil/xfer HTTP/1.0 |
| 149 | Host: fossil-scm.hwaci.com:80 |
| 150 | Content-Type: application/x-fossil |
| 151 | Content-Length: 4216 |
| 152 | </pre> |
| 153 | |
| 154 | <i><pre>content...</pre></i> |
| 155 | |
| 156 | In the example above, the pathname given after the POST keyword |
| 157 | on the first line is a copy of the URL pathname. The Host: parameter |
| 158 | is also taken from the URL. The content type is always either |
| 159 | "application/x-fossil" or "application/x-fossil-debug". The "x-fossil" |
| @@ -165,20 +161,20 @@ | |
| 161 | content is compressed using zlib whereas "x-fossil-debug" is sent |
| 162 | uncompressed. |
| 163 | |
| 164 | A typical reply from the server might look something like this: |
| 165 | |
| 166 | <pre> |
| 167 | HTTP/1.0 200 OK |
| 168 | Date: Mon, 10 Sep 2007 12:21:01 GMT |
| 169 | Connection: close |
| 170 | Cache-control: private |
| 171 | Content-Type: application/x-fossil; charset=US-ASCII |
| 172 | Content-Length: 265 |
| 173 | </pre> |
| 174 | |
| 175 | <i><pre>content...</pre></i> |
| 176 | |
| 177 | The content type of the reply is always the same as the content type |
| 178 | of the request. |
| 179 | |
| 180 | <h2>3.0 Fossil Synchronization Content</h2> |
| @@ -202,13 +198,11 @@ | |
| 198 | <h3>3.2 Login Cards</h3> |
| 199 | |
| 200 | Every message from client to server begins with one or more login |
| 201 | cards. Each login card has the following format: |
| 202 | |
| 203 | <pre><b>login</b> <i>userid nonce signature</i></pre> |
| 204 | |
| 205 | The userid is the name of the user that is requesting service |
| 206 | from the server. The nonce is the SHA1 hash of the remainder of |
| 207 | the message - all text that follows the newline character that |
| 208 | terminates the login card. The signature is the SHA1 hash of |
| @@ -241,14 +235,14 @@ | |
| 235 | cards. File cards come in two different formats depending |
| 236 | on whether the artifact is sent directly or as a |
| 237 | [./delta_format.wiki|delta] from some |
| 238 | other artifact. |
| 239 | |
| 240 | <pre> |
| 241 | <b>file</b> <i>artifact-id size</i> <b>\n</b> <i>content</i> |
| 242 | <b>file</b> <i>artifact-id delta-artifact-id size</i> <b>\n</b> <i>content</i> |
| 243 | </pre> |
| 244 | |
| 245 | File cards are followed by in-line "payload" data. |
| 246 | The content of the artifact |
| 247 | or the artifact delta is the first <i>size</i> bytes of the |
| 248 | x-fossil content that immediately follow the newline that |
| @@ -282,14 +276,14 @@ | |
| 276 | in-line "payload" data characteristics and also the same treatment of |
| 277 | direct content or delta content. Cfile cards come in two different formats |
| 278 | depending on whether the artifact is sent directly or as a delta from |
| 279 | some other artifact. |
| 280 | |
| 281 | <pre> |
| 282 | <b>cfile</b> <i>artifact-id usize csize</i> <b>\n</b> <i>content</i> |
| 283 | <b>cfile</b> <i>artifact-id delta-artifact-id usize csize</i> <b>\n</b> <i>content</i> |
| 284 | </pre> |
| 285 | |
| 286 | The first argument of the cfile card is the ID of the artifact that |
| 287 | is being transferred. The artifact ID is the lower-case hexadecimal |
| 288 | representation of the name hash for the artifact. The second argument of |
| 289 | the cfile card is the original size in bytes of the artifact. The last |
| @@ -311,25 +305,21 @@ | |
| 305 | the [/help?cmd=sync|fossil sync] command includes the "--private" option. |
| 306 | |
| 307 | |
| 308 | Private content is marked by a "private" card: |
| 309 | |
| 310 | <pre><b>private</b></pre> |
| 311 | |
| 312 | The private card has no arguments and must directly precede a |
| 313 | file card that contains the private content. |
| 314 | |
| 315 | <h4>3.3.4 Unversioned File Cards</h4> |
| 316 | |
| 317 | Unversioned content is sent in both directions (client to server and |
| 318 | server to client) using "uvfile" cards in the following format: |
| 319 | |
| 320 | <pre><b>uvfile</b> <i>name mtime hash size flags</i> <b>\n</b> <i>content</i></pre> |
| 321 | |
| 322 | The <i>name</i> field is the name of the unversioned file. The |
| 323 | <i>mtime</i> is the last modification time of the file in seconds |
| 324 | since 1970. The <i>hash</i> field is the hash of the content |
| 325 | for the unversioned file, or "<b>-</b>" for deleted content. |
| @@ -360,14 +350,14 @@ | |
| 350 | the push and pull cards. The push card tells the server that |
| 351 | the client is pushing content. The pull card tells the server |
| 352 | that the client wants to pull content. In the event of a sync, |
| 353 | both cards are sent. The format is as follows: |
| 354 | |
| 355 | <pre> |
| 356 | <b>push</b> <i>servercode projectcode</i> |
| 357 | <b>pull</b> <i>servercode projectcode</i> |
| 358 | </pre> |
| 359 | |
| 360 | The <i>servercode</i> argument is the repository ID for the |
| 361 | client. The <i>projectcode</i> is the identifier |
| 362 | of the software project that the client repository contains. |
| 363 | The projectcode for the client and server must match in order |
| @@ -385,14 +375,14 @@ | |
| 375 | client to server in order to tell the server that the client |
| 376 | wants to pull content. The clone card comes in two formats. Older |
| 377 | clients use the no-argument format and newer clients use the |
| 378 | two-argument format. |
| 379 | |
| 380 | <pre> |
| 381 | <b>clone</b> |
| 382 | <b>clone</b> <i>protocol-version sequence-number</i> |
| 383 | </pre> |
| 384 | |
| 385 | <h4>3.5.1 Protocol 3</h4> |
| 386 | |
| 387 | The latest clients send a two-argument clone message with a |
| 388 | protocol version of "3". (Future versions of Fossil might use larger |
| @@ -409,13 +399,13 @@ | |
| 399 | cards for some number of artifacts up to the maximum message size. |
| 400 | |
| 401 | The server will also send a single "clone_seqno" card to the client |
| 402 | so that the client can know where the server left off. |
| 403 | |
| 404 | <pre> |
| 405 | <b>clone_seqno</b> <i>sequence-number</i> |
| 406 | </pre> |
| 407 | |
| 408 | The clone message in subsequent HTTP requests for the same clone |
| 409 | operation will use the sequence-number from the |
| 410 | clone_seqno of the previous reply. |
| 411 | |
| @@ -440,13 +430,13 @@ | |
| 430 | |
| 431 | An igot card can be sent from either client to server or from |
| 432 | server to client in order to indicate that the sender holds a copy |
| 433 | of a particular artifact. The format is: |
| 434 | |
| 435 | <pre> |
| 436 | <b>igot</b> <i>artifact-id</i> ?<i>flag</i>? |
| 437 | </pre> |
| 438 | |
| 439 | The first argument of the igot card is the ID of the artifact that |
| 440 | the sender possesses. |
| 441 | The receiver of an igot card will typically check to see if |
| 442 | it also holds the same artifact and if not it will request the artifact |
| @@ -463,13 +453,13 @@ | |
| 453 | |
| 454 | Zero or more "uvigot" cards are sent from server to client when |
| 455 | synchronizing unversioned content. The format of a uvigot card is |
| 456 | as follows: |
| 457 | |
| 458 | <pre> |
| 459 | <b>uvigot</b> <i>name mtime hash size</i> |
| 460 | </pre> |
| 461 | |
| 462 | The <i>name</i> argument is the name of an unversioned file. |
| 463 | The <i>mtime</i> is the last modification time of the unversioned file |
| 464 | in seconds since 1970. |
| 465 | The <i>hash</i> is the SHA1 or SHA3-256 hash of the unversioned file |
| @@ -495,13 +485,13 @@ | |
| 485 | |
| 486 | A gimme card is sent from either client to server or from server |
| 487 | to client. The gimme card asks the receiver to send a particular |
| 488 | artifact back to the sender. The format of a gimme card is this: |
| 489 | |
| 490 | <pre> |
| 491 | <b>gimme</b> <i>artifact-id</i> |
| 492 | </pre> |
| 493 | |
| 494 | The argument to the gimme card is the ID of the artifact that |
| 495 | the sender wants. The receiver will typically respond to a |
| 496 | gimme card by sending a file card in its reply or in the next |
| 497 | message. |
| @@ -515,13 +505,13 @@ | |
| 505 | Sync synchronizing unversioned content, the client may send "uvgimme" |
| 506 | cards to the server. A uvgimme card requests that the server send |
| 507 | unversioned content to the client. The format of a uvgimme card is |
| 508 | as follows: |
| 509 | |
| 510 | <pre> |
| 511 | <b>uvgimme</b> <i>name</i> |
| 512 | </pre> |
| 513 | |
| 514 | The <i>name</i> is the name of the unversioned file found on the |
| 515 | server that the client would like to have. When a server sees a |
| 516 | uvgimme card, it normally responses with a uvfile card, though it might |
| 517 | also send another uvigot card if the HTTP reply is already oversized. |
| @@ -532,13 +522,13 @@ | |
| 522 | of state information on a client. The server sends a cookie to the |
| 523 | client. The client sends the same cookie back to the server on |
| 524 | its next request. The cookie card has a single argument which |
| 525 | is its payload. |
| 526 | |
| 527 | <pre> |
| 528 | <b>cookie</b> <i>payload</i> |
| 529 | </pre> |
| 530 | |
| 531 | The client is not required to return the cookie to the server on |
| 532 | its next request. Or the client might send a cookie from a different |
| 533 | server on the next request. So the server must not depend on the |
| 534 | cookie and the server must structure the cookie payload in such |
| @@ -558,13 +548,13 @@ | |
| 548 | data elements. |
| 549 | |
| 550 | The reqconfig card is normally sent in response to the |
| 551 | "fossil configuration pull" command. The format is as follows: |
| 552 | |
| 553 | <pre> |
| 554 | <b>reqconfig</b> <i>configuration-name</i> |
| 555 | </pre> |
| 556 | |
| 557 | As of 2018-06-04, the configuration-name must be one of the |
| 558 | following values: |
| 559 | |
| 560 | <table border=0 align="center"> |
| @@ -603,11 +593,11 @@ | |
| 593 | <li> crlf-glob |
| 594 | <ul></td><td valign="top"><ul> |
| 595 | <li> crnl-glob |
| 596 | <li> encoding-glob |
| 597 | <li> empty-dirs |
| 598 | <li> <s title="removed 2020-08, version 2.12.1">allow-symlinks</s> |
| 599 | <li> dotfiles |
| 600 | <li> parent-project-code |
| 601 | <li> parent-projet-name |
| 602 | <li> hash-policy |
| 603 | <li> mv-rm-files |
| @@ -660,13 +650,13 @@ | |
| 650 | A "config" card is used to send configuration information from client |
| 651 | to server (in response to a "fossil configuration push" command) or |
| 652 | from server to client (in response to a "fossil configuration pull" or |
| 653 | "fossil clone" command). The format is as follows: |
| 654 | |
| 655 | <pre> |
| 656 | <b>config</b> <i>configuration-name size</i> <b>\n</b> <i>content</i> |
| 657 | </pre> |
| 658 | |
| 659 | The server will only accept a config card if the user has |
| 660 | "Admin" privilege. A client will only accept a config card if |
| 661 | it had sent a corresponding reqconfig card in its request. |
| 662 | |
| @@ -676,13 +666,13 @@ | |
| 666 | <h3>3.11 Pragma Cards</h3> |
| 667 | |
| 668 | The client may try to influence the behavior of the server by |
| 669 | issuing a pragma card: |
| 670 | |
| 671 | <pre> |
| 672 | <b>pragma</i> <i>name value...</i> |
| 673 | </pre> |
| 674 | |
| 675 | The "pragma" card has at least one argument which is the pragma name. |
| 676 | The pragma name defines what the pragma does. |
| 677 | A pragma might have zero or more "value" arguments |
| 678 | depending on the pragma name. |
| @@ -775,13 +765,13 @@ | |
| 765 | If the server discovers anything wrong with a request, it generates |
| 766 | an error card in its reply. When the client sees the error card, |
| 767 | it displays an error message to the user and aborts the sync |
| 768 | operation. An error card looks like this: |
| 769 | |
| 770 | <pre> |
| 771 | <b>error</b> <i>error-message</i> |
| 772 | </pre> |
| 773 | |
| 774 | The error message is English text that is encoded in order to |
| 775 | be a single token. |
| 776 | A space (ASCII 0x20) is represented as "\s" (ASCII 0x5C, 0x73). A |
| 777 | newline (ASCII 0x0a) is "\n" (ASCII 0x6C, x6E). A backslash |
| @@ -791,13 +781,13 @@ | |
| 781 | the error message. |
| 782 | |
| 783 | The server can also send a message card that also prints a |
| 784 | message on the client console, but which is not an error: |
| 785 | |
| 786 | <pre> |
| 787 | <b>message</b> <i>message-text</i> |
| 788 | </pre> |
| 789 | |
| 790 | The message-text uses the same format as an error message. |
| 791 | |
| 792 | <h3>3.14 Unknown Cards</h3> |
| 793 | |
| 794 |
+18
-22
| --- www/tech_overview.wiki | ||
| +++ www/tech_overview.wiki | ||
| @@ -65,35 +65,31 @@ | ||
| 65 | 65 | SQLite's [http://www.sqlite.org/lang_attach.html | ATTACH] command. |
| 66 | 66 | |
| 67 | 67 | The chart below provides a quick summary of how each of these |
| 68 | 68 | database files are used by Fossil, with detailed discussion following. |
| 69 | 69 | |
| 70 | -<table border="1" width="80%" cellpadding="0" align="center"> | |
| 71 | -<tr> | |
| 72 | -<td width="33%" valign="top"> | |
| 73 | -<h3 align="center">Configuration Database<br>"~/.fossil" or<br> | |
| 74 | -"~/.config/fossil.db"</h3> | |
| 75 | -<ul> | |
| 70 | +<table align="center"> | |
| 71 | +<tr valign="bottom"> | |
| 72 | +<th style="text-align:center">Configuration Database<br>"~/.fossil" or<br> | |
| 73 | +"~/.config/fossil.db" | |
| 74 | +<th style="text-align:center">Repository Database<br>"<i>project</i>.fossil" | |
| 75 | +<th style="text-align:center">Checkout Database<br>"_FOSSIL_" or ".fslckout" | |
| 76 | +<tr valign="top"> | |
| 77 | +<td><ul> | |
| 76 | 78 | <li>Global [/help/settings |settings] |
| 77 | 79 | <li>List of active repositories used by the [/help/all | all] command |
| 78 | -</ul> | |
| 79 | -</td> | |
| 80 | -<td width="34%" valign="top"> | |
| 81 | -<h3 align="center">Repository Database<br>"<i>project</i>.fossil"</h3> | |
| 82 | -<ul> | |
| 80 | +</ul></td> | |
| 81 | +<td><ul> | |
| 83 | 82 | <li>[./fileformat.wiki | Global state of the project] |
| 84 | 83 | encoded using delta-compression |
| 85 | 84 | <li>Local [/help/settings|settings] |
| 86 | 85 | <li>Web interface display preferences |
| 87 | 86 | <li>User credentials and permissions |
| 88 | 87 | <li>Metadata about the global state to facilitate rapid |
| 89 | 88 | queries |
| 90 | -</ul> | |
| 91 | -</td> | |
| 92 | -<td width="33%" valign="top"> | |
| 93 | -<h3 align="center">Checkout Database<br>"_FOSSIL_" or ".fslckout"</h3> | |
| 94 | -<ul> | |
| 89 | +</ul></td> | |
| 90 | +<td><ul> | |
| 95 | 91 | <li>The repository database used by this checkout |
| 96 | 92 | <li>The version currently checked out |
| 97 | 93 | <li>Other versions [/help/merge | merged] in but not |
| 98 | 94 | yet [/help/commit | committed] |
| 99 | 95 | <li>Changes from the [/help/add | add], [/help/delete | delete], |
| @@ -100,12 +96,11 @@ | ||
| 100 | 96 | and [/help/rename | rename] commands that have not yet been committed |
| 101 | 97 | <li>"mtime" values and other information used to efficiently detect |
| 102 | 98 | local edits |
| 103 | 99 | <li>The "[/help/stash | stash]" |
| 104 | 100 | <li>Information needed to "[/help/undo|undo]" or "[/help/redo|redo]" |
| 105 | -</ul> | |
| 106 | -</td> | |
| 101 | +</ul></td> | |
| 107 | 102 | </tr> |
| 108 | 103 | </table> |
| 109 | 104 | |
| 110 | 105 | <h3 id="configdb">2.1 The Configuration Database</h3> |
| 111 | 106 | |
| @@ -129,20 +124,21 @@ | ||
| 129 | 124 | <h4 id="configloc">2.1.1 Location Of The Configuration Database</h4> |
| 130 | 125 | |
| 131 | 126 | On Unix systems, the configuration database is named by the following |
| 132 | 127 | algorithm: |
| 133 | 128 | |
| 134 | -<blockquote><table border="0"> | |
| 129 | +<table> | |
| 135 | 130 | <tr><td>1. if environment variable FOSSIL_HOME exists |
| 136 | -<td> → <td>$FOSSIL_HOME/.fossil | |
| 137 | -<tr><td>2. if file ~/.fossil exists<td> →<td>~/.fossil | |
| 131 | + <td> → <td>$FOSSIL_HOME/.fossil | |
| 132 | +<tr><td>2. if file ~/.fossil exists | |
| 133 | + <td> →<td>~/.fossil | |
| 138 | 134 | <tr><td>3. if environment variable XDG_CONFIG_HOME exists |
| 139 | 135 | <td> →<td>$XDG_CONFIG_HOME/fossil.db |
| 140 | 136 | <tr><td>4. if the directory ~/.config exists |
| 141 | 137 | <td> →<td>~/.config/fossil.db |
| 142 | 138 | <tr><td>5. Otherwise<td> →<td>~/.fossil |
| 143 | -</table></blockquote> | |
| 139 | +</table> | |
| 144 | 140 | |
| 145 | 141 | Another way of thinking of this algorithm is the following: |
| 146 | 142 | |
| 147 | 143 | * Use "$FOSSIL_HOME/.fossil" if the FOSSIL_HOME variable is defined |
| 148 | 144 | * Use the XDG-compatible name (usually ~/.config/fossil.db) on XDG systems |
| 149 | 145 |
| --- www/tech_overview.wiki | |
| +++ www/tech_overview.wiki | |
| @@ -65,35 +65,31 @@ | |
| 65 | SQLite's [http://www.sqlite.org/lang_attach.html | ATTACH] command. |
| 66 | |
| 67 | The chart below provides a quick summary of how each of these |
| 68 | database files are used by Fossil, with detailed discussion following. |
| 69 | |
| 70 | <table border="1" width="80%" cellpadding="0" align="center"> |
| 71 | <tr> |
| 72 | <td width="33%" valign="top"> |
| 73 | <h3 align="center">Configuration Database<br>"~/.fossil" or<br> |
| 74 | "~/.config/fossil.db"</h3> |
| 75 | <ul> |
| 76 | <li>Global [/help/settings |settings] |
| 77 | <li>List of active repositories used by the [/help/all | all] command |
| 78 | </ul> |
| 79 | </td> |
| 80 | <td width="34%" valign="top"> |
| 81 | <h3 align="center">Repository Database<br>"<i>project</i>.fossil"</h3> |
| 82 | <ul> |
| 83 | <li>[./fileformat.wiki | Global state of the project] |
| 84 | encoded using delta-compression |
| 85 | <li>Local [/help/settings|settings] |
| 86 | <li>Web interface display preferences |
| 87 | <li>User credentials and permissions |
| 88 | <li>Metadata about the global state to facilitate rapid |
| 89 | queries |
| 90 | </ul> |
| 91 | </td> |
| 92 | <td width="33%" valign="top"> |
| 93 | <h3 align="center">Checkout Database<br>"_FOSSIL_" or ".fslckout"</h3> |
| 94 | <ul> |
| 95 | <li>The repository database used by this checkout |
| 96 | <li>The version currently checked out |
| 97 | <li>Other versions [/help/merge | merged] in but not |
| 98 | yet [/help/commit | committed] |
| 99 | <li>Changes from the [/help/add | add], [/help/delete | delete], |
| @@ -100,12 +96,11 @@ | |
| 100 | and [/help/rename | rename] commands that have not yet been committed |
| 101 | <li>"mtime" values and other information used to efficiently detect |
| 102 | local edits |
| 103 | <li>The "[/help/stash | stash]" |
| 104 | <li>Information needed to "[/help/undo|undo]" or "[/help/redo|redo]" |
| 105 | </ul> |
| 106 | </td> |
| 107 | </tr> |
| 108 | </table> |
| 109 | |
| 110 | <h3 id="configdb">2.1 The Configuration Database</h3> |
| 111 | |
| @@ -129,20 +124,21 @@ | |
| 129 | <h4 id="configloc">2.1.1 Location Of The Configuration Database</h4> |
| 130 | |
| 131 | On Unix systems, the configuration database is named by the following |
| 132 | algorithm: |
| 133 | |
| 134 | <blockquote><table border="0"> |
| 135 | <tr><td>1. if environment variable FOSSIL_HOME exists |
| 136 | <td> → <td>$FOSSIL_HOME/.fossil |
| 137 | <tr><td>2. if file ~/.fossil exists<td> →<td>~/.fossil |
| 138 | <tr><td>3. if environment variable XDG_CONFIG_HOME exists |
| 139 | <td> →<td>$XDG_CONFIG_HOME/fossil.db |
| 140 | <tr><td>4. if the directory ~/.config exists |
| 141 | <td> →<td>~/.config/fossil.db |
| 142 | <tr><td>5. Otherwise<td> →<td>~/.fossil |
| 143 | </table></blockquote> |
| 144 | |
| 145 | Another way of thinking of this algorithm is the following: |
| 146 | |
| 147 | * Use "$FOSSIL_HOME/.fossil" if the FOSSIL_HOME variable is defined |
| 148 | * Use the XDG-compatible name (usually ~/.config/fossil.db) on XDG systems |
| 149 |
| --- www/tech_overview.wiki | |
| +++ www/tech_overview.wiki | |
| @@ -65,35 +65,31 @@ | |
| 65 | SQLite's [http://www.sqlite.org/lang_attach.html | ATTACH] command. |
| 66 | |
| 67 | The chart below provides a quick summary of how each of these |
| 68 | database files are used by Fossil, with detailed discussion following. |
| 69 | |
| 70 | <table align="center"> |
| 71 | <tr valign="bottom"> |
| 72 | <th style="text-align:center">Configuration Database<br>"~/.fossil" or<br> |
| 73 | "~/.config/fossil.db" |
| 74 | <th style="text-align:center">Repository Database<br>"<i>project</i>.fossil" |
| 75 | <th style="text-align:center">Checkout Database<br>"_FOSSIL_" or ".fslckout" |
| 76 | <tr valign="top"> |
| 77 | <td><ul> |
| 78 | <li>Global [/help/settings |settings] |
| 79 | <li>List of active repositories used by the [/help/all | all] command |
| 80 | </ul></td> |
| 81 | <td><ul> |
| 82 | <li>[./fileformat.wiki | Global state of the project] |
| 83 | encoded using delta-compression |
| 84 | <li>Local [/help/settings|settings] |
| 85 | <li>Web interface display preferences |
| 86 | <li>User credentials and permissions |
| 87 | <li>Metadata about the global state to facilitate rapid |
| 88 | queries |
| 89 | </ul></td> |
| 90 | <td><ul> |
| 91 | <li>The repository database used by this checkout |
| 92 | <li>The version currently checked out |
| 93 | <li>Other versions [/help/merge | merged] in but not |
| 94 | yet [/help/commit | committed] |
| 95 | <li>Changes from the [/help/add | add], [/help/delete | delete], |
| @@ -100,12 +96,11 @@ | |
| 96 | and [/help/rename | rename] commands that have not yet been committed |
| 97 | <li>"mtime" values and other information used to efficiently detect |
| 98 | local edits |
| 99 | <li>The "[/help/stash | stash]" |
| 100 | <li>Information needed to "[/help/undo|undo]" or "[/help/redo|redo]" |
| 101 | </ul></td> |
| 102 | </tr> |
| 103 | </table> |
| 104 | |
| 105 | <h3 id="configdb">2.1 The Configuration Database</h3> |
| 106 | |
| @@ -129,20 +124,21 @@ | |
| 124 | <h4 id="configloc">2.1.1 Location Of The Configuration Database</h4> |
| 125 | |
| 126 | On Unix systems, the configuration database is named by the following |
| 127 | algorithm: |
| 128 | |
| 129 | <table> |
| 130 | <tr><td>1. if environment variable FOSSIL_HOME exists |
| 131 | <td> → <td>$FOSSIL_HOME/.fossil |
| 132 | <tr><td>2. if file ~/.fossil exists |
| 133 | <td> →<td>~/.fossil |
| 134 | <tr><td>3. if environment variable XDG_CONFIG_HOME exists |
| 135 | <td> →<td>$XDG_CONFIG_HOME/fossil.db |
| 136 | <tr><td>4. if the directory ~/.config exists |
| 137 | <td> →<td>~/.config/fossil.db |
| 138 | <tr><td>5. Otherwise<td> →<td>~/.fossil |
| 139 | </table> |
| 140 | |
| 141 | Another way of thinking of this algorithm is the following: |
| 142 | |
| 143 | * Use "$FOSSIL_HOME/.fossil" if the FOSSIL_HOME variable is defined |
| 144 | * Use the XDG-compatible name (usually ~/.config/fossil.db) on XDG systems |
| 145 |
+22
-22
| --- www/th1.md | ||
| +++ www/th1.md | ||
| @@ -54,15 +54,15 @@ | ||
| 54 | 54 | C/C++ programmers because TH1 does look a lot like C/C++, but the semantics |
| 55 | 55 | of TH1 are closer to FORTH or Lisp than they are to C. |
| 56 | 56 | |
| 57 | 57 | Consider the `if` command in TH1. |
| 58 | 58 | |
| 59 | - if {$current eq "dev"} { | |
| 60 | - puts "hello" | |
| 61 | - } else { | |
| 62 | - puts "world" | |
| 63 | - } | |
| 59 | + if {$current eq "dev"} { | |
| 60 | + puts "hello" | |
| 61 | + } else { | |
| 62 | + puts "world" | |
| 63 | + } | |
| 64 | 64 | |
| 65 | 65 | The example above is a single command. The first token, and the name |
| 66 | 66 | of the command, is `if`. |
| 67 | 67 | The second token is `$current eq "dev"` - an expression. (The outer {...} |
| 68 | 68 | are removed from each token by the command parser.) The third token |
| @@ -83,16 +83,16 @@ | ||
| 83 | 83 | block delimiters as in C. This is how we can have a command that extends |
| 84 | 84 | over multiple lines. It is also why the `else` keyword must be cuddled |
| 85 | 85 | up with the closing brace for the `if` clause's scriptlet. The following |
| 86 | 86 | is invalid Tcl/TH1: |
| 87 | 87 | |
| 88 | - if {$current eq "dev"} { | |
| 89 | - puts "hello" | |
| 90 | - } | |
| 91 | - else { | |
| 92 | - puts "world" | |
| 93 | - } | |
| 88 | + if {$current eq "dev"} { | |
| 89 | + puts "hello" | |
| 90 | + } | |
| 91 | + else { | |
| 92 | + puts "world" | |
| 93 | + } | |
| 94 | 94 | |
| 95 | 95 | If you try to run this under either Tcl or TH1, the interpreter will |
| 96 | 96 | tell you that there is no `else` command, because with the newline on |
| 97 | 97 | the third line, you terminated the `if` command. |
| 98 | 98 | |
| @@ -99,13 +99,13 @@ | ||
| 99 | 99 | Occasionally in Tcl/TH1 scripts, you may need to use a backslash at the |
| 100 | 100 | end of a line to allow a command to extend over multiple lines without |
| 101 | 101 | being considered two separate commands. Here's an example from one of |
| 102 | 102 | Fossil's test scripts: |
| 103 | 103 | |
| 104 | - return [lindex [regexp -line -inline -nocase -- \ | |
| 105 | - {^uuid:\s+([0-9A-F]{40}) } [eval [getFossilCommand \ | |
| 106 | - $repository "" info trunk]]] end] | |
| 104 | + return [lindex [regexp -line -inline -nocase -- \ | |
| 105 | + {^uuid:\s+([0-9A-F]{40}) } [eval [getFossilCommand \ | |
| 106 | + $repository "" info trunk]]] end] | |
| 107 | 107 | |
| 108 | 108 | Those backslashes allow the command to wrap nicely within a standard |
| 109 | 109 | terminal width while telling the interpreter to consider those three |
| 110 | 110 | lines as a single command. |
| 111 | 111 | |
| @@ -298,16 +298,16 @@ | ||
| 298 | 298 | always true. |
| 299 | 299 | |
| 300 | 300 | Examples: |
| 301 | 301 | |
| 302 | 302 | ``` |
| 303 | - capexpr {j o r} True if any one of j, o, or r are available | |
| 304 | - capexpr {oh} True if both o and h are available | |
| 305 | - capexpr {@2 @3 4 5 6} 2 or 3 available for anonymous or one of | |
| 306 | - 4, 5 or 6 is available for the user | |
| 307 | - capexpr L True if the user is logged in | |
| 308 | - capexpr !L True if the user is not logged in | |
| 303 | +capexpr {j o r} True if any one of j, o, or r are available | |
| 304 | +capexpr {oh} True if both o and h are available | |
| 305 | +capexpr {@2 @3 4 5 6} 2 or 3 available for anonymous or one of | |
| 306 | + 4, 5 or 6 is available for the user | |
| 307 | +capexpr L True if the user is logged in | |
| 308 | +capexpr !L True if the user is not logged in | |
| 309 | 309 | ``` |
| 310 | 310 | |
| 311 | 311 | The `L` pseudo-capability is intended only to be used on its own or with |
| 312 | 312 | the `!` prefix for implementing login/logout menus via the `mainmenu` |
| 313 | 313 | site configuration option: |
| @@ -683,15 +683,15 @@ | ||
| 683 | 683 | To be clear, only one of the document classes identified by each STRING |
| 684 | 684 | needs to be searchable in order for that argument to be true. But all |
| 685 | 685 | arguments must be true for this routine to return true. Hence, to see |
| 686 | 686 | if ALL document classes are searchable: |
| 687 | 687 | |
| 688 | - if {[searchable c d t w]} {...} | |
| 688 | + if {[searchable c d t w]} {...} | |
| 689 | 689 | |
| 690 | 690 | But to see if ANY document class is searchable: |
| 691 | 691 | |
| 692 | - if {[searchable cdtw]} {...} | |
| 692 | + if {[searchable cdtw]} {...} | |
| 693 | 693 | |
| 694 | 694 | This command is useful for enabling or disabling a "Search" entry on the |
| 695 | 695 | menu bar. |
| 696 | 696 | |
| 697 | 697 | <a id="setParameter"></a>TH1 setParameter Command |
| 698 | 698 |
| --- www/th1.md | |
| +++ www/th1.md | |
| @@ -54,15 +54,15 @@ | |
| 54 | C/C++ programmers because TH1 does look a lot like C/C++, but the semantics |
| 55 | of TH1 are closer to FORTH or Lisp than they are to C. |
| 56 | |
| 57 | Consider the `if` command in TH1. |
| 58 | |
| 59 | if {$current eq "dev"} { |
| 60 | puts "hello" |
| 61 | } else { |
| 62 | puts "world" |
| 63 | } |
| 64 | |
| 65 | The example above is a single command. The first token, and the name |
| 66 | of the command, is `if`. |
| 67 | The second token is `$current eq "dev"` - an expression. (The outer {...} |
| 68 | are removed from each token by the command parser.) The third token |
| @@ -83,16 +83,16 @@ | |
| 83 | block delimiters as in C. This is how we can have a command that extends |
| 84 | over multiple lines. It is also why the `else` keyword must be cuddled |
| 85 | up with the closing brace for the `if` clause's scriptlet. The following |
| 86 | is invalid Tcl/TH1: |
| 87 | |
| 88 | if {$current eq "dev"} { |
| 89 | puts "hello" |
| 90 | } |
| 91 | else { |
| 92 | puts "world" |
| 93 | } |
| 94 | |
| 95 | If you try to run this under either Tcl or TH1, the interpreter will |
| 96 | tell you that there is no `else` command, because with the newline on |
| 97 | the third line, you terminated the `if` command. |
| 98 | |
| @@ -99,13 +99,13 @@ | |
| 99 | Occasionally in Tcl/TH1 scripts, you may need to use a backslash at the |
| 100 | end of a line to allow a command to extend over multiple lines without |
| 101 | being considered two separate commands. Here's an example from one of |
| 102 | Fossil's test scripts: |
| 103 | |
| 104 | return [lindex [regexp -line -inline -nocase -- \ |
| 105 | {^uuid:\s+([0-9A-F]{40}) } [eval [getFossilCommand \ |
| 106 | $repository "" info trunk]]] end] |
| 107 | |
| 108 | Those backslashes allow the command to wrap nicely within a standard |
| 109 | terminal width while telling the interpreter to consider those three |
| 110 | lines as a single command. |
| 111 | |
| @@ -298,16 +298,16 @@ | |
| 298 | always true. |
| 299 | |
| 300 | Examples: |
| 301 | |
| 302 | ``` |
| 303 | capexpr {j o r} True if any one of j, o, or r are available |
| 304 | capexpr {oh} True if both o and h are available |
| 305 | capexpr {@2 @3 4 5 6} 2 or 3 available for anonymous or one of |
| 306 | 4, 5 or 6 is available for the user |
| 307 | capexpr L True if the user is logged in |
| 308 | capexpr !L True if the user is not logged in |
| 309 | ``` |
| 310 | |
| 311 | The `L` pseudo-capability is intended only to be used on its own or with |
| 312 | the `!` prefix for implementing login/logout menus via the `mainmenu` |
| 313 | site configuration option: |
| @@ -683,15 +683,15 @@ | |
| 683 | To be clear, only one of the document classes identified by each STRING |
| 684 | needs to be searchable in order for that argument to be true. But all |
| 685 | arguments must be true for this routine to return true. Hence, to see |
| 686 | if ALL document classes are searchable: |
| 687 | |
| 688 | if {[searchable c d t w]} {...} |
| 689 | |
| 690 | But to see if ANY document class is searchable: |
| 691 | |
| 692 | if {[searchable cdtw]} {...} |
| 693 | |
| 694 | This command is useful for enabling or disabling a "Search" entry on the |
| 695 | menu bar. |
| 696 | |
| 697 | <a id="setParameter"></a>TH1 setParameter Command |
| 698 |
| --- www/th1.md | |
| +++ www/th1.md | |
| @@ -54,15 +54,15 @@ | |
| 54 | C/C++ programmers because TH1 does look a lot like C/C++, but the semantics |
| 55 | of TH1 are closer to FORTH or Lisp than they are to C. |
| 56 | |
| 57 | Consider the `if` command in TH1. |
| 58 | |
| 59 | if {$current eq "dev"} { |
| 60 | puts "hello" |
| 61 | } else { |
| 62 | puts "world" |
| 63 | } |
| 64 | |
| 65 | The example above is a single command. The first token, and the name |
| 66 | of the command, is `if`. |
| 67 | The second token is `$current eq "dev"` - an expression. (The outer {...} |
| 68 | are removed from each token by the command parser.) The third token |
| @@ -83,16 +83,16 @@ | |
| 83 | block delimiters as in C. This is how we can have a command that extends |
| 84 | over multiple lines. It is also why the `else` keyword must be cuddled |
| 85 | up with the closing brace for the `if` clause's scriptlet. The following |
| 86 | is invalid Tcl/TH1: |
| 87 | |
| 88 | if {$current eq "dev"} { |
| 89 | puts "hello" |
| 90 | } |
| 91 | else { |
| 92 | puts "world" |
| 93 | } |
| 94 | |
| 95 | If you try to run this under either Tcl or TH1, the interpreter will |
| 96 | tell you that there is no `else` command, because with the newline on |
| 97 | the third line, you terminated the `if` command. |
| 98 | |
| @@ -99,13 +99,13 @@ | |
| 99 | Occasionally in Tcl/TH1 scripts, you may need to use a backslash at the |
| 100 | end of a line to allow a command to extend over multiple lines without |
| 101 | being considered two separate commands. Here's an example from one of |
| 102 | Fossil's test scripts: |
| 103 | |
| 104 | return [lindex [regexp -line -inline -nocase -- \ |
| 105 | {^uuid:\s+([0-9A-F]{40}) } [eval [getFossilCommand \ |
| 106 | $repository "" info trunk]]] end] |
| 107 | |
| 108 | Those backslashes allow the command to wrap nicely within a standard |
| 109 | terminal width while telling the interpreter to consider those three |
| 110 | lines as a single command. |
| 111 | |
| @@ -298,16 +298,16 @@ | |
| 298 | always true. |
| 299 | |
| 300 | Examples: |
| 301 | |
| 302 | ``` |
| 303 | capexpr {j o r} True if any one of j, o, or r are available |
| 304 | capexpr {oh} True if both o and h are available |
| 305 | capexpr {@2 @3 4 5 6} 2 or 3 available for anonymous or one of |
| 306 | 4, 5 or 6 is available for the user |
| 307 | capexpr L True if the user is logged in |
| 308 | capexpr !L True if the user is not logged in |
| 309 | ``` |
| 310 | |
| 311 | The `L` pseudo-capability is intended only to be used on its own or with |
| 312 | the `!` prefix for implementing login/logout menus via the `mainmenu` |
| 313 | site configuration option: |
| @@ -683,15 +683,15 @@ | |
| 683 | To be clear, only one of the document classes identified by each STRING |
| 684 | needs to be searchable in order for that argument to be true. But all |
| 685 | arguments must be true for this routine to return true. Hence, to see |
| 686 | if ALL document classes are searchable: |
| 687 | |
| 688 | if {[searchable c d t w]} {...} |
| 689 | |
| 690 | But to see if ANY document class is searchable: |
| 691 | |
| 692 | if {[searchable cdtw]} {...} |
| 693 | |
| 694 | This command is useful for enabling or disabling a "Search" entry on the |
| 695 | menu bar. |
| 696 | |
| 697 | <a id="setParameter"></a>TH1 setParameter Command |
| 698 |
-1
| --- www/theory1.wiki | ||
| +++ www/theory1.wiki | ||
| @@ -1,7 +1,6 @@ | ||
| 1 | 1 | <title>Thoughts On The Design Of The Fossil DVCS</title> |
| 2 | -<h1 align="center">Thoughts On The Design Of The Fossil DVCS</h1> | |
| 3 | 2 | |
| 4 | 3 | Two questions (or criticisms) that arise frequently regarding Fossil |
| 5 | 4 | can be summarized as follows: |
| 6 | 5 | |
| 7 | 6 | 1. Why is Fossil based on SQLite instead of a distributed NoSQL database? |
| 8 | 7 |
| --- www/theory1.wiki | |
| +++ www/theory1.wiki | |
| @@ -1,7 +1,6 @@ | |
| 1 | <title>Thoughts On The Design Of The Fossil DVCS</title> |
| 2 | <h1 align="center">Thoughts On The Design Of The Fossil DVCS</h1> |
| 3 | |
| 4 | Two questions (or criticisms) that arise frequently regarding Fossil |
| 5 | can be summarized as follows: |
| 6 | |
| 7 | 1. Why is Fossil based on SQLite instead of a distributed NoSQL database? |
| 8 |
| --- www/theory1.wiki | |
| +++ www/theory1.wiki | |
| @@ -1,7 +1,6 @@ | |
| 1 | <title>Thoughts On The Design Of The Fossil DVCS</title> |
| 2 | |
| 3 | Two questions (or criticisms) that arise frequently regarding Fossil |
| 4 | can be summarized as follows: |
| 5 | |
| 6 | 1. Why is Fossil based on SQLite instead of a distributed NoSQL database? |
| 7 |
+2
-2
| --- www/tickets.wiki | ||
| +++ www/tickets.wiki | ||
| @@ -47,11 +47,11 @@ | ||
| 47 | 47 | |
| 48 | 48 | The two ticket tables are called TICKET and TICKETCHNG. |
| 49 | 49 | The default schema (as of this writing) for these two tables is shown |
| 50 | 50 | below: |
| 51 | 51 | |
| 52 | -<blockquote><verbatim> | |
| 52 | +<verbatim> | |
| 53 | 53 | CREATE TABLE ticket( |
| 54 | 54 | -- Do not change any column that begins with tkt_ |
| 55 | 55 | tkt_id INTEGER PRIMARY KEY, |
| 56 | 56 | tkt_uuid TEXT UNIQUE, |
| 57 | 57 | tkt_mtime DATE, |
| @@ -78,11 +78,11 @@ | ||
| 78 | 78 | username TEXT, |
| 79 | 79 | mimetype TEXT, |
| 80 | 80 | icomment TEXT |
| 81 | 81 | ); |
| 82 | 82 | CREATE INDEX ticketchng_idx1 ON ticketchng(tkt_id, tkt_mtime); |
| 83 | -</verbatim></blockquote> | |
| 83 | +</verbatim> | |
| 84 | 84 | |
| 85 | 85 | Generally speaking, there is one row in the TICKETCHNG table for each |
| 86 | 86 | change to each ticket. In other words, there is one row in the |
| 87 | 87 | TICKETCHNG table for each low-level ticket change artifact. The |
| 88 | 88 | TICKET table, on the other hand, contains a summary of the current |
| 89 | 89 |
| --- www/tickets.wiki | |
| +++ www/tickets.wiki | |
| @@ -47,11 +47,11 @@ | |
| 47 | |
| 48 | The two ticket tables are called TICKET and TICKETCHNG. |
| 49 | The default schema (as of this writing) for these two tables is shown |
| 50 | below: |
| 51 | |
| 52 | <blockquote><verbatim> |
| 53 | CREATE TABLE ticket( |
| 54 | -- Do not change any column that begins with tkt_ |
| 55 | tkt_id INTEGER PRIMARY KEY, |
| 56 | tkt_uuid TEXT UNIQUE, |
| 57 | tkt_mtime DATE, |
| @@ -78,11 +78,11 @@ | |
| 78 | username TEXT, |
| 79 | mimetype TEXT, |
| 80 | icomment TEXT |
| 81 | ); |
| 82 | CREATE INDEX ticketchng_idx1 ON ticketchng(tkt_id, tkt_mtime); |
| 83 | </verbatim></blockquote> |
| 84 | |
| 85 | Generally speaking, there is one row in the TICKETCHNG table for each |
| 86 | change to each ticket. In other words, there is one row in the |
| 87 | TICKETCHNG table for each low-level ticket change artifact. The |
| 88 | TICKET table, on the other hand, contains a summary of the current |
| 89 |
| --- www/tickets.wiki | |
| +++ www/tickets.wiki | |
| @@ -47,11 +47,11 @@ | |
| 47 | |
| 48 | The two ticket tables are called TICKET and TICKETCHNG. |
| 49 | The default schema (as of this writing) for these two tables is shown |
| 50 | below: |
| 51 | |
| 52 | <verbatim> |
| 53 | CREATE TABLE ticket( |
| 54 | -- Do not change any column that begins with tkt_ |
| 55 | tkt_id INTEGER PRIMARY KEY, |
| 56 | tkt_uuid TEXT UNIQUE, |
| 57 | tkt_mtime DATE, |
| @@ -78,11 +78,11 @@ | |
| 78 | username TEXT, |
| 79 | mimetype TEXT, |
| 80 | icomment TEXT |
| 81 | ); |
| 82 | CREATE INDEX ticketchng_idx1 ON ticketchng(tkt_id, tkt_mtime); |
| 83 | </verbatim> |
| 84 | |
| 85 | Generally speaking, there is one row in the TICKETCHNG table for each |
| 86 | change to each ticket. In other words, there is one row in the |
| 87 | TICKETCHNG table for each low-level ticket change artifact. The |
| 88 | TICKET table, on the other hand, contains a summary of the current |
| 89 |
+6
-7
| --- www/unvers.wiki | ||
| +++ www/unvers.wiki | ||
| @@ -1,7 +1,6 @@ | ||
| 1 | 1 | <title>Unversioned Content</title> |
| 2 | -<h1 align="center">Unversioned Content</h1> | |
| 3 | 2 | |
| 4 | 3 | "Unversioned content" or "unversioned files" are |
| 5 | 4 | files stored in a Fossil repository without history, meaning |
| 6 | 5 | it retains the newest version of each such file, and that alone. |
| 7 | 6 | |
| @@ -34,15 +33,15 @@ | ||
| 34 | 33 | <h2>Syncing Unversioned Files</h2> |
| 35 | 34 | |
| 36 | 35 | Unversioned content does not sync between repositories by default. |
| 37 | 36 | One must request it via commands such as: |
| 38 | 37 | |
| 39 | -<blockquote><pre> | |
| 38 | +<pre> | |
| 40 | 39 | fossil sync <b>-u</b> |
| 41 | 40 | fossil clone <b>-u</b> <i>URL local-repo-name</i> |
| 42 | 41 | fossil unversioned sync |
| 43 | -</pre></blockquote> | |
| 42 | +</pre> | |
| 44 | 43 | |
| 45 | 44 | The [/help?cmd=sync|fossil sync] and [/help?cmd=clone|fossil clone] |
| 46 | 45 | commands will synchronize unversioned content if and only if they're |
| 47 | 46 | given the "-u" (or "--unversioned") command-line option. The |
| 48 | 47 | [/help?cmd=unversioned|fossil unversioned sync] command synchronizes the |
| @@ -72,11 +71,11 @@ | ||
| 72 | 71 | files. This is not an interface spec and hence subject to change.)</i> |
| 73 | 72 | |
| 74 | 73 | Unversioned content is stored in the repository in the |
| 75 | 74 | "unversioned" table: |
| 76 | 75 | |
| 77 | -<blockquote><pre> | |
| 76 | +<pre> | |
| 78 | 77 | CREATE TABLE unversioned( |
| 79 | 78 | uvid INTEGER PRIMARY KEY AUTOINCREMENT, -- unique ID for this file |
| 80 | 79 | name TEXT UNIQUE, -- Name of the file |
| 81 | 80 | rcvid INTEGER, -- From whence this file was received |
| 82 | 81 | mtime DATETIME, -- Last change (seconds since 1970) |
| @@ -83,21 +82,21 @@ | ||
| 83 | 82 | hash TEXT, -- SHA1 or SHA3-256 hash of uncompressed content |
| 84 | 83 | sz INTEGER, -- Size of uncompressed content |
| 85 | 84 | encoding INT, -- 0: plaintext 1: zlib compressed |
| 86 | 85 | content BLOB -- File content |
| 87 | 86 | ); |
| 88 | -</pre></blockquote> | |
| 87 | +</pre> | |
| 89 | 88 | |
| 90 | 89 | Fossil does not create the table ahead of need. |
| 91 | 90 | If there are no unversioned files in the repository, the |
| 92 | 91 | "unversioned" table will not exist. Consequently, |
| 93 | 92 | one simple way to purge all unversioned content from a repository |
| 94 | 93 | is to run: |
| 95 | 94 | |
| 96 | -<blockquote><pre> | |
| 95 | +<pre> | |
| 97 | 96 | fossil sql "DROP TABLE unversioned; VACUUM;" |
| 98 | -</pre></blockquote> | |
| 97 | +</pre> | |
| 99 | 98 | |
| 100 | 99 | Lacking history for unversioned files, Fossil does not attempt delta |
| 101 | 100 | compression on them. |
| 102 | 101 | |
| 103 | 102 | Fossil servers exchange unversioned content whole; it does not attempt |
| 104 | 103 |
| --- www/unvers.wiki | |
| +++ www/unvers.wiki | |
| @@ -1,7 +1,6 @@ | |
| 1 | <title>Unversioned Content</title> |
| 2 | <h1 align="center">Unversioned Content</h1> |
| 3 | |
| 4 | "Unversioned content" or "unversioned files" are |
| 5 | files stored in a Fossil repository without history, meaning |
| 6 | it retains the newest version of each such file, and that alone. |
| 7 | |
| @@ -34,15 +33,15 @@ | |
| 34 | <h2>Syncing Unversioned Files</h2> |
| 35 | |
| 36 | Unversioned content does not sync between repositories by default. |
| 37 | One must request it via commands such as: |
| 38 | |
| 39 | <blockquote><pre> |
| 40 | fossil sync <b>-u</b> |
| 41 | fossil clone <b>-u</b> <i>URL local-repo-name</i> |
| 42 | fossil unversioned sync |
| 43 | </pre></blockquote> |
| 44 | |
| 45 | The [/help?cmd=sync|fossil sync] and [/help?cmd=clone|fossil clone] |
| 46 | commands will synchronize unversioned content if and only if they're |
| 47 | given the "-u" (or "--unversioned") command-line option. The |
| 48 | [/help?cmd=unversioned|fossil unversioned sync] command synchronizes the |
| @@ -72,11 +71,11 @@ | |
| 72 | files. This is not an interface spec and hence subject to change.)</i> |
| 73 | |
| 74 | Unversioned content is stored in the repository in the |
| 75 | "unversioned" table: |
| 76 | |
| 77 | <blockquote><pre> |
| 78 | CREATE TABLE unversioned( |
| 79 | uvid INTEGER PRIMARY KEY AUTOINCREMENT, -- unique ID for this file |
| 80 | name TEXT UNIQUE, -- Name of the file |
| 81 | rcvid INTEGER, -- From whence this file was received |
| 82 | mtime DATETIME, -- Last change (seconds since 1970) |
| @@ -83,21 +82,21 @@ | |
| 83 | hash TEXT, -- SHA1 or SHA3-256 hash of uncompressed content |
| 84 | sz INTEGER, -- Size of uncompressed content |
| 85 | encoding INT, -- 0: plaintext 1: zlib compressed |
| 86 | content BLOB -- File content |
| 87 | ); |
| 88 | </pre></blockquote> |
| 89 | |
| 90 | Fossil does not create the table ahead of need. |
| 91 | If there are no unversioned files in the repository, the |
| 92 | "unversioned" table will not exist. Consequently, |
| 93 | one simple way to purge all unversioned content from a repository |
| 94 | is to run: |
| 95 | |
| 96 | <blockquote><pre> |
| 97 | fossil sql "DROP TABLE unversioned; VACUUM;" |
| 98 | </pre></blockquote> |
| 99 | |
| 100 | Lacking history for unversioned files, Fossil does not attempt delta |
| 101 | compression on them. |
| 102 | |
| 103 | Fossil servers exchange unversioned content whole; it does not attempt |
| 104 |
| --- www/unvers.wiki | |
| +++ www/unvers.wiki | |
| @@ -1,7 +1,6 @@ | |
| 1 | <title>Unversioned Content</title> |
| 2 | |
| 3 | "Unversioned content" or "unversioned files" are |
| 4 | files stored in a Fossil repository without history, meaning |
| 5 | it retains the newest version of each such file, and that alone. |
| 6 | |
| @@ -34,15 +33,15 @@ | |
| 33 | <h2>Syncing Unversioned Files</h2> |
| 34 | |
| 35 | Unversioned content does not sync between repositories by default. |
| 36 | One must request it via commands such as: |
| 37 | |
| 38 | <pre> |
| 39 | fossil sync <b>-u</b> |
| 40 | fossil clone <b>-u</b> <i>URL local-repo-name</i> |
| 41 | fossil unversioned sync |
| 42 | </pre> |
| 43 | |
| 44 | The [/help?cmd=sync|fossil sync] and [/help?cmd=clone|fossil clone] |
| 45 | commands will synchronize unversioned content if and only if they're |
| 46 | given the "-u" (or "--unversioned") command-line option. The |
| 47 | [/help?cmd=unversioned|fossil unversioned sync] command synchronizes the |
| @@ -72,11 +71,11 @@ | |
| 71 | files. This is not an interface spec and hence subject to change.)</i> |
| 72 | |
| 73 | Unversioned content is stored in the repository in the |
| 74 | "unversioned" table: |
| 75 | |
| 76 | <pre> |
| 77 | CREATE TABLE unversioned( |
| 78 | uvid INTEGER PRIMARY KEY AUTOINCREMENT, -- unique ID for this file |
| 79 | name TEXT UNIQUE, -- Name of the file |
| 80 | rcvid INTEGER, -- From whence this file was received |
| 81 | mtime DATETIME, -- Last change (seconds since 1970) |
| @@ -83,21 +82,21 @@ | |
| 82 | hash TEXT, -- SHA1 or SHA3-256 hash of uncompressed content |
| 83 | sz INTEGER, -- Size of uncompressed content |
| 84 | encoding INT, -- 0: plaintext 1: zlib compressed |
| 85 | content BLOB -- File content |
| 86 | ); |
| 87 | </pre> |
| 88 | |
| 89 | Fossil does not create the table ahead of need. |
| 90 | If there are no unversioned files in the repository, the |
| 91 | "unversioned" table will not exist. Consequently, |
| 92 | one simple way to purge all unversioned content from a repository |
| 93 | is to run: |
| 94 | |
| 95 | <pre> |
| 96 | fossil sql "DROP TABLE unversioned; VACUUM;" |
| 97 | </pre> |
| 98 | |
| 99 | Lacking history for unversioned files, Fossil does not attempt delta |
| 100 | compression on them. |
| 101 | |
| 102 | Fossil servers exchange unversioned content whole; it does not attempt |
| 103 |
+8
-12
| --- www/webui.wiki | ||
| +++ www/webui.wiki | ||
| @@ -32,14 +32,14 @@ | ||
| 32 | 32 | the entire [./index.wiki | Fossil website], |
| 33 | 33 | including the document you are now reading, |
| 34 | 34 | is rendered using the Fossil web interface, with no enhancements, |
| 35 | 35 | and little customization. |
| 36 | 36 | |
| 37 | -<blockquote> | |
| 37 | +<p class="indent"> | |
| 38 | 38 | <b>Key point:</b> <i>The Fossil website is just a running instance |
| 39 | 39 | of Fossil! |
| 40 | -</blockquote> | |
| 40 | +</p> | |
| 41 | 41 | |
| 42 | 42 | Note also that because Fossil is a distributed system, you can run |
| 43 | 43 | the web interface on your local machine while off network (for example, |
| 44 | 44 | while on an airplane) including |
| 45 | 45 | making changes to wiki pages and/or trouble ticket, then synchronize with your |
| @@ -50,19 +50,19 @@ | ||
| 50 | 50 | <h2>Very Simple Startup</h2> |
| 51 | 51 | |
| 52 | 52 | To start using the built-in Fossil web interface on an existing Fossil |
| 53 | 53 | repository, simply type this: |
| 54 | 54 | |
| 55 | - <b>fossil ui existing-repository.fossil</b> | |
| 55 | +<pre>fossil ui existing-repository.fossil</pre> | |
| 56 | 56 | |
| 57 | 57 | Substitute the name of your repository, of course. |
| 58 | 58 | The "ui" command will start a web server running (it figures out an |
| 59 | 59 | available TCP port to use on its own) and then automatically launches |
| 60 | 60 | your web browser to point at that server. If you run the "ui" command |
| 61 | 61 | from within an open check-out, you can omit the repository name: |
| 62 | 62 | |
| 63 | - <b>fossil ui</b> | |
| 63 | +<pre>fossil ui</pre> | |
| 64 | 64 | |
| 65 | 65 | The latter case is a very useful short-cut when you are working on a |
| 66 | 66 | Fossil project and you want to quickly do some work with the web interface. |
| 67 | 67 | Notice that Fossil automatically finds an unused TCP port to run the |
| 68 | 68 | server on and automatically points your web browser to the correct |
| @@ -153,14 +153,12 @@ | ||
| 153 | 153 | run Fossil as CGI, just put the |
| 154 | 154 | <b>sample-project.fossil</b> file in a directory where CGI scripts |
| 155 | 155 | have both read and write permission on the file and the directory that |
| 156 | 156 | contains the file, then add a CGI script that looks something like this: |
| 157 | 157 | |
| 158 | - <verbatim> | |
| 159 | - #!/usr/local/bin/fossil | |
| 160 | - repository: /home/www/sample-project.fossil | |
| 161 | - </verbatim> | |
| 158 | +<verbatim> #!/usr/local/bin/fossil | |
| 159 | + repository: /home/www/sample-project.fossil</verbatim> | |
| 162 | 160 | |
| 163 | 161 | Adjust the script above so that the paths are correct for your system, |
| 164 | 162 | of course, and also make sure the Fossil binary is installed on the server. |
| 165 | 163 | But that is <u>all</u> you have to do. You now have everything you need to host |
| 166 | 164 | a distributed software development project in less than five minutes using a |
| @@ -173,13 +171,11 @@ | ||
| 173 | 171 | server machine? |
| 174 | 172 | Not a problem. The Fossil interface can also be launched via inetd or |
| 175 | 173 | xinetd. An inetd configuration line sufficient to launch the Fossil |
| 176 | 174 | web interface looks like this: |
| 177 | 175 | |
| 178 | - <verbatim> | |
| 179 | - 80 stream tcp nowait.1000 root /usr/local/bin/fossil \ | |
| 180 | - /usr/local/bin/fossil http /home/www/sample-project.fossil | |
| 181 | - </verbatim> | |
| 176 | +<verbatim> 80 stream tcp nowait.1000 root /usr/local/bin/fossil \ | |
| 177 | + /usr/local/bin/fossil http /home/www/sample-project.fossil</verbatim> | |
| 182 | 178 | |
| 183 | 179 | As always, you'll want to adjust the pathnames to whatever is appropriate |
| 184 | 180 | for your system. The xinetd setup uses a different syntax but follows |
| 185 | 181 | the same idea. |
| 186 | 182 |
| --- www/webui.wiki | |
| +++ www/webui.wiki | |
| @@ -32,14 +32,14 @@ | |
| 32 | the entire [./index.wiki | Fossil website], |
| 33 | including the document you are now reading, |
| 34 | is rendered using the Fossil web interface, with no enhancements, |
| 35 | and little customization. |
| 36 | |
| 37 | <blockquote> |
| 38 | <b>Key point:</b> <i>The Fossil website is just a running instance |
| 39 | of Fossil! |
| 40 | </blockquote> |
| 41 | |
| 42 | Note also that because Fossil is a distributed system, you can run |
| 43 | the web interface on your local machine while off network (for example, |
| 44 | while on an airplane) including |
| 45 | making changes to wiki pages and/or trouble ticket, then synchronize with your |
| @@ -50,19 +50,19 @@ | |
| 50 | <h2>Very Simple Startup</h2> |
| 51 | |
| 52 | To start using the built-in Fossil web interface on an existing Fossil |
| 53 | repository, simply type this: |
| 54 | |
| 55 | <b>fossil ui existing-repository.fossil</b> |
| 56 | |
| 57 | Substitute the name of your repository, of course. |
| 58 | The "ui" command will start a web server running (it figures out an |
| 59 | available TCP port to use on its own) and then automatically launches |
| 60 | your web browser to point at that server. If you run the "ui" command |
| 61 | from within an open check-out, you can omit the repository name: |
| 62 | |
| 63 | <b>fossil ui</b> |
| 64 | |
| 65 | The latter case is a very useful short-cut when you are working on a |
| 66 | Fossil project and you want to quickly do some work with the web interface. |
| 67 | Notice that Fossil automatically finds an unused TCP port to run the |
| 68 | server on and automatically points your web browser to the correct |
| @@ -153,14 +153,12 @@ | |
| 153 | run Fossil as CGI, just put the |
| 154 | <b>sample-project.fossil</b> file in a directory where CGI scripts |
| 155 | have both read and write permission on the file and the directory that |
| 156 | contains the file, then add a CGI script that looks something like this: |
| 157 | |
| 158 | <verbatim> |
| 159 | #!/usr/local/bin/fossil |
| 160 | repository: /home/www/sample-project.fossil |
| 161 | </verbatim> |
| 162 | |
| 163 | Adjust the script above so that the paths are correct for your system, |
| 164 | of course, and also make sure the Fossil binary is installed on the server. |
| 165 | But that is <u>all</u> you have to do. You now have everything you need to host |
| 166 | a distributed software development project in less than five minutes using a |
| @@ -173,13 +171,11 @@ | |
| 173 | server machine? |
| 174 | Not a problem. The Fossil interface can also be launched via inetd or |
| 175 | xinetd. An inetd configuration line sufficient to launch the Fossil |
| 176 | web interface looks like this: |
| 177 | |
| 178 | <verbatim> |
| 179 | 80 stream tcp nowait.1000 root /usr/local/bin/fossil \ |
| 180 | /usr/local/bin/fossil http /home/www/sample-project.fossil |
| 181 | </verbatim> |
| 182 | |
| 183 | As always, you'll want to adjust the pathnames to whatever is appropriate |
| 184 | for your system. The xinetd setup uses a different syntax but follows |
| 185 | the same idea. |
| 186 |
| --- www/webui.wiki | |
| +++ www/webui.wiki | |
| @@ -32,14 +32,14 @@ | |
| 32 | the entire [./index.wiki | Fossil website], |
| 33 | including the document you are now reading, |
| 34 | is rendered using the Fossil web interface, with no enhancements, |
| 35 | and little customization. |
| 36 | |
| 37 | <p class="indent"> |
| 38 | <b>Key point:</b> <i>The Fossil website is just a running instance |
| 39 | of Fossil! |
| 40 | </p> |
| 41 | |
| 42 | Note also that because Fossil is a distributed system, you can run |
| 43 | the web interface on your local machine while off network (for example, |
| 44 | while on an airplane) including |
| 45 | making changes to wiki pages and/or trouble ticket, then synchronize with your |
| @@ -50,19 +50,19 @@ | |
| 50 | <h2>Very Simple Startup</h2> |
| 51 | |
| 52 | To start using the built-in Fossil web interface on an existing Fossil |
| 53 | repository, simply type this: |
| 54 | |
| 55 | <pre>fossil ui existing-repository.fossil</pre> |
| 56 | |
| 57 | Substitute the name of your repository, of course. |
| 58 | The "ui" command will start a web server running (it figures out an |
| 59 | available TCP port to use on its own) and then automatically launches |
| 60 | your web browser to point at that server. If you run the "ui" command |
| 61 | from within an open check-out, you can omit the repository name: |
| 62 | |
| 63 | <pre>fossil ui</pre> |
| 64 | |
| 65 | The latter case is a very useful short-cut when you are working on a |
| 66 | Fossil project and you want to quickly do some work with the web interface. |
| 67 | Notice that Fossil automatically finds an unused TCP port to run the |
| 68 | server on and automatically points your web browser to the correct |
| @@ -153,14 +153,12 @@ | |
| 153 | run Fossil as CGI, just put the |
| 154 | <b>sample-project.fossil</b> file in a directory where CGI scripts |
| 155 | have both read and write permission on the file and the directory that |
| 156 | contains the file, then add a CGI script that looks something like this: |
| 157 | |
| 158 | <verbatim> #!/usr/local/bin/fossil |
| 159 | repository: /home/www/sample-project.fossil</verbatim> |
| 160 | |
| 161 | Adjust the script above so that the paths are correct for your system, |
| 162 | of course, and also make sure the Fossil binary is installed on the server. |
| 163 | But that is <u>all</u> you have to do. You now have everything you need to host |
| 164 | a distributed software development project in less than five minutes using a |
| @@ -173,13 +171,11 @@ | |
| 171 | server machine? |
| 172 | Not a problem. The Fossil interface can also be launched via inetd or |
| 173 | xinetd. An inetd configuration line sufficient to launch the Fossil |
| 174 | web interface looks like this: |
| 175 | |
| 176 | <verbatim> 80 stream tcp nowait.1000 root /usr/local/bin/fossil \ |
| 177 | /usr/local/bin/fossil http /home/www/sample-project.fossil</verbatim> |
| 178 | |
| 179 | As always, you'll want to adjust the pathnames to whatever is appropriate |
| 180 | for your system. The xinetd setup uses a different syntax but follows |
| 181 | the same idea. |
| 182 |