Fossil SCM
In an effort to make www/* source documents read as cleanly as their rendered counterparts, replaced nearly all use of HTML "p" tags, relying instead on the Wiki and Markdown markup features to achieve the same appearance. The only uses remaining are: * in Markdown nested lists, where blank lines should render the list items as separate paragraphs just as at the list's top level; since it does not, if you want a line break, you either have to wrap the item in "p" tags or do the double-br hack. * in Wiki where blank lines within a list give you a separate list in the HTML output; this is fine for bullet lists, but with numbered lists it causes the numbering to restart unless you do the same sort of manual HTML workaround as with the prior item * in plain HTML docs and wiki docs between "nowiki" tags In many places, this cleanup gets rid of pointless stray "p" tags, placating HTML verifiers.
Commit
1fd407f61ae8824f554b4fe483946e2f846ef18b1b2791fd8a350644e8329f52
Parent
0cb4f1fc5e25087…
24 files changed
+25
-24
+1
-1
+56
-47
+22
-24
+22
-24
+11
-11
+38
-44
+6
-5
+1
-1
+1
-1
+27
-27
+70
-72
+2
-2
+52
-59
+2
-2
+68
-71
+18
-18
+121
-117
+2
-2
+4
-4
+22
-12
+49
-50
+14
-11
+191
-200
~
www/aboutcgi.wiki
~
www/blockchain.md
~
www/build.wiki
~
www/concepts.wiki
~
www/custom_ticket.wiki
~
www/customskin.md
~
www/delta_format.wiki
~
www/encryptedrepos.wiki
~
www/faq.tcl
~
www/faq.wiki
~
www/foss-cklist.wiki
~
www/fossil-v-git.wiki
~
www/index.wiki
~
www/mirrortogithub.md
~
www/newrepo.wiki
~
www/pop.wiki
~
www/qandc.wiki
~
www/quickstart.wiki
~
www/quotes.wiki
~
www/server/any/althttpd.md
~
www/server/whyuseaserver.wiki
~
www/shunning.wiki
~
www/ssl.wiki
~
www/sync.wiki
+25
-24
| --- www/aboutcgi.wiki | ||
| +++ www/aboutcgi.wiki | ||
| @@ -1,19 +1,20 @@ | ||
| 1 | 1 | <title>How CGI Works In Fossil</title> |
| 2 | 2 | <h2>Introduction</h2><blockquote> |
| 3 | -<p>CGI or "Common Gateway Interface" is a venerable yet reliable technique for | |
| 3 | +CGI or "Common Gateway Interface" is a venerable yet reliable technique for | |
| 4 | 4 | generating dynamic web content. This article gives a quick background on how |
| 5 | 5 | CGI works and describes how Fossil can act as a CGI service. |
| 6 | -<p>This is a "how it works" guide. This document provides background | |
| 6 | + | |
| 7 | +This is a "how it works" guide. This document provides background | |
| 7 | 8 | information on the CGI protocol so that you can better understand what |
| 8 | 9 | is going on behind the scenes. If you just want to set up Fossil |
| 9 | 10 | as a CGI server, see the [./server/ | Fossil Server Setup] page. Or |
| 10 | 11 | if you want to development CGI-based extensions to Fossil, see |
| 11 | 12 | the [./serverext.wiki|CGI Server Extensions] page. |
| 12 | 13 | </blockquote> |
| 13 | 14 | <h2>A Quick Review Of CGI</h2><blockquote> |
| 14 | -<p> | |
| 15 | + | |
| 15 | 16 | An HTTP request is a block of text that is sent by a client application |
| 16 | 17 | (usually a web browser) and arrives at the web server over a network |
| 17 | 18 | connection. The HTTP request contains a URL that describes the information |
| 18 | 19 | being requested. The URL in the HTTP request is typically the same URL |
| 19 | 20 | that appears in the URL bar at the top of the web browser that is making |
| @@ -20,33 +21,33 @@ | ||
| 20 | 21 | the request. The URL might contain a "?" character followed |
| 21 | 22 | query parameters. The HTTP will usually also contain other information |
| 22 | 23 | such as the name of the application that made the request, whether or |
| 23 | 24 | not the requesting application can accept a compressed reply, POST |
| 24 | 25 | parameters from forms, and so forth. |
| 25 | -<p> | |
| 26 | + | |
| 26 | 27 | The job of the web server is to interpret the HTTP request and formulate |
| 27 | 28 | an appropriate reply. |
| 28 | 29 | The web server is free to interpret the HTTP request in any way it wants. |
| 29 | 30 | But most web servers follow a similar pattern, described below. |
| 30 | 31 | (Note: details may vary from one web server to another.) |
| 31 | -<p> | |
| 32 | + | |
| 32 | 33 | Suppose the filename component of the URL in the HTTP request looks like this: |
| 33 | 34 | <blockquote><b>/one/two/timeline/four</b></blockquote> |
| 34 | 35 | Most web servers will search their content area for files that match |
| 35 | 36 | some prefix of the URL. The search starts with <b>/one</b>, then goes to |
| 36 | 37 | <b>/one/two</b>, then <b>/one/two/timeline</b>, and finally |
| 37 | 38 | <b>/one/two/timeline/four</b> is checked. The search stops at the first |
| 38 | 39 | match. |
| 39 | -<p> | |
| 40 | + | |
| 40 | 41 | Suppose the first match is <b>/one/two</b>. If <b>/one/two</b> is an |
| 41 | 42 | ordinary file in the content area, then that file is returned as static |
| 42 | 43 | content. The "<b>/timeline/four</b>" suffix is silently ignored. |
| 43 | -<p> | |
| 44 | + | |
| 44 | 45 | If <b>/one/two</b> is a CGI script (or program), then the web server |
| 45 | 46 | executes the <b>/one/two</b> script. The output generated by |
| 46 | 47 | the script is collected and repackaged as the HTTP reply. |
| 47 | -<p> | |
| 48 | + | |
| 48 | 49 | Before executing the CGI script, the web server will set up various |
| 49 | 50 | environment variables with information useful to the CGI script: |
| 50 | 51 | <table border=1 cellpadding=5> |
| 51 | 52 | <tr><th>Environment<br>Variable<th>Meaning |
| 52 | 53 | <tr><td>GATEWAY_INTERFACE<td>Always set to "CGI/1.0" |
| @@ -59,21 +60,21 @@ | ||
| 59 | 60 | <td>The suffix of the URL beyond the name of the CGI script. |
| 60 | 61 | In this example: "timeline/four". |
| 61 | 62 | <tr><td>QUERY_STRING |
| 62 | 63 | <td>The query string that follows the "?" in the URL, if there is one. |
| 63 | 64 | </table> |
| 64 | -<p> | |
| 65 | + | |
| 65 | 66 | There are other CGI environment variables beyond those listed above. |
| 66 | 67 | Many Fossil servers implement the |
| 67 | 68 | [https://fossil-scm.org/home/test_env/two/three?abc=xyz|test_env] |
| 68 | 69 | webpage that shows some of the CGI environment |
| 69 | 70 | variables that Fossil pays attention to. |
| 70 | -<p> | |
| 71 | + | |
| 71 | 72 | In addition to setting various CGI environment variables, if the HTTP |
| 72 | 73 | request contains POST content, then the web server relays the POST content |
| 73 | 74 | to standard input of the CGI script. |
| 74 | -<p> | |
| 75 | + | |
| 75 | 76 | In summary, the task of the |
| 76 | 77 | CGI script is to read the various CGI environment variables and |
| 77 | 78 | the POST content on standard input (if any), figure out an appropriate |
| 78 | 79 | reply, then write that reply on standard output. |
| 79 | 80 | The web server will read the output from the CGI script, reformat it |
| @@ -80,11 +81,11 @@ | ||
| 80 | 81 | into an appropriate HTTP reply, and relay the result back to the |
| 81 | 82 | requesting application. |
| 82 | 83 | The CGI script exits as soon as it generates a single reply. |
| 83 | 84 | The web server will (usually) persist and handle multiple HTTP requests, |
| 84 | 85 | but a CGI script handles just one HTTP request and then exits. |
| 85 | -<p> | |
| 86 | + | |
| 86 | 87 | The above is a rough outline of how CGI works. |
| 87 | 88 | There are many details omitted from this brief discussion. |
| 88 | 89 | See other on-line CGI tutorials for further information. |
| 89 | 90 | </blockquote> |
| 90 | 91 | <h2>How Fossil Acts As A CGI Program</h2> |
| @@ -103,33 +104,33 @@ | ||
| 103 | 104 | shebang with a single argument that is the full pathname of the script |
| 104 | 105 | itself. |
| 105 | 106 | In our example, the interpreter is Fossil, and the argument might |
| 106 | 107 | be something like "/var/www/cgi-bin/one/two" (depending on how your |
| 107 | 108 | particular web server is configured). |
| 108 | -<p> | |
| 109 | + | |
| 109 | 110 | The Fossil program that is run as the script interpreter |
| 110 | 111 | is the same Fossil that runs when |
| 111 | 112 | you type ordinary Fossil commands like "fossil sync" or "fossil commit". |
| 112 | 113 | But in this case, as soon as it launches, the Fossil program |
| 113 | 114 | recognizes that the GATEWAY_INTERFACE environment variable is |
| 114 | 115 | set to "CGI/1.0" and it therefore knows that it is being used as |
| 115 | 116 | CGI rather than as an ordinary command-line tool, and behaves accordingly. |
| 116 | -<p> | |
| 117 | + | |
| 117 | 118 | When Fossil recognizes that it is being run as CGI, it opens and reads |
| 118 | 119 | the file identified by its sole argument (the file named by |
| 119 | 120 | <code>argv[1]</code>). In our example, the second line of that file |
| 120 | 121 | tells Fossil the location of the repository it will be serving. |
| 121 | 122 | Fossil then starts looking at the CGI environment variables to figure |
| 122 | 123 | out what web page is being requested, generates that one web page, |
| 123 | 124 | then exits. |
| 124 | -<p> | |
| 125 | + | |
| 125 | 126 | Usually, the webpage being requested is the first term of the |
| 126 | 127 | PATH_INFO environment variable. (Exceptions to this rule are noted |
| 127 | 128 | in the sequel.) For our example, the first term of PATH_INFO |
| 128 | 129 | is "timeline", which means that Fossil will generate |
| 129 | 130 | the [/help?cmd=/timeline|/timeline] webpage. |
| 130 | -<p> | |
| 131 | + | |
| 131 | 132 | With Fossil, terms of PATH_INFO beyond the webpage name are converted into |
| 132 | 133 | the "name" query parameter. Hence, the following two URLs mean |
| 133 | 134 | exactly the same thing to Fossil: |
| 134 | 135 | <ol type='A'> |
| 135 | 136 | <li> [https://fossil-scm.org/home/info/c14ecc43] |
| @@ -149,11 +150,11 @@ | ||
| 149 | 150 | using a single CGI script. |
| 150 | 151 | On a website that wants to serve multiple repositories, one could |
| 151 | 152 | simply create multiple CGI scripts, one script for each repository. |
| 152 | 153 | But it is also possible to serve multiple Fossil repositories from |
| 153 | 154 | a single CGI script. |
| 154 | -<p> | |
| 155 | + | |
| 155 | 156 | If the CGI script for Fossil contains a "directory:" line instead of |
| 156 | 157 | a "repository:" line, then the argument to "directory:" is the name |
| 157 | 158 | of a directory that contains multiple repository files, each ending |
| 158 | 159 | with ".fossil". For example: |
| 159 | 160 | <blockquote><pre> |
| @@ -200,44 +201,44 @@ | ||
| 200 | 201 | HTTP_HOST SCRIPT_NAME PATH_INFO QUERY_STRING |
| 201 | 202 | </pre> |
| 202 | 203 | </blockquote> |
| 203 | 204 | <h2>Additional CGI Script Options</h2> |
| 204 | 205 | <blockquote> |
| 205 | -<p> | |
| 206 | + | |
| 206 | 207 | The CGI script can have additional options used to fine-tune |
| 207 | 208 | Fossil's behavior. See the [./cgi.wiki|CGI script documentation] |
| 208 | 209 | for details. |
| 209 | -</p> | |
| 210 | + | |
| 210 | 211 | </blockquote> |
| 211 | 212 | <h2>Additional Observations</h2> |
| 212 | 213 | <blockquote><ol type="I"> |
| 213 | 214 | <li><p> |
| 214 | 215 | Fossil does not distinguish between the various HTTP methods (GET, PUT, |
| 215 | 216 | DELETE, etc). Fossil figures out what it needs to do purely from the |
| 216 | -webpage term of the URI. | |
| 217 | +webpage term of the URI.</p></li> | |
| 217 | 218 | <li><p> |
| 218 | 219 | Fossil does not distinguish between query parameters that are part of the |
| 219 | 220 | URI, application/x-www-form-urlencoded or multipart/form-data encoded |
| 220 | 221 | parameter that are part of the POST content, and cookies. Each information |
| 221 | 222 | source is seen as a space of key/value pairs which are loaded into an |
| 222 | 223 | internal property hash table. The code that runs to generate the reply |
| 223 | 224 | can then reference various properties values. |
| 224 | 225 | Fossil does not care where the value of each property comes from (POST |
| 225 | 226 | content, cookies, or query parameters) only that the property exists |
| 226 | -and has a value. | |
| 227 | +and has a value.</p></li> | |
| 227 | 228 | <li><p> |
| 228 | 229 | The "[/help?cmd=ui|fossil ui]" and "[/help?cmd=server|fossil server]" commands |
| 229 | 230 | are implemented using a simple built-in web server that accepts incoming HTTP |
| 230 | 231 | requests, translates each request into a CGI invocation, then creates a |
| 231 | 232 | separate child Fossil process to handle each request. In other words, CGI |
| 232 | 233 | is used internally to implement "fossil ui/server". |
| 233 | -<p> | |
| 234 | +<br><br> | |
| 234 | 235 | SCGI is processed using the same built-in web server, just modified |
| 235 | 236 | to parse SCGI requests instead of HTTP requests. Each SCGI request is |
| 236 | 237 | converted into CGI, then Fossil creates a separate child Fossil |
| 237 | -process to handle each CGI request. | |
| 238 | +process to handle each CGI request.</p></li> | |
| 238 | 239 | <li><p> |
| 239 | 240 | Fossil is itself often launched using CGI. But Fossil can also then |
| 240 | 241 | turn around and launch [./serverext.wiki|sub-CGI scripts to implement |
| 241 | -extensions]. | |
| 242 | +extensions].</p></li> | |
| 242 | 243 | </ol> |
| 243 | 244 | </blockquote> |
| 244 | 245 |
| --- www/aboutcgi.wiki | |
| +++ www/aboutcgi.wiki | |
| @@ -1,19 +1,20 @@ | |
| 1 | <title>How CGI Works In Fossil</title> |
| 2 | <h2>Introduction</h2><blockquote> |
| 3 | <p>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 | <p>This is a "how it works" guide. This document provides background |
| 7 | information on the CGI protocol so that you can better understand what |
| 8 | is going on behind the scenes. If you just want to set up Fossil |
| 9 | as a CGI server, see the [./server/ | Fossil Server Setup] page. Or |
| 10 | if you want to development CGI-based extensions to Fossil, see |
| 11 | the [./serverext.wiki|CGI Server Extensions] page. |
| 12 | </blockquote> |
| 13 | <h2>A Quick Review Of CGI</h2><blockquote> |
| 14 | <p> |
| 15 | An HTTP request is a block of text that is sent by a client application |
| 16 | (usually a web browser) and arrives at the web server over a network |
| 17 | connection. The HTTP request contains a URL that describes the information |
| 18 | being requested. The URL in the HTTP request is typically the same URL |
| 19 | that appears in the URL bar at the top of the web browser that is making |
| @@ -20,33 +21,33 @@ | |
| 20 | the request. The URL might contain a "?" character followed |
| 21 | query parameters. The HTTP will usually also contain other information |
| 22 | such as the name of the application that made the request, whether or |
| 23 | not the requesting application can accept a compressed reply, POST |
| 24 | parameters from forms, and so forth. |
| 25 | <p> |
| 26 | The job of the web server is to interpret the HTTP request and formulate |
| 27 | an appropriate reply. |
| 28 | The web server is free to interpret the HTTP request in any way it wants. |
| 29 | But most web servers follow a similar pattern, described below. |
| 30 | (Note: details may vary from one web server to another.) |
| 31 | <p> |
| 32 | Suppose the filename component of the URL in the HTTP request looks like this: |
| 33 | <blockquote><b>/one/two/timeline/four</b></blockquote> |
| 34 | Most web servers will search their content area for files that match |
| 35 | some prefix of the URL. The search starts with <b>/one</b>, then goes to |
| 36 | <b>/one/two</b>, then <b>/one/two/timeline</b>, and finally |
| 37 | <b>/one/two/timeline/four</b> is checked. The search stops at the first |
| 38 | match. |
| 39 | <p> |
| 40 | Suppose the first match is <b>/one/two</b>. If <b>/one/two</b> is an |
| 41 | ordinary file in the content area, then that file is returned as static |
| 42 | content. The "<b>/timeline/four</b>" suffix is silently ignored. |
| 43 | <p> |
| 44 | If <b>/one/two</b> is a CGI script (or program), then the web server |
| 45 | executes the <b>/one/two</b> script. The output generated by |
| 46 | the script is collected and repackaged as the HTTP reply. |
| 47 | <p> |
| 48 | Before executing the CGI script, the web server will set up various |
| 49 | environment variables with information useful to the CGI script: |
| 50 | <table border=1 cellpadding=5> |
| 51 | <tr><th>Environment<br>Variable<th>Meaning |
| 52 | <tr><td>GATEWAY_INTERFACE<td>Always set to "CGI/1.0" |
| @@ -59,21 +60,21 @@ | |
| 59 | <td>The suffix of the URL beyond the name of the CGI script. |
| 60 | In this example: "timeline/four". |
| 61 | <tr><td>QUERY_STRING |
| 62 | <td>The query string that follows the "?" in the URL, if there is one. |
| 63 | </table> |
| 64 | <p> |
| 65 | There are other CGI environment variables beyond those listed above. |
| 66 | Many Fossil servers implement the |
| 67 | [https://fossil-scm.org/home/test_env/two/three?abc=xyz|test_env] |
| 68 | webpage that shows some of the CGI environment |
| 69 | variables that Fossil pays attention to. |
| 70 | <p> |
| 71 | In addition to setting various CGI environment variables, if the HTTP |
| 72 | request contains POST content, then the web server relays the POST content |
| 73 | to standard input of the CGI script. |
| 74 | <p> |
| 75 | In summary, the task of the |
| 76 | CGI script is to read the various CGI environment variables and |
| 77 | the POST content on standard input (if any), figure out an appropriate |
| 78 | reply, then write that reply on standard output. |
| 79 | The web server will read the output from the CGI script, reformat it |
| @@ -80,11 +81,11 @@ | |
| 80 | into an appropriate HTTP reply, and relay the result back to the |
| 81 | requesting application. |
| 82 | The CGI script exits as soon as it generates a single reply. |
| 83 | The web server will (usually) persist and handle multiple HTTP requests, |
| 84 | but a CGI script handles just one HTTP request and then exits. |
| 85 | <p> |
| 86 | The above is a rough outline of how CGI works. |
| 87 | There are many details omitted from this brief discussion. |
| 88 | See other on-line CGI tutorials for further information. |
| 89 | </blockquote> |
| 90 | <h2>How Fossil Acts As A CGI Program</h2> |
| @@ -103,33 +104,33 @@ | |
| 103 | shebang with a single argument that is the full pathname of the script |
| 104 | itself. |
| 105 | In our example, the interpreter is Fossil, and the argument might |
| 106 | be something like "/var/www/cgi-bin/one/two" (depending on how your |
| 107 | particular web server is configured). |
| 108 | <p> |
| 109 | The Fossil program that is run as the script interpreter |
| 110 | is the same Fossil that runs when |
| 111 | you type ordinary Fossil commands like "fossil sync" or "fossil commit". |
| 112 | But in this case, as soon as it launches, the Fossil program |
| 113 | recognizes that the GATEWAY_INTERFACE environment variable is |
| 114 | set to "CGI/1.0" and it therefore knows that it is being used as |
| 115 | CGI rather than as an ordinary command-line tool, and behaves accordingly. |
| 116 | <p> |
| 117 | When Fossil recognizes that it is being run as CGI, it opens and reads |
| 118 | the file identified by its sole argument (the file named by |
| 119 | <code>argv[1]</code>). In our example, the second line of that file |
| 120 | tells Fossil the location of the repository it will be serving. |
| 121 | Fossil then starts looking at the CGI environment variables to figure |
| 122 | out what web page is being requested, generates that one web page, |
| 123 | then exits. |
| 124 | <p> |
| 125 | Usually, the webpage being requested is the first term of the |
| 126 | PATH_INFO environment variable. (Exceptions to this rule are noted |
| 127 | in the sequel.) For our example, the first term of PATH_INFO |
| 128 | is "timeline", which means that Fossil will generate |
| 129 | the [/help?cmd=/timeline|/timeline] webpage. |
| 130 | <p> |
| 131 | With Fossil, terms of PATH_INFO beyond the webpage name are converted into |
| 132 | the "name" query parameter. Hence, the following two URLs mean |
| 133 | exactly the same thing to Fossil: |
| 134 | <ol type='A'> |
| 135 | <li> [https://fossil-scm.org/home/info/c14ecc43] |
| @@ -149,11 +150,11 @@ | |
| 149 | using a single CGI script. |
| 150 | On a website that wants to serve multiple repositories, one could |
| 151 | simply create multiple CGI scripts, one script for each repository. |
| 152 | But it is also possible to serve multiple Fossil repositories from |
| 153 | a single CGI script. |
| 154 | <p> |
| 155 | If the CGI script for Fossil contains a "directory:" line instead of |
| 156 | a "repository:" line, then the argument to "directory:" is the name |
| 157 | of a directory that contains multiple repository files, each ending |
| 158 | with ".fossil". For example: |
| 159 | <blockquote><pre> |
| @@ -200,44 +201,44 @@ | |
| 200 | HTTP_HOST SCRIPT_NAME PATH_INFO QUERY_STRING |
| 201 | </pre> |
| 202 | </blockquote> |
| 203 | <h2>Additional CGI Script Options</h2> |
| 204 | <blockquote> |
| 205 | <p> |
| 206 | The CGI script can have additional options used to fine-tune |
| 207 | Fossil's behavior. See the [./cgi.wiki|CGI script documentation] |
| 208 | for details. |
| 209 | </p> |
| 210 | </blockquote> |
| 211 | <h2>Additional Observations</h2> |
| 212 | <blockquote><ol type="I"> |
| 213 | <li><p> |
| 214 | Fossil does not distinguish between the various HTTP methods (GET, PUT, |
| 215 | DELETE, etc). Fossil figures out what it needs to do purely from the |
| 216 | webpage term of the URI. |
| 217 | <li><p> |
| 218 | Fossil does not distinguish between query parameters that are part of the |
| 219 | URI, application/x-www-form-urlencoded or multipart/form-data encoded |
| 220 | parameter that are part of the POST content, and cookies. Each information |
| 221 | source is seen as a space of key/value pairs which are loaded into an |
| 222 | internal property hash table. The code that runs to generate the reply |
| 223 | can then reference various properties values. |
| 224 | Fossil does not care where the value of each property comes from (POST |
| 225 | content, cookies, or query parameters) only that the property exists |
| 226 | and has a value. |
| 227 | <li><p> |
| 228 | The "[/help?cmd=ui|fossil ui]" and "[/help?cmd=server|fossil server]" commands |
| 229 | are implemented using a simple built-in web server that accepts incoming HTTP |
| 230 | requests, translates each request into a CGI invocation, then creates a |
| 231 | separate child Fossil process to handle each request. In other words, CGI |
| 232 | is used internally to implement "fossil ui/server". |
| 233 | <p> |
| 234 | SCGI is processed using the same built-in web server, just modified |
| 235 | to parse SCGI requests instead of HTTP requests. Each SCGI request is |
| 236 | converted into CGI, then Fossil creates a separate child Fossil |
| 237 | process to handle each CGI request. |
| 238 | <li><p> |
| 239 | Fossil is itself often launched using CGI. But Fossil can also then |
| 240 | turn around and launch [./serverext.wiki|sub-CGI scripts to implement |
| 241 | extensions]. |
| 242 | </ol> |
| 243 | </blockquote> |
| 244 |
| --- www/aboutcgi.wiki | |
| +++ www/aboutcgi.wiki | |
| @@ -1,19 +1,20 @@ | |
| 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 | 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 |
| 20 | that appears in the URL bar at the top of the web browser that is making |
| @@ -20,33 +21,33 @@ | |
| 21 | the request. The URL might contain a "?" character followed |
| 22 | query parameters. The HTTP will usually also contain other information |
| 23 | such as the name of the application that made the request, whether or |
| 24 | not the requesting application can accept a compressed reply, POST |
| 25 | parameters from forms, and so forth. |
| 26 | |
| 27 | The job of the web server is to interpret the HTTP request and formulate |
| 28 | an appropriate reply. |
| 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. |
| 40 | |
| 41 | Suppose the first match is <b>/one/two</b>. If <b>/one/two</b> is an |
| 42 | ordinary file in the content area, then that file is returned as static |
| 43 | content. The "<b>/timeline/four</b>" suffix is silently ignored. |
| 44 | |
| 45 | If <b>/one/two</b> is a CGI script (or program), then the web server |
| 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" |
| @@ -59,21 +60,21 @@ | |
| 60 | <td>The suffix of the URL beyond the name of the CGI script. |
| 61 | In this example: "timeline/four". |
| 62 | <tr><td>QUERY_STRING |
| 63 | <td>The query string that follows the "?" in the URL, if there is one. |
| 64 | </table> |
| 65 | |
| 66 | There are other CGI environment variables beyond those listed above. |
| 67 | Many Fossil servers implement the |
| 68 | [https://fossil-scm.org/home/test_env/two/three?abc=xyz|test_env] |
| 69 | webpage that shows some of the CGI environment |
| 70 | variables that Fossil pays attention to. |
| 71 | |
| 72 | In addition to setting various CGI environment variables, if the HTTP |
| 73 | request contains POST content, then the web server relays the POST content |
| 74 | to standard input of the CGI script. |
| 75 | |
| 76 | In summary, the task of the |
| 77 | CGI script is to read the various CGI environment variables and |
| 78 | the POST content on standard input (if any), figure out an appropriate |
| 79 | reply, then write that reply on standard output. |
| 80 | The web server will read the output from the CGI script, reformat it |
| @@ -80,11 +81,11 @@ | |
| 81 | into an appropriate HTTP reply, and relay the result back to the |
| 82 | requesting application. |
| 83 | The CGI script exits as soon as it generates a single reply. |
| 84 | The web server will (usually) persist and handle multiple HTTP requests, |
| 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> |
| @@ -103,33 +104,33 @@ | |
| 104 | shebang with a single argument that is the full pathname of the script |
| 105 | itself. |
| 106 | In our example, the interpreter is Fossil, and the argument might |
| 107 | be something like "/var/www/cgi-bin/one/two" (depending on how your |
| 108 | particular web server is configured). |
| 109 | |
| 110 | The Fossil program that is run as the script interpreter |
| 111 | is the same Fossil that runs when |
| 112 | you type ordinary Fossil commands like "fossil sync" or "fossil commit". |
| 113 | But in this case, as soon as it launches, the Fossil program |
| 114 | recognizes that the GATEWAY_INTERFACE environment variable is |
| 115 | set to "CGI/1.0" and it therefore knows that it is being used as |
| 116 | CGI rather than as an ordinary command-line tool, and behaves accordingly. |
| 117 | |
| 118 | When Fossil recognizes that it is being run as CGI, it opens and reads |
| 119 | the file identified by its sole argument (the file named by |
| 120 | <code>argv[1]</code>). In our example, the second line of that file |
| 121 | tells Fossil the location of the repository it will be serving. |
| 122 | Fossil then starts looking at the CGI environment variables to figure |
| 123 | out what web page is being requested, generates that one web page, |
| 124 | then exits. |
| 125 | |
| 126 | Usually, the webpage being requested is the first term of the |
| 127 | PATH_INFO environment variable. (Exceptions to this rule are noted |
| 128 | in the sequel.) For our example, the first term of PATH_INFO |
| 129 | is "timeline", which means that Fossil will generate |
| 130 | the [/help?cmd=/timeline|/timeline] webpage. |
| 131 | |
| 132 | With Fossil, terms of PATH_INFO beyond the webpage name are converted into |
| 133 | the "name" query parameter. Hence, the following two URLs mean |
| 134 | exactly the same thing to Fossil: |
| 135 | <ol type='A'> |
| 136 | <li> [https://fossil-scm.org/home/info/c14ecc43] |
| @@ -149,11 +150,11 @@ | |
| 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 |
| 154 | a single CGI script. |
| 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> |
| @@ -200,44 +201,44 @@ | |
| 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> |
| 219 | Fossil does not distinguish between query parameters that are part of the |
| 220 | URI, application/x-www-form-urlencoded or multipart/form-data encoded |
| 221 | parameter that are part of the POST content, and cookies. Each information |
| 222 | source is seen as a space of key/value pairs which are loaded into an |
| 223 | internal property hash table. The code that runs to generate the reply |
| 224 | can then reference various properties values. |
| 225 | Fossil does not care where the value of each property comes from (POST |
| 226 | content, cookies, or query parameters) only that the property exists |
| 227 | and has a value.</p></li> |
| 228 | <li><p> |
| 229 | The "[/help?cmd=ui|fossil ui]" and "[/help?cmd=server|fossil server]" commands |
| 230 | are implemented using a simple built-in web server that accepts incoming HTTP |
| 231 | requests, translates each request into a CGI invocation, then creates a |
| 232 | separate child Fossil process to handle each request. In other words, CGI |
| 233 | is used internally to implement "fossil ui/server". |
| 234 | <br><br> |
| 235 | SCGI is processed using the same built-in web server, just modified |
| 236 | to parse SCGI requests instead of HTTP requests. Each SCGI request is |
| 237 | converted into CGI, then Fossil creates a separate child Fossil |
| 238 | process to handle each CGI request.</p></li> |
| 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 |
+1
-1
| --- www/blockchain.md | ||
| +++ www/blockchain.md | ||
| @@ -60,11 +60,11 @@ | ||
| 60 | 60 | * **Type 2** is creation of new fraudulent currency that will pass |
| 61 | 61 | in commerce. To extend our analogy, it is the creation of new |
| 62 | 62 | US $10 bills. There are two sub-types to this fraud. In terms of |
| 63 | 63 | our analogy, they are: |
| 64 | 64 | |
| 65 | - * **Type 2a**: copying an existing legitimate $10 bill<p> | |
| 65 | + * **Type 2a**: copying an existing legitimate $10 bill<br><br> | |
| 66 | 66 | |
| 67 | 67 | * **Type 2b**: printing a new $10 bill that is unlike an existing |
| 68 | 68 | legitimate one, yet which will still pass in commerce |
| 69 | 69 | |
| 70 | 70 | * **Type 3** is double-spending existing legitimate cryptocurrency. |
| 71 | 71 |
| --- www/blockchain.md | |
| +++ www/blockchain.md | |
| @@ -60,11 +60,11 @@ | |
| 60 | * **Type 2** is creation of new fraudulent currency that will pass |
| 61 | in commerce. To extend our analogy, it is the creation of new |
| 62 | US $10 bills. There are two sub-types to this fraud. In terms of |
| 63 | our analogy, they are: |
| 64 | |
| 65 | * **Type 2a**: copying an existing legitimate $10 bill<p> |
| 66 | |
| 67 | * **Type 2b**: printing a new $10 bill that is unlike an existing |
| 68 | legitimate one, yet which will still pass in commerce |
| 69 | |
| 70 | * **Type 3** is double-spending existing legitimate cryptocurrency. |
| 71 |
| --- www/blockchain.md | |
| +++ www/blockchain.md | |
| @@ -60,11 +60,11 @@ | |
| 60 | * **Type 2** is creation of new fraudulent currency that will pass |
| 61 | in commerce. To extend our analogy, it is the creation of new |
| 62 | US $10 bills. There are two sub-types to this fraud. In terms of |
| 63 | our analogy, they are: |
| 64 | |
| 65 | * **Type 2a**: copying an existing legitimate $10 bill<br><br> |
| 66 | |
| 67 | * **Type 2b**: printing a new $10 bill that is unlike an existing |
| 68 | legitimate one, yet which will still pass in commerce |
| 69 | |
| 70 | * **Type 3** is double-spending existing legitimate cryptocurrency. |
| 71 |
+56
-47
| --- www/build.wiki | ||
| +++ www/build.wiki | ||
| @@ -1,57 +1,57 @@ | ||
| 1 | 1 | <title>Compiling and Installing Fossil</title> |
| 2 | 2 | |
| 3 | 3 | <h2>0.0 Using A Pre-compiled Binary</h2> |
| 4 | 4 | |
| 5 | -<p>[/uv/download.html|Pre-compiled binaries] are available for recent | |
| 5 | +[/uv/download.html|Pre-compiled binaries] are available for recent | |
| 6 | 6 | releases. Just download |
| 7 | 7 | the appropriate executable for your platform |
| 8 | 8 | and put it on your $PATH. |
| 9 | 9 | To uninstall, simply delete the executable. |
| 10 | 10 | To upgrade from an older release, just overwrite the older binary with |
| 11 | -the newer one.</p> | |
| 11 | +the newer one. | |
| 12 | 12 | |
| 13 | -<p>For details about how those binaries are built, see | |
| 14 | -[/wiki?name=Release+Build+How-To | the Release Build How-To wiki page].</p> | |
| 13 | +For details about how those binaries are built, see | |
| 14 | +[/wiki?name=Release+Build+How-To | the Release Build How-To wiki page]. | |
| 15 | 15 | |
| 16 | 16 | |
| 17 | 17 | <h2>0.1 Executive Summary</h2> |
| 18 | 18 | |
| 19 | -<p>Building and installing is very simple. Three steps:</p> | |
| 19 | +Building and installing is very simple. Three steps: | |
| 20 | 20 | |
| 21 | 21 | <ol> |
| 22 | 22 | <li> Download and unpack a source tarball or ZIP. |
| 23 | 23 | <li> <b>./configure; make</b> |
| 24 | 24 | <li> Move the resulting "fossil" or "fossil.exe" executable to someplace on |
| 25 | 25 | your $PATH. |
| 26 | 26 | </ol> |
| 27 | 27 | |
| 28 | -<p><hr> | |
| 28 | +<hr> | |
| 29 | 29 | |
| 30 | 30 | <h2>1.0 Obtaining The Source Code</h2> |
| 31 | 31 | |
| 32 | -<p>Fossil is self-hosting, so you can obtain a ZIP archive or tarball | |
| 32 | +Fossil is self-hosting, so you can obtain a ZIP archive or tarball | |
| 33 | 33 | containing a snapshot of the <em>latest</em> version directly from |
| 34 | 34 | Fossil's own fossil repository. Additionally, source archives of |
| 35 | 35 | <em>released</em> versions of |
| 36 | 36 | fossil are available from the [/uv/download.html|downloads page]. |
| 37 | -To obtain a development version of fossil, follow these steps:</p> | |
| 37 | +To obtain a development version of fossil, follow these steps: | |
| 38 | 38 | |
| 39 | 39 | <ol> |
| 40 | -<li><p>Point your web browser to [https://fossil-scm.org/]</li> | |
| 40 | +<li>Point your web browser to [https://fossil-scm.org/]</li> | |
| 41 | 41 | |
| 42 | -<li><p>Click on the [/timeline|Timeline] | |
| 43 | -link at the top of the page.</p></li> | |
| 42 | +<li>Click on the [/timeline|Timeline] | |
| 43 | +link at the top of the page.</li> | |
| 44 | 44 | |
| 45 | -<li><p>Select a version of of Fossil you want to download. The latest | |
| 45 | +<li>Select a version of of Fossil you want to download. The latest | |
| 46 | 46 | version on the trunk branch is usually a good choice. Click on its |
| 47 | -link.</p></li> | |
| 47 | +link.</li> | |
| 48 | 48 | |
| 49 | -<li><p>Finally, click on one of the | |
| 49 | +<li>Finally, click on one of the | |
| 50 | 50 | "Zip Archive" or "Tarball" links, according to your preference. |
| 51 | 51 | These link will build a ZIP archive or a gzip-compressed tarball of the |
| 52 | -complete source code and download it to your computer. | |
| 52 | +complete source code and download it to your computer.</li> | |
| 53 | 53 | </ol> |
| 54 | 54 | |
| 55 | 55 | <h2>Aside: Is it really safe to use an unreleased development version of |
| 56 | 56 | the Fossil source code?</h2> |
| 57 | 57 | |
| @@ -74,78 +74,82 @@ | ||
| 74 | 74 | |
| 75 | 75 | <h2>2.0 Compiling</h2> |
| 76 | 76 | |
| 77 | 77 | <ol> |
| 78 | 78 | <li value="5"> |
| 79 | -<p>Unpack the ZIP or tarball you downloaded then | |
| 80 | -<b>cd</b> into the directory created.</p></li> | |
| 79 | +Unpack the ZIP or tarball you downloaded then | |
| 80 | +<b>cd</b> into the directory created.</li> | |
| 81 | 81 | |
| 82 | 82 | <li><i>(Optional, Debian-compatible Linux only)</i> |
| 83 | 83 | Make sure you have all the necessary tools and libraries at hand by running: |
| 84 | 84 | <b>sudo apt install tcl-dev tk libssl-dev zlib1g-dev</b>. |
| 85 | 85 | |
| 86 | 86 | <li><i>(Optional, Unix only)</i> |
| 87 | 87 | Run <b>./configure</b> to construct a makefile. |
| 88 | 88 | |
| 89 | 89 | <ol type="a"> |
| 90 | -<li><p> | |
| 90 | +<li> | |
| 91 | 91 | The build system for Fossil on Unix-like systems assumes that the |
| 92 | 92 | OpenSSL development and runtime files are available on your system, |
| 93 | 93 | because unprotected repositories are trivial to attack otherwise. |
| 94 | 94 | Indeed, some public Fossil repositories — including Fossil's own — today |
| 95 | 95 | run in an HTTPS-only mode, so that you can't even do an anonymous clone |
| 96 | 96 | from them without using the TLS features added to Fossil by OpenSSL. To |
| 97 | 97 | weaken that stance could allow a |
| 98 | 98 | [https://en.wikipedia.org/wiki/Man-in-the-middle_attack|man in the |
| 99 | 99 | middle attack], such as one that substitutes malicious code into your |
| 100 | -Fossil repository clone.</p> | |
| 100 | +Fossil repository clone. | |
| 101 | 101 | |
| 102 | -<p>You can force the Fossil build system to avoid searching for, building | |
| 102 | +You can force the Fossil build system to avoid searching for, building | |
| 103 | 103 | against, and linking to the OpenSSL library by passing |
| 104 | -<b>--with-openssl=none</b> to the <tt>configure</tt> script.</p> | |
| 104 | +<b>--with-openssl=none</b> to the <tt>configure</tt> script. | |
| 105 | 105 | |
| 106 | -<p>If you do not have the OpenSSL development libraries on your system, | |
| 106 | +If you do not have the OpenSSL development libraries on your system, | |
| 107 | 107 | we recommend that you install them, typically via your OS's package |
| 108 | 108 | manager. The Fossil build system goes to a lot of effort to seek these |
| 109 | 109 | out wherever they may be found, so that is typically all you need to |
| 110 | -do.</p> | |
| 110 | +do. | |
| 111 | 111 | |
| 112 | -<p>For more advanced use cases, see the [./ssl.wiki#openssl-bin|OpenSSL | |
| 113 | -discussion in the "TLS and Fossil" document].</p> | |
| 112 | +For more advanced use cases, see the [./ssl.wiki#openssl-bin|OpenSSL | |
| 113 | +discussion in the "TLS and Fossil" document]. | |
| 114 | +</li> | |
| 114 | 115 | |
| 115 | -<li><p> | |
| 116 | +<li> | |
| 116 | 117 | To build a statically linked binary, you can <i>try</i> adding |
| 117 | 118 | the <b>--static</b> option, but |
| 118 | 119 | [https://stackoverflow.com/questions/3430400/linux-static-linking-is-dead |
| 119 | 120 | | it may well not work]. If your platform of choice is affected by this, |
| 120 | 121 | the simplest workaround we're aware of is to build a Fossil container, |
| 121 | 122 | then [./containers.md#static | extract the static executable from it]. |
| 123 | +</li> | |
| 122 | 124 | |
| 123 | -<li><p> | |
| 125 | +<li> | |
| 124 | 126 | To enable the native [./th1.md#tclEval | Tcl integration feature] feature, |
| 125 | 127 | add the <b>--with-tcl=1</b> and <b>--with-tcl-private-stubs=1</b> options. |
| 128 | +</li> | |
| 126 | 129 | |
| 127 | -<li><p> | |
| 130 | +<li> | |
| 128 | 131 | Other configuration options can be seen by running |
| 129 | 132 | <b>./configure --help</b> |
| 133 | +</li> | |
| 130 | 134 | </ol> |
| 131 | 135 | |
| 132 | -<li><p>Run "<b>make</b>" to build the "fossil" or "fossil.exe" executable. | |
| 133 | -The details depend on your platform and compiler. | |
| 136 | +<li>Run "<b>make</b>" to build the "fossil" or "fossil.exe" executable. | |
| 137 | +The details depend on your platform and compiler.</li> | |
| 134 | 138 | |
| 135 | 139 | <ol type="a"> |
| 136 | -<li><p><i>Unix</i> → the configure-generated Makefile should work on | |
| 137 | -all Unix and Unix-like systems. Simply type "<b>make</b>". | |
| 140 | +<li><i>Unix</i> → the configure-generated Makefile should work on | |
| 141 | +all Unix and Unix-like systems. Simply type "<b>make</b>".</li> | |
| 138 | 142 | |
| 139 | -<li><p><i>Unix without running "configure"</i> → if you prefer to avoid | |
| 143 | +<li><i>Unix without running "configure"</i> → if you prefer to avoid | |
| 140 | 144 | running configure, you can also use: <b>make -f Makefile.classic</b>. You may |
| 141 | 145 | want to make minor edits to Makefile.classic to configure the build for your |
| 142 | -system. | |
| 146 | +system.</li> | |
| 143 | 147 | |
| 144 | -<li><p><i>MinGW / MinGW-w64</i> → The best-supported path is to build | |
| 148 | +<li><i>MinGW / MinGW-w64</i> → The best-supported path is to build | |
| 145 | 149 | via the MinGW specific Makefile under a POSIX build of GNU make: |
| 146 | -"<b>make -f win/Makefile.mingw</b>". | |
| 150 | +"<b>make -f win/Makefile.mingw</b>".</li> | |
| 147 | 151 | |
| 148 | 152 | There is limited support for building under MinGW's native Windows port |
| 149 | 153 | of GNU Make instead by defining the <tt>USE_WINDOWS=1</tt> variable, but |
| 150 | 154 | it's better to build under MSYS, Cygwin, or WSL on Windows since this |
| 151 | 155 | mode doesn't take care of cases such as the "openssl" target, which |
| @@ -170,11 +174,11 @@ | ||
| 170 | 174 | Alternatively, running <b>./configure</b> under MSYS should give a |
| 171 | 175 | suitable top-level Makefile. However, options passed to configure that are |
| 172 | 176 | not applicable on Windows may cause the configuration or compilation to fail |
| 173 | 177 | (e.g. fusefs, internal-sqlite, etc). |
| 174 | 178 | |
| 175 | -<li><p><i>MSVC</i> → Use the MSVC makefile. | |
| 179 | +<li><i>MSVC</i> → Use the MSVC makefile.</li> | |
| 176 | 180 | |
| 177 | 181 | Run all of the following from a "x64 Native Tools Command Prompt". |
| 178 | 182 | |
| 179 | 183 | First |
| 180 | 184 | change to the "win/" subdirectory ("<b>cd win</b>") then run |
| @@ -202,58 +206,63 @@ | ||
| 202 | 206 | </pre></blockquote> |
| 203 | 207 | <blockquote><pre> |
| 204 | 208 | buildmsvc.bat FOSSIL_ENABLE_TCL=1 |
| 205 | 209 | </pre></blockquote> |
| 206 | 210 | |
| 207 | -<li><p><i>Cygwin</i> → The same as other Unix-like systems. It is | |
| 211 | +<li><i>Cygwin</i> → The same as other Unix-like systems. It is | |
| 208 | 212 | recommended to configure using: "<b>configure --disable-internal-sqlite</b>", |
| 209 | 213 | making sure you have the "libsqlite3-devel" , "zlib-devel" and |
| 210 | -"openssl-devel" packages installed first. | |
| 214 | +"openssl-devel" packages installed first.</li> | |
| 211 | 215 | </ol> |
| 212 | 216 | </ol> |
| 213 | 217 | |
| 214 | 218 | <h2>3.0 Installing</h2> |
| 215 | 219 | |
| 216 | 220 | <ol> |
| 217 | 221 | <li value="9"> |
| 218 | -<p>The finished binary is named "fossil" (or "fossil.exe" on Windows). | |
| 222 | +The finished binary is named "fossil" (or "fossil.exe" on Windows). | |
| 219 | 223 | Put this binary in a |
| 220 | 224 | directory that is somewhere on your PATH environment variable. |
| 221 | -It does not matter where.</p> | |
| 225 | +It does not matter where. | |
| 226 | +</li> | |
| 222 | 227 | |
| 223 | 228 | <li> |
| 224 | -<p><b>(Optional:)</b> | |
| 225 | -To uninstall, just delete the binary.</p> | |
| 229 | +<b>(Optional:)</b> | |
| 230 | +To uninstall, just delete the binary. | |
| 231 | +</li> | |
| 226 | 232 | </ol> |
| 227 | 233 | |
| 228 | 234 | <h2>4.0 Additional Considerations</h2> |
| 229 | 235 | |
| 230 | 236 | <ul> |
| 231 | -<li><p> | |
| 237 | +<li> | |
| 232 | 238 | If the makefiles that come with Fossil do not work for |
| 233 | 239 | you, or for some other reason you want to know how to build |
| 234 | 240 | Fossil manually, then refer to the |
| 235 | 241 | [./makefile.wiki | Fossil Build Process] document which describes |
| 236 | 242 | in detail what the makefiles do behind the scenes. |
| 243 | +</li> | |
| 237 | 244 | |
| 238 | -<li><p> | |
| 245 | +<li> | |
| 239 | 246 | The fossil executable is self-contained and stand-alone and usually |
| 240 | 247 | requires no special libraries or other software to be installed. However, |
| 241 | 248 | the "--tk" option to the [/help/diff|diff command] requires that Tcl/Tk |
| 242 | 249 | be installed on the local machine. You can get Tcl/Tk from |
| 243 | 250 | [http://www.activestate.com/activetcl|ActiveState]. |
| 251 | +</li> | |
| 244 | 252 | |
| 245 | -<li><p> | |
| 253 | +<li> | |
| 246 | 254 | To build on older Macs (circa 2002, MacOS 10.2) edit the Makefile |
| 247 | 255 | generated by configure to add the following lines: |
| 248 | 256 | <blockquote><pre> |
| 249 | 257 | TCC += -DSQLITE_WITHOUT_ZONEMALLOC |
| 250 | 258 | TCC += -D_BSD_SOURCE |
| 251 | 259 | TCC += -DWITHOUT_ICONV |
| 252 | 260 | TCC += -Dsocketlen_t=int |
| 253 | 261 | TCC += -DSQLITE_MAX_MMAP_SIZE=0 |
| 254 | -</pre></blockquote> | |
| 262 | + </pre></blockquote> | |
| 263 | +</li> | |
| 255 | 264 | </ul> |
| 256 | 265 | |
| 257 | 266 | |
| 258 | 267 | <h2 id="docker" name="oci">5.0 Building a Docker Container</h2> |
| 259 | 268 | |
| 260 | 269 |
| --- www/build.wiki | |
| +++ www/build.wiki | |
| @@ -1,57 +1,57 @@ | |
| 1 | <title>Compiling and Installing Fossil</title> |
| 2 | |
| 3 | <h2>0.0 Using A Pre-compiled Binary</h2> |
| 4 | |
| 5 | <p>[/uv/download.html|Pre-compiled binaries] are available for recent |
| 6 | releases. Just download |
| 7 | the appropriate executable for your platform |
| 8 | and put it on your $PATH. |
| 9 | To uninstall, simply delete the executable. |
| 10 | To upgrade from an older release, just overwrite the older binary with |
| 11 | the newer one.</p> |
| 12 | |
| 13 | <p>For details about how those binaries are built, see |
| 14 | [/wiki?name=Release+Build+How-To | the Release Build How-To wiki page].</p> |
| 15 | |
| 16 | |
| 17 | <h2>0.1 Executive Summary</h2> |
| 18 | |
| 19 | <p>Building and installing is very simple. Three steps:</p> |
| 20 | |
| 21 | <ol> |
| 22 | <li> Download and unpack a source tarball or ZIP. |
| 23 | <li> <b>./configure; make</b> |
| 24 | <li> Move the resulting "fossil" or "fossil.exe" executable to someplace on |
| 25 | your $PATH. |
| 26 | </ol> |
| 27 | |
| 28 | <p><hr> |
| 29 | |
| 30 | <h2>1.0 Obtaining The Source Code</h2> |
| 31 | |
| 32 | <p>Fossil is self-hosting, so you can obtain a ZIP archive or tarball |
| 33 | containing a snapshot of the <em>latest</em> version directly from |
| 34 | Fossil's own fossil repository. Additionally, source archives of |
| 35 | <em>released</em> versions of |
| 36 | fossil are available from the [/uv/download.html|downloads page]. |
| 37 | To obtain a development version of fossil, follow these steps:</p> |
| 38 | |
| 39 | <ol> |
| 40 | <li><p>Point your web browser to [https://fossil-scm.org/]</li> |
| 41 | |
| 42 | <li><p>Click on the [/timeline|Timeline] |
| 43 | link at the top of the page.</p></li> |
| 44 | |
| 45 | <li><p>Select a version of of Fossil you want to download. The latest |
| 46 | version on the trunk branch is usually a good choice. Click on its |
| 47 | link.</p></li> |
| 48 | |
| 49 | <li><p>Finally, click on one of the |
| 50 | "Zip Archive" or "Tarball" links, according to your preference. |
| 51 | These link will build a ZIP archive or a gzip-compressed tarball of the |
| 52 | complete source code and download it to your computer. |
| 53 | </ol> |
| 54 | |
| 55 | <h2>Aside: Is it really safe to use an unreleased development version of |
| 56 | the Fossil source code?</h2> |
| 57 | |
| @@ -74,78 +74,82 @@ | |
| 74 | |
| 75 | <h2>2.0 Compiling</h2> |
| 76 | |
| 77 | <ol> |
| 78 | <li value="5"> |
| 79 | <p>Unpack the ZIP or tarball you downloaded then |
| 80 | <b>cd</b> into the directory created.</p></li> |
| 81 | |
| 82 | <li><i>(Optional, Debian-compatible Linux only)</i> |
| 83 | Make sure you have all the necessary tools and libraries at hand by running: |
| 84 | <b>sudo apt install tcl-dev tk libssl-dev zlib1g-dev</b>. |
| 85 | |
| 86 | <li><i>(Optional, Unix only)</i> |
| 87 | Run <b>./configure</b> to construct a makefile. |
| 88 | |
| 89 | <ol type="a"> |
| 90 | <li><p> |
| 91 | The build system for Fossil on Unix-like systems assumes that the |
| 92 | OpenSSL development and runtime files are available on your system, |
| 93 | because unprotected repositories are trivial to attack otherwise. |
| 94 | Indeed, some public Fossil repositories — including Fossil's own — today |
| 95 | run in an HTTPS-only mode, so that you can't even do an anonymous clone |
| 96 | from them without using the TLS features added to Fossil by OpenSSL. To |
| 97 | weaken that stance could allow a |
| 98 | [https://en.wikipedia.org/wiki/Man-in-the-middle_attack|man in the |
| 99 | middle attack], such as one that substitutes malicious code into your |
| 100 | Fossil repository clone.</p> |
| 101 | |
| 102 | <p>You can force the Fossil build system to avoid searching for, building |
| 103 | against, and linking to the OpenSSL library by passing |
| 104 | <b>--with-openssl=none</b> to the <tt>configure</tt> script.</p> |
| 105 | |
| 106 | <p>If you do not have the OpenSSL development libraries on your system, |
| 107 | we recommend that you install them, typically via your OS's package |
| 108 | manager. The Fossil build system goes to a lot of effort to seek these |
| 109 | out wherever they may be found, so that is typically all you need to |
| 110 | do.</p> |
| 111 | |
| 112 | <p>For more advanced use cases, see the [./ssl.wiki#openssl-bin|OpenSSL |
| 113 | discussion in the "TLS and Fossil" document].</p> |
| 114 | |
| 115 | <li><p> |
| 116 | To build a statically linked binary, you can <i>try</i> adding |
| 117 | the <b>--static</b> option, but |
| 118 | [https://stackoverflow.com/questions/3430400/linux-static-linking-is-dead |
| 119 | | it may well not work]. If your platform of choice is affected by this, |
| 120 | the simplest workaround we're aware of is to build a Fossil container, |
| 121 | then [./containers.md#static | extract the static executable from it]. |
| 122 | |
| 123 | <li><p> |
| 124 | To enable the native [./th1.md#tclEval | Tcl integration feature] feature, |
| 125 | add the <b>--with-tcl=1</b> and <b>--with-tcl-private-stubs=1</b> options. |
| 126 | |
| 127 | <li><p> |
| 128 | Other configuration options can be seen by running |
| 129 | <b>./configure --help</b> |
| 130 | </ol> |
| 131 | |
| 132 | <li><p>Run "<b>make</b>" to build the "fossil" or "fossil.exe" executable. |
| 133 | The details depend on your platform and compiler. |
| 134 | |
| 135 | <ol type="a"> |
| 136 | <li><p><i>Unix</i> → the configure-generated Makefile should work on |
| 137 | all Unix and Unix-like systems. Simply type "<b>make</b>". |
| 138 | |
| 139 | <li><p><i>Unix without running "configure"</i> → if you prefer to avoid |
| 140 | running configure, you can also use: <b>make -f Makefile.classic</b>. You may |
| 141 | want to make minor edits to Makefile.classic to configure the build for your |
| 142 | system. |
| 143 | |
| 144 | <li><p><i>MinGW / MinGW-w64</i> → The best-supported path is to build |
| 145 | via the MinGW specific Makefile under a POSIX build of GNU make: |
| 146 | "<b>make -f win/Makefile.mingw</b>". |
| 147 | |
| 148 | There is limited support for building under MinGW's native Windows port |
| 149 | of GNU Make instead by defining the <tt>USE_WINDOWS=1</tt> variable, but |
| 150 | it's better to build under MSYS, Cygwin, or WSL on Windows since this |
| 151 | mode doesn't take care of cases such as the "openssl" target, which |
| @@ -170,11 +174,11 @@ | |
| 170 | Alternatively, running <b>./configure</b> under MSYS should give a |
| 171 | suitable top-level Makefile. However, options passed to configure that are |
| 172 | not applicable on Windows may cause the configuration or compilation to fail |
| 173 | (e.g. fusefs, internal-sqlite, etc). |
| 174 | |
| 175 | <li><p><i>MSVC</i> → Use the MSVC makefile. |
| 176 | |
| 177 | Run all of the following from a "x64 Native Tools Command Prompt". |
| 178 | |
| 179 | First |
| 180 | change to the "win/" subdirectory ("<b>cd win</b>") then run |
| @@ -202,58 +206,63 @@ | |
| 202 | </pre></blockquote> |
| 203 | <blockquote><pre> |
| 204 | buildmsvc.bat FOSSIL_ENABLE_TCL=1 |
| 205 | </pre></blockquote> |
| 206 | |
| 207 | <li><p><i>Cygwin</i> → The same as other Unix-like systems. It is |
| 208 | recommended to configure using: "<b>configure --disable-internal-sqlite</b>", |
| 209 | making sure you have the "libsqlite3-devel" , "zlib-devel" and |
| 210 | "openssl-devel" packages installed first. |
| 211 | </ol> |
| 212 | </ol> |
| 213 | |
| 214 | <h2>3.0 Installing</h2> |
| 215 | |
| 216 | <ol> |
| 217 | <li value="9"> |
| 218 | <p>The finished binary is named "fossil" (or "fossil.exe" on Windows). |
| 219 | Put this binary in a |
| 220 | directory that is somewhere on your PATH environment variable. |
| 221 | It does not matter where.</p> |
| 222 | |
| 223 | <li> |
| 224 | <p><b>(Optional:)</b> |
| 225 | To uninstall, just delete the binary.</p> |
| 226 | </ol> |
| 227 | |
| 228 | <h2>4.0 Additional Considerations</h2> |
| 229 | |
| 230 | <ul> |
| 231 | <li><p> |
| 232 | If the makefiles that come with Fossil do not work for |
| 233 | you, or for some other reason you want to know how to build |
| 234 | Fossil manually, then refer to the |
| 235 | [./makefile.wiki | Fossil Build Process] document which describes |
| 236 | in detail what the makefiles do behind the scenes. |
| 237 | |
| 238 | <li><p> |
| 239 | The fossil executable is self-contained and stand-alone and usually |
| 240 | requires no special libraries or other software to be installed. However, |
| 241 | the "--tk" option to the [/help/diff|diff command] requires that Tcl/Tk |
| 242 | be installed on the local machine. You can get Tcl/Tk from |
| 243 | [http://www.activestate.com/activetcl|ActiveState]. |
| 244 | |
| 245 | <li><p> |
| 246 | To build on older Macs (circa 2002, MacOS 10.2) edit the Makefile |
| 247 | generated by configure to add the following lines: |
| 248 | <blockquote><pre> |
| 249 | TCC += -DSQLITE_WITHOUT_ZONEMALLOC |
| 250 | TCC += -D_BSD_SOURCE |
| 251 | TCC += -DWITHOUT_ICONV |
| 252 | TCC += -Dsocketlen_t=int |
| 253 | TCC += -DSQLITE_MAX_MMAP_SIZE=0 |
| 254 | </pre></blockquote> |
| 255 | </ul> |
| 256 | |
| 257 | |
| 258 | <h2 id="docker" name="oci">5.0 Building a Docker Container</h2> |
| 259 | |
| 260 |
| --- www/build.wiki | |
| +++ www/build.wiki | |
| @@ -1,57 +1,57 @@ | |
| 1 | <title>Compiling and Installing Fossil</title> |
| 2 | |
| 3 | <h2>0.0 Using A Pre-compiled Binary</h2> |
| 4 | |
| 5 | [/uv/download.html|Pre-compiled binaries] are available for recent |
| 6 | releases. Just download |
| 7 | the appropriate executable for your platform |
| 8 | and put it on your $PATH. |
| 9 | To uninstall, simply delete the executable. |
| 10 | To upgrade from an older release, just overwrite the older binary with |
| 11 | the newer one. |
| 12 | |
| 13 | For details about how those binaries are built, see |
| 14 | [/wiki?name=Release+Build+How-To | the Release Build How-To wiki page]. |
| 15 | |
| 16 | |
| 17 | <h2>0.1 Executive Summary</h2> |
| 18 | |
| 19 | Building and installing is very simple. Three steps: |
| 20 | |
| 21 | <ol> |
| 22 | <li> Download and unpack a source tarball or ZIP. |
| 23 | <li> <b>./configure; make</b> |
| 24 | <li> Move the resulting "fossil" or "fossil.exe" executable to someplace on |
| 25 | your $PATH. |
| 26 | </ol> |
| 27 | |
| 28 | <hr> |
| 29 | |
| 30 | <h2>1.0 Obtaining The Source Code</h2> |
| 31 | |
| 32 | Fossil is self-hosting, so you can obtain a ZIP archive or tarball |
| 33 | containing a snapshot of the <em>latest</em> version directly from |
| 34 | Fossil's own fossil repository. Additionally, source archives of |
| 35 | <em>released</em> versions of |
| 36 | fossil are available from the [/uv/download.html|downloads page]. |
| 37 | To obtain a development version of fossil, follow these steps: |
| 38 | |
| 39 | <ol> |
| 40 | <li>Point your web browser to [https://fossil-scm.org/]</li> |
| 41 | |
| 42 | <li>Click on the [/timeline|Timeline] |
| 43 | link at the top of the page.</li> |
| 44 | |
| 45 | <li>Select a version of of Fossil you want to download. The latest |
| 46 | version on the trunk branch is usually a good choice. Click on its |
| 47 | link.</li> |
| 48 | |
| 49 | <li>Finally, click on one of the |
| 50 | "Zip Archive" or "Tarball" links, according to your preference. |
| 51 | These link will build a ZIP archive or a gzip-compressed tarball of the |
| 52 | complete source code and download it to your computer.</li> |
| 53 | </ol> |
| 54 | |
| 55 | <h2>Aside: Is it really safe to use an unreleased development version of |
| 56 | the Fossil source code?</h2> |
| 57 | |
| @@ -74,78 +74,82 @@ | |
| 74 | |
| 75 | <h2>2.0 Compiling</h2> |
| 76 | |
| 77 | <ol> |
| 78 | <li value="5"> |
| 79 | Unpack the ZIP or tarball you downloaded then |
| 80 | <b>cd</b> into the directory created.</li> |
| 81 | |
| 82 | <li><i>(Optional, Debian-compatible Linux only)</i> |
| 83 | Make sure you have all the necessary tools and libraries at hand by running: |
| 84 | <b>sudo apt install tcl-dev tk libssl-dev zlib1g-dev</b>. |
| 85 | |
| 86 | <li><i>(Optional, Unix only)</i> |
| 87 | Run <b>./configure</b> to construct a makefile. |
| 88 | |
| 89 | <ol type="a"> |
| 90 | <li> |
| 91 | The build system for Fossil on Unix-like systems assumes that the |
| 92 | OpenSSL development and runtime files are available on your system, |
| 93 | because unprotected repositories are trivial to attack otherwise. |
| 94 | Indeed, some public Fossil repositories — including Fossil's own — today |
| 95 | run in an HTTPS-only mode, so that you can't even do an anonymous clone |
| 96 | from them without using the TLS features added to Fossil by OpenSSL. To |
| 97 | weaken that stance could allow a |
| 98 | [https://en.wikipedia.org/wiki/Man-in-the-middle_attack|man in the |
| 99 | middle attack], such as one that substitutes malicious code into your |
| 100 | Fossil repository clone. |
| 101 | |
| 102 | You can force the Fossil build system to avoid searching for, building |
| 103 | against, and linking to the OpenSSL library by passing |
| 104 | <b>--with-openssl=none</b> to the <tt>configure</tt> script. |
| 105 | |
| 106 | If you do not have the OpenSSL development libraries on your system, |
| 107 | we recommend that you install them, typically via your OS's package |
| 108 | manager. The Fossil build system goes to a lot of effort to seek these |
| 109 | out wherever they may be found, so that is typically all you need to |
| 110 | do. |
| 111 | |
| 112 | For more advanced use cases, see the [./ssl.wiki#openssl-bin|OpenSSL |
| 113 | discussion in the "TLS and Fossil" document]. |
| 114 | </li> |
| 115 | |
| 116 | <li> |
| 117 | To build a statically linked binary, you can <i>try</i> adding |
| 118 | the <b>--static</b> option, but |
| 119 | [https://stackoverflow.com/questions/3430400/linux-static-linking-is-dead |
| 120 | | it may well not work]. If your platform of choice is affected by this, |
| 121 | the simplest workaround we're aware of is to build a Fossil container, |
| 122 | then [./containers.md#static | extract the static executable from it]. |
| 123 | </li> |
| 124 | |
| 125 | <li> |
| 126 | To enable the native [./th1.md#tclEval | Tcl integration feature] feature, |
| 127 | add the <b>--with-tcl=1</b> and <b>--with-tcl-private-stubs=1</b> options. |
| 128 | </li> |
| 129 | |
| 130 | <li> |
| 131 | Other configuration options can be seen by running |
| 132 | <b>./configure --help</b> |
| 133 | </li> |
| 134 | </ol> |
| 135 | |
| 136 | <li>Run "<b>make</b>" to build the "fossil" or "fossil.exe" executable. |
| 137 | The details depend on your platform and compiler.</li> |
| 138 | |
| 139 | <ol type="a"> |
| 140 | <li><i>Unix</i> → the configure-generated Makefile should work on |
| 141 | all Unix and Unix-like systems. Simply type "<b>make</b>".</li> |
| 142 | |
| 143 | <li><i>Unix without running "configure"</i> → if you prefer to avoid |
| 144 | running configure, you can also use: <b>make -f Makefile.classic</b>. You may |
| 145 | want to make minor edits to Makefile.classic to configure the build for your |
| 146 | system.</li> |
| 147 | |
| 148 | <li><i>MinGW / MinGW-w64</i> → The best-supported path is to build |
| 149 | via the MinGW specific Makefile under a POSIX build of GNU make: |
| 150 | "<b>make -f win/Makefile.mingw</b>".</li> |
| 151 | |
| 152 | There is limited support for building under MinGW's native Windows port |
| 153 | of GNU Make instead by defining the <tt>USE_WINDOWS=1</tt> variable, but |
| 154 | it's better to build under MSYS, Cygwin, or WSL on Windows since this |
| 155 | mode doesn't take care of cases such as the "openssl" target, which |
| @@ -170,11 +174,11 @@ | |
| 174 | Alternatively, running <b>./configure</b> under MSYS should give a |
| 175 | suitable top-level Makefile. However, options passed to configure that are |
| 176 | not applicable on Windows may cause the configuration or compilation to fail |
| 177 | (e.g. fusefs, internal-sqlite, etc). |
| 178 | |
| 179 | <li><i>MSVC</i> → Use the MSVC makefile.</li> |
| 180 | |
| 181 | Run all of the following from a "x64 Native Tools Command Prompt". |
| 182 | |
| 183 | First |
| 184 | change to the "win/" subdirectory ("<b>cd win</b>") then run |
| @@ -202,58 +206,63 @@ | |
| 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> |
| 215 | </ol> |
| 216 | </ol> |
| 217 | |
| 218 | <h2>3.0 Installing</h2> |
| 219 | |
| 220 | <ol> |
| 221 | <li value="9"> |
| 222 | The finished binary is named "fossil" (or "fossil.exe" on Windows). |
| 223 | Put this binary in a |
| 224 | directory that is somewhere on your PATH environment variable. |
| 225 | It does not matter where. |
| 226 | </li> |
| 227 | |
| 228 | <li> |
| 229 | <b>(Optional:)</b> |
| 230 | To uninstall, just delete the binary. |
| 231 | </li> |
| 232 | </ol> |
| 233 | |
| 234 | <h2>4.0 Additional Considerations</h2> |
| 235 | |
| 236 | <ul> |
| 237 | <li> |
| 238 | If the makefiles that come with Fossil do not work for |
| 239 | you, or for some other reason you want to know how to build |
| 240 | Fossil manually, then refer to the |
| 241 | [./makefile.wiki | Fossil Build Process] document which describes |
| 242 | in detail what the makefiles do behind the scenes. |
| 243 | </li> |
| 244 | |
| 245 | <li> |
| 246 | The fossil executable is self-contained and stand-alone and usually |
| 247 | requires no special libraries or other software to be installed. However, |
| 248 | the "--tk" option to the [/help/diff|diff command] requires that Tcl/Tk |
| 249 | be installed on the local machine. You can get Tcl/Tk from |
| 250 | [http://www.activestate.com/activetcl|ActiveState]. |
| 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> |
| 268 | |
| 269 |
+22
-24
| --- www/concepts.wiki | ||
| +++ www/concepts.wiki | ||
| @@ -159,33 +159,33 @@ | ||
| 159 | 159 | of the manifest is the identifier for the entire check-in. When |
| 160 | 160 | you look at a "timeline" of changes in Fossil, the ID associated |
| 161 | 161 | with each check-in or commit is really just the artifact ID of the |
| 162 | 162 | manifest for that check-in. |
| 163 | 163 | |
| 164 | -<p>The manifest file is not normally a real file on disk. Instead, | |
| 164 | +The manifest file is not normally a real file on disk. Instead, | |
| 165 | 165 | the manifest is computed in memory by Fossil whenever it needs it. |
| 166 | 166 | However, the "fossil setting manifest on" command will cause the |
| 167 | 167 | manifest file to be materialized to disk, if desired. Both Fossil |
| 168 | 168 | itself, and SQLite cause the manifest file to be materialized to disk |
| 169 | 169 | so that the makefiles for these project can read the manifest and |
| 170 | 170 | embed version information in generated binaries. |
| 171 | 171 | |
| 172 | -<p>Fossil automatically generates a manifest whenever you "commit" | |
| 172 | +Fossil automatically generates a manifest whenever you "commit" | |
| 173 | 173 | a new check-in. So this is not something that you, the developer, |
| 174 | 174 | need to worry with. The format of a manifest is intentionally |
| 175 | 175 | designed to be simple to parse, so that if |
| 176 | 176 | you want to read and interpret a manifest, either by hand or |
| 177 | 177 | with a script, that is easy to do. But you will probably never |
| 178 | -need to do so.</p> | |
| 178 | +need to do so. | |
| 179 | 179 | |
| 180 | -<p>In addition to identifying all files in the check-in, a | |
| 180 | +In addition to identifying all files in the check-in, a | |
| 181 | 181 | manifest also contains a check-in comment, the date and time |
| 182 | 182 | when the check-in was established, who created the check-in, |
| 183 | 183 | and links to other check-ins from which the current check-in |
| 184 | 184 | is derived. There is also a couple of checksums used to verify |
| 185 | 185 | the integrity of the check-in. And the whole manifest might |
| 186 | -be PGP clearsigned.</p> | |
| 186 | +be PGP clearsigned. | |
| 187 | 187 | |
| 188 | 188 | <h3 id="keyconc">2.3 Key concepts</h3> |
| 189 | 189 | |
| 190 | 190 | <ul> |
| 191 | 191 | <li>A <b>check-in</b> is a set of files arranged |
| @@ -435,29 +435,27 @@ | ||
| 435 | 435 | <h2>5.0 Setting Up A Fossil Server</h2> |
| 436 | 436 | |
| 437 | 437 | With other configuration management software, setting up a server is |
| 438 | 438 | a lot of work and normally takes time, patience, and a lot of system |
| 439 | 439 | knowledge. Fossil is designed to avoid this frustration. Setting up |
| 440 | -a server with Fossil is ridiculously easy. You have four options:</p> | |
| 441 | - | |
| 442 | -<ol> | |
| 443 | -<li><p><b>Stand-alone server.</b> | |
| 444 | -Simply run the [/help?cmd=server|fossil server] or | |
| 445 | -[/help?cmd=ui|fossil ui] command from the command-line. | |
| 446 | - | |
| 447 | -<li><p><b>CGI.</b> | |
| 448 | -Install a 2-line CGI script on a CGI-enabled web-server like Apache. | |
| 449 | - | |
| 450 | -<li><p><b>SCGI.</b> | |
| 451 | -Start an SCGI server using the | |
| 452 | -[/help?cmd=server| fossil server --scgi] command for handling | |
| 453 | -SCGI requests from web-servers like Nginx. | |
| 454 | - | |
| 455 | -<li><p><b>Inetd or Stunnel.</b> | |
| 456 | -Configure programs like inetd, xinetd, or stunnel to hand off HTTP requests | |
| 457 | -directly to the [/help?cmd=http|fossil http] command. | |
| 458 | -</ol> | |
| 440 | +a server with Fossil is ridiculously easy. You have four options: | |
| 441 | + | |
| 442 | + # <b>Stand-alone server.</b> | |
| 443 | + Simply run the [/help?cmd=server|fossil server] or | |
| 444 | + [/help?cmd=ui|fossil ui] command from the command-line. | |
| 445 | + <br><br> | |
| 446 | + # <b>CGI.</b> | |
| 447 | + Install a 2-line CGI script on a CGI-enabled web-server like Apache. | |
| 448 | + <br><br> | |
| 449 | + # <b>SCGI.</b> | |
| 450 | + Start an SCGI server using the | |
| 451 | + [/help?cmd=server| fossil server --scgi] command for handling | |
| 452 | + SCGI requests from web-servers like Nginx. | |
| 453 | + <br><br> | |
| 454 | + # <b>Inetd or Stunnel.</b> | |
| 455 | + Configure programs like inetd, xinetd, or stunnel to hand off HTTP requests | |
| 456 | + directly to the [/help?cmd=http|fossil http] command. | |
| 459 | 457 | |
| 460 | 458 | See the [./server/ | How To Configure A Fossil Server] document |
| 461 | 459 | for details. |
| 462 | 460 | |
| 463 | 461 | <h2>6.0 Review Of Key Concepts</h2> |
| 464 | 462 |
| --- www/concepts.wiki | |
| +++ www/concepts.wiki | |
| @@ -159,33 +159,33 @@ | |
| 159 | of the manifest is the identifier for the entire check-in. When |
| 160 | you look at a "timeline" of changes in Fossil, the ID associated |
| 161 | with each check-in or commit is really just the artifact ID of the |
| 162 | manifest for that check-in. |
| 163 | |
| 164 | <p>The manifest file is not normally a real file on disk. Instead, |
| 165 | the manifest is computed in memory by Fossil whenever it needs it. |
| 166 | However, the "fossil setting manifest on" command will cause the |
| 167 | manifest file to be materialized to disk, if desired. Both Fossil |
| 168 | itself, and SQLite cause the manifest file to be materialized to disk |
| 169 | so that the makefiles for these project can read the manifest and |
| 170 | embed version information in generated binaries. |
| 171 | |
| 172 | <p>Fossil automatically generates a manifest whenever you "commit" |
| 173 | a new check-in. So this is not something that you, the developer, |
| 174 | need to worry with. The format of a manifest is intentionally |
| 175 | designed to be simple to parse, so that if |
| 176 | you want to read and interpret a manifest, either by hand or |
| 177 | with a script, that is easy to do. But you will probably never |
| 178 | need to do so.</p> |
| 179 | |
| 180 | <p>In addition to identifying all files in the check-in, a |
| 181 | manifest also contains a check-in comment, the date and time |
| 182 | when the check-in was established, who created the check-in, |
| 183 | and links to other check-ins from which the current check-in |
| 184 | is derived. There is also a couple of checksums used to verify |
| 185 | the integrity of the check-in. And the whole manifest might |
| 186 | be PGP clearsigned.</p> |
| 187 | |
| 188 | <h3 id="keyconc">2.3 Key concepts</h3> |
| 189 | |
| 190 | <ul> |
| 191 | <li>A <b>check-in</b> is a set of files arranged |
| @@ -435,29 +435,27 @@ | |
| 435 | <h2>5.0 Setting Up A Fossil Server</h2> |
| 436 | |
| 437 | With other configuration management software, setting up a server is |
| 438 | a lot of work and normally takes time, patience, and a lot of system |
| 439 | knowledge. Fossil is designed to avoid this frustration. Setting up |
| 440 | a server with Fossil is ridiculously easy. You have four options:</p> |
| 441 | |
| 442 | <ol> |
| 443 | <li><p><b>Stand-alone server.</b> |
| 444 | Simply run the [/help?cmd=server|fossil server] or |
| 445 | [/help?cmd=ui|fossil ui] command from the command-line. |
| 446 | |
| 447 | <li><p><b>CGI.</b> |
| 448 | Install a 2-line CGI script on a CGI-enabled web-server like Apache. |
| 449 | |
| 450 | <li><p><b>SCGI.</b> |
| 451 | Start an SCGI server using the |
| 452 | [/help?cmd=server| fossil server --scgi] command for handling |
| 453 | SCGI requests from web-servers like Nginx. |
| 454 | |
| 455 | <li><p><b>Inetd or Stunnel.</b> |
| 456 | Configure programs like inetd, xinetd, or stunnel to hand off HTTP requests |
| 457 | directly to the [/help?cmd=http|fossil http] command. |
| 458 | </ol> |
| 459 | |
| 460 | See the [./server/ | How To Configure A Fossil Server] document |
| 461 | for details. |
| 462 | |
| 463 | <h2>6.0 Review Of Key Concepts</h2> |
| 464 |
| --- www/concepts.wiki | |
| +++ www/concepts.wiki | |
| @@ -159,33 +159,33 @@ | |
| 159 | of the manifest is the identifier for the entire check-in. When |
| 160 | you look at a "timeline" of changes in Fossil, the ID associated |
| 161 | with each check-in or commit is really just the artifact ID of the |
| 162 | manifest for that check-in. |
| 163 | |
| 164 | The manifest file is not normally a real file on disk. Instead, |
| 165 | the manifest is computed in memory by Fossil whenever it needs it. |
| 166 | However, the "fossil setting manifest on" command will cause the |
| 167 | manifest file to be materialized to disk, if desired. Both Fossil |
| 168 | itself, and SQLite cause the manifest file to be materialized to disk |
| 169 | so that the makefiles for these project can read the manifest and |
| 170 | embed version information in generated binaries. |
| 171 | |
| 172 | Fossil automatically generates a manifest whenever you "commit" |
| 173 | a new check-in. So this is not something that you, the developer, |
| 174 | need to worry with. The format of a manifest is intentionally |
| 175 | designed to be simple to parse, so that if |
| 176 | you want to read and interpret a manifest, either by hand or |
| 177 | with a script, that is easy to do. But you will probably never |
| 178 | need to do so. |
| 179 | |
| 180 | In addition to identifying all files in the check-in, a |
| 181 | manifest also contains a check-in comment, the date and time |
| 182 | when the check-in was established, who created the check-in, |
| 183 | and links to other check-ins from which the current check-in |
| 184 | is derived. There is also a couple of checksums used to verify |
| 185 | the integrity of the check-in. And the whole manifest might |
| 186 | be PGP clearsigned. |
| 187 | |
| 188 | <h3 id="keyconc">2.3 Key concepts</h3> |
| 189 | |
| 190 | <ul> |
| 191 | <li>A <b>check-in</b> is a set of files arranged |
| @@ -435,29 +435,27 @@ | |
| 435 | <h2>5.0 Setting Up A Fossil Server</h2> |
| 436 | |
| 437 | With other configuration management software, setting up a server is |
| 438 | a lot of work and normally takes time, patience, and a lot of system |
| 439 | knowledge. Fossil is designed to avoid this frustration. Setting up |
| 440 | a server with Fossil is ridiculously easy. You have four options: |
| 441 | |
| 442 | # <b>Stand-alone server.</b> |
| 443 | Simply run the [/help?cmd=server|fossil server] or |
| 444 | [/help?cmd=ui|fossil ui] command from the command-line. |
| 445 | <br><br> |
| 446 | # <b>CGI.</b> |
| 447 | Install a 2-line CGI script on a CGI-enabled web-server like Apache. |
| 448 | <br><br> |
| 449 | # <b>SCGI.</b> |
| 450 | Start an SCGI server using the |
| 451 | [/help?cmd=server| fossil server --scgi] command for handling |
| 452 | SCGI requests from web-servers like Nginx. |
| 453 | <br><br> |
| 454 | # <b>Inetd or Stunnel.</b> |
| 455 | Configure programs like inetd, xinetd, or stunnel to hand off HTTP requests |
| 456 | directly to the [/help?cmd=http|fossil http] command. |
| 457 | |
| 458 | See the [./server/ | How To Configure A Fossil Server] document |
| 459 | for details. |
| 460 | |
| 461 | <h2>6.0 Review Of Key Concepts</h2> |
| 462 |
+22
-24
| --- www/custom_ticket.wiki | ||
| +++ www/custom_ticket.wiki | ||
| @@ -1,16 +1,16 @@ | ||
| 1 | 1 | <title>Customizing The Ticket System</title> |
| 2 | 2 | <nowiki> |
| 3 | 3 | <h2>Introduction</h2> |
| 4 | -<p> | |
| 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 | -</p> | |
| 8 | + | |
| 9 | +<h2>First modify the TICKET table</h2> | |
| 9 | 10 | |
| 10 | -<h2>First modify the TICKET table</h2><blockquote> | |
| 11 | -<p> | |
| 11 | +<blockquote> | |
| 12 | 12 | Click on the "Admin" menu, then "Tickets", then "Table". After the other fields |
| 13 | 13 | and before the final ")", insert: |
| 14 | 14 | <pre> |
| 15 | 15 | , |
| 16 | 16 | assigned_to TEXT, |
| @@ -17,15 +17,15 @@ | ||
| 17 | 17 | opened_by TEXT |
| 18 | 18 | </pre> |
| 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 | -</p> | |
| 23 | 22 | </blockquote> |
| 24 | 23 | |
| 25 | -<h2>Next add assignees</h2><blockquote> | |
| 26 | -<p> | |
| 24 | +<h2>Next add assignees</h2> | |
| 25 | + | |
| 26 | +<blockquote> | |
| 27 | 27 | Back to the "Tickets" admin page, and click "Common". Add something like this: |
| 28 | 28 | <pre> |
| 29 | 29 | set assigned_choices { |
| 30 | 30 | unassigned |
| 31 | 31 | tom |
| @@ -34,15 +34,15 @@ | ||
| 34 | 34 | } |
| 35 | 35 | </pre> |
| 36 | 36 | Obviously, choose names corresponding to the logins on your system. The |
| 37 | 37 | 'unassigned' entry is important, as it prevents you from having a NULL in that |
| 38 | 38 | field (which causes problems later when editing). |
| 39 | -</p> | |
| 40 | 39 | </blockquote> |
| 41 | 40 | |
| 42 | -<h2>Now modify the 'new ticket' page</h2><blockquote> | |
| 43 | -<p> | |
| 41 | +<h2>Now modify the 'new ticket' page</h2> | |
| 42 | + | |
| 43 | +<blockquote> | |
| 44 | 44 | Back to the "Tickets" admin page, and click "New Ticket Page". This is a little |
| 45 | 45 | more tricky. Edit the top part: |
| 46 | 46 | <pre> |
| 47 | 47 | if {[info exists submit]} { |
| 48 | 48 | set status Open |
| @@ -66,22 +66,21 @@ | ||
| 66 | 66 | <th1>enable_output 1</th1> |
| 67 | 67 | </pre> |
| 68 | 68 | This bit of code will get rid of the "email" field entry for logged-in users. |
| 69 | 69 | Since we know the user's information, we don't have to ask for it. NOTE: it |
| 70 | 70 | might be good to automatically scoop up the user's email and put it here. |
| 71 | -</p> | |
| 72 | -<p> | |
| 71 | + | |
| 73 | 72 | You might also want to enable people to actually assign the ticket to a specific |
| 74 | 73 | person during creation. For this to work, you need to add the code |
| 75 | 74 | for "assigned_to" as shown below under the heading "Modify the 'edit ticket' page". |
| 76 | 75 | This will give you an additional combobox where you can choose a person during |
| 77 | 76 | ticket creation. |
| 78 | -</p> | |
| 79 | 77 | </blockquote> |
| 80 | 78 | |
| 81 | -<h2>Modify the 'view ticket' page</h2><blockquote> | |
| 82 | -<p> | |
| 79 | +<h2>Modify the 'view ticket' page</h2> | |
| 80 | + | |
| 81 | +<blockquote> | |
| 83 | 82 | Look for the text "Contact:" (about halfway through). Then insert these lines |
| 84 | 83 | after the closing tr tag and before the "enable_output" line: |
| 85 | 84 | <pre> |
| 86 | 85 | <tr> |
| 87 | 86 | <td align="right">Assigned to:</td><td bgcolor="#d0d0d0"> |
| @@ -91,15 +90,15 @@ | ||
| 91 | 90 | $<opened_by> |
| 92 | 91 | </td> |
| 93 | 92 | </pre> |
| 94 | 93 | This will add a row which displays these two fields, in the event the user has |
| 95 | 94 | <a href="./caps/ref.html#w">ticket "edit" capability</a>. |
| 96 | -</p> | |
| 97 | 95 | </blockquote> |
| 98 | 96 | |
| 99 | -<h2>Modify the 'edit ticket' page</h2><blockquote> | |
| 100 | -<p> | |
| 97 | +<h2>Modify the 'edit ticket' page</h2> | |
| 98 | + | |
| 99 | +<blockquote> | |
| 101 | 100 | Before the "Severity:" line, add this: |
| 102 | 101 | <pre> |
| 103 | 102 | <tr><td align="right">Assigned to:</td><td> |
| 104 | 103 | <th1>combobox assigned_to $assigned_choices 1</th1> |
| 105 | 104 | </td></tr> |
| @@ -107,25 +106,25 @@ | ||
| 107 | 106 | That will give you a drop-down list of assignees. The first argument to the TH1 |
| 108 | 107 | command 'combobox' is the database field which the combobox is associated to. |
| 109 | 108 | The next argument is the list of choices you want to show in the combobox (and |
| 110 | 109 | that you specified in the second step above. The last argument should be 1 for a |
| 111 | 110 | true combobox (see the <a href="th1.md#combobox">TH1 documentation</a> for |
| 112 | -details).</p> | |
| 111 | +details). | |
| 113 | 112 | |
| 114 | -<p>Now, similar to the previous | |
| 113 | +Now, similar to the previous | |
| 115 | 114 | section, look for "Contact:" and add this: |
| 116 | 115 | <pre> |
| 117 | 116 | <tr><td align="right">Reported by:</td><td> |
| 118 | 117 | <input type="text" name="opened_by" size="40" |
| 119 | 118 | value="$<opened_by>"> |
| 120 | 119 | </td></tr> |
| 121 | 120 | </pre> |
| 122 | -</p> | |
| 123 | 121 | </blockquote> |
| 124 | 122 | |
| 125 | -<h2>What next?</h2><blockquote> | |
| 126 | -<p> | |
| 123 | +<h2>What next?</h2> | |
| 124 | + | |
| 125 | +<blockquote> | |
| 127 | 126 | Now you can add custom reports which select based on the person to whom the |
| 128 | 127 | ticket is assigned. For example, an "Assigned to me" report could be: |
| 129 | 128 | <pre> |
| 130 | 129 | SELECT |
| 131 | 130 | CASE WHEN status IN ('Open','Verified') THEN '#f2dcdc' |
| @@ -141,8 +140,7 @@ | ||
| 141 | 140 | subsystem, |
| 142 | 141 | title |
| 143 | 142 | FROM ticket |
| 144 | 143 | WHERE assigned_to=user() |
| 145 | 144 | </pre> |
| 146 | -</p> | |
| 147 | 145 | </blockquote> |
| 148 | 146 | </nowiki> |
| 149 | 147 |
| --- www/custom_ticket.wiki | |
| +++ www/custom_ticket.wiki | |
| @@ -1,16 +1,16 @@ | |
| 1 | <title>Customizing The Ticket System</title> |
| 2 | <nowiki> |
| 3 | <h2>Introduction</h2> |
| 4 | <p> |
| 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 | </p> |
| 9 | |
| 10 | <h2>First modify the TICKET table</h2><blockquote> |
| 11 | <p> |
| 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,15 +17,15 @@ | |
| 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 | </p> |
| 23 | </blockquote> |
| 24 | |
| 25 | <h2>Next add assignees</h2><blockquote> |
| 26 | <p> |
| 27 | Back to the "Tickets" admin page, and click "Common". Add something like this: |
| 28 | <pre> |
| 29 | set assigned_choices { |
| 30 | unassigned |
| 31 | tom |
| @@ -34,15 +34,15 @@ | |
| 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 | </p> |
| 40 | </blockquote> |
| 41 | |
| 42 | <h2>Now modify the 'new ticket' page</h2><blockquote> |
| 43 | <p> |
| 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 |
| @@ -66,22 +66,21 @@ | |
| 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 | </p> |
| 72 | <p> |
| 73 | You might also want to enable people to actually assign the ticket to a specific |
| 74 | person during creation. For this to work, you need to add the code |
| 75 | for "assigned_to" as shown below under the heading "Modify the 'edit ticket' page". |
| 76 | This will give you an additional combobox where you can choose a person during |
| 77 | ticket creation. |
| 78 | </p> |
| 79 | </blockquote> |
| 80 | |
| 81 | <h2>Modify the 'view ticket' page</h2><blockquote> |
| 82 | <p> |
| 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 | <pre> |
| 86 | <tr> |
| 87 | <td align="right">Assigned to:</td><td bgcolor="#d0d0d0"> |
| @@ -91,15 +90,15 @@ | |
| 91 | $<opened_by> |
| 92 | </td> |
| 93 | </pre> |
| 94 | This will add a row which displays these two fields, in the event the user has |
| 95 | <a href="./caps/ref.html#w">ticket "edit" capability</a>. |
| 96 | </p> |
| 97 | </blockquote> |
| 98 | |
| 99 | <h2>Modify the 'edit ticket' page</h2><blockquote> |
| 100 | <p> |
| 101 | Before the "Severity:" line, add this: |
| 102 | <pre> |
| 103 | <tr><td align="right">Assigned to:</td><td> |
| 104 | <th1>combobox assigned_to $assigned_choices 1</th1> |
| 105 | </td></tr> |
| @@ -107,25 +106,25 @@ | |
| 107 | That will give you a drop-down list of assignees. The first argument to the TH1 |
| 108 | command 'combobox' is the database field which the combobox is associated to. |
| 109 | The next argument is the list of choices you want to show in the combobox (and |
| 110 | that you specified in the second step above. The last argument should be 1 for a |
| 111 | true combobox (see the <a href="th1.md#combobox">TH1 documentation</a> for |
| 112 | details).</p> |
| 113 | |
| 114 | <p>Now, similar to the previous |
| 115 | section, look for "Contact:" and add this: |
| 116 | <pre> |
| 117 | <tr><td align="right">Reported by:</td><td> |
| 118 | <input type="text" name="opened_by" size="40" |
| 119 | value="$<opened_by>"> |
| 120 | </td></tr> |
| 121 | </pre> |
| 122 | </p> |
| 123 | </blockquote> |
| 124 | |
| 125 | <h2>What next?</h2><blockquote> |
| 126 | <p> |
| 127 | Now you can add custom reports which select based on the person to whom the |
| 128 | ticket is assigned. For example, an "Assigned to me" report could be: |
| 129 | <pre> |
| 130 | SELECT |
| 131 | CASE WHEN status IN ('Open','Verified') THEN '#f2dcdc' |
| @@ -141,8 +140,7 @@ | |
| 141 | subsystem, |
| 142 | title |
| 143 | FROM ticket |
| 144 | WHERE assigned_to=user() |
| 145 | </pre> |
| 146 | </p> |
| 147 | </blockquote> |
| 148 | </nowiki> |
| 149 |
| --- www/custom_ticket.wiki | |
| +++ www/custom_ticket.wiki | |
| @@ -1,16 +1,16 @@ | |
| 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,15 +17,15 @@ | |
| 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 |
| @@ -34,15 +34,15 @@ | |
| 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 |
| @@ -66,22 +66,21 @@ | |
| 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"> |
| @@ -91,15 +90,15 @@ | |
| 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> |
| @@ -107,25 +106,25 @@ | |
| 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' |
| @@ -141,8 +140,7 @@ | |
| 140 | subsystem, |
| 141 | title |
| 142 | FROM ticket |
| 143 | WHERE assigned_to=user() |
| 144 | </pre> |
| 145 | </blockquote> |
| 146 | </nowiki> |
| 147 |
+11
-11
| --- www/customskin.md | ||
| +++ www/customskin.md | ||
| @@ -180,21 +180,21 @@ | ||
| 180 | 180 | desired result. |
| 181 | 181 | |
| 182 | 182 | The skin is controlled by five files: |
| 183 | 183 | |
| 184 | 184 | <blockquote><dl> |
| 185 | -<dt><b>css.txt</b></dt><dd> | |
| 185 | +<dt><b>css.txt</b></dt> | |
| 186 | 186 | |
| 187 | -<p>The css.txt file is the text of the CSS for Fossil. | |
| 187 | +<dd>The css.txt file is the text of the CSS for Fossil. | |
| 188 | 188 | Fossil might add additional CSS elements after |
| 189 | 189 | the css.txt file, if it sees that the css.txt omits some |
| 190 | 190 | CSS components that Fossil needs. But for the most part, |
| 191 | 191 | the content of the css.txt is the CSS for the page.</dd> |
| 192 | 192 | |
| 193 | -<dt><b>details.txt</b><dt><dd> | |
| 193 | +<dt><b>details.txt</b><dt> | |
| 194 | 194 | |
| 195 | -<p>The details.txt file is short list of settings that control | |
| 195 | +<dd>The details.txt file is short list of settings that control | |
| 196 | 196 | the look and feel, mostly of the timeline. The default |
| 197 | 197 | details.txt file looks like this: |
| 198 | 198 | |
| 199 | 199 | <blockquote><pre> |
| 200 | 200 | pikchr-background: "" |
| @@ -211,11 +211,11 @@ | ||
| 211 | 211 | of certain aspects of the timeline graph. The number on the |
| 212 | 212 | right is a boolean - "1" to activate the feature and "0" to |
| 213 | 213 | disable it. The "white-foreground:" setting should be set to |
| 214 | 214 | "1" if the page color has light-color text on a darker background, |
| 215 | 215 | and "0" if the page has dark text on a light-colored background. |
| 216 | -<p> | |
| 216 | + | |
| 217 | 217 | If the "pikchr-foreground" setting (added in Fossil 2.14) |
| 218 | 218 | is defined and is not an empty string then it specifies a |
| 219 | 219 | foreground color to use for [pikchr diagrams](./pikchr.md). The |
| 220 | 220 | default pikchr foreground color is black, or white if the |
| 221 | 221 | "white-foreground" boolean is set. The "pikchr-background" |
| @@ -224,24 +224,24 @@ | ||
| 224 | 224 | empty strings, then they should be floating point values (close |
| 225 | 225 | to 1.0) that specify relative scaling of the fonts in pikchr |
| 226 | 226 | diagrams and other elements of the diagrams, respectively. |
| 227 | 227 | </dd> |
| 228 | 228 | |
| 229 | -<dt><b>footer.txt</b> and <b>header.txt</b></dt><dd> | |
| 229 | +<dt><b>footer.txt</b> and <b>header.txt</b></dt> | |
| 230 | 230 | |
| 231 | -<p>The footer.txt and header.txt files contain the Content Footer | |
| 231 | +<dd>The footer.txt and header.txt files contain the Content Footer | |
| 232 | 232 | and Content Header respectively. Of these, the Content Header is |
| 233 | 233 | the most important, as it contains the markup used to generate |
| 234 | 234 | the banner and menu bar for each page. |
| 235 | 235 | |
| 236 | -<p>Both the footer.txt and header.txt file are | |
| 236 | +Both the footer.txt and header.txt file are | |
| 237 | 237 | [processed using TH1](#headfoot) prior to being output as |
| 238 | 238 | part of the overall web page.</dd> |
| 239 | 239 | |
| 240 | -<dt><b>js.txt</b></dt><dd> | |
| 240 | +<dt><b>js.txt</b></dt> | |
| 241 | 241 | |
| 242 | -<p>The js.txt file is optional. It is intended to be javascript. | |
| 242 | +<dd>The js.txt file is optional. It is intended to be javascript. | |
| 243 | 243 | The complete text of this javascript might be inserted into |
| 244 | 244 | the Content Footer, after being processed using TH1, using |
| 245 | 245 | code like the following in the "footer.txt" file: |
| 246 | 246 | |
| 247 | 247 | <blockquote><pre> |
| @@ -248,11 +248,11 @@ | ||
| 248 | 248 | <script nonce="$nonce"> |
| 249 | 249 | <th1>styleScript</th1> |
| 250 | 250 | </script> |
| 251 | 251 | </pre></blockquote> |
| 252 | 252 | |
| 253 | -<p>The js.txt file was originally used to insert javascript | |
| 253 | +The js.txt file was originally used to insert javascript | |
| 254 | 254 | that controls the hamburger menu in the default skin. More |
| 255 | 255 | recently, the javascript for the hamburger menu was moved into |
| 256 | 256 | a separate built-in file. Skins that use the hamburger menu |
| 257 | 257 | typically cause the javascript to be loaded by including the |
| 258 | 258 | following TH1 code in the "header.txt" file: |
| 259 | 259 |
| --- www/customskin.md | |
| +++ www/customskin.md | |
| @@ -180,21 +180,21 @@ | |
| 180 | desired result. |
| 181 | |
| 182 | The skin is controlled by five files: |
| 183 | |
| 184 | <blockquote><dl> |
| 185 | <dt><b>css.txt</b></dt><dd> |
| 186 | |
| 187 | <p>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 |
| 190 | CSS components that Fossil needs. But for the most part, |
| 191 | the content of the css.txt is the CSS for the page.</dd> |
| 192 | |
| 193 | <dt><b>details.txt</b><dt><dd> |
| 194 | |
| 195 | <p>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: "" |
| @@ -211,11 +211,11 @@ | |
| 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 |
| 214 | "1" if the page color has light-color text on a darker background, |
| 215 | and "0" if the page has dark text on a light-colored background. |
| 216 | <p> |
| 217 | If the "pikchr-foreground" setting (added in Fossil 2.14) |
| 218 | is defined and is not an empty string then it specifies a |
| 219 | foreground color to use for [pikchr diagrams](./pikchr.md). The |
| 220 | default pikchr foreground color is black, or white if the |
| 221 | "white-foreground" boolean is set. The "pikchr-background" |
| @@ -224,24 +224,24 @@ | |
| 224 | empty strings, then they should be floating point values (close |
| 225 | to 1.0) that specify relative scaling of the fonts in pikchr |
| 226 | diagrams and other elements of the diagrams, respectively. |
| 227 | </dd> |
| 228 | |
| 229 | <dt><b>footer.txt</b> and <b>header.txt</b></dt><dd> |
| 230 | |
| 231 | <p>The footer.txt and header.txt files contain the Content Footer |
| 232 | and Content Header respectively. Of these, the Content Header is |
| 233 | the most important, as it contains the markup used to generate |
| 234 | the banner and menu bar for each page. |
| 235 | |
| 236 | <p>Both the footer.txt and header.txt file are |
| 237 | [processed using TH1](#headfoot) prior to being output as |
| 238 | part of the overall web page.</dd> |
| 239 | |
| 240 | <dt><b>js.txt</b></dt><dd> |
| 241 | |
| 242 | <p>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,11 +248,11 @@ | |
| 248 | <script nonce="$nonce"> |
| 249 | <th1>styleScript</th1> |
| 250 | </script> |
| 251 | </pre></blockquote> |
| 252 | |
| 253 | <p>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 |
| --- www/customskin.md | |
| +++ www/customskin.md | |
| @@ -180,21 +180,21 @@ | |
| 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 |
| 190 | CSS components that Fossil needs. But for the most part, |
| 191 | the content of the css.txt is the CSS for the page.</dd> |
| 192 | |
| 193 | <dt><b>details.txt</b><dt> |
| 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: "" |
| @@ -211,11 +211,11 @@ | |
| 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 |
| 214 | "1" if the page color has light-color text on a darker background, |
| 215 | and "0" if the page has dark text on a light-colored background. |
| 216 | |
| 217 | If the "pikchr-foreground" setting (added in Fossil 2.14) |
| 218 | is defined and is not an empty string then it specifies a |
| 219 | foreground color to use for [pikchr diagrams](./pikchr.md). The |
| 220 | default pikchr foreground color is black, or white if the |
| 221 | "white-foreground" boolean is set. The "pikchr-background" |
| @@ -224,24 +224,24 @@ | |
| 224 | empty strings, then they should be floating point values (close |
| 225 | to 1.0) that specify relative scaling of the fonts in pikchr |
| 226 | diagrams and other elements of the diagrams, respectively. |
| 227 | </dd> |
| 228 | |
| 229 | <dt><b>footer.txt</b> and <b>header.txt</b></dt> |
| 230 | |
| 231 | <dd>The footer.txt and header.txt files contain the Content Footer |
| 232 | and Content Header respectively. Of these, the Content Header is |
| 233 | the most important, as it contains the markup used to generate |
| 234 | the banner and menu bar for each page. |
| 235 | |
| 236 | Both the footer.txt and header.txt file are |
| 237 | [processed using TH1](#headfoot) prior to being output as |
| 238 | part of the overall web page.</dd> |
| 239 | |
| 240 | <dt><b>js.txt</b></dt> |
| 241 | |
| 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,11 +248,11 @@ | |
| 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 |
+38
-44
| --- www/delta_format.wiki | ||
| +++ www/delta_format.wiki | ||
| @@ -1,34 +1,33 @@ | ||
| 1 | 1 | <title>Fossil Delta Format</title> |
| 2 | 2 | <h1>1.0 Overview</h1> |
| 3 | 3 | |
| 4 | -<p>Fossil achieves efficient storage and low-bandwidth synchronization | |
| 4 | +Fossil achieves efficient storage and low-bandwidth synchronization | |
| 5 | 5 | through the use of delta-compression. Instead of storing |
| 6 | 6 | or transmitting the complete content of an artifact, Fossil stores or |
| 7 | 7 | transmits only the changes relative to a related artifact. |
| 8 | -</p> | |
| 9 | 8 | |
| 10 | -<p>This document describes the delta-encoding format used by Fossil. | |
| 9 | +This document describes the delta-encoding format used by Fossil. | |
| 11 | 10 | The intended audience is developers working on either |
| 12 | 11 | <a href="index.wiki">Fossil</a> itself, or on tools compatible with |
| 13 | 12 | Fossil. Understanding of this document is <em>not</em> required for |
| 14 | -ordinary users of Fossil. This document is an implementation detail.</p> | |
| 13 | +ordinary users of Fossil. This document is an implementation detail. | |
| 15 | 14 | |
| 16 | -<p>This document only describes the delta file format. A | |
| 15 | +This document only describes the delta file format. A | |
| 17 | 16 | [./delta_encoder_algorithm.wiki|separate document] describes one possible |
| 18 | -algorithm for generating deltas in this format.</p> | |
| 17 | +algorithm for generating deltas in this format. | |
| 19 | 18 | |
| 20 | 19 | <h2>1.1 Sample Software And Analysis Tools</h2> |
| 21 | 20 | |
| 22 | -<p>The core routines used to generate and apply deltas in this format | |
| 21 | +The core routines used to generate and apply deltas in this format | |
| 23 | 22 | are contained in the [../src/delta.c|delta.c] source file. Interface |
| 24 | 23 | logic, including "test-*" commands to directly manipulate deltas are |
| 25 | 24 | contained in the [../src/deltacmd.c|deltacmd.c] source file. SQL functions |
| 26 | 25 | to create, apply, and analyze deltas are implemented by code in the |
| 27 | 26 | [../src/deltafunc.c|deltafunc.c] source file. |
| 28 | 27 | |
| 29 | -<p>The following command-line tools are available to create and apply | |
| 28 | +The following command-line tools are available to create and apply | |
| 30 | 29 | deltas and to test the delta logic: |
| 31 | 30 | |
| 32 | 31 | * [/help?cmd=test-delta|fossil test-delta] → Run self-tests of |
| 33 | 32 | the delta logic |
| 34 | 33 | |
| @@ -40,11 +39,11 @@ | ||
| 40 | 39 | |
| 41 | 40 | * [/help?cmd=test-delta-analyze|fossil test-delta-analyze X Y] → compute |
| 42 | 41 | and delta that converts file X into file Y but instead of writing the |
| 43 | 42 | delta to output, write performance information about the delta. |
| 44 | 43 | |
| 45 | -<p>When running the [/help?cmd=sqlite3|fossil sql] command to get an | |
| 44 | +When running the [/help?cmd=sqlite3|fossil sql] command to get an | |
| 46 | 45 | interactive SQL session connected to the repository, the following |
| 47 | 46 | additional SQL functions are provided: |
| 48 | 47 | |
| 49 | 48 | * <b>delta_create(</b><i>X</i><b>,</b><i>Y</i><b>)</b> → |
| 50 | 49 | Compute a data that carries blob X into blob Y and return that delta |
| @@ -68,53 +67,53 @@ | ||
| 68 | 67 | box height 50% "Header" |
| 69 | 68 | box same "Segments" |
| 70 | 69 | box same "Trailer" |
| 71 | 70 | </verbatim> |
| 72 | 71 | |
| 73 | -<p>A delta consists of three parts, a "header", a "trailer", and a | |
| 74 | -"segment-list" between them.</p> | |
| 72 | +A delta consists of three parts, a "header", a "trailer", and a | |
| 73 | +"segment-list" between them. | |
| 75 | 74 | |
| 76 | -<p>Both header and trailer provide information about the target | |
| 75 | +Both header and trailer provide information about the target | |
| 77 | 76 | helping the decoder, and the segment-list describes how the target can |
| 78 | -be constructed from the original.</p> | |
| 77 | +be constructed from the original. | |
| 79 | 78 | |
| 80 | 79 | <h2 id="header">2.1 Header</h2> |
| 81 | 80 | <verbatim type="pikchr"> |
| 82 | 81 | leftmargin = 0.1 |
| 83 | 82 | box height 50% "Size" |
| 84 | 83 | box same "\"\\n\"" |
| 85 | 84 | </verbatim> |
| 86 | 85 | |
| 87 | -<p>The header consists of a single number followed by a newline | |
| 86 | +The header consists of a single number followed by a newline | |
| 88 | 87 | character (ASCII 0x0a). The number is the length of the target in |
| 89 | -bytes.</p> | |
| 88 | +bytes. | |
| 90 | 89 | |
| 91 | -<p>This means that, given a delta, the decoder can compute the size of | |
| 90 | +This means that, given a delta, the decoder can compute the size of | |
| 92 | 91 | the target (and allocate any necessary memory based on that) by simply |
| 93 | 92 | reading the first line of the delta and decoding the number found |
| 94 | -there. In other words, before it has to decode everything else.</p> | |
| 93 | +there. In other words, before it has to decode everything else. | |
| 95 | 94 | |
| 96 | 95 | <h2 id="trailer">2.2 Trailer</h2> |
| 97 | 96 | <verbatim type="pikchr"> |
| 98 | 97 | leftmargin = 0.1 |
| 99 | 98 | box height 50% "Checksum" |
| 100 | 99 | box same "\";\"" |
| 101 | 100 | </verbatim> |
| 102 | 101 | |
| 103 | -<p>The trailer consists of a single number followed by a semicolon (ASCII | |
| 102 | +The trailer consists of a single number followed by a semicolon (ASCII | |
| 104 | 103 | 0x3b). This number is a checksum of the target and can be used by a |
| 105 | 104 | decoder to verify that the delta applied correctly, reconstructing the |
| 106 | -target from the original.</p> | |
| 105 | +target from the original. | |
| 107 | 106 | |
| 108 | -<p>The checksum is computed by treating the target as a series of | |
| 107 | +The checksum is computed by treating the target as a series of | |
| 109 | 108 | 32-bit integer numbers (MSB first), and summing these up, modulo |
| 110 | 109 | 2^32-1. A target whose length is not a multiple of 4 is padded with |
| 111 | -0-bytes (ASCII 0x00) at the end.</p> | |
| 110 | +0-bytes (ASCII 0x00) at the end. | |
| 112 | 111 | |
| 113 | -<p>By putting this information at the end of the delta a decoder has | |
| 112 | +By putting this information at the end of the delta a decoder has | |
| 114 | 113 | it available immediately after the target has been reconstructed |
| 115 | -fully.</p> | |
| 114 | +fully. | |
| 116 | 115 | |
| 117 | 116 | <h2 id="slist">2.3 Segment-List</h2> |
| 118 | 117 | <verbatim type="pikchr"> |
| 119 | 118 | leftmargin = 0.1 |
| 120 | 119 | PART1: [ |
| @@ -138,41 +137,41 @@ | ||
| 138 | 137 | box "\":\"" same |
| 139 | 138 | box "Bytes" same |
| 140 | 139 | ] with .nw at previous.sw |
| 141 | 140 | </verbatim> |
| 142 | 141 | |
| 143 | -<p>The segment-list of a delta describes how to create the target from | |
| 142 | +The segment-list of a delta describes how to create the target from | |
| 144 | 143 | the original by a combination of inserting literal byte-sequences and |
| 145 | 144 | copying ranges of bytes from the original. This is where the |
| 146 | 145 | compression takes place, by encoding the large common parts of |
| 147 | -original and target in small copy instructions.</p> | |
| 146 | +original and target in small copy instructions. | |
| 148 | 147 | |
| 149 | -<p>The target is constructed from beginning to end, with the data | |
| 148 | +The target is constructed from beginning to end, with the data | |
| 150 | 149 | generated by each instruction appended after the data of all previous |
| 151 | -instructions, with no gaps.</p> | |
| 150 | +instructions, with no gaps. | |
| 152 | 151 | |
| 153 | 152 | <h3 id="insertlit">2.3.1 Insert Literal</h3> |
| 154 | 153 | |
| 155 | -<p>A literal is specified by two elements, the size of the literal in | |
| 156 | -bytes, and the bytes of the literal itself.</p> | |
| 154 | +A literal is specified by two elements, the size of the literal in | |
| 155 | +bytes, and the bytes of the literal itself. | |
| 157 | 156 | |
| 158 | 157 | <verbatim type="pikchr"> |
| 159 | 158 | leftmargin = 0.1 |
| 160 | 159 | box "Length" height 50% |
| 161 | 160 | box "\":\"" same |
| 162 | 161 | box "Bytes" same |
| 163 | 162 | </verbatim> |
| 164 | 163 | |
| 165 | -<p>The length is written first, followed by a colon character (ASCII | |
| 166 | -0x3a), followed by the bytes of the literal.</p> | |
| 164 | +The length is written first, followed by a colon character (ASCII | |
| 165 | +0x3a), followed by the bytes of the literal. | |
| 167 | 166 | |
| 168 | 167 | <h3 id="copyrange">2.3.2 Copy Range</h3> |
| 169 | 168 | |
| 170 | -<p>A range to copy is specified by two numbers, the offset of the | |
| 169 | +A range to copy is specified by two numbers, the offset of the | |
| 171 | 170 | first byte in the original to copy, and the size of the range, in |
| 172 | 171 | bytes. The size zero is special, its usage indicates that the range |
| 173 | -extends to the end of the original.</p> | |
| 172 | +extends to the end of the original. | |
| 174 | 173 | |
| 175 | 174 | <verbatim type="pikchr"> |
| 176 | 175 | leftmargin = 0.1 |
| 177 | 176 | box "Length" height 50% |
| 178 | 177 | box "\"@\"" same |
| @@ -179,37 +178,32 @@ | ||
| 179 | 178 | box "Offset" same |
| 180 | 179 | box "\",\"" same |
| 181 | 180 | </verbatim> |
| 182 | 181 | |
| 183 | 182 | |
| 184 | -<p>The length is written first, followed by an "at" character (ASCII | |
| 185 | -0x40), then the offset, followed by a comma (ASCII 0x2c).</p> | |
| 183 | +The length is written first, followed by an "at" character (ASCII | |
| 184 | +0x40), then the offset, followed by a comma (ASCII 0x2c). | |
| 186 | 185 | |
| 187 | 186 | <h1 id="intcoding">3.0 Encoding of integers</h1> |
| 188 | 187 | |
| 189 | -<p> | |
| 190 | 188 | The format currently handles only 32 bit integer numbers. They are |
| 191 | 189 | written base-64 encoded, MSB first, and without leading |
| 192 | 190 | "0"-characters, except if they are significant (i.e. 0 => "0"). |
| 193 | -</p> | |
| 194 | 191 | |
| 195 | -<p> | |
| 196 | 192 | The base-64 encoding uses one character for each 6 bits of |
| 197 | 193 | the integer to be encoded. The encoding characters are: |
| 198 | -</p> | |
| 199 | 194 | |
| 200 | 195 | <blockquote><pre> |
| 201 | 196 | 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz~ |
| 202 | 197 | </pre></blockquote> |
| 203 | 198 | |
| 204 | -<p>The least significant 6 bits of the integer are encoded by | |
| 199 | +The least significant 6 bits of the integer are encoded by | |
| 205 | 200 | the first character, followed by |
| 206 | 201 | the next 6 bits, and so on until all non-zero bits of the integer |
| 207 | 202 | are encoded. The minimum number of encoding characters is used. |
| 208 | 203 | Note that for integers less than 10, the base-64 coding is a |
| 209 | 204 | ASCII decimal rendering of the number itself. |
| 210 | -</p> | |
| 211 | 205 | |
| 212 | 206 | <h1 id="examples">4.0 Examples</h1> |
| 213 | 207 | |
| 214 | 208 | <h2 id="examplesint">4.1 Integer encoding</h2> |
| 215 | 209 | |
| @@ -232,18 +226,18 @@ | ||
| 232 | 226 | </tr> |
| 233 | 227 | </table> |
| 234 | 228 | |
| 235 | 229 | <h2 id="examplesdelta">4.2 Delta encoding</h2> |
| 236 | 230 | |
| 237 | -<p>An example of a delta using the specified encoding is:</p> | |
| 231 | +An example of a delta using the specified encoding is: | |
| 238 | 232 | |
| 239 | 233 | <table border=1><tr><td><pre> |
| 240 | 234 | 1Xb |
| 241 | 235 | 4E@0,2:thFN@4C,6:scenda1B@Jd,6:scenda5x@Kt,6:pieces79@Qt,F: Example: eskil~E@Y0,2zMM3E;</pre> |
| 242 | 236 | </td></tr></table> |
| 243 | 237 | |
| 244 | -<p>This can be taken apart into the following parts:</p> | |
| 238 | +This can be taken apart into the following parts: | |
| 245 | 239 | |
| 246 | 240 | <table border=1> |
| 247 | 241 | <tr><th>What </th> <th>Encoding </th><th>Meaning </th><th>Details</th></tr> |
| 248 | 242 | <tr><td>Header</td> <td>1Xb </td><td>Size </td><td> 6246 </td></tr> |
| 249 | 243 | <tr><td>S-List</td> <td>4E@0, </td><td>Copy </td><td> 270 @ 0 </td></tr> |
| @@ -258,11 +252,11 @@ | ||
| 258 | 252 | <tr><td> </td> <td>F: Example: eskil</td><td>Literal </td><td> 15 ' Example: eskil'</td></tr> |
| 259 | 253 | <tr><td> </td> <td>~E@Y0, </td><td>Copy </td><td> 4046 @ 2176 </td></tr> |
| 260 | 254 | <tr><td>Trailer</td><td>2zMM3E </td><td>Checksum</td><td> -1101438770 </td></tr> |
| 261 | 255 | </table> |
| 262 | 256 | |
| 263 | -<p>The unified diff behind the above delta is</p> | |
| 257 | +The unified diff behind the above delta is | |
| 264 | 258 | |
| 265 | 259 | <table border=1><tr><td><pre> |
| 266 | 260 | bluepeak:(761) ~/Projects/Tcl/Fossil/Devel/devel > diff -u ../DELTA/old ../DELTA/new |
| 267 | 261 | --- ../DELTA/old 2007-08-23 21:14:40.000000000 -0700 |
| 268 | 262 | +++ ../DELTA/new 2007-08-23 21:14:33.000000000 -0700 |
| 269 | 263 |
| --- www/delta_format.wiki | |
| +++ www/delta_format.wiki | |
| @@ -1,34 +1,33 @@ | |
| 1 | <title>Fossil Delta Format</title> |
| 2 | <h1>1.0 Overview</h1> |
| 3 | |
| 4 | <p>Fossil achieves efficient storage and low-bandwidth synchronization |
| 5 | through the use of delta-compression. Instead of storing |
| 6 | or transmitting the complete content of an artifact, Fossil stores or |
| 7 | transmits only the changes relative to a related artifact. |
| 8 | </p> |
| 9 | |
| 10 | <p>This document describes the delta-encoding format used by Fossil. |
| 11 | The intended audience is developers working on either |
| 12 | <a href="index.wiki">Fossil</a> itself, or on tools compatible with |
| 13 | Fossil. Understanding of this document is <em>not</em> required for |
| 14 | ordinary users of Fossil. This document is an implementation detail.</p> |
| 15 | |
| 16 | <p>This document only describes the delta file format. A |
| 17 | [./delta_encoder_algorithm.wiki|separate document] describes one possible |
| 18 | algorithm for generating deltas in this format.</p> |
| 19 | |
| 20 | <h2>1.1 Sample Software And Analysis Tools</h2> |
| 21 | |
| 22 | <p>The core routines used to generate and apply deltas in this format |
| 23 | are contained in the [../src/delta.c|delta.c] source file. Interface |
| 24 | logic, including "test-*" commands to directly manipulate deltas are |
| 25 | contained in the [../src/deltacmd.c|deltacmd.c] source file. SQL functions |
| 26 | to create, apply, and analyze deltas are implemented by code in the |
| 27 | [../src/deltafunc.c|deltafunc.c] source file. |
| 28 | |
| 29 | <p>The following command-line tools are available to create and apply |
| 30 | deltas and to test the delta logic: |
| 31 | |
| 32 | * [/help?cmd=test-delta|fossil test-delta] → Run self-tests of |
| 33 | the delta logic |
| 34 | |
| @@ -40,11 +39,11 @@ | |
| 40 | |
| 41 | * [/help?cmd=test-delta-analyze|fossil test-delta-analyze X Y] → compute |
| 42 | and delta that converts file X into file Y but instead of writing the |
| 43 | delta to output, write performance information about the delta. |
| 44 | |
| 45 | <p>When running the [/help?cmd=sqlite3|fossil sql] command to get an |
| 46 | interactive SQL session connected to the repository, the following |
| 47 | additional SQL functions are provided: |
| 48 | |
| 49 | * <b>delta_create(</b><i>X</i><b>,</b><i>Y</i><b>)</b> → |
| 50 | Compute a data that carries blob X into blob Y and return that delta |
| @@ -68,53 +67,53 @@ | |
| 68 | box height 50% "Header" |
| 69 | box same "Segments" |
| 70 | box same "Trailer" |
| 71 | </verbatim> |
| 72 | |
| 73 | <p>A delta consists of three parts, a "header", a "trailer", and a |
| 74 | "segment-list" between them.</p> |
| 75 | |
| 76 | <p>Both header and trailer provide information about the target |
| 77 | helping the decoder, and the segment-list describes how the target can |
| 78 | be constructed from the original.</p> |
| 79 | |
| 80 | <h2 id="header">2.1 Header</h2> |
| 81 | <verbatim type="pikchr"> |
| 82 | leftmargin = 0.1 |
| 83 | box height 50% "Size" |
| 84 | box same "\"\\n\"" |
| 85 | </verbatim> |
| 86 | |
| 87 | <p>The header consists of a single number followed by a newline |
| 88 | character (ASCII 0x0a). The number is the length of the target in |
| 89 | bytes.</p> |
| 90 | |
| 91 | <p>This means that, given a delta, the decoder can compute the size of |
| 92 | the target (and allocate any necessary memory based on that) by simply |
| 93 | reading the first line of the delta and decoding the number found |
| 94 | there. In other words, before it has to decode everything else.</p> |
| 95 | |
| 96 | <h2 id="trailer">2.2 Trailer</h2> |
| 97 | <verbatim type="pikchr"> |
| 98 | leftmargin = 0.1 |
| 99 | box height 50% "Checksum" |
| 100 | box same "\";\"" |
| 101 | </verbatim> |
| 102 | |
| 103 | <p>The trailer consists of a single number followed by a semicolon (ASCII |
| 104 | 0x3b). This number is a checksum of the target and can be used by a |
| 105 | decoder to verify that the delta applied correctly, reconstructing the |
| 106 | target from the original.</p> |
| 107 | |
| 108 | <p>The checksum is computed by treating the target as a series of |
| 109 | 32-bit integer numbers (MSB first), and summing these up, modulo |
| 110 | 2^32-1. A target whose length is not a multiple of 4 is padded with |
| 111 | 0-bytes (ASCII 0x00) at the end.</p> |
| 112 | |
| 113 | <p>By putting this information at the end of the delta a decoder has |
| 114 | it available immediately after the target has been reconstructed |
| 115 | fully.</p> |
| 116 | |
| 117 | <h2 id="slist">2.3 Segment-List</h2> |
| 118 | <verbatim type="pikchr"> |
| 119 | leftmargin = 0.1 |
| 120 | PART1: [ |
| @@ -138,41 +137,41 @@ | |
| 138 | box "\":\"" same |
| 139 | box "Bytes" same |
| 140 | ] with .nw at previous.sw |
| 141 | </verbatim> |
| 142 | |
| 143 | <p>The segment-list of a delta describes how to create the target from |
| 144 | the original by a combination of inserting literal byte-sequences and |
| 145 | copying ranges of bytes from the original. This is where the |
| 146 | compression takes place, by encoding the large common parts of |
| 147 | original and target in small copy instructions.</p> |
| 148 | |
| 149 | <p>The target is constructed from beginning to end, with the data |
| 150 | generated by each instruction appended after the data of all previous |
| 151 | instructions, with no gaps.</p> |
| 152 | |
| 153 | <h3 id="insertlit">2.3.1 Insert Literal</h3> |
| 154 | |
| 155 | <p>A literal is specified by two elements, the size of the literal in |
| 156 | bytes, and the bytes of the literal itself.</p> |
| 157 | |
| 158 | <verbatim type="pikchr"> |
| 159 | leftmargin = 0.1 |
| 160 | box "Length" height 50% |
| 161 | box "\":\"" same |
| 162 | box "Bytes" same |
| 163 | </verbatim> |
| 164 | |
| 165 | <p>The length is written first, followed by a colon character (ASCII |
| 166 | 0x3a), followed by the bytes of the literal.</p> |
| 167 | |
| 168 | <h3 id="copyrange">2.3.2 Copy Range</h3> |
| 169 | |
| 170 | <p>A range to copy is specified by two numbers, the offset of the |
| 171 | first byte in the original to copy, and the size of the range, in |
| 172 | bytes. The size zero is special, its usage indicates that the range |
| 173 | extends to the end of the original.</p> |
| 174 | |
| 175 | <verbatim type="pikchr"> |
| 176 | leftmargin = 0.1 |
| 177 | box "Length" height 50% |
| 178 | box "\"@\"" same |
| @@ -179,37 +178,32 @@ | |
| 179 | box "Offset" same |
| 180 | box "\",\"" same |
| 181 | </verbatim> |
| 182 | |
| 183 | |
| 184 | <p>The length is written first, followed by an "at" character (ASCII |
| 185 | 0x40), then the offset, followed by a comma (ASCII 0x2c).</p> |
| 186 | |
| 187 | <h1 id="intcoding">3.0 Encoding of integers</h1> |
| 188 | |
| 189 | <p> |
| 190 | The format currently handles only 32 bit integer numbers. They are |
| 191 | written base-64 encoded, MSB first, and without leading |
| 192 | "0"-characters, except if they are significant (i.e. 0 => "0"). |
| 193 | </p> |
| 194 | |
| 195 | <p> |
| 196 | The base-64 encoding uses one character for each 6 bits of |
| 197 | the integer to be encoded. The encoding characters are: |
| 198 | </p> |
| 199 | |
| 200 | <blockquote><pre> |
| 201 | 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz~ |
| 202 | </pre></blockquote> |
| 203 | |
| 204 | <p>The least significant 6 bits of the integer are encoded by |
| 205 | the first character, followed by |
| 206 | the next 6 bits, and so on until all non-zero bits of the integer |
| 207 | are encoded. The minimum number of encoding characters is used. |
| 208 | Note that for integers less than 10, the base-64 coding is a |
| 209 | ASCII decimal rendering of the number itself. |
| 210 | </p> |
| 211 | |
| 212 | <h1 id="examples">4.0 Examples</h1> |
| 213 | |
| 214 | <h2 id="examplesint">4.1 Integer encoding</h2> |
| 215 | |
| @@ -232,18 +226,18 @@ | |
| 232 | </tr> |
| 233 | </table> |
| 234 | |
| 235 | <h2 id="examplesdelta">4.2 Delta encoding</h2> |
| 236 | |
| 237 | <p>An example of a delta using the specified encoding is:</p> |
| 238 | |
| 239 | <table border=1><tr><td><pre> |
| 240 | 1Xb |
| 241 | 4E@0,2:thFN@4C,6:scenda1B@Jd,6:scenda5x@Kt,6:pieces79@Qt,F: Example: eskil~E@Y0,2zMM3E;</pre> |
| 242 | </td></tr></table> |
| 243 | |
| 244 | <p>This can be taken apart into the following parts:</p> |
| 245 | |
| 246 | <table border=1> |
| 247 | <tr><th>What </th> <th>Encoding </th><th>Meaning </th><th>Details</th></tr> |
| 248 | <tr><td>Header</td> <td>1Xb </td><td>Size </td><td> 6246 </td></tr> |
| 249 | <tr><td>S-List</td> <td>4E@0, </td><td>Copy </td><td> 270 @ 0 </td></tr> |
| @@ -258,11 +252,11 @@ | |
| 258 | <tr><td> </td> <td>F: Example: eskil</td><td>Literal </td><td> 15 ' Example: eskil'</td></tr> |
| 259 | <tr><td> </td> <td>~E@Y0, </td><td>Copy </td><td> 4046 @ 2176 </td></tr> |
| 260 | <tr><td>Trailer</td><td>2zMM3E </td><td>Checksum</td><td> -1101438770 </td></tr> |
| 261 | </table> |
| 262 | |
| 263 | <p>The unified diff behind the above delta is</p> |
| 264 | |
| 265 | <table border=1><tr><td><pre> |
| 266 | bluepeak:(761) ~/Projects/Tcl/Fossil/Devel/devel > diff -u ../DELTA/old ../DELTA/new |
| 267 | --- ../DELTA/old 2007-08-23 21:14:40.000000000 -0700 |
| 268 | +++ ../DELTA/new 2007-08-23 21:14:33.000000000 -0700 |
| 269 |
| --- www/delta_format.wiki | |
| +++ www/delta_format.wiki | |
| @@ -1,34 +1,33 @@ | |
| 1 | <title>Fossil Delta Format</title> |
| 2 | <h1>1.0 Overview</h1> |
| 3 | |
| 4 | Fossil achieves efficient storage and low-bandwidth synchronization |
| 5 | through the use of delta-compression. Instead of storing |
| 6 | or transmitting the complete content of an artifact, Fossil stores or |
| 7 | transmits only the changes relative to a related artifact. |
| 8 | |
| 9 | This document describes the delta-encoding format used by Fossil. |
| 10 | The intended audience is developers working on either |
| 11 | <a href="index.wiki">Fossil</a> itself, or on tools compatible with |
| 12 | Fossil. Understanding of this document is <em>not</em> required for |
| 13 | ordinary users of Fossil. This document is an implementation detail. |
| 14 | |
| 15 | This document only describes the delta file format. A |
| 16 | [./delta_encoder_algorithm.wiki|separate document] describes one possible |
| 17 | algorithm for generating deltas in this format. |
| 18 | |
| 19 | <h2>1.1 Sample Software And Analysis Tools</h2> |
| 20 | |
| 21 | The core routines used to generate and apply deltas in this format |
| 22 | are contained in the [../src/delta.c|delta.c] source file. Interface |
| 23 | logic, including "test-*" commands to directly manipulate deltas are |
| 24 | contained in the [../src/deltacmd.c|deltacmd.c] source file. SQL functions |
| 25 | to create, apply, and analyze deltas are implemented by code in the |
| 26 | [../src/deltafunc.c|deltafunc.c] source file. |
| 27 | |
| 28 | The following command-line tools are available to create and apply |
| 29 | deltas and to test the delta logic: |
| 30 | |
| 31 | * [/help?cmd=test-delta|fossil test-delta] → Run self-tests of |
| 32 | the delta logic |
| 33 | |
| @@ -40,11 +39,11 @@ | |
| 39 | |
| 40 | * [/help?cmd=test-delta-analyze|fossil test-delta-analyze X Y] → compute |
| 41 | and delta that converts file X into file Y but instead of writing the |
| 42 | delta to output, write performance information about the delta. |
| 43 | |
| 44 | When running the [/help?cmd=sqlite3|fossil sql] command to get an |
| 45 | interactive SQL session connected to the repository, the following |
| 46 | additional SQL functions are provided: |
| 47 | |
| 48 | * <b>delta_create(</b><i>X</i><b>,</b><i>Y</i><b>)</b> → |
| 49 | Compute a data that carries blob X into blob Y and return that delta |
| @@ -68,53 +67,53 @@ | |
| 67 | box height 50% "Header" |
| 68 | box same "Segments" |
| 69 | box same "Trailer" |
| 70 | </verbatim> |
| 71 | |
| 72 | A delta consists of three parts, a "header", a "trailer", and a |
| 73 | "segment-list" between them. |
| 74 | |
| 75 | Both header and trailer provide information about the target |
| 76 | helping the decoder, and the segment-list describes how the target can |
| 77 | be constructed from the original. |
| 78 | |
| 79 | <h2 id="header">2.1 Header</h2> |
| 80 | <verbatim type="pikchr"> |
| 81 | leftmargin = 0.1 |
| 82 | box height 50% "Size" |
| 83 | box same "\"\\n\"" |
| 84 | </verbatim> |
| 85 | |
| 86 | The header consists of a single number followed by a newline |
| 87 | character (ASCII 0x0a). The number is the length of the target in |
| 88 | bytes. |
| 89 | |
| 90 | This means that, given a delta, the decoder can compute the size of |
| 91 | the target (and allocate any necessary memory based on that) by simply |
| 92 | reading the first line of the delta and decoding the number found |
| 93 | there. In other words, before it has to decode everything else. |
| 94 | |
| 95 | <h2 id="trailer">2.2 Trailer</h2> |
| 96 | <verbatim type="pikchr"> |
| 97 | leftmargin = 0.1 |
| 98 | box height 50% "Checksum" |
| 99 | box same "\";\"" |
| 100 | </verbatim> |
| 101 | |
| 102 | The trailer consists of a single number followed by a semicolon (ASCII |
| 103 | 0x3b). This number is a checksum of the target and can be used by a |
| 104 | decoder to verify that the delta applied correctly, reconstructing the |
| 105 | target from the original. |
| 106 | |
| 107 | The checksum is computed by treating the target as a series of |
| 108 | 32-bit integer numbers (MSB first), and summing these up, modulo |
| 109 | 2^32-1. A target whose length is not a multiple of 4 is padded with |
| 110 | 0-bytes (ASCII 0x00) at the end. |
| 111 | |
| 112 | By putting this information at the end of the delta a decoder has |
| 113 | it available immediately after the target has been reconstructed |
| 114 | fully. |
| 115 | |
| 116 | <h2 id="slist">2.3 Segment-List</h2> |
| 117 | <verbatim type="pikchr"> |
| 118 | leftmargin = 0.1 |
| 119 | PART1: [ |
| @@ -138,41 +137,41 @@ | |
| 137 | box "\":\"" same |
| 138 | box "Bytes" same |
| 139 | ] with .nw at previous.sw |
| 140 | </verbatim> |
| 141 | |
| 142 | The segment-list of a delta describes how to create the target from |
| 143 | the original by a combination of inserting literal byte-sequences and |
| 144 | copying ranges of bytes from the original. This is where the |
| 145 | compression takes place, by encoding the large common parts of |
| 146 | original and target in small copy instructions. |
| 147 | |
| 148 | The target is constructed from beginning to end, with the data |
| 149 | generated by each instruction appended after the data of all previous |
| 150 | instructions, with no gaps. |
| 151 | |
| 152 | <h3 id="insertlit">2.3.1 Insert Literal</h3> |
| 153 | |
| 154 | A literal is specified by two elements, the size of the literal in |
| 155 | bytes, and the bytes of the literal itself. |
| 156 | |
| 157 | <verbatim type="pikchr"> |
| 158 | leftmargin = 0.1 |
| 159 | box "Length" height 50% |
| 160 | box "\":\"" same |
| 161 | box "Bytes" same |
| 162 | </verbatim> |
| 163 | |
| 164 | The length is written first, followed by a colon character (ASCII |
| 165 | 0x3a), followed by the bytes of the literal. |
| 166 | |
| 167 | <h3 id="copyrange">2.3.2 Copy Range</h3> |
| 168 | |
| 169 | A range to copy is specified by two numbers, the offset of the |
| 170 | first byte in the original to copy, and the size of the range, in |
| 171 | bytes. The size zero is special, its usage indicates that the range |
| 172 | extends to the end of the original. |
| 173 | |
| 174 | <verbatim type="pikchr"> |
| 175 | leftmargin = 0.1 |
| 176 | box "Length" height 50% |
| 177 | box "\"@\"" same |
| @@ -179,37 +178,32 @@ | |
| 178 | box "Offset" same |
| 179 | box "\",\"" same |
| 180 | </verbatim> |
| 181 | |
| 182 | |
| 183 | The length is written first, followed by an "at" character (ASCII |
| 184 | 0x40), then the offset, followed by a comma (ASCII 0x2c). |
| 185 | |
| 186 | <h1 id="intcoding">3.0 Encoding of integers</h1> |
| 187 | |
| 188 | The format currently handles only 32 bit integer numbers. They are |
| 189 | written base-64 encoded, MSB first, and without leading |
| 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. |
| 203 | Note that for integers less than 10, the base-64 coding is a |
| 204 | ASCII decimal rendering of the number itself. |
| 205 | |
| 206 | <h1 id="examples">4.0 Examples</h1> |
| 207 | |
| 208 | <h2 id="examplesint">4.1 Integer encoding</h2> |
| 209 | |
| @@ -232,18 +226,18 @@ | |
| 226 | </tr> |
| 227 | </table> |
| 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> |
| @@ -258,11 +252,11 @@ | |
| 252 | <tr><td> </td> <td>F: Example: eskil</td><td>Literal </td><td> 15 ' Example: eskil'</td></tr> |
| 253 | <tr><td> </td> <td>~E@Y0, </td><td>Copy </td><td> 4046 @ 2176 </td></tr> |
| 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 |
+6
-5
| --- www/encryptedrepos.wiki | ||
| +++ www/encryptedrepos.wiki | ||
| @@ -5,41 +5,42 @@ | ||
| 5 | 5 | This technical note explains the process. |
| 6 | 6 | </blockquote> |
| 7 | 7 | <h2>Building An Encryption-Enabled Fossil</h2><blockquote> |
| 8 | 8 | The SQLite Encryption Extension (SEE) is proprietary software and requires |
| 9 | 9 | [https://sqlite.org/purchase/see|purchasing a license]. |
| 10 | -<p> | |
| 10 | + | |
| 11 | 11 | Assuming you have an SEE license, the first step of compiling Fossil to |
| 12 | 12 | use SEE is to create an SEE-enabled version of the SQLite database source code. |
| 13 | 13 | This alternative SQLite database source file should be called "sqlite3-see.c" |
| 14 | 14 | and should be placed in the extsrc/ subfolder of the Fossil sources, right beside |
| 15 | 15 | the public-domain "sqlite3.c" source file. Also make a copy of the SEE-enabled |
| 16 | 16 | "shell.c" file, renamed as "shell-see.c", and place it in the extsrc/ subfolder |
| 17 | 17 | beside the original "shell.c". |
| 18 | -<p> | |
| 18 | + | |
| 19 | 19 | Add the --with-see command-line option to the configuration script to enable |
| 20 | 20 | the use of SEE on unix-like systems. |
| 21 | 21 | <blockquote><pre> |
| 22 | 22 | ./configure --with-see; make |
| 23 | 23 | </pre></blockquote> |
| 24 | -<p>To build for Windows using MSVC, add | |
| 24 | + | |
| 25 | +To build for Windows using MSVC, add | |
| 25 | 26 | the "USE_SEE=1" argument to the "nmake" command line. |
| 26 | 27 | <blockquote><pre> |
| 27 | 28 | nmake -f makefile.msc USE_SEE=1 |
| 28 | 29 | </pre></blockquote> |
| 29 | 30 | </blockquote> |
| 30 | 31 | <h2>Using Encrypted Repositories</h2><blockquote> |
| 31 | 32 | Any Fossil repositories whose filename ends with ".efossil" is taken to be |
| 32 | 33 | an encrypted repository. Fossil will prompt for the encryption password and |
| 33 | 34 | attempt to open the repository database using that password. |
| 34 | -<p> | |
| 35 | + | |
| 35 | 36 | Every invocation of fossil on an encrypted repository requires retyping the |
| 36 | 37 | encryption password. |
| 37 | 38 | To avoid excess password typing, consider using the "fossil shell" |
| 38 | 39 | command which prompts for the password just once, then reuses it for each |
| 39 | 40 | subsequent Fossil command entered at the prompt. |
| 40 | -<p> | |
| 41 | + | |
| 41 | 42 | On Windows, the "fossil server", "fossil ui", and "fossil shell" commands do not |
| 42 | 43 | (currently) work on an encrypted repository. |
| 43 | 44 | </blockquote> |
| 44 | 45 | <h2>Additional Security</h2><blockquote> |
| 45 | 46 | Use the FOSSIL_SECURITY_LEVEL environment for additional protection. |
| 46 | 47 |
| --- www/encryptedrepos.wiki | |
| +++ www/encryptedrepos.wiki | |
| @@ -5,41 +5,42 @@ | |
| 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 | <p> |
| 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. |
| 13 | This alternative SQLite database source file should be called "sqlite3-see.c" |
| 14 | and should be placed in the extsrc/ subfolder of the Fossil sources, right beside |
| 15 | the public-domain "sqlite3.c" source file. Also make a copy of the SEE-enabled |
| 16 | "shell.c" file, renamed as "shell-see.c", and place it in the extsrc/ subfolder |
| 17 | beside the original "shell.c". |
| 18 | <p> |
| 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 | <p>To build for Windows using MSVC, add |
| 25 | the "USE_SEE=1" argument to the "nmake" command line. |
| 26 | <blockquote><pre> |
| 27 | nmake -f makefile.msc USE_SEE=1 |
| 28 | </pre></blockquote> |
| 29 | </blockquote> |
| 30 | <h2>Using Encrypted Repositories</h2><blockquote> |
| 31 | Any Fossil repositories whose filename ends with ".efossil" is taken to be |
| 32 | an encrypted repository. Fossil will prompt for the encryption password and |
| 33 | attempt to open the repository database using that password. |
| 34 | <p> |
| 35 | Every invocation of fossil on an encrypted repository requires retyping the |
| 36 | encryption password. |
| 37 | To avoid excess password typing, consider using the "fossil shell" |
| 38 | command which prompts for the password just once, then reuses it for each |
| 39 | subsequent Fossil command entered at the prompt. |
| 40 | <p> |
| 41 | On Windows, the "fossil server", "fossil ui", and "fossil shell" commands do not |
| 42 | (currently) work on an encrypted repository. |
| 43 | </blockquote> |
| 44 | <h2>Additional Security</h2><blockquote> |
| 45 | Use the FOSSIL_SECURITY_LEVEL environment for additional protection. |
| 46 |
| --- www/encryptedrepos.wiki | |
| +++ www/encryptedrepos.wiki | |
| @@ -5,41 +5,42 @@ | |
| 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. |
| 13 | This alternative SQLite database source file should be called "sqlite3-see.c" |
| 14 | and should be placed in the extsrc/ subfolder of the Fossil sources, right beside |
| 15 | the public-domain "sqlite3.c" source file. Also make a copy of the SEE-enabled |
| 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 |
| 37 | encryption password. |
| 38 | To avoid excess password typing, consider using the "fossil shell" |
| 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 |
+1
-1
| --- www/faq.tcl | ||
| +++ www/faq.tcl | ||
| @@ -157,11 +157,11 @@ | ||
| 157 | 157 | ############################################################################# |
| 158 | 158 | # Code to actually generate the FAQ |
| 159 | 159 | # |
| 160 | 160 | puts "<title>Fossil FAQ</title>" |
| 161 | 161 | puts "<h1 align=\"center\">Frequently Asked Questions</h1>\n" |
| 162 | -puts "<p>Note: See also <a href=\"qandc.wiki\">Questions and Criticisms</a>.\n" | |
| 162 | +puts "Note: See also <a href=\"qandc.wiki\">Questions and Criticisms</a>.\n" | |
| 163 | 163 | |
| 164 | 164 | puts {<ol>} |
| 165 | 165 | for {set i 1} {$i<$cnt} {incr i} { |
| 166 | 166 | puts "<li><a href=\"#q$i\">[lindex $faq($i) 0]</a></li>" |
| 167 | 167 | } |
| 168 | 168 |
| --- www/faq.tcl | |
| +++ www/faq.tcl | |
| @@ -157,11 +157,11 @@ | |
| 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 "<p>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>" |
| 167 | } |
| 168 |
| --- www/faq.tcl | |
| +++ www/faq.tcl | |
| @@ -157,11 +157,11 @@ | |
| 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>" |
| 167 | } |
| 168 |
+1
-1
| --- www/faq.wiki | ||
| +++ www/faq.wiki | ||
| @@ -1,9 +1,9 @@ | ||
| 1 | 1 | <title>Fossil FAQ</title> |
| 2 | 2 | <h1 align="center">Frequently Asked Questions</h1> |
| 3 | 3 | |
| 4 | -<p>Note: See also <a href="qandc.wiki">Questions and Criticisms</a>. | |
| 4 | +Note: See also <a href="qandc.wiki">Questions and Criticisms</a>. | |
| 5 | 5 | |
| 6 | 6 | <ol> |
| 7 | 7 | <li><a href="#q1">What GUIs are available for fossil?</a></li> |
| 8 | 8 | <li><a href="#q2">What is the difference between a "branch" and a "fork"?</a></li> |
| 9 | 9 | <li><a href="#q3">How do I create a new branch?</a></li> |
| 10 | 10 |
| --- www/faq.wiki | |
| +++ www/faq.wiki | |
| @@ -1,9 +1,9 @@ | |
| 1 | <title>Fossil FAQ</title> |
| 2 | <h1 align="center">Frequently Asked Questions</h1> |
| 3 | |
| 4 | <p>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> |
| 8 | <li><a href="#q2">What is the difference between a "branch" and a "fork"?</a></li> |
| 9 | <li><a href="#q3">How do I create a new branch?</a></li> |
| 10 |
| --- www/faq.wiki | |
| +++ www/faq.wiki | |
| @@ -1,9 +1,9 @@ | |
| 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> |
| 8 | <li><a href="#q2">What is the difference between a "branch" and a "fork"?</a></li> |
| 9 | <li><a href="#q3">How do I create a new branch?</a></li> |
| 10 |
+27
-27
| --- www/foss-cklist.wiki | ||
| +++ www/foss-cklist.wiki | ||
| @@ -1,25 +1,25 @@ | ||
| 1 | 1 | <title>Checklist For Successful Open-Source Projects</title> |
| 2 | 2 | <nowiki> |
| 3 | 3 | |
| 4 | -<p>This checklist is loosely derived from Tom "Spot" Callaway's Fail Score | |
| 4 | +This checklist is loosely derived from Tom "Spot" Callaway's Fail Score | |
| 5 | 5 | blog post <a href="http://spot.livejournal.com/308370.html"> |
| 6 | 6 | http://spot.livejournal.com/308370.html</a> (see also |
| 7 | 7 | <a href="http://www.theopensourceway.org/book/The_Open_Source_Way-How_to_tell_if_a_FLOSS_project_is_doomed_to_FAIL.html">[1]</a>). |
| 8 | 8 | Tom's original post assigned point scores to the various elements and |
| 9 | 9 | by adding together the individual points, the reader is supposed to be able |
| 10 | 10 | to judge the likelihood that the project will fail. |
| 11 | 11 | The point scores, and the items on the list, clearly reflect Tom's |
| 12 | 12 | biases and are not necessarily those of the larger open-source community. |
| 13 | 13 | Nevertheless, the policy of the Fossil shall be to strive for a perfect |
| 14 | -score.</p> | |
| 14 | +score. | |
| 15 | 15 | |
| 16 | -<p>This checklist is an inversion of Tom's original post in that it strives to | |
| 16 | +This checklist is an inversion of Tom's original post in that it strives to | |
| 17 | 17 | say what the project should do in order to succeed rather than what it |
| 18 | -should not do to avoid failure. The point values are omitted.</p> | |
| 18 | +should not do to avoid failure. The point values are omitted. | |
| 19 | 19 | |
| 20 | -<p>See also: | |
| 20 | +See also: | |
| 21 | 21 | <ul> |
| 22 | 22 | <li><a href="http://offog.org/articles/packaging/"> |
| 23 | 23 | http://offog.org/articles/packaging/</a> |
| 24 | 24 | <li> |
| 25 | 25 | <a href="http://www.gnu.org/prep/standards/standards.html#Managing-Releases"> |
| @@ -27,36 +27,36 @@ | ||
| 27 | 27 | </ul> |
| 28 | 28 | |
| 29 | 29 | <hr> |
| 30 | 30 | |
| 31 | 31 | <ol> |
| 32 | -<li><p>The source code size is less than 100 MB, uncompressed. | |
| 32 | +<li>The source code size is less than 100 MB, uncompressed. | |
| 33 | 33 | |
| 34 | -<li><p>The project uses a Version Control System (VCS). | |
| 34 | +<li>The project uses a Version Control System (VCS). | |
| 35 | 35 | <ol type="a"> |
| 36 | 36 | <li>The VCS has a working web interface. |
| 37 | 37 | <li>There is documentation on how to use the VCS. |
| 38 | 38 | <li>The VCS is general-purpose, not something hacked together for this |
| 39 | 39 | one project. |
| 40 | 40 | </ol> |
| 41 | 41 | |
| 42 | -<li><p>The project comes with documentation on how to build from source | |
| 42 | +<li>The project comes with documentation on how to build from source | |
| 43 | 43 | and that documentation is lucid, correct, and up-to-date. |
| 44 | 44 | |
| 45 | -<li><p>The project is configurable using an autoconf-generated configure | |
| 45 | +<li>The project is configurable using an autoconf-generated configure | |
| 46 | 46 | script, or the equivalent, and does not require: |
| 47 | 47 | <ol type="a"> |
| 48 | 48 | <li>Manually editing flat files |
| 49 | 49 | <li>Editing code header files |
| 50 | 50 | </ol> |
| 51 | 51 | |
| 52 | -<li><p>The project should be buildable using commonly available and | |
| 52 | +<li>The project should be buildable using commonly available and | |
| 53 | 53 | standard tools like "make". |
| 54 | 54 | |
| 55 | -<li><p>The project does not depend on 3rd-party proprietary build tools. | |
| 55 | +<li>The project does not depend on 3rd-party proprietary build tools. | |
| 56 | 56 | |
| 57 | -<li><p>The project is able to dynamically link against standard libraries | |
| 57 | +<li>The project is able to dynamically link against standard libraries | |
| 58 | 58 | such as zlib and libjpeg. |
| 59 | 59 | <ol type="a"> |
| 60 | 60 | <li>The project does not ship with the sources to standard libraries. |
| 61 | 61 | <i>(On the Fossil project, we will allow the SQLite library sources |
| 62 | 62 | to be included in the source tree as long as a system-installed |
| @@ -65,48 +65,48 @@ | ||
| 65 | 65 | libraries. Any required bug fixes in standard libraries are pushed |
| 66 | 66 | back upstream. |
| 67 | 67 | </ol> |
| 68 | 68 | |
| 69 | 69 | |
| 70 | -<li><p>"make install" works and can be configured to target any | |
| 70 | +<li>"make install" works and can be configured to target any | |
| 71 | 71 | directory of the installer's choosing. |
| 72 | 72 | <ol type="a"> |
| 73 | 73 | <li>The project contains no unconfigurable hard-coded pathnames like |
| 74 | 74 | "/opt" or "/usr/local". |
| 75 | 75 | <li>After installation, the source tree can be moved or deleted and |
| 76 | 76 | the application will continue working. |
| 77 | 77 | </ol> |
| 78 | 78 | |
| 79 | 79 | |
| 80 | -<li><p>The source code uses only \n for line endings, not \r\n. | |
| 80 | +<li>The source code uses only \n for line endings, not \r\n. | |
| 81 | 81 | |
| 82 | -<li><p>The code does not depend on any special compiler features or bugs. | |
| 82 | +<li>The code does not depend on any special compiler features or bugs. | |
| 83 | 83 | |
| 84 | -<li><p>The project has a mailing list and announces releases on | |
| 84 | +<li>The project has a mailing list and announces releases on | |
| 85 | 85 | the mailing list. |
| 86 | 86 | |
| 87 | -<li><p>The project has a bug tracker. | |
| 87 | +<li>The project has a bug tracker. | |
| 88 | + | |
| 89 | +<li>The project has a website. | |
| 88 | 90 | |
| 89 | -<li><p>The project has a website. | |
| 91 | +<li>Release version numbers are in the traditional X.Y or X.Y.Z format. | |
| 90 | 92 | |
| 91 | -<li><p>Release version numbers are in the traditional X.Y or X.Y.Z format. | |
| 92 | - | |
| 93 | -<li><p>Releases can be downloaded as tarball using | |
| 93 | +<li>Releases can be downloaded as tarball using | |
| 94 | 94 | gzip or bzip2 compression. |
| 95 | 95 | |
| 96 | -<li><p>Releases unpack into a versioned top-level directory. | |
| 96 | +<li>Releases unpack into a versioned top-level directory. | |
| 97 | 97 | (ex: "projectname-1.2.3/"). |
| 98 | 98 | |
| 99 | -<li><p>A statement of license appears at the top of every source code file | |
| 99 | +<li>A statement of license appears at the top of every source code file | |
| 100 | 100 | and the complete text of the license is included in the source code |
| 101 | 101 | tarball. |
| 102 | 102 | |
| 103 | -<li><p>There are no incompatible licenses in the code. | |
| 103 | +<li>There are no incompatible licenses in the code. | |
| 104 | 104 | |
| 105 | -<li><p>The project has not been blithely proclaimed "public domain" without | |
| 105 | +<li>The project has not been blithely proclaimed "public domain" without | |
| 106 | 106 | having gone through the tedious and exacting legal steps to actually put it |
| 107 | 107 | in the public domain. |
| 108 | 108 | |
| 109 | -<li><p>There is an accurate change log in the code and on the website. | |
| 109 | +<li>There is an accurate change log in the code and on the website. | |
| 110 | 110 | |
| 111 | -<li><p>There is documentation in the code and on the website. | |
| 111 | +<li>There is documentation in the code and on the website. | |
| 112 | 112 | </ol> |
| 113 | 113 |
| --- www/foss-cklist.wiki | |
| +++ www/foss-cklist.wiki | |
| @@ -1,25 +1,25 @@ | |
| 1 | <title>Checklist For Successful Open-Source Projects</title> |
| 2 | <nowiki> |
| 3 | |
| 4 | <p>This checklist is loosely derived from Tom "Spot" Callaway's Fail Score |
| 5 | blog post <a href="http://spot.livejournal.com/308370.html"> |
| 6 | http://spot.livejournal.com/308370.html</a> (see also |
| 7 | <a href="http://www.theopensourceway.org/book/The_Open_Source_Way-How_to_tell_if_a_FLOSS_project_is_doomed_to_FAIL.html">[1]</a>). |
| 8 | Tom's original post assigned point scores to the various elements and |
| 9 | by adding together the individual points, the reader is supposed to be able |
| 10 | to judge the likelihood that the project will fail. |
| 11 | The point scores, and the items on the list, clearly reflect Tom's |
| 12 | biases and are not necessarily those of the larger open-source community. |
| 13 | Nevertheless, the policy of the Fossil shall be to strive for a perfect |
| 14 | score.</p> |
| 15 | |
| 16 | <p>This checklist is an inversion of Tom's original post in that it strives to |
| 17 | say what the project should do in order to succeed rather than what it |
| 18 | should not do to avoid failure. The point values are omitted.</p> |
| 19 | |
| 20 | <p>See also: |
| 21 | <ul> |
| 22 | <li><a href="http://offog.org/articles/packaging/"> |
| 23 | http://offog.org/articles/packaging/</a> |
| 24 | <li> |
| 25 | <a href="http://www.gnu.org/prep/standards/standards.html#Managing-Releases"> |
| @@ -27,36 +27,36 @@ | |
| 27 | </ul> |
| 28 | |
| 29 | <hr> |
| 30 | |
| 31 | <ol> |
| 32 | <li><p>The source code size is less than 100 MB, uncompressed. |
| 33 | |
| 34 | <li><p>The project uses a Version Control System (VCS). |
| 35 | <ol type="a"> |
| 36 | <li>The VCS has a working web interface. |
| 37 | <li>There is documentation on how to use the VCS. |
| 38 | <li>The VCS is general-purpose, not something hacked together for this |
| 39 | one project. |
| 40 | </ol> |
| 41 | |
| 42 | <li><p>The project comes with documentation on how to build from source |
| 43 | and that documentation is lucid, correct, and up-to-date. |
| 44 | |
| 45 | <li><p>The project is configurable using an autoconf-generated configure |
| 46 | script, or the equivalent, and does not require: |
| 47 | <ol type="a"> |
| 48 | <li>Manually editing flat files |
| 49 | <li>Editing code header files |
| 50 | </ol> |
| 51 | |
| 52 | <li><p>The project should be buildable using commonly available and |
| 53 | standard tools like "make". |
| 54 | |
| 55 | <li><p>The project does not depend on 3rd-party proprietary build tools. |
| 56 | |
| 57 | <li><p>The project is able to dynamically link against standard libraries |
| 58 | such as zlib and libjpeg. |
| 59 | <ol type="a"> |
| 60 | <li>The project does not ship with the sources to standard libraries. |
| 61 | <i>(On the Fossil project, we will allow the SQLite library sources |
| 62 | to be included in the source tree as long as a system-installed |
| @@ -65,48 +65,48 @@ | |
| 65 | libraries. Any required bug fixes in standard libraries are pushed |
| 66 | back upstream. |
| 67 | </ol> |
| 68 | |
| 69 | |
| 70 | <li><p>"make install" works and can be configured to target any |
| 71 | directory of the installer's choosing. |
| 72 | <ol type="a"> |
| 73 | <li>The project contains no unconfigurable hard-coded pathnames like |
| 74 | "/opt" or "/usr/local". |
| 75 | <li>After installation, the source tree can be moved or deleted and |
| 76 | the application will continue working. |
| 77 | </ol> |
| 78 | |
| 79 | |
| 80 | <li><p>The source code uses only \n for line endings, not \r\n. |
| 81 | |
| 82 | <li><p>The code does not depend on any special compiler features or bugs. |
| 83 | |
| 84 | <li><p>The project has a mailing list and announces releases on |
| 85 | the mailing list. |
| 86 | |
| 87 | <li><p>The project has a bug tracker. |
| 88 | |
| 89 | <li><p>The project has a website. |
| 90 | |
| 91 | <li><p>Release version numbers are in the traditional X.Y or X.Y.Z format. |
| 92 | |
| 93 | <li><p>Releases can be downloaded as tarball using |
| 94 | gzip or bzip2 compression. |
| 95 | |
| 96 | <li><p>Releases unpack into a versioned top-level directory. |
| 97 | (ex: "projectname-1.2.3/"). |
| 98 | |
| 99 | <li><p>A statement of license appears at the top of every source code file |
| 100 | and the complete text of the license is included in the source code |
| 101 | tarball. |
| 102 | |
| 103 | <li><p>There are no incompatible licenses in the code. |
| 104 | |
| 105 | <li><p>The project has not been blithely proclaimed "public domain" without |
| 106 | having gone through the tedious and exacting legal steps to actually put it |
| 107 | in the public domain. |
| 108 | |
| 109 | <li><p>There is an accurate change log in the code and on the website. |
| 110 | |
| 111 | <li><p>There is documentation in the code and on the website. |
| 112 | </ol> |
| 113 |
| --- www/foss-cklist.wiki | |
| +++ www/foss-cklist.wiki | |
| @@ -1,25 +1,25 @@ | |
| 1 | <title>Checklist For Successful Open-Source Projects</title> |
| 2 | <nowiki> |
| 3 | |
| 4 | This checklist is loosely derived from Tom "Spot" Callaway's Fail Score |
| 5 | blog post <a href="http://spot.livejournal.com/308370.html"> |
| 6 | http://spot.livejournal.com/308370.html</a> (see also |
| 7 | <a href="http://www.theopensourceway.org/book/The_Open_Source_Way-How_to_tell_if_a_FLOSS_project_is_doomed_to_FAIL.html">[1]</a>). |
| 8 | Tom's original post assigned point scores to the various elements and |
| 9 | by adding together the individual points, the reader is supposed to be able |
| 10 | to judge the likelihood that the project will fail. |
| 11 | The point scores, and the items on the list, clearly reflect Tom's |
| 12 | biases and are not necessarily those of the larger open-source community. |
| 13 | Nevertheless, the policy of the Fossil shall be to strive for a perfect |
| 14 | score. |
| 15 | |
| 16 | This checklist is an inversion of Tom's original post in that it strives to |
| 17 | say what the project should do in order to succeed rather than what it |
| 18 | should not do to avoid failure. The point values are omitted. |
| 19 | |
| 20 | See also: |
| 21 | <ul> |
| 22 | <li><a href="http://offog.org/articles/packaging/"> |
| 23 | http://offog.org/articles/packaging/</a> |
| 24 | <li> |
| 25 | <a href="http://www.gnu.org/prep/standards/standards.html#Managing-Releases"> |
| @@ -27,36 +27,36 @@ | |
| 27 | </ul> |
| 28 | |
| 29 | <hr> |
| 30 | |
| 31 | <ol> |
| 32 | <li>The source code size is less than 100 MB, uncompressed. |
| 33 | |
| 34 | <li>The project uses a Version Control System (VCS). |
| 35 | <ol type="a"> |
| 36 | <li>The VCS has a working web interface. |
| 37 | <li>There is documentation on how to use the VCS. |
| 38 | <li>The VCS is general-purpose, not something hacked together for this |
| 39 | one project. |
| 40 | </ol> |
| 41 | |
| 42 | <li>The project comes with documentation on how to build from source |
| 43 | and that documentation is lucid, correct, and up-to-date. |
| 44 | |
| 45 | <li>The project is configurable using an autoconf-generated configure |
| 46 | script, or the equivalent, and does not require: |
| 47 | <ol type="a"> |
| 48 | <li>Manually editing flat files |
| 49 | <li>Editing code header files |
| 50 | </ol> |
| 51 | |
| 52 | <li>The project should be buildable using commonly available and |
| 53 | standard tools like "make". |
| 54 | |
| 55 | <li>The project does not depend on 3rd-party proprietary build tools. |
| 56 | |
| 57 | <li>The project is able to dynamically link against standard libraries |
| 58 | such as zlib and libjpeg. |
| 59 | <ol type="a"> |
| 60 | <li>The project does not ship with the sources to standard libraries. |
| 61 | <i>(On the Fossil project, we will allow the SQLite library sources |
| 62 | to be included in the source tree as long as a system-installed |
| @@ -65,48 +65,48 @@ | |
| 65 | libraries. Any required bug fixes in standard libraries are pushed |
| 66 | back upstream. |
| 67 | </ol> |
| 68 | |
| 69 | |
| 70 | <li>"make install" works and can be configured to target any |
| 71 | directory of the installer's choosing. |
| 72 | <ol type="a"> |
| 73 | <li>The project contains no unconfigurable hard-coded pathnames like |
| 74 | "/opt" or "/usr/local". |
| 75 | <li>After installation, the source tree can be moved or deleted and |
| 76 | the application will continue working. |
| 77 | </ol> |
| 78 | |
| 79 | |
| 80 | <li>The source code uses only \n for line endings, not \r\n. |
| 81 | |
| 82 | <li>The code does not depend on any special compiler features or bugs. |
| 83 | |
| 84 | <li>The project has a mailing list and announces releases on |
| 85 | the mailing list. |
| 86 | |
| 87 | <li>The project has a bug tracker. |
| 88 | |
| 89 | <li>The project has a website. |
| 90 | |
| 91 | <li>Release version numbers are in the traditional X.Y or X.Y.Z format. |
| 92 | |
| 93 | <li>Releases can be downloaded as tarball using |
| 94 | gzip or bzip2 compression. |
| 95 | |
| 96 | <li>Releases unpack into a versioned top-level directory. |
| 97 | (ex: "projectname-1.2.3/"). |
| 98 | |
| 99 | <li>A statement of license appears at the top of every source code file |
| 100 | and the complete text of the license is included in the source code |
| 101 | tarball. |
| 102 | |
| 103 | <li>There are no incompatible licenses in the code. |
| 104 | |
| 105 | <li>The project has not been blithely proclaimed "public domain" without |
| 106 | having gone through the tedious and exacting legal steps to actually put it |
| 107 | in the public domain. |
| 108 | |
| 109 | <li>There is an accurate change log in the code and on the website. |
| 110 | |
| 111 | <li>There is documentation in the code and on the website. |
| 112 | </ol> |
| 113 |
+70
-72
| --- www/fossil-v-git.wiki | ||
| +++ www/fossil-v-git.wiki | ||
| @@ -424,82 +424,80 @@ | ||
| 424 | 424 | |
| 425 | 425 | Fossil's normal mode of operation differs on every one of these points, |
| 426 | 426 | with the specific designed-in goal of promoting SQLite's cathedral |
| 427 | 427 | development model: |
| 428 | 428 | |
| 429 | -<ul> | |
| 430 | - <li><p><b>Personal engagement:</b> SQLite's developers know each | |
| 431 | - other by name and work together daily on the project.</p></li> | |
| 432 | - | |
| 433 | - <li><p><b>Trust over hierarchy:</b> SQLite's developers check | |
| 434 | - changes into their local repository, and these are immediately and | |
| 435 | - automatically synchronized up to the central repository; there is no | |
| 436 | - "[https://git-scm.com/book/en/v2/Distributed-Git-Distributed-Workflows#_dictator_and_lieutenants_workflow|dictator | |
| 437 | - and lieutenants]" hierarchy as with Linux kernel contributions. D. | |
| 438 | - Richard Hipp rarely overrides decisions made by those he has trusted | |
| 439 | - with commit access on his repositories. Fossil allows you to give | |
| 440 | - [./caps/admin-v-setup.md|some users] more power over what | |
| 441 | - they can do with the repository, but Fossil [./caps/index.md#ucap | | |
| 442 | - only loosely supports] the enforcement of a development organization's | |
| 443 | - social and power hierarchies. Fossil is a great fit for | |
| 444 | - [https://en.wikipedia.org/wiki/Flat_organization|flat | |
| 445 | - organizations].</p></li> | |
| 446 | - | |
| 447 | - <li><p><b>No easy drive-by contributions:</b> Git | |
| 448 | - [https://www.git-scm.com/docs/git-request-pull|pull requests] offer | |
| 449 | - a low-friction path to accepting | |
| 450 | - [https://www.jonobacon.com/2012/07/25/building-strong-community-structural-integrity/|drive-by | |
| 451 | - contributions]. Fossil's closest equivalents are its unique | |
| 452 | - [/help?cmd=bundle|bundle] and [/help?cmd=patch|patch] features, which require higher engagement | |
| 453 | - than firing off a PR.⁷ This difference comes directly from the | |
| 454 | - initial designed purpose for each tool: the SQLite project doesn't | |
| 455 | - accept outside contributions from previously-unknown developers, but | |
| 456 | - the Linux kernel does.</p></li> | |
| 457 | - | |
| 458 | - <li><p><b>No rebasing:</b> When your local repo clone syncs changes | |
| 459 | - up to its parent, those changes are sent exactly as they were | |
| 460 | - committed locally. [#history|There is no rebasing mechanism in | |
| 461 | - Fossil, on purpose.]</p></li> | |
| 462 | - | |
| 463 | - <li><p><b>Sync over push:</b> Explicit pushes are uncommon in | |
| 464 | - Fossil-based projects: the default is to rely on | |
| 465 | - [/help?cmd=autosync|autosync mode] instead, in which each commit | |
| 466 | - syncs immediately to its parent repository. This is a mode so you | |
| 467 | - can turn it off temporarily when needed, such as when working | |
| 468 | - offline. Fossil is still a truly distributed version control system; | |
| 469 | - it's just that its starting default is to assume you're rarely out | |
| 470 | - of communication with the parent repo. | |
| 471 | - <br><br> | |
| 472 | - This is not merely a reflection of modern always-connected computing | |
| 473 | - environments. It is a conscious decision in direct support of | |
| 474 | - SQLite's cathedral development model: we don't want developers going | |
| 475 | - dark, then showing up weeks later with a massive bolus of changes | |
| 476 | - for us to integrate all at once. | |
| 477 | - [https://en.wikipedia.org/wiki/Jim_McCarthy_(author)|Jim McCarthy] | |
| 478 | - put it well in his book on software project management, | |
| 479 | - <i>[https://www.amazon.com/dp/0735623198/|Dynamics of Software | |
| 480 | - Development]</i>: "[https://www.youtube.com/watch?v=oY6BCHqEbyc|Beware | |
| 481 | - of a guy in a room]."</p></li> | |
| 482 | - | |
| 483 | - <li><p><b>Branch names sync:</b> Unlike in Git, branch names in | |
| 484 | - Fossil are not purely local labels. They sync along with everything | |
| 485 | - else, so everyone sees the same set of branch names. Fossil's design | |
| 486 | - choice here is a direct reflection of the Linux vs. SQLite project | |
| 487 | - outlook: SQLite's developers collaborate closely on a single | |
| 488 | - coherent project, whereas Linux's developers go off on tangents and | |
| 489 | - occasionally send selected change sets to each other.</p></li> | |
| 490 | - | |
| 491 | - <li><p><b>Private branches are rare:</b> | |
| 492 | - [/doc/trunk/www/private.wiki|Private branches exist in Fossil], but | |
| 493 | - they're normally used to handle rare exception cases, whereas in | |
| 494 | - many Git projects, they're part of the straight-line development | |
| 495 | - process.</p></li> | |
| 496 | - | |
| 497 | - <li><p><b>Identical clones:</b> Fossil's autosync system tries to | |
| 498 | - keep each local clone identical to the repository it cloned | |
| 499 | - from.</p></li> | |
| 500 | -</ul> | |
| 429 | + * <b>Personal engagement:</b> SQLite's developers know each | |
| 430 | + other by name and work together daily on the project. | |
| 431 | + | |
| 432 | + * <b>Trust over hierarchy:</b> SQLite's developers check | |
| 433 | + changes into their local repository, and these are immediately and | |
| 434 | + automatically synchronized up to the central repository; there is no | |
| 435 | + "[https://git-scm.com/book/en/v2/Distributed-Git-Distributed-Workflows#_dictator_and_lieutenants_workflow|dictator | |
| 436 | + and lieutenants]" hierarchy as with Linux kernel contributions. D. | |
| 437 | + Richard Hipp rarely overrides decisions made by those he has trusted | |
| 438 | + with commit access on his repositories. Fossil allows you to give | |
| 439 | + [./caps/admin-v-setup.md|some users] more power over what | |
| 440 | + they can do with the repository, but Fossil [./caps/index.md#ucap | | |
| 441 | + only loosely supports] the enforcement of a development organization's | |
| 442 | + social and power hierarchies. Fossil is a great fit for | |
| 443 | + [https://en.wikipedia.org/wiki/Flat_organization|flat | |
| 444 | + organizations]. | |
| 445 | + | |
| 446 | + * <b>No easy drive-by contributions:</b> Git | |
| 447 | + [https://www.git-scm.com/docs/git-request-pull|pull requests] offer | |
| 448 | + a low-friction path to accepting | |
| 449 | + [https://www.jonobacon.com/2012/07/25/building-strong-community-structural-integrity/|drive-by | |
| 450 | + contributions]. Fossil's closest equivalents are its unique | |
| 451 | + [/help?cmd=bundle|bundle] and [/help?cmd=patch|patch] features, which require higher engagement | |
| 452 | + than firing off a PR.⁷ This difference comes directly from the | |
| 453 | + initial designed purpose for each tool: the SQLite project doesn't | |
| 454 | + accept outside contributions from previously-unknown developers, but | |
| 455 | + the Linux kernel does. | |
| 456 | + | |
| 457 | + * <b>No rebasing:</b> When your local repo clone syncs changes | |
| 458 | + up to its parent, those changes are sent exactly as they were | |
| 459 | + committed locally. [#history|There is no rebasing mechanism in | |
| 460 | + Fossil, on purpose.] | |
| 461 | + | |
| 462 | + * <b>Sync over push:</b> Explicit pushes are uncommon in | |
| 463 | + Fossil-based projects: the default is to rely on | |
| 464 | + [/help?cmd=autosync|autosync mode] instead, in which each commit | |
| 465 | + syncs immediately to its parent repository. This is a mode so you | |
| 466 | + can turn it off temporarily when needed, such as when working | |
| 467 | + offline. Fossil is still a truly distributed version control system; | |
| 468 | + it's just that its starting default is to assume you're rarely out | |
| 469 | + of communication with the parent repo. | |
| 470 | + <br><br> | |
| 471 | + This is not merely a reflection of modern always-connected computing | |
| 472 | + environments. It is a conscious decision in direct support of | |
| 473 | + SQLite's cathedral development model: we don't want developers going | |
| 474 | + dark, then showing up weeks later with a massive bolus of changes | |
| 475 | + for us to integrate all at once. | |
| 476 | + [https://en.wikipedia.org/wiki/Jim_McCarthy_(author)|Jim McCarthy] | |
| 477 | + put it well in his book on software project management, | |
| 478 | + <i>[https://www.amazon.com/dp/0735623198/|Dynamics of Software | |
| 479 | + Development]</i>: "[https://www.youtube.com/watch?v=oY6BCHqEbyc|Beware | |
| 480 | + of a guy in a room]." | |
| 481 | + | |
| 482 | + * <b>Branch names sync:</b> Unlike in Git, branch names in | |
| 483 | + Fossil are not purely local labels. They sync along with everything | |
| 484 | + else, so everyone sees the same set of branch names. Fossil's design | |
| 485 | + choice here is a direct reflection of the Linux vs. SQLite project | |
| 486 | + outlook: SQLite's developers collaborate closely on a single | |
| 487 | + coherent project, whereas Linux's developers go off on tangents and | |
| 488 | + occasionally send selected change sets to each other. | |
| 489 | + | |
| 490 | + * <b>Private branches are rare:</b> | |
| 491 | + [/doc/trunk/www/private.wiki|Private branches exist in Fossil], but | |
| 492 | + they're normally used to handle rare exception cases, whereas in | |
| 493 | + many Git projects, they're part of the straight-line development | |
| 494 | + process. | |
| 495 | + | |
| 496 | + * <b>Identical clones:</b> Fossil's autosync system tries to | |
| 497 | + keep each local clone identical to the repository it cloned | |
| 498 | + from. | |
| 501 | 499 | |
| 502 | 500 | Where Git encourages siloed development, Fossil fights against it. |
| 503 | 501 | Fossil places a lot of emphasis on synchronizing everyone's work and on |
| 504 | 502 | reporting on the state of the project and the work of its developers, so |
| 505 | 503 | that everyone — especially the project leader — can maintain a better |
| 506 | 504 |
| --- www/fossil-v-git.wiki | |
| +++ www/fossil-v-git.wiki | |
| @@ -424,82 +424,80 @@ | |
| 424 | |
| 425 | Fossil's normal mode of operation differs on every one of these points, |
| 426 | with the specific designed-in goal of promoting SQLite's cathedral |
| 427 | development model: |
| 428 | |
| 429 | <ul> |
| 430 | <li><p><b>Personal engagement:</b> SQLite's developers know each |
| 431 | other by name and work together daily on the project.</p></li> |
| 432 | |
| 433 | <li><p><b>Trust over hierarchy:</b> SQLite's developers check |
| 434 | changes into their local repository, and these are immediately and |
| 435 | automatically synchronized up to the central repository; there is no |
| 436 | "[https://git-scm.com/book/en/v2/Distributed-Git-Distributed-Workflows#_dictator_and_lieutenants_workflow|dictator |
| 437 | and lieutenants]" hierarchy as with Linux kernel contributions. D. |
| 438 | Richard Hipp rarely overrides decisions made by those he has trusted |
| 439 | with commit access on his repositories. Fossil allows you to give |
| 440 | [./caps/admin-v-setup.md|some users] more power over what |
| 441 | they can do with the repository, but Fossil [./caps/index.md#ucap | |
| 442 | only loosely supports] the enforcement of a development organization's |
| 443 | social and power hierarchies. Fossil is a great fit for |
| 444 | [https://en.wikipedia.org/wiki/Flat_organization|flat |
| 445 | organizations].</p></li> |
| 446 | |
| 447 | <li><p><b>No easy drive-by contributions:</b> Git |
| 448 | [https://www.git-scm.com/docs/git-request-pull|pull requests] offer |
| 449 | a low-friction path to accepting |
| 450 | [https://www.jonobacon.com/2012/07/25/building-strong-community-structural-integrity/|drive-by |
| 451 | contributions]. Fossil's closest equivalents are its unique |
| 452 | [/help?cmd=bundle|bundle] and [/help?cmd=patch|patch] features, which require higher engagement |
| 453 | than firing off a PR.⁷ This difference comes directly from the |
| 454 | initial designed purpose for each tool: the SQLite project doesn't |
| 455 | accept outside contributions from previously-unknown developers, but |
| 456 | the Linux kernel does.</p></li> |
| 457 | |
| 458 | <li><p><b>No rebasing:</b> When your local repo clone syncs changes |
| 459 | up to its parent, those changes are sent exactly as they were |
| 460 | committed locally. [#history|There is no rebasing mechanism in |
| 461 | Fossil, on purpose.]</p></li> |
| 462 | |
| 463 | <li><p><b>Sync over push:</b> Explicit pushes are uncommon in |
| 464 | Fossil-based projects: the default is to rely on |
| 465 | [/help?cmd=autosync|autosync mode] instead, in which each commit |
| 466 | syncs immediately to its parent repository. This is a mode so you |
| 467 | can turn it off temporarily when needed, such as when working |
| 468 | offline. Fossil is still a truly distributed version control system; |
| 469 | it's just that its starting default is to assume you're rarely out |
| 470 | of communication with the parent repo. |
| 471 | <br><br> |
| 472 | This is not merely a reflection of modern always-connected computing |
| 473 | environments. It is a conscious decision in direct support of |
| 474 | SQLite's cathedral development model: we don't want developers going |
| 475 | dark, then showing up weeks later with a massive bolus of changes |
| 476 | for us to integrate all at once. |
| 477 | [https://en.wikipedia.org/wiki/Jim_McCarthy_(author)|Jim McCarthy] |
| 478 | put it well in his book on software project management, |
| 479 | <i>[https://www.amazon.com/dp/0735623198/|Dynamics of Software |
| 480 | Development]</i>: "[https://www.youtube.com/watch?v=oY6BCHqEbyc|Beware |
| 481 | of a guy in a room]."</p></li> |
| 482 | |
| 483 | <li><p><b>Branch names sync:</b> Unlike in Git, branch names in |
| 484 | Fossil are not purely local labels. They sync along with everything |
| 485 | else, so everyone sees the same set of branch names. Fossil's design |
| 486 | choice here is a direct reflection of the Linux vs. SQLite project |
| 487 | outlook: SQLite's developers collaborate closely on a single |
| 488 | coherent project, whereas Linux's developers go off on tangents and |
| 489 | occasionally send selected change sets to each other.</p></li> |
| 490 | |
| 491 | <li><p><b>Private branches are rare:</b> |
| 492 | [/doc/trunk/www/private.wiki|Private branches exist in Fossil], but |
| 493 | they're normally used to handle rare exception cases, whereas in |
| 494 | many Git projects, they're part of the straight-line development |
| 495 | process.</p></li> |
| 496 | |
| 497 | <li><p><b>Identical clones:</b> Fossil's autosync system tries to |
| 498 | keep each local clone identical to the repository it cloned |
| 499 | from.</p></li> |
| 500 | </ul> |
| 501 | |
| 502 | Where Git encourages siloed development, Fossil fights against it. |
| 503 | Fossil places a lot of emphasis on synchronizing everyone's work and on |
| 504 | reporting on the state of the project and the work of its developers, so |
| 505 | that everyone — especially the project leader — can maintain a better |
| 506 |
| --- www/fossil-v-git.wiki | |
| +++ www/fossil-v-git.wiki | |
| @@ -424,82 +424,80 @@ | |
| 424 | |
| 425 | Fossil's normal mode of operation differs on every one of these points, |
| 426 | with the specific designed-in goal of promoting SQLite's cathedral |
| 427 | development model: |
| 428 | |
| 429 | * <b>Personal engagement:</b> SQLite's developers know each |
| 430 | other by name and work together daily on the project. |
| 431 | |
| 432 | * <b>Trust over hierarchy:</b> SQLite's developers check |
| 433 | changes into their local repository, and these are immediately and |
| 434 | automatically synchronized up to the central repository; there is no |
| 435 | "[https://git-scm.com/book/en/v2/Distributed-Git-Distributed-Workflows#_dictator_and_lieutenants_workflow|dictator |
| 436 | and lieutenants]" hierarchy as with Linux kernel contributions. D. |
| 437 | Richard Hipp rarely overrides decisions made by those he has trusted |
| 438 | with commit access on his repositories. Fossil allows you to give |
| 439 | [./caps/admin-v-setup.md|some users] more power over what |
| 440 | they can do with the repository, but Fossil [./caps/index.md#ucap | |
| 441 | only loosely supports] the enforcement of a development organization's |
| 442 | social and power hierarchies. Fossil is a great fit for |
| 443 | [https://en.wikipedia.org/wiki/Flat_organization|flat |
| 444 | organizations]. |
| 445 | |
| 446 | * <b>No easy drive-by contributions:</b> Git |
| 447 | [https://www.git-scm.com/docs/git-request-pull|pull requests] offer |
| 448 | a low-friction path to accepting |
| 449 | [https://www.jonobacon.com/2012/07/25/building-strong-community-structural-integrity/|drive-by |
| 450 | contributions]. Fossil's closest equivalents are its unique |
| 451 | [/help?cmd=bundle|bundle] and [/help?cmd=patch|patch] features, which require higher engagement |
| 452 | than firing off a PR.⁷ This difference comes directly from the |
| 453 | initial designed purpose for each tool: the SQLite project doesn't |
| 454 | accept outside contributions from previously-unknown developers, but |
| 455 | the Linux kernel does. |
| 456 | |
| 457 | * <b>No rebasing:</b> When your local repo clone syncs changes |
| 458 | up to its parent, those changes are sent exactly as they were |
| 459 | committed locally. [#history|There is no rebasing mechanism in |
| 460 | Fossil, on purpose.] |
| 461 | |
| 462 | * <b>Sync over push:</b> Explicit pushes are uncommon in |
| 463 | Fossil-based projects: the default is to rely on |
| 464 | [/help?cmd=autosync|autosync mode] instead, in which each commit |
| 465 | syncs immediately to its parent repository. This is a mode so you |
| 466 | can turn it off temporarily when needed, such as when working |
| 467 | offline. Fossil is still a truly distributed version control system; |
| 468 | it's just that its starting default is to assume you're rarely out |
| 469 | of communication with the parent repo. |
| 470 | <br><br> |
| 471 | This is not merely a reflection of modern always-connected computing |
| 472 | environments. It is a conscious decision in direct support of |
| 473 | SQLite's cathedral development model: we don't want developers going |
| 474 | dark, then showing up weeks later with a massive bolus of changes |
| 475 | for us to integrate all at once. |
| 476 | [https://en.wikipedia.org/wiki/Jim_McCarthy_(author)|Jim McCarthy] |
| 477 | put it well in his book on software project management, |
| 478 | <i>[https://www.amazon.com/dp/0735623198/|Dynamics of Software |
| 479 | Development]</i>: "[https://www.youtube.com/watch?v=oY6BCHqEbyc|Beware |
| 480 | of a guy in a room]." |
| 481 | |
| 482 | * <b>Branch names sync:</b> Unlike in Git, branch names in |
| 483 | Fossil are not purely local labels. They sync along with everything |
| 484 | else, so everyone sees the same set of branch names. Fossil's design |
| 485 | choice here is a direct reflection of the Linux vs. SQLite project |
| 486 | outlook: SQLite's developers collaborate closely on a single |
| 487 | coherent project, whereas Linux's developers go off on tangents and |
| 488 | occasionally send selected change sets to each other. |
| 489 | |
| 490 | * <b>Private branches are rare:</b> |
| 491 | [/doc/trunk/www/private.wiki|Private branches exist in Fossil], but |
| 492 | they're normally used to handle rare exception cases, whereas in |
| 493 | many Git projects, they're part of the straight-line development |
| 494 | process. |
| 495 | |
| 496 | * <b>Identical clones:</b> Fossil's autosync system tries to |
| 497 | keep each local clone identical to the repository it cloned |
| 498 | from. |
| 499 | |
| 500 | Where Git encourages siloed development, Fossil fights against it. |
| 501 | Fossil places a lot of emphasis on synchronizing everyone's work and on |
| 502 | reporting on the state of the project and the work of its developers, so |
| 503 | that everyone — especially the project leader — can maintain a better |
| 504 |
+2
-2
| --- www/index.wiki | ||
| +++ www/index.wiki | ||
| @@ -17,11 +17,11 @@ | ||
| 17 | 17 | <li> [./permutedindex.html | Doc Index] |
| 18 | 18 | </ul> |
| 19 | 19 | <center><img src="fossil3.gif" align="center"></center> |
| 20 | 20 | </div> |
| 21 | 21 | |
| 22 | -<p>Fossil is a simple, high-reliability, distributed software configuration | |
| 22 | +Fossil is a simple, high-reliability, distributed software configuration | |
| 23 | 23 | management system with these advanced features: |
| 24 | 24 | |
| 25 | 25 | 1. <b>Project Management</b> - |
| 26 | 26 | In addition to doing [./concepts.wiki | distributed version control] |
| 27 | 27 | like Git and Mercurial, |
| @@ -33,11 +33,11 @@ | ||
| 33 | 33 | 2. <b>Built-in Web Interface</b> - |
| 34 | 34 | Fossil has a built-in, [/skins | themeable], [./serverext.wiki | extensible], |
| 35 | 35 | and intuitive [./webui.wiki | web interface] |
| 36 | 36 | with a rich variety of information pages |
| 37 | 37 | ([./webpage-ex.md|examples]) promoting situational awareness. |
| 38 | - <p> | |
| 38 | + <br><br> | |
| 39 | 39 | This entire website is just a running instance of Fossil. |
| 40 | 40 | The pages you see here are all [./wikitheory.wiki | wiki] or |
| 41 | 41 | [./embeddeddoc.wiki | embedded documentation] or (in the case of |
| 42 | 42 | the [/uv/download.html|download] page) |
| 43 | 43 | [./unvers.wiki | unversioned files]. |
| 44 | 44 |
| --- www/index.wiki | |
| +++ www/index.wiki | |
| @@ -17,11 +17,11 @@ | |
| 17 | <li> [./permutedindex.html | Doc Index] |
| 18 | </ul> |
| 19 | <center><img src="fossil3.gif" align="center"></center> |
| 20 | </div> |
| 21 | |
| 22 | <p>Fossil is a simple, high-reliability, distributed software configuration |
| 23 | management system with these advanced features: |
| 24 | |
| 25 | 1. <b>Project Management</b> - |
| 26 | In addition to doing [./concepts.wiki | distributed version control] |
| 27 | like Git and Mercurial, |
| @@ -33,11 +33,11 @@ | |
| 33 | 2. <b>Built-in Web Interface</b> - |
| 34 | Fossil has a built-in, [/skins | themeable], [./serverext.wiki | extensible], |
| 35 | and intuitive [./webui.wiki | web interface] |
| 36 | with a rich variety of information pages |
| 37 | ([./webpage-ex.md|examples]) promoting situational awareness. |
| 38 | <p> |
| 39 | This entire website is just a running instance of Fossil. |
| 40 | The pages you see here are all [./wikitheory.wiki | wiki] or |
| 41 | [./embeddeddoc.wiki | embedded documentation] or (in the case of |
| 42 | the [/uv/download.html|download] page) |
| 43 | [./unvers.wiki | unversioned files]. |
| 44 |
| --- www/index.wiki | |
| +++ www/index.wiki | |
| @@ -17,11 +17,11 @@ | |
| 17 | <li> [./permutedindex.html | Doc Index] |
| 18 | </ul> |
| 19 | <center><img src="fossil3.gif" align="center"></center> |
| 20 | </div> |
| 21 | |
| 22 | Fossil is a simple, high-reliability, distributed software configuration |
| 23 | management system with these advanced features: |
| 24 | |
| 25 | 1. <b>Project Management</b> - |
| 26 | In addition to doing [./concepts.wiki | distributed version control] |
| 27 | like Git and Mercurial, |
| @@ -33,11 +33,11 @@ | |
| 33 | 2. <b>Built-in Web Interface</b> - |
| 34 | Fossil has a built-in, [/skins | themeable], [./serverext.wiki | extensible], |
| 35 | and intuitive [./webui.wiki | web interface] |
| 36 | with a rich variety of information pages |
| 37 | ([./webpage-ex.md|examples]) promoting situational awareness. |
| 38 | <br><br> |
| 39 | This entire website is just a running instance of Fossil. |
| 40 | The pages you see here are all [./wikitheory.wiki | wiki] or |
| 41 | [./embeddeddoc.wiki | embedded documentation] or (in the case of |
| 42 | the [/uv/download.html|download] page) |
| 43 | [./unvers.wiki | unversioned files]. |
| 44 |
+52
-59
| --- www/mirrortogithub.md | ||
| +++ www/mirrortogithub.md | ||
| @@ -2,83 +2,76 @@ | ||
| 2 | 2 | |
| 3 | 3 | Beginning with Fossil version 2.9, you can mirror a Fossil-based |
| 4 | 4 | project on GitHub (with [limitations](./mirrorlimitations.md)) |
| 5 | 5 | by following these steps: |
| 6 | 6 | |
| 7 | -<ol> | |
| 8 | -<li><p>Create an account on GitHub if you do not have one already. Log | |
| 7 | +1. Create an account on GitHub if you do not have one already. Log | |
| 9 | 8 | into that account. |
| 10 | 9 | |
| 11 | -<li><p>Create a new project. GitHub will ask you if you want to prepopulate | |
| 10 | +2. Create a new project. GitHub will ask you if you want to prepopulate | |
| 12 | 11 | your project with various things like a README file. Answer "no" to |
| 13 | 12 | everything. You want a completely blank project. GitHub will then |
| 14 | 13 | supply you with a URL for your project that will look something |
| 15 | 14 | like this: |
| 16 | 15 | |
| 17 | -<blockquote> | |
| 18 | -https://github.com/username/project.git | |
| 19 | -</blockquote> | |
| 16 | + https://github.com/username/project.git | |
| 20 | 17 | |
| 21 | -<li><p>Back on your workstation, move to a checkout for your Fossil | |
| 18 | +3. Back on your workstation, move to a checkout for your Fossil | |
| 22 | 19 | project and type: |
| 23 | 20 | |
| 24 | -<blockquote> | |
| 25 | -<pre>$ fossil git export /path/to/git/repo --autopush \ | |
| 26 | - https://<font color="orange">username</font>:<font color="red">password</font>@github.com/username/project.git</pre> | |
| 27 | -</blockquote> | |
| 28 | - | |
| 29 | -<p> In place of the <code>/path/to...</code> argument above, put in | |
| 30 | - some directory name that is <i>outside</i> of your Fossil checkout. If | |
| 31 | - you keep multiple Fossil checkouts in a directory of their own, | |
| 32 | - consider using <code>../git-mirror</code> to place the Git export | |
| 33 | - mirror alongside them, for example. Fossil will create this | |
| 34 | - directory if necessary. This directory will become a Git | |
| 35 | - repository that holds a translation of your Fossil repository. | |
| 36 | - | |
| 37 | -<p> The <code>--autopush</code> option tells Fossil that you want to | |
| 38 | - push the Git translation up to GitHub every time it is updated. | |
| 39 | - | |
| 40 | -<p> The URL parameter is the same as the one GitHub gave you, but with | |
| 41 | - your GitHub <font color="orange">username</font> and <font | |
| 42 | - color="red">password</font> added. | |
| 43 | - | |
| 44 | -<p> If your GitHub account uses two-factor authentication (2FA), you | |
| 45 | - will have to <a href="https://github.com/settings/tokens">generate | |
| 46 | - a personal access token</a> and use that in place of your actual | |
| 47 | - password in the URL. This token should have “repo” scope enabled, | |
| 48 | - only. | |
| 49 | - | |
| 50 | -<p> You can also run the command above outside of any open checkout of | |
| 51 | - your project by supplying the “<code>-R repository</code>” | |
| 52 | - option. | |
| 53 | - | |
| 54 | -<li><p>Get some coffee. Depending on the size of your project, the | |
| 55 | - initial "<code>fossil git export</code>" command in the previous | |
| 56 | - step might run for several minutes. | |
| 57 | - | |
| 58 | -<li><p>And you are done! Assuming everything worked, your project is now | |
| 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 | |
| 30 | + you keep multiple Fossil checkouts in a directory of their own, | |
| 31 | + consider using <code>../git-mirror</code> to place the Git export | |
| 32 | + mirror alongside them, for example. Fossil will create this | |
| 33 | + directory if necessary. This directory will become a Git | |
| 34 | + repository that holds a translation of your Fossil repository. | |
| 35 | + | |
| 36 | + The <code>--autopush</code> option tells Fossil that you want to | |
| 37 | + push the Git translation up to GitHub every time it is updated. | |
| 38 | + | |
| 39 | + The URL parameter is the same as the one GitHub gave you, but with | |
| 40 | + your GitHub <font color="orange">username</font> and <font | |
| 41 | + color="red">password</font> added. | |
| 42 | + | |
| 43 | + If your GitHub account uses two-factor authentication (2FA), you | |
| 44 | + will have to <a href="https://github.com/settings/tokens">generate | |
| 45 | + a personal access token</a> and use that in place of your actual | |
| 46 | + password in the URL. This token should have “repo” scope enabled, | |
| 47 | + only. | |
| 48 | + | |
| 49 | + You can also run the command above outside of any open checkout of | |
| 50 | + your project by supplying the “<code>-R repository</code>” | |
| 51 | + option. | |
| 52 | + | |
| 53 | +4. Get some coffee. Depending on the size of your project, the | |
| 54 | + initial "<code>fossil git export</code>" command in the previous | |
| 55 | + step might run for several minutes. | |
| 56 | + | |
| 57 | +5. And you are done! Assuming everything worked, your project is now | |
| 59 | 58 | mirrored on GitHub. |
| 60 | 59 | |
| 61 | -<li><p>Whenever you update your project, simply run this command to update | |
| 60 | +6. Whenever you update your project, simply run this command to update | |
| 62 | 61 | the mirror: |
| 63 | 62 | |
| 64 | -<blockquote> | |
| 65 | -<pre>$ fossil git export</pre> | |
| 66 | -</blockquote> | |
| 67 | - | |
| 68 | - | |
| 69 | -<p> Unlike with the first time you ran that command, you don’t need | |
| 70 | - the remaining arguments, because Fossil remembers those things. | |
| 71 | - Subsequent mirror updates should usually happen in a fraction of | |
| 72 | - a second. | |
| 73 | - | |
| 74 | -<li><p>To see the status of your mirror, run: | |
| 75 | - | |
| 76 | -<blockquote> | |
| 77 | -<pre>$ fossil git status</pre> | |
| 78 | -</blockquote> | |
| 79 | -</ol> | |
| 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 | |
| 80 | 73 | |
| 81 | 74 | ## Notes: |
| 82 | 75 | |
| 83 | 76 | * Unless you specify --force, the mirroring only happens if the Fossil |
| 84 | 77 | repo has changed, with Fossil reporting "no changes", because Fossil |
| 85 | 78 |
| --- www/mirrortogithub.md | |
| +++ www/mirrortogithub.md | |
| @@ -2,83 +2,76 @@ | |
| 2 | |
| 3 | Beginning with Fossil version 2.9, you can mirror a Fossil-based |
| 4 | project on GitHub (with [limitations](./mirrorlimitations.md)) |
| 5 | by following these steps: |
| 6 | |
| 7 | <ol> |
| 8 | <li><p>Create an account on GitHub if you do not have one already. Log |
| 9 | into that account. |
| 10 | |
| 11 | <li><p>Create a new project. GitHub will ask you if you want to prepopulate |
| 12 | your project with various things like a README file. Answer "no" to |
| 13 | everything. You want a completely blank project. GitHub will then |
| 14 | supply you with a URL for your project that will look something |
| 15 | like this: |
| 16 | |
| 17 | <blockquote> |
| 18 | https://github.com/username/project.git |
| 19 | </blockquote> |
| 20 | |
| 21 | <li><p>Back on your workstation, move to a checkout for your Fossil |
| 22 | project and type: |
| 23 | |
| 24 | <blockquote> |
| 25 | <pre>$ fossil git export /path/to/git/repo --autopush \ |
| 26 | https://<font color="orange">username</font>:<font color="red">password</font>@github.com/username/project.git</pre> |
| 27 | </blockquote> |
| 28 | |
| 29 | <p> In place of the <code>/path/to...</code> argument above, put in |
| 30 | some directory name that is <i>outside</i> of your Fossil checkout. If |
| 31 | you keep multiple Fossil checkouts in a directory of their own, |
| 32 | consider using <code>../git-mirror</code> to place the Git export |
| 33 | mirror alongside them, for example. Fossil will create this |
| 34 | directory if necessary. This directory will become a Git |
| 35 | repository that holds a translation of your Fossil repository. |
| 36 | |
| 37 | <p> The <code>--autopush</code> option tells Fossil that you want to |
| 38 | push the Git translation up to GitHub every time it is updated. |
| 39 | |
| 40 | <p> The URL parameter is the same as the one GitHub gave you, but with |
| 41 | your GitHub <font color="orange">username</font> and <font |
| 42 | color="red">password</font> added. |
| 43 | |
| 44 | <p> If your GitHub account uses two-factor authentication (2FA), you |
| 45 | will have to <a href="https://github.com/settings/tokens">generate |
| 46 | a personal access token</a> and use that in place of your actual |
| 47 | password in the URL. This token should have “repo” scope enabled, |
| 48 | only. |
| 49 | |
| 50 | <p> You can also run the command above outside of any open checkout of |
| 51 | your project by supplying the “<code>-R repository</code>” |
| 52 | option. |
| 53 | |
| 54 | <li><p>Get some coffee. Depending on the size of your project, the |
| 55 | initial "<code>fossil git export</code>" command in the previous |
| 56 | step might run for several minutes. |
| 57 | |
| 58 | <li><p>And you are done! Assuming everything worked, your project is now |
| 59 | mirrored on GitHub. |
| 60 | |
| 61 | <li><p>Whenever you update your project, simply run this command to update |
| 62 | the mirror: |
| 63 | |
| 64 | <blockquote> |
| 65 | <pre>$ fossil git export</pre> |
| 66 | </blockquote> |
| 67 | |
| 68 | |
| 69 | <p> Unlike with the first time you ran that command, you don’t need |
| 70 | the remaining arguments, because Fossil remembers those things. |
| 71 | Subsequent mirror updates should usually happen in a fraction of |
| 72 | a second. |
| 73 | |
| 74 | <li><p>To see the status of your mirror, run: |
| 75 | |
| 76 | <blockquote> |
| 77 | <pre>$ fossil git status</pre> |
| 78 | </blockquote> |
| 79 | </ol> |
| 80 | |
| 81 | ## Notes: |
| 82 | |
| 83 | * Unless you specify --force, the mirroring only happens if the Fossil |
| 84 | repo has changed, with Fossil reporting "no changes", because Fossil |
| 85 |
| --- www/mirrortogithub.md | |
| +++ www/mirrortogithub.md | |
| @@ -2,83 +2,76 @@ | |
| 2 | |
| 3 | Beginning with Fossil version 2.9, you can mirror a Fossil-based |
| 4 | project on GitHub (with [limitations](./mirrorlimitations.md)) |
| 5 | by following these steps: |
| 6 | |
| 7 | 1. Create an account on GitHub if you do not have one already. Log |
| 8 | into that account. |
| 9 | |
| 10 | 2. Create a new project. GitHub will ask you if you want to prepopulate |
| 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 |
| 30 | you keep multiple Fossil checkouts in a directory of their own, |
| 31 | consider using <code>../git-mirror</code> to place the Git export |
| 32 | mirror alongside them, for example. Fossil will create this |
| 33 | directory if necessary. This directory will become a Git |
| 34 | repository that holds a translation of your Fossil repository. |
| 35 | |
| 36 | The <code>--autopush</code> option tells Fossil that you want to |
| 37 | push the Git translation up to GitHub every time it is updated. |
| 38 | |
| 39 | The URL parameter is the same as the one GitHub gave you, but with |
| 40 | your GitHub <font color="orange">username</font> and <font |
| 41 | color="red">password</font> added. |
| 42 | |
| 43 | If your GitHub account uses two-factor authentication (2FA), you |
| 44 | will have to <a href="https://github.com/settings/tokens">generate |
| 45 | a personal access token</a> and use that in place of your actual |
| 46 | password in the URL. This token should have “repo” scope enabled, |
| 47 | only. |
| 48 | |
| 49 | You can also run the command above outside of any open checkout of |
| 50 | your project by supplying the “<code>-R repository</code>” |
| 51 | option. |
| 52 | |
| 53 | 4. Get some coffee. Depending on the size of your project, the |
| 54 | initial "<code>fossil git export</code>" command in the previous |
| 55 | step might run for several minutes. |
| 56 | |
| 57 | 5. And you are done! Assuming everything worked, your project is now |
| 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 |
| 78 |
+2
-2
| --- www/newrepo.wiki | ||
| +++ www/newrepo.wiki | ||
| @@ -1,12 +1,12 @@ | ||
| 1 | 1 | <title>How To Create A New Fossil Repository</title> |
| 2 | 2 | |
| 3 | -<p> The [/doc/tip/www/quickstart.wiki|quickstart guide] explains how | |
| 3 | +The [/doc/tip/www/quickstart.wiki|quickstart guide] explains how | |
| 4 | 4 | to get up and running with fossil. But once you're running, what can |
| 5 | 5 | you do with it? This document will walk you through the process of |
| 6 | 6 | creating a fossil repository, populating it with files, and then |
| 7 | -sharing it over the web.</p> | |
| 7 | +sharing it over the web. | |
| 8 | 8 | |
| 9 | 9 | The first thing we need to do is create a fossil repository file: |
| 10 | 10 | |
| 11 | 11 | <verbatim> |
| 12 | 12 | stephan@ludo:~/fossil$ fossil new demo.fossil |
| 13 | 13 |
| --- www/newrepo.wiki | |
| +++ www/newrepo.wiki | |
| @@ -1,12 +1,12 @@ | |
| 1 | <title>How To Create A New Fossil Repository</title> |
| 2 | |
| 3 | <p> The [/doc/tip/www/quickstart.wiki|quickstart guide] explains how |
| 4 | to get up and running with fossil. But once you're running, what can |
| 5 | you do with it? This document will walk you through the process of |
| 6 | creating a fossil repository, populating it with files, and then |
| 7 | sharing it over the web.</p> |
| 8 | |
| 9 | The first thing we need to do is create a fossil repository file: |
| 10 | |
| 11 | <verbatim> |
| 12 | stephan@ludo:~/fossil$ fossil new demo.fossil |
| 13 |
| --- www/newrepo.wiki | |
| +++ www/newrepo.wiki | |
| @@ -1,12 +1,12 @@ | |
| 1 | <title>How To Create A New Fossil Repository</title> |
| 2 | |
| 3 | The [/doc/tip/www/quickstart.wiki|quickstart guide] explains how |
| 4 | to get up and running with fossil. But once you're running, what can |
| 5 | you do with it? This document will walk you through the process of |
| 6 | creating a fossil repository, populating it with files, and then |
| 7 | sharing it over the web. |
| 8 | |
| 9 | The first thing we need to do is create a fossil repository file: |
| 10 | |
| 11 | <verbatim> |
| 12 | stephan@ludo:~/fossil$ fossil new demo.fossil |
| 13 |
+68
-71
| --- www/pop.wiki | ||
| +++ www/pop.wiki | ||
| @@ -1,76 +1,73 @@ | ||
| 1 | 1 | <title>Principles Of Operation</title> |
| 2 | 2 | <h1 align="center">Principles Of Operation</h1> |
| 3 | 3 | |
| 4 | -<p> | |
| 5 | 4 | This page attempts to define the foundational principals upon |
| 6 | 5 | which Fossil is built. |
| 7 | -</p> | |
| 8 | - | |
| 9 | -<ul> | |
| 10 | -<li><p>A project consists of source files, wiki pages, and | |
| 11 | -trouble tickets, and control files (collectively "artifacts"). | |
| 12 | -All historical copies of all artifacts | |
| 13 | -are saved. The project maintains an audit | |
| 14 | -trail.</p></li> | |
| 15 | - | |
| 16 | -<li><p>A project resides in one or more repositories. Each | |
| 17 | -repository is administered and operates independently | |
| 18 | -of the others.</p></li> | |
| 19 | - | |
| 20 | -<li><p>Each repository has both global and local state. The | |
| 21 | -global state is common to all repositories (or at least | |
| 22 | -has the potential to be shared in common when the | |
| 23 | -repositories are fully synchronized). The local state | |
| 24 | -for each repository is private to that repository. | |
| 25 | -The global state represents the content of the project. | |
| 26 | -The local state identifies the authorized users and | |
| 27 | -access policies for a particular repository.</p></li> | |
| 28 | - | |
| 29 | -<li><p>The global state of a repository is an unordered | |
| 30 | -collection of artifacts. Each artifact is named by a | |
| 31 | -cryptographic hash (SHA1 or SHA3-256) encoded in | |
| 32 | -lowercase hexadecimal. | |
| 33 | -In many contexts, the name can be | |
| 34 | -abbreviated to a unique prefix. A five- or six-character | |
| 35 | -prefix usually suffices to uniquely identify a file.</p></li> | |
| 36 | - | |
| 37 | -<li><p>Because artifacts are named by a cryptographic hash, all artifacts | |
| 38 | -are immutable. Any change to the content of an artifact also | |
| 39 | -changes the hash that forms the artifacts name, thus | |
| 40 | -creating a new artifact. Both the old original version of the | |
| 41 | -artifact and the new change are preserved under different names.</p></li> | |
| 42 | - | |
| 43 | -<li><p>It is theoretically possible for two artifacts with different | |
| 44 | -content to share the same hash. But finding two such | |
| 45 | -artifacts is so incredibly difficult and unlikely that we | |
| 46 | -consider it to be an impossibility.</p></li> | |
| 47 | - | |
| 48 | -<li><p>The signature of an artifact is the cryptographic hash of the | |
| 49 | -artifact itself, exactly as it would appear in a disk file. No prefix | |
| 50 | -or meta-information about the artifact is added before computing | |
| 51 | -the hash. So you can | |
| 52 | -always find the signature of a file by using the | |
| 53 | -"sha1sum" or "sha3sum" or similar command-line utilities.</p></li> | |
| 54 | - | |
| 55 | -<li><p>The artifacts that comprise the global state of a repository | |
| 56 | -are the complete global state of that repository. The SQLite | |
| 57 | -database that holds the repository contains additional information | |
| 58 | -about linkages between artifacts, but all of that added information | |
| 59 | -can be discarded and reconstructed by rescanning the content | |
| 60 | -artifacts.</p></li> | |
| 61 | - | |
| 62 | -<li><p>Two repositories for the same project can synchronize | |
| 63 | -their global states simply by sharing artifacts. The local | |
| 64 | -state of repositories is not normally synchronized or | |
| 65 | -shared.</p></li> | |
| 66 | - | |
| 67 | -<li><p>Every check-in has a special file at the top-level | |
| 68 | -named "manifest" which is an index of all other files in | |
| 69 | -that check-in. The manifest is automatically created and | |
| 70 | -maintained by the system.</p></li> | |
| 71 | - | |
| 72 | -<li><p>The <a href="fileformat.wiki">file formats</a> | |
| 73 | -used by Fossil are all very simple so that with access | |
| 74 | -to the original content files, one can easily reconstruct | |
| 75 | -the content of a check-in without the need for any | |
| 76 | -special tools or software.</p></li> | |
| 6 | + | |
| 7 | + * A project consists of source files, wiki pages, and | |
| 8 | + trouble tickets, and control files (collectively "artifacts"). | |
| 9 | + All historical copies of all artifacts | |
| 10 | + are saved. The project maintains an audit | |
| 11 | + trail. | |
| 12 | + | |
| 13 | + * A project resides in one or more repositories. Each | |
| 14 | + repository is administered and operates independently | |
| 15 | + of the others. | |
| 16 | + | |
| 17 | + * Each repository has both global and local state. The | |
| 18 | + global state is common to all repositories (or at least | |
| 19 | + has the potential to be shared in common when the | |
| 20 | + repositories are fully synchronized). The local state | |
| 21 | + for each repository is private to that repository. | |
| 22 | + The global state represents the content of the project. | |
| 23 | + The local state identifies the authorized users and | |
| 24 | + access policies for a particular repository. | |
| 25 | + | |
| 26 | + * The global state of a repository is an unordered | |
| 27 | + collection of artifacts. Each artifact is named by a | |
| 28 | + cryptographic hash (SHA1 or SHA3-256) encoded in | |
| 29 | + lowercase hexadecimal. | |
| 30 | + In many contexts, the name can be | |
| 31 | + abbreviated to a unique prefix. A five- or six-character | |
| 32 | + prefix usually suffices to uniquely identify a file. | |
| 33 | + | |
| 34 | + * Because artifacts are named by a cryptographic hash, all artifacts | |
| 35 | + are immutable. Any change to the content of an artifact also | |
| 36 | + changes the hash that forms the artifacts name, thus | |
| 37 | + creating a new artifact. Both the old original version of the | |
| 38 | + artifact and the new change are preserved under different names. | |
| 39 | + | |
| 40 | + * It is theoretically possible for two artifacts with different | |
| 41 | + content to share the same hash. But finding two such | |
| 42 | + artifacts is so incredibly difficult and unlikely that we | |
| 43 | + consider it to be an impossibility. | |
| 44 | + | |
| 45 | + * The signature of an artifact is the cryptographic hash of the | |
| 46 | + artifact itself, exactly as it would appear in a disk file. No prefix | |
| 47 | + or meta-information about the artifact is added before computing | |
| 48 | + the hash. So you can | |
| 49 | + always find the signature of a file by using the | |
| 50 | + "sha1sum" or "sha3sum" or similar command-line utilities. | |
| 51 | + | |
| 52 | + * The artifacts that comprise the global state of a repository | |
| 53 | + are the complete global state of that repository. The SQLite | |
| 54 | + database that holds the repository contains additional information | |
| 55 | + about linkages between artifacts, but all of that added information | |
| 56 | + can be discarded and reconstructed by rescanning the content | |
| 57 | + artifacts. | |
| 58 | + | |
| 59 | + * Two repositories for the same project can synchronize | |
| 60 | + their global states simply by sharing artifacts. The local | |
| 61 | + state of repositories is not normally synchronized or | |
| 62 | + shared. | |
| 63 | + | |
| 64 | + * Every check-in has a special file at the top-level | |
| 65 | + named "manifest" which is an index of all other files in | |
| 66 | + that check-in. The manifest is automatically created and | |
| 67 | + maintained by the system. | |
| 68 | + | |
| 69 | + * The <a href="fileformat.wiki">file formats</a> | |
| 70 | + used by Fossil are all very simple so that with access | |
| 71 | + to the original content files, one can easily reconstruct | |
| 72 | + the content of a check-in without the need for any | |
| 73 | + special tools or software. | |
| 77 | 74 |
| --- www/pop.wiki | |
| +++ www/pop.wiki | |
| @@ -1,76 +1,73 @@ | |
| 1 | <title>Principles Of Operation</title> |
| 2 | <h1 align="center">Principles Of Operation</h1> |
| 3 | |
| 4 | <p> |
| 5 | This page attempts to define the foundational principals upon |
| 6 | which Fossil is built. |
| 7 | </p> |
| 8 | |
| 9 | <ul> |
| 10 | <li><p>A project consists of source files, wiki pages, and |
| 11 | trouble tickets, and control files (collectively "artifacts"). |
| 12 | All historical copies of all artifacts |
| 13 | are saved. The project maintains an audit |
| 14 | trail.</p></li> |
| 15 | |
| 16 | <li><p>A project resides in one or more repositories. Each |
| 17 | repository is administered and operates independently |
| 18 | of the others.</p></li> |
| 19 | |
| 20 | <li><p>Each repository has both global and local state. The |
| 21 | global state is common to all repositories (or at least |
| 22 | has the potential to be shared in common when the |
| 23 | repositories are fully synchronized). The local state |
| 24 | for each repository is private to that repository. |
| 25 | The global state represents the content of the project. |
| 26 | The local state identifies the authorized users and |
| 27 | access policies for a particular repository.</p></li> |
| 28 | |
| 29 | <li><p>The global state of a repository is an unordered |
| 30 | collection of artifacts. Each artifact is named by a |
| 31 | cryptographic hash (SHA1 or SHA3-256) encoded in |
| 32 | lowercase hexadecimal. |
| 33 | In many contexts, the name can be |
| 34 | abbreviated to a unique prefix. A five- or six-character |
| 35 | prefix usually suffices to uniquely identify a file.</p></li> |
| 36 | |
| 37 | <li><p>Because artifacts are named by a cryptographic hash, all artifacts |
| 38 | are immutable. Any change to the content of an artifact also |
| 39 | changes the hash that forms the artifacts name, thus |
| 40 | creating a new artifact. Both the old original version of the |
| 41 | artifact and the new change are preserved under different names.</p></li> |
| 42 | |
| 43 | <li><p>It is theoretically possible for two artifacts with different |
| 44 | content to share the same hash. But finding two such |
| 45 | artifacts is so incredibly difficult and unlikely that we |
| 46 | consider it to be an impossibility.</p></li> |
| 47 | |
| 48 | <li><p>The signature of an artifact is the cryptographic hash of the |
| 49 | artifact itself, exactly as it would appear in a disk file. No prefix |
| 50 | or meta-information about the artifact is added before computing |
| 51 | the hash. So you can |
| 52 | always find the signature of a file by using the |
| 53 | "sha1sum" or "sha3sum" or similar command-line utilities.</p></li> |
| 54 | |
| 55 | <li><p>The artifacts that comprise the global state of a repository |
| 56 | are the complete global state of that repository. The SQLite |
| 57 | database that holds the repository contains additional information |
| 58 | about linkages between artifacts, but all of that added information |
| 59 | can be discarded and reconstructed by rescanning the content |
| 60 | artifacts.</p></li> |
| 61 | |
| 62 | <li><p>Two repositories for the same project can synchronize |
| 63 | their global states simply by sharing artifacts. The local |
| 64 | state of repositories is not normally synchronized or |
| 65 | shared.</p></li> |
| 66 | |
| 67 | <li><p>Every check-in has a special file at the top-level |
| 68 | named "manifest" which is an index of all other files in |
| 69 | that check-in. The manifest is automatically created and |
| 70 | maintained by the system.</p></li> |
| 71 | |
| 72 | <li><p>The <a href="fileformat.wiki">file formats</a> |
| 73 | used by Fossil are all very simple so that with access |
| 74 | to the original content files, one can easily reconstruct |
| 75 | the content of a check-in without the need for any |
| 76 | special tools or software.</p></li> |
| 77 |
| --- www/pop.wiki | |
| +++ www/pop.wiki | |
| @@ -1,76 +1,73 @@ | |
| 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 | trouble tickets, and control files (collectively "artifacts"). |
| 9 | All historical copies of all artifacts |
| 10 | are saved. The project maintains an audit |
| 11 | trail. |
| 12 | |
| 13 | * A project resides in one or more repositories. Each |
| 14 | repository is administered and operates independently |
| 15 | of the others. |
| 16 | |
| 17 | * Each repository has both global and local state. The |
| 18 | global state is common to all repositories (or at least |
| 19 | has the potential to be shared in common when the |
| 20 | repositories are fully synchronized). The local state |
| 21 | for each repository is private to that repository. |
| 22 | The global state represents the content of the project. |
| 23 | The local state identifies the authorized users and |
| 24 | access policies for a particular repository. |
| 25 | |
| 26 | * The global state of a repository is an unordered |
| 27 | collection of artifacts. Each artifact is named by a |
| 28 | cryptographic hash (SHA1 or SHA3-256) encoded in |
| 29 | lowercase hexadecimal. |
| 30 | In many contexts, the name can be |
| 31 | abbreviated to a unique prefix. A five- or six-character |
| 32 | prefix usually suffices to uniquely identify a file. |
| 33 | |
| 34 | * Because artifacts are named by a cryptographic hash, all artifacts |
| 35 | are immutable. Any change to the content of an artifact also |
| 36 | changes the hash that forms the artifacts name, thus |
| 37 | creating a new artifact. Both the old original version of the |
| 38 | artifact and the new change are preserved under different names. |
| 39 | |
| 40 | * It is theoretically possible for two artifacts with different |
| 41 | content to share the same hash. But finding two such |
| 42 | artifacts is so incredibly difficult and unlikely that we |
| 43 | consider it to be an impossibility. |
| 44 | |
| 45 | * The signature of an artifact is the cryptographic hash of the |
| 46 | artifact itself, exactly as it would appear in a disk file. No prefix |
| 47 | or meta-information about the artifact is added before computing |
| 48 | the hash. So you can |
| 49 | always find the signature of a file by using the |
| 50 | "sha1sum" or "sha3sum" or similar command-line utilities. |
| 51 | |
| 52 | * The artifacts that comprise the global state of a repository |
| 53 | are the complete global state of that repository. The SQLite |
| 54 | database that holds the repository contains additional information |
| 55 | about linkages between artifacts, but all of that added information |
| 56 | can be discarded and reconstructed by rescanning the content |
| 57 | artifacts. |
| 58 | |
| 59 | * Two repositories for the same project can synchronize |
| 60 | their global states simply by sharing artifacts. The local |
| 61 | state of repositories is not normally synchronized or |
| 62 | shared. |
| 63 | |
| 64 | * Every check-in has a special file at the top-level |
| 65 | named "manifest" which is an index of all other files in |
| 66 | that check-in. The manifest is automatically created and |
| 67 | maintained by the system. |
| 68 | |
| 69 | * The <a href="fileformat.wiki">file formats</a> |
| 70 | used by Fossil are all very simple so that with access |
| 71 | to the original content files, one can easily reconstruct |
| 72 | the content of a check-in without the need for any |
| 73 | special tools or software. |
| 74 |
+18
-18
| --- www/qandc.wiki | ||
| +++ www/qandc.wiki | ||
| @@ -1,25 +1,25 @@ | ||
| 1 | 1 | <title>Questions And Criticisms</title> |
| 2 | 2 | <nowiki> |
| 3 | 3 | <h1 align="center">Questions And Criticisms</h1> |
| 4 | 4 | |
| 5 | -<p>This page is a collection of real questions and criticisms that were | |
| 5 | +This page is a collection of real questions and criticisms that were | |
| 6 | 6 | raised against Fossil early in its history (circa 2008). |
| 7 | 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>.</p> | |
| 8 | +</nowiki>[/finfo?name=www/qandc.wiki|change history of this page]<nowiki>. | |
| 9 | 9 | |
| 10 | 10 | <b>Fossil sounds like a lot of reinvention of the wheel. |
| 11 | 11 | Why create your own DVCS when you could have reused mercurial?</b> |
| 12 | 12 | |
| 13 | 13 | <blockquote> |
| 14 | - <p>I wrote fossil because none of the | |
| 14 | + I wrote fossil because none of the | |
| 15 | 15 | other available DVCSes met my needs. If the other DVCSes do |
| 16 | 16 | meet your needs, then you might not need fossil. But they |
| 17 | - don't meet mine, and so fossil is necessary for me.</p> | |
| 17 | + don't meet mine, and so fossil is necessary for me. | |
| 18 | 18 | |
| 19 | - <p>Features provided by fossil that one does not get with other | |
| 20 | - DVCSes include:</p> | |
| 19 | + Features provided by fossil that one does not get with other | |
| 20 | + DVCSes include: | |
| 21 | 21 | |
| 22 | 22 | <ol> |
| 23 | 23 | <li> Integrated <a href="wikitheory.wiki">wiki</a>. </li> |
| 24 | 24 | <li> Integrated <a href="bugtheory.wiki">bug tracking</a> </li> |
| 25 | 25 | <li> Immutable artifacts </li> |
| @@ -67,30 +67,30 @@ | ||
| 67 | 67 | |
| 68 | 68 | <b>Fossil looks like the bug tracker that would be in your |
| 69 | 69 | Linksys Router's administration screen.</b> |
| 70 | 70 | |
| 71 | 71 | <blockquote> |
| 72 | -<p>I take a pragmatic approach to software: form follows function. | |
| 72 | +I take a pragmatic approach to software: form follows function. | |
| 73 | 73 | To me, it is more important to have a reliable, fast, efficient, |
| 74 | -enduring, and simple DVCS than one that looks pretty.</p> | |
| 74 | +enduring, and simple DVCS than one that looks pretty. | |
| 75 | 75 | |
| 76 | -<p>On the other hand, if you have patches that improve the appearance | |
| 76 | +On the other hand, if you have patches that improve the appearance | |
| 77 | 77 | of Fossil without seriously compromising its reliability, performance, |
| 78 | 78 | and/or maintainability, I will be happy to accept them. Fossil is |
| 79 | 79 | self-hosting. Send email to request a password that will let |
| 80 | -you push to the main fossil repository.</p> | |
| 80 | +you push to the main fossil repository. | |
| 81 | 81 | </blockquote> |
| 82 | 82 | |
| 83 | 83 | <b>It would be useful to have a separate application that |
| 84 | 84 | keeps the bug-tracking database in a versioned file. That file can |
| 85 | 85 | then be pushed and pulled along with the rest repository.</b> |
| 86 | 86 | |
| 87 | 87 | <blockquote> |
| 88 | -<p>Fossil already <u>does</u> push and pull bugs along with the files | |
| 88 | +Fossil already <u>does</u> push and pull bugs along with the files | |
| 89 | 89 | in your repository. |
| 90 | 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:</p> | |
| 91 | +That approach to bug tracking was rejected for three reasons: | |
| 92 | 92 | |
| 93 | 93 | <ol> |
| 94 | 94 | <li> Check-ins in fossil are immutable. So if |
| 95 | 95 | tickets were part of the check-in, then there would be no way to add |
| 96 | 96 | new tickets to a check-in as new bugs are discovered. |
| @@ -105,12 +105,12 @@ | ||
| 105 | 105 | of tickets to developers with check-in privileges and an installed |
| 106 | 106 | copy of the fossil executable. Casual passers-by on the internet should |
| 107 | 107 | be permitted to create tickets. |
| 108 | 108 | </ol> |
| 109 | 109 | |
| 110 | -<p>These points are reiterated in the opening paragraphs of | |
| 111 | -the <a href="bugtheory.wiki">Bug-Tracking In Fossil</a> document.</p> | |
| 110 | +These points are reiterated in the opening paragraphs of | |
| 111 | +the <a href="bugtheory.wiki">Bug-Tracking In Fossil</a> document. | |
| 112 | 112 | </blockquote> |
| 113 | 113 | |
| 114 | 114 | <b>Fossil is already the name of a plan9 versioned |
| 115 | 115 | append-only filesystem.</b> |
| 116 | 116 | |
| @@ -136,24 +136,24 @@ | ||
| 136 | 136 | directly in the VCS - either they are under-featured compared to full |
| 137 | 137 | software like Trac, or the VCS is massively bloated compared to |
| 138 | 138 | Subversion or Bazaar.</b> |
| 139 | 139 | |
| 140 | 140 | <blockquote> |
| 141 | -<p>I have no doubt that Trac has many features that fossil lacks. But that | |
| 141 | +I have no doubt that Trac has many features that fossil lacks. But that | |
| 142 | 142 | is not the point. Fossil has several key features that Trac lacks and that |
| 143 | 143 | I need: most notably the fact that |
| 144 | -fossil supports disconnected operation.</p> | |
| 144 | +fossil supports disconnected operation. | |
| 145 | 145 | |
| 146 | -<p>As for bloat: Fossil is a single self-contained executable. | |
| 146 | +As for bloat: Fossil is a single self-contained executable. | |
| 147 | 147 | You do not need any other packages |
| 148 | 148 | (diff, patch, merge, cvs, svn, rcs, git, python, perl, tcl, apache, |
| 149 | 149 | sqlite, and so forth) |
| 150 | 150 | in order to run fossil. Fossil runs just fine in a chroot jail all |
| 151 | 151 | by itself. And the self-contained fossil |
| 152 | 152 | executable is much less than 1MB in size. (Update 2015-01-12: Fossil has |
| 153 | 153 | grown in the years since the previous sentence was written but is still |
| 154 | 154 | much less than 2MB according to "size" when compiled using -Os on x64 Linux.) |
| 155 | -Fossil is the very opposite of bloat.</p> | |
| 155 | +Fossil is the very opposite of bloat. | |
| 156 | 156 | </blockquote> |
| 157 | 157 | |
| 158 | 158 | |
| 159 | 159 | </nowiki> |
| 160 | 160 |
| --- www/qandc.wiki | |
| +++ www/qandc.wiki | |
| @@ -1,25 +1,25 @@ | |
| 1 | <title>Questions And Criticisms</title> |
| 2 | <nowiki> |
| 3 | <h1 align="center">Questions And Criticisms</h1> |
| 4 | |
| 5 | <p>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>.</p> |
| 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 | <p>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.</p> |
| 18 | |
| 19 | <p>Features provided by fossil that one does not get with other |
| 20 | DVCSes include:</p> |
| 21 | |
| 22 | <ol> |
| 23 | <li> Integrated <a href="wikitheory.wiki">wiki</a>. </li> |
| 24 | <li> Integrated <a href="bugtheory.wiki">bug tracking</a> </li> |
| 25 | <li> Immutable artifacts </li> |
| @@ -67,30 +67,30 @@ | |
| 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 | <p>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.</p> |
| 75 | |
| 76 | <p>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.</p> |
| 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 | <p>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:</p> |
| 92 | |
| 93 | <ol> |
| 94 | <li> Check-ins in fossil are immutable. So if |
| 95 | tickets were part of the check-in, then there would be no way to add |
| 96 | new tickets to a check-in as new bugs are discovered. |
| @@ -105,12 +105,12 @@ | |
| 105 | of tickets to developers with check-in privileges and an installed |
| 106 | copy of the fossil executable. Casual passers-by on the internet should |
| 107 | be permitted to create tickets. |
| 108 | </ol> |
| 109 | |
| 110 | <p>These points are reiterated in the opening paragraphs of |
| 111 | the <a href="bugtheory.wiki">Bug-Tracking In Fossil</a> document.</p> |
| 112 | </blockquote> |
| 113 | |
| 114 | <b>Fossil is already the name of a plan9 versioned |
| 115 | append-only filesystem.</b> |
| 116 | |
| @@ -136,24 +136,24 @@ | |
| 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 | <p>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.</p> |
| 145 | |
| 146 | <p>As for bloat: Fossil is a single self-contained executable. |
| 147 | You do not need any other packages |
| 148 | (diff, patch, merge, cvs, svn, rcs, git, python, perl, tcl, apache, |
| 149 | sqlite, and so forth) |
| 150 | in order to run fossil. Fossil runs just fine in a chroot jail all |
| 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.</p> |
| 156 | </blockquote> |
| 157 | |
| 158 | |
| 159 | </nowiki> |
| 160 |
| --- www/qandc.wiki | |
| +++ www/qandc.wiki | |
| @@ -1,25 +1,25 @@ | |
| 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 | |
| 19 | Features provided by fossil that one does not get with other |
| 20 | DVCSes include: |
| 21 | |
| 22 | <ol> |
| 23 | <li> Integrated <a href="wikitheory.wiki">wiki</a>. </li> |
| 24 | <li> Integrated <a href="bugtheory.wiki">bug tracking</a> </li> |
| 25 | <li> Immutable artifacts </li> |
| @@ -67,30 +67,30 @@ | |
| 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 | |
| 93 | <ol> |
| 94 | <li> Check-ins in fossil are immutable. So if |
| 95 | tickets were part of the check-in, then there would be no way to add |
| 96 | new tickets to a check-in as new bugs are discovered. |
| @@ -105,12 +105,12 @@ | |
| 105 | of tickets to developers with check-in privileges and an installed |
| 106 | copy of the fossil executable. Casual passers-by on the internet should |
| 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 | |
| @@ -136,24 +136,24 @@ | |
| 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 | |
| 146 | As for bloat: Fossil is a single self-contained executable. |
| 147 | You do not need any other packages |
| 148 | (diff, patch, merge, cvs, svn, rcs, git, python, perl, tcl, apache, |
| 149 | sqlite, and so forth) |
| 150 | in order to run fossil. Fossil runs just fine in a chroot jail all |
| 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 |
+121
-117
| --- www/quickstart.wiki | ||
| +++ www/quickstart.wiki | ||
| @@ -1,20 +1,21 @@ | ||
| 1 | 1 | <title>Fossil Quick Start Guide</title> |
| 2 | 2 | <h1 align="center">Fossil Quick Start</h1> |
| 3 | 3 | |
| 4 | -<p>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.</p> | |
| 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 | 6 | |
| 7 | 7 | <h2 id="install">Installing</h2> |
| 8 | 8 | |
| 9 | -<p>Fossil is a single self-contained C program. You need to | |
| 9 | +Fossil is a single self-contained C program. You need to | |
| 10 | 10 | either download a |
| 11 | 11 | [https://fossil-scm.org/home/uv/download.html|precompiled |
| 12 | 12 | binary] |
| 13 | 13 | or <a href="build.wiki">compile it yourself</a> from sources. |
| 14 | 14 | Install Fossil by putting the fossil binary |
| 15 | -someplace on your $PATH.</p> | |
| 15 | +someplace on your $PATH. | |
| 16 | + | |
| 16 | 17 | You can test that Fossil is present and working like this: |
| 17 | 18 | |
| 18 | 19 | <blockquote> |
| 19 | 20 | <b> |
| 20 | 21 | fossil version<br> |
| @@ -22,15 +23,15 @@ | ||
| 22 | 23 | </b> |
| 23 | 24 | </blockquote> |
| 24 | 25 | |
| 25 | 26 | <h2 id="workflow" name="fslclone">General Work Flow</h2> |
| 26 | 27 | |
| 27 | -<p>Fossil works with repository files (a database in a single file with the project's | |
| 28 | +Fossil works with repository files (a database in a single file with the project's | |
| 28 | 29 | complete history) and with checked-out local trees (the working directory |
| 29 | 30 | you use to do your work). |
| 30 | 31 | (See [./glossary.md | the glossary] for more background.) |
| 31 | -The workflow looks like this:</p> | |
| 32 | +The workflow looks like this: | |
| 32 | 33 | |
| 33 | 34 | <ul> |
| 34 | 35 | <li>Create or clone a repository file. ([/help/init|fossil init] or |
| 35 | 36 | [/help/clone | fossil clone]) |
| 36 | 37 | <li>Check out a local tree. ([/help/open | fossil open]) |
| @@ -39,17 +40,17 @@ | ||
| 39 | 40 | </ul> |
| 40 | 41 | |
| 41 | 42 | Fossil can be entirely driven from the command line. Many features |
| 42 | 43 | can also be conveniently accessed from the built-in web user interface. |
| 43 | 44 | |
| 44 | -<p>The following sections give a brief overview of these | |
| 45 | -operations.</p> | |
| 45 | +The following sections give a brief overview of these | |
| 46 | +operations. | |
| 46 | 47 | |
| 47 | 48 | <h2 id="new">Starting A New Project</h2> |
| 48 | 49 | |
| 49 | -<p>To start a new project with fossil create a new empty repository | |
| 50 | -this way: ([/help/init | more info]) </p> | |
| 50 | +To start a new project with fossil create a new empty repository | |
| 51 | +this way: ([/help/init | more info]) | |
| 51 | 52 | |
| 52 | 53 | <blockquote> |
| 53 | 54 | <b>fossil init </b><i> repository-filename</i> |
| 54 | 55 | </blockquote> |
| 55 | 56 | |
| @@ -57,23 +58,23 @@ | ||
| 57 | 58 | The <tt>.fossil</tt> extension is traditional but only required if you are going to use the |
| 58 | 59 | <tt>[/help/server | fossil server DIRECTORY]</tt> feature.” |
| 59 | 60 | |
| 60 | 61 | <h2 id="clone">Cloning An Existing Repository</h2> |
| 61 | 62 | |
| 62 | -<p>Most fossil operations interact with a repository that is on the | |
| 63 | +Most fossil operations interact with a repository that is on the | |
| 63 | 64 | local disk drive, not on a remote system. Hence, before accessing |
| 64 | 65 | a remote repository it is necessary to make a local copy of that |
| 65 | 66 | repository. Making a local copy of a remote repository is called |
| 66 | -"cloning".</p> | |
| 67 | +"cloning". | |
| 67 | 68 | |
| 68 | -<p>Clone a remote repository as follows: ([/help/clone | more info])</p> | |
| 69 | +Clone a remote repository as follows: ([/help/clone | more info]) | |
| 69 | 70 | |
| 70 | 71 | <blockquote> |
| 71 | 72 | <b>fossil clone</b> <i>URL repository-filename</i> |
| 72 | 73 | </blockquote> |
| 73 | 74 | |
| 74 | -<p>The <i>URL</i> specifies the fossil repository | |
| 75 | +The <i>URL</i> specifies the fossil repository | |
| 75 | 76 | you want to clone. The <i>repository-filename</i> is the new local |
| 76 | 77 | filename into which the cloned repository will be written. For |
| 77 | 78 | example, to clone the source code of Fossil itself: |
| 78 | 79 | |
| 79 | 80 | <blockquote> |
| @@ -94,25 +95,25 @@ | ||
| 94 | 95 | server-id: 016595e9043054038a9ea9bc526d7f33f7ac0e42<br> |
| 95 | 96 | admin-user: exampleuser (password is "yoWgDR42iv")><br> |
| 96 | 97 | </tt></b> |
| 97 | 98 | </blockquote> |
| 98 | 99 | |
| 99 | -<p>If the remote repository requires a login, include a | |
| 100 | +If the remote repository requires a login, include a | |
| 100 | 101 | userid in the URL like this: |
| 101 | 102 | |
| 102 | 103 | <blockquote> |
| 103 | 104 | <b>fossil clone https://</b><i>remoteuserid</i><b>@www.example.org/ myclone.fossil</b> |
| 104 | 105 | </blockquote> |
| 105 | 106 | |
| 106 | -<p>You will be prompted separately for the password. | |
| 107 | - Use [https://en.wikipedia.org/wiki/Percent-encoding#Percent-encoding_reserved_characters|"%HH"] escapes for special characters in the userid. | |
| 108 | - For example "/" would be replaced by "%2F" meaning that a userid of "Projects/Budget" would become "Projects%2FBudget") </p> | |
| 109 | - | |
| 110 | -<p>If you are behind a restrictive firewall, you might need | |
| 111 | -to <a href="#proxy">specify an HTTP proxy</a>.</p> | |
| 112 | - | |
| 113 | -<p>A Fossil repository is a single disk file. Instead of cloning, | |
| 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 | + | |
| 111 | +If you are behind a restrictive firewall, you might need | |
| 112 | +to <a href="#proxy">specify an HTTP proxy</a>. | |
| 113 | + | |
| 114 | +A Fossil repository is a single disk file. Instead of cloning, | |
| 114 | 115 | you can just make a copy of the repository file (for example, using |
| 115 | 116 | "scp"). Note, however, that the repository file contains auxiliary |
| 116 | 117 | information above and beyond the versioned files, including some |
| 117 | 118 | sensitive information such as password hashes and email addresses. If you |
| 118 | 119 | want to share Fossil repositories directly by copying, consider running the |
| @@ -119,11 +120,11 @@ | ||
| 119 | 120 | [/help/scrub|fossil scrub] command to remove sensitive information |
| 120 | 121 | before transmitting the file. |
| 121 | 122 | |
| 122 | 123 | <h2 id="import">Importing From Another Version Control System</h2> |
| 123 | 124 | |
| 124 | -<p>Rather than start a new project, or clone an existing Fossil project, | |
| 125 | +Rather than start a new project, or clone an existing Fossil project, | |
| 125 | 126 | you might prefer to |
| 126 | 127 | <a href="./inout.wiki">import an existing Git project</a> |
| 127 | 128 | into Fossil using the [/help/import | fossil import] command. |
| 128 | 129 | |
| 129 | 130 | You can even decide to export your project back into git using the |
| @@ -137,14 +138,14 @@ | ||
| 137 | 138 | [https://www.mercurial-scm.org/|Mercurial]. |
| 138 | 139 | Fossil can also import [https://subversion.apache.org/|Subversion projects] directly. |
| 139 | 140 | |
| 140 | 141 | <h2 id="checkout">Checking Out A Local Tree</h2> |
| 141 | 142 | |
| 142 | -<p>To work on a project in fossil, you need to check out a local | |
| 143 | +To work on a project in fossil, you need to check out a local | |
| 143 | 144 | copy of the source tree. Create the directory you want to be |
| 144 | 145 | the root of your tree and cd into that directory. Then |
| 145 | -do this: ([/help/open | more info])</p> | |
| 146 | +do this: ([/help/open | more info]) | |
| 146 | 147 | |
| 147 | 148 | <blockquote> |
| 148 | 149 | <b>fossil open </b><i> repository-filename</i> |
| 149 | 150 | </blockquote> |
| 150 | 151 | |
| @@ -160,15 +161,15 @@ | ||
| 160 | 161 | </tt></b> |
| 161 | 162 | </blockquote> |
| 162 | 163 | |
| 163 | 164 | (or "fossil open ..\myclone.fossil" on Windows). |
| 164 | 165 | |
| 165 | -<p>This leaves you with the newest version of the tree | |
| 166 | +This leaves you with the newest version of the tree | |
| 166 | 167 | checked out. |
| 167 | 168 | From anywhere underneath the root of your local tree, you |
| 168 | 169 | can type commands like the following to find out the status of |
| 169 | -your local tree:</p> | |
| 170 | +your local tree: | |
| 170 | 171 | |
| 171 | 172 | <blockquote> |
| 172 | 173 | <b>[/help/info | fossil info]</b><br> |
| 173 | 174 | <b>[/help/status | fossil status]</b><br> |
| 174 | 175 | <b>[/help/changes | fossil changes]</b><br> |
| @@ -176,60 +177,63 @@ | ||
| 176 | 177 | <b>[/help/timeline | fossil timeline]</b><br> |
| 177 | 178 | <b>[/help/ls | fossil ls]</b><br> |
| 178 | 179 | <b>[/help/branch | fossil branch]</b><br> |
| 179 | 180 | </blockquote> |
| 180 | 181 | |
| 181 | -<p>If you created a new repository using "fossil init" some commands will not | |
| 182 | -produce much output.</p> | |
| 182 | +If you created a new repository using "fossil init" some commands will not | |
| 183 | +produce much output. | |
| 183 | 184 | |
| 184 | -<p>Note that Fossil allows you to make multiple check-outs in | |
| 185 | +Note that Fossil allows you to make multiple check-outs in | |
| 185 | 186 | separate directories from the same repository. This enables you, |
| 186 | 187 | for example, to do builds from multiple branches or versions at |
| 187 | -the same time without having to generate extra clones.</p> | |
| 188 | +the same time without having to generate extra clones. | |
| 188 | 189 | |
| 189 | -<p>To switch a checkout between different versions and branches, | |
| 190 | -use:</p> | |
| 190 | +To switch a checkout between different versions and branches, | |
| 191 | +use:< | |
| 191 | 192 | |
| 192 | 193 | <blockquote> |
| 193 | 194 | <b>[/help/update | fossil update]</b><br> |
| 194 | 195 | <b>[/help/checkout | fossil checkout]</b><br> |
| 195 | 196 | </blockquote> |
| 196 | 197 | |
| 197 | -<p>[/help/update | update] honors the "autosync" option and | |
| 198 | +[/help/update | update] honors the "autosync" option and | |
| 198 | 199 | does a "soft" switch, merging any local changes into the target |
| 199 | 200 | version, whereas [/help/checkout | checkout] does not |
| 200 | 201 | automatically sync and does a "hard" switch, overwriting local |
| 201 | -changes if told to do so.</p> | |
| 202 | +changes if told to do so. | |
| 202 | 203 | |
| 203 | 204 | <h2 id="changes">Making and Committing Changes</h2> |
| 204 | 205 | |
| 205 | -<p>To add new files to your project or remove existing ones, use these | |
| 206 | -commands:</p> | |
| 206 | +To add new files to your project or remove existing ones, use these | |
| 207 | +commands: | |
| 207 | 208 | |
| 208 | 209 | <blockquote> |
| 209 | 210 | <b>[/help/add | fossil add]</b> <i>file...</i><br> |
| 210 | 211 | <b>[/help/rm | fossil rm]</b> <i>file...</i><br> |
| 211 | 212 | <b>[/help/addremove | fossil addremove]</b> <i>file...</i><br> |
| 212 | 213 | </blockquote> |
| 213 | 214 | |
| 214 | -<p>The command:</p> | |
| 215 | +The command: | |
| 216 | + | |
| 215 | 217 | <blockquote> |
| 216 | 218 | <b> |
| 217 | 219 | [/help/changes | fossil changes]</b> |
| 218 | 220 | </blockquote> |
| 219 | -<p>lists files that have changed since the last commit to the repository. For | |
| 220 | -example, if you edit the file "README.md":</p> | |
| 221 | + | |
| 222 | +lists files that have changed since the last commit to the repository. For | |
| 223 | +example, if you edit the file "README.md": | |
| 221 | 224 | |
| 222 | 225 | <blockquote> |
| 223 | 226 | <b> |
| 224 | 227 | fossil changes<br> |
| 225 | 228 | EDITED README.md |
| 226 | 229 | </b> |
| 227 | 230 | </blockquote> |
| 228 | 231 | |
| 229 | -<p>To see exactly what change was made you can use the command</p> | |
| 230 | -[/help/diff | fossil diff]: | |
| 232 | +To see exactly what change was made you can use the command | |
| 233 | +<b>[/help/diff | fossil diff]</b>: | |
| 234 | + | |
| 231 | 235 | <blockquote> |
| 232 | 236 | <b> |
| 233 | 237 | fossil diff <br><tt> |
| 234 | 238 | Index: README.md<br> |
| 235 | 239 | ============================================================<br> |
| @@ -239,17 +243,17 @@ | ||
| 239 | 243 | +Made some changes to the project<br> |
| 240 | 244 | # Original text<br> |
| 241 | 245 | </tt></b> |
| 242 | 246 | </blockquote> |
| 243 | 247 | |
| 244 | -<p>"fossil diff" is the difference between your tree on disk now and as the tree was | |
| 248 | +"fossil diff" is the difference between your tree on disk now and as the tree was | |
| 245 | 249 | when you did "fossil open". An open is the first checkout from a repository |
| 246 | -into a new directory. </p> | |
| 250 | +into a new directory. | |
| 247 | 251 | |
| 248 | -<p>To see the most recent changes made to the repository by other users, use "fossil timeline" to | |
| 252 | +To see the most recent changes made to the repository by other users, use "fossil timeline" to | |
| 249 | 253 | find out the most recent commit, and then "fossil diff" between that commit and the |
| 250 | -current tree: </p> | |
| 254 | +current tree: | |
| 251 | 255 | <blockquote> |
| 252 | 256 | <b> |
| 253 | 257 | fossil timeline <br><tt> |
| 254 | 258 | === 2021-03-28 === <br> |
| 255 | 259 | 03:18:54 [ad75dfa4a0] *CURRENT* Added details to frobnicate command (user: user-one tags: trunk) <br> |
| @@ -269,11 +273,11 @@ | ||
| 269 | 273 | </blockquote> |
| 270 | 274 | |
| 271 | 275 | "current" is an alias for the checkout version, so the command |
| 272 | 276 | "fossil diff --from ad75dfa4a0 --to ab975c6632" gives identical results. |
| 273 | 277 | |
| 274 | -<p>To commit your changes to a local-only repository:</p> | |
| 278 | +To commit your changes to a local-only repository: | |
| 275 | 279 | <blockquote> |
| 276 | 280 | <b> |
| 277 | 281 | fossil commit </b><i>(... Fossil will start your editor, if defined)</i><b><br><tt> |
| 278 | 282 | # Enter a commit message for this check-in. Lines beginning with # are ignored.<br> |
| 279 | 283 | #<br> |
| @@ -284,163 +288,163 @@ | ||
| 284 | 288 | Edited file to add description of code changes<br> |
| 285 | 289 | New_Version: 7b9a416ced4a69a60589dde1aedd1a30fde8eec3528d265dbeed5135530440ab<br> |
| 286 | 290 | </tt></b> |
| 287 | 291 | </blockquote> |
| 288 | 292 | |
| 289 | -<p>You will be prompted for check-in comments using whatever editor | |
| 293 | +You will be prompted for check-in comments using whatever editor | |
| 290 | 294 | is specified by your VISUAL or EDITOR environment variable. If none is |
| 291 | -specified Fossil uses line-editing in the terminal.</p> | |
| 295 | +specified Fossil uses line-editing in the terminal. | |
| 292 | 296 | |
| 293 | -<p>To commit your changes to a repository that was cloned from remote you | |
| 297 | +To commit your changes to a repository that was cloned from remote you | |
| 294 | 298 | perform the same actions but the results are different. Fossil |
| 295 | 299 | defaults to 'autosync' mode, a single-stage commit that sends all changes |
| 296 | 300 | committed to the local repository immediately on to the remote parent repository. This |
| 297 | -only works if you have write permission to the remote respository.</p> | |
| 301 | +only works if you have write permission to the remote respository. | |
| 298 | 302 | |
| 299 | 303 | <h2 id="naming">Naming of Files, Checkins, and Branches</h2> |
| 300 | 304 | |
| 301 | -<p>Fossil deals with information artifacts. This Quickstart document only deals | |
| 305 | +Fossil deals with information artifacts. This Quickstart document only deals | |
| 302 | 306 | with files and collections of files, but be aware there are also tickets, wiki pages and more. |
| 303 | 307 | Every artifact in Fossil has a universally-unique hash id, and may also have a |
| 304 | -human-readable name.</p> | |
| 308 | +human-readable name. | |
| 305 | 309 | |
| 306 | -<p>The following are all equivalent ways of identifying a Fossil file, | |
| 307 | -checkin or branch artifact:</p> | |
| 310 | +The following are all equivalent ways of identifying a Fossil file, | |
| 311 | +checkin or branch artifact: | |
| 308 | 312 | |
| 309 | 313 | <ul> |
| 310 | 314 | <li> the full unique SHA-256 hash, such as be836de35a821523beac2e53168e135d5ebd725d7af421e5f736a28e8034673a |
| 311 | 315 | <li> an abbreviated hash prefix, such as the first ten characters: be836de35a . This won't be universally unique, but it is usually unique within any one repository. As an example, the [https://fossil-scm.org/home/hash-collisions|Fossil project hash collisions] showed at the time of writing that there are no artifacts with identical first 8 characters |
| 312 | 316 | <li> a branch name, such as "special-features" or "juliet-testing". Each branch also has a unique SHA-256 hash |
| 313 | 317 | </ul> |
| 314 | 318 | |
| 315 | -<p>A special convenience branch is "trunk", which is Fossil's default branch name for | |
| 319 | +A special convenience branch is "trunk", which is Fossil's default branch name for | |
| 316 | 320 | the first checkin, and the default for any time a branch name is needed but not |
| 317 | -specified.</p> | |
| 321 | +specified. | |
| 318 | 322 | |
| 319 | 323 | This will get you started on identifying checkins. The |
| 320 | 324 | <a href="./checkin_names.wiki">Checkin Names document</a> is a complete reference, including |
| 321 | 325 | how timestamps can also be used. |
| 322 | 326 | |
| 323 | 327 | <h2 id="config">Configuring Your Local Repository</h2> |
| 324 | 328 | |
| 325 | -<p>When you create a new repository, either by cloning an existing | |
| 329 | +When you create a new repository, either by cloning an existing | |
| 326 | 330 | project or create a new project of your own, you usually want to do some |
| 327 | 331 | local configuration. This is easily accomplished using the web-server |
| 328 | 332 | that is built into fossil. Start the fossil web server like this: |
| 329 | -([/help/ui | more info])</p> | |
| 333 | +([/help/ui | more info]) | |
| 330 | 334 | |
| 331 | 335 | <blockquote> |
| 332 | 336 | <b>fossil ui </b><i> repository-filename</i> |
| 333 | 337 | </blockquote> |
| 334 | 338 | |
| 335 | -<p>You can omit the <i>repository-filename</i> from the command above | |
| 336 | -if you are inside a checked-out local tree.</p> | |
| 339 | +You can omit the <i>repository-filename</i> from the command above | |
| 340 | +if you are inside a checked-out local tree. | |
| 337 | 341 | |
| 338 | -<p>This starts a web server then automatically launches your | |
| 342 | +This starts a web server then automatically launches your | |
| 339 | 343 | web browser and makes it point to this web server. If your system |
| 340 | 344 | has an unusual configuration, fossil might not be able to figure out |
| 341 | 345 | how to start your web browser. In that case, first tell fossil |
| 342 | -where to find your web browser using a command like this:</p> | |
| 346 | +where to find your web browser using a command like this: | |
| 343 | 347 | |
| 344 | 348 | <blockquote> |
| 345 | 349 | <b>fossil setting web-browser </b><i> path-to-web-browser</i> |
| 346 | 350 | </blockquote> |
| 347 | 351 | |
| 348 | -<p>By default, fossil does not require a login for HTTP connections | |
| 352 | +By default, fossil does not require a login for HTTP connections | |
| 349 | 353 | coming in from the IP loopback address 127.0.0.1. You can, and perhaps |
| 350 | -should, change this after you create a few users.</p> | |
| 354 | +should, change this after you create a few users. | |
| 351 | 355 | |
| 352 | -<p>When you are finished configuring, just press Control-C or use | |
| 353 | -the <b>kill</b> command to shut down the mini-server.</p> | |
| 356 | +When you are finished configuring, just press Control-C or use | |
| 357 | +the <b>kill</b> command to shut down the mini-server. | |
| 354 | 358 | |
| 355 | 359 | <h2 id="changes">Making Changes</h2> |
| 356 | 360 | |
| 357 | -<p>To add new files to your project, or remove old files, use these | |
| 358 | -commands:</p> | |
| 361 | +To add new files to your project, or remove old files, use these | |
| 362 | +commands: | |
| 359 | 363 | |
| 360 | 364 | <blockquote> |
| 361 | 365 | <b>[/help/add | fossil add]</b> <i>file...</i><br> |
| 362 | 366 | <b>[/help/rm | fossil rm]</b> <i>file...</i><br> |
| 363 | 367 | <b>[/help/addremove | fossil addremove]</b> <i>file...</i><br> |
| 364 | 368 | </blockquote> |
| 365 | 369 | |
| 366 | -<p>You can also edit files freely. Once you are ready to commit | |
| 367 | -your changes, type:</p> | |
| 370 | +You can also edit files freely. Once you are ready to commit | |
| 371 | +your changes, type: | |
| 368 | 372 | |
| 369 | 373 | <blockquote> |
| 370 | 374 | <b>[/help/commit | fossil commit]</b> |
| 371 | 375 | </blockquote> |
| 372 | 376 | |
| 373 | -<p>You will be prompted for check-in comments using whatever editor | |
| 374 | -is specified by your VISUAL or EDITOR environment variable.</p> | |
| 377 | +You will be prompted for check-in comments using whatever editor | |
| 378 | +is specified by your VISUAL or EDITOR environment variable. | |
| 375 | 379 | |
| 376 | 380 | In the default configuration, the [/help/commit|commit] |
| 377 | 381 | command will also automatically [/help/push|push] your changes, but that |
| 378 | 382 | feature can be disabled. (More information about |
| 379 | 383 | [./concepts.wiki#workflow|autosync] and how to disable it.) |
| 380 | 384 | Remember that your coworkers can not see your changes until you |
| 381 | -commit and push them.</p> | |
| 385 | +commit and push them. | |
| 382 | 386 | |
| 383 | 387 | <h2 id="sharing">Sharing Changes</h2> |
| 384 | 388 | |
| 385 | -<p>When [./concepts.wiki#workflow|autosync] is turned off, | |
| 389 | +When [./concepts.wiki#workflow|autosync] is turned off, | |
| 386 | 390 | the changes you [/help/commit | commit] are only |
| 387 | 391 | on your local repository. |
| 388 | -To share those changes with other repositories, do:</p> | |
| 392 | +To share those changes with other repositories, do: | |
| 389 | 393 | |
| 390 | 394 | <blockquote> |
| 391 | 395 | <b>[/help/push | fossil push]</b> <i>URL</i> |
| 392 | 396 | </blockquote> |
| 393 | 397 | |
| 394 | -<p>Where <i>URL</i> is the http: URL of the server repository you | |
| 398 | +Where <i>URL</i> is the http: URL of the server repository you | |
| 395 | 399 | want to share your changes with. If you omit the <i>URL</i> argument, |
| 396 | -fossil will use whatever server you most recently synced with.</p> | |
| 400 | +fossil will use whatever server you most recently synced with. | |
| 397 | 401 | |
| 398 | -<p>The [/help/push | push] command only sends your changes to others. To | |
| 402 | +The [/help/push | push] command only sends your changes to others. To | |
| 399 | 403 | Receive changes from others, use [/help/pull | pull]. Or go both ways at |
| 400 | -once using [/help/sync | sync]:</p> | |
| 404 | +once using [/help/sync | sync]: | |
| 401 | 405 | |
| 402 | 406 | <blockquote> |
| 403 | 407 | <b>[/help/pull | fossil pull]</b> <i>URL</i><br> |
| 404 | 408 | <b>[/help/sync | fossil sync]</b> <i>URL</i> |
| 405 | 409 | </blockquote> |
| 406 | 410 | |
| 407 | -<p>When you pull in changes from others, they go into your repository, | |
| 411 | +When you pull in changes from others, they go into your repository, | |
| 408 | 412 | not into your checked-out local tree. To get the changes into your |
| 409 | -local tree, use [/help/update | update]:</p> | |
| 413 | +local tree, use [/help/update | update]: | |
| 410 | 414 | |
| 411 | 415 | <blockquote> |
| 412 | 416 | <b>[/help/update | fossil update]</b> <i>VERSION</i> |
| 413 | 417 | </blockquote> |
| 414 | 418 | |
| 415 | -<p>The <i>VERSION</i> can be the name of a branch or tag or any | |
| 419 | +The <i>VERSION</i> can be the name of a branch or tag or any | |
| 416 | 420 | abbreviation to the 40-character |
| 417 | 421 | artifact identifier for a particular check-in, or it can be a |
| 418 | 422 | date/time stamp. ([./checkin_names.wiki | more info]) |
| 419 | 423 | If you omit |
| 420 | 424 | the <i>VERSION</i>, then fossil moves you to the |
| 421 | -latest version of the branch your are currently on.</p> | |
| 425 | +latest version of the branch your are currently on. | |
| 422 | 426 | |
| 423 | -<p>The default behavior is for [./concepts.wiki#workflow|autosync] to | |
| 427 | +The default behavior is for [./concepts.wiki#workflow|autosync] to | |
| 424 | 428 | be turned on. That means that a [/help/pull|pull] automatically occurs |
| 425 | 429 | when you run [/help/update|update] and a [/help/push|push] happens |
| 426 | 430 | automatically after you [/help/commit|commit]. So in normal practice, |
| 427 | 431 | the push, pull, and sync commands are rarely used. But it is important |
| 428 | -to know about them, all the same.</p> | |
| 432 | +to know about them, all the same. | |
| 429 | 433 | |
| 430 | 434 | <blockquote> |
| 431 | 435 | <b>[/help/checkout | fossil checkout]</b> <i>VERSION</i> |
| 432 | 436 | </blockquote> |
| 433 | 437 | |
| 434 | -<p>Is similar to update except that it does not honor the autosync | |
| 438 | +Is similar to update except that it does not honor the autosync | |
| 435 | 439 | setting, nor does it merge in local changes - it prefers to overwrite |
| 436 | 440 | them and fails if local changes exist unless the <tt>--force</tt> |
| 437 | -flag is used.</p> | |
| 441 | +flag is used. | |
| 438 | 442 | |
| 439 | 443 | <h2 id="branch" name="merge">Branching And Merging</h2> |
| 440 | 444 | |
| 441 | -<p>Use the --branch option to the [/help/commit | commit] command | |
| 445 | +Use the --branch option to the [/help/commit | commit] command | |
| 442 | 446 | to start a new branch. Note that in Fossil, branches are normally |
| 443 | 447 | created when you commit, not before you start editing. You can |
| 444 | 448 | use the [/help/branch | branch new] command to create a new branch |
| 445 | 449 | before you start editing, if you want, but most people just wait |
| 446 | 450 | until they are ready to commit. |
| @@ -447,25 +451,25 @@ | ||
| 447 | 451 | |
| 448 | 452 | To merge two branches back together, first |
| 449 | 453 | [/help/update | update] to the branch you want to merge into. |
| 450 | 454 | Then do a [/help/merge|merge] of the other branch that you want to incorporate |
| 451 | 455 | the changes from. For example, to merge "featureX" changes into "trunk" |
| 452 | -do this:</p> | |
| 456 | +do this: | |
| 453 | 457 | |
| 454 | 458 | <blockquote> |
| 455 | 459 | <b>fossil [/help/update|update] trunk</b><br> |
| 456 | 460 | <b>fossil [/help/merge|merge] featureX</b><br> |
| 457 | 461 | <i># make sure the merge didn't break anything...</i><br> |
| 458 | 462 | <b>fossil [/help/commit|commit] |
| 459 | 463 | </blockquote> |
| 460 | 464 | |
| 461 | -<p>The argument to the [/help/merge|merge] command can be any of the | |
| 465 | +The argument to the [/help/merge|merge] command can be any of the | |
| 462 | 466 | version identifier forms that work for [/help/update|update]. |
| 463 | 467 | ([./checkin_names.wiki|more info].) |
| 464 | 468 | The merge command has options to cherry-pick individual |
| 465 | 469 | changes, or to back out individual changes, if you don't want to |
| 466 | -do a full merge.</p> | |
| 470 | +do a full merge. | |
| 467 | 471 | |
| 468 | 472 | The merge command puts all changes in your working check-out. |
| 469 | 473 | No changes are made to the repository. |
| 470 | 474 | You must run [/help/commit|commit] separately |
| 471 | 475 | to add the merge changes into your repository to make them persistent |
| @@ -478,110 +482,110 @@ | ||
| 478 | 482 | multiple merges. So even if you have merged the featureX branch |
| 479 | 483 | into trunk previously, you can do so again and Fossil will automatically |
| 480 | 484 | know to pull in only those changes that have occurred since the previous |
| 481 | 485 | merge. |
| 482 | 486 | |
| 483 | -<p>If a merge or update doesn't work out (perhaps something breaks or | |
| 484 | -there are many merge conflicts) then you back up using:</p> | |
| 487 | +If a merge or update doesn't work out (perhaps something breaks or | |
| 488 | +there are many merge conflicts) then you back up using: | |
| 485 | 489 | |
| 486 | 490 | <blockquote> |
| 487 | 491 | <b>[/help/undo | fossil undo]</b> |
| 488 | 492 | </blockquote> |
| 489 | 493 | |
| 490 | -<p>This will back out the changes that the merge or update made to the | |
| 494 | +This will back out the changes that the merge or update made to the | |
| 491 | 495 | working checkout. There is also a [/help/redo|redo] command if you undo by |
| 492 | 496 | mistake. Undo and redo only work for changes that have |
| 493 | 497 | not yet been checked in using commit and there is only a single |
| 494 | -level of undo/redo.</p> | |
| 498 | +level of undo/redo. | |
| 495 | 499 | |
| 496 | 500 | |
| 497 | 501 | <h2 id="server">Setting Up A Server</h2> |
| 498 | 502 | |
| 499 | -<p>Fossil can act as a stand-alone web server using one of these | |
| 500 | -commands:</p> | |
| 503 | +Fossil can act as a stand-alone web server using one of these | |
| 504 | +commands: | |
| 501 | 505 | |
| 502 | 506 | <blockquote> |
| 503 | 507 | <b>[/help/server | fossil server]</b> <i>repository-filename</i><br> |
| 504 | 508 | <b>[/help/ui | fossil ui]</b> <i>repository-filename</i> |
| 505 | 509 | </blockquote> |
| 506 | 510 | |
| 507 | -<p>The <i>repository-filename</i> can be omitted when these commands | |
| 511 | +The <i>repository-filename</i> can be omitted when these commands | |
| 508 | 512 | are run from within an open check-out, which is a particularly useful |
| 509 | 513 | shortcut with the <b>fossil ui</b> command. |
| 510 | 514 | |
| 511 | -<p>The <b>ui</b> command is intended for accessing the web user interface | |
| 515 | +The <b>ui</b> command is intended for accessing the web user interface | |
| 512 | 516 | from a local desktop. (We sometimes call this mode "Fossil UI.") |
| 513 | 517 | The <b>ui</b> command differs from the |
| 514 | 518 | <b>server</b> command by binding to the loopback IP |
| 515 | 519 | address only (thus making the web UI visible only on the |
| 516 | 520 | local machine) and by automatically starting your default web browser, |
| 517 | 521 | pointing it at the running UI |
| 518 | 522 | server. The localhost restriction exists because it also gives anyone |
| 519 | 523 | who can access the resulting web UI full control over the |
| 520 | 524 | repository. (This is the [./caps/admin-v-setup.md#apsu | all-powerful |
| 521 | -Setup capabliity].)</p> | |
| 525 | +Setup capabliity].) | |
| 522 | 526 | |
| 523 | -<p>For cross-machine collaboration, use the <b>server</b> command instead, | |
| 527 | +For cross-machine collaboration, use the <b>server</b> command instead, | |
| 524 | 528 | which binds on all IP addresses, does not try to start a web browser, |
| 525 | -and enforces [./caps/ | Fossil's role-based access control system].</p> | |
| 529 | +and enforces [./caps/ | Fossil's role-based access control system]. | |
| 526 | 530 | |
| 527 | -<p>Servers are also easily configured as: | |
| 531 | +Servers are also easily configured as: | |
| 528 | 532 | |
| 529 | 533 | <ul> |
| 530 | 534 | <li>[./server/any/inetd.md|inetd] |
| 531 | 535 | <li>[./server/debian/service.md|systemd] |
| 532 | 536 | <li>[./server/any/cgi.md|CGI] |
| 533 | 537 | <li>[./server/any/scgi.md|SCGI] |
| 534 | 538 | </ul> |
| 535 | 539 | |
| 536 | -<p>…along with [./server/#matrix | several other options].</p> | |
| 540 | +…along with [./server/#matrix | several other options]. | |
| 537 | 541 | |
| 538 | -<p>The [./selfhost.wiki | self-hosting fossil repositories] use | |
| 542 | +The [./selfhost.wiki | self-hosting fossil repositories] use | |
| 539 | 543 | CGI. |
| 540 | 544 | |
| 541 | -<p>You might <i>need</i> to set up a server, whether you know it yet or | |
| 545 | +You might <i>need</i> to set up a server, whether you know it yet or | |
| 542 | 546 | not. See the [./server/whyuseaserver.wiki | Benefits of a Fossil Server] |
| 543 | -article for details.</p> | |
| 547 | +article for details. | |
| 544 | 548 | |
| 545 | 549 | <h2 id="proxy">HTTP Proxies</h2> |
| 546 | 550 | |
| 547 | -<p>If you are behind a restrictive firewall that requires you to use | |
| 551 | +If you are behind a restrictive firewall that requires you to use | |
| 548 | 552 | an HTTP proxy to reach the internet, then you can configure the proxy |
| 549 | 553 | in three different ways. You can tell fossil about your proxy using |
| 550 | 554 | a command-line option on commands that use the network, |
| 551 | -<b>sync</b>, <b>clone</b>, <b>push</b>, and <b>pull</b>.</p> | |
| 555 | +<b>sync</b>, <b>clone</b>, <b>push</b>, and <b>pull</b>. | |
| 552 | 556 | |
| 553 | 557 | <blockquote> |
| 554 | 558 | <b>fossil clone </b><i>URL</i> <b>--proxy</b> <i>Proxy-URL</i> |
| 555 | 559 | </blockquote> |
| 556 | 560 | |
| 557 | -<p>It is annoying to have to type in the proxy URL every time you | |
| 561 | +It is annoying to have to type in the proxy URL every time you | |
| 558 | 562 | sync your project, though, so you can make the proxy configuration |
| 559 | -persistent using the [/help/setting | setting] command:</p> | |
| 563 | +persistent using the [/help/setting | setting] command: | |
| 560 | 564 | |
| 561 | 565 | <blockquote> |
| 562 | 566 | <b>fossil setting proxy </b><i>Proxy-URL</i> |
| 563 | 567 | </blockquote> |
| 564 | 568 | |
| 565 | -<p>Or, you can set the "<b>http_proxy</b>" environment variable:</p> | |
| 569 | +Or, you can set the "<b>http_proxy</b>" environment variable: | |
| 566 | 570 | |
| 567 | 571 | <blockquote> |
| 568 | 572 | <b>export http_proxy=</b><i>Proxy-URL</i> |
| 569 | 573 | </blockquote> |
| 570 | 574 | |
| 571 | -<p>To stop using the proxy, do:</p> | |
| 575 | +To stop using the proxy, do: | |
| 572 | 576 | |
| 573 | 577 | <blockquote> |
| 574 | 578 | <b>fossil setting proxy off</b> |
| 575 | 579 | </blockquote> |
| 576 | 580 | |
| 577 | -<p>Or unset the environment variable. The fossil setting for the | |
| 581 | +Or unset the environment variable. The fossil setting for the | |
| 578 | 582 | HTTP proxy takes precedence over the environment variable and the |
| 579 | 583 | command-line option overrides both. If you have a persistent |
| 580 | 584 | proxy setting that you want to override for a one-time sync, that |
| 581 | 585 | is easily done on the command-line. For example, to sync with |
| 582 | -a co-worker's repository on your LAN, you might type:</p> | |
| 586 | +a co-worker's repository on your LAN, you might type: | |
| 583 | 587 | |
| 584 | 588 | <blockquote> |
| 585 | 589 | <b>fossil sync http://192.168.1.36:8080/ --proxy off</b> |
| 586 | 590 | </blockquote> |
| 587 | 591 | |
| 588 | 592 |
| --- www/quickstart.wiki | |
| +++ www/quickstart.wiki | |
| @@ -1,20 +1,21 @@ | |
| 1 | <title>Fossil Quick Start Guide</title> |
| 2 | <h1 align="center">Fossil Quick Start</h1> |
| 3 | |
| 4 | <p>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.</p> |
| 6 | |
| 7 | <h2 id="install">Installing</h2> |
| 8 | |
| 9 | <p>Fossil is a single self-contained C program. You need to |
| 10 | either download a |
| 11 | [https://fossil-scm.org/home/uv/download.html|precompiled |
| 12 | binary] |
| 13 | or <a href="build.wiki">compile it yourself</a> from sources. |
| 14 | Install Fossil by putting the fossil binary |
| 15 | someplace on your $PATH.</p> |
| 16 | You can test that Fossil is present and working like this: |
| 17 | |
| 18 | <blockquote> |
| 19 | <b> |
| 20 | fossil version<br> |
| @@ -22,15 +23,15 @@ | |
| 22 | </b> |
| 23 | </blockquote> |
| 24 | |
| 25 | <h2 id="workflow" name="fslclone">General Work Flow</h2> |
| 26 | |
| 27 | <p>Fossil works with repository files (a database in a single file with the project's |
| 28 | complete history) and with checked-out local trees (the working directory |
| 29 | you use to do your work). |
| 30 | (See [./glossary.md | the glossary] for more background.) |
| 31 | The workflow looks like this:</p> |
| 32 | |
| 33 | <ul> |
| 34 | <li>Create or clone a repository file. ([/help/init|fossil init] or |
| 35 | [/help/clone | fossil clone]) |
| 36 | <li>Check out a local tree. ([/help/open | fossil open]) |
| @@ -39,17 +40,17 @@ | |
| 39 | </ul> |
| 40 | |
| 41 | Fossil can be entirely driven from the command line. Many features |
| 42 | can also be conveniently accessed from the built-in web user interface. |
| 43 | |
| 44 | <p>The following sections give a brief overview of these |
| 45 | operations.</p> |
| 46 | |
| 47 | <h2 id="new">Starting A New Project</h2> |
| 48 | |
| 49 | <p>To start a new project with fossil create a new empty repository |
| 50 | this way: ([/help/init | more info]) </p> |
| 51 | |
| 52 | <blockquote> |
| 53 | <b>fossil init </b><i> repository-filename</i> |
| 54 | </blockquote> |
| 55 | |
| @@ -57,23 +58,23 @@ | |
| 57 | The <tt>.fossil</tt> extension is traditional but only required if you are going to use the |
| 58 | <tt>[/help/server | fossil server DIRECTORY]</tt> feature.” |
| 59 | |
| 60 | <h2 id="clone">Cloning An Existing Repository</h2> |
| 61 | |
| 62 | <p>Most fossil operations interact with a repository that is on the |
| 63 | local disk drive, not on a remote system. Hence, before accessing |
| 64 | a remote repository it is necessary to make a local copy of that |
| 65 | repository. Making a local copy of a remote repository is called |
| 66 | "cloning".</p> |
| 67 | |
| 68 | <p>Clone a remote repository as follows: ([/help/clone | more info])</p> |
| 69 | |
| 70 | <blockquote> |
| 71 | <b>fossil clone</b> <i>URL repository-filename</i> |
| 72 | </blockquote> |
| 73 | |
| 74 | <p>The <i>URL</i> specifies the fossil repository |
| 75 | you want to clone. The <i>repository-filename</i> is the new local |
| 76 | filename into which the cloned repository will be written. For |
| 77 | example, to clone the source code of Fossil itself: |
| 78 | |
| 79 | <blockquote> |
| @@ -94,25 +95,25 @@ | |
| 94 | server-id: 016595e9043054038a9ea9bc526d7f33f7ac0e42<br> |
| 95 | admin-user: exampleuser (password is "yoWgDR42iv")><br> |
| 96 | </tt></b> |
| 97 | </blockquote> |
| 98 | |
| 99 | <p>If the remote repository requires a login, include a |
| 100 | userid in the URL like this: |
| 101 | |
| 102 | <blockquote> |
| 103 | <b>fossil clone https://</b><i>remoteuserid</i><b>@www.example.org/ myclone.fossil</b> |
| 104 | </blockquote> |
| 105 | |
| 106 | <p>You will be prompted separately for the password. |
| 107 | Use [https://en.wikipedia.org/wiki/Percent-encoding#Percent-encoding_reserved_characters|"%HH"] escapes for special characters in the userid. |
| 108 | For example "/" would be replaced by "%2F" meaning that a userid of "Projects/Budget" would become "Projects%2FBudget") </p> |
| 109 | |
| 110 | <p>If you are behind a restrictive firewall, you might need |
| 111 | to <a href="#proxy">specify an HTTP proxy</a>.</p> |
| 112 | |
| 113 | <p>A Fossil repository is a single disk file. Instead of cloning, |
| 114 | you can just make a copy of the repository file (for example, using |
| 115 | "scp"). Note, however, that the repository file contains auxiliary |
| 116 | information above and beyond the versioned files, including some |
| 117 | sensitive information such as password hashes and email addresses. If you |
| 118 | want to share Fossil repositories directly by copying, consider running the |
| @@ -119,11 +120,11 @@ | |
| 119 | [/help/scrub|fossil scrub] command to remove sensitive information |
| 120 | before transmitting the file. |
| 121 | |
| 122 | <h2 id="import">Importing From Another Version Control System</h2> |
| 123 | |
| 124 | <p>Rather than start a new project, or clone an existing Fossil project, |
| 125 | you might prefer to |
| 126 | <a href="./inout.wiki">import an existing Git project</a> |
| 127 | into Fossil using the [/help/import | fossil import] command. |
| 128 | |
| 129 | You can even decide to export your project back into git using the |
| @@ -137,14 +138,14 @@ | |
| 137 | [https://www.mercurial-scm.org/|Mercurial]. |
| 138 | Fossil can also import [https://subversion.apache.org/|Subversion projects] directly. |
| 139 | |
| 140 | <h2 id="checkout">Checking Out A Local Tree</h2> |
| 141 | |
| 142 | <p>To work on a project in fossil, you need to check out a local |
| 143 | copy of the source tree. Create the directory you want to be |
| 144 | the root of your tree and cd into that directory. Then |
| 145 | do this: ([/help/open | more info])</p> |
| 146 | |
| 147 | <blockquote> |
| 148 | <b>fossil open </b><i> repository-filename</i> |
| 149 | </blockquote> |
| 150 | |
| @@ -160,15 +161,15 @@ | |
| 160 | </tt></b> |
| 161 | </blockquote> |
| 162 | |
| 163 | (or "fossil open ..\myclone.fossil" on Windows). |
| 164 | |
| 165 | <p>This leaves you with the newest version of the tree |
| 166 | checked out. |
| 167 | From anywhere underneath the root of your local tree, you |
| 168 | can type commands like the following to find out the status of |
| 169 | your local tree:</p> |
| 170 | |
| 171 | <blockquote> |
| 172 | <b>[/help/info | fossil info]</b><br> |
| 173 | <b>[/help/status | fossil status]</b><br> |
| 174 | <b>[/help/changes | fossil changes]</b><br> |
| @@ -176,60 +177,63 @@ | |
| 176 | <b>[/help/timeline | fossil timeline]</b><br> |
| 177 | <b>[/help/ls | fossil ls]</b><br> |
| 178 | <b>[/help/branch | fossil branch]</b><br> |
| 179 | </blockquote> |
| 180 | |
| 181 | <p>If you created a new repository using "fossil init" some commands will not |
| 182 | produce much output.</p> |
| 183 | |
| 184 | <p>Note that Fossil allows you to make multiple check-outs in |
| 185 | separate directories from the same repository. This enables you, |
| 186 | for example, to do builds from multiple branches or versions at |
| 187 | the same time without having to generate extra clones.</p> |
| 188 | |
| 189 | <p>To switch a checkout between different versions and branches, |
| 190 | use:</p> |
| 191 | |
| 192 | <blockquote> |
| 193 | <b>[/help/update | fossil update]</b><br> |
| 194 | <b>[/help/checkout | fossil checkout]</b><br> |
| 195 | </blockquote> |
| 196 | |
| 197 | <p>[/help/update | update] honors the "autosync" option and |
| 198 | does a "soft" switch, merging any local changes into the target |
| 199 | version, whereas [/help/checkout | checkout] does not |
| 200 | automatically sync and does a "hard" switch, overwriting local |
| 201 | changes if told to do so.</p> |
| 202 | |
| 203 | <h2 id="changes">Making and Committing Changes</h2> |
| 204 | |
| 205 | <p>To add new files to your project or remove existing ones, use these |
| 206 | commands:</p> |
| 207 | |
| 208 | <blockquote> |
| 209 | <b>[/help/add | fossil add]</b> <i>file...</i><br> |
| 210 | <b>[/help/rm | fossil rm]</b> <i>file...</i><br> |
| 211 | <b>[/help/addremove | fossil addremove]</b> <i>file...</i><br> |
| 212 | </blockquote> |
| 213 | |
| 214 | <p>The command:</p> |
| 215 | <blockquote> |
| 216 | <b> |
| 217 | [/help/changes | fossil changes]</b> |
| 218 | </blockquote> |
| 219 | <p>lists files that have changed since the last commit to the repository. For |
| 220 | example, if you edit the file "README.md":</p> |
| 221 | |
| 222 | <blockquote> |
| 223 | <b> |
| 224 | fossil changes<br> |
| 225 | EDITED README.md |
| 226 | </b> |
| 227 | </blockquote> |
| 228 | |
| 229 | <p>To see exactly what change was made you can use the command</p> |
| 230 | [/help/diff | fossil diff]: |
| 231 | <blockquote> |
| 232 | <b> |
| 233 | fossil diff <br><tt> |
| 234 | Index: README.md<br> |
| 235 | ============================================================<br> |
| @@ -239,17 +243,17 @@ | |
| 239 | +Made some changes to the project<br> |
| 240 | # Original text<br> |
| 241 | </tt></b> |
| 242 | </blockquote> |
| 243 | |
| 244 | <p>"fossil diff" is the difference between your tree on disk now and as the tree was |
| 245 | when you did "fossil open". An open is the first checkout from a repository |
| 246 | into a new directory. </p> |
| 247 | |
| 248 | <p>To see the most recent changes made to the repository by other users, use "fossil timeline" to |
| 249 | find out the most recent commit, and then "fossil diff" between that commit and the |
| 250 | current tree: </p> |
| 251 | <blockquote> |
| 252 | <b> |
| 253 | fossil timeline <br><tt> |
| 254 | === 2021-03-28 === <br> |
| 255 | 03:18:54 [ad75dfa4a0] *CURRENT* Added details to frobnicate command (user: user-one tags: trunk) <br> |
| @@ -269,11 +273,11 @@ | |
| 269 | </blockquote> |
| 270 | |
| 271 | "current" is an alias for the checkout version, so the command |
| 272 | "fossil diff --from ad75dfa4a0 --to ab975c6632" gives identical results. |
| 273 | |
| 274 | <p>To commit your changes to a local-only repository:</p> |
| 275 | <blockquote> |
| 276 | <b> |
| 277 | fossil commit </b><i>(... Fossil will start your editor, if defined)</i><b><br><tt> |
| 278 | # Enter a commit message for this check-in. Lines beginning with # are ignored.<br> |
| 279 | #<br> |
| @@ -284,163 +288,163 @@ | |
| 284 | Edited file to add description of code changes<br> |
| 285 | New_Version: 7b9a416ced4a69a60589dde1aedd1a30fde8eec3528d265dbeed5135530440ab<br> |
| 286 | </tt></b> |
| 287 | </blockquote> |
| 288 | |
| 289 | <p>You will be prompted for check-in comments using whatever editor |
| 290 | is specified by your VISUAL or EDITOR environment variable. If none is |
| 291 | specified Fossil uses line-editing in the terminal.</p> |
| 292 | |
| 293 | <p>To commit your changes to a repository that was cloned from remote you |
| 294 | perform the same actions but the results are different. Fossil |
| 295 | defaults to 'autosync' mode, a single-stage commit that sends all changes |
| 296 | committed to the local repository immediately on to the remote parent repository. This |
| 297 | only works if you have write permission to the remote respository.</p> |
| 298 | |
| 299 | <h2 id="naming">Naming of Files, Checkins, and Branches</h2> |
| 300 | |
| 301 | <p>Fossil deals with information artifacts. This Quickstart document only deals |
| 302 | with files and collections of files, but be aware there are also tickets, wiki pages and more. |
| 303 | Every artifact in Fossil has a universally-unique hash id, and may also have a |
| 304 | human-readable name.</p> |
| 305 | |
| 306 | <p>The following are all equivalent ways of identifying a Fossil file, |
| 307 | checkin or branch artifact:</p> |
| 308 | |
| 309 | <ul> |
| 310 | <li> the full unique SHA-256 hash, such as be836de35a821523beac2e53168e135d5ebd725d7af421e5f736a28e8034673a |
| 311 | <li> an abbreviated hash prefix, such as the first ten characters: be836de35a . This won't be universally unique, but it is usually unique within any one repository. As an example, the [https://fossil-scm.org/home/hash-collisions|Fossil project hash collisions] showed at the time of writing that there are no artifacts with identical first 8 characters |
| 312 | <li> a branch name, such as "special-features" or "juliet-testing". Each branch also has a unique SHA-256 hash |
| 313 | </ul> |
| 314 | |
| 315 | <p>A special convenience branch is "trunk", which is Fossil's default branch name for |
| 316 | the first checkin, and the default for any time a branch name is needed but not |
| 317 | specified.</p> |
| 318 | |
| 319 | This will get you started on identifying checkins. The |
| 320 | <a href="./checkin_names.wiki">Checkin Names document</a> is a complete reference, including |
| 321 | how timestamps can also be used. |
| 322 | |
| 323 | <h2 id="config">Configuring Your Local Repository</h2> |
| 324 | |
| 325 | <p>When you create a new repository, either by cloning an existing |
| 326 | project or create a new project of your own, you usually want to do some |
| 327 | local configuration. This is easily accomplished using the web-server |
| 328 | that is built into fossil. Start the fossil web server like this: |
| 329 | ([/help/ui | more info])</p> |
| 330 | |
| 331 | <blockquote> |
| 332 | <b>fossil ui </b><i> repository-filename</i> |
| 333 | </blockquote> |
| 334 | |
| 335 | <p>You can omit the <i>repository-filename</i> from the command above |
| 336 | if you are inside a checked-out local tree.</p> |
| 337 | |
| 338 | <p>This starts a web server then automatically launches your |
| 339 | web browser and makes it point to this web server. If your system |
| 340 | has an unusual configuration, fossil might not be able to figure out |
| 341 | how to start your web browser. In that case, first tell fossil |
| 342 | where to find your web browser using a command like this:</p> |
| 343 | |
| 344 | <blockquote> |
| 345 | <b>fossil setting web-browser </b><i> path-to-web-browser</i> |
| 346 | </blockquote> |
| 347 | |
| 348 | <p>By default, fossil does not require a login for HTTP connections |
| 349 | coming in from the IP loopback address 127.0.0.1. You can, and perhaps |
| 350 | should, change this after you create a few users.</p> |
| 351 | |
| 352 | <p>When you are finished configuring, just press Control-C or use |
| 353 | the <b>kill</b> command to shut down the mini-server.</p> |
| 354 | |
| 355 | <h2 id="changes">Making Changes</h2> |
| 356 | |
| 357 | <p>To add new files to your project, or remove old files, use these |
| 358 | commands:</p> |
| 359 | |
| 360 | <blockquote> |
| 361 | <b>[/help/add | fossil add]</b> <i>file...</i><br> |
| 362 | <b>[/help/rm | fossil rm]</b> <i>file...</i><br> |
| 363 | <b>[/help/addremove | fossil addremove]</b> <i>file...</i><br> |
| 364 | </blockquote> |
| 365 | |
| 366 | <p>You can also edit files freely. Once you are ready to commit |
| 367 | your changes, type:</p> |
| 368 | |
| 369 | <blockquote> |
| 370 | <b>[/help/commit | fossil commit]</b> |
| 371 | </blockquote> |
| 372 | |
| 373 | <p>You will be prompted for check-in comments using whatever editor |
| 374 | is specified by your VISUAL or EDITOR environment variable.</p> |
| 375 | |
| 376 | In the default configuration, the [/help/commit|commit] |
| 377 | command will also automatically [/help/push|push] your changes, but that |
| 378 | feature can be disabled. (More information about |
| 379 | [./concepts.wiki#workflow|autosync] and how to disable it.) |
| 380 | Remember that your coworkers can not see your changes until you |
| 381 | commit and push them.</p> |
| 382 | |
| 383 | <h2 id="sharing">Sharing Changes</h2> |
| 384 | |
| 385 | <p>When [./concepts.wiki#workflow|autosync] is turned off, |
| 386 | the changes you [/help/commit | commit] are only |
| 387 | on your local repository. |
| 388 | To share those changes with other repositories, do:</p> |
| 389 | |
| 390 | <blockquote> |
| 391 | <b>[/help/push | fossil push]</b> <i>URL</i> |
| 392 | </blockquote> |
| 393 | |
| 394 | <p>Where <i>URL</i> is the http: URL of the server repository you |
| 395 | want to share your changes with. If you omit the <i>URL</i> argument, |
| 396 | fossil will use whatever server you most recently synced with.</p> |
| 397 | |
| 398 | <p>The [/help/push | push] command only sends your changes to others. To |
| 399 | Receive changes from others, use [/help/pull | pull]. Or go both ways at |
| 400 | once using [/help/sync | sync]:</p> |
| 401 | |
| 402 | <blockquote> |
| 403 | <b>[/help/pull | fossil pull]</b> <i>URL</i><br> |
| 404 | <b>[/help/sync | fossil sync]</b> <i>URL</i> |
| 405 | </blockquote> |
| 406 | |
| 407 | <p>When you pull in changes from others, they go into your repository, |
| 408 | not into your checked-out local tree. To get the changes into your |
| 409 | local tree, use [/help/update | update]:</p> |
| 410 | |
| 411 | <blockquote> |
| 412 | <b>[/help/update | fossil update]</b> <i>VERSION</i> |
| 413 | </blockquote> |
| 414 | |
| 415 | <p>The <i>VERSION</i> can be the name of a branch or tag or any |
| 416 | abbreviation to the 40-character |
| 417 | artifact identifier for a particular check-in, or it can be a |
| 418 | date/time stamp. ([./checkin_names.wiki | more info]) |
| 419 | If you omit |
| 420 | the <i>VERSION</i>, then fossil moves you to the |
| 421 | latest version of the branch your are currently on.</p> |
| 422 | |
| 423 | <p>The default behavior is for [./concepts.wiki#workflow|autosync] to |
| 424 | be turned on. That means that a [/help/pull|pull] automatically occurs |
| 425 | when you run [/help/update|update] and a [/help/push|push] happens |
| 426 | automatically after you [/help/commit|commit]. So in normal practice, |
| 427 | the push, pull, and sync commands are rarely used. But it is important |
| 428 | to know about them, all the same.</p> |
| 429 | |
| 430 | <blockquote> |
| 431 | <b>[/help/checkout | fossil checkout]</b> <i>VERSION</i> |
| 432 | </blockquote> |
| 433 | |
| 434 | <p>Is similar to update except that it does not honor the autosync |
| 435 | setting, nor does it merge in local changes - it prefers to overwrite |
| 436 | them and fails if local changes exist unless the <tt>--force</tt> |
| 437 | flag is used.</p> |
| 438 | |
| 439 | <h2 id="branch" name="merge">Branching And Merging</h2> |
| 440 | |
| 441 | <p>Use the --branch option to the [/help/commit | commit] command |
| 442 | to start a new branch. Note that in Fossil, branches are normally |
| 443 | created when you commit, not before you start editing. You can |
| 444 | use the [/help/branch | branch new] command to create a new branch |
| 445 | before you start editing, if you want, but most people just wait |
| 446 | until they are ready to commit. |
| @@ -447,25 +451,25 @@ | |
| 447 | |
| 448 | To merge two branches back together, first |
| 449 | [/help/update | update] to the branch you want to merge into. |
| 450 | Then do a [/help/merge|merge] of the other branch that you want to incorporate |
| 451 | the changes from. For example, to merge "featureX" changes into "trunk" |
| 452 | do this:</p> |
| 453 | |
| 454 | <blockquote> |
| 455 | <b>fossil [/help/update|update] trunk</b><br> |
| 456 | <b>fossil [/help/merge|merge] featureX</b><br> |
| 457 | <i># make sure the merge didn't break anything...</i><br> |
| 458 | <b>fossil [/help/commit|commit] |
| 459 | </blockquote> |
| 460 | |
| 461 | <p>The argument to the [/help/merge|merge] command can be any of the |
| 462 | version identifier forms that work for [/help/update|update]. |
| 463 | ([./checkin_names.wiki|more info].) |
| 464 | The merge command has options to cherry-pick individual |
| 465 | changes, or to back out individual changes, if you don't want to |
| 466 | do a full merge.</p> |
| 467 | |
| 468 | The merge command puts all changes in your working check-out. |
| 469 | No changes are made to the repository. |
| 470 | You must run [/help/commit|commit] separately |
| 471 | to add the merge changes into your repository to make them persistent |
| @@ -478,110 +482,110 @@ | |
| 478 | multiple merges. So even if you have merged the featureX branch |
| 479 | into trunk previously, you can do so again and Fossil will automatically |
| 480 | know to pull in only those changes that have occurred since the previous |
| 481 | merge. |
| 482 | |
| 483 | <p>If a merge or update doesn't work out (perhaps something breaks or |
| 484 | there are many merge conflicts) then you back up using:</p> |
| 485 | |
| 486 | <blockquote> |
| 487 | <b>[/help/undo | fossil undo]</b> |
| 488 | </blockquote> |
| 489 | |
| 490 | <p>This will back out the changes that the merge or update made to the |
| 491 | working checkout. There is also a [/help/redo|redo] command if you undo by |
| 492 | mistake. Undo and redo only work for changes that have |
| 493 | not yet been checked in using commit and there is only a single |
| 494 | level of undo/redo.</p> |
| 495 | |
| 496 | |
| 497 | <h2 id="server">Setting Up A Server</h2> |
| 498 | |
| 499 | <p>Fossil can act as a stand-alone web server using one of these |
| 500 | commands:</p> |
| 501 | |
| 502 | <blockquote> |
| 503 | <b>[/help/server | fossil server]</b> <i>repository-filename</i><br> |
| 504 | <b>[/help/ui | fossil ui]</b> <i>repository-filename</i> |
| 505 | </blockquote> |
| 506 | |
| 507 | <p>The <i>repository-filename</i> can be omitted when these commands |
| 508 | are run from within an open check-out, which is a particularly useful |
| 509 | shortcut with the <b>fossil ui</b> command. |
| 510 | |
| 511 | <p>The <b>ui</b> command is intended for accessing the web user interface |
| 512 | from a local desktop. (We sometimes call this mode "Fossil UI.") |
| 513 | The <b>ui</b> command differs from the |
| 514 | <b>server</b> command by binding to the loopback IP |
| 515 | address only (thus making the web UI visible only on the |
| 516 | local machine) and by automatically starting your default web browser, |
| 517 | pointing it at the running UI |
| 518 | server. The localhost restriction exists because it also gives anyone |
| 519 | who can access the resulting web UI full control over the |
| 520 | repository. (This is the [./caps/admin-v-setup.md#apsu | all-powerful |
| 521 | Setup capabliity].)</p> |
| 522 | |
| 523 | <p>For cross-machine collaboration, use the <b>server</b> command instead, |
| 524 | which binds on all IP addresses, does not try to start a web browser, |
| 525 | and enforces [./caps/ | Fossil's role-based access control system].</p> |
| 526 | |
| 527 | <p>Servers are also easily configured as: |
| 528 | |
| 529 | <ul> |
| 530 | <li>[./server/any/inetd.md|inetd] |
| 531 | <li>[./server/debian/service.md|systemd] |
| 532 | <li>[./server/any/cgi.md|CGI] |
| 533 | <li>[./server/any/scgi.md|SCGI] |
| 534 | </ul> |
| 535 | |
| 536 | <p>…along with [./server/#matrix | several other options].</p> |
| 537 | |
| 538 | <p>The [./selfhost.wiki | self-hosting fossil repositories] use |
| 539 | CGI. |
| 540 | |
| 541 | <p>You might <i>need</i> to set up a server, whether you know it yet or |
| 542 | not. See the [./server/whyuseaserver.wiki | Benefits of a Fossil Server] |
| 543 | article for details.</p> |
| 544 | |
| 545 | <h2 id="proxy">HTTP Proxies</h2> |
| 546 | |
| 547 | <p>If you are behind a restrictive firewall that requires you to use |
| 548 | an HTTP proxy to reach the internet, then you can configure the proxy |
| 549 | in three different ways. You can tell fossil about your proxy using |
| 550 | a command-line option on commands that use the network, |
| 551 | <b>sync</b>, <b>clone</b>, <b>push</b>, and <b>pull</b>.</p> |
| 552 | |
| 553 | <blockquote> |
| 554 | <b>fossil clone </b><i>URL</i> <b>--proxy</b> <i>Proxy-URL</i> |
| 555 | </blockquote> |
| 556 | |
| 557 | <p>It is annoying to have to type in the proxy URL every time you |
| 558 | sync your project, though, so you can make the proxy configuration |
| 559 | persistent using the [/help/setting | setting] command:</p> |
| 560 | |
| 561 | <blockquote> |
| 562 | <b>fossil setting proxy </b><i>Proxy-URL</i> |
| 563 | </blockquote> |
| 564 | |
| 565 | <p>Or, you can set the "<b>http_proxy</b>" environment variable:</p> |
| 566 | |
| 567 | <blockquote> |
| 568 | <b>export http_proxy=</b><i>Proxy-URL</i> |
| 569 | </blockquote> |
| 570 | |
| 571 | <p>To stop using the proxy, do:</p> |
| 572 | |
| 573 | <blockquote> |
| 574 | <b>fossil setting proxy off</b> |
| 575 | </blockquote> |
| 576 | |
| 577 | <p>Or unset the environment variable. The fossil setting for the |
| 578 | HTTP proxy takes precedence over the environment variable and the |
| 579 | command-line option overrides both. If you have a persistent |
| 580 | proxy setting that you want to override for a one-time sync, that |
| 581 | is easily done on the command-line. For example, to sync with |
| 582 | a co-worker's repository on your LAN, you might type:</p> |
| 583 | |
| 584 | <blockquote> |
| 585 | <b>fossil sync http://192.168.1.36:8080/ --proxy off</b> |
| 586 | </blockquote> |
| 587 | |
| 588 |
| --- www/quickstart.wiki | |
| +++ www/quickstart.wiki | |
| @@ -1,20 +1,21 @@ | |
| 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> |
| 8 | |
| 9 | Fossil is a single self-contained C program. You need to |
| 10 | either download a |
| 11 | [https://fossil-scm.org/home/uv/download.html|precompiled |
| 12 | binary] |
| 13 | or <a href="build.wiki">compile it yourself</a> from sources. |
| 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,15 +23,15 @@ | |
| 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 |
| 30 | you use to do your work). |
| 31 | (See [./glossary.md | the glossary] for more background.) |
| 32 | The workflow looks like this: |
| 33 | |
| 34 | <ul> |
| 35 | <li>Create or clone a repository file. ([/help/init|fossil init] or |
| 36 | [/help/clone | fossil clone]) |
| 37 | <li>Check out a local tree. ([/help/open | fossil open]) |
| @@ -39,17 +40,17 @@ | |
| 40 | </ul> |
| 41 | |
| 42 | Fossil can be entirely driven from the command line. Many features |
| 43 | can also be conveniently accessed from the built-in web user interface. |
| 44 | |
| 45 | The following sections give a brief overview of these |
| 46 | operations. |
| 47 | |
| 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,23 +58,23 @@ | |
| 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 | |
| 61 | <h2 id="clone">Cloning An Existing Repository</h2> |
| 62 | |
| 63 | Most fossil operations interact with a repository that is on the |
| 64 | local disk drive, not on a remote system. Hence, before accessing |
| 65 | a remote repository it is necessary to make a local copy of that |
| 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> |
| @@ -94,25 +95,25 @@ | |
| 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 | |
| 111 | If you are behind a restrictive firewall, you might need |
| 112 | to <a href="#proxy">specify an HTTP proxy</a>. |
| 113 | |
| 114 | A Fossil repository is a single disk file. Instead of cloning, |
| 115 | you can just make a copy of the repository file (for example, using |
| 116 | "scp"). Note, however, that the repository file contains auxiliary |
| 117 | information above and beyond the versioned files, including some |
| 118 | sensitive information such as password hashes and email addresses. If you |
| 119 | want to share Fossil repositories directly by copying, consider running the |
| @@ -119,11 +120,11 @@ | |
| 120 | [/help/scrub|fossil scrub] command to remove sensitive information |
| 121 | before transmitting the file. |
| 122 | |
| 123 | <h2 id="import">Importing From Another Version Control System</h2> |
| 124 | |
| 125 | Rather than start a new project, or clone an existing Fossil project, |
| 126 | you might prefer to |
| 127 | <a href="./inout.wiki">import an existing Git project</a> |
| 128 | into Fossil using the [/help/import | fossil import] command. |
| 129 | |
| 130 | You can even decide to export your project back into git using the |
| @@ -137,14 +138,14 @@ | |
| 138 | [https://www.mercurial-scm.org/|Mercurial]. |
| 139 | Fossil can also import [https://subversion.apache.org/|Subversion projects] directly. |
| 140 | |
| 141 | <h2 id="checkout">Checking Out A Local Tree</h2> |
| 142 | |
| 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 | |
| @@ -160,15 +161,15 @@ | |
| 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,60 +177,63 @@ | |
| 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 |
| 186 | separate directories from the same repository. This enables you, |
| 187 | for example, to do builds from multiple branches or versions at |
| 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 |
| 202 | changes if told to do so. |
| 203 | |
| 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> |
| @@ -239,17 +243,17 @@ | |
| 243 | +Made some changes to the project<br> |
| 244 | # Original text<br> |
| 245 | </tt></b> |
| 246 | </blockquote> |
| 247 | |
| 248 | "fossil diff" is the difference between your tree on disk now and as the tree was |
| 249 | when you did "fossil open". An open is the first checkout from a repository |
| 250 | into a new directory. |
| 251 | |
| 252 | To see the most recent changes made to the repository by other users, use "fossil timeline" to |
| 253 | find out the most recent commit, and then "fossil diff" between that commit and the |
| 254 | current tree: |
| 255 | <blockquote> |
| 256 | <b> |
| 257 | fossil timeline <br><tt> |
| 258 | === 2021-03-28 === <br> |
| 259 | 03:18:54 [ad75dfa4a0] *CURRENT* Added details to frobnicate command (user: user-one tags: trunk) <br> |
| @@ -269,11 +273,11 @@ | |
| 273 | </blockquote> |
| 274 | |
| 275 | "current" is an alias for the checkout version, so the command |
| 276 | "fossil diff --from ad75dfa4a0 --to ab975c6632" gives identical results. |
| 277 | |
| 278 | To commit your changes to a local-only repository: |
| 279 | <blockquote> |
| 280 | <b> |
| 281 | fossil commit </b><i>(... Fossil will start your editor, if defined)</i><b><br><tt> |
| 282 | # Enter a commit message for this check-in. Lines beginning with # are ignored.<br> |
| 283 | #<br> |
| @@ -284,163 +288,163 @@ | |
| 288 | Edited file to add description of code changes<br> |
| 289 | New_Version: 7b9a416ced4a69a60589dde1aedd1a30fde8eec3528d265dbeed5135530440ab<br> |
| 290 | </tt></b> |
| 291 | </blockquote> |
| 292 | |
| 293 | You will be prompted for check-in comments using whatever editor |
| 294 | is specified by your VISUAL or EDITOR environment variable. If none is |
| 295 | specified Fossil uses line-editing in the terminal. |
| 296 | |
| 297 | To commit your changes to a repository that was cloned from remote you |
| 298 | perform the same actions but the results are different. Fossil |
| 299 | defaults to 'autosync' mode, a single-stage commit that sends all changes |
| 300 | committed to the local repository immediately on to the remote parent repository. This |
| 301 | only works if you have write permission to the remote respository. |
| 302 | |
| 303 | <h2 id="naming">Naming of Files, Checkins, and Branches</h2> |
| 304 | |
| 305 | Fossil deals with information artifacts. This Quickstart document only deals |
| 306 | with files and collections of files, but be aware there are also tickets, wiki pages and more. |
| 307 | Every artifact in Fossil has a universally-unique hash id, and may also have a |
| 308 | human-readable name. |
| 309 | |
| 310 | The following are all equivalent ways of identifying a Fossil file, |
| 311 | checkin or branch artifact: |
| 312 | |
| 313 | <ul> |
| 314 | <li> the full unique SHA-256 hash, such as be836de35a821523beac2e53168e135d5ebd725d7af421e5f736a28e8034673a |
| 315 | <li> an abbreviated hash prefix, such as the first ten characters: be836de35a . This won't be universally unique, but it is usually unique within any one repository. As an example, the [https://fossil-scm.org/home/hash-collisions|Fossil project hash collisions] showed at the time of writing that there are no artifacts with identical first 8 characters |
| 316 | <li> a branch name, such as "special-features" or "juliet-testing". Each branch also has a unique SHA-256 hash |
| 317 | </ul> |
| 318 | |
| 319 | A special convenience branch is "trunk", which is Fossil's default branch name for |
| 320 | the first checkin, and the default for any time a branch name is needed but not |
| 321 | specified. |
| 322 | |
| 323 | This will get you started on identifying checkins. The |
| 324 | <a href="./checkin_names.wiki">Checkin Names document</a> is a complete reference, including |
| 325 | how timestamps can also be used. |
| 326 | |
| 327 | <h2 id="config">Configuring Your Local Repository</h2> |
| 328 | |
| 329 | When you create a new repository, either by cloning an existing |
| 330 | project or create a new project of your own, you usually want to do some |
| 331 | local configuration. This is easily accomplished using the web-server |
| 332 | that is built into fossil. Start the fossil web server like this: |
| 333 | ([/help/ui | more info]) |
| 334 | |
| 335 | <blockquote> |
| 336 | <b>fossil ui </b><i> repository-filename</i> |
| 337 | </blockquote> |
| 338 | |
| 339 | You can omit the <i>repository-filename</i> from the command above |
| 340 | if you are inside a checked-out local tree. |
| 341 | |
| 342 | This starts a web server then automatically launches your |
| 343 | web browser and makes it point to this web server. If your system |
| 344 | has an unusual configuration, fossil might not be able to figure out |
| 345 | how to start your web browser. In that case, first tell fossil |
| 346 | where to find your web browser using a command like this: |
| 347 | |
| 348 | <blockquote> |
| 349 | <b>fossil setting web-browser </b><i> path-to-web-browser</i> |
| 350 | </blockquote> |
| 351 | |
| 352 | By default, fossil does not require a login for HTTP connections |
| 353 | coming in from the IP loopback address 127.0.0.1. You can, and perhaps |
| 354 | should, change this after you create a few users. |
| 355 | |
| 356 | When you are finished configuring, just press Control-C or use |
| 357 | the <b>kill</b> command to shut down the mini-server. |
| 358 | |
| 359 | <h2 id="changes">Making Changes</h2> |
| 360 | |
| 361 | To add new files to your project, or remove old files, use these |
| 362 | commands: |
| 363 | |
| 364 | <blockquote> |
| 365 | <b>[/help/add | fossil add]</b> <i>file...</i><br> |
| 366 | <b>[/help/rm | fossil rm]</b> <i>file...</i><br> |
| 367 | <b>[/help/addremove | fossil addremove]</b> <i>file...</i><br> |
| 368 | </blockquote> |
| 369 | |
| 370 | You can also edit files freely. Once you are ready to commit |
| 371 | your changes, type: |
| 372 | |
| 373 | <blockquote> |
| 374 | <b>[/help/commit | fossil commit]</b> |
| 375 | </blockquote> |
| 376 | |
| 377 | You will be prompted for check-in comments using whatever editor |
| 378 | is specified by your VISUAL or EDITOR environment variable. |
| 379 | |
| 380 | In the default configuration, the [/help/commit|commit] |
| 381 | command will also automatically [/help/push|push] your changes, but that |
| 382 | feature can be disabled. (More information about |
| 383 | [./concepts.wiki#workflow|autosync] and how to disable it.) |
| 384 | Remember that your coworkers can not see your changes until you |
| 385 | commit and push them. |
| 386 | |
| 387 | <h2 id="sharing">Sharing Changes</h2> |
| 388 | |
| 389 | When [./concepts.wiki#workflow|autosync] is turned off, |
| 390 | the changes you [/help/commit | commit] are only |
| 391 | on your local repository. |
| 392 | To share those changes with other repositories, do: |
| 393 | |
| 394 | <blockquote> |
| 395 | <b>[/help/push | fossil push]</b> <i>URL</i> |
| 396 | </blockquote> |
| 397 | |
| 398 | Where <i>URL</i> is the http: URL of the server repository you |
| 399 | want to share your changes with. If you omit the <i>URL</i> argument, |
| 400 | fossil will use whatever server you most recently synced with. |
| 401 | |
| 402 | The [/help/push | push] command only sends your changes to others. To |
| 403 | Receive changes from others, use [/help/pull | pull]. Or go both ways at |
| 404 | once using [/help/sync | sync]: |
| 405 | |
| 406 | <blockquote> |
| 407 | <b>[/help/pull | fossil pull]</b> <i>URL</i><br> |
| 408 | <b>[/help/sync | fossil sync]</b> <i>URL</i> |
| 409 | </blockquote> |
| 410 | |
| 411 | When you pull in changes from others, they go into your repository, |
| 412 | not into your checked-out local tree. To get the changes into your |
| 413 | local tree, use [/help/update | update]: |
| 414 | |
| 415 | <blockquote> |
| 416 | <b>[/help/update | fossil update]</b> <i>VERSION</i> |
| 417 | </blockquote> |
| 418 | |
| 419 | The <i>VERSION</i> can be the name of a branch or tag or any |
| 420 | abbreviation to the 40-character |
| 421 | artifact identifier for a particular check-in, or it can be a |
| 422 | date/time stamp. ([./checkin_names.wiki | more info]) |
| 423 | If you omit |
| 424 | the <i>VERSION</i>, then fossil moves you to the |
| 425 | latest version of the branch your are currently on. |
| 426 | |
| 427 | The default behavior is for [./concepts.wiki#workflow|autosync] to |
| 428 | be turned on. That means that a [/help/pull|pull] automatically occurs |
| 429 | when you run [/help/update|update] and a [/help/push|push] happens |
| 430 | automatically after you [/help/commit|commit]. So in normal practice, |
| 431 | the push, pull, and sync commands are rarely used. But it is important |
| 432 | to know about them, all the same. |
| 433 | |
| 434 | <blockquote> |
| 435 | <b>[/help/checkout | fossil checkout]</b> <i>VERSION</i> |
| 436 | </blockquote> |
| 437 | |
| 438 | Is similar to update except that it does not honor the autosync |
| 439 | setting, nor does it merge in local changes - it prefers to overwrite |
| 440 | them and fails if local changes exist unless the <tt>--force</tt> |
| 441 | flag is used. |
| 442 | |
| 443 | <h2 id="branch" name="merge">Branching And Merging</h2> |
| 444 | |
| 445 | Use the --branch option to the [/help/commit | commit] command |
| 446 | to start a new branch. Note that in Fossil, branches are normally |
| 447 | created when you commit, not before you start editing. You can |
| 448 | use the [/help/branch | branch new] command to create a new branch |
| 449 | before you start editing, if you want, but most people just wait |
| 450 | until they are ready to commit. |
| @@ -447,25 +451,25 @@ | |
| 451 | |
| 452 | To merge two branches back together, first |
| 453 | [/help/update | update] to the branch you want to merge into. |
| 454 | Then do a [/help/merge|merge] of the other branch that you want to incorporate |
| 455 | the changes from. For example, to merge "featureX" changes into "trunk" |
| 456 | do this: |
| 457 | |
| 458 | <blockquote> |
| 459 | <b>fossil [/help/update|update] trunk</b><br> |
| 460 | <b>fossil [/help/merge|merge] featureX</b><br> |
| 461 | <i># make sure the merge didn't break anything...</i><br> |
| 462 | <b>fossil [/help/commit|commit] |
| 463 | </blockquote> |
| 464 | |
| 465 | The argument to the [/help/merge|merge] command can be any of the |
| 466 | version identifier forms that work for [/help/update|update]. |
| 467 | ([./checkin_names.wiki|more info].) |
| 468 | The merge command has options to cherry-pick individual |
| 469 | changes, or to back out individual changes, if you don't want to |
| 470 | do a full merge. |
| 471 | |
| 472 | The merge command puts all changes in your working check-out. |
| 473 | No changes are made to the repository. |
| 474 | You must run [/help/commit|commit] separately |
| 475 | to add the merge changes into your repository to make them persistent |
| @@ -478,110 +482,110 @@ | |
| 482 | multiple merges. So even if you have merged the featureX branch |
| 483 | into trunk previously, you can do so again and Fossil will automatically |
| 484 | know to pull in only those changes that have occurred since the previous |
| 485 | merge. |
| 486 | |
| 487 | If a merge or update doesn't work out (perhaps something breaks or |
| 488 | there are many merge conflicts) then you back up using: |
| 489 | |
| 490 | <blockquote> |
| 491 | <b>[/help/undo | fossil undo]</b> |
| 492 | </blockquote> |
| 493 | |
| 494 | This will back out the changes that the merge or update made to the |
| 495 | working checkout. There is also a [/help/redo|redo] command if you undo by |
| 496 | mistake. Undo and redo only work for changes that have |
| 497 | not yet been checked in using commit and there is only a single |
| 498 | level of undo/redo. |
| 499 | |
| 500 | |
| 501 | <h2 id="server">Setting Up A Server</h2> |
| 502 | |
| 503 | Fossil can act as a stand-alone web server using one of these |
| 504 | commands: |
| 505 | |
| 506 | <blockquote> |
| 507 | <b>[/help/server | fossil server]</b> <i>repository-filename</i><br> |
| 508 | <b>[/help/ui | fossil ui]</b> <i>repository-filename</i> |
| 509 | </blockquote> |
| 510 | |
| 511 | The <i>repository-filename</i> can be omitted when these commands |
| 512 | are run from within an open check-out, which is a particularly useful |
| 513 | shortcut with the <b>fossil ui</b> command. |
| 514 | |
| 515 | The <b>ui</b> command is intended for accessing the web user interface |
| 516 | from a local desktop. (We sometimes call this mode "Fossil UI.") |
| 517 | The <b>ui</b> command differs from the |
| 518 | <b>server</b> command by binding to the loopback IP |
| 519 | address only (thus making the web UI visible only on the |
| 520 | local machine) and by automatically starting your default web browser, |
| 521 | pointing it at the running UI |
| 522 | server. The localhost restriction exists because it also gives anyone |
| 523 | who can access the resulting web UI full control over the |
| 524 | repository. (This is the [./caps/admin-v-setup.md#apsu | all-powerful |
| 525 | Setup capabliity].) |
| 526 | |
| 527 | For cross-machine collaboration, use the <b>server</b> command instead, |
| 528 | which binds on all IP addresses, does not try to start a web browser, |
| 529 | and enforces [./caps/ | Fossil's role-based access control system]. |
| 530 | |
| 531 | Servers are also easily configured as: |
| 532 | |
| 533 | <ul> |
| 534 | <li>[./server/any/inetd.md|inetd] |
| 535 | <li>[./server/debian/service.md|systemd] |
| 536 | <li>[./server/any/cgi.md|CGI] |
| 537 | <li>[./server/any/scgi.md|SCGI] |
| 538 | </ul> |
| 539 | |
| 540 | …along with [./server/#matrix | several other options]. |
| 541 | |
| 542 | The [./selfhost.wiki | self-hosting fossil repositories] use |
| 543 | CGI. |
| 544 | |
| 545 | You might <i>need</i> to set up a server, whether you know it yet or |
| 546 | not. See the [./server/whyuseaserver.wiki | Benefits of a Fossil Server] |
| 547 | article for details. |
| 548 | |
| 549 | <h2 id="proxy">HTTP Proxies</h2> |
| 550 | |
| 551 | If you are behind a restrictive firewall that requires you to use |
| 552 | an HTTP proxy to reach the internet, then you can configure the proxy |
| 553 | in three different ways. You can tell fossil about your proxy using |
| 554 | a command-line option on commands that use the network, |
| 555 | <b>sync</b>, <b>clone</b>, <b>push</b>, and <b>pull</b>. |
| 556 | |
| 557 | <blockquote> |
| 558 | <b>fossil clone </b><i>URL</i> <b>--proxy</b> <i>Proxy-URL</i> |
| 559 | </blockquote> |
| 560 | |
| 561 | It is annoying to have to type in the proxy URL every time you |
| 562 | sync your project, though, so you can make the proxy configuration |
| 563 | persistent using the [/help/setting | setting] command: |
| 564 | |
| 565 | <blockquote> |
| 566 | <b>fossil setting proxy </b><i>Proxy-URL</i> |
| 567 | </blockquote> |
| 568 | |
| 569 | Or, you can set the "<b>http_proxy</b>" environment variable: |
| 570 | |
| 571 | <blockquote> |
| 572 | <b>export http_proxy=</b><i>Proxy-URL</i> |
| 573 | </blockquote> |
| 574 | |
| 575 | To stop using the proxy, do: |
| 576 | |
| 577 | <blockquote> |
| 578 | <b>fossil setting proxy off</b> |
| 579 | </blockquote> |
| 580 | |
| 581 | Or unset the environment variable. The fossil setting for the |
| 582 | HTTP proxy takes precedence over the environment variable and the |
| 583 | command-line option overrides both. If you have a persistent |
| 584 | proxy setting that you want to override for a one-time sync, that |
| 585 | is easily done on the command-line. For example, to sync with |
| 586 | a co-worker's repository on your LAN, you might type: |
| 587 | |
| 588 | <blockquote> |
| 589 | <b>fossil sync http://192.168.1.36:8080/ --proxy off</b> |
| 590 | </blockquote> |
| 591 | |
| 592 |
+2
-2
| --- www/quotes.wiki | ||
| +++ www/quotes.wiki | ||
| @@ -145,12 +145,12 @@ | ||
| 145 | 145 | </blockquote> |
| 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 | - | |
| 151 | -<p>In git (or rather, the git community), the development history is part of | |
| 150 | +<br><br> | |
| 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 | 156 | <blockquote> |
| 157 | 157 |
| --- www/quotes.wiki | |
| +++ www/quotes.wiki | |
| @@ -145,12 +145,12 @@ | |
| 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 | |
| 151 | <p>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 |
| --- www/quotes.wiki | |
| +++ www/quotes.wiki | |
| @@ -145,12 +145,12 @@ | |
| 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 | 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 |
+4
-4
| --- www/server/any/althttpd.md | ||
| +++ www/server/any/althttpd.md | ||
| @@ -6,14 +6,14 @@ | ||
| 6 | 6 | security, ease of configuration, and low resource usage. |
| 7 | 7 | |
| 8 | 8 | To set up a Fossil server as CGI on a host running the althttpd web |
| 9 | 9 | server, follow these steps. |
| 10 | 10 | <ol> |
| 11 | -<li<p>Get the althttpd webserver running on the host. This is easily | |
| 11 | +<li>Get the althttpd webserver running on the host. This is easily | |
| 12 | 12 | done by following the [althttpd documentation][althttpd]. |
| 13 | 13 | |
| 14 | -<li><p>Create a CGI script for your Fossil repository. The script will | |
| 14 | +<li>Create a CGI script for your Fossil repository. The script will | |
| 15 | 15 | be typically be two lines of code that look something like this: |
| 16 | 16 | |
| 17 | 17 | ~~~ |
| 18 | 18 | #!/usr/bin/fossil |
| 19 | 19 | repository: /home/yourlogin/fossils/project.fossil |
| @@ -23,13 +23,13 @@ | ||
| 23 | 23 | CGI script accepts [other options][cgi] besides the |
| 24 | 24 | repository:" line. You can add in other options as you desire, |
| 25 | 25 | but the single "repository:" line is normally all that is needed |
| 26 | 26 | to get started. |
| 27 | 27 | |
| 28 | -<li><p>Make the CGI script executable. | |
| 28 | +<li>Make the CGI script executable. | |
| 29 | 29 | |
| 30 | -<li><p>Verify that the fossil repository file and the directory that contains | |
| 30 | +<li>Verify that the fossil repository file and the directory that contains | |
| 31 | 31 | the repository are both writable by whatever user the web server is |
| 32 | 32 | running and. |
| 33 | 33 | </ol> |
| 34 | 34 | |
| 35 | 35 | And you are done. Visit the URL that corresponds to the CGI script |
| 36 | 36 |
| --- www/server/any/althttpd.md | |
| +++ www/server/any/althttpd.md | |
| @@ -6,14 +6,14 @@ | |
| 6 | security, ease of configuration, and low resource usage. |
| 7 | |
| 8 | To set up a Fossil server as CGI on a host running the althttpd web |
| 9 | server, follow these steps. |
| 10 | <ol> |
| 11 | <li<p>Get the althttpd webserver running on the host. This is easily |
| 12 | done by following the [althttpd documentation][althttpd]. |
| 13 | |
| 14 | <li><p>Create a CGI script for your Fossil repository. The script will |
| 15 | be typically be two lines of code that look something like this: |
| 16 | |
| 17 | ~~~ |
| 18 | #!/usr/bin/fossil |
| 19 | repository: /home/yourlogin/fossils/project.fossil |
| @@ -23,13 +23,13 @@ | |
| 23 | CGI script accepts [other options][cgi] besides the |
| 24 | repository:" line. You can add in other options as you desire, |
| 25 | but the single "repository:" line is normally all that is needed |
| 26 | to get started. |
| 27 | |
| 28 | <li><p>Make the CGI script executable. |
| 29 | |
| 30 | <li><p>Verify that the fossil repository file and the directory that contains |
| 31 | the repository are both writable by whatever user the web server is |
| 32 | running and. |
| 33 | </ol> |
| 34 | |
| 35 | And you are done. Visit the URL that corresponds to the CGI script |
| 36 |
| --- www/server/any/althttpd.md | |
| +++ www/server/any/althttpd.md | |
| @@ -6,14 +6,14 @@ | |
| 6 | security, ease of configuration, and low resource usage. |
| 7 | |
| 8 | To set up a Fossil server as CGI on a host running the althttpd web |
| 9 | server, follow these steps. |
| 10 | <ol> |
| 11 | <li>Get the althttpd webserver running on the host. This is easily |
| 12 | done by following the [althttpd documentation][althttpd]. |
| 13 | |
| 14 | <li>Create a CGI script for your Fossil repository. The script will |
| 15 | be typically be two lines of code that look something like this: |
| 16 | |
| 17 | ~~~ |
| 18 | #!/usr/bin/fossil |
| 19 | repository: /home/yourlogin/fossils/project.fossil |
| @@ -23,13 +23,13 @@ | |
| 23 | CGI script accepts [other options][cgi] besides the |
| 24 | repository:" line. You can add in other options as you desire, |
| 25 | but the single "repository:" line is normally all that is needed |
| 26 | to get started. |
| 27 | |
| 28 | <li>Make the CGI script executable. |
| 29 | |
| 30 | <li>Verify that the fossil repository file and the directory that contains |
| 31 | the repository are both writable by whatever user the web server is |
| 32 | running and. |
| 33 | </ol> |
| 34 | |
| 35 | And you are done. Visit the URL that corresponds to the CGI script |
| 36 |
+22
-12
| --- www/server/whyuseaserver.wiki | ||
| +++ www/server/whyuseaserver.wiki | ||
| @@ -12,11 +12,12 @@ | ||
| 12 | 12 | <h2>But, a Server Can Be Useful</h2> |
| 13 | 13 | |
| 14 | 14 | Fossil does not require a server, but a server can be very useful. |
| 15 | 15 | Here are a few reasons to set up a Fossil server for your project: |
| 16 | 16 | |
| 17 | - 1. <b>A server works as a complete project website.</b><p> | |
| 17 | + 1. <b>A server works as a complete project website.</b> | |
| 18 | + | |
| 18 | 19 | Fossil does more than just version control. It also supports |
| 19 | 20 | [../tickets.wiki|trouble-tickets], |
| 20 | 21 | [../wikitheory.wiki|wiki], |
| 21 | 22 | a [../chat.md|developer chat room], and a [../forum.wiki|forum]. |
| 22 | 23 | The [../embeddeddoc.wiki|embedded documentation] |
| @@ -23,11 +24,12 @@ | ||
| 23 | 24 | feature provides a great mechanism for providing project documentation. |
| 24 | 25 | The [../unvers.wiki|unversioned files] feature is a convenient way |
| 25 | 26 | to host builds and downloads on the project website. |
| 26 | 27 | |
| 27 | 28 | 2. <b>A server gives developers a common point of rendezvous for |
| 28 | - syncing their work.</b><p> | |
| 29 | + syncing their work.</b> | |
| 30 | + | |
| 29 | 31 | It is possible for developers to synchronize peer-to-peer but |
| 30 | 32 | that requires the developers coordinate the sync, which in turn |
| 31 | 33 | requires that the developers both want to sync at the same moment. |
| 32 | 34 | A server alleviates this time dependency by allowing each developer |
| 33 | 35 | to sync whenever it is convenient. For example, a developer may |
| @@ -34,52 +36,60 @@ | ||
| 34 | 36 | choose to automatically sync |
| 35 | 37 | after each commit and before each update. Developers all stay |
| 36 | 38 | in sync with each other without having to interrupt each other |
| 37 | 39 | constantly to set up a peer-to-peer sync. |
| 38 | 40 | |
| 39 | - 3. <b>A server provides project leaders with up-to-date status.</b><p> | |
| 41 | + 3. <b>A server provides project leaders with up-to-date status.</b> | |
| 42 | + | |
| 40 | 43 | Project coordinators and BDFLs can click on a link or two at the |
| 41 | 44 | central Fossil server for a project and quickly tell what is |
| 42 | 45 | going on. They can do this from anywhere — even from their phones |
| 43 | 46 | — without needing to actually sync to the device they are using. |
| 44 | 47 | |
| 45 | - 4. <b>A server provides automatic off-site backups.</b><p> | |
| 48 | + 4. <b>A server provides automatic off-site backups.</b> | |
| 49 | + | |
| 46 | 50 | A Fossil server is an automatic remote backup for all the work |
| 47 | 51 | going into a project. ([../backup.md | Within limits].) |
| 48 | 52 | You can even set up multiple servers at |
| 49 | 53 | multiple sites with automatic synchronization between them for |
| 50 | 54 | added redundancy. Such a setup means that no work is lost due |
| 51 | 55 | to a single machine failure. |
| 52 | 56 | |
| 53 | 57 | 5. <b>A server consolidates [https://www.sqlite.org/howtocorrupt.html |
| 54 | - | SQLite corruption risk mitigation] to a single point.</b><p> | |
| 58 | + | SQLite corruption risk mitigation] to a single point.</b> | |
| 59 | + | |
| 55 | 60 | The concerns in section 1 of that document assume you have direct |
| 56 | 61 | access to the central DB files, which isn't the case when the |
| 57 | - server is remote and secure against tampering.<p> | |
| 62 | + server is remote and secure against tampering. | |
| 63 | + | |
| 58 | 64 | Section 2 is about file locking, which concerns disappear when Fossil's |
| 59 | 65 | on the other side of an HTTP boundary and your server is set up |
| 60 | - properly.<p> | |
| 66 | + properly. | |
| 67 | + | |
| 61 | 68 | Sections 3.1, 4 thru 6, and 8 apply to all Fossil configurations, |
| 62 | 69 | but setting up a server lets you address the risks |
| 63 | 70 | in a single place. Once a given commit is |
| 64 | 71 | sync'd to the server, you can be reasonably sure any client-side |
| 65 | 72 | corruption can be fixed with a fresh clone. Ultimately, this |
| 66 | 73 | is an argument for off-machine backups, which returns us to reason |
| 67 | - #4 above.<p> | |
| 74 | + #4 above. | |
| 75 | + | |
| 68 | 76 | Sections 3.2 and the entirety of section 7 are no concern with |
| 69 | 77 | Fossil at all, since it's primarily written by the creator and |
| 70 | 78 | primary maintainer of SQLite, so you can be certain Fossil doesn't |
| 71 | - actively pursue coding strategies known to risk database corruption.<p> | |
| 72 | - <p>For another take on this topic, see the article | |
| 79 | + actively pursue coding strategies known to risk database corruption. | |
| 80 | + | |
| 81 | + For another take on this topic, see the article | |
| 73 | 82 | "[https://sqlite.org/useovernet.html | SQLite Over a Network, |
| 74 | 83 | Caveats and Considerations]". Fossil runs in rollback mode by |
| 75 | 84 | default per recommendation #3 at the end of that article, and a |
| 76 | 85 | Fossil server operates as a network proxy for the underlying |
| 77 | 86 | SQLite repository DB per recommendation #2. This <i>may</i> permit |
| 78 | 87 | you to safely switch it into WAL mode (<b>fossil rebuild --wal</b>) |
| 79 | - depending on the underlying storage used by the server itself.</p> | |
| 88 | + depending on the underlying storage used by the server itself. | |
| 80 | 89 | |
| 81 | - 6. <b>A server allows [../caps/ | Fossil's RBAC system] to work.</b><p> | |
| 90 | + 6. <b>A server allows [../caps/ | Fossil's RBAC system] to work.</b> | |
| 91 | + | |
| 82 | 92 | The role-based access control (RBAC) system in Fossil only works |
| 83 | 93 | when the remote system is on the other side of an HTTP barrier. |
| 84 | 94 | ([../caps/#webonly | Details].) If you want its benefits, you need |
| 85 | 95 | a Fossil server setup of some kind. |
| 86 | 96 |
| --- www/server/whyuseaserver.wiki | |
| +++ www/server/whyuseaserver.wiki | |
| @@ -12,11 +12,12 @@ | |
| 12 | <h2>But, a Server Can Be Useful</h2> |
| 13 | |
| 14 | Fossil does not require a server, but a server can be very useful. |
| 15 | Here are a few reasons to set up a Fossil server for your project: |
| 16 | |
| 17 | 1. <b>A server works as a complete project website.</b><p> |
| 18 | Fossil does more than just version control. It also supports |
| 19 | [../tickets.wiki|trouble-tickets], |
| 20 | [../wikitheory.wiki|wiki], |
| 21 | a [../chat.md|developer chat room], and a [../forum.wiki|forum]. |
| 22 | The [../embeddeddoc.wiki|embedded documentation] |
| @@ -23,11 +24,12 @@ | |
| 23 | feature provides a great mechanism for providing project documentation. |
| 24 | The [../unvers.wiki|unversioned files] feature is a convenient way |
| 25 | to host builds and downloads on the project website. |
| 26 | |
| 27 | 2. <b>A server gives developers a common point of rendezvous for |
| 28 | syncing their work.</b><p> |
| 29 | It is possible for developers to synchronize peer-to-peer but |
| 30 | that requires the developers coordinate the sync, which in turn |
| 31 | requires that the developers both want to sync at the same moment. |
| 32 | A server alleviates this time dependency by allowing each developer |
| 33 | to sync whenever it is convenient. For example, a developer may |
| @@ -34,52 +36,60 @@ | |
| 34 | choose to automatically sync |
| 35 | after each commit and before each update. Developers all stay |
| 36 | in sync with each other without having to interrupt each other |
| 37 | constantly to set up a peer-to-peer sync. |
| 38 | |
| 39 | 3. <b>A server provides project leaders with up-to-date status.</b><p> |
| 40 | Project coordinators and BDFLs can click on a link or two at the |
| 41 | central Fossil server for a project and quickly tell what is |
| 42 | going on. They can do this from anywhere — even from their phones |
| 43 | — without needing to actually sync to the device they are using. |
| 44 | |
| 45 | 4. <b>A server provides automatic off-site backups.</b><p> |
| 46 | A Fossil server is an automatic remote backup for all the work |
| 47 | going into a project. ([../backup.md | Within limits].) |
| 48 | You can even set up multiple servers at |
| 49 | multiple sites with automatic synchronization between them for |
| 50 | added redundancy. Such a setup means that no work is lost due |
| 51 | to a single machine failure. |
| 52 | |
| 53 | 5. <b>A server consolidates [https://www.sqlite.org/howtocorrupt.html |
| 54 | | SQLite corruption risk mitigation] to a single point.</b><p> |
| 55 | The concerns in section 1 of that document assume you have direct |
| 56 | access to the central DB files, which isn't the case when the |
| 57 | server is remote and secure against tampering.<p> |
| 58 | Section 2 is about file locking, which concerns disappear when Fossil's |
| 59 | on the other side of an HTTP boundary and your server is set up |
| 60 | properly.<p> |
| 61 | Sections 3.1, 4 thru 6, and 8 apply to all Fossil configurations, |
| 62 | but setting up a server lets you address the risks |
| 63 | in a single place. Once a given commit is |
| 64 | sync'd to the server, you can be reasonably sure any client-side |
| 65 | corruption can be fixed with a fresh clone. Ultimately, this |
| 66 | is an argument for off-machine backups, which returns us to reason |
| 67 | #4 above.<p> |
| 68 | Sections 3.2 and the entirety of section 7 are no concern with |
| 69 | Fossil at all, since it's primarily written by the creator and |
| 70 | primary maintainer of SQLite, so you can be certain Fossil doesn't |
| 71 | actively pursue coding strategies known to risk database corruption.<p> |
| 72 | <p>For another take on this topic, see the article |
| 73 | "[https://sqlite.org/useovernet.html | SQLite Over a Network, |
| 74 | Caveats and Considerations]". Fossil runs in rollback mode by |
| 75 | default per recommendation #3 at the end of that article, and a |
| 76 | Fossil server operates as a network proxy for the underlying |
| 77 | SQLite repository DB per recommendation #2. This <i>may</i> permit |
| 78 | you to safely switch it into WAL mode (<b>fossil rebuild --wal</b>) |
| 79 | depending on the underlying storage used by the server itself.</p> |
| 80 | |
| 81 | 6. <b>A server allows [../caps/ | Fossil's RBAC system] to work.</b><p> |
| 82 | The role-based access control (RBAC) system in Fossil only works |
| 83 | when the remote system is on the other side of an HTTP barrier. |
| 84 | ([../caps/#webonly | Details].) If you want its benefits, you need |
| 85 | a Fossil server setup of some kind. |
| 86 |
| --- www/server/whyuseaserver.wiki | |
| +++ www/server/whyuseaserver.wiki | |
| @@ -12,11 +12,12 @@ | |
| 12 | <h2>But, a Server Can Be Useful</h2> |
| 13 | |
| 14 | Fossil does not require a server, but a server can be very useful. |
| 15 | Here are a few reasons to set up a Fossil server for your project: |
| 16 | |
| 17 | 1. <b>A server works as a complete project website.</b> |
| 18 | |
| 19 | Fossil does more than just version control. It also supports |
| 20 | [../tickets.wiki|trouble-tickets], |
| 21 | [../wikitheory.wiki|wiki], |
| 22 | a [../chat.md|developer chat room], and a [../forum.wiki|forum]. |
| 23 | The [../embeddeddoc.wiki|embedded documentation] |
| @@ -23,11 +24,12 @@ | |
| 24 | feature provides a great mechanism for providing project documentation. |
| 25 | The [../unvers.wiki|unversioned files] feature is a convenient way |
| 26 | to host builds and downloads on the project website. |
| 27 | |
| 28 | 2. <b>A server gives developers a common point of rendezvous for |
| 29 | syncing their work.</b> |
| 30 | |
| 31 | It is possible for developers to synchronize peer-to-peer but |
| 32 | that requires the developers coordinate the sync, which in turn |
| 33 | requires that the developers both want to sync at the same moment. |
| 34 | A server alleviates this time dependency by allowing each developer |
| 35 | to sync whenever it is convenient. For example, a developer may |
| @@ -34,52 +36,60 @@ | |
| 36 | choose to automatically sync |
| 37 | after each commit and before each update. Developers all stay |
| 38 | in sync with each other without having to interrupt each other |
| 39 | constantly to set up a peer-to-peer sync. |
| 40 | |
| 41 | 3. <b>A server provides project leaders with up-to-date status.</b> |
| 42 | |
| 43 | Project coordinators and BDFLs can click on a link or two at the |
| 44 | central Fossil server for a project and quickly tell what is |
| 45 | going on. They can do this from anywhere — even from their phones |
| 46 | — without needing to actually sync to the device they are using. |
| 47 | |
| 48 | 4. <b>A server provides automatic off-site backups.</b> |
| 49 | |
| 50 | A Fossil server is an automatic remote backup for all the work |
| 51 | going into a project. ([../backup.md | Within limits].) |
| 52 | You can even set up multiple servers at |
| 53 | multiple sites with automatic synchronization between them for |
| 54 | added redundancy. Such a setup means that no work is lost due |
| 55 | to a single machine failure. |
| 56 | |
| 57 | 5. <b>A server consolidates [https://www.sqlite.org/howtocorrupt.html |
| 58 | | SQLite corruption risk mitigation] to a single point.</b> |
| 59 | |
| 60 | The concerns in section 1 of that document assume you have direct |
| 61 | access to the central DB files, which isn't the case when the |
| 62 | server is remote and secure against tampering. |
| 63 | |
| 64 | Section 2 is about file locking, which concerns disappear when Fossil's |
| 65 | on the other side of an HTTP boundary and your server is set up |
| 66 | properly. |
| 67 | |
| 68 | Sections 3.1, 4 thru 6, and 8 apply to all Fossil configurations, |
| 69 | but setting up a server lets you address the risks |
| 70 | in a single place. Once a given commit is |
| 71 | sync'd to the server, you can be reasonably sure any client-side |
| 72 | corruption can be fixed with a fresh clone. Ultimately, this |
| 73 | is an argument for off-machine backups, which returns us to reason |
| 74 | #4 above. |
| 75 | |
| 76 | Sections 3.2 and the entirety of section 7 are no concern with |
| 77 | Fossil at all, since it's primarily written by the creator and |
| 78 | primary maintainer of SQLite, so you can be certain Fossil doesn't |
| 79 | actively pursue coding strategies known to risk database corruption. |
| 80 | |
| 81 | For another take on this topic, see the article |
| 82 | "[https://sqlite.org/useovernet.html | SQLite Over a Network, |
| 83 | Caveats and Considerations]". Fossil runs in rollback mode by |
| 84 | default per recommendation #3 at the end of that article, and a |
| 85 | Fossil server operates as a network proxy for the underlying |
| 86 | SQLite repository DB per recommendation #2. This <i>may</i> permit |
| 87 | you to safely switch it into WAL mode (<b>fossil rebuild --wal</b>) |
| 88 | depending on the underlying storage used by the server itself. |
| 89 | |
| 90 | 6. <b>A server allows [../caps/ | Fossil's RBAC system] to work.</b> |
| 91 | |
| 92 | The role-based access control (RBAC) system in Fossil only works |
| 93 | when the remote system is on the other side of an HTTP barrier. |
| 94 | ([../caps/#webonly | Details].) If you want its benefits, you need |
| 95 | a Fossil server setup of some kind. |
| 96 |
+49
-50
| --- www/shunning.wiki | ||
| +++ www/shunning.wiki | ||
| @@ -37,60 +37,59 @@ | ||
| 37 | 37 | Fossil to insert bad control artifacts. Therefore, before we get to |
| 38 | 38 | methods of permanently deleting content from a Fossil repos, let's give |
| 39 | 39 | some alternatives that usually suffice, which don't damage the project's |
| 40 | 40 | fossil record: |
| 41 | 41 | |
| 42 | -<ul> | |
| 43 | - <li><p>When a forum post or wiki article is "deleted," what actually | |
| 44 | - happens is that a new empty version is added to the Fossil repository. | |
| 45 | - The web interface interprets this | |
| 46 | - as "deleted," but the prior version remains available if you go | |
| 47 | - digging for it.</p></li> | |
| 48 | - | |
| 49 | - <li><p>When you close a ticket, it's marked in a way that causes it | |
| 50 | - to not show up in the normal ticket reports. You usually want to | |
| 51 | - give it a Resolution such as "Rejected" when this happens, plus | |
| 52 | - possibly a comment explaining why you're closing it. This is all new | |
| 53 | - information added to the ticket, not deletion.</p></li> | |
| 54 | - | |
| 55 | - <li><p>When you <tt>fossil rm</tt> a file, a new manifest is | |
| 56 | - checked into the repository with the same file list as for the prior | |
| 57 | - version minus the "removed" file. The file is still present in the | |
| 58 | - repository; it just isn't part of that version forward on that | |
| 59 | - branch.</p></li> | |
| 60 | - | |
| 61 | - <li><p>If you make a bad check-in, you can shunt it off to the side | |
| 62 | - by amending it to put it on a different branch, then continuing | |
| 63 | - development on the prior branch: | |
| 64 | - <p> | |
| 65 | - <tt>$ fossil amend abcd1234 --branch BOGUS --hide<br> | |
| 66 | - $ fossil up trunk</tt> | |
| 67 | - <p> | |
| 68 | - The first command moves check-in ID <tt>abcd1234</tt> (and any | |
| 69 | - subsequent check-ins on that branch!) to a branch called | |
| 70 | - <tt>BOGUS</tt>, then hides it so it doesn't show up on the | |
| 71 | - timeline. You can call this branch anything you like, and you can | |
| 72 | - re-use the same name as many times as you like. No content is | |
| 73 | - actually deleted: it's just shunted off to the side and hidden away. | |
| 74 | - You might find it easier to do this from the Fossil web UI in | |
| 75 | - the "edit" function for a check-in. | |
| 76 | - <p> | |
| 77 | - The second command returns to the last good check-in on that branch | |
| 78 | - so you can continue work from that point.</p></li> | |
| 79 | - | |
| 80 | - <li><p>When the check-in you want to remove is followed by good | |
| 81 | - check-ins on the same branch, you can't use the previous method, | |
| 82 | - because it will move the good check-ins, too. The solution is: | |
| 83 | - <p> | |
| 84 | - <tt>$ fossil merge --backout abcd1234</tt> | |
| 85 | - <p>That creates a diff in the check-out directory that backs out the | |
| 86 | - bad check-in <tt>abcd1234</tt>. You then fix up any merge conflicts, | |
| 87 | - build, test, etc., then check the reverting change into the | |
| 88 | - repository. Again, nothing is actually deleted; you're just adding | |
| 89 | - more information to the repository which corrects a prior | |
| 90 | - check-in.</p></li> | |
| 91 | -</ul> | |
| 42 | + * When a forum post or wiki article is "deleted," what actually | |
| 43 | + happens is that a new empty version is added to the Fossil repository. | |
| 44 | + The web interface interprets this | |
| 45 | + as "deleted," but the prior version remains available if you go | |
| 46 | + digging for it. | |
| 47 | + | |
| 48 | + * When you close a ticket, it's marked in a way that causes it | |
| 49 | + to not show up in the normal ticket reports. You usually want to | |
| 50 | + give it a Resolution such as "Rejected" when this happens, plus | |
| 51 | + possibly a comment explaining why you're closing it. This is all new | |
| 52 | + information added to the ticket, not deletion. | |
| 53 | + | |
| 54 | + * When you <tt>fossil rm</tt> a file, a new manifest is | |
| 55 | + checked into the repository with the same file list as for the prior | |
| 56 | + version minus the "removed" file. The file is still present in the | |
| 57 | + repository; it just isn't part of that version forward on that | |
| 58 | + branch. | |
| 59 | + | |
| 60 | + * If you make a bad check-in, you can shunt it off to the side | |
| 61 | + by amending it to put it on a different branch, then continuing | |
| 62 | + development on the prior branch: | |
| 63 | + <br><br> | |
| 64 | + <code>$ fossil amend abcd1234 --branch BOGUS --hide<br> | |
| 65 | + $ fossil up trunk</code> | |
| 66 | + <br><br> | |
| 67 | + The first command moves check-in ID <tt>abcd1234</tt> (and any | |
| 68 | + subsequent check-ins on that branch!) to a branch called | |
| 69 | + <tt>BOGUS</tt>, then hides it so it doesn't show up on the | |
| 70 | + timeline. You can call this branch anything you like, and you can | |
| 71 | + re-use the same name as many times as you like. No content is | |
| 72 | + actually deleted: it's just shunted off to the side and hidden away. | |
| 73 | + You might find it easier to do this from the Fossil web UI in | |
| 74 | + the "edit" function for a check-in. | |
| 75 | + <br><br> | |
| 76 | + The second command returns to the last good check-in on that branch | |
| 77 | + so you can continue work from that point. | |
| 78 | + | |
| 79 | + * When the check-in you want to remove is followed by good | |
| 80 | + check-ins on the same branch, you can't use the previous method, | |
| 81 | + because it will move the good check-ins, too. The solution is: | |
| 82 | + <br><br> | |
| 83 | + <tt>$ fossil merge --backout abcd1234</tt> | |
| 84 | + <br><br> | |
| 85 | + That creates a diff in the check-out directory that backs out the | |
| 86 | + bad check-in <tt>abcd1234</tt>. You then fix up any merge conflicts, | |
| 87 | + build, test, etc., then check the reverting change into the | |
| 88 | + repository. Again, nothing is actually deleted; you're just adding | |
| 89 | + more information to the repository which corrects a prior | |
| 90 | + check-in. | |
| 92 | 91 | |
| 93 | 92 | <h2>Exception: Non-versioned Content</h2> |
| 94 | 93 | |
| 95 | 94 | It is normal and expected to delete data which is not versioned, such as |
| 96 | 95 | usernames and passwords in the user table. The [/help/scrub|fossil scrub] |
| 97 | 96 |
| --- www/shunning.wiki | |
| +++ www/shunning.wiki | |
| @@ -37,60 +37,59 @@ | |
| 37 | Fossil to insert bad control artifacts. Therefore, before we get to |
| 38 | methods of permanently deleting content from a Fossil repos, let's give |
| 39 | some alternatives that usually suffice, which don't damage the project's |
| 40 | fossil record: |
| 41 | |
| 42 | <ul> |
| 43 | <li><p>When a forum post or wiki article is "deleted," what actually |
| 44 | happens is that a new empty version is added to the Fossil repository. |
| 45 | The web interface interprets this |
| 46 | as "deleted," but the prior version remains available if you go |
| 47 | digging for it.</p></li> |
| 48 | |
| 49 | <li><p>When you close a ticket, it's marked in a way that causes it |
| 50 | to not show up in the normal ticket reports. You usually want to |
| 51 | give it a Resolution such as "Rejected" when this happens, plus |
| 52 | possibly a comment explaining why you're closing it. This is all new |
| 53 | information added to the ticket, not deletion.</p></li> |
| 54 | |
| 55 | <li><p>When you <tt>fossil rm</tt> a file, a new manifest is |
| 56 | checked into the repository with the same file list as for the prior |
| 57 | version minus the "removed" file. The file is still present in the |
| 58 | repository; it just isn't part of that version forward on that |
| 59 | branch.</p></li> |
| 60 | |
| 61 | <li><p>If you make a bad check-in, you can shunt it off to the side |
| 62 | by amending it to put it on a different branch, then continuing |
| 63 | development on the prior branch: |
| 64 | <p> |
| 65 | <tt>$ fossil amend abcd1234 --branch BOGUS --hide<br> |
| 66 | $ fossil up trunk</tt> |
| 67 | <p> |
| 68 | The first command moves check-in ID <tt>abcd1234</tt> (and any |
| 69 | subsequent check-ins on that branch!) to a branch called |
| 70 | <tt>BOGUS</tt>, then hides it so it doesn't show up on the |
| 71 | timeline. You can call this branch anything you like, and you can |
| 72 | re-use the same name as many times as you like. No content is |
| 73 | actually deleted: it's just shunted off to the side and hidden away. |
| 74 | You might find it easier to do this from the Fossil web UI in |
| 75 | the "edit" function for a check-in. |
| 76 | <p> |
| 77 | The second command returns to the last good check-in on that branch |
| 78 | so you can continue work from that point.</p></li> |
| 79 | |
| 80 | <li><p>When the check-in you want to remove is followed by good |
| 81 | check-ins on the same branch, you can't use the previous method, |
| 82 | because it will move the good check-ins, too. The solution is: |
| 83 | <p> |
| 84 | <tt>$ fossil merge --backout abcd1234</tt> |
| 85 | <p>That creates a diff in the check-out directory that backs out the |
| 86 | bad check-in <tt>abcd1234</tt>. You then fix up any merge conflicts, |
| 87 | build, test, etc., then check the reverting change into the |
| 88 | repository. Again, nothing is actually deleted; you're just adding |
| 89 | more information to the repository which corrects a prior |
| 90 | check-in.</p></li> |
| 91 | </ul> |
| 92 | |
| 93 | <h2>Exception: Non-versioned Content</h2> |
| 94 | |
| 95 | It is normal and expected to delete data which is not versioned, such as |
| 96 | usernames and passwords in the user table. The [/help/scrub|fossil scrub] |
| 97 |
| --- www/shunning.wiki | |
| +++ www/shunning.wiki | |
| @@ -37,60 +37,59 @@ | |
| 37 | Fossil to insert bad control artifacts. Therefore, before we get to |
| 38 | methods of permanently deleting content from a Fossil repos, let's give |
| 39 | some alternatives that usually suffice, which don't damage the project's |
| 40 | fossil record: |
| 41 | |
| 42 | * When a forum post or wiki article is "deleted," what actually |
| 43 | happens is that a new empty version is added to the Fossil repository. |
| 44 | The web interface interprets this |
| 45 | as "deleted," but the prior version remains available if you go |
| 46 | digging for it. |
| 47 | |
| 48 | * When you close a ticket, it's marked in a way that causes it |
| 49 | to not show up in the normal ticket reports. You usually want to |
| 50 | give it a Resolution such as "Rejected" when this happens, plus |
| 51 | possibly a comment explaining why you're closing it. This is all new |
| 52 | information added to the ticket, not deletion. |
| 53 | |
| 54 | * When you <tt>fossil rm</tt> a file, a new manifest is |
| 55 | checked into the repository with the same file list as for the prior |
| 56 | version minus the "removed" file. The file is still present in the |
| 57 | repository; it just isn't part of that version forward on that |
| 58 | branch. |
| 59 | |
| 60 | * If you make a bad check-in, you can shunt it off to the side |
| 61 | by amending it to put it on a different branch, then continuing |
| 62 | development on the prior branch: |
| 63 | <br><br> |
| 64 | <code>$ fossil amend abcd1234 --branch BOGUS --hide<br> |
| 65 | $ fossil up trunk</code> |
| 66 | <br><br> |
| 67 | The first command moves check-in ID <tt>abcd1234</tt> (and any |
| 68 | subsequent check-ins on that branch!) to a branch called |
| 69 | <tt>BOGUS</tt>, then hides it so it doesn't show up on the |
| 70 | timeline. You can call this branch anything you like, and you can |
| 71 | re-use the same name as many times as you like. No content is |
| 72 | actually deleted: it's just shunted off to the side and hidden away. |
| 73 | You might find it easier to do this from the Fossil web UI in |
| 74 | the "edit" function for a check-in. |
| 75 | <br><br> |
| 76 | The second command returns to the last good check-in on that branch |
| 77 | so you can continue work from that point. |
| 78 | |
| 79 | * When the check-in you want to remove is followed by good |
| 80 | check-ins on the same branch, you can't use the previous method, |
| 81 | because it will move the good check-ins, too. The solution is: |
| 82 | <br><br> |
| 83 | <tt>$ fossil merge --backout abcd1234</tt> |
| 84 | <br><br> |
| 85 | That creates a diff in the check-out directory that backs out the |
| 86 | bad check-in <tt>abcd1234</tt>. You then fix up any merge conflicts, |
| 87 | build, test, etc., then check the reverting change into the |
| 88 | repository. Again, nothing is actually deleted; you're just adding |
| 89 | more information to the repository which corrects a prior |
| 90 | check-in. |
| 91 | |
| 92 | <h2>Exception: Non-versioned Content</h2> |
| 93 | |
| 94 | It is normal and expected to delete data which is not versioned, such as |
| 95 | usernames and passwords in the user table. The [/help/scrub|fossil scrub] |
| 96 |
+14
-11
| --- www/ssl.wiki | ||
| +++ www/ssl.wiki | ||
| @@ -140,15 +140,16 @@ | ||
| 140 | 140 | </pre> |
| 141 | 141 | |
| 142 | 142 | Fossil relies on the OpenSSL library to have some way to check a trusted |
| 143 | 143 | list of CA signing keys. There are two common ways this fails: |
| 144 | 144 | |
| 145 | - # <p>The OpenSSL library Fossil is linked to doesn't have a CA | |
| 145 | + # The OpenSSL library Fossil is linked to doesn't have a CA | |
| 146 | 146 | signing key set at all, so that it initially trusts no certificates |
| 147 | - at all.</p> | |
| 148 | - # <p>The OpenSSL library does have a CA cert set, but your Fossil server's | |
| 149 | - TLS certificate was signed by a CA that isn't in that set.</p> | |
| 147 | + at all. | |
| 148 | + | |
| 149 | + # The OpenSSL library does have a CA cert set, but your Fossil server's | |
| 150 | + TLS certificate was signed by a CA that isn't in that set. | |
| 150 | 151 | |
| 151 | 152 | A common reason to fall into the second trap is that you're using |
| 152 | 153 | certificates signed by a local private CA, as often happens in large |
| 153 | 154 | enterprises. You can solve this sort of problem by getting your local |
| 154 | 155 | CA's signing certificate in PEM format and pointing OpenSSL at it: |
| @@ -272,26 +273,28 @@ | ||
| 272 | 273 | it issues a redirect...'round and 'round it goes until the web browser |
| 273 | 274 | detects it's in a redirect loop and gives up. This problem prevents you |
| 274 | 275 | from getting back into the Admin UI to fix it, but there are several |
| 275 | 276 | ways to fix it: |
| 276 | 277 | |
| 277 | - # <p><b>Reset via CLI.</b> You can turn the setting back off from the | |
| 278 | + # <b>Reset via CLI.</b> You can turn the setting back off from the | |
| 278 | 279 | CLI with the command "<tt>fossil -R /path/to/repo.fossil set |
| 279 | - redirect-to-https 0</tt>". (Currently doesn't work.)</p> | |
| 280 | - # <p><b>Backup first.</b> This setting is stored in the Fossil | |
| 280 | + redirect-to-https 0</tt>". (Currently doesn't work.) | |
| 281 | + | |
| 282 | + # <b>Backup first.</b> This setting is stored in the Fossil | |
| 281 | 283 | repository, so if you make a backup first <i>on the server</i>, you |
| 282 | 284 | can restore the repo file if enabling this feature creates a |
| 283 | - redirect loop.</p> | |
| 284 | - # <p><b>Download, fix, and restore.</b> You can copy the remote | |
| 285 | + redirect loop. | |
| 286 | + | |
| 287 | + # <b>Download, fix, and restore.</b> You can copy the remote | |
| 285 | 288 | repository file down to a local machine, use <tt>fossil ui</tt> to |
| 286 | 289 | fix the setting, and then upload it to the repository server |
| 287 | - again.</p> | |
| 290 | + again. | |
| 288 | 291 | |
| 289 | 292 | It's best to enforce TLS-only access at the front-end proxy level |
| 290 | 293 | anyway. It not only avoids the problem entirely, it can be significantly |
| 291 | 294 | more secure. The [./server/debian/nginx.md#tls | nginx-on-Debian proxy guide] shows one way |
| 292 | -to achieve this.</p> | |
| 295 | +to achieve this. | |
| 293 | 296 | |
| 294 | 297 | |
| 295 | 298 | <h2>Terminology Note</h2> |
| 296 | 299 | |
| 297 | 300 | This document is called <tt>ssl.wiki</tt> for historical reasons. The |
| 298 | 301 |
| --- www/ssl.wiki | |
| +++ www/ssl.wiki | |
| @@ -140,15 +140,16 @@ | |
| 140 | </pre> |
| 141 | |
| 142 | Fossil relies on the OpenSSL library to have some way to check a trusted |
| 143 | list of CA signing keys. There are two common ways this fails: |
| 144 | |
| 145 | # <p>The OpenSSL library Fossil is linked to doesn't have a CA |
| 146 | signing key set at all, so that it initially trusts no certificates |
| 147 | at all.</p> |
| 148 | # <p>The OpenSSL library does have a CA cert set, but your Fossil server's |
| 149 | TLS certificate was signed by a CA that isn't in that set.</p> |
| 150 | |
| 151 | A common reason to fall into the second trap is that you're using |
| 152 | certificates signed by a local private CA, as often happens in large |
| 153 | enterprises. You can solve this sort of problem by getting your local |
| 154 | CA's signing certificate in PEM format and pointing OpenSSL at it: |
| @@ -272,26 +273,28 @@ | |
| 272 | it issues a redirect...'round and 'round it goes until the web browser |
| 273 | detects it's in a redirect loop and gives up. This problem prevents you |
| 274 | from getting back into the Admin UI to fix it, but there are several |
| 275 | ways to fix it: |
| 276 | |
| 277 | # <p><b>Reset via CLI.</b> You can turn the setting back off from the |
| 278 | CLI with the command "<tt>fossil -R /path/to/repo.fossil set |
| 279 | redirect-to-https 0</tt>". (Currently doesn't work.)</p> |
| 280 | # <p><b>Backup first.</b> This setting is stored in the Fossil |
| 281 | repository, so if you make a backup first <i>on the server</i>, you |
| 282 | can restore the repo file if enabling this feature creates a |
| 283 | redirect loop.</p> |
| 284 | # <p><b>Download, fix, and restore.</b> You can copy the remote |
| 285 | repository file down to a local machine, use <tt>fossil ui</tt> to |
| 286 | fix the setting, and then upload it to the repository server |
| 287 | again.</p> |
| 288 | |
| 289 | It's best to enforce TLS-only access at the front-end proxy level |
| 290 | anyway. It not only avoids the problem entirely, it can be significantly |
| 291 | more secure. The [./server/debian/nginx.md#tls | nginx-on-Debian proxy guide] shows one way |
| 292 | to achieve this.</p> |
| 293 | |
| 294 | |
| 295 | <h2>Terminology Note</h2> |
| 296 | |
| 297 | This document is called <tt>ssl.wiki</tt> for historical reasons. The |
| 298 |
| --- www/ssl.wiki | |
| +++ www/ssl.wiki | |
| @@ -140,15 +140,16 @@ | |
| 140 | </pre> |
| 141 | |
| 142 | Fossil relies on the OpenSSL library to have some way to check a trusted |
| 143 | list of CA signing keys. There are two common ways this fails: |
| 144 | |
| 145 | # The OpenSSL library Fossil is linked to doesn't have a CA |
| 146 | signing key set at all, so that it initially trusts no certificates |
| 147 | at all. |
| 148 | |
| 149 | # The OpenSSL library does have a CA cert set, but your Fossil server's |
| 150 | TLS certificate was signed by a CA that isn't in that set. |
| 151 | |
| 152 | A common reason to fall into the second trap is that you're using |
| 153 | certificates signed by a local private CA, as often happens in large |
| 154 | enterprises. You can solve this sort of problem by getting your local |
| 155 | CA's signing certificate in PEM format and pointing OpenSSL at it: |
| @@ -272,26 +273,28 @@ | |
| 273 | it issues a redirect...'round and 'round it goes until the web browser |
| 274 | detects it's in a redirect loop and gives up. This problem prevents you |
| 275 | from getting back into the Admin UI to fix it, but there are several |
| 276 | ways to fix it: |
| 277 | |
| 278 | # <b>Reset via CLI.</b> You can turn the setting back off from the |
| 279 | CLI with the command "<tt>fossil -R /path/to/repo.fossil set |
| 280 | redirect-to-https 0</tt>". (Currently doesn't work.) |
| 281 | |
| 282 | # <b>Backup first.</b> This setting is stored in the Fossil |
| 283 | repository, so if you make a backup first <i>on the server</i>, you |
| 284 | can restore the repo file if enabling this feature creates a |
| 285 | redirect loop. |
| 286 | |
| 287 | # <b>Download, fix, and restore.</b> You can copy the remote |
| 288 | repository file down to a local machine, use <tt>fossil ui</tt> to |
| 289 | fix the setting, and then upload it to the repository server |
| 290 | again. |
| 291 | |
| 292 | It's best to enforce TLS-only access at the front-end proxy level |
| 293 | anyway. It not only avoids the problem entirely, it can be significantly |
| 294 | more secure. The [./server/debian/nginx.md#tls | nginx-on-Debian proxy guide] shows one way |
| 295 | to achieve this. |
| 296 | |
| 297 | |
| 298 | <h2>Terminology Note</h2> |
| 299 | |
| 300 | This document is called <tt>ssl.wiki</tt> for historical reasons. The |
| 301 |
+191
-200
| --- www/sync.wiki | ||
| +++ www/sync.wiki | ||
| @@ -1,13 +1,13 @@ | ||
| 1 | 1 | <title>The Fossil Sync Protocol</title> |
| 2 | 2 | |
| 3 | -<p>This document describes the wire protocol used to synchronize | |
| 4 | -content between two Fossil repositories.</p> | |
| 3 | +This document describes the wire protocol used to synchronize | |
| 4 | +content between two Fossil repositories. | |
| 5 | 5 | |
| 6 | 6 | <h2>1.0 Overview</h2> |
| 7 | 7 | |
| 8 | -<p>The global state of a fossil repository consists of an unordered | |
| 8 | +The global state of a fossil repository consists of an unordered | |
| 9 | 9 | collection of artifacts. Each artifact is identified by a cryptographic |
| 10 | 10 | hash of its content, expressed as a lower-case hexadecimal string. |
| 11 | 11 | Synchronization is the process of sharing artifacts between |
| 12 | 12 | repositories so that all repositories have copies of all artifacts. Because |
| 13 | 13 | artifacts are unordered, the order in which artifacts are received |
| @@ -17,13 +17,13 @@ | ||
| 17 | 17 | of hashes for available artifacts, then sharing the content of artifacts |
| 18 | 18 | whose names are missing from one side or the other of the connection. |
| 19 | 19 | In practice, a repository might contain millions of artifacts. The list of |
| 20 | 20 | hash names for this many artifacts can be large. So optimizations are |
| 21 | 21 | employed that usually reduce the number of hashes that need to be |
| 22 | -shared to a few hundred.</p> | |
| 22 | +shared to a few hundred. | |
| 23 | 23 | |
| 24 | -<p>Each repository also has local state. The local state determines | |
| 24 | +Each repository also has local state. The local state determines | |
| 25 | 25 | the web-page formatting preferences, authorized users, ticket formats, |
| 26 | 26 | and similar information that varies from one repository to another. |
| 27 | 27 | The local state is not usually transferred during a sync. Except, |
| 28 | 28 | some local state is transferred during a [/help?cmd=clone|clone] |
| 29 | 29 | in order to initialize the local state of the new repository. Also, |
| @@ -32,67 +32,67 @@ | ||
| 32 | 32 | [/help?cmd=configuration|config pull] |
| 33 | 33 | commands. |
| 34 | 34 | |
| 35 | 35 | <h3 id="crdt">1.1 Conflict-Free Replicated Datatypes</h3> |
| 36 | 36 | |
| 37 | -<p>The "bag of artifacts" data model used by Fossil is apparently an | |
| 37 | +The "bag of artifacts" data model used by Fossil is apparently an | |
| 38 | 38 | implementation of a particular |
| 39 | 39 | [https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type|Conflict-Free |
| 40 | 40 | Replicated Datatype (CRDT)] called a "G-Set" or "Grow-only Set". The |
| 41 | 41 | academic literature on CRDTs only began to appear in about 2011, and |
| 42 | 42 | Fossil predates that research by at least 4 years. But it is nice to |
| 43 | 43 | know that theorists have now proven that the underlying data model of |
| 44 | 44 | Fossil can provide strongly-consistent replicas using only |
| 45 | 45 | peer-to-peer communication and without any kind of central |
| 46 | -authority.</p> | |
| 46 | +authority. | |
| 47 | 47 | |
| 48 | -<p>If you are already familiar with CRDTs and were wondering if Fossil | |
| 49 | -used them, the answer is "yes". We just don't call them by that name.</p> | |
| 48 | +If you are already familiar with CRDTs and were wondering if Fossil | |
| 49 | +used them, the answer is "yes". We just don't call them by that name. | |
| 50 | 50 | |
| 51 | 51 | |
| 52 | 52 | <h2>2.0 Transport</h2> |
| 53 | 53 | |
| 54 | -<p>All communication between client and server is via HTTP requests. | |
| 54 | +All communication between client and server is via HTTP requests. | |
| 55 | 55 | The server is listening for incoming HTTP requests. The client |
| 56 | 56 | issues one or more HTTP requests and receives replies for each |
| 57 | -request.</p> | |
| 57 | +request. | |
| 58 | 58 | |
| 59 | -<p>The server might be running as an independent server | |
| 59 | +The server might be running as an independent server | |
| 60 | 60 | using the <b>server</b> command, or it might be launched from |
| 61 | 61 | inetd or xinetd using the <b>http</b> command. Or the server might |
| 62 | 62 | be launched from CGI. |
| 63 | 63 | (See "[./server/|How To Configure A Fossil Server]" for details.) |
| 64 | 64 | The specifics of how the server listens |
| 65 | 65 | for incoming HTTP requests is immaterial to this protocol. |
| 66 | 66 | The important point is that the server is listening for requests and |
| 67 | -the client is the issuer of the requests.</p> | |
| 67 | +the client is the issuer of the requests. | |
| 68 | 68 | |
| 69 | -<p>A single push, pull, or sync might involve multiple HTTP requests. | |
| 69 | +A single push, pull, or sync might involve multiple HTTP requests. | |
| 70 | 70 | The client maintains state between all requests. But on the server |
| 71 | 71 | side, each request is independent. The server does not preserve |
| 72 | -any information about the client from one request to the next.</p> | |
| 72 | +any information about the client from one request to the next. | |
| 73 | 73 | |
| 74 | -<p>Note: Throughout this article, we use the terms "server" and "client" | |
| 74 | +Note: Throughout this article, we use the terms "server" and "client" | |
| 75 | 75 | to represent the listener and initiator of the interaction, respectively. |
| 76 | 76 | Nothing in this protocol requires that the server actually be a back-room |
| 77 | 77 | processor housed in a datacenter, nor does the client need to be a desktop |
| 78 | 78 | or handheld device. For the purposes of this article "client" simply means |
| 79 | 79 | the repository that initiates the conversation and "server" is the repository |
| 80 | -that responds. Nothing more.</p> | |
| 80 | +that responds. Nothing more. | |
| 81 | 81 | |
| 82 | 82 | <h4>2.0.1 HTTPS Transport</h4> |
| 83 | 83 | |
| 84 | -<p>In the current implementation of Fossil, the server only | |
| 84 | +In the current implementation of Fossil, the server only | |
| 85 | 85 | understands HTTP requests. The client can send either |
| 86 | 86 | clear-text HTTP requests or encrypted HTTPS requests. But when |
| 87 | 87 | HTTPS requests are sent, they first must be decrypted by a web server |
| 88 | 88 | or proxy before being passed to the Fossil server. This limitation |
| 89 | -may be relaxed in a future release.</p> | |
| 89 | +may be relaxed in a future release. | |
| 90 | 90 | |
| 91 | 91 | <h4>2.0.2 SSH Transport</h4> |
| 92 | 92 | |
| 93 | -<p>When doing a sync using an "ssh:..." URL, the same HTTP transport protocol | |
| 93 | +When doing a sync using an "ssh:..." URL, the same HTTP transport protocol | |
| 94 | 94 | is used. Fossil simply uses [https://en.wikipedia.org/wiki/Secure_Shell|ssh] |
| 95 | 95 | to start an instance of the [/help?cmd=test-http|fossil test-http] command |
| 96 | 96 | running on the remote machine. It then sends HTTP requests and gets back HTTP |
| 97 | 97 | replies over the SSH connection, rather than sending and receiving over an |
| 98 | 98 | internet socket. To see the specific "ssh" command that the Fossil client |
| @@ -99,11 +99,11 @@ | ||
| 99 | 99 | runs in order to set up a connection, add either of the the "--httptrace" or |
| 100 | 100 | "--sshtrace" options to the "fossil sync" command line. |
| 101 | 101 | |
| 102 | 102 | <h4>2.0.3 FILE Transport</h4> |
| 103 | 103 | |
| 104 | -<p>When doing a sync using a "file:..." URL, the same HTTP protocol is | |
| 104 | +When doing a sync using a "file:..." URL, the same HTTP protocol is | |
| 105 | 105 | still used. But instead of sending each HTTP request over a socket or |
| 106 | 106 | via SSH, the HTTP request is written into a temporary file. The client |
| 107 | 107 | then invokes the [/help?cmd=http|fossil http] command in a subprocess |
| 108 | 108 | to process the request and and generate a reply. The client then reads |
| 109 | 109 | the HTTP reply out of a temporary file on disk, and deletes the two |
| @@ -111,36 +111,36 @@ | ||
| 111 | 111 | in order to implement the "file:" transport, add the "--httptrace" |
| 112 | 112 | option to the "fossil sync" command. |
| 113 | 113 | |
| 114 | 114 | <h3>2.1 Server Identification</h3> |
| 115 | 115 | |
| 116 | -<p>The server is identified by a URL argument that accompanies the | |
| 116 | +The server is identified by a URL argument that accompanies the | |
| 117 | 117 | push, pull, or sync command on the client. (As a convenience to |
| 118 | 118 | users, the URL can be omitted on the client command and the same URL |
| 119 | 119 | from the most recent push, pull, or sync will be reused. This saves |
| 120 | 120 | typing in the common case where the client does multiple syncs to |
| 121 | -the same server.)</p> | |
| 121 | +the same server.) | |
| 122 | 122 | |
| 123 | -<p>The client modifies the URL by appending the method name "<b>/xfer</b>" | |
| 123 | +The client modifies the URL by appending the method name "<b>/xfer</b>" | |
| 124 | 124 | to the end. For example, if the URL specified on the client command |
| 125 | -line is</p> | |
| 125 | +line is | |
| 126 | 126 | |
| 127 | 127 | <blockquote> |
| 128 | 128 | https://fossil-scm.org/fossil |
| 129 | 129 | </blockquote> |
| 130 | 130 | |
| 131 | -<p>Then the URL that is really used to do the synchronization will | |
| 132 | -be:</p> | |
| 131 | +Then the URL that is really used to do the synchronization will | |
| 132 | +be: | |
| 133 | 133 | |
| 134 | 134 | <blockquote> |
| 135 | 135 | https://fossil-scm.org/fossil/xfer |
| 136 | 136 | </blockquote> |
| 137 | 137 | |
| 138 | 138 | <h3>2.2 HTTP Request Format</h3> |
| 139 | 139 | |
| 140 | -<p>The client always sends a POST request to the server. The | |
| 141 | -general format of the POST request is as follows:</p> | |
| 140 | +The client always sends a POST request to the server. The | |
| 141 | +general format of the POST request is as follows: | |
| 142 | 142 | |
| 143 | 143 | <blockquote><pre> |
| 144 | 144 | POST /fossil/xfer HTTP/1.0 |
| 145 | 145 | Host: fossil-scm.hwaci.com:80 |
| 146 | 146 | Content-Type: application/x-fossil |
| @@ -147,19 +147,19 @@ | ||
| 147 | 147 | Content-Length: 4216 |
| 148 | 148 | |
| 149 | 149 | <i>content...</i> |
| 150 | 150 | </pre></blockquote> |
| 151 | 151 | |
| 152 | -<p>In the example above, the pathname given after the POST keyword | |
| 152 | +In the example above, the pathname given after the POST keyword | |
| 153 | 153 | on the first line is a copy of the URL pathname. The Host: parameter |
| 154 | 154 | is also taken from the URL. The content type is always either |
| 155 | 155 | "application/x-fossil" or "application/x-fossil-debug". The "x-fossil" |
| 156 | 156 | content type is the default. The only difference is that "x-fossil" |
| 157 | 157 | content is compressed using zlib whereas "x-fossil-debug" is sent |
| 158 | -uncompressed.</p> | |
| 158 | +uncompressed. | |
| 159 | 159 | |
| 160 | -<p>A typical reply from the server might look something like this:</p> | |
| 160 | +A typical reply from the server might look something like this: | |
| 161 | 161 | |
| 162 | 162 | <blockquote><pre> |
| 163 | 163 | HTTP/1.0 200 OK |
| 164 | 164 | Date: Mon, 10 Sep 2007 12:21:01 GMT |
| 165 | 165 | Connection: close |
| @@ -168,160 +168,160 @@ | ||
| 168 | 168 | Content-Length: 265 |
| 169 | 169 | |
| 170 | 170 | <i>content...</i> |
| 171 | 171 | </pre></blockquote> |
| 172 | 172 | |
| 173 | -<p>The content type of the reply is always the same as the content type | |
| 174 | -of the request.</p> | |
| 173 | +The content type of the reply is always the same as the content type | |
| 174 | +of the request. | |
| 175 | 175 | |
| 176 | 176 | <h2>3.0 Fossil Synchronization Content</h2> |
| 177 | 177 | |
| 178 | -<p>A synchronization request between a client and server consists of | |
| 178 | +A synchronization request between a client and server consists of | |
| 179 | 179 | one or more HTTP requests as described in the previous section. This |
| 180 | -section details the "x-fossil" content type.</p> | |
| 180 | +section details the "x-fossil" content type. | |
| 181 | 181 | |
| 182 | 182 | <h3>3.1 Line-oriented Format</h3> |
| 183 | 183 | |
| 184 | -<p>The x-fossil content type consists of zero or more "cards". Cards | |
| 184 | +The x-fossil content type consists of zero or more "cards". Cards | |
| 185 | 185 | are separated by the newline character ("\n"). Leading and trailing |
| 186 | -whitespace on a card is ignored. Blank cards are ignored.</p> | |
| 186 | +whitespace on a card is ignored. Blank cards are ignored. | |
| 187 | 187 | |
| 188 | -<p>Each card is divided into zero or more space separated tokens. | |
| 188 | +Each card is divided into zero or more space separated tokens. | |
| 189 | 189 | The first token on each card is the operator. Subsequent tokens |
| 190 | 190 | are arguments. The set of operators understood by servers is slightly |
| 191 | 191 | different from the operators understood by clients, though the two |
| 192 | -are very similar.</p> | |
| 192 | +are very similar. | |
| 193 | 193 | |
| 194 | 194 | <h3>3.2 Login Cards</h3> |
| 195 | 195 | |
| 196 | -<p>Every message from client to server begins with one or more login | |
| 197 | -cards. Each login card has the following format:</p> | |
| 196 | +Every message from client to server begins with one or more login | |
| 197 | +cards. Each login card has the following format: | |
| 198 | 198 | |
| 199 | 199 | <blockquote> |
| 200 | 200 | <b>login</b> <i>userid nonce signature</i> |
| 201 | 201 | </blockquote> |
| 202 | 202 | |
| 203 | -<p>The userid is the name of the user that is requesting service | |
| 203 | +The userid is the name of the user that is requesting service | |
| 204 | 204 | from the server. The nonce is the SHA1 hash of the remainder of |
| 205 | 205 | the message - all text that follows the newline character that |
| 206 | 206 | terminates the login card. The signature is the SHA1 hash of |
| 207 | -the concatenation of the nonce and the users password.</p> | |
| 207 | +the concatenation of the nonce and the users password. | |
| 208 | 208 | |
| 209 | -<p>For each login card, the server looks up the user and verifies | |
| 209 | +For each login card, the server looks up the user and verifies | |
| 210 | 210 | that the nonce matches the SHA1 hash of the remainder of the |
| 211 | 211 | message. It then checks the signature hash to make sure the |
| 212 | 212 | signature matches. If everything |
| 213 | 213 | checks out, then the client is granted all privileges of the |
| 214 | -specified user.</p> | |
| 214 | +specified user. | |
| 215 | 215 | |
| 216 | -<p>Privileges are cumulative. There can be multiple successful | |
| 216 | +Privileges are cumulative. There can be multiple successful | |
| 217 | 217 | login cards. The session privileges are the bit-wise OR of the |
| 218 | -privileges of each individual login.</p> | |
| 218 | +privileges of each individual login. | |
| 219 | 219 | |
| 220 | 220 | <h3>3.3 File Cards</h3> |
| 221 | 221 | |
| 222 | -<p>Artifacts are transferred using either "file" cards, or "cfile" | |
| 222 | +Artifacts are transferred using either "file" cards, or "cfile" | |
| 223 | 223 | or "uvfile" cards. |
| 224 | 224 | The name "file" card comes from the fact that most artifacts correspond to |
| 225 | 225 | files that are under version control. |
| 226 | 226 | The "cfile" name is an abbreviation for "compressed file". |
| 227 | 227 | The "uvfile" name is an abbreviation for "unversioned file". |
| 228 | -</p> | |
| 228 | + | |
| 229 | 229 | |
| 230 | 230 | <h4>3.3.1 Ordinary File Cards</h4> |
| 231 | 231 | |
| 232 | -<p>For sync protocols, artifacts are transferred using "file" | |
| 232 | +For sync protocols, artifacts are transferred using "file" | |
| 233 | 233 | cards. File cards come in two different formats depending |
| 234 | 234 | on whether the artifact is sent directly or as a delta from some |
| 235 | -other artifact.</p> | |
| 235 | +other artifact. | |
| 236 | 236 | |
| 237 | 237 | <blockquote> |
| 238 | 238 | <b>file</b> <i>artifact-id size</i> <b>\n</b> <i>content</i><br> |
| 239 | 239 | <b>file</b> <i>artifact-id delta-artifact-id size</i> <b>\n</b> <i>content</i> |
| 240 | 240 | </blockquote> |
| 241 | 241 | |
| 242 | -<p>File cards are followed by in-line "payload" data. | |
| 242 | +File cards are followed by in-line "payload" data. | |
| 243 | 243 | The content of the artifact |
| 244 | 244 | or the artifact delta is the first <i>size</i> bytes of the |
| 245 | 245 | x-fossil content that immediately follow the newline that |
| 246 | 246 | terminates the file card. |
| 247 | -</p> | |
| 248 | 247 | |
| 249 | -<p>The first argument of a file card is the ID of the artifact that | |
| 248 | + | |
| 249 | +The first argument of a file card is the ID of the artifact that | |
| 250 | 250 | is being transferred. The artifact ID is the lower-case hexadecimal |
| 251 | 251 | representation of the name hash for the artifact. |
| 252 | 252 | The last argument of the file card is the number of bytes of |
| 253 | 253 | payload that immediately follow the file card. If the file |
| 254 | 254 | card has only two arguments, that means the payload is the |
| 255 | 255 | complete content of the artifact. If the file card has three |
| 256 | 256 | arguments, then the payload is a delta and second argument is |
| 257 | -the ID of another artifact that is the source of the delta.</p> | |
| 257 | +the ID of another artifact that is the source of the delta. | |
| 258 | 258 | |
| 259 | -<p>File cards are sent in both directions: client to server and | |
| 259 | +File cards are sent in both directions: client to server and | |
| 260 | 260 | server to client. A delta might be sent before the source of |
| 261 | 261 | the delta, so both client and server should remember deltas |
| 262 | -and be able to apply them when their source arrives.</p> | |
| 262 | +and be able to apply them when their source arrives. | |
| 263 | 263 | |
| 264 | 264 | <h4>3.3.2 Compressed File Cards</h4> |
| 265 | 265 | |
| 266 | -<p>A client that sends a clone protocol version "3" or greater will | |
| 266 | +A client that sends a clone protocol version "3" or greater will | |
| 267 | 267 | receive artifacts as "cfile" cards while cloning. This card was |
| 268 | 268 | introduced to improve the speed of the transfer of content by sending the |
| 269 | -compressed artifact directly from the server database to the client.</p> | |
| 269 | +compressed artifact directly from the server database to the client. | |
| 270 | 270 | |
| 271 | -<p>Compressed File cards are similar to File cards, sharing the same | |
| 271 | +Compressed File cards are similar to File cards, sharing the same | |
| 272 | 272 | in-line "payload" data characteristics and also the same treatment of |
| 273 | 273 | direct content or delta content. Cfile cards come in two different formats |
| 274 | 274 | depending on whether the artifact is sent directly or as a delta from |
| 275 | -some other artifact.</p> | |
| 275 | +some other artifact. | |
| 276 | 276 | |
| 277 | 277 | <blockquote> |
| 278 | 278 | <b>cfile</b> <i>artifact-id usize csize</i> <b>\n</b> <i>content</i><br> |
| 279 | 279 | <b>cfile</b> <i>artifact-id delta-artifact-id usize csize</i> <b>\n</b> <i>content</i><br> |
| 280 | 280 | </blockquote> |
| 281 | 281 | |
| 282 | -<p>The first argument of the cfile card is the ID of the artifact that | |
| 282 | +The first argument of the cfile card is the ID of the artifact that | |
| 283 | 283 | is being transferred. The artifact ID is the lower-case hexadecimal |
| 284 | 284 | representation of the name hash for the artifact. The second argument of |
| 285 | 285 | the cfile card is the original size in bytes of the artifact. The last |
| 286 | 286 | argument of the cfile card is the number of compressed bytes of payload |
| 287 | 287 | that immediately follow the cfile card. If the cfile card has only |
| 288 | 288 | three arguments, that means the payload is the complete content of the |
| 289 | 289 | artifact. If the cfile card has four arguments, then the payload is a |
| 290 | 290 | delta and the second argument is the ID of another artifact that is the |
| 291 | 291 | source of the delta and the third argument is the original size of the |
| 292 | -delta artifact.</p> | |
| 292 | +delta artifact. | |
| 293 | 293 | |
| 294 | -<p>Unlike file cards, cfile cards are only sent in one direction during a | |
| 295 | -clone from server to client for clone protocol version "3" or greater.</p> | |
| 294 | +Unlike file cards, cfile cards are only sent in one direction during a | |
| 295 | +clone from server to client for clone protocol version "3" or greater. | |
| 296 | 296 | |
| 297 | 297 | <h4>3.3.3 Private artifacts</h4> |
| 298 | 298 | |
| 299 | -<p>"Private" content consist of artifacts that are not normally synced. | |
| 299 | +"Private" content consist of artifacts that are not normally synced. | |
| 300 | 300 | However, private content will be synced when the |
| 301 | 301 | the [/help?cmd=sync|fossil sync] command includes the "--private" option. |
| 302 | -</p> | |
| 303 | 302 | |
| 304 | -<p>Private content is marked by a "private" card: | |
| 303 | + | |
| 304 | +Private content is marked by a "private" card: | |
| 305 | 305 | |
| 306 | 306 | <blockquote> |
| 307 | 307 | <b>private</b> |
| 308 | 308 | </blockquote> |
| 309 | 309 | |
| 310 | -<p>The private card has no arguments and must directly precede a | |
| 311 | -file card that contains the private content.</p> | |
| 310 | +The private card has no arguments and must directly precede a | |
| 311 | +file card that contains the private content. | |
| 312 | 312 | |
| 313 | 313 | <h4>3.3.4 Unversioned File Cards</h4> |
| 314 | 314 | |
| 315 | -<p>Unversioned content is sent in both directions (client to server and | |
| 315 | +Unversioned content is sent in both directions (client to server and | |
| 316 | 316 | server to client) using "uvfile" cards in the following format: |
| 317 | 317 | |
| 318 | 318 | <blockquote> |
| 319 | 319 | <b>uvfile</b> <i>name mtime hash size flags</i> <b>\n</b> <i>content</i> |
| 320 | 320 | </blockquote> |
| 321 | 321 | |
| 322 | -<p>The <i>name</i> field is the name of the unversioned file. The | |
| 322 | +The <i>name</i> field is the name of the unversioned file. The | |
| 323 | 323 | <i>mtime</i> is the last modification time of the file in seconds |
| 324 | 324 | since 1970. The <i>hash</i> field is the hash of the content |
| 325 | 325 | for the unversioned file, or "<b>-</b>" for deleted content. |
| 326 | 326 | The <i>size</i> field is the (uncompressed) size of the content |
| 327 | 327 | in bytes. The <i>flags</i> field is an integer which is interpreted |
| @@ -329,234 +329,234 @@ | ||
| 329 | 329 | the <i>content</i> is to be omitted. The content might be omitted if |
| 330 | 330 | it is too large to transmit, or if the sender merely wants to update the |
| 331 | 331 | modification time of the file without changing the files content. |
| 332 | 332 | The <i>content</i> is the (uncompressed) content of the file. |
| 333 | 333 | |
| 334 | -<p>The receiver should only accept the uvfile card if the hash and | |
| 334 | +The receiver should only accept the uvfile card if the hash and | |
| 335 | 335 | size match the content and if the mtime is newer than any existing |
| 336 | 336 | instance of the same file held by the receiver. The sender will not |
| 337 | 337 | normally transmit a uvfile card unless all these constraints are true, |
| 338 | 338 | but the receiver should double-check. |
| 339 | 339 | |
| 340 | -<p>A server should only accept uvfile cards if the login user has | |
| 340 | +A server should only accept uvfile cards if the login user has | |
| 341 | 341 | the "y" write-unversioned permission. |
| 342 | 342 | |
| 343 | -<p>Servers send uvfile cards in response to uvgimme cards received from | |
| 343 | +Servers send uvfile cards in response to uvgimme cards received from | |
| 344 | 344 | the client. Clients send uvfile cards when they determine that the server |
| 345 | 345 | needs the content based on uvigot cards previously received from the server. |
| 346 | 346 | |
| 347 | 347 | <h3>3.4 Push and Pull Cards</h3> |
| 348 | 348 | |
| 349 | -<p>Among the first cards in a client-to-server message are | |
| 349 | +Among the first cards in a client-to-server message are | |
| 350 | 350 | the push and pull cards. The push card tells the server that |
| 351 | 351 | the client is pushing content. The pull card tells the server |
| 352 | 352 | that the client wants to pull content. In the event of a sync, |
| 353 | -both cards are sent. The format is as follows:</p> | |
| 353 | +both cards are sent. The format is as follows: | |
| 354 | 354 | |
| 355 | 355 | <blockquote> |
| 356 | 356 | <b>push</b> <i>servercode projectcode</i><br> |
| 357 | 357 | <b>pull</b> <i>servercode projectcode</i> |
| 358 | 358 | </blockquote> |
| 359 | 359 | |
| 360 | -<p>The <i>servercode</i> argument is the repository ID for the | |
| 360 | +The <i>servercode</i> argument is the repository ID for the | |
| 361 | 361 | client. The <i>projectcode</i> is the identifier |
| 362 | 362 | of the software project that the client repository contains. |
| 363 | 363 | The projectcode for the client and server must match in order |
| 364 | -for the transaction to proceed.</p> | |
| 364 | +for the transaction to proceed. | |
| 365 | 365 | |
| 366 | -<p>The server will also send a push card back to the client | |
| 366 | +The server will also send a push card back to the client | |
| 367 | 367 | during a clone. This is how the client determines what project |
| 368 | -code to put in the new repository it is constructing.</p> | |
| 368 | +code to put in the new repository it is constructing. | |
| 369 | 369 | |
| 370 | -<p>The <i>servercode</i> argument is currently unused. | |
| 370 | +The <i>servercode</i> argument is currently unused. | |
| 371 | 371 | |
| 372 | 372 | <h3>3.5 Clone Cards</h3> |
| 373 | 373 | |
| 374 | -<p>A clone card works like a pull card in that it is sent from | |
| 374 | +A clone card works like a pull card in that it is sent from | |
| 375 | 375 | client to server in order to tell the server that the client |
| 376 | 376 | wants to pull content. The clone card comes in two formats. Older |
| 377 | 377 | clients use the no-argument format and newer clients use the |
| 378 | -two-argument format.</p> | |
| 378 | +two-argument format. | |
| 379 | 379 | |
| 380 | 380 | <blockquote> |
| 381 | 381 | <b>clone</b><br> |
| 382 | 382 | <b>clone</b> <i>protocol-version sequence-number</i> |
| 383 | 383 | </blockquote> |
| 384 | 384 | |
| 385 | 385 | <h4>3.5.1 Protocol 3</h4> |
| 386 | 386 | |
| 387 | -<p>The latest clients send a two-argument clone message with a | |
| 387 | +The latest clients send a two-argument clone message with a | |
| 388 | 388 | protocol version of "3". (Future versions of Fossil might use larger |
| 389 | 389 | protocol version numbers.) Version "3" of the protocol enhanced version |
| 390 | 390 | "2" by introducing the "cfile" card which is intended to speed up clone |
| 391 | 391 | operations. Instead of sending "file" cards, the server will send "cfile" |
| 392 | -cards</p> | |
| 392 | +cards | |
| 393 | 393 | |
| 394 | 394 | <h4>3.5.2 Protocol 2</h4> |
| 395 | 395 | |
| 396 | -<p>The sequence-number sent is the number | |
| 396 | +The sequence-number sent is the number | |
| 397 | 397 | of artifacts received so far. For the first clone message, the |
| 398 | 398 | sequence number is 0. The server will respond by sending file |
| 399 | 399 | cards for some number of artifacts up to the maximum message size. |
| 400 | 400 | |
| 401 | -<p>The server will also send a single "clone_seqno" card to the client | |
| 401 | +The server will also send a single "clone_seqno" card to the client | |
| 402 | 402 | so that the client can know where the server left off. |
| 403 | 403 | |
| 404 | 404 | <blockquote> |
| 405 | 405 | <b>clone_seqno</b> <i>sequence-number</i> |
| 406 | 406 | </blockquote> |
| 407 | 407 | |
| 408 | -<p>The clone message in subsequent HTTP requests for the same clone | |
| 408 | +The clone message in subsequent HTTP requests for the same clone | |
| 409 | 409 | operation will use the sequence-number from the |
| 410 | -clone_seqno of the previous reply.</p> | |
| 410 | +clone_seqno of the previous reply. | |
| 411 | 411 | |
| 412 | -<p>In response to an initial clone message, the server also sends the client | |
| 412 | +In response to an initial clone message, the server also sends the client | |
| 413 | 413 | a push message so that the client can discover the projectcode for |
| 414 | -this project.</p> | |
| 414 | +this project. | |
| 415 | 415 | |
| 416 | 416 | <h4>3.5.3 Legacy Protocol</h4> |
| 417 | 417 | |
| 418 | -<p>Older clients send a clone card with no argument. The server responds | |
| 418 | +Older clients send a clone card with no argument. The server responds | |
| 419 | 419 | to a blank clone card by sending an "igot" card for every artifact in the |
| 420 | 420 | repository. The client will then issue "gimme" cards to pull down all the |
| 421 | 421 | content it needs. |
| 422 | 422 | |
| 423 | -<p>The legacy protocol works well for smaller repositories (50MB with 50,000 | |
| 423 | +The legacy protocol works well for smaller repositories (50MB with 50,000 | |
| 424 | 424 | artifacts) but is too slow and unwieldy for larger repositories. |
| 425 | 425 | The version 2 protocol is an effort to improve performance. Further |
| 426 | 426 | performance improvements with higher-numbered clone protocols are |
| 427 | 427 | possible in future versions of Fossil. |
| 428 | 428 | |
| 429 | 429 | <h3>3.6 Igot Cards</h3> |
| 430 | 430 | |
| 431 | -<p>An igot card can be sent from either client to server or from | |
| 431 | +An igot card can be sent from either client to server or from | |
| 432 | 432 | server to client in order to indicate that the sender holds a copy |
| 433 | -of a particular artifact. The format is:</p> | |
| 433 | +of a particular artifact. The format is: | |
| 434 | 434 | |
| 435 | 435 | <blockquote> |
| 436 | 436 | <b>igot</b> <i>artifact-id</i> ?<i>flag</i>? |
| 437 | 437 | </blockquote> |
| 438 | 438 | |
| 439 | -<p>The first argument of the igot card is the ID of the artifact that | |
| 439 | +The first argument of the igot card is the ID of the artifact that | |
| 440 | 440 | the sender possesses. |
| 441 | 441 | The receiver of an igot card will typically check to see if |
| 442 | 442 | it also holds the same artifact and if not it will request the artifact |
| 443 | -using a gimme card in either the reply or in the next message.</p> | |
| 443 | +using a gimme card in either the reply or in the next message. | |
| 444 | 444 | |
| 445 | -<p>If the second argument exists and is "1", then the artifact | |
| 445 | +If the second argument exists and is "1", then the artifact | |
| 446 | 446 | identified by the first argument is private on the sender and should |
| 447 | 447 | be ignored unless a "--private" [/help?cmd=sync|sync] is occurring. |
| 448 | 448 | |
| 449 | -<p>The name "igot" comes from the English slang expression "I got" meaning | |
| 449 | +The name "igot" comes from the English slang expression "I got" meaning | |
| 450 | 450 | "I have". |
| 451 | 451 | |
| 452 | 452 | <h4>3.6.1 Unversioned Igot Cards</h4> |
| 453 | 453 | |
| 454 | -<p>Zero or more "uvigot" cards are sent from server to client when | |
| 454 | +Zero or more "uvigot" cards are sent from server to client when | |
| 455 | 455 | synchronizing unversioned content. The format of a uvigot card is |
| 456 | 456 | as follows: |
| 457 | 457 | |
| 458 | 458 | <blockquote> |
| 459 | 459 | <b>uvigot</b> <i>name mtime hash size</i> |
| 460 | 460 | </blockquote> |
| 461 | 461 | |
| 462 | -<p>The <i>name</i> argument is the name of an unversioned file. | |
| 462 | +The <i>name</i> argument is the name of an unversioned file. | |
| 463 | 463 | The <i>mtime</i> is the last modification time of the unversioned file |
| 464 | 464 | in seconds since 1970. |
| 465 | 465 | The <i>hash</i> is the SHA1 or SHA3-256 hash of the unversioned file |
| 466 | 466 | content, or "<b>-</b>" if the file has been deleted. |
| 467 | 467 | The <i>size</i> is the uncompressed size of the file in bytes. |
| 468 | 468 | |
| 469 | -<p>When the server sees a "pragma uv-hash" card for which the hash | |
| 469 | +When the server sees a "pragma uv-hash" card for which the hash | |
| 470 | 470 | does not match, it sends uvigot cards for every unversioned file that it |
| 471 | 471 | holds. The client will use this information to figure out which |
| 472 | 472 | unversioned files need to be synchronized. |
| 473 | 473 | The server might also send a uvigot card when it receives a uvgimme card |
| 474 | 474 | but its reply message size is already oversized and hence unable to hold |
| 475 | 475 | the usual uvfile reply. |
| 476 | 476 | |
| 477 | -<p>When a client receives a "uvigot" card, it checks to see if the | |
| 477 | +When a client receives a "uvigot" card, it checks to see if the | |
| 478 | 478 | file needs to be transferred from client to server or from server to client. |
| 479 | 479 | If a client-to-server transmission is needed, the client schedules that |
| 480 | 480 | transfer to occur on a subsequent HTTP request. If a server-to-client |
| 481 | 481 | transfer is needed, then the client sends a "uvgimme" card back to the |
| 482 | 482 | server to request the file content. |
| 483 | 483 | |
| 484 | 484 | <h3>3.7 Gimme Cards</h3> |
| 485 | 485 | |
| 486 | -<p>A gimme card is sent from either client to server or from server | |
| 486 | +A gimme card is sent from either client to server or from server | |
| 487 | 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:</p> | |
| 488 | +artifact back to the sender. The format of a gimme card is this: | |
| 489 | 489 | |
| 490 | 490 | <blockquote> |
| 491 | 491 | <b>gimme</b> <i>artifact-id</i> |
| 492 | 492 | </blockquote> |
| 493 | 493 | |
| 494 | -<p>The argument to the gimme card is the ID of the artifact that | |
| 494 | +The argument to the gimme card is the ID of the artifact that | |
| 495 | 495 | the sender wants. The receiver will typically respond to a |
| 496 | 496 | gimme card by sending a file card in its reply or in the next |
| 497 | -message.</p> | |
| 497 | +message. | |
| 498 | 498 | |
| 499 | -<p>The "gimme" name means "give me". The imperative "give me" is | |
| 499 | +The "gimme" name means "give me". The imperative "give me" is | |
| 500 | 500 | pronounced as if it were a single word "gimme" in some dialects of |
| 501 | 501 | English (including the dialect spoken by the original author of Fossil). |
| 502 | 502 | |
| 503 | 503 | <h4>3.7.1 Unversioned Gimme Cards</h4> |
| 504 | 504 | |
| 505 | -<p>Sync synchronizing unversioned content, the client may send "uvgimme" | |
| 505 | +Sync synchronizing unversioned content, the client may send "uvgimme" | |
| 506 | 506 | cards to the server. A uvgimme card requests that the server send |
| 507 | 507 | unversioned content to the client. The format of a uvgimme card is |
| 508 | 508 | as follows: |
| 509 | 509 | |
| 510 | 510 | <blockquote> |
| 511 | 511 | <b>uvgimme</b> <i>name</i> |
| 512 | 512 | </blockquote> |
| 513 | 513 | |
| 514 | -<p>The <i>name</i> is the name of the unversioned file found on the | |
| 514 | +The <i>name</i> is the name of the unversioned file found on the | |
| 515 | 515 | server that the client would like to have. When a server sees a |
| 516 | 516 | uvgimme card, it normally responses with a uvfile card, though it might |
| 517 | 517 | also send another uvigot card if the HTTP reply is already oversized. |
| 518 | 518 | |
| 519 | 519 | <h3>3.8 Cookie Cards</h3> |
| 520 | 520 | |
| 521 | -<p>A cookie card can be used by a server to record a small amount | |
| 521 | +A cookie card can be used by a server to record a small amount | |
| 522 | 522 | of state information on a client. The server sends a cookie to the |
| 523 | 523 | client. The client sends the same cookie back to the server on |
| 524 | 524 | its next request. The cookie card has a single argument which |
| 525 | -is its payload.</p> | |
| 525 | +is its payload. | |
| 526 | 526 | |
| 527 | 527 | <blockquote> |
| 528 | 528 | <b>cookie</b> <i>payload</i> |
| 529 | 529 | </blockquote> |
| 530 | 530 | |
| 531 | -<p>The client is not required to return the cookie to the server on | |
| 531 | +The client is not required to return the cookie to the server on | |
| 532 | 532 | its next request. Or the client might send a cookie from a different |
| 533 | 533 | server on the next request. So the server must not depend on the |
| 534 | 534 | cookie and the server must structure the cookie payload in such |
| 535 | 535 | a way that it can tell if the cookie it sees is its own cookie or |
| 536 | 536 | a cookie from another server. (Typically the server will embed |
| 537 | -its servercode as part of the cookie.)</p> | |
| 537 | +its servercode as part of the cookie.) | |
| 538 | 538 | |
| 539 | 539 | <h3>3.9 Request-Configuration Cards</h3> |
| 540 | 540 | |
| 541 | -<p>A request-configuration or "reqconfig" card is sent from client to | |
| 541 | +A request-configuration or "reqconfig" card is sent from client to | |
| 542 | 542 | server in order to request that the server send back "configuration" |
| 543 | 543 | data. "Configuration" data is information about users or website |
| 544 | 544 | appearance or other administrative details which are not part of the |
| 545 | 545 | persistent and versioned state of the project. For example, the "name" |
| 546 | 546 | of the project, the default Cascading Style Sheet (CSS) for the web-interface, |
| 547 | 547 | and the project logo displayed on the web-interface are all configuration |
| 548 | 548 | data elements. |
| 549 | 549 | |
| 550 | -<p>The reqconfig card is normally sent in response to the | |
| 550 | +The reqconfig card is normally sent in response to the | |
| 551 | 551 | "fossil configuration pull" command. The format is as follows: |
| 552 | 552 | |
| 553 | 553 | <blockquote> |
| 554 | 554 | <b>reqconfig</b> <i>configuration-name</i> |
| 555 | 555 | </blockquote> |
| 556 | 556 | |
| 557 | -<p>As of 2018-06-04, the configuration-name must be one of the | |
| 557 | +As of 2018-06-04, the configuration-name must be one of the | |
| 558 | 558 | following values: |
| 559 | 559 | |
| 560 | 560 | <table border=0 align="center"> |
| 561 | 561 | <tr><td valign="top"> |
| 562 | 562 | <ul> |
| @@ -622,84 +622,81 @@ | ||
| 622 | 622 | <li> @concealed |
| 623 | 623 | <li> @shun |
| 624 | 624 | </ul></td></tr> |
| 625 | 625 | </table> |
| 626 | 626 | |
| 627 | -<p>New configuration-names are likely to be added in future releases of | |
| 627 | +New configuration-names are likely to be added in future releases of | |
| 628 | 628 | Fossil. If the server receives a configuration-name that it does not |
| 629 | 629 | understand, the entire reqconfig card is silently ignored. The reqconfig |
| 630 | 630 | card might also be ignored if the user lacks sufficient privilege to |
| 631 | 631 | access the requested information. |
| 632 | 632 | |
| 633 | -<p>The configuration-names that begin with an alphabetic character refer | |
| 633 | +The configuration-names that begin with an alphabetic character refer | |
| 634 | 634 | to values in the "config" table of the server database. For example, |
| 635 | 635 | the "logo-image" configuration item refers to the project logo image |
| 636 | 636 | that is configured on the Admin page of the [./webui.wiki | web-interface]. |
| 637 | 637 | The value of the configuration item is returned to the client using a |
| 638 | 638 | "config" card. |
| 639 | 639 | |
| 640 | -<p>If the configuration-name begins with "@", that refers to a class of | |
| 640 | +If the configuration-name begins with "@", that refers to a class of | |
| 641 | 641 | values instead of a single value. The content of these configuration items |
| 642 | 642 | is returned in a "config" card that contains pure SQL text that is |
| 643 | 643 | intended to be evaluated by the client. |
| 644 | 644 | |
| 645 | -<p>The @user and @concealed configuration items contain sensitive information | |
| 645 | +The @user and @concealed configuration items contain sensitive information | |
| 646 | 646 | and are ignored for clients without sufficient privilege. |
| 647 | 647 | |
| 648 | 648 | <h3>3.10 Configuration Cards</h3> |
| 649 | 649 | |
| 650 | -<p>A "config" card is used to send configuration information from client | |
| 650 | +A "config" card is used to send configuration information from client | |
| 651 | 651 | to server (in response to a "fossil configuration push" command) or |
| 652 | 652 | from server to client (in response to a "fossil configuration pull" or |
| 653 | 653 | "fossil clone" command). The format is as follows: |
| 654 | 654 | |
| 655 | 655 | <blockquote> |
| 656 | 656 | <b>config</b> <i>configuration-name size</i> <b>\n</b> <i>content</i> |
| 657 | 657 | </blockquote> |
| 658 | 658 | |
| 659 | -<p>The server will only accept a config card if the user has | |
| 659 | +The server will only accept a config card if the user has | |
| 660 | 660 | "Admin" privilege. A client will only accept a config card if |
| 661 | 661 | it had sent a corresponding reqconfig card in its request. |
| 662 | 662 | |
| 663 | -<p>The content of the configuration item is used to overwrite the | |
| 663 | +The content of the configuration item is used to overwrite the | |
| 664 | 664 | corresponding configuration data in the receiver. |
| 665 | 665 | |
| 666 | 666 | <h3>3.11 Pragma Cards</h3> |
| 667 | 667 | |
| 668 | -<p>The client may try to influence the behavior of the server by | |
| 668 | +The client may try to influence the behavior of the server by | |
| 669 | 669 | issuing a pragma card: |
| 670 | 670 | |
| 671 | 671 | <blockquote> |
| 672 | 672 | <b>pragma</i> <i>name value...</i> |
| 673 | 673 | </blockquote> |
| 674 | 674 | |
| 675 | -<p>The "pragma" card has at least one argument which is the pragma name. | |
| 675 | +The "pragma" card has at least one argument which is the pragma name. | |
| 676 | 676 | The pragma name defines what the pragma does. |
| 677 | 677 | A pragma might have zero or more "value" arguments |
| 678 | 678 | depending on the pragma name. |
| 679 | 679 | |
| 680 | -<p>New pragma names may be added to the protocol from time to time | |
| 680 | +New pragma names may be added to the protocol from time to time | |
| 681 | 681 | in order to enhance the capabilities of Fossil. |
| 682 | 682 | Unknown pragmas are silently ignored, for backwards compatibility. |
| 683 | 683 | |
| 684 | -<p>The following are the known pragma names as of 2019-06-30: | |
| 684 | +The following are the known pragma names as of 2019-06-30: | |
| 685 | 685 | |
| 686 | 686 | <ol> |
| 687 | -<li><p><b>send-private</b> | |
| 688 | -<p>The send-private pragma instructs the server to send all of its | |
| 687 | +<li><b>send-private</b> The send-private pragma instructs the server to send all of its | |
| 689 | 688 | private artifacts to the client. The server will only obey this |
| 690 | 689 | request if the user has the "x" or "Private" privilege. |
| 691 | 690 | |
| 692 | -<li><p><b>send-catalog</b> | |
| 693 | -<p>The send-catalog pragma instructs the server to transmit igot | |
| 691 | +<li><b>send-catalog</b> The send-catalog pragma instructs the server to transmit igot | |
| 694 | 692 | cards for every known artifact. This can help the client and server |
| 695 | 693 | to get back in synchronization after a prior protocol error. The |
| 696 | 694 | "--verily" option to the [/help?cmd=sync|fossil sync] command causes |
| 697 | -the send-catalog pragma to be transmitted.</p> | |
| 695 | +the send-catalog pragma to be transmitted. | |
| 698 | 696 | |
| 699 | -<li><p><b>uv-hash</b> <i>HASH</i> | |
| 700 | -<p>The uv-hash pragma is sent from client to server to provoke a | |
| 697 | +<li><b>uv-hash</b> <i>HASH</i> The uv-hash pragma is sent from client to server to provoke a | |
| 701 | 698 | synchronization of unversioned content. The <i>HASH</i> is a SHA1 |
| 702 | 699 | hash of the names, modification times, and individual hashes of all |
| 703 | 700 | unversioned files on the client. If the unversioned content hash |
| 704 | 701 | from the client does not match the unversioned content hash on the |
| 705 | 702 | server, then the server will reply with either a "pragma uv-push-ok" |
| @@ -707,157 +704,151 @@ | ||
| 707 | 704 | each unversioned file currently held on the server. The collection |
| 708 | 705 | of "uvigot" cards sent in response to a "uv-hash" pragma is called |
| 709 | 706 | the "unversioned catalog". The client will used the unversioned |
| 710 | 707 | catalog to figure out which files (if any) need to be synchronized |
| 711 | 708 | between client and server and send appropriate "uvfile" or "uvgimme" |
| 712 | -cards on the next HTTP request.</p> | |
| 709 | +cards on the next HTTP request. | |
| 713 | 710 | |
| 714 | -<p>If a client sends a uv-hash pragma and does not receive back | |
| 711 | +If a client sends a uv-hash pragma and does not receive back | |
| 715 | 712 | either a uv-pull-only or uv-push-ok pragma, that means that the |
| 716 | 713 | content on the server exactly matches the content on the client and |
| 717 | 714 | no further synchronization is required. |
| 718 | 715 | |
| 719 | -<li><p><b>uv-pull-only</b></i> | |
| 720 | -<p>A server sends the uv-pull-only pragma to the client in response | |
| 716 | +<li><b>uv-pull-only</b></i> A server sends the uv-pull-only pragma to the client in response | |
| 721 | 717 | to a uv-hash pragma with a mismatched content hash argument. This |
| 722 | 718 | pragma indicates that there are differences in unversioned content |
| 723 | 719 | between the client and server but that content can only be transferred |
| 724 | 720 | from server to client. The server is unwilling to accept content from |
| 725 | 721 | the client because the client login lacks the "write-unversioned" |
| 726 | -permission.</p> | |
| 722 | +permission. | |
| 727 | 723 | |
| 728 | -<li><p><b>uv-push-ok</b></i> | |
| 729 | -<p>A server sends the uv-push-ok pragma to the client in response | |
| 724 | +<li><b>uv-push-ok</b></i> A server sends the uv-push-ok pragma to the client in response | |
| 730 | 725 | to a uv-hash pragma with a mismatched content hash argument. This |
| 731 | 726 | pragma indicates that there are differences in unversioned content |
| 732 | 727 | between the client and server and that content can be transferred |
| 733 | 728 | in either direction. The server is willing to accept content from |
| 734 | 729 | the client because the client login has the "write-unversioned" |
| 735 | -permission.</p> | |
| 730 | +permission. | |
| 736 | 731 | |
| 737 | -<li><p><b>ci-lock</b> <i>CHECKIN-HASH CLIENT-ID</i></p> | |
| 738 | -<p>A client sends the "ci-lock" pragma to the server to indicate | |
| 732 | +<li><b>ci-lock</b> <i>CHECKIN-HASH CLIENT-ID</i> A client sends the "ci-lock" pragma to the server to indicate | |
| 739 | 733 | that it is about to add a new check-in as a child of the |
| 740 | 734 | CHECKIN-HASH check-in and on the same branch as CHECKIN-HASH. |
| 741 | 735 | If some other client has already indicated that it was also |
| 742 | 736 | trying to commit against CHECKIN-HASH, that indicates that a |
| 743 | 737 | fork is about to occur, and the server will reply with |
| 744 | 738 | a "ci-lock-fail" pragma (see below). Check-in locks |
| 745 | 739 | automatically expire when the check-in actually occurs, or |
| 746 | 740 | after a timeout (currently one minute but subject to change). |
| 747 | 741 | |
| 748 | -<li><p><b>ci-lock-fail</b> <i>LOGIN MTIME</i></p> | |
| 749 | -<p>When a server receives two or more "ci-lock" pragma messages | |
| 742 | +<li><b>ci-lock-fail</b> <i>LOGIN MTIME</i> When a server receives two or more "ci-lock" pragma messages | |
| 750 | 743 | for the same check-in but from different clients, the second a |
| 751 | 744 | subsequent ci-lock will provoke a ci-lock-fail pragma in the |
| 752 | 745 | reply to let the client know that it if continues with the |
| 753 | 746 | check-in it will likely generate a fork. The LOGIN and MTIME |
| 754 | 747 | arguments are intended to provide information to the client to |
| 755 | 748 | help it generate a more useful error message. |
| 756 | -</p> | |
| 757 | 749 | |
| 758 | -<li><p><b>ci-unlock</b> <i>CLIENT-ID</i></p> | |
| 759 | -<p>A client sends the "ci-unlock" pragma to the server after | |
| 750 | +<li><b>ci-unlock</b> <i>CLIENT-ID</i> A client sends the "ci-unlock" pragma to the server after | |
| 760 | 751 | a successful commit. This instructs the server to release |
| 761 | 752 | any lock on any check-in previously held by that client. |
| 762 | 753 | The ci-unlock pragma helps to avoid false-positive lock warnings |
| 763 | 754 | that might arise if a check-in is aborted and then restarted |
| 764 | 755 | on a branch. |
| 765 | 756 | </ol> |
| 766 | 757 | |
| 767 | 758 | <h3>3.12 Comment Cards</h3> |
| 768 | 759 | |
| 769 | -<p>Any card that begins with "#" (ASCII 0x23) is a comment card and | |
| 770 | -is silently ignored.</p> | |
| 760 | +Any card that begins with "#" (ASCII 0x23) is a comment card and | |
| 761 | +is silently ignored. | |
| 771 | 762 | |
| 772 | 763 | <h3>3.13 Message and Error Cards</h3> |
| 773 | 764 | |
| 774 | -<p>If the server discovers anything wrong with a request, it generates | |
| 765 | +If the server discovers anything wrong with a request, it generates | |
| 775 | 766 | an error card in its reply. When the client sees the error card, |
| 776 | 767 | it displays an error message to the user and aborts the sync |
| 777 | -operation. An error card looks like this:</p> | |
| 768 | +operation. An error card looks like this: | |
| 778 | 769 | |
| 779 | 770 | <blockquote> |
| 780 | 771 | <b>error</b> <i>error-message</i> |
| 781 | 772 | </blockquote> |
| 782 | 773 | |
| 783 | -<p>The error message is English text that is encoded in order to | |
| 774 | +The error message is English text that is encoded in order to | |
| 784 | 775 | be a single token. |
| 785 | 776 | A space (ASCII 0x20) is represented as "\s" (ASCII 0x5C, 0x73). A |
| 786 | 777 | newline (ASCII 0x0a) is "\n" (ASCII 0x6C, x6E). A backslash |
| 787 | 778 | (ASCII 0x5C) is represented as two backslashes "\\". Apart from |
| 788 | 779 | space and newline, no other whitespace characters nor any |
| 789 | 780 | unprintable characters are allowed in |
| 790 | -the error message.</p> | |
| 781 | +the error message. | |
| 791 | 782 | |
| 792 | -<p>The server can also send a message card that also prints a | |
| 783 | +The server can also send a message card that also prints a | |
| 793 | 784 | message on the client console, but which is not an error: |
| 794 | 785 | |
| 795 | 786 | <blockquote> |
| 796 | 787 | <b>message</b> <i>message-text</i> |
| 797 | 788 | </blockquote> |
| 798 | 789 | |
| 799 | -<p>The message-text uses the same format as an error message. | |
| 790 | +The message-text uses the same format as an error message. | |
| 800 | 791 | |
| 801 | 792 | <h3>3.14 Unknown Cards</h3> |
| 802 | 793 | |
| 803 | -<p>If either the client or the server sees a card that is not | |
| 804 | -described above, then it generates an error and aborts.</p> | |
| 794 | +If either the client or the server sees a card that is not | |
| 795 | +described above, then it generates an error and aborts. | |
| 805 | 796 | |
| 806 | 797 | <h2>4.0 Phantoms And Clusters</h2> |
| 807 | 798 | |
| 808 | -<p>When a repository knows that an artifact exists and knows the ID of | |
| 799 | +When a repository knows that an artifact exists and knows the ID of | |
| 809 | 800 | that artifact, but it does not know the artifact content, then it stores that |
| 810 | 801 | artifact as a "phantom". A repository will typically create a phantom when |
| 811 | 802 | it receives an igot card for an artifact that it does not hold or when it |
| 812 | 803 | receives a file card that references a delta source that it does not |
| 813 | 804 | hold. When a server is generating its reply or when a client is |
| 814 | 805 | generating a new request, it will usually send gimme cards for every |
| 815 | -phantom that it holds.</p> | |
| 806 | +phantom that it holds. | |
| 816 | 807 | |
| 817 | -<p>A cluster is a special artifact that tells of the existence of other | |
| 808 | +A cluster is a special artifact that tells of the existence of other | |
| 818 | 809 | artifacts. Any artifact in the repository that follows the syntactic rules |
| 819 | -of a cluster is considered a cluster.</p> | |
| 810 | +of a cluster is considered a cluster. | |
| 820 | 811 | |
| 821 | -<p>A cluster is line oriented. Each line of a cluster | |
| 812 | +A cluster is line oriented. Each line of a cluster | |
| 822 | 813 | is a card. The cards are separated by the newline ("\n") character. |
| 823 | 814 | Each card consists of a single character card type, a space, and a |
| 824 | 815 | single argument. No extra whitespace and no trailing or leading |
| 825 | 816 | whitespace is allowed. All cards in the cluster must occur in |
| 826 | -strict lexicographical order.</p> | |
| 817 | +strict lexicographical order. | |
| 827 | 818 | |
| 828 | -<p>A cluster consists of one or more "M" cards followed by a single | |
| 819 | +A cluster consists of one or more "M" cards followed by a single | |
| 829 | 820 | "Z" card. Each M card holds an argument which is an artifact ID for an |
| 830 | 821 | artifact in the repository. The Z card has a single argument which is the |
| 831 | 822 | lower-case hexadecimal representation of the MD5 checksum of all |
| 832 | 823 | preceding M cards up to and included the newline character that |
| 833 | -occurred just before the Z that starts the Z card.</p> | |
| 824 | +occurred just before the Z that starts the Z card. | |
| 834 | 825 | |
| 835 | -<p>Any artifact that does not match the specifications of a cluster | |
| 826 | +Any artifact that does not match the specifications of a cluster | |
| 836 | 827 | exactly is not a cluster. There must be no extra whitespace in |
| 837 | 828 | the artifact. There must be one or more M cards. There must be a |
| 838 | 829 | single Z card with a correct MD5 checksum. And all cards must |
| 839 | -be in strict lexicographical order.</p> | |
| 830 | +be in strict lexicographical order. | |
| 840 | 831 | |
| 841 | 832 | <h3>4.1 The Unclustered Table</h3> |
| 842 | 833 | |
| 843 | -<p>Every repository maintains a table named "<b>unclustered</b>" | |
| 834 | +Every repository maintains a table named "<b>unclustered</b>" | |
| 844 | 835 | which records the identity of every artifact and phantom it holds that is not |
| 845 | 836 | mentioned in a cluster. The entries in the unclustered table can |
| 846 | 837 | be thought of as leaves on a tree of artifacts. Some of the unclustered |
| 847 | 838 | artifacts will be other clusters. Those clusters may contain other clusters, |
| 848 | 839 | which might contain still more clusters, and so forth. Beginning |
| 849 | 840 | with the artifacts in the unclustered table, one can follow the chain |
| 850 | -of clusters to find every artifact in the repository.</p> | |
| 841 | +of clusters to find every artifact in the repository. | |
| 851 | 842 | |
| 852 | 843 | <h2>5.0 Synchronization Strategies</h2> |
| 853 | 844 | |
| 854 | 845 | <h3>5.1 Pull</h3> |
| 855 | 846 | |
| 856 | -<p>A typical pull operation proceeds as shown below. Details | |
| 847 | +A typical pull operation proceeds as shown below. Details | |
| 857 | 848 | of the actual implementation may very slightly but the gist of |
| 858 | -a pull is captured in the following steps:</p> | |
| 849 | +a pull is captured in the following steps: | |
| 859 | 850 | |
| 860 | 851 | <ol> |
| 861 | 852 | <li>The client sends login and pull cards. |
| 862 | 853 | <li>The client sends a cookie card if it has previously received a cookie. |
| 863 | 854 | <li>The client sends gimme cards for every phantom that it holds. |
| @@ -877,38 +868,38 @@ | ||
| 877 | 868 | that mentions an artifact that the client does not possess. |
| 878 | 869 | <li>The client creates a phantom for the delta source of file cards when |
| 879 | 870 | the delta source is an artifact that the client does not possess. |
| 880 | 871 | </ol> |
| 881 | 872 | |
| 882 | -<p>These ten steps represent a single HTTP round-trip request. | |
| 873 | +These ten steps represent a single HTTP round-trip request. | |
| 883 | 874 | The first three steps are the processing that occurs on the client |
| 884 | 875 | to generate the request. The middle four steps are processing |
| 885 | 876 | that occurs on the server to interpret the request and generate a |
| 886 | 877 | reply. And the last three steps are the processing that the |
| 887 | -client does to interpret the reply.</p> | |
| 878 | +client does to interpret the reply. | |
| 888 | 879 | |
| 889 | -<p>During a pull, the client will keep sending HTTP requests | |
| 890 | -until it holds all artifacts that exist on the server.</p> | |
| 880 | +During a pull, the client will keep sending HTTP requests | |
| 881 | +until it holds all artifacts that exist on the server. | |
| 891 | 882 | |
| 892 | -<p>Note that the server tries | |
| 883 | +Note that the server tries | |
| 893 | 884 | to limit the size of its reply message to something reasonable |
| 894 | 885 | (usually about 1MB) so that it might stop sending file cards as |
| 895 | -described in step (6) if the reply becomes too large.</p> | |
| 886 | +described in step (6) if the reply becomes too large. | |
| 896 | 887 | |
| 897 | -<p>Step (5) is the only way in which new clusters can be created. | |
| 888 | +Step (5) is the only way in which new clusters can be created. | |
| 898 | 889 | By only creating clusters on the server, we hope to minimize the |
| 899 | 890 | amount of overlap between clusters in the common configuration where |
| 900 | 891 | there is a single server and many clients. The same synchronization |
| 901 | 892 | protocol will continue to work even if there are multiple servers |
| 902 | 893 | or if servers and clients sometimes change roles. The only negative |
| 903 | 894 | effects of these unusual arrangements is that more than the minimum |
| 904 | -number of clusters might be generated.</p> | |
| 895 | +number of clusters might be generated. | |
| 905 | 896 | |
| 906 | 897 | <h3>5.2 Push</h3> |
| 907 | 898 | |
| 908 | -<p>A typical push operation proceeds roughly as shown below. As | |
| 909 | -with a pull, the actual implementation may vary slightly.</p> | |
| 899 | +A typical push operation proceeds roughly as shown below. As | |
| 900 | +with a pull, the actual implementation may vary slightly. | |
| 910 | 901 | |
| 911 | 902 | <ol> |
| 912 | 903 | <li>The client sends login and push cards. |
| 913 | 904 | <li>The client sends file cards for any artifacts that it holds that have |
| 914 | 905 | never before been pushed - artifacts that come from local check-ins. |
| @@ -929,40 +920,40 @@ | ||
| 929 | 920 | <hr> |
| 930 | 921 | <li>The client remembers the gimme cards from the server so that it |
| 931 | 922 | can generate file cards in reply on the next cycle. |
| 932 | 923 | </ol> |
| 933 | 924 | |
| 934 | -<p>As with a pull, the steps of a push operation repeat until the | |
| 925 | +As with a pull, the steps of a push operation repeat until the | |
| 935 | 926 | server knows all artifacts that exist on the client. Also, as with |
| 936 | 927 | pull, the client attempts to keep the size of the request from |
| 937 | 928 | growing too large by suppressing file cards once the |
| 938 | -size of the request reaches 1MB.</p> | |
| 929 | +size of the request reaches 1MB. | |
| 939 | 930 | |
| 940 | 931 | <h3 id="sync">5.3 Sync</h3> |
| 941 | 932 | |
| 942 | -<p>A sync is just a pull and a push that happen at the same time. | |
| 933 | +A sync is just a pull and a push that happen at the same time. | |
| 943 | 934 | The first three steps of a pull are combined with the first five steps |
| 944 | 935 | of a push. Steps (4) through (7) of a pull are combined with steps |
| 945 | 936 | (5) through (8) of a push. And steps (8) through (10) of a pull |
| 946 | -are combined with step (9) of a push.</p> | |
| 937 | +are combined with step (9) of a push. | |
| 947 | 938 | |
| 948 | 939 | <h3>5.4 Unversioned File Sync</h3> |
| 949 | 940 | |
| 950 | -<p>"Unversioned files" are files held in the repository | |
| 941 | +"Unversioned files" are files held in the repository | |
| 951 | 942 | where only the most recent version of the file is kept rather than |
| 952 | 943 | the entire change history. Unversioned files are intended to be |
| 953 | 944 | used to store ephemeral content, such as compiled binaries of the |
| 954 | 945 | most recent release. |
| 955 | 946 | |
| 956 | -<p>Unversioned files are identified by name and timestamp (mtime). | |
| 947 | +Unversioned files are identified by name and timestamp (mtime). | |
| 957 | 948 | Only the most recent version of each file (the version with |
| 958 | 949 | the largest mtime value) is retained. |
| 959 | 950 | |
| 960 | -<p>Unversioned files are synchronized using the | |
| 951 | +Unversioned files are synchronized using the | |
| 961 | 952 | [/help?cmd=unversioned|fossil unversioned sync] command. |
| 962 | 953 | |
| 963 | -<p>A schematic of an unversioned file synchronization is as follows: | |
| 954 | +A schematic of an unversioned file synchronization is as follows: | |
| 964 | 955 | |
| 965 | 956 | <ol> |
| 966 | 957 | <li>The client sends a "pragma uv-hash" card to the server. The argument |
| 967 | 958 | to the uv-hash pragma is a hash of all filesnames, mtimes, and |
| 968 | 959 | content hashes for the unversioned files held by the client. |
| @@ -981,17 +972,17 @@ | ||
| 981 | 972 | <hr> |
| 982 | 973 | <li>The server updates its unversioned file store with received "uvfile" |
| 983 | 974 | cards and answers "uvgimme" cards with "uvfile" cards in its reply. |
| 984 | 975 | </ol> |
| 985 | 976 | |
| 986 | -<p>The last two steps might be repeated multiple | |
| 977 | +The last two steps might be repeated multiple | |
| 987 | 978 | times if there is more unversioned content to be transferred than will |
| 988 | 979 | fit comfortably in a single HTTP request. |
| 989 | 980 | |
| 990 | 981 | <h2>6.0 Summary</h2> |
| 991 | 982 | |
| 992 | -<p>Here are the key points of the synchronization protocol:</p> | |
| 983 | +Here are the key points of the synchronization protocol: | |
| 993 | 984 | |
| 994 | 985 | <ol> |
| 995 | 986 | <li>The client sends one or more PUSH HTTP requests to the server. |
| 996 | 987 | The request and reply content type is "application/x-fossil". |
| 997 | 988 | <li>HTTP request content is compressed using zlib. |
| @@ -1031,11 +1022,11 @@ | ||
| 1031 | 1022 | gimme messages for those artifacts. |
| 1032 | 1023 | </ol> |
| 1033 | 1024 | |
| 1034 | 1025 | <h2>7.0 Troubleshooting And Debugging Hints</h2> |
| 1035 | 1026 | |
| 1036 | -<p> | |
| 1027 | + | |
| 1037 | 1028 | If you run the [/help?cmd=sync|fossil sync] command |
| 1038 | 1029 | (or [/help?cmd=pull|pull] or [/help?cmd=push|push] or |
| 1039 | 1030 | [/help?cmd=clone|clone]) with the --httptrace option, Fossil |
| 1040 | 1031 | will keep a copy of each HTTP request and reply in files |
| 1041 | 1032 | named: |
| @@ -1042,17 +1033,17 @@ | ||
| 1042 | 1033 | <ul> |
| 1043 | 1034 | <li> <tt>http-request-</tt><i>N</i><tt>.txt</tt> |
| 1044 | 1035 | <li> <tt>http-reply-</tt><i>N</i><tt>.txt</tt> |
| 1045 | 1036 | </ul> |
| 1046 | 1037 | |
| 1047 | -<p>In the above, <i>N</i> is an integer that increments with each | |
| 1038 | +In the above, <i>N</i> is an integer that increments with each | |
| 1048 | 1039 | round-trip. If you are having trouble on the server side, |
| 1049 | 1040 | you can run the "[/help?cmd=test-http|fossil test-http]" command in a |
| 1050 | 1041 | debugger using one the "http-request-N.txt" files as input and |
| 1051 | 1042 | single step through the processing performed by the server. |
| 1052 | 1043 | |
| 1053 | -<p>The "--transport-command CMD" option on [/help?cmd=sync|fossil sync] | |
| 1044 | +The "--transport-command CMD" option on [/help?cmd=sync|fossil sync] | |
| 1054 | 1045 | (and similar) causes the external program "CMD" to be used to move |
| 1055 | 1046 | the sync message to the server and retrieve the sync reply. The |
| 1056 | 1047 | CMD is given three arguments: |
| 1057 | 1048 | <ol> |
| 1058 | 1049 | <li> The URL of the server |
| @@ -1060,9 +1051,9 @@ | ||
| 1060 | 1051 | protocol text, with the HTTP headers |
| 1061 | 1052 | <li> The name of a temporary file into which the CMD should write the |
| 1062 | 1053 | reply sync protocol text, again without any HTTP headers |
| 1063 | 1054 | </ol> |
| 1064 | 1055 | |
| 1065 | -<p>In a complex debugging situation, you can run the command | |
| 1056 | +In a complex debugging situation, you can run the command | |
| 1066 | 1057 | "fossil sync --transport-command ./debugging_script" where |
| 1067 | 1058 | "debugging_script" is some script of your own that invokes |
| 1068 | 1059 | the anomolous behavior your are trying to debug. |
| 1069 | 1060 |
| --- www/sync.wiki | |
| +++ www/sync.wiki | |
| @@ -1,13 +1,13 @@ | |
| 1 | <title>The Fossil Sync Protocol</title> |
| 2 | |
| 3 | <p>This document describes the wire protocol used to synchronize |
| 4 | content between two Fossil repositories.</p> |
| 5 | |
| 6 | <h2>1.0 Overview</h2> |
| 7 | |
| 8 | <p>The global state of a fossil repository consists of an unordered |
| 9 | collection of artifacts. Each artifact is identified by a cryptographic |
| 10 | hash of its content, expressed as a lower-case hexadecimal string. |
| 11 | Synchronization is the process of sharing artifacts between |
| 12 | repositories so that all repositories have copies of all artifacts. Because |
| 13 | artifacts are unordered, the order in which artifacts are received |
| @@ -17,13 +17,13 @@ | |
| 17 | of hashes for available artifacts, then sharing the content of artifacts |
| 18 | whose names are missing from one side or the other of the connection. |
| 19 | In practice, a repository might contain millions of artifacts. The list of |
| 20 | hash names for this many artifacts can be large. So optimizations are |
| 21 | employed that usually reduce the number of hashes that need to be |
| 22 | shared to a few hundred.</p> |
| 23 | |
| 24 | <p>Each repository also has local state. The local state determines |
| 25 | the web-page formatting preferences, authorized users, ticket formats, |
| 26 | and similar information that varies from one repository to another. |
| 27 | The local state is not usually transferred during a sync. Except, |
| 28 | some local state is transferred during a [/help?cmd=clone|clone] |
| 29 | in order to initialize the local state of the new repository. Also, |
| @@ -32,67 +32,67 @@ | |
| 32 | [/help?cmd=configuration|config pull] |
| 33 | commands. |
| 34 | |
| 35 | <h3 id="crdt">1.1 Conflict-Free Replicated Datatypes</h3> |
| 36 | |
| 37 | <p>The "bag of artifacts" data model used by Fossil is apparently an |
| 38 | implementation of a particular |
| 39 | [https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type|Conflict-Free |
| 40 | Replicated Datatype (CRDT)] called a "G-Set" or "Grow-only Set". The |
| 41 | academic literature on CRDTs only began to appear in about 2011, and |
| 42 | Fossil predates that research by at least 4 years. But it is nice to |
| 43 | know that theorists have now proven that the underlying data model of |
| 44 | Fossil can provide strongly-consistent replicas using only |
| 45 | peer-to-peer communication and without any kind of central |
| 46 | authority.</p> |
| 47 | |
| 48 | <p>If you are already familiar with CRDTs and were wondering if Fossil |
| 49 | used them, the answer is "yes". We just don't call them by that name.</p> |
| 50 | |
| 51 | |
| 52 | <h2>2.0 Transport</h2> |
| 53 | |
| 54 | <p>All communication between client and server is via HTTP requests. |
| 55 | The server is listening for incoming HTTP requests. The client |
| 56 | issues one or more HTTP requests and receives replies for each |
| 57 | request.</p> |
| 58 | |
| 59 | <p>The server might be running as an independent server |
| 60 | using the <b>server</b> command, or it might be launched from |
| 61 | inetd or xinetd using the <b>http</b> command. Or the server might |
| 62 | be launched from CGI. |
| 63 | (See "[./server/|How To Configure A Fossil Server]" for details.) |
| 64 | The specifics of how the server listens |
| 65 | for incoming HTTP requests is immaterial to this protocol. |
| 66 | The important point is that the server is listening for requests and |
| 67 | the client is the issuer of the requests.</p> |
| 68 | |
| 69 | <p>A single push, pull, or sync might involve multiple HTTP requests. |
| 70 | The client maintains state between all requests. But on the server |
| 71 | side, each request is independent. The server does not preserve |
| 72 | any information about the client from one request to the next.</p> |
| 73 | |
| 74 | <p>Note: Throughout this article, we use the terms "server" and "client" |
| 75 | to represent the listener and initiator of the interaction, respectively. |
| 76 | Nothing in this protocol requires that the server actually be a back-room |
| 77 | processor housed in a datacenter, nor does the client need to be a desktop |
| 78 | or handheld device. For the purposes of this article "client" simply means |
| 79 | the repository that initiates the conversation and "server" is the repository |
| 80 | that responds. Nothing more.</p> |
| 81 | |
| 82 | <h4>2.0.1 HTTPS Transport</h4> |
| 83 | |
| 84 | <p>In the current implementation of Fossil, the server only |
| 85 | understands HTTP requests. The client can send either |
| 86 | clear-text HTTP requests or encrypted HTTPS requests. But when |
| 87 | HTTPS requests are sent, they first must be decrypted by a web server |
| 88 | or proxy before being passed to the Fossil server. This limitation |
| 89 | may be relaxed in a future release.</p> |
| 90 | |
| 91 | <h4>2.0.2 SSH Transport</h4> |
| 92 | |
| 93 | <p>When doing a sync using an "ssh:..." URL, the same HTTP transport protocol |
| 94 | is used. Fossil simply uses [https://en.wikipedia.org/wiki/Secure_Shell|ssh] |
| 95 | to start an instance of the [/help?cmd=test-http|fossil test-http] command |
| 96 | running on the remote machine. It then sends HTTP requests and gets back HTTP |
| 97 | replies over the SSH connection, rather than sending and receiving over an |
| 98 | internet socket. To see the specific "ssh" command that the Fossil client |
| @@ -99,11 +99,11 @@ | |
| 99 | runs in order to set up a connection, add either of the the "--httptrace" or |
| 100 | "--sshtrace" options to the "fossil sync" command line. |
| 101 | |
| 102 | <h4>2.0.3 FILE Transport</h4> |
| 103 | |
| 104 | <p>When doing a sync using a "file:..." URL, the same HTTP protocol is |
| 105 | still used. But instead of sending each HTTP request over a socket or |
| 106 | via SSH, the HTTP request is written into a temporary file. The client |
| 107 | then invokes the [/help?cmd=http|fossil http] command in a subprocess |
| 108 | to process the request and and generate a reply. The client then reads |
| 109 | the HTTP reply out of a temporary file on disk, and deletes the two |
| @@ -111,36 +111,36 @@ | |
| 111 | in order to implement the "file:" transport, add the "--httptrace" |
| 112 | option to the "fossil sync" command. |
| 113 | |
| 114 | <h3>2.1 Server Identification</h3> |
| 115 | |
| 116 | <p>The server is identified by a URL argument that accompanies the |
| 117 | push, pull, or sync command on the client. (As a convenience to |
| 118 | users, the URL can be omitted on the client command and the same URL |
| 119 | from the most recent push, pull, or sync will be reused. This saves |
| 120 | typing in the common case where the client does multiple syncs to |
| 121 | the same server.)</p> |
| 122 | |
| 123 | <p>The client modifies the URL by appending the method name "<b>/xfer</b>" |
| 124 | to the end. For example, if the URL specified on the client command |
| 125 | line is</p> |
| 126 | |
| 127 | <blockquote> |
| 128 | https://fossil-scm.org/fossil |
| 129 | </blockquote> |
| 130 | |
| 131 | <p>Then the URL that is really used to do the synchronization will |
| 132 | be:</p> |
| 133 | |
| 134 | <blockquote> |
| 135 | https://fossil-scm.org/fossil/xfer |
| 136 | </blockquote> |
| 137 | |
| 138 | <h3>2.2 HTTP Request Format</h3> |
| 139 | |
| 140 | <p>The client always sends a POST request to the server. The |
| 141 | general format of the POST request is as follows:</p> |
| 142 | |
| 143 | <blockquote><pre> |
| 144 | POST /fossil/xfer HTTP/1.0 |
| 145 | Host: fossil-scm.hwaci.com:80 |
| 146 | Content-Type: application/x-fossil |
| @@ -147,19 +147,19 @@ | |
| 147 | Content-Length: 4216 |
| 148 | |
| 149 | <i>content...</i> |
| 150 | </pre></blockquote> |
| 151 | |
| 152 | <p>In the example above, the pathname given after the POST keyword |
| 153 | on the first line is a copy of the URL pathname. The Host: parameter |
| 154 | is also taken from the URL. The content type is always either |
| 155 | "application/x-fossil" or "application/x-fossil-debug". The "x-fossil" |
| 156 | content type is the default. The only difference is that "x-fossil" |
| 157 | content is compressed using zlib whereas "x-fossil-debug" is sent |
| 158 | uncompressed.</p> |
| 159 | |
| 160 | <p>A typical reply from the server might look something like this:</p> |
| 161 | |
| 162 | <blockquote><pre> |
| 163 | HTTP/1.0 200 OK |
| 164 | Date: Mon, 10 Sep 2007 12:21:01 GMT |
| 165 | Connection: close |
| @@ -168,160 +168,160 @@ | |
| 168 | Content-Length: 265 |
| 169 | |
| 170 | <i>content...</i> |
| 171 | </pre></blockquote> |
| 172 | |
| 173 | <p>The content type of the reply is always the same as the content type |
| 174 | of the request.</p> |
| 175 | |
| 176 | <h2>3.0 Fossil Synchronization Content</h2> |
| 177 | |
| 178 | <p>A synchronization request between a client and server consists of |
| 179 | one or more HTTP requests as described in the previous section. This |
| 180 | section details the "x-fossil" content type.</p> |
| 181 | |
| 182 | <h3>3.1 Line-oriented Format</h3> |
| 183 | |
| 184 | <p>The x-fossil content type consists of zero or more "cards". Cards |
| 185 | are separated by the newline character ("\n"). Leading and trailing |
| 186 | whitespace on a card is ignored. Blank cards are ignored.</p> |
| 187 | |
| 188 | <p>Each card is divided into zero or more space separated tokens. |
| 189 | The first token on each card is the operator. Subsequent tokens |
| 190 | are arguments. The set of operators understood by servers is slightly |
| 191 | different from the operators understood by clients, though the two |
| 192 | are very similar.</p> |
| 193 | |
| 194 | <h3>3.2 Login Cards</h3> |
| 195 | |
| 196 | <p>Every message from client to server begins with one or more login |
| 197 | cards. Each login card has the following format:</p> |
| 198 | |
| 199 | <blockquote> |
| 200 | <b>login</b> <i>userid nonce signature</i> |
| 201 | </blockquote> |
| 202 | |
| 203 | <p>The userid is the name of the user that is requesting service |
| 204 | from the server. The nonce is the SHA1 hash of the remainder of |
| 205 | the message - all text that follows the newline character that |
| 206 | terminates the login card. The signature is the SHA1 hash of |
| 207 | the concatenation of the nonce and the users password.</p> |
| 208 | |
| 209 | <p>For each login card, the server looks up the user and verifies |
| 210 | that the nonce matches the SHA1 hash of the remainder of the |
| 211 | message. It then checks the signature hash to make sure the |
| 212 | signature matches. If everything |
| 213 | checks out, then the client is granted all privileges of the |
| 214 | specified user.</p> |
| 215 | |
| 216 | <p>Privileges are cumulative. There can be multiple successful |
| 217 | login cards. The session privileges are the bit-wise OR of the |
| 218 | privileges of each individual login.</p> |
| 219 | |
| 220 | <h3>3.3 File Cards</h3> |
| 221 | |
| 222 | <p>Artifacts are transferred using either "file" cards, or "cfile" |
| 223 | or "uvfile" cards. |
| 224 | The name "file" card comes from the fact that most artifacts correspond to |
| 225 | files that are under version control. |
| 226 | The "cfile" name is an abbreviation for "compressed file". |
| 227 | The "uvfile" name is an abbreviation for "unversioned file". |
| 228 | </p> |
| 229 | |
| 230 | <h4>3.3.1 Ordinary File Cards</h4> |
| 231 | |
| 232 | <p>For sync protocols, artifacts are transferred using "file" |
| 233 | cards. File cards come in two different formats depending |
| 234 | on whether the artifact is sent directly or as a delta from some |
| 235 | other artifact.</p> |
| 236 | |
| 237 | <blockquote> |
| 238 | <b>file</b> <i>artifact-id size</i> <b>\n</b> <i>content</i><br> |
| 239 | <b>file</b> <i>artifact-id delta-artifact-id size</i> <b>\n</b> <i>content</i> |
| 240 | </blockquote> |
| 241 | |
| 242 | <p>File cards are followed by in-line "payload" data. |
| 243 | The content of the artifact |
| 244 | or the artifact delta is the first <i>size</i> bytes of the |
| 245 | x-fossil content that immediately follow the newline that |
| 246 | terminates the file card. |
| 247 | </p> |
| 248 | |
| 249 | <p>The first argument of a file card is the ID of the artifact that |
| 250 | is being transferred. The artifact ID is the lower-case hexadecimal |
| 251 | representation of the name hash for the artifact. |
| 252 | The last argument of the file card is the number of bytes of |
| 253 | payload that immediately follow the file card. If the file |
| 254 | card has only two arguments, that means the payload is the |
| 255 | complete content of the artifact. If the file card has three |
| 256 | arguments, then the payload is a delta and second argument is |
| 257 | the ID of another artifact that is the source of the delta.</p> |
| 258 | |
| 259 | <p>File cards are sent in both directions: client to server and |
| 260 | server to client. A delta might be sent before the source of |
| 261 | the delta, so both client and server should remember deltas |
| 262 | and be able to apply them when their source arrives.</p> |
| 263 | |
| 264 | <h4>3.3.2 Compressed File Cards</h4> |
| 265 | |
| 266 | <p>A client that sends a clone protocol version "3" or greater will |
| 267 | receive artifacts as "cfile" cards while cloning. This card was |
| 268 | introduced to improve the speed of the transfer of content by sending the |
| 269 | compressed artifact directly from the server database to the client.</p> |
| 270 | |
| 271 | <p>Compressed File cards are similar to File cards, sharing the same |
| 272 | in-line "payload" data characteristics and also the same treatment of |
| 273 | direct content or delta content. Cfile cards come in two different formats |
| 274 | depending on whether the artifact is sent directly or as a delta from |
| 275 | some other artifact.</p> |
| 276 | |
| 277 | <blockquote> |
| 278 | <b>cfile</b> <i>artifact-id usize csize</i> <b>\n</b> <i>content</i><br> |
| 279 | <b>cfile</b> <i>artifact-id delta-artifact-id usize csize</i> <b>\n</b> <i>content</i><br> |
| 280 | </blockquote> |
| 281 | |
| 282 | <p>The first argument of the cfile card is the ID of the artifact that |
| 283 | is being transferred. The artifact ID is the lower-case hexadecimal |
| 284 | representation of the name hash for the artifact. The second argument of |
| 285 | the cfile card is the original size in bytes of the artifact. The last |
| 286 | argument of the cfile card is the number of compressed bytes of payload |
| 287 | that immediately follow the cfile card. If the cfile card has only |
| 288 | three arguments, that means the payload is the complete content of the |
| 289 | artifact. If the cfile card has four arguments, then the payload is a |
| 290 | delta and the second argument is the ID of another artifact that is the |
| 291 | source of the delta and the third argument is the original size of the |
| 292 | delta artifact.</p> |
| 293 | |
| 294 | <p>Unlike file cards, cfile cards are only sent in one direction during a |
| 295 | clone from server to client for clone protocol version "3" or greater.</p> |
| 296 | |
| 297 | <h4>3.3.3 Private artifacts</h4> |
| 298 | |
| 299 | <p>"Private" content consist of artifacts that are not normally synced. |
| 300 | However, private content will be synced when the |
| 301 | the [/help?cmd=sync|fossil sync] command includes the "--private" option. |
| 302 | </p> |
| 303 | |
| 304 | <p>Private content is marked by a "private" card: |
| 305 | |
| 306 | <blockquote> |
| 307 | <b>private</b> |
| 308 | </blockquote> |
| 309 | |
| 310 | <p>The private card has no arguments and must directly precede a |
| 311 | file card that contains the private content.</p> |
| 312 | |
| 313 | <h4>3.3.4 Unversioned File Cards</h4> |
| 314 | |
| 315 | <p>Unversioned content is sent in both directions (client to server and |
| 316 | server to client) using "uvfile" cards in the following format: |
| 317 | |
| 318 | <blockquote> |
| 319 | <b>uvfile</b> <i>name mtime hash size flags</i> <b>\n</b> <i>content</i> |
| 320 | </blockquote> |
| 321 | |
| 322 | <p>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. |
| 326 | The <i>size</i> field is the (uncompressed) size of the content |
| 327 | in bytes. The <i>flags</i> field is an integer which is interpreted |
| @@ -329,234 +329,234 @@ | |
| 329 | the <i>content</i> is to be omitted. The content might be omitted if |
| 330 | it is too large to transmit, or if the sender merely wants to update the |
| 331 | modification time of the file without changing the files content. |
| 332 | The <i>content</i> is the (uncompressed) content of the file. |
| 333 | |
| 334 | <p>The receiver should only accept the uvfile card if the hash and |
| 335 | size match the content and if the mtime is newer than any existing |
| 336 | instance of the same file held by the receiver. The sender will not |
| 337 | normally transmit a uvfile card unless all these constraints are true, |
| 338 | but the receiver should double-check. |
| 339 | |
| 340 | <p>A server should only accept uvfile cards if the login user has |
| 341 | the "y" write-unversioned permission. |
| 342 | |
| 343 | <p>Servers send uvfile cards in response to uvgimme cards received from |
| 344 | the client. Clients send uvfile cards when they determine that the server |
| 345 | needs the content based on uvigot cards previously received from the server. |
| 346 | |
| 347 | <h3>3.4 Push and Pull Cards</h3> |
| 348 | |
| 349 | <p>Among the first cards in a client-to-server message are |
| 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:</p> |
| 354 | |
| 355 | <blockquote> |
| 356 | <b>push</b> <i>servercode projectcode</i><br> |
| 357 | <b>pull</b> <i>servercode projectcode</i> |
| 358 | </blockquote> |
| 359 | |
| 360 | <p>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 |
| 364 | for the transaction to proceed.</p> |
| 365 | |
| 366 | <p>The server will also send a push card back to the client |
| 367 | during a clone. This is how the client determines what project |
| 368 | code to put in the new repository it is constructing.</p> |
| 369 | |
| 370 | <p>The <i>servercode</i> argument is currently unused. |
| 371 | |
| 372 | <h3>3.5 Clone Cards</h3> |
| 373 | |
| 374 | <p>A clone card works like a pull card in that it is sent from |
| 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.</p> |
| 379 | |
| 380 | <blockquote> |
| 381 | <b>clone</b><br> |
| 382 | <b>clone</b> <i>protocol-version sequence-number</i> |
| 383 | </blockquote> |
| 384 | |
| 385 | <h4>3.5.1 Protocol 3</h4> |
| 386 | |
| 387 | <p>The latest clients send a two-argument clone message with a |
| 388 | protocol version of "3". (Future versions of Fossil might use larger |
| 389 | protocol version numbers.) Version "3" of the protocol enhanced version |
| 390 | "2" by introducing the "cfile" card which is intended to speed up clone |
| 391 | operations. Instead of sending "file" cards, the server will send "cfile" |
| 392 | cards</p> |
| 393 | |
| 394 | <h4>3.5.2 Protocol 2</h4> |
| 395 | |
| 396 | <p>The sequence-number sent is the number |
| 397 | of artifacts received so far. For the first clone message, the |
| 398 | sequence number is 0. The server will respond by sending file |
| 399 | cards for some number of artifacts up to the maximum message size. |
| 400 | |
| 401 | <p>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 | <blockquote> |
| 405 | <b>clone_seqno</b> <i>sequence-number</i> |
| 406 | </blockquote> |
| 407 | |
| 408 | <p>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.</p> |
| 411 | |
| 412 | <p>In response to an initial clone message, the server also sends the client |
| 413 | a push message so that the client can discover the projectcode for |
| 414 | this project.</p> |
| 415 | |
| 416 | <h4>3.5.3 Legacy Protocol</h4> |
| 417 | |
| 418 | <p>Older clients send a clone card with no argument. The server responds |
| 419 | to a blank clone card by sending an "igot" card for every artifact in the |
| 420 | repository. The client will then issue "gimme" cards to pull down all the |
| 421 | content it needs. |
| 422 | |
| 423 | <p>The legacy protocol works well for smaller repositories (50MB with 50,000 |
| 424 | artifacts) but is too slow and unwieldy for larger repositories. |
| 425 | The version 2 protocol is an effort to improve performance. Further |
| 426 | performance improvements with higher-numbered clone protocols are |
| 427 | possible in future versions of Fossil. |
| 428 | |
| 429 | <h3>3.6 Igot Cards</h3> |
| 430 | |
| 431 | <p>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:</p> |
| 434 | |
| 435 | <blockquote> |
| 436 | <b>igot</b> <i>artifact-id</i> ?<i>flag</i>? |
| 437 | </blockquote> |
| 438 | |
| 439 | <p>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 |
| 443 | using a gimme card in either the reply or in the next message.</p> |
| 444 | |
| 445 | <p>If the second argument exists and is "1", then the artifact |
| 446 | identified by the first argument is private on the sender and should |
| 447 | be ignored unless a "--private" [/help?cmd=sync|sync] is occurring. |
| 448 | |
| 449 | <p>The name "igot" comes from the English slang expression "I got" meaning |
| 450 | "I have". |
| 451 | |
| 452 | <h4>3.6.1 Unversioned Igot Cards</h4> |
| 453 | |
| 454 | <p>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 | <blockquote> |
| 459 | <b>uvigot</b> <i>name mtime hash size</i> |
| 460 | </blockquote> |
| 461 | |
| 462 | <p>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 |
| 466 | content, or "<b>-</b>" if the file has been deleted. |
| 467 | The <i>size</i> is the uncompressed size of the file in bytes. |
| 468 | |
| 469 | <p>When the server sees a "pragma uv-hash" card for which the hash |
| 470 | does not match, it sends uvigot cards for every unversioned file that it |
| 471 | holds. The client will use this information to figure out which |
| 472 | unversioned files need to be synchronized. |
| 473 | The server might also send a uvigot card when it receives a uvgimme card |
| 474 | but its reply message size is already oversized and hence unable to hold |
| 475 | the usual uvfile reply. |
| 476 | |
| 477 | <p>When a client receives a "uvigot" card, it checks to see if the |
| 478 | file needs to be transferred from client to server or from server to client. |
| 479 | If a client-to-server transmission is needed, the client schedules that |
| 480 | transfer to occur on a subsequent HTTP request. If a server-to-client |
| 481 | transfer is needed, then the client sends a "uvgimme" card back to the |
| 482 | server to request the file content. |
| 483 | |
| 484 | <h3>3.7 Gimme Cards</h3> |
| 485 | |
| 486 | <p>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:</p> |
| 489 | |
| 490 | <blockquote> |
| 491 | <b>gimme</b> <i>artifact-id</i> |
| 492 | </blockquote> |
| 493 | |
| 494 | <p>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.</p> |
| 498 | |
| 499 | <p>The "gimme" name means "give me". The imperative "give me" is |
| 500 | pronounced as if it were a single word "gimme" in some dialects of |
| 501 | English (including the dialect spoken by the original author of Fossil). |
| 502 | |
| 503 | <h4>3.7.1 Unversioned Gimme Cards</h4> |
| 504 | |
| 505 | <p>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 | <blockquote> |
| 511 | <b>uvgimme</b> <i>name</i> |
| 512 | </blockquote> |
| 513 | |
| 514 | <p>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. |
| 518 | |
| 519 | <h3>3.8 Cookie Cards</h3> |
| 520 | |
| 521 | <p>A cookie card can be used by a server to record a small amount |
| 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.</p> |
| 526 | |
| 527 | <blockquote> |
| 528 | <b>cookie</b> <i>payload</i> |
| 529 | </blockquote> |
| 530 | |
| 531 | <p>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 |
| 535 | a way that it can tell if the cookie it sees is its own cookie or |
| 536 | a cookie from another server. (Typically the server will embed |
| 537 | its servercode as part of the cookie.)</p> |
| 538 | |
| 539 | <h3>3.9 Request-Configuration Cards</h3> |
| 540 | |
| 541 | <p>A request-configuration or "reqconfig" card is sent from client to |
| 542 | server in order to request that the server send back "configuration" |
| 543 | data. "Configuration" data is information about users or website |
| 544 | appearance or other administrative details which are not part of the |
| 545 | persistent and versioned state of the project. For example, the "name" |
| 546 | of the project, the default Cascading Style Sheet (CSS) for the web-interface, |
| 547 | and the project logo displayed on the web-interface are all configuration |
| 548 | data elements. |
| 549 | |
| 550 | <p>The reqconfig card is normally sent in response to the |
| 551 | "fossil configuration pull" command. The format is as follows: |
| 552 | |
| 553 | <blockquote> |
| 554 | <b>reqconfig</b> <i>configuration-name</i> |
| 555 | </blockquote> |
| 556 | |
| 557 | <p>As of 2018-06-04, the configuration-name must be one of the |
| 558 | following values: |
| 559 | |
| 560 | <table border=0 align="center"> |
| 561 | <tr><td valign="top"> |
| 562 | <ul> |
| @@ -622,84 +622,81 @@ | |
| 622 | <li> @concealed |
| 623 | <li> @shun |
| 624 | </ul></td></tr> |
| 625 | </table> |
| 626 | |
| 627 | <p>New configuration-names are likely to be added in future releases of |
| 628 | Fossil. If the server receives a configuration-name that it does not |
| 629 | understand, the entire reqconfig card is silently ignored. The reqconfig |
| 630 | card might also be ignored if the user lacks sufficient privilege to |
| 631 | access the requested information. |
| 632 | |
| 633 | <p>The configuration-names that begin with an alphabetic character refer |
| 634 | to values in the "config" table of the server database. For example, |
| 635 | the "logo-image" configuration item refers to the project logo image |
| 636 | that is configured on the Admin page of the [./webui.wiki | web-interface]. |
| 637 | The value of the configuration item is returned to the client using a |
| 638 | "config" card. |
| 639 | |
| 640 | <p>If the configuration-name begins with "@", that refers to a class of |
| 641 | values instead of a single value. The content of these configuration items |
| 642 | is returned in a "config" card that contains pure SQL text that is |
| 643 | intended to be evaluated by the client. |
| 644 | |
| 645 | <p>The @user and @concealed configuration items contain sensitive information |
| 646 | and are ignored for clients without sufficient privilege. |
| 647 | |
| 648 | <h3>3.10 Configuration Cards</h3> |
| 649 | |
| 650 | <p>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 | <blockquote> |
| 656 | <b>config</b> <i>configuration-name size</i> <b>\n</b> <i>content</i> |
| 657 | </blockquote> |
| 658 | |
| 659 | <p>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 | |
| 663 | <p>The content of the configuration item is used to overwrite the |
| 664 | corresponding configuration data in the receiver. |
| 665 | |
| 666 | <h3>3.11 Pragma Cards</h3> |
| 667 | |
| 668 | <p>The client may try to influence the behavior of the server by |
| 669 | issuing a pragma card: |
| 670 | |
| 671 | <blockquote> |
| 672 | <b>pragma</i> <i>name value...</i> |
| 673 | </blockquote> |
| 674 | |
| 675 | <p>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. |
| 679 | |
| 680 | <p>New pragma names may be added to the protocol from time to time |
| 681 | in order to enhance the capabilities of Fossil. |
| 682 | Unknown pragmas are silently ignored, for backwards compatibility. |
| 683 | |
| 684 | <p>The following are the known pragma names as of 2019-06-30: |
| 685 | |
| 686 | <ol> |
| 687 | <li><p><b>send-private</b> |
| 688 | <p>The send-private pragma instructs the server to send all of its |
| 689 | private artifacts to the client. The server will only obey this |
| 690 | request if the user has the "x" or "Private" privilege. |
| 691 | |
| 692 | <li><p><b>send-catalog</b> |
| 693 | <p>The send-catalog pragma instructs the server to transmit igot |
| 694 | cards for every known artifact. This can help the client and server |
| 695 | to get back in synchronization after a prior protocol error. The |
| 696 | "--verily" option to the [/help?cmd=sync|fossil sync] command causes |
| 697 | the send-catalog pragma to be transmitted.</p> |
| 698 | |
| 699 | <li><p><b>uv-hash</b> <i>HASH</i> |
| 700 | <p>The uv-hash pragma is sent from client to server to provoke a |
| 701 | synchronization of unversioned content. The <i>HASH</i> is a SHA1 |
| 702 | hash of the names, modification times, and individual hashes of all |
| 703 | unversioned files on the client. If the unversioned content hash |
| 704 | from the client does not match the unversioned content hash on the |
| 705 | server, then the server will reply with either a "pragma uv-push-ok" |
| @@ -707,157 +704,151 @@ | |
| 707 | each unversioned file currently held on the server. The collection |
| 708 | of "uvigot" cards sent in response to a "uv-hash" pragma is called |
| 709 | the "unversioned catalog". The client will used the unversioned |
| 710 | catalog to figure out which files (if any) need to be synchronized |
| 711 | between client and server and send appropriate "uvfile" or "uvgimme" |
| 712 | cards on the next HTTP request.</p> |
| 713 | |
| 714 | <p>If a client sends a uv-hash pragma and does not receive back |
| 715 | either a uv-pull-only or uv-push-ok pragma, that means that the |
| 716 | content on the server exactly matches the content on the client and |
| 717 | no further synchronization is required. |
| 718 | |
| 719 | <li><p><b>uv-pull-only</b></i> |
| 720 | <p>A server sends the uv-pull-only pragma to the client in response |
| 721 | to a uv-hash pragma with a mismatched content hash argument. This |
| 722 | pragma indicates that there are differences in unversioned content |
| 723 | between the client and server but that content can only be transferred |
| 724 | from server to client. The server is unwilling to accept content from |
| 725 | the client because the client login lacks the "write-unversioned" |
| 726 | permission.</p> |
| 727 | |
| 728 | <li><p><b>uv-push-ok</b></i> |
| 729 | <p>A server sends the uv-push-ok pragma to the client in response |
| 730 | to a uv-hash pragma with a mismatched content hash argument. This |
| 731 | pragma indicates that there are differences in unversioned content |
| 732 | between the client and server and that content can be transferred |
| 733 | in either direction. The server is willing to accept content from |
| 734 | the client because the client login has the "write-unversioned" |
| 735 | permission.</p> |
| 736 | |
| 737 | <li><p><b>ci-lock</b> <i>CHECKIN-HASH CLIENT-ID</i></p> |
| 738 | <p>A client sends the "ci-lock" pragma to the server to indicate |
| 739 | that it is about to add a new check-in as a child of the |
| 740 | CHECKIN-HASH check-in and on the same branch as CHECKIN-HASH. |
| 741 | If some other client has already indicated that it was also |
| 742 | trying to commit against CHECKIN-HASH, that indicates that a |
| 743 | fork is about to occur, and the server will reply with |
| 744 | a "ci-lock-fail" pragma (see below). Check-in locks |
| 745 | automatically expire when the check-in actually occurs, or |
| 746 | after a timeout (currently one minute but subject to change). |
| 747 | |
| 748 | <li><p><b>ci-lock-fail</b> <i>LOGIN MTIME</i></p> |
| 749 | <p>When a server receives two or more "ci-lock" pragma messages |
| 750 | for the same check-in but from different clients, the second a |
| 751 | subsequent ci-lock will provoke a ci-lock-fail pragma in the |
| 752 | reply to let the client know that it if continues with the |
| 753 | check-in it will likely generate a fork. The LOGIN and MTIME |
| 754 | arguments are intended to provide information to the client to |
| 755 | help it generate a more useful error message. |
| 756 | </p> |
| 757 | |
| 758 | <li><p><b>ci-unlock</b> <i>CLIENT-ID</i></p> |
| 759 | <p>A client sends the "ci-unlock" pragma to the server after |
| 760 | a successful commit. This instructs the server to release |
| 761 | any lock on any check-in previously held by that client. |
| 762 | The ci-unlock pragma helps to avoid false-positive lock warnings |
| 763 | that might arise if a check-in is aborted and then restarted |
| 764 | on a branch. |
| 765 | </ol> |
| 766 | |
| 767 | <h3>3.12 Comment Cards</h3> |
| 768 | |
| 769 | <p>Any card that begins with "#" (ASCII 0x23) is a comment card and |
| 770 | is silently ignored.</p> |
| 771 | |
| 772 | <h3>3.13 Message and Error Cards</h3> |
| 773 | |
| 774 | <p>If the server discovers anything wrong with a request, it generates |
| 775 | an error card in its reply. When the client sees the error card, |
| 776 | it displays an error message to the user and aborts the sync |
| 777 | operation. An error card looks like this:</p> |
| 778 | |
| 779 | <blockquote> |
| 780 | <b>error</b> <i>error-message</i> |
| 781 | </blockquote> |
| 782 | |
| 783 | <p>The error message is English text that is encoded in order to |
| 784 | be a single token. |
| 785 | A space (ASCII 0x20) is represented as "\s" (ASCII 0x5C, 0x73). A |
| 786 | newline (ASCII 0x0a) is "\n" (ASCII 0x6C, x6E). A backslash |
| 787 | (ASCII 0x5C) is represented as two backslashes "\\". Apart from |
| 788 | space and newline, no other whitespace characters nor any |
| 789 | unprintable characters are allowed in |
| 790 | the error message.</p> |
| 791 | |
| 792 | <p>The server can also send a message card that also prints a |
| 793 | message on the client console, but which is not an error: |
| 794 | |
| 795 | <blockquote> |
| 796 | <b>message</b> <i>message-text</i> |
| 797 | </blockquote> |
| 798 | |
| 799 | <p>The message-text uses the same format as an error message. |
| 800 | |
| 801 | <h3>3.14 Unknown Cards</h3> |
| 802 | |
| 803 | <p>If either the client or the server sees a card that is not |
| 804 | described above, then it generates an error and aborts.</p> |
| 805 | |
| 806 | <h2>4.0 Phantoms And Clusters</h2> |
| 807 | |
| 808 | <p>When a repository knows that an artifact exists and knows the ID of |
| 809 | that artifact, but it does not know the artifact content, then it stores that |
| 810 | artifact as a "phantom". A repository will typically create a phantom when |
| 811 | it receives an igot card for an artifact that it does not hold or when it |
| 812 | receives a file card that references a delta source that it does not |
| 813 | hold. When a server is generating its reply or when a client is |
| 814 | generating a new request, it will usually send gimme cards for every |
| 815 | phantom that it holds.</p> |
| 816 | |
| 817 | <p>A cluster is a special artifact that tells of the existence of other |
| 818 | artifacts. Any artifact in the repository that follows the syntactic rules |
| 819 | of a cluster is considered a cluster.</p> |
| 820 | |
| 821 | <p>A cluster is line oriented. Each line of a cluster |
| 822 | is a card. The cards are separated by the newline ("\n") character. |
| 823 | Each card consists of a single character card type, a space, and a |
| 824 | single argument. No extra whitespace and no trailing or leading |
| 825 | whitespace is allowed. All cards in the cluster must occur in |
| 826 | strict lexicographical order.</p> |
| 827 | |
| 828 | <p>A cluster consists of one or more "M" cards followed by a single |
| 829 | "Z" card. Each M card holds an argument which is an artifact ID for an |
| 830 | artifact in the repository. The Z card has a single argument which is the |
| 831 | lower-case hexadecimal representation of the MD5 checksum of all |
| 832 | preceding M cards up to and included the newline character that |
| 833 | occurred just before the Z that starts the Z card.</p> |
| 834 | |
| 835 | <p>Any artifact that does not match the specifications of a cluster |
| 836 | exactly is not a cluster. There must be no extra whitespace in |
| 837 | the artifact. There must be one or more M cards. There must be a |
| 838 | single Z card with a correct MD5 checksum. And all cards must |
| 839 | be in strict lexicographical order.</p> |
| 840 | |
| 841 | <h3>4.1 The Unclustered Table</h3> |
| 842 | |
| 843 | <p>Every repository maintains a table named "<b>unclustered</b>" |
| 844 | which records the identity of every artifact and phantom it holds that is not |
| 845 | mentioned in a cluster. The entries in the unclustered table can |
| 846 | be thought of as leaves on a tree of artifacts. Some of the unclustered |
| 847 | artifacts will be other clusters. Those clusters may contain other clusters, |
| 848 | which might contain still more clusters, and so forth. Beginning |
| 849 | with the artifacts in the unclustered table, one can follow the chain |
| 850 | of clusters to find every artifact in the repository.</p> |
| 851 | |
| 852 | <h2>5.0 Synchronization Strategies</h2> |
| 853 | |
| 854 | <h3>5.1 Pull</h3> |
| 855 | |
| 856 | <p>A typical pull operation proceeds as shown below. Details |
| 857 | of the actual implementation may very slightly but the gist of |
| 858 | a pull is captured in the following steps:</p> |
| 859 | |
| 860 | <ol> |
| 861 | <li>The client sends login and pull cards. |
| 862 | <li>The client sends a cookie card if it has previously received a cookie. |
| 863 | <li>The client sends gimme cards for every phantom that it holds. |
| @@ -877,38 +868,38 @@ | |
| 877 | that mentions an artifact that the client does not possess. |
| 878 | <li>The client creates a phantom for the delta source of file cards when |
| 879 | the delta source is an artifact that the client does not possess. |
| 880 | </ol> |
| 881 | |
| 882 | <p>These ten steps represent a single HTTP round-trip request. |
| 883 | The first three steps are the processing that occurs on the client |
| 884 | to generate the request. The middle four steps are processing |
| 885 | that occurs on the server to interpret the request and generate a |
| 886 | reply. And the last three steps are the processing that the |
| 887 | client does to interpret the reply.</p> |
| 888 | |
| 889 | <p>During a pull, the client will keep sending HTTP requests |
| 890 | until it holds all artifacts that exist on the server.</p> |
| 891 | |
| 892 | <p>Note that the server tries |
| 893 | to limit the size of its reply message to something reasonable |
| 894 | (usually about 1MB) so that it might stop sending file cards as |
| 895 | described in step (6) if the reply becomes too large.</p> |
| 896 | |
| 897 | <p>Step (5) is the only way in which new clusters can be created. |
| 898 | By only creating clusters on the server, we hope to minimize the |
| 899 | amount of overlap between clusters in the common configuration where |
| 900 | there is a single server and many clients. The same synchronization |
| 901 | protocol will continue to work even if there are multiple servers |
| 902 | or if servers and clients sometimes change roles. The only negative |
| 903 | effects of these unusual arrangements is that more than the minimum |
| 904 | number of clusters might be generated.</p> |
| 905 | |
| 906 | <h3>5.2 Push</h3> |
| 907 | |
| 908 | <p>A typical push operation proceeds roughly as shown below. As |
| 909 | with a pull, the actual implementation may vary slightly.</p> |
| 910 | |
| 911 | <ol> |
| 912 | <li>The client sends login and push cards. |
| 913 | <li>The client sends file cards for any artifacts that it holds that have |
| 914 | never before been pushed - artifacts that come from local check-ins. |
| @@ -929,40 +920,40 @@ | |
| 929 | <hr> |
| 930 | <li>The client remembers the gimme cards from the server so that it |
| 931 | can generate file cards in reply on the next cycle. |
| 932 | </ol> |
| 933 | |
| 934 | <p>As with a pull, the steps of a push operation repeat until the |
| 935 | server knows all artifacts that exist on the client. Also, as with |
| 936 | pull, the client attempts to keep the size of the request from |
| 937 | growing too large by suppressing file cards once the |
| 938 | size of the request reaches 1MB.</p> |
| 939 | |
| 940 | <h3 id="sync">5.3 Sync</h3> |
| 941 | |
| 942 | <p>A sync is just a pull and a push that happen at the same time. |
| 943 | The first three steps of a pull are combined with the first five steps |
| 944 | of a push. Steps (4) through (7) of a pull are combined with steps |
| 945 | (5) through (8) of a push. And steps (8) through (10) of a pull |
| 946 | are combined with step (9) of a push.</p> |
| 947 | |
| 948 | <h3>5.4 Unversioned File Sync</h3> |
| 949 | |
| 950 | <p>"Unversioned files" are files held in the repository |
| 951 | where only the most recent version of the file is kept rather than |
| 952 | the entire change history. Unversioned files are intended to be |
| 953 | used to store ephemeral content, such as compiled binaries of the |
| 954 | most recent release. |
| 955 | |
| 956 | <p>Unversioned files are identified by name and timestamp (mtime). |
| 957 | Only the most recent version of each file (the version with |
| 958 | the largest mtime value) is retained. |
| 959 | |
| 960 | <p>Unversioned files are synchronized using the |
| 961 | [/help?cmd=unversioned|fossil unversioned sync] command. |
| 962 | |
| 963 | <p>A schematic of an unversioned file synchronization is as follows: |
| 964 | |
| 965 | <ol> |
| 966 | <li>The client sends a "pragma uv-hash" card to the server. The argument |
| 967 | to the uv-hash pragma is a hash of all filesnames, mtimes, and |
| 968 | content hashes for the unversioned files held by the client. |
| @@ -981,17 +972,17 @@ | |
| 981 | <hr> |
| 982 | <li>The server updates its unversioned file store with received "uvfile" |
| 983 | cards and answers "uvgimme" cards with "uvfile" cards in its reply. |
| 984 | </ol> |
| 985 | |
| 986 | <p>The last two steps might be repeated multiple |
| 987 | times if there is more unversioned content to be transferred than will |
| 988 | fit comfortably in a single HTTP request. |
| 989 | |
| 990 | <h2>6.0 Summary</h2> |
| 991 | |
| 992 | <p>Here are the key points of the synchronization protocol:</p> |
| 993 | |
| 994 | <ol> |
| 995 | <li>The client sends one or more PUSH HTTP requests to the server. |
| 996 | The request and reply content type is "application/x-fossil". |
| 997 | <li>HTTP request content is compressed using zlib. |
| @@ -1031,11 +1022,11 @@ | |
| 1031 | gimme messages for those artifacts. |
| 1032 | </ol> |
| 1033 | |
| 1034 | <h2>7.0 Troubleshooting And Debugging Hints</h2> |
| 1035 | |
| 1036 | <p> |
| 1037 | If you run the [/help?cmd=sync|fossil sync] command |
| 1038 | (or [/help?cmd=pull|pull] or [/help?cmd=push|push] or |
| 1039 | [/help?cmd=clone|clone]) with the --httptrace option, Fossil |
| 1040 | will keep a copy of each HTTP request and reply in files |
| 1041 | named: |
| @@ -1042,17 +1033,17 @@ | |
| 1042 | <ul> |
| 1043 | <li> <tt>http-request-</tt><i>N</i><tt>.txt</tt> |
| 1044 | <li> <tt>http-reply-</tt><i>N</i><tt>.txt</tt> |
| 1045 | </ul> |
| 1046 | |
| 1047 | <p>In the above, <i>N</i> is an integer that increments with each |
| 1048 | round-trip. If you are having trouble on the server side, |
| 1049 | you can run the "[/help?cmd=test-http|fossil test-http]" command in a |
| 1050 | debugger using one the "http-request-N.txt" files as input and |
| 1051 | single step through the processing performed by the server. |
| 1052 | |
| 1053 | <p>The "--transport-command CMD" option on [/help?cmd=sync|fossil sync] |
| 1054 | (and similar) causes the external program "CMD" to be used to move |
| 1055 | the sync message to the server and retrieve the sync reply. The |
| 1056 | CMD is given three arguments: |
| 1057 | <ol> |
| 1058 | <li> The URL of the server |
| @@ -1060,9 +1051,9 @@ | |
| 1060 | protocol text, with the HTTP headers |
| 1061 | <li> The name of a temporary file into which the CMD should write the |
| 1062 | reply sync protocol text, again without any HTTP headers |
| 1063 | </ol> |
| 1064 | |
| 1065 | <p>In a complex debugging situation, you can run the command |
| 1066 | "fossil sync --transport-command ./debugging_script" where |
| 1067 | "debugging_script" is some script of your own that invokes |
| 1068 | the anomolous behavior your are trying to debug. |
| 1069 |
| --- www/sync.wiki | |
| +++ www/sync.wiki | |
| @@ -1,13 +1,13 @@ | |
| 1 | <title>The Fossil Sync Protocol</title> |
| 2 | |
| 3 | This document describes the wire protocol used to synchronize |
| 4 | content between two Fossil repositories. |
| 5 | |
| 6 | <h2>1.0 Overview</h2> |
| 7 | |
| 8 | The global state of a fossil repository consists of an unordered |
| 9 | collection of artifacts. Each artifact is identified by a cryptographic |
| 10 | hash of its content, expressed as a lower-case hexadecimal string. |
| 11 | Synchronization is the process of sharing artifacts between |
| 12 | repositories so that all repositories have copies of all artifacts. Because |
| 13 | artifacts are unordered, the order in which artifacts are received |
| @@ -17,13 +17,13 @@ | |
| 17 | of hashes for available artifacts, then sharing the content of artifacts |
| 18 | whose names are missing from one side or the other of the connection. |
| 19 | In practice, a repository might contain millions of artifacts. The list of |
| 20 | hash names for this many artifacts can be large. So optimizations are |
| 21 | employed that usually reduce the number of hashes that need to be |
| 22 | shared to a few hundred. |
| 23 | |
| 24 | Each repository also has local state. The local state determines |
| 25 | the web-page formatting preferences, authorized users, ticket formats, |
| 26 | and similar information that varies from one repository to another. |
| 27 | The local state is not usually transferred during a sync. Except, |
| 28 | some local state is transferred during a [/help?cmd=clone|clone] |
| 29 | in order to initialize the local state of the new repository. Also, |
| @@ -32,67 +32,67 @@ | |
| 32 | [/help?cmd=configuration|config pull] |
| 33 | commands. |
| 34 | |
| 35 | <h3 id="crdt">1.1 Conflict-Free Replicated Datatypes</h3> |
| 36 | |
| 37 | The "bag of artifacts" data model used by Fossil is apparently an |
| 38 | implementation of a particular |
| 39 | [https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type|Conflict-Free |
| 40 | Replicated Datatype (CRDT)] called a "G-Set" or "Grow-only Set". The |
| 41 | academic literature on CRDTs only began to appear in about 2011, and |
| 42 | Fossil predates that research by at least 4 years. But it is nice to |
| 43 | know that theorists have now proven that the underlying data model of |
| 44 | Fossil can provide strongly-consistent replicas using only |
| 45 | peer-to-peer communication and without any kind of central |
| 46 | authority. |
| 47 | |
| 48 | If you are already familiar with CRDTs and were wondering if Fossil |
| 49 | used them, the answer is "yes". We just don't call them by that name. |
| 50 | |
| 51 | |
| 52 | <h2>2.0 Transport</h2> |
| 53 | |
| 54 | All communication between client and server is via HTTP requests. |
| 55 | The server is listening for incoming HTTP requests. The client |
| 56 | issues one or more HTTP requests and receives replies for each |
| 57 | request. |
| 58 | |
| 59 | The server might be running as an independent server |
| 60 | using the <b>server</b> command, or it might be launched from |
| 61 | inetd or xinetd using the <b>http</b> command. Or the server might |
| 62 | be launched from CGI. |
| 63 | (See "[./server/|How To Configure A Fossil Server]" for details.) |
| 64 | The specifics of how the server listens |
| 65 | for incoming HTTP requests is immaterial to this protocol. |
| 66 | The important point is that the server is listening for requests and |
| 67 | the client is the issuer of the requests. |
| 68 | |
| 69 | A single push, pull, or sync might involve multiple HTTP requests. |
| 70 | The client maintains state between all requests. But on the server |
| 71 | side, each request is independent. The server does not preserve |
| 72 | any information about the client from one request to the next. |
| 73 | |
| 74 | Note: Throughout this article, we use the terms "server" and "client" |
| 75 | to represent the listener and initiator of the interaction, respectively. |
| 76 | Nothing in this protocol requires that the server actually be a back-room |
| 77 | processor housed in a datacenter, nor does the client need to be a desktop |
| 78 | or handheld device. For the purposes of this article "client" simply means |
| 79 | the repository that initiates the conversation and "server" is the repository |
| 80 | that responds. Nothing more. |
| 81 | |
| 82 | <h4>2.0.1 HTTPS Transport</h4> |
| 83 | |
| 84 | In the current implementation of Fossil, the server only |
| 85 | understands HTTP requests. The client can send either |
| 86 | clear-text HTTP requests or encrypted HTTPS requests. But when |
| 87 | HTTPS requests are sent, they first must be decrypted by a web server |
| 88 | or proxy before being passed to the Fossil server. This limitation |
| 89 | may be relaxed in a future release. |
| 90 | |
| 91 | <h4>2.0.2 SSH Transport</h4> |
| 92 | |
| 93 | When doing a sync using an "ssh:..." URL, the same HTTP transport protocol |
| 94 | is used. Fossil simply uses [https://en.wikipedia.org/wiki/Secure_Shell|ssh] |
| 95 | to start an instance of the [/help?cmd=test-http|fossil test-http] command |
| 96 | running on the remote machine. It then sends HTTP requests and gets back HTTP |
| 97 | replies over the SSH connection, rather than sending and receiving over an |
| 98 | internet socket. To see the specific "ssh" command that the Fossil client |
| @@ -99,11 +99,11 @@ | |
| 99 | runs in order to set up a connection, add either of the the "--httptrace" or |
| 100 | "--sshtrace" options to the "fossil sync" command line. |
| 101 | |
| 102 | <h4>2.0.3 FILE Transport</h4> |
| 103 | |
| 104 | When doing a sync using a "file:..." URL, the same HTTP protocol is |
| 105 | still used. But instead of sending each HTTP request over a socket or |
| 106 | via SSH, the HTTP request is written into a temporary file. The client |
| 107 | then invokes the [/help?cmd=http|fossil http] command in a subprocess |
| 108 | to process the request and and generate a reply. The client then reads |
| 109 | the HTTP reply out of a temporary file on disk, and deletes the two |
| @@ -111,36 +111,36 @@ | |
| 111 | in order to implement the "file:" transport, add the "--httptrace" |
| 112 | option to the "fossil sync" command. |
| 113 | |
| 114 | <h3>2.1 Server Identification</h3> |
| 115 | |
| 116 | The server is identified by a URL argument that accompanies the |
| 117 | push, pull, or sync command on the client. (As a convenience to |
| 118 | users, the URL can be omitted on the client command and the same URL |
| 119 | from the most recent push, pull, or sync will be reused. This saves |
| 120 | typing in the common case where the client does multiple syncs to |
| 121 | the same server.) |
| 122 | |
| 123 | The client modifies the URL by appending the method name "<b>/xfer</b>" |
| 124 | to the end. For example, if the URL specified on the client command |
| 125 | line is |
| 126 | |
| 127 | <blockquote> |
| 128 | https://fossil-scm.org/fossil |
| 129 | </blockquote> |
| 130 | |
| 131 | Then the URL that is really used to do the synchronization will |
| 132 | be: |
| 133 | |
| 134 | <blockquote> |
| 135 | https://fossil-scm.org/fossil/xfer |
| 136 | </blockquote> |
| 137 | |
| 138 | <h3>2.2 HTTP Request Format</h3> |
| 139 | |
| 140 | The client always sends a POST request to the server. The |
| 141 | general format of the POST request is as follows: |
| 142 | |
| 143 | <blockquote><pre> |
| 144 | POST /fossil/xfer HTTP/1.0 |
| 145 | Host: fossil-scm.hwaci.com:80 |
| 146 | Content-Type: application/x-fossil |
| @@ -147,19 +147,19 @@ | |
| 147 | Content-Length: 4216 |
| 148 | |
| 149 | <i>content...</i> |
| 150 | </pre></blockquote> |
| 151 | |
| 152 | In the example above, the pathname given after the POST keyword |
| 153 | on the first line is a copy of the URL pathname. The Host: parameter |
| 154 | is also taken from the URL. The content type is always either |
| 155 | "application/x-fossil" or "application/x-fossil-debug". The "x-fossil" |
| 156 | content type is the default. The only difference is that "x-fossil" |
| 157 | content is compressed using zlib whereas "x-fossil-debug" is sent |
| 158 | uncompressed. |
| 159 | |
| 160 | A typical reply from the server might look something like this: |
| 161 | |
| 162 | <blockquote><pre> |
| 163 | HTTP/1.0 200 OK |
| 164 | Date: Mon, 10 Sep 2007 12:21:01 GMT |
| 165 | Connection: close |
| @@ -168,160 +168,160 @@ | |
| 168 | Content-Length: 265 |
| 169 | |
| 170 | <i>content...</i> |
| 171 | </pre></blockquote> |
| 172 | |
| 173 | The content type of the reply is always the same as the content type |
| 174 | of the request. |
| 175 | |
| 176 | <h2>3.0 Fossil Synchronization Content</h2> |
| 177 | |
| 178 | A synchronization request between a client and server consists of |
| 179 | one or more HTTP requests as described in the previous section. This |
| 180 | section details the "x-fossil" content type. |
| 181 | |
| 182 | <h3>3.1 Line-oriented Format</h3> |
| 183 | |
| 184 | The x-fossil content type consists of zero or more "cards". Cards |
| 185 | are separated by the newline character ("\n"). Leading and trailing |
| 186 | whitespace on a card is ignored. Blank cards are ignored. |
| 187 | |
| 188 | Each card is divided into zero or more space separated tokens. |
| 189 | The first token on each card is the operator. Subsequent tokens |
| 190 | are arguments. The set of operators understood by servers is slightly |
| 191 | different from the operators understood by clients, though the two |
| 192 | are very similar. |
| 193 | |
| 194 | <h3>3.2 Login Cards</h3> |
| 195 | |
| 196 | Every message from client to server begins with one or more login |
| 197 | cards. Each login card has the following format: |
| 198 | |
| 199 | <blockquote> |
| 200 | <b>login</b> <i>userid nonce signature</i> |
| 201 | </blockquote> |
| 202 | |
| 203 | The userid is the name of the user that is requesting service |
| 204 | from the server. The nonce is the SHA1 hash of the remainder of |
| 205 | the message - all text that follows the newline character that |
| 206 | terminates the login card. The signature is the SHA1 hash of |
| 207 | the concatenation of the nonce and the users password. |
| 208 | |
| 209 | For each login card, the server looks up the user and verifies |
| 210 | that the nonce matches the SHA1 hash of the remainder of the |
| 211 | message. It then checks the signature hash to make sure the |
| 212 | signature matches. If everything |
| 213 | checks out, then the client is granted all privileges of the |
| 214 | specified user. |
| 215 | |
| 216 | Privileges are cumulative. There can be multiple successful |
| 217 | login cards. The session privileges are the bit-wise OR of the |
| 218 | privileges of each individual login. |
| 219 | |
| 220 | <h3>3.3 File Cards</h3> |
| 221 | |
| 222 | Artifacts are transferred using either "file" cards, or "cfile" |
| 223 | or "uvfile" cards. |
| 224 | The name "file" card comes from the fact that most artifacts correspond to |
| 225 | files that are under version control. |
| 226 | The "cfile" name is an abbreviation for "compressed file". |
| 227 | The "uvfile" name is an abbreviation for "unversioned file". |
| 228 | |
| 229 | |
| 230 | <h4>3.3.1 Ordinary File Cards</h4> |
| 231 | |
| 232 | For sync protocols, artifacts are transferred using "file" |
| 233 | cards. File cards come in two different formats depending |
| 234 | on whether the artifact is sent directly or as a delta from some |
| 235 | other artifact. |
| 236 | |
| 237 | <blockquote> |
| 238 | <b>file</b> <i>artifact-id size</i> <b>\n</b> <i>content</i><br> |
| 239 | <b>file</b> <i>artifact-id delta-artifact-id size</i> <b>\n</b> <i>content</i> |
| 240 | </blockquote> |
| 241 | |
| 242 | File cards are followed by in-line "payload" data. |
| 243 | The content of the artifact |
| 244 | or the artifact delta is the first <i>size</i> bytes of the |
| 245 | x-fossil content that immediately follow the newline that |
| 246 | terminates the file card. |
| 247 | |
| 248 | |
| 249 | The first argument of a file card is the ID of the artifact that |
| 250 | is being transferred. The artifact ID is the lower-case hexadecimal |
| 251 | representation of the name hash for the artifact. |
| 252 | The last argument of the file card is the number of bytes of |
| 253 | payload that immediately follow the file card. If the file |
| 254 | card has only two arguments, that means the payload is the |
| 255 | complete content of the artifact. If the file card has three |
| 256 | arguments, then the payload is a delta and second argument is |
| 257 | the ID of another artifact that is the source of the delta. |
| 258 | |
| 259 | File cards are sent in both directions: client to server and |
| 260 | server to client. A delta might be sent before the source of |
| 261 | the delta, so both client and server should remember deltas |
| 262 | and be able to apply them when their source arrives. |
| 263 | |
| 264 | <h4>3.3.2 Compressed File Cards</h4> |
| 265 | |
| 266 | A client that sends a clone protocol version "3" or greater will |
| 267 | receive artifacts as "cfile" cards while cloning. This card was |
| 268 | introduced to improve the speed of the transfer of content by sending the |
| 269 | compressed artifact directly from the server database to the client. |
| 270 | |
| 271 | Compressed File cards are similar to File cards, sharing the same |
| 272 | in-line "payload" data characteristics and also the same treatment of |
| 273 | direct content or delta content. Cfile cards come in two different formats |
| 274 | depending on whether the artifact is sent directly or as a delta from |
| 275 | some other artifact. |
| 276 | |
| 277 | <blockquote> |
| 278 | <b>cfile</b> <i>artifact-id usize csize</i> <b>\n</b> <i>content</i><br> |
| 279 | <b>cfile</b> <i>artifact-id delta-artifact-id usize csize</i> <b>\n</b> <i>content</i><br> |
| 280 | </blockquote> |
| 281 | |
| 282 | The first argument of the cfile card is the ID of the artifact that |
| 283 | is being transferred. The artifact ID is the lower-case hexadecimal |
| 284 | representation of the name hash for the artifact. The second argument of |
| 285 | the cfile card is the original size in bytes of the artifact. The last |
| 286 | argument of the cfile card is the number of compressed bytes of payload |
| 287 | that immediately follow the cfile card. If the cfile card has only |
| 288 | three arguments, that means the payload is the complete content of the |
| 289 | artifact. If the cfile card has four arguments, then the payload is a |
| 290 | delta and the second argument is the ID of another artifact that is the |
| 291 | source of the delta and the third argument is the original size of the |
| 292 | delta artifact. |
| 293 | |
| 294 | Unlike file cards, cfile cards are only sent in one direction during a |
| 295 | clone from server to client for clone protocol version "3" or greater. |
| 296 | |
| 297 | <h4>3.3.3 Private artifacts</h4> |
| 298 | |
| 299 | "Private" content consist of artifacts that are not normally synced. |
| 300 | However, private content will be synced when the |
| 301 | the [/help?cmd=sync|fossil sync] command includes the "--private" option. |
| 302 | |
| 303 | |
| 304 | Private content is marked by a "private" card: |
| 305 | |
| 306 | <blockquote> |
| 307 | <b>private</b> |
| 308 | </blockquote> |
| 309 | |
| 310 | The private card has no arguments and must directly precede a |
| 311 | file card that contains the private content. |
| 312 | |
| 313 | <h4>3.3.4 Unversioned File Cards</h4> |
| 314 | |
| 315 | Unversioned content is sent in both directions (client to server and |
| 316 | server to client) using "uvfile" cards in the following format: |
| 317 | |
| 318 | <blockquote> |
| 319 | <b>uvfile</b> <i>name mtime hash size flags</i> <b>\n</b> <i>content</i> |
| 320 | </blockquote> |
| 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. |
| 326 | The <i>size</i> field is the (uncompressed) size of the content |
| 327 | in bytes. The <i>flags</i> field is an integer which is interpreted |
| @@ -329,234 +329,234 @@ | |
| 329 | the <i>content</i> is to be omitted. The content might be omitted if |
| 330 | it is too large to transmit, or if the sender merely wants to update the |
| 331 | modification time of the file without changing the files content. |
| 332 | The <i>content</i> is the (uncompressed) content of the file. |
| 333 | |
| 334 | The receiver should only accept the uvfile card if the hash and |
| 335 | size match the content and if the mtime is newer than any existing |
| 336 | instance of the same file held by the receiver. The sender will not |
| 337 | normally transmit a uvfile card unless all these constraints are true, |
| 338 | but the receiver should double-check. |
| 339 | |
| 340 | A server should only accept uvfile cards if the login user has |
| 341 | the "y" write-unversioned permission. |
| 342 | |
| 343 | Servers send uvfile cards in response to uvgimme cards received from |
| 344 | the client. Clients send uvfile cards when they determine that the server |
| 345 | needs the content based on uvigot cards previously received from the server. |
| 346 | |
| 347 | <h3>3.4 Push and Pull Cards</h3> |
| 348 | |
| 349 | Among the first cards in a client-to-server message are |
| 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 | <blockquote> |
| 356 | <b>push</b> <i>servercode projectcode</i><br> |
| 357 | <b>pull</b> <i>servercode projectcode</i> |
| 358 | </blockquote> |
| 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 |
| 364 | for the transaction to proceed. |
| 365 | |
| 366 | The server will also send a push card back to the client |
| 367 | during a clone. This is how the client determines what project |
| 368 | code to put in the new repository it is constructing. |
| 369 | |
| 370 | The <i>servercode</i> argument is currently unused. |
| 371 | |
| 372 | <h3>3.5 Clone Cards</h3> |
| 373 | |
| 374 | A clone card works like a pull card in that it is sent from |
| 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 | <blockquote> |
| 381 | <b>clone</b><br> |
| 382 | <b>clone</b> <i>protocol-version sequence-number</i> |
| 383 | </blockquote> |
| 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 |
| 389 | protocol version numbers.) Version "3" of the protocol enhanced version |
| 390 | "2" by introducing the "cfile" card which is intended to speed up clone |
| 391 | operations. Instead of sending "file" cards, the server will send "cfile" |
| 392 | cards |
| 393 | |
| 394 | <h4>3.5.2 Protocol 2</h4> |
| 395 | |
| 396 | The sequence-number sent is the number |
| 397 | of artifacts received so far. For the first clone message, the |
| 398 | sequence number is 0. The server will respond by sending file |
| 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 | <blockquote> |
| 405 | <b>clone_seqno</b> <i>sequence-number</i> |
| 406 | </blockquote> |
| 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 | |
| 412 | In response to an initial clone message, the server also sends the client |
| 413 | a push message so that the client can discover the projectcode for |
| 414 | this project. |
| 415 | |
| 416 | <h4>3.5.3 Legacy Protocol</h4> |
| 417 | |
| 418 | Older clients send a clone card with no argument. The server responds |
| 419 | to a blank clone card by sending an "igot" card for every artifact in the |
| 420 | repository. The client will then issue "gimme" cards to pull down all the |
| 421 | content it needs. |
| 422 | |
| 423 | The legacy protocol works well for smaller repositories (50MB with 50,000 |
| 424 | artifacts) but is too slow and unwieldy for larger repositories. |
| 425 | The version 2 protocol is an effort to improve performance. Further |
| 426 | performance improvements with higher-numbered clone protocols are |
| 427 | possible in future versions of Fossil. |
| 428 | |
| 429 | <h3>3.6 Igot Cards</h3> |
| 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 | <blockquote> |
| 436 | <b>igot</b> <i>artifact-id</i> ?<i>flag</i>? |
| 437 | </blockquote> |
| 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 |
| 443 | using a gimme card in either the reply or in the next message. |
| 444 | |
| 445 | If the second argument exists and is "1", then the artifact |
| 446 | identified by the first argument is private on the sender and should |
| 447 | be ignored unless a "--private" [/help?cmd=sync|sync] is occurring. |
| 448 | |
| 449 | The name "igot" comes from the English slang expression "I got" meaning |
| 450 | "I have". |
| 451 | |
| 452 | <h4>3.6.1 Unversioned Igot Cards</h4> |
| 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 | <blockquote> |
| 459 | <b>uvigot</b> <i>name mtime hash size</i> |
| 460 | </blockquote> |
| 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 |
| 466 | content, or "<b>-</b>" if the file has been deleted. |
| 467 | The <i>size</i> is the uncompressed size of the file in bytes. |
| 468 | |
| 469 | When the server sees a "pragma uv-hash" card for which the hash |
| 470 | does not match, it sends uvigot cards for every unversioned file that it |
| 471 | holds. The client will use this information to figure out which |
| 472 | unversioned files need to be synchronized. |
| 473 | The server might also send a uvigot card when it receives a uvgimme card |
| 474 | but its reply message size is already oversized and hence unable to hold |
| 475 | the usual uvfile reply. |
| 476 | |
| 477 | When a client receives a "uvigot" card, it checks to see if the |
| 478 | file needs to be transferred from client to server or from server to client. |
| 479 | If a client-to-server transmission is needed, the client schedules that |
| 480 | transfer to occur on a subsequent HTTP request. If a server-to-client |
| 481 | transfer is needed, then the client sends a "uvgimme" card back to the |
| 482 | server to request the file content. |
| 483 | |
| 484 | <h3>3.7 Gimme Cards</h3> |
| 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 | <blockquote> |
| 491 | <b>gimme</b> <i>artifact-id</i> |
| 492 | </blockquote> |
| 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. |
| 498 | |
| 499 | The "gimme" name means "give me". The imperative "give me" is |
| 500 | pronounced as if it were a single word "gimme" in some dialects of |
| 501 | English (including the dialect spoken by the original author of Fossil). |
| 502 | |
| 503 | <h4>3.7.1 Unversioned Gimme Cards</h4> |
| 504 | |
| 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 | <blockquote> |
| 511 | <b>uvgimme</b> <i>name</i> |
| 512 | </blockquote> |
| 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. |
| 518 | |
| 519 | <h3>3.8 Cookie Cards</h3> |
| 520 | |
| 521 | A cookie card can be used by a server to record a small amount |
| 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 | <blockquote> |
| 528 | <b>cookie</b> <i>payload</i> |
| 529 | </blockquote> |
| 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 |
| 535 | a way that it can tell if the cookie it sees is its own cookie or |
| 536 | a cookie from another server. (Typically the server will embed |
| 537 | its servercode as part of the cookie.) |
| 538 | |
| 539 | <h3>3.9 Request-Configuration Cards</h3> |
| 540 | |
| 541 | A request-configuration or "reqconfig" card is sent from client to |
| 542 | server in order to request that the server send back "configuration" |
| 543 | data. "Configuration" data is information about users or website |
| 544 | appearance or other administrative details which are not part of the |
| 545 | persistent and versioned state of the project. For example, the "name" |
| 546 | of the project, the default Cascading Style Sheet (CSS) for the web-interface, |
| 547 | and the project logo displayed on the web-interface are all configuration |
| 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 | <blockquote> |
| 554 | <b>reqconfig</b> <i>configuration-name</i> |
| 555 | </blockquote> |
| 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"> |
| 561 | <tr><td valign="top"> |
| 562 | <ul> |
| @@ -622,84 +622,81 @@ | |
| 622 | <li> @concealed |
| 623 | <li> @shun |
| 624 | </ul></td></tr> |
| 625 | </table> |
| 626 | |
| 627 | New configuration-names are likely to be added in future releases of |
| 628 | Fossil. If the server receives a configuration-name that it does not |
| 629 | understand, the entire reqconfig card is silently ignored. The reqconfig |
| 630 | card might also be ignored if the user lacks sufficient privilege to |
| 631 | access the requested information. |
| 632 | |
| 633 | The configuration-names that begin with an alphabetic character refer |
| 634 | to values in the "config" table of the server database. For example, |
| 635 | the "logo-image" configuration item refers to the project logo image |
| 636 | that is configured on the Admin page of the [./webui.wiki | web-interface]. |
| 637 | The value of the configuration item is returned to the client using a |
| 638 | "config" card. |
| 639 | |
| 640 | If the configuration-name begins with "@", that refers to a class of |
| 641 | values instead of a single value. The content of these configuration items |
| 642 | is returned in a "config" card that contains pure SQL text that is |
| 643 | intended to be evaluated by the client. |
| 644 | |
| 645 | The @user and @concealed configuration items contain sensitive information |
| 646 | and are ignored for clients without sufficient privilege. |
| 647 | |
| 648 | <h3>3.10 Configuration Cards</h3> |
| 649 | |
| 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 | <blockquote> |
| 656 | <b>config</b> <i>configuration-name size</i> <b>\n</b> <i>content</i> |
| 657 | </blockquote> |
| 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 | |
| 663 | The content of the configuration item is used to overwrite the |
| 664 | corresponding configuration data in the receiver. |
| 665 | |
| 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 | <blockquote> |
| 672 | <b>pragma</i> <i>name value...</i> |
| 673 | </blockquote> |
| 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. |
| 679 | |
| 680 | New pragma names may be added to the protocol from time to time |
| 681 | in order to enhance the capabilities of Fossil. |
| 682 | Unknown pragmas are silently ignored, for backwards compatibility. |
| 683 | |
| 684 | The following are the known pragma names as of 2019-06-30: |
| 685 | |
| 686 | <ol> |
| 687 | <li><b>send-private</b> The send-private pragma instructs the server to send all of its |
| 688 | private artifacts to the client. The server will only obey this |
| 689 | request if the user has the "x" or "Private" privilege. |
| 690 | |
| 691 | <li><b>send-catalog</b> The send-catalog pragma instructs the server to transmit igot |
| 692 | cards for every known artifact. This can help the client and server |
| 693 | to get back in synchronization after a prior protocol error. The |
| 694 | "--verily" option to the [/help?cmd=sync|fossil sync] command causes |
| 695 | the send-catalog pragma to be transmitted. |
| 696 | |
| 697 | <li><b>uv-hash</b> <i>HASH</i> The uv-hash pragma is sent from client to server to provoke a |
| 698 | synchronization of unversioned content. The <i>HASH</i> is a SHA1 |
| 699 | hash of the names, modification times, and individual hashes of all |
| 700 | unversioned files on the client. If the unversioned content hash |
| 701 | from the client does not match the unversioned content hash on the |
| 702 | server, then the server will reply with either a "pragma uv-push-ok" |
| @@ -707,157 +704,151 @@ | |
| 704 | each unversioned file currently held on the server. The collection |
| 705 | of "uvigot" cards sent in response to a "uv-hash" pragma is called |
| 706 | the "unversioned catalog". The client will used the unversioned |
| 707 | catalog to figure out which files (if any) need to be synchronized |
| 708 | between client and server and send appropriate "uvfile" or "uvgimme" |
| 709 | cards on the next HTTP request. |
| 710 | |
| 711 | If a client sends a uv-hash pragma and does not receive back |
| 712 | either a uv-pull-only or uv-push-ok pragma, that means that the |
| 713 | content on the server exactly matches the content on the client and |
| 714 | no further synchronization is required. |
| 715 | |
| 716 | <li><b>uv-pull-only</b></i> A server sends the uv-pull-only pragma to the client in response |
| 717 | to a uv-hash pragma with a mismatched content hash argument. This |
| 718 | pragma indicates that there are differences in unversioned content |
| 719 | between the client and server but that content can only be transferred |
| 720 | from server to client. The server is unwilling to accept content from |
| 721 | the client because the client login lacks the "write-unversioned" |
| 722 | permission. |
| 723 | |
| 724 | <li><b>uv-push-ok</b></i> A server sends the uv-push-ok pragma to the client in response |
| 725 | to a uv-hash pragma with a mismatched content hash argument. This |
| 726 | pragma indicates that there are differences in unversioned content |
| 727 | between the client and server and that content can be transferred |
| 728 | in either direction. The server is willing to accept content from |
| 729 | the client because the client login has the "write-unversioned" |
| 730 | permission. |
| 731 | |
| 732 | <li><b>ci-lock</b> <i>CHECKIN-HASH CLIENT-ID</i> A client sends the "ci-lock" pragma to the server to indicate |
| 733 | that it is about to add a new check-in as a child of the |
| 734 | CHECKIN-HASH check-in and on the same branch as CHECKIN-HASH. |
| 735 | If some other client has already indicated that it was also |
| 736 | trying to commit against CHECKIN-HASH, that indicates that a |
| 737 | fork is about to occur, and the server will reply with |
| 738 | a "ci-lock-fail" pragma (see below). Check-in locks |
| 739 | automatically expire when the check-in actually occurs, or |
| 740 | after a timeout (currently one minute but subject to change). |
| 741 | |
| 742 | <li><b>ci-lock-fail</b> <i>LOGIN MTIME</i> When a server receives two or more "ci-lock" pragma messages |
| 743 | for the same check-in but from different clients, the second a |
| 744 | subsequent ci-lock will provoke a ci-lock-fail pragma in the |
| 745 | reply to let the client know that it if continues with the |
| 746 | check-in it will likely generate a fork. The LOGIN and MTIME |
| 747 | arguments are intended to provide information to the client to |
| 748 | help it generate a more useful error message. |
| 749 | |
| 750 | <li><b>ci-unlock</b> <i>CLIENT-ID</i> A client sends the "ci-unlock" pragma to the server after |
| 751 | a successful commit. This instructs the server to release |
| 752 | any lock on any check-in previously held by that client. |
| 753 | The ci-unlock pragma helps to avoid false-positive lock warnings |
| 754 | that might arise if a check-in is aborted and then restarted |
| 755 | on a branch. |
| 756 | </ol> |
| 757 | |
| 758 | <h3>3.12 Comment Cards</h3> |
| 759 | |
| 760 | Any card that begins with "#" (ASCII 0x23) is a comment card and |
| 761 | is silently ignored. |
| 762 | |
| 763 | <h3>3.13 Message and Error Cards</h3> |
| 764 | |
| 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 | <blockquote> |
| 771 | <b>error</b> <i>error-message</i> |
| 772 | </blockquote> |
| 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 |
| 778 | (ASCII 0x5C) is represented as two backslashes "\\". Apart from |
| 779 | space and newline, no other whitespace characters nor any |
| 780 | unprintable characters are allowed in |
| 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 | <blockquote> |
| 787 | <b>message</b> <i>message-text</i> |
| 788 | </blockquote> |
| 789 | |
| 790 | The message-text uses the same format as an error message. |
| 791 | |
| 792 | <h3>3.14 Unknown Cards</h3> |
| 793 | |
| 794 | If either the client or the server sees a card that is not |
| 795 | described above, then it generates an error and aborts. |
| 796 | |
| 797 | <h2>4.0 Phantoms And Clusters</h2> |
| 798 | |
| 799 | When a repository knows that an artifact exists and knows the ID of |
| 800 | that artifact, but it does not know the artifact content, then it stores that |
| 801 | artifact as a "phantom". A repository will typically create a phantom when |
| 802 | it receives an igot card for an artifact that it does not hold or when it |
| 803 | receives a file card that references a delta source that it does not |
| 804 | hold. When a server is generating its reply or when a client is |
| 805 | generating a new request, it will usually send gimme cards for every |
| 806 | phantom that it holds. |
| 807 | |
| 808 | A cluster is a special artifact that tells of the existence of other |
| 809 | artifacts. Any artifact in the repository that follows the syntactic rules |
| 810 | of a cluster is considered a cluster. |
| 811 | |
| 812 | A cluster is line oriented. Each line of a cluster |
| 813 | is a card. The cards are separated by the newline ("\n") character. |
| 814 | Each card consists of a single character card type, a space, and a |
| 815 | single argument. No extra whitespace and no trailing or leading |
| 816 | whitespace is allowed. All cards in the cluster must occur in |
| 817 | strict lexicographical order. |
| 818 | |
| 819 | A cluster consists of one or more "M" cards followed by a single |
| 820 | "Z" card. Each M card holds an argument which is an artifact ID for an |
| 821 | artifact in the repository. The Z card has a single argument which is the |
| 822 | lower-case hexadecimal representation of the MD5 checksum of all |
| 823 | preceding M cards up to and included the newline character that |
| 824 | occurred just before the Z that starts the Z card. |
| 825 | |
| 826 | Any artifact that does not match the specifications of a cluster |
| 827 | exactly is not a cluster. There must be no extra whitespace in |
| 828 | the artifact. There must be one or more M cards. There must be a |
| 829 | single Z card with a correct MD5 checksum. And all cards must |
| 830 | be in strict lexicographical order. |
| 831 | |
| 832 | <h3>4.1 The Unclustered Table</h3> |
| 833 | |
| 834 | Every repository maintains a table named "<b>unclustered</b>" |
| 835 | which records the identity of every artifact and phantom it holds that is not |
| 836 | mentioned in a cluster. The entries in the unclustered table can |
| 837 | be thought of as leaves on a tree of artifacts. Some of the unclustered |
| 838 | artifacts will be other clusters. Those clusters may contain other clusters, |
| 839 | which might contain still more clusters, and so forth. Beginning |
| 840 | with the artifacts in the unclustered table, one can follow the chain |
| 841 | of clusters to find every artifact in the repository. |
| 842 | |
| 843 | <h2>5.0 Synchronization Strategies</h2> |
| 844 | |
| 845 | <h3>5.1 Pull</h3> |
| 846 | |
| 847 | A typical pull operation proceeds as shown below. Details |
| 848 | of the actual implementation may very slightly but the gist of |
| 849 | a pull is captured in the following steps: |
| 850 | |
| 851 | <ol> |
| 852 | <li>The client sends login and pull cards. |
| 853 | <li>The client sends a cookie card if it has previously received a cookie. |
| 854 | <li>The client sends gimme cards for every phantom that it holds. |
| @@ -877,38 +868,38 @@ | |
| 868 | that mentions an artifact that the client does not possess. |
| 869 | <li>The client creates a phantom for the delta source of file cards when |
| 870 | the delta source is an artifact that the client does not possess. |
| 871 | </ol> |
| 872 | |
| 873 | These ten steps represent a single HTTP round-trip request. |
| 874 | The first three steps are the processing that occurs on the client |
| 875 | to generate the request. The middle four steps are processing |
| 876 | that occurs on the server to interpret the request and generate a |
| 877 | reply. And the last three steps are the processing that the |
| 878 | client does to interpret the reply. |
| 879 | |
| 880 | During a pull, the client will keep sending HTTP requests |
| 881 | until it holds all artifacts that exist on the server. |
| 882 | |
| 883 | Note that the server tries |
| 884 | to limit the size of its reply message to something reasonable |
| 885 | (usually about 1MB) so that it might stop sending file cards as |
| 886 | described in step (6) if the reply becomes too large. |
| 887 | |
| 888 | Step (5) is the only way in which new clusters can be created. |
| 889 | By only creating clusters on the server, we hope to minimize the |
| 890 | amount of overlap between clusters in the common configuration where |
| 891 | there is a single server and many clients. The same synchronization |
| 892 | protocol will continue to work even if there are multiple servers |
| 893 | or if servers and clients sometimes change roles. The only negative |
| 894 | effects of these unusual arrangements is that more than the minimum |
| 895 | number of clusters might be generated. |
| 896 | |
| 897 | <h3>5.2 Push</h3> |
| 898 | |
| 899 | A typical push operation proceeds roughly as shown below. As |
| 900 | with a pull, the actual implementation may vary slightly. |
| 901 | |
| 902 | <ol> |
| 903 | <li>The client sends login and push cards. |
| 904 | <li>The client sends file cards for any artifacts that it holds that have |
| 905 | never before been pushed - artifacts that come from local check-ins. |
| @@ -929,40 +920,40 @@ | |
| 920 | <hr> |
| 921 | <li>The client remembers the gimme cards from the server so that it |
| 922 | can generate file cards in reply on the next cycle. |
| 923 | </ol> |
| 924 | |
| 925 | As with a pull, the steps of a push operation repeat until the |
| 926 | server knows all artifacts that exist on the client. Also, as with |
| 927 | pull, the client attempts to keep the size of the request from |
| 928 | growing too large by suppressing file cards once the |
| 929 | size of the request reaches 1MB. |
| 930 | |
| 931 | <h3 id="sync">5.3 Sync</h3> |
| 932 | |
| 933 | A sync is just a pull and a push that happen at the same time. |
| 934 | The first three steps of a pull are combined with the first five steps |
| 935 | of a push. Steps (4) through (7) of a pull are combined with steps |
| 936 | (5) through (8) of a push. And steps (8) through (10) of a pull |
| 937 | are combined with step (9) of a push. |
| 938 | |
| 939 | <h3>5.4 Unversioned File Sync</h3> |
| 940 | |
| 941 | "Unversioned files" are files held in the repository |
| 942 | where only the most recent version of the file is kept rather than |
| 943 | the entire change history. Unversioned files are intended to be |
| 944 | used to store ephemeral content, such as compiled binaries of the |
| 945 | most recent release. |
| 946 | |
| 947 | Unversioned files are identified by name and timestamp (mtime). |
| 948 | Only the most recent version of each file (the version with |
| 949 | the largest mtime value) is retained. |
| 950 | |
| 951 | Unversioned files are synchronized using the |
| 952 | [/help?cmd=unversioned|fossil unversioned sync] command. |
| 953 | |
| 954 | A schematic of an unversioned file synchronization is as follows: |
| 955 | |
| 956 | <ol> |
| 957 | <li>The client sends a "pragma uv-hash" card to the server. The argument |
| 958 | to the uv-hash pragma is a hash of all filesnames, mtimes, and |
| 959 | content hashes for the unversioned files held by the client. |
| @@ -981,17 +972,17 @@ | |
| 972 | <hr> |
| 973 | <li>The server updates its unversioned file store with received "uvfile" |
| 974 | cards and answers "uvgimme" cards with "uvfile" cards in its reply. |
| 975 | </ol> |
| 976 | |
| 977 | The last two steps might be repeated multiple |
| 978 | times if there is more unversioned content to be transferred than will |
| 979 | fit comfortably in a single HTTP request. |
| 980 | |
| 981 | <h2>6.0 Summary</h2> |
| 982 | |
| 983 | Here are the key points of the synchronization protocol: |
| 984 | |
| 985 | <ol> |
| 986 | <li>The client sends one or more PUSH HTTP requests to the server. |
| 987 | The request and reply content type is "application/x-fossil". |
| 988 | <li>HTTP request content is compressed using zlib. |
| @@ -1031,11 +1022,11 @@ | |
| 1022 | gimme messages for those artifacts. |
| 1023 | </ol> |
| 1024 | |
| 1025 | <h2>7.0 Troubleshooting And Debugging Hints</h2> |
| 1026 | |
| 1027 | |
| 1028 | If you run the [/help?cmd=sync|fossil sync] command |
| 1029 | (or [/help?cmd=pull|pull] or [/help?cmd=push|push] or |
| 1030 | [/help?cmd=clone|clone]) with the --httptrace option, Fossil |
| 1031 | will keep a copy of each HTTP request and reply in files |
| 1032 | named: |
| @@ -1042,17 +1033,17 @@ | |
| 1033 | <ul> |
| 1034 | <li> <tt>http-request-</tt><i>N</i><tt>.txt</tt> |
| 1035 | <li> <tt>http-reply-</tt><i>N</i><tt>.txt</tt> |
| 1036 | </ul> |
| 1037 | |
| 1038 | In the above, <i>N</i> is an integer that increments with each |
| 1039 | round-trip. If you are having trouble on the server side, |
| 1040 | you can run the "[/help?cmd=test-http|fossil test-http]" command in a |
| 1041 | debugger using one the "http-request-N.txt" files as input and |
| 1042 | single step through the processing performed by the server. |
| 1043 | |
| 1044 | The "--transport-command CMD" option on [/help?cmd=sync|fossil sync] |
| 1045 | (and similar) causes the external program "CMD" to be used to move |
| 1046 | the sync message to the server and retrieve the sync reply. The |
| 1047 | CMD is given three arguments: |
| 1048 | <ol> |
| 1049 | <li> The URL of the server |
| @@ -1060,9 +1051,9 @@ | |
| 1051 | protocol text, with the HTTP headers |
| 1052 | <li> The name of a temporary file into which the CMD should write the |
| 1053 | reply sync protocol text, again without any HTTP headers |
| 1054 | </ol> |
| 1055 | |
| 1056 | In a complex debugging situation, you can run the command |
| 1057 | "fossil sync --transport-command ./debugging_script" where |
| 1058 | "debugging_script" is some script of your own that invokes |
| 1059 | the anomolous behavior your are trying to debug. |
| 1060 |