Fossil

Artifact Content
Login

Artifact cdb125adad3e8311a3badefa59b99dd9f417dc7c:


     1  <title>The Fossil Web Interface</title>
     2  
     3  One of the innovative features of Fossil is its built-in web interface.
     4  This web interface provides everything you need to run a software
     5  development project:
     6  
     7    *  [./bugtheory.wiki | Ticketing and bug tracking]
     8    *  [./wikitheory.wiki | Wiki]
     9    *  [./embeddeddoc.wiki | On-line documentation]
    10    *  [./event.wiki | Technical notes]
    11    *  Timelines
    12    *  Full text search over all of the above
    13    *  Status information
    14    *  Graphs of revision and branching history
    15    *  File and version lists and differences
    16    *  Download historical versions as ZIP archives
    17    *  Historical change data
    18    *  Add and remove tags on check-ins
    19    *  Move check-ins between branches
    20    *  Revise check-in comments
    21    *  Manage user credentials and access permissions
    22    *  And so forth... (some [./webpage-ex.md|examples])
    23  
    24  You get all of this, and more, for free when you use Fossil.
    25  There are no extra programs to install or setup.
    26  Everything you need is already pre-configured and built into the
    27  self-contained, stand-alone Fossil executable.
    28  
    29  As an example of how useful this web interface can be,
30 the entire [./index.wiki | Fossil website] (except for the 31 [http://www.fossil-scm.org/download.html | download page]),
32 including the document you are now reading, 33 is rendered using the Fossil web interface, with no enhancements, 34 and little customization. 35 36 <blockquote> 37 <b>Key point:</b> <i>The Fossil website is just a running instance 38 of Fossil! 39 </blockquote> 40 41 Note also that because Fossil is a distributed system, you can run 42 the web interface on your local machine while off network (for example, 43 while on an airplane) including 44 making changes to wiki pages and/or trouble ticket, then synchronize with your 45 co-workers after you reconnect. When you clone a Fossil repository, you 46 don't just get the project source code, you get the entire project 47 management website. 48 49 <h2>Drop-Dead Simple Startup</h2> 50 51 To start using the built-in Fossil web interface on an existing Fossil 52 repository, simply type this: 53 54 <b>fossil ui existing-repository.fossil</b> 55 56 Substitute the name of your repository, of course. 57 The "ui" command will start a webserver running (it figures out an 58 available TCP port to use on its own) and then automatically launches 59 your web browser to point at that server. If you run the "ui" command 60 from within an open check-out, you can omit the repository name: 61 62 <b>fossil ui</b> 63 64 The latter case is a very useful short-cut when you are working on a 65 Fossil project and you want to quickly do some work with the web interface. 66 Notice that Fossil automatically finds an unused TCP port to run the 67 server on and automatically points your web browser to the correct 68 URL. So there is never any fumbling around trying to find an open 69 port or to type arcane strings into your browser URL entry box. 70 The interface just pops right up, ready to run. 71 72 The Fossil web interface is also very easy to setup and run on a 73 network server, as either a CGI program or from inetd, or as an 74 SCGI server. Details on how 75 to do that are described further below. 76 77 <h2>Things To Do Using The Web Interface</h2> 78 79 You can view <b>timelines</b> of changes to the project. The default 80 "Timeline" link on the menu bar takes you to a page that shows the 20 81 most recent check-ins, wiki page edits, ticket/bug-report changes, 82 and/or blog entries. 83 This gives a very useful snapshot of what has been happening lately on the 84 project. You can click to go further back in time, if needed. Or 85 follow hyperlinks to see details, including diffs and annotated diffs, 86 of individual check-ins, wiki page edits, ticket changes, and 87 blog edits. 88 89 You can view and edit <b>tickets and bug reports</b> by following the 90 "Tickets" link on the menu bar. 91 Fossil is backed by an SQL database, so users with appropriate permissions 92 can write new ticket report formats based on SQL query statements. 93 Fossil is careful to prevent ticket report formats from doing any mischief 94 on the database (it only allows SELECT statements to run) and it restricts 95 access to sensitive data such as user passwords. So it is actually safe 96 to let anonymous users on the internet write their own ticket formats if 97 you like. In addition to viewing and/or creating report formats, you can 98 also create new tickets or look at summaries or complete histories of 99 existing tickets. Any changes you make will automatically merge with 100 changes from your co-workers the next time your repository is synchronized. 101 102 You can view and edit <b>wiki</b> by following the "Wiki" link on the 103 menu bar. Fossil uses simple and easy-to-remember 104 [/wiki_rules | wiki formatting rules] so you won't have to spend a lot 105 of time learning a new markup language. And, as with tickets, all of 106 your edits will automatically merge with those of your co-workers when 107 your repository synchronizes. 108 109 You can view summary reports of <b>branches</b> in the 110 check-in graph by visiting the "Branches" link on the 111 menu bar. From those pages you can follow hyperlinks to get additional 112 details. These screens allow you to easily keep track of what is going 113 on with separate subteams within your project team. 114 115 The "Files" link on the menu allows you to browse through the <b>file 116 hierarchy</b> of the project and to view complete changes histories on 117 individual files, with hyperlinks to the check-ins that made those 118 changes, and with diffs and annotated diffs between versions. 119 120 The web interface supports [./embeddeddoc.wiki | embedded documentation]. 121 Embedded documentation is documentation files (usually in wiki format) 122 that are checked into project as part of the source tree. Such files 123 can be viewed as if they were ordinary web pages. This document that 124 you are now reading is an example of embedded documentation. 125 126 <h2>Customizing The Web Interface Appearance</h2> 127 128 Users with appropriate permissions can customize the look and feel of 129 the web interface using the "Admin" link on the main menu of the web 130 interface. Templates 131 for the header and footer of each page can be edited, as can the CSS 132 for the entire page. You can even change around the main menu. 133 Timeline display preferences can be edited. The page that is brought 134 up as the "Home" page can be changed. It is often useful to set the 135 "Home" page to be a wiki page or an embedded document. 136 137 <h2>Installing On A Network Server</h2> 138 139 When you create a new Fossil project and after you have configured it 140 like you want it using the web interface, you can make the project 141 available to a distributed team by simply copying the single 142 repository file up to a web server that supports CGI or SCGI. To 143 run Fossil as CGI, just put the 144 <b>sample-project.fossil</b> file in a directory where CGI scripts 145 have both read and write permission on the file and the directory that 146 contains the file, then add a CGI script that looks something like this: 147 148 <verbatim> 149 #!/usr/local/bin/fossil 150 repository: /home/www/sample-project.fossil 151 </verbatim> 152 153 Adjust the script above so that the paths are correct for your system, 154 of course, and also make sure the Fossil binary is installed on the server. 155 But that is <u>all</u> you have to do. You now have everything you need to host 156 a distributed software development project in less than five minutes using a 157 two-line CGI script. 158 159 Instructions for setting up an SCGI server are 160 [./scgi.wiki | available separately]. 161 162 You don't have a CGI- or SCGI-capable web server running on your 163 server machine? 164 Not a problem. The Fossil interface can also be launched via inetd or 165 xinetd. An inetd configuration line sufficient to launch the Fossil 166 web interface looks like this: 167 168 <verbatim> 169 80 stream tcp nowait.1000 root /usr/local/bin/fossil \ 170 /usr/local/bin/fossil http /home/www/sample-project.fossil 171 </verbatim> 172 173 As always, you'll want to adjust the pathnames to whatever is appropriate 174 for your system. The xinetd setup uses a different syntax but follows 175 the same idea.