Fossil SCM
Incremental check-in. Now up to 82 reasons. 19 more to go.
Commit
ff819b5ec8f555ed8c04706620c1cf3c6c7159f0b2537169a671e919be76b635
Parent
f023bca98209d0b…
1 file changed
+221
-2
+221
-2
| --- www/hundredandone.md | ||
| +++ www/hundredandone.md | ||
| @@ -1,8 +1,8 @@ | ||
| 1 | 1 | # 101 Reasons Why Fossil Is Better Than Git |
| 2 | 2 | |
| 3 | -*This is a work in progress. Only 60 reasons have been typed in so far, | |
| 3 | +*This is a work in progress. Only 82 reasons have been typed in so far, | |
| 4 | 4 | but I have a separate text file of notes that lists 104 candidate reasons. |
| 5 | 5 | It's just taking me a while to compose and edit the rationale for each |
| 6 | 6 | one, and to arrange the reasons in a sensible order. I will merge this |
| 7 | 7 | document from its current branch onto trunk when it gets closer to being |
| 8 | 8 | ready to publish.* |
| @@ -141,10 +141,27 @@ | ||
| 141 | 141 | on column headers to sort by that column.<p> |
| 142 | 142 | If you are like me and have hundreds of repositories on your desktop |
| 143 | 143 | system, this feature makes it easier to keep track of them all. |
| 144 | 144 | Are you on an infrequently used travel laptop and forgot where you |
| 145 | 145 | put a particular repository, this feature helps you find it. |
| 146 | + | |
| 147 | + 1. **Fossil lets you quickly find all of your local checkouts that have | |
| 148 | + uncommitted changes.**<p> | |
| 149 | + Simply run "<tt>fossil all changes</tt>" to get a quick | |
| 150 | + summary of every checkout on your local machine that needs a commit. | |
| 151 | + | |
| 152 | + 1. **Fossil lets you sync all of the changes in all of your local | |
| 153 | + repositories to their remotes, with a single command.**<p> | |
| 154 | + Run "<tt>fossil all sync</tt>" and all your local | |
| 155 | + repositories will sync up. This is useful, for example when | |
| 156 | + taking a laptop off-network. Before disconnecting, you sync | |
| 157 | + all of your repositories (I typically have about a hundred) | |
| 158 | + with a single command, so there is no chance that you forget | |
| 159 | + one. While off-network, you might commit changes to one or | |
| 160 | + more of those repositories. Once you reconnect, you simply | |
| 161 | + run "fossil all sync" again to push out your edits to the | |
| 162 | + rest of the community. | |
| 146 | 163 | |
| 147 | 164 | 1. **Fossil allows multiple checkins to have the same tag.**<p> |
| 148 | 165 | For example, on the SQLite project, every release is tagged with |
| 149 | 166 | "release". |
| 150 | 167 | |
| @@ -341,10 +358,38 @@ | ||
| 341 | 358 | 1. **The Fossil web interface supports "embedded documentation"**</p> |
| 342 | 359 | See the [Project Documentation](/doc/trunk/www/embeddeddoc.wiki) page |
| 343 | 360 | for details. Markdown, Wiki, plain-text, and HTML files in the |
| 344 | 361 | source tree can be rendered and used as documentation pages. This |
| 345 | 362 | is how all of the documentation files for Fossil itself are rendered. |
| 363 | + | |
| 364 | + 1. **Fossil can easily host an entire project website, using only the | |
| 365 | + repository as the backing store.**<p> | |
| 366 | + The embedded documentation and wiki features allow you to write | |
| 367 | + web pages. The unversioned file feature gives you space to put of | |
| 368 | + precompiled binaries or other transient and/or derived resources | |
| 369 | + without contaminating the source tree. Indeed, the | |
| 370 | + [canonical Fossil website](https://fossil-scm.org/home) is just | |
| 371 | + an instance of Fossil running on the self-hosting Fossil repository. | |
| 372 | + If you clone the Fossil self-hosting repository, you don't get just | |
| 373 | + code - you get the entire website. (Exception: | |
| 374 | + [Fossil Forum](https://sqlite.org/forum) is hosted separately using | |
| 375 | + a separate Fossil repository, so you'd actually need to clone that | |
| 376 | + one too, in order to get the whole website.) | |
| 377 | + | |
| 378 | + 1. **Using Fossil, backing up your project website is just a sync.**<p> | |
| 379 | + If you do host your entire project website in a Fossil repository, | |
| 380 | + as Fossil itself does, then backing up that website is as simple | |
| 381 | + as creating a clone and keeping the clone synced. | |
| 382 | + | |
| 383 | + 1. **Fossil will render uncommitted changes to embedded documentation.** | |
| 384 | + <p> | |
| 385 | + Using the "<tt>fossil ui</tt>", if in for the | |
| 386 | + [/doc/VERSION/FILE](/help/www/doc) webpage, if the VERSION is the | |
| 387 | + special keyword "ckout", then the content is taken from the local | |
| 388 | + checkout not from the repository. This allows you to edit embedded | |
| 389 | + documentation files and then see how they look and work on the | |
| 390 | + actual website without having to commit. | |
| 346 | 391 | |
| 347 | 392 | 1. **Fossil has a wiki sandbox for experimenting with markup.**</p> |
| 348 | 393 | The [wiki sandbox](/wikiedit?name=Sandbox) allows users to experiment |
| 349 | 394 | with Markdown or other text markup languages supported by Fossil, |
| 350 | 395 | without making permanent changes to the repository. |
| @@ -609,11 +654,10 @@ | ||
| 609 | 654 | fossil patch pull @ -f</pre> |
| 610 | 655 | (Aside: the -f option tells the command to first "revert" any |
| 611 | 656 | uncommitted changes prior currently in the checkout prior to pulling |
| 612 | 657 | over the new ones from r21:sqlite/sqlite. Without that option, the |
| 613 | 658 | changes would be merged.) |
| 614 | - | |
| 615 | 659 | |
| 616 | 660 | 1. **Fossil allows you view uncommitted changes on a remote machine |
| 617 | 661 | in a web browser over SSH.**<p> |
| 618 | 662 | Suppose you have some edits on a remote, headless machine and you |
| 619 | 663 | would like to review those changes. Fossil lets you see those |
| @@ -643,5 +687,180 @@ | ||
| 643 | 687 | It causes Fossil to consult the $HOME/.config/fossil.db file |
| 644 | 688 | (or %LOCALAPPDATA%/_fossil on Windows) to find the locations of all |
| 645 | 689 | repositories on the remote machine, then bring up a web page listing |
| 646 | 690 | all those repositories. Links on that initial page let you explore |
| 647 | 691 | deeper into the details of each repository. |
| 692 | + | |
| 693 | + 1. **The Fossil web interface supports multiple timeline formats, to | |
| 694 | + accommodate personal tastes.**<p> | |
| 695 | + The different formats are called "Views". The current repertiore | |
| 696 | + includes "Modern", "Columnar", "Compact", "Simple", "Verbose", and | |
| 697 | + "Classic". Users can select whichever format they want and their | |
| 698 | + preference is remembered in a cookie. | |
| 699 | + | |
| 700 | + 1. **A Fossil web server admin can set the default timeline format.**<p> | |
| 701 | + Individual users have a lot of control over what their own timeline | |
| 702 | + displays look like, but the repository administrator can set the | |
| 703 | + default separately for each repository. | |
| 704 | + | |
| 705 | + 1. **Fossil is open and transparent about the cookies that it uses.**<p> | |
| 706 | + There are really only two: The login cookie (if you are logged in) | |
| 707 | + and the display preferences cookie. If you visit the | |
| 708 | + [/cookies page](/cookies), Fossil will | |
| 709 | + show you all the cookies it use and it will decode them for you to | |
| 710 | + show you exactly what they mean and what information they are holding | |
| 711 | + and give you an opportunity to delete them individually. | |
| 712 | + | |
| 713 | + 1. **The Fossil web interface comes with a variety of "skins" built in.**<p> | |
| 714 | + Visit the [/skins page](/skins) to see all the available skins and | |
| 715 | + which one is currently in use. | |
| 716 | + | |
| 717 | + 1. **Individual users get to choose their favorite Fossil skin.**<p> | |
| 718 | + The repository administrator sets the default skin, but if | |
| 719 | + individual users do not like that choice, they can select a different | |
| 720 | + skin and their choice is recorded in the display preferences cookie. | |
| 721 | + | |
| 722 | + 1. **Repository administators can create new custom skins.**<p> | |
| 723 | + The current library of skins are most derived from custom skins that | |
| 724 | + users of Fossil have created over the years and generously donated | |
| 725 | + to the project. If none of the default skins work for you, you can | |
| 726 | + create your own, perhaps using one of the existing skins as a template. | |
| 727 | + | |
| 728 | + 1. **Most Fossil web-interface skins include a hamburger (☰) menu.**<p> | |
| 729 | + Clicking on the hamburger menu brings up a dropdown "site-map" | |
| 730 | + page that lets you quickly navigate to the information you want. | |
| 731 | + (Note: The presence an operation of the hamburger menu is a | |
| 732 | + skin-specific feature and might not be present on every skin, but | |
| 733 | + it is used on the more popular skins.) Curiously, none of GitHub, | |
| 734 | + GitLab, Gitea, nor Forgejo have a hamburger menu, which in my | |
| 735 | + experience makes sites based on those systems much harder to | |
| 736 | + navigate. | |
| 737 | + | |
| 738 | + 1. **The Fossil web interface /sitemap page is responsive to | |
| 739 | + individual user permissions and capabilities.**<p> | |
| 740 | + Each user on the Fossil web interface, including the special | |
| 741 | + user "nobody" used if no login is attempted, has rich collection | |
| 742 | + of "capabilities" assigned by the repository administrator. | |
| 743 | + Depending on capabilities, some pages will display different or | |
| 744 | + will not display at all. Pages that a user does not have access | |
| 745 | + to are automatically omitted from the [/sitemap page](/sitemap). | |
| 746 | + | |
| 747 | + 1. **The Fossil web interface allows "anonymous" users.**<p> | |
| 748 | + The "anonymous" user is a human (we think, because he has solved | |
| 749 | + a captcha) but we do not know who. User who do not want to | |
| 750 | + identify themselves but who also don't want to be mistaken for | |
| 751 | + a spider or robot can log in as anonymous. | |
| 752 | + <p> | |
| 753 | + The repository administrator has complete control over the capabilities | |
| 754 | + of anonymous. Anonymous can be completely banned, or maybe given | |
| 755 | + read-only capabilities, or given complete access, with lots of shade | |
| 756 | + in between, according to the needs of the project. | |
| 757 | + <p> | |
| 758 | + The "anonymous" user is distinct from user "nobody" in that we | |
| 759 | + believe anonymous is a real human, whereas user nobody is presumed | |
| 760 | + to be a robot. The repository administrator also has complete control | |
| 761 | + over the capabilities for user "nobody". | |
| 762 | + | |
| 763 | + 1. **The Fossil web interface has lots of built-in defenses against | |
| 764 | + abuse by spiders and robots.**<p> | |
| 765 | + Sadly, the internet is rapidly devolving such that most HTTP requests | |
| 766 | + now come from AI spiders trying to find training content, and/or robots | |
| 767 | + looking for website vulnerabilities. The flood of requests can | |
| 768 | + rapidly bog down an undefended server. Fossil includes a range of | |
| 769 | + defenses against aggressive bots that help keep the server load and | |
| 770 | + hence ISP costs down while still providing fast and detailed responses | |
| 771 | + to real humans. This is an on-going battle. But Fossil is, at least, | |
| 772 | + in the fight. Everything is easily configurable, via the web interface, | |
| 773 | + by repository administrators. | |
| 774 | + | |
| 775 | + 1. **The Fossil web interface includes a "security audit" page accessible | |
| 776 | + to repositoriy administrators.**<p> | |
| 777 | + The security-audit pages give a succinct summary of how a repository | |
| 778 | + web interface is configured, with an eye toward operational security. | |
| 779 | + As with any full-featured web application, the Fossil web interface | |
| 780 | + as a large number of settings. A common worry amoung system | |
| 781 | + administrators is overlooking or omitting or misconfiguring some | |
| 782 | + security-sensitive setting. The security-audit page is designed to | |
| 783 | + assuage that worry. | |
| 784 | + <p> | |
| 785 | + The security-audit shows at a glance how a repository web interface | |
| 786 | + is set up, and raises alerts about any settings that are questionable | |
| 787 | + or that might facilitate mischief. The page fits on a single screen | |
| 788 | + with minimal or no scrolling. After standing up a new Fossil server, | |
| 789 | + a quick glance at the security-audit page (accessible only to | |
| 790 | + administrators) gives peace of mind that all is well and that nothing | |
| 791 | + was overlooked. | |
| 792 | + | |
| 793 | + 1. **The Fossil web interface menu bar can be customized.**<p> | |
| 794 | + Repository administrators can customize the menu bar on the web | |
| 795 | + interface. Individual items can be added or omitted from the | |
| 796 | + menu bar based on user capabilities and/or whether or not the | |
| 797 | + client is a phone or other narrow-screen mobile devide, a standard | |
| 798 | + desktop browser, or a wide-screen desktop browser. | |
| 799 | + | |
| 800 | + 1. **The Fossil web interface sitemap can be customized.**<p> | |
| 801 | + Repository administrators can add new entries to the | |
| 802 | + [/sitemap](/sitemap) that are shown or omitted | |
| 803 | + based on user capabilities. | |
| 804 | + | |
| 805 | + 1. **The Fossil web interface can be augmented with auxiliary content | |
| 806 | + and/or CGIs that exist outside of the repository.**<p> | |
| 807 | + The auxiliary content or CGI result uses the same theme and skin as | |
| 808 | + the default website, and blends right in. An example of this is | |
| 809 | + the | |
| 810 | + [SQLite Release Checklist](https://sqlite.org/src/ext/checklist/top/index). | |
| 811 | + The SQLite Release Checklist is a CGI that is completely separate from | |
| 812 | + Fossil, but appears to be integrated in the Fossil web interface. | |
| 813 | + It uses the same skin and interface settings. But the content is | |
| 814 | + created by a separate CGI program. Fossil passes down additional | |
| 815 | + CGI variables to tell the CGI what the Fossil user name is and what | |
| 816 | + capabilities that user has, among other things. In the case of the | |
| 817 | + SQLite Release Checklist, those additional settings mean only project | |
| 818 | + committers can make changes to the checklist (such as marking items | |
| 819 | + as "done") and that the checklist is read-only for the general public. | |
| 820 | + <p> | |
| 821 | + Additional information about this advanced feature of Fossil | |
| 822 | + can be seen at <https://fossil-scm.org/home/doc/trunk/www/serverext.wiki>. | |
| 823 | + | |
| 824 | + 1. **Experts can browse low-level details of a Fossil repository | |
| 825 | + using SQL.**<p> | |
| 826 | + A Fossil repository is just an SQLite database file. Low-level content | |
| 827 | + of that database file can be viewed and even changed using ordinary | |
| 828 | + SQL and the "<tt>fossil sql</tt>" command. The "fossil sql" | |
| 829 | + command brings up a standard SQLite command-line shell, already | |
| 830 | + connected to the repository database, and extended to include extra | |
| 831 | + functions (including table-valued functions) to help interpret the | |
| 832 | + low-level content of the repository. This feature is not needed nor | |
| 833 | + recommended for the average user, however, if you want to learn more | |
| 834 | + about the inner workings of Fossil, the SQL interface is a great tool | |
| 835 | + to help you explore. | |
| 836 | + | |
| 837 | + 1. **The underlying artifacts of a Fossil repository are well-documented, | |
| 838 | + human-readable, and human-understandable.**<p> | |
| 839 | + A Fossil repository is an SQLite database file, but not every SQLite | |
| 840 | + database file is a Fossil repository. Fossil repositories store | |
| 841 | + "artifacts" in a very particular format. See | |
| 842 | + <https://fossil-scm.org/home/doc/trunk/www/fileformat.wiki> for | |
| 843 | + the details of that format. | |
| 844 | + <p> | |
| 845 | + This underlying format is text-only. It is designed to be easily | |
| 846 | + parsed and interpreted by programs written in any language. It is | |
| 847 | + designed to be easily understood by humans, even humans not yet born. | |
| 848 | + <p> | |
| 849 | + Many of the low-level artifact formats for Git, in contrast, are | |
| 850 | + binary and are only thinly documented. | |
| 851 | + | |
| 852 | + 1. **The Fossil web interface has a "This Day In History" page.**<p> | |
| 853 | + See that page for [Fossil](/thisdayinhistory) or | |
| 854 | + [SQLite](https://sqlite.org/src/thisdayinhistory). | |
| 855 | + It should multiple timeline snippets for a day that at various | |
| 856 | + points in the past. | |
| 857 | + <p> | |
| 858 | + This is something of a vanity page. It is difficult to describe a | |
| 859 | + real business need for this information. But the page does jog old | |
| 860 | + memories and helps developers keep perspective on how a project has | |
| 861 | + changed through the years. | |
| 862 | + <p> | |
| 863 | + One important aspect of Fossil that this page illustrates due to the | |
| 864 | + rebust and modular design of the Fossil implementation, | |
| 865 | + pages like this can be generated, using very little memory or CPU, | |
| 866 | + and with not very much code. | |
| 648 | 867 |
| --- www/hundredandone.md | |
| +++ www/hundredandone.md | |
| @@ -1,8 +1,8 @@ | |
| 1 | # 101 Reasons Why Fossil Is Better Than Git |
| 2 | |
| 3 | *This is a work in progress. Only 60 reasons have been typed in so far, |
| 4 | but I have a separate text file of notes that lists 104 candidate reasons. |
| 5 | It's just taking me a while to compose and edit the rationale for each |
| 6 | one, and to arrange the reasons in a sensible order. I will merge this |
| 7 | document from its current branch onto trunk when it gets closer to being |
| 8 | ready to publish.* |
| @@ -141,10 +141,27 @@ | |
| 141 | on column headers to sort by that column.<p> |
| 142 | If you are like me and have hundreds of repositories on your desktop |
| 143 | system, this feature makes it easier to keep track of them all. |
| 144 | Are you on an infrequently used travel laptop and forgot where you |
| 145 | put a particular repository, this feature helps you find it. |
| 146 | |
| 147 | 1. **Fossil allows multiple checkins to have the same tag.**<p> |
| 148 | For example, on the SQLite project, every release is tagged with |
| 149 | "release". |
| 150 | |
| @@ -341,10 +358,38 @@ | |
| 341 | 1. **The Fossil web interface supports "embedded documentation"**</p> |
| 342 | See the [Project Documentation](/doc/trunk/www/embeddeddoc.wiki) page |
| 343 | for details. Markdown, Wiki, plain-text, and HTML files in the |
| 344 | source tree can be rendered and used as documentation pages. This |
| 345 | is how all of the documentation files for Fossil itself are rendered. |
| 346 | |
| 347 | 1. **Fossil has a wiki sandbox for experimenting with markup.**</p> |
| 348 | The [wiki sandbox](/wikiedit?name=Sandbox) allows users to experiment |
| 349 | with Markdown or other text markup languages supported by Fossil, |
| 350 | without making permanent changes to the repository. |
| @@ -609,11 +654,10 @@ | |
| 609 | fossil patch pull @ -f</pre> |
| 610 | (Aside: the -f option tells the command to first "revert" any |
| 611 | uncommitted changes prior currently in the checkout prior to pulling |
| 612 | over the new ones from r21:sqlite/sqlite. Without that option, the |
| 613 | changes would be merged.) |
| 614 | |
| 615 | |
| 616 | 1. **Fossil allows you view uncommitted changes on a remote machine |
| 617 | in a web browser over SSH.**<p> |
| 618 | Suppose you have some edits on a remote, headless machine and you |
| 619 | would like to review those changes. Fossil lets you see those |
| @@ -643,5 +687,180 @@ | |
| 643 | It causes Fossil to consult the $HOME/.config/fossil.db file |
| 644 | (or %LOCALAPPDATA%/_fossil on Windows) to find the locations of all |
| 645 | repositories on the remote machine, then bring up a web page listing |
| 646 | all those repositories. Links on that initial page let you explore |
| 647 | deeper into the details of each repository. |
| 648 |
| --- www/hundredandone.md | |
| +++ www/hundredandone.md | |
| @@ -1,8 +1,8 @@ | |
| 1 | # 101 Reasons Why Fossil Is Better Than Git |
| 2 | |
| 3 | *This is a work in progress. Only 82 reasons have been typed in so far, |
| 4 | but I have a separate text file of notes that lists 104 candidate reasons. |
| 5 | It's just taking me a while to compose and edit the rationale for each |
| 6 | one, and to arrange the reasons in a sensible order. I will merge this |
| 7 | document from its current branch onto trunk when it gets closer to being |
| 8 | ready to publish.* |
| @@ -141,10 +141,27 @@ | |
| 141 | on column headers to sort by that column.<p> |
| 142 | If you are like me and have hundreds of repositories on your desktop |
| 143 | system, this feature makes it easier to keep track of them all. |
| 144 | Are you on an infrequently used travel laptop and forgot where you |
| 145 | put a particular repository, this feature helps you find it. |
| 146 | |
| 147 | 1. **Fossil lets you quickly find all of your local checkouts that have |
| 148 | uncommitted changes.**<p> |
| 149 | Simply run "<tt>fossil all changes</tt>" to get a quick |
| 150 | summary of every checkout on your local machine that needs a commit. |
| 151 | |
| 152 | 1. **Fossil lets you sync all of the changes in all of your local |
| 153 | repositories to their remotes, with a single command.**<p> |
| 154 | Run "<tt>fossil all sync</tt>" and all your local |
| 155 | repositories will sync up. This is useful, for example when |
| 156 | taking a laptop off-network. Before disconnecting, you sync |
| 157 | all of your repositories (I typically have about a hundred) |
| 158 | with a single command, so there is no chance that you forget |
| 159 | one. While off-network, you might commit changes to one or |
| 160 | more of those repositories. Once you reconnect, you simply |
| 161 | run "fossil all sync" again to push out your edits to the |
| 162 | rest of the community. |
| 163 | |
| 164 | 1. **Fossil allows multiple checkins to have the same tag.**<p> |
| 165 | For example, on the SQLite project, every release is tagged with |
| 166 | "release". |
| 167 | |
| @@ -341,10 +358,38 @@ | |
| 358 | 1. **The Fossil web interface supports "embedded documentation"**</p> |
| 359 | See the [Project Documentation](/doc/trunk/www/embeddeddoc.wiki) page |
| 360 | for details. Markdown, Wiki, plain-text, and HTML files in the |
| 361 | source tree can be rendered and used as documentation pages. This |
| 362 | is how all of the documentation files for Fossil itself are rendered. |
| 363 | |
| 364 | 1. **Fossil can easily host an entire project website, using only the |
| 365 | repository as the backing store.**<p> |
| 366 | The embedded documentation and wiki features allow you to write |
| 367 | web pages. The unversioned file feature gives you space to put of |
| 368 | precompiled binaries or other transient and/or derived resources |
| 369 | without contaminating the source tree. Indeed, the |
| 370 | [canonical Fossil website](https://fossil-scm.org/home) is just |
| 371 | an instance of Fossil running on the self-hosting Fossil repository. |
| 372 | If you clone the Fossil self-hosting repository, you don't get just |
| 373 | code - you get the entire website. (Exception: |
| 374 | [Fossil Forum](https://sqlite.org/forum) is hosted separately using |
| 375 | a separate Fossil repository, so you'd actually need to clone that |
| 376 | one too, in order to get the whole website.) |
| 377 | |
| 378 | 1. **Using Fossil, backing up your project website is just a sync.**<p> |
| 379 | If you do host your entire project website in a Fossil repository, |
| 380 | as Fossil itself does, then backing up that website is as simple |
| 381 | as creating a clone and keeping the clone synced. |
| 382 | |
| 383 | 1. **Fossil will render uncommitted changes to embedded documentation.** |
| 384 | <p> |
| 385 | Using the "<tt>fossil ui</tt>", if in for the |
| 386 | [/doc/VERSION/FILE](/help/www/doc) webpage, if the VERSION is the |
| 387 | special keyword "ckout", then the content is taken from the local |
| 388 | checkout not from the repository. This allows you to edit embedded |
| 389 | documentation files and then see how they look and work on the |
| 390 | actual website without having to commit. |
| 391 | |
| 392 | 1. **Fossil has a wiki sandbox for experimenting with markup.**</p> |
| 393 | The [wiki sandbox](/wikiedit?name=Sandbox) allows users to experiment |
| 394 | with Markdown or other text markup languages supported by Fossil, |
| 395 | without making permanent changes to the repository. |
| @@ -609,11 +654,10 @@ | |
| 654 | fossil patch pull @ -f</pre> |
| 655 | (Aside: the -f option tells the command to first "revert" any |
| 656 | uncommitted changes prior currently in the checkout prior to pulling |
| 657 | over the new ones from r21:sqlite/sqlite. Without that option, the |
| 658 | changes would be merged.) |
| 659 | |
| 660 | 1. **Fossil allows you view uncommitted changes on a remote machine |
| 661 | in a web browser over SSH.**<p> |
| 662 | Suppose you have some edits on a remote, headless machine and you |
| 663 | would like to review those changes. Fossil lets you see those |
| @@ -643,5 +687,180 @@ | |
| 687 | It causes Fossil to consult the $HOME/.config/fossil.db file |
| 688 | (or %LOCALAPPDATA%/_fossil on Windows) to find the locations of all |
| 689 | repositories on the remote machine, then bring up a web page listing |
| 690 | all those repositories. Links on that initial page let you explore |
| 691 | deeper into the details of each repository. |
| 692 | |
| 693 | 1. **The Fossil web interface supports multiple timeline formats, to |
| 694 | accommodate personal tastes.**<p> |
| 695 | The different formats are called "Views". The current repertiore |
| 696 | includes "Modern", "Columnar", "Compact", "Simple", "Verbose", and |
| 697 | "Classic". Users can select whichever format they want and their |
| 698 | preference is remembered in a cookie. |
| 699 | |
| 700 | 1. **A Fossil web server admin can set the default timeline format.**<p> |
| 701 | Individual users have a lot of control over what their own timeline |
| 702 | displays look like, but the repository administrator can set the |
| 703 | default separately for each repository. |
| 704 | |
| 705 | 1. **Fossil is open and transparent about the cookies that it uses.**<p> |
| 706 | There are really only two: The login cookie (if you are logged in) |
| 707 | and the display preferences cookie. If you visit the |
| 708 | [/cookies page](/cookies), Fossil will |
| 709 | show you all the cookies it use and it will decode them for you to |
| 710 | show you exactly what they mean and what information they are holding |
| 711 | and give you an opportunity to delete them individually. |
| 712 | |
| 713 | 1. **The Fossil web interface comes with a variety of "skins" built in.**<p> |
| 714 | Visit the [/skins page](/skins) to see all the available skins and |
| 715 | which one is currently in use. |
| 716 | |
| 717 | 1. **Individual users get to choose their favorite Fossil skin.**<p> |
| 718 | The repository administrator sets the default skin, but if |
| 719 | individual users do not like that choice, they can select a different |
| 720 | skin and their choice is recorded in the display preferences cookie. |
| 721 | |
| 722 | 1. **Repository administators can create new custom skins.**<p> |
| 723 | The current library of skins are most derived from custom skins that |
| 724 | users of Fossil have created over the years and generously donated |
| 725 | to the project. If none of the default skins work for you, you can |
| 726 | create your own, perhaps using one of the existing skins as a template. |
| 727 | |
| 728 | 1. **Most Fossil web-interface skins include a hamburger (☰) menu.**<p> |
| 729 | Clicking on the hamburger menu brings up a dropdown "site-map" |
| 730 | page that lets you quickly navigate to the information you want. |
| 731 | (Note: The presence an operation of the hamburger menu is a |
| 732 | skin-specific feature and might not be present on every skin, but |
| 733 | it is used on the more popular skins.) Curiously, none of GitHub, |
| 734 | GitLab, Gitea, nor Forgejo have a hamburger menu, which in my |
| 735 | experience makes sites based on those systems much harder to |
| 736 | navigate. |
| 737 | |
| 738 | 1. **The Fossil web interface /sitemap page is responsive to |
| 739 | individual user permissions and capabilities.**<p> |
| 740 | Each user on the Fossil web interface, including the special |
| 741 | user "nobody" used if no login is attempted, has rich collection |
| 742 | of "capabilities" assigned by the repository administrator. |
| 743 | Depending on capabilities, some pages will display different or |
| 744 | will not display at all. Pages that a user does not have access |
| 745 | to are automatically omitted from the [/sitemap page](/sitemap). |
| 746 | |
| 747 | 1. **The Fossil web interface allows "anonymous" users.**<p> |
| 748 | The "anonymous" user is a human (we think, because he has solved |
| 749 | a captcha) but we do not know who. User who do not want to |
| 750 | identify themselves but who also don't want to be mistaken for |
| 751 | a spider or robot can log in as anonymous. |
| 752 | <p> |
| 753 | The repository administrator has complete control over the capabilities |
| 754 | of anonymous. Anonymous can be completely banned, or maybe given |
| 755 | read-only capabilities, or given complete access, with lots of shade |
| 756 | in between, according to the needs of the project. |
| 757 | <p> |
| 758 | The "anonymous" user is distinct from user "nobody" in that we |
| 759 | believe anonymous is a real human, whereas user nobody is presumed |
| 760 | to be a robot. The repository administrator also has complete control |
| 761 | over the capabilities for user "nobody". |
| 762 | |
| 763 | 1. **The Fossil web interface has lots of built-in defenses against |
| 764 | abuse by spiders and robots.**<p> |
| 765 | Sadly, the internet is rapidly devolving such that most HTTP requests |
| 766 | now come from AI spiders trying to find training content, and/or robots |
| 767 | looking for website vulnerabilities. The flood of requests can |
| 768 | rapidly bog down an undefended server. Fossil includes a range of |
| 769 | defenses against aggressive bots that help keep the server load and |
| 770 | hence ISP costs down while still providing fast and detailed responses |
| 771 | to real humans. This is an on-going battle. But Fossil is, at least, |
| 772 | in the fight. Everything is easily configurable, via the web interface, |
| 773 | by repository administrators. |
| 774 | |
| 775 | 1. **The Fossil web interface includes a "security audit" page accessible |
| 776 | to repositoriy administrators.**<p> |
| 777 | The security-audit pages give a succinct summary of how a repository |
| 778 | web interface is configured, with an eye toward operational security. |
| 779 | As with any full-featured web application, the Fossil web interface |
| 780 | as a large number of settings. A common worry amoung system |
| 781 | administrators is overlooking or omitting or misconfiguring some |
| 782 | security-sensitive setting. The security-audit page is designed to |
| 783 | assuage that worry. |
| 784 | <p> |
| 785 | The security-audit shows at a glance how a repository web interface |
| 786 | is set up, and raises alerts about any settings that are questionable |
| 787 | or that might facilitate mischief. The page fits on a single screen |
| 788 | with minimal or no scrolling. After standing up a new Fossil server, |
| 789 | a quick glance at the security-audit page (accessible only to |
| 790 | administrators) gives peace of mind that all is well and that nothing |
| 791 | was overlooked. |
| 792 | |
| 793 | 1. **The Fossil web interface menu bar can be customized.**<p> |
| 794 | Repository administrators can customize the menu bar on the web |
| 795 | interface. Individual items can be added or omitted from the |
| 796 | menu bar based on user capabilities and/or whether or not the |
| 797 | client is a phone or other narrow-screen mobile devide, a standard |
| 798 | desktop browser, or a wide-screen desktop browser. |
| 799 | |
| 800 | 1. **The Fossil web interface sitemap can be customized.**<p> |
| 801 | Repository administrators can add new entries to the |
| 802 | [/sitemap](/sitemap) that are shown or omitted |
| 803 | based on user capabilities. |
| 804 | |
| 805 | 1. **The Fossil web interface can be augmented with auxiliary content |
| 806 | and/or CGIs that exist outside of the repository.**<p> |
| 807 | The auxiliary content or CGI result uses the same theme and skin as |
| 808 | the default website, and blends right in. An example of this is |
| 809 | the |
| 810 | [SQLite Release Checklist](https://sqlite.org/src/ext/checklist/top/index). |
| 811 | The SQLite Release Checklist is a CGI that is completely separate from |
| 812 | Fossil, but appears to be integrated in the Fossil web interface. |
| 813 | It uses the same skin and interface settings. But the content is |
| 814 | created by a separate CGI program. Fossil passes down additional |
| 815 | CGI variables to tell the CGI what the Fossil user name is and what |
| 816 | capabilities that user has, among other things. In the case of the |
| 817 | SQLite Release Checklist, those additional settings mean only project |
| 818 | committers can make changes to the checklist (such as marking items |
| 819 | as "done") and that the checklist is read-only for the general public. |
| 820 | <p> |
| 821 | Additional information about this advanced feature of Fossil |
| 822 | can be seen at <https://fossil-scm.org/home/doc/trunk/www/serverext.wiki>. |
| 823 | |
| 824 | 1. **Experts can browse low-level details of a Fossil repository |
| 825 | using SQL.**<p> |
| 826 | A Fossil repository is just an SQLite database file. Low-level content |
| 827 | of that database file can be viewed and even changed using ordinary |
| 828 | SQL and the "<tt>fossil sql</tt>" command. The "fossil sql" |
| 829 | command brings up a standard SQLite command-line shell, already |
| 830 | connected to the repository database, and extended to include extra |
| 831 | functions (including table-valued functions) to help interpret the |
| 832 | low-level content of the repository. This feature is not needed nor |
| 833 | recommended for the average user, however, if you want to learn more |
| 834 | about the inner workings of Fossil, the SQL interface is a great tool |
| 835 | to help you explore. |
| 836 | |
| 837 | 1. **The underlying artifacts of a Fossil repository are well-documented, |
| 838 | human-readable, and human-understandable.**<p> |
| 839 | A Fossil repository is an SQLite database file, but not every SQLite |
| 840 | database file is a Fossil repository. Fossil repositories store |
| 841 | "artifacts" in a very particular format. See |
| 842 | <https://fossil-scm.org/home/doc/trunk/www/fileformat.wiki> for |
| 843 | the details of that format. |
| 844 | <p> |
| 845 | This underlying format is text-only. It is designed to be easily |
| 846 | parsed and interpreted by programs written in any language. It is |
| 847 | designed to be easily understood by humans, even humans not yet born. |
| 848 | <p> |
| 849 | Many of the low-level artifact formats for Git, in contrast, are |
| 850 | binary and are only thinly documented. |
| 851 | |
| 852 | 1. **The Fossil web interface has a "This Day In History" page.**<p> |
| 853 | See that page for [Fossil](/thisdayinhistory) or |
| 854 | [SQLite](https://sqlite.org/src/thisdayinhistory). |
| 855 | It should multiple timeline snippets for a day that at various |
| 856 | points in the past. |
| 857 | <p> |
| 858 | This is something of a vanity page. It is difficult to describe a |
| 859 | real business need for this information. But the page does jog old |
| 860 | memories and helps developers keep perspective on how a project has |
| 861 | changed through the years. |
| 862 | <p> |
| 863 | One important aspect of Fossil that this page illustrates due to the |
| 864 | rebust and modular design of the Fossil implementation, |
| 865 | pages like this can be generated, using very little memory or CPU, |
| 866 | and with not very much code. |
| 867 |