|
1ad4ae2…
|
rberteig
|
1 |
Environment Variables and Global Options |
|
1ad4ae2…
|
rberteig
|
2 |
======================================== |
|
1ad4ae2…
|
rberteig
|
3 |
|
|
1ad4ae2…
|
rberteig
|
4 |
Fossil uses a number of environment variables and supports a number |
|
1ad4ae2…
|
rberteig
|
5 |
of global options. Most of these seem to be primarily documented in |
|
1ad4ae2…
|
rberteig
|
6 |
the source code, with the primary exception of `--args` which is |
|
1ad4ae2…
|
rberteig
|
7 |
described in the usage text printed by running fossil with no |
|
1ad4ae2…
|
rberteig
|
8 |
arguments at all. |
|
1ad4ae2…
|
rberteig
|
9 |
|
|
1ad4ae2…
|
rberteig
|
10 |
|
|
1ad4ae2…
|
rberteig
|
11 |
|
|
1ad4ae2…
|
rberteig
|
12 |
Global Options |
|
1ad4ae2…
|
rberteig
|
13 |
-------------- |
|
1ad4ae2…
|
rberteig
|
14 |
|
|
1ad4ae2…
|
rberteig
|
15 |
The following options are understood by the fossil command itself, and |
|
1ad4ae2…
|
rberteig
|
16 |
are collected before any subcommand begins processing. |
|
1ad4ae2…
|
rberteig
|
17 |
|
|
1ad4ae2…
|
rberteig
|
18 |
`--args FILENAME`: Read the file `FILENAME` and replace these two |
|
1ad4ae2…
|
rberteig
|
19 |
arguments with its content. Each line of the file is assumed to be an |
|
1ad4ae2…
|
rberteig
|
20 |
argument unless it starts with '-' and contains a space, in which case |
|
1ad4ae2…
|
rberteig
|
21 |
it is assumed to be another flag and is treated as such. `--args |
|
1ad4ae2…
|
rberteig
|
22 |
FILENAME` may be used in conjunction with any other flags. |
|
1ad4ae2…
|
rberteig
|
23 |
|
|
1ad4ae2…
|
rberteig
|
24 |
`--case-sensitive BOOL`: Override the `case-sensitive` setting, which |
|
1ad4ae2…
|
rberteig
|
25 |
can override the native preferences of the platform for case sensitive |
|
1ad4ae2…
|
rberteig
|
26 |
file names: insensitive on Windows, sensitive on Unix. There are |
|
1ad4ae2…
|
rberteig
|
27 |
probably odd interactions possible if you mix case sensitive and case |
|
1ad4ae2…
|
rberteig
|
28 |
insensitive file systems on any single platform. This option or the |
|
1ad4ae2…
|
rberteig
|
29 |
global setting should be used to force the case sensitivity to the |
|
1ad4ae2…
|
rberteig
|
30 |
most sensible condition. |
|
1ad4ae2…
|
rberteig
|
31 |
|
|
54cdf29…
|
danield
|
32 |
`--cgitrace`: Active CGI tracing. |
|
54cdf29…
|
danield
|
33 |
|
|
1ad4ae2…
|
rberteig
|
34 |
`--chdir DIRECTORY`: Change to the named directory before processing |
|
1ad4ae2…
|
rberteig
|
35 |
any commands. |
|
1ad4ae2…
|
rberteig
|
36 |
|
|
1ad4ae2…
|
rberteig
|
37 |
|
|
93b0afc…
|
drh
|
38 |
`--comfmtflags NUMBER`: Specify flags that control how check-in comments |
|
2e2e13b…
|
mistachkin
|
39 |
and certain other text outputs are formatted for display. The flags are |
|
2e2e13b…
|
mistachkin
|
40 |
individual bits in `NUMBER`, which must be specified in base 10: |
|
2e2e13b…
|
mistachkin
|
41 |
|
|
2e2e13b…
|
mistachkin
|
42 |
* _0_ — Uses the revised algorithm with no special handling. |
|
2e2e13b…
|
mistachkin
|
43 |
|
|
007fd18…
|
florian
|
44 |
* _1_ — Uses the canonical algorithm, other flags are ignored. |
|
2e2e13b…
|
mistachkin
|
45 |
|
|
2e2e13b…
|
mistachkin
|
46 |
* _2_ — Trims leading and trailing carriage-returns and line-feeds |
|
2e2e13b…
|
mistachkin
|
47 |
where they do not materially impact pre-existing formatting |
|
ed36875…
|
mistachkin
|
48 |
(i.e. at the start of the comment string _and_ right before |
|
2e2e13b…
|
mistachkin
|
49 |
line indentation). |
|
2e2e13b…
|
mistachkin
|
50 |
|
|
2e2e13b…
|
mistachkin
|
51 |
* _4_ — Trims leading and trailing spaces where they do not materially |
|
2e2e13b…
|
mistachkin
|
52 |
impact the pre-existing formatting (i.e. at the start of the |
|
ed36875…
|
mistachkin
|
53 |
comment string _and_ right before line indentation). |
|
2e2e13b…
|
mistachkin
|
54 |
|
|
2e2e13b…
|
mistachkin
|
55 |
* _8_ — Attempts to break lines on word boundaries while honoring the |
|
2e2e13b…
|
mistachkin
|
56 |
logical line length. |
|
2e2e13b…
|
mistachkin
|
57 |
|
|
16ef8ee…
|
mistachkin
|
58 |
* _16_ — Looks for the original comment text within the text being |
|
2e2e13b…
|
mistachkin
|
59 |
printed. Upon matching, a new line will be emitted, thus |
|
2e2e13b…
|
mistachkin
|
60 |
preserving more of the pre-existing formatting. |
|
93b0afc…
|
drh
|
61 |
|
|
93b0afc…
|
drh
|
62 |
|
|
93b0afc…
|
drh
|
63 |
`--comment-format NUMBER`: Alias for `--comfmtflags NUMBER`. |
|
007fd18…
|
florian
|
64 |
|
|
007fd18…
|
florian
|
65 |
|
|
007fd18…
|
florian
|
66 |
> NOTE: As of Fossil version 2.26, use of the `--comfmtflags` and |
|
007fd18…
|
florian
|
67 |
> `--comment-format` options is no longer recommended and they are |
|
007fd18…
|
florian
|
68 |
> no longer documented, but retained for backwards compatibility. |
|
57f178e…
|
mistachkin
|
69 |
|
|
57f178e…
|
mistachkin
|
70 |
|
|
1ad4ae2…
|
rberteig
|
71 |
`--errorlog ERRLOG`: Name a file to which fossil will log panics, |
|
1ad4ae2…
|
rberteig
|
72 |
errors, and warnings. |
|
1ad4ae2…
|
rberteig
|
73 |
|
|
1ad4ae2…
|
rberteig
|
74 |
|
|
1ad4ae2…
|
rberteig
|
75 |
`--help`: If `--help` is found anywhere on the command line, translate |
|
1ad4ae2…
|
rberteig
|
76 |
the command to `fossil help cmdname` where `cmdname` is the first |
|
1ad4ae2…
|
rberteig
|
77 |
argument that does not begin with a `-` character. If all arguments |
|
1ad4ae2…
|
rberteig
|
78 |
start with `-`, translate to `fossil help argv[1] argv[2]...`. |
|
1ad4ae2…
|
rberteig
|
79 |
|
|
1ad4ae2…
|
rberteig
|
80 |
`--httptrace`: (Sets `g.fHttpTrace`.) Trace outbound HTTP requests. |
|
1ad4ae2…
|
rberteig
|
81 |
|
|
1ad4ae2…
|
rberteig
|
82 |
`--localtime`: Override the `timeline-utc` option to explicitly use |
|
1ad4ae2…
|
rberteig
|
83 |
local time. |
|
1ad4ae2…
|
rberteig
|
84 |
|
|
1ad4ae2…
|
rberteig
|
85 |
`--nocgi`: Prevent fossil from acting as a CGI by default even if the |
|
1ad4ae2…
|
rberteig
|
86 |
`GATEWAY_INTERFACE` environment variable is set. |
|
1ad4ae2…
|
rberteig
|
87 |
|
|
1ad4ae2…
|
rberteig
|
88 |
`--no-th-hook`: (Sets `g.fNoThHook`.) Override the `th1-hooks` setting |
|
1ad4ae2…
|
rberteig
|
89 |
and prevent any TH1 hooks from being executed. |
|
1ad4ae2…
|
rberteig
|
90 |
|
|
1ad4ae2…
|
rberteig
|
91 |
`--quiet`: (Sets `g.fQuiet`.) Cause fossil to suppress various messages and progress |
|
1ad4ae2…
|
rberteig
|
92 |
indicators that would otherwise be printed. |
|
1ad4ae2…
|
rberteig
|
93 |
|
|
1ad4ae2…
|
rberteig
|
94 |
`--sqltrace`: (Sets `g.SqlTrace`.) Implies `--sqlstats`. Trace certain |
|
1ad4ae2…
|
rberteig
|
95 |
SQLite database activity, especially showing every SQL query |
|
1ad4ae2…
|
rberteig
|
96 |
processed. |
|
1ad4ae2…
|
rberteig
|
97 |
|
|
1ad4ae2…
|
rberteig
|
98 |
`--sqlstats`: (Sets `g.fSqlStats`.) Print a number of performance |
|
1ad4ae2…
|
rberteig
|
99 |
statistics about each SQLite database used when it is closed. |
|
1ad4ae2…
|
rberteig
|
100 |
|
|
1ad4ae2…
|
rberteig
|
101 |
`--sshtrace`: (Sets `g.fSshTrace`.) |
|
1ad4ae2…
|
rberteig
|
102 |
|
|
7c75972…
|
mistachkin
|
103 |
`--ssl-identity`: The fully qualified name of the file containing the client |
|
7c75972…
|
mistachkin
|
104 |
certificate and private key to use, in PEM format. It can be created by |
|
7c75972…
|
mistachkin
|
105 |
concatenating the client certificate and private key files. This identity will |
|
7c75972…
|
mistachkin
|
106 |
be presented to SSL servers to authenticate the client, in addition to the |
|
7c75972…
|
mistachkin
|
107 |
normal password authentication. |
|
1ad4ae2…
|
rberteig
|
108 |
|
|
1ad4ae2…
|
rberteig
|
109 |
`--systemtrace`: (Sets `g.fSystemTrace`.) Trace all commands launched |
|
1ad4ae2…
|
rberteig
|
110 |
as sub processes. |
|
1ad4ae2…
|
rberteig
|
111 |
|
|
1ad4ae2…
|
rberteig
|
112 |
`--user LOGIN`: (Sets `g.zLogin`) Also `-U LOGIN`. Set the user name |
|
1ad4ae2…
|
rberteig
|
113 |
used with the repository. |
|
1ad4ae2…
|
rberteig
|
114 |
|
|
1ad4ae2…
|
rberteig
|
115 |
`--utc`: Override the `timeline-utc` option to explicitly use |
|
1ad4ae2…
|
rberteig
|
116 |
UTC time. |
|
1ad4ae2…
|
rberteig
|
117 |
|
|
1ad4ae2…
|
rberteig
|
118 |
`--vfs VFSNAME`: Load the named VFS into SQLite. |
|
1ad4ae2…
|
rberteig
|
119 |
|
|
1ad4ae2…
|
rberteig
|
120 |
|
|
1ad4ae2…
|
rberteig
|
121 |
Environment Variables |
|
1ad4ae2…
|
rberteig
|
122 |
--------------------- |
|
1ad4ae2…
|
rberteig
|
123 |
|
|
4645e9b…
|
drh
|
124 |
The location of the user's account-wide [configuration database][configdb] |
|
e755561…
|
danield
|
125 |
depends on the operating system and on the existence of various |
|
4645e9b…
|
drh
|
126 |
environment variables and/or files. See the discussion of the |
|
4645e9b…
|
drh
|
127 |
[configuration database location algorithm][configloc] for details. |
|
1ad4ae2…
|
rberteig
|
128 |
|
|
1ad4ae2…
|
rberteig
|
129 |
`EDITOR`: Name the editor to use for check-in and stash comments. |
|
1ad4ae2…
|
rberteig
|
130 |
Overridden by the local or global `editor` setting or the `VISUAL` |
|
1ad4ae2…
|
rberteig
|
131 |
environment variable. |
|
e285341…
|
mistachkin
|
132 |
|
|
e285341…
|
mistachkin
|
133 |
`FOSSIL_BREAK`: If set, an opportunity will be created to attach a |
|
e285341…
|
mistachkin
|
134 |
debugger to the Fossil process prior to any significant work being |
|
e285341…
|
mistachkin
|
135 |
performed. |
|
1ad4ae2…
|
rberteig
|
136 |
|
|
1ad4ae2…
|
rberteig
|
137 |
`FOSSIL_FORCE_TICKET_MODERATION`: If set, *ALL* changes for tickets |
|
1ad4ae2…
|
rberteig
|
138 |
will be required to go through moderation (even those performed by the |
|
1ad4ae2…
|
rberteig
|
139 |
local interactive user via the command line). This can be useful for |
|
1ad4ae2…
|
rberteig
|
140 |
local (or remote) testing of the moderation subsystem and its impact |
|
1ad4ae2…
|
rberteig
|
141 |
on the contents and status of tickets. |
|
1ad4ae2…
|
rberteig
|
142 |
|
|
1ad4ae2…
|
rberteig
|
143 |
`FOSSIL_FORCE_WIKI_MODERATION`: If set, *ALL* changes for wiki pages |
|
1ad4ae2…
|
rberteig
|
144 |
will be required to go through moderation (even those performed by the |
|
1ad4ae2…
|
rberteig
|
145 |
local interactive user via the command line). This can be useful for |
|
1ad4ae2…
|
rberteig
|
146 |
local (or remote) testing of the moderation subsystem and its impact |
|
1ad4ae2…
|
rberteig
|
147 |
on the contents and status of wiki pages. |
|
1ad4ae2…
|
rberteig
|
148 |
|
|
1ad4ae2…
|
rberteig
|
149 |
|
|
22f879d…
|
drh
|
150 |
`FOSSIL_HOME`: Location of [configuration database][configdb]. |
|
22f879d…
|
drh
|
151 |
See the [configuration database location][configloc] description |
|
22f879d…
|
drh
|
152 |
for additional information. |
|
e755561…
|
danield
|
153 |
|
|
c591bbe…
|
florian
|
154 |
`FOSSIL_REPOLIST_TITLE`: The page title of the "Repository List" page |
|
c591bbe…
|
florian
|
155 |
loaded by the `fossil all ui` or `fossil ui /` commands. Only used if |
|
c591bbe…
|
florian
|
156 |
none of the listed repositories has the `repolist_skin` property set. |
|
c591bbe…
|
florian
|
157 |
Can be set from the [CGI control file][cgictlfile]. |
|
c591bbe…
|
florian
|
158 |
|
|
fbd7731…
|
drh
|
159 |
`FOSSIL_REPOLIST_SHOW`: If this variable exists and has a text value |
|
fbd7731…
|
drh
|
160 |
that contains the substring "description", then the "Project Description" |
|
fbd7731…
|
drh
|
161 |
column appears on the repolist page. If it contains the substring |
|
fbd7731…
|
drh
|
162 |
"login-group", then the Login-Group column appears on the repolist page. |
|
fbd7731…
|
drh
|
163 |
Can be set from the [CGI control file][cgictlfile]. |
|
fbd7731…
|
drh
|
164 |
|
|
00dfbdb…
|
mistachkin
|
165 |
`FOSSIL_USE_SEE_TEXTKEY`: If set, treat the encryption key string for |
|
79c2cb0…
|
wyoung
|
166 |
SEE as text to be hashed into the actual encryption key. This has no |
|
00dfbdb…
|
mistachkin
|
167 |
effect if Fossil was not compiled with SEE support enabled. |
|
00dfbdb…
|
mistachkin
|
168 |
|
|
1ad4ae2…
|
rberteig
|
169 |
|
|
1ad4ae2…
|
rberteig
|
170 |
`FOSSIL_USER`: Name of the default user account if the checkout, local |
|
1ad4ae2…
|
rberteig
|
171 |
or global `default-user` setting is not present. The first environment |
|
1ad4ae2…
|
rberteig
|
172 |
variable found in the environment from the list `FOSSIL_USER`, `USER`, |
|
1ad4ae2…
|
rberteig
|
173 |
`LOGNAME`, and `USERNAME` is the user name. If none of those are set, |
|
1ad4ae2…
|
rberteig
|
174 |
then the default user name is "root". See the discussion of Fossil |
|
1ad4ae2…
|
rberteig
|
175 |
Username below for a lot more detail. |
|
1ad4ae2…
|
rberteig
|
176 |
|
|
d168be0…
|
drh
|
177 |
|
|
d168be0…
|
drh
|
178 |
`FOSSIL_SECURITY_LEVEL`: If set to any of the values listed below, |
|
d168be0…
|
drh
|
179 |
additional measures for password security will be enabled (also see |
|
d168be0…
|
drh
|
180 |
[How To Use Encrypted Repositories][encryptedrepos.wiki]): |
|
d168be0…
|
drh
|
181 |
|
|
d168be0…
|
drh
|
182 |
[encryptedrepos.wiki]: /doc/trunk/www/encryptedrepos.wiki |
|
d168be0…
|
drh
|
183 |
|
|
d168be0…
|
drh
|
184 |
* _≥1_ — Do not remember passwords. |
|
d168be0…
|
drh
|
185 |
|
|
d168be0…
|
drh
|
186 |
* _≥2_ — Use a scrambled matrix for password input. |
|
d168be0…
|
drh
|
187 |
|
|
d168be0…
|
drh
|
188 |
|
|
1ad4ae2…
|
rberteig
|
189 |
`FOSSIL_TCL_PATH`: When Tcl stubs support is configured, point to a |
|
1ad4ae2…
|
rberteig
|
190 |
specific file or folder containing the version of Tcl to load at run |
|
1ad4ae2…
|
rberteig
|
191 |
time. |
|
1ad4ae2…
|
rberteig
|
192 |
|
|
f4f3af4…
|
mistachkin
|
193 |
`FOSSIL_TEST_DANGEROUS_IGNORE_OPEN_CHECKOUT`: When set to the literal |
|
f4f3af4…
|
mistachkin
|
194 |
value `YES_DO_IT`, the test suite will relax the constraint that some |
|
f4f3af4…
|
mistachkin
|
195 |
tests may not run within an open checkout. This is subject to removal |
|
f4f3af4…
|
mistachkin
|
196 |
in the future. |
|
1ad4ae2…
|
rberteig
|
197 |
|
|
1ad4ae2…
|
rberteig
|
198 |
`FOSSIL_VFS`: Name a VFS to load into SQLite. |
|
1ad4ae2…
|
rberteig
|
199 |
|
|
1ad4ae2…
|
rberteig
|
200 |
`GATEWAY_INTERFACE`: If present and the `--nocgi` option is not, assume |
|
1ad4ae2…
|
rberteig
|
201 |
fossil is invoked from a web server as a CGI command, and act |
|
1ad4ae2…
|
rberteig
|
202 |
accordingly. |
|
1ad4ae2…
|
rberteig
|
203 |
|
|
22f879d…
|
drh
|
204 |
`HOME`: Potential location of the [configuration database][configdb]. |
|
22f879d…
|
drh
|
205 |
See the [configuration database location][configloc] description for details. |
|
1ad4ae2…
|
rberteig
|
206 |
|
|
1ad4ae2…
|
rberteig
|
207 |
`HOMEDRIVE`, `HOMEPATH`: (Windows) Location of the `~/.fossil` file. |
|
1ad4ae2…
|
rberteig
|
208 |
The first environment variable found in the environment from the list |
|
1ad4ae2…
|
rberteig
|
209 |
`FOSSIL_HOME`, `LOCALAPPDATA` (Windows), `APPDATA` (Windows), |
|
1ad4ae2…
|
rberteig
|
210 |
`HOMEDRIVE` and `HOMEPATH` (Windows, used together), and `HOME` is |
|
1ad4ae2…
|
rberteig
|
211 |
used as the location of the `~/.fossil` file. |
|
1ad4ae2…
|
rberteig
|
212 |
|
|
1ad4ae2…
|
rberteig
|
213 |
`HTTP_HOST`: If defined, included in error log messages. |
|
1ad4ae2…
|
rberteig
|
214 |
|
|
1ad4ae2…
|
rberteig
|
215 |
`http_proxy`: If the global or local settings `proxy` is not set, this |
|
1ad4ae2…
|
rberteig
|
216 |
is used as the default value for the `proxy` setting. |
|
1ad4ae2…
|
rberteig
|
217 |
|
|
1ad4ae2…
|
rberteig
|
218 |
|
|
1ad4ae2…
|
rberteig
|
219 |
`HTTP_USER_AGENT`: If defined, included in error log messages. |
|
1ad4ae2…
|
rberteig
|
220 |
|
|
1ad4ae2…
|
rberteig
|
221 |
|
|
1ad4ae2…
|
rberteig
|
222 |
`LOCALAPPDATA`: (Windows) Location of the `~/.fossil` file. The first |
|
1ad4ae2…
|
rberteig
|
223 |
environment variable found in the environment from the list |
|
1ad4ae2…
|
rberteig
|
224 |
`FOSSIL_HOME`, `LOCALAPPDATA` (Windows), `APPDATA` (Windows), |
|
1ad4ae2…
|
rberteig
|
225 |
`HOMEDRIVE` and `HOMEPATH` (Windows, used together), and `HOME` is |
|
1ad4ae2…
|
rberteig
|
226 |
used as the location of the `~/.fossil` file. |
|
1ad4ae2…
|
rberteig
|
227 |
|
|
1ad4ae2…
|
rberteig
|
228 |
`LOGNAME`: Name of the logged in user on many Unix-like platforms. |
|
1ad4ae2…
|
rberteig
|
229 |
Used as the fossil user name if `FOSSIL_USER` is not specified. See |
|
1ad4ae2…
|
rberteig
|
230 |
the discussion of Fossil Username below for a lot more detail. |
|
1ad4ae2…
|
rberteig
|
231 |
|
|
007fd18…
|
florian
|
232 |
`NO_COLOR`: If defined and not set to a `false` value (i.e. "off", "no", |
|
007fd18…
|
florian
|
233 |
"false", "0"), the `fossil search` command skips colorization of console |
|
007fd18…
|
florian
|
234 |
output using ANSI escape codes (VT100). |
|
007fd18…
|
florian
|
235 |
|
|
1ad4ae2…
|
rberteig
|
236 |
`PATH`: Used by most platforms to locate programs invoked without a |
|
1ad4ae2…
|
rberteig
|
237 |
fully qualified name. Explicitly used by `fossil ui` on certain platforms |
|
1ad4ae2…
|
rberteig
|
238 |
to choose the browser to launch. |
|
1ad4ae2…
|
rberteig
|
239 |
|
|
1ad4ae2…
|
rberteig
|
240 |
`PATH_INFO`: If defined, included in error log messages. |
|
1ad4ae2…
|
rberteig
|
241 |
|
|
1ad4ae2…
|
rberteig
|
242 |
`QUERY_STRING`: If defined, included in error log messages. |
|
1ad4ae2…
|
rberteig
|
243 |
|
|
1ad4ae2…
|
rberteig
|
244 |
`REMOTE_ADDR`: If defined, included in error log messages. |
|
1ad4ae2…
|
rberteig
|
245 |
|
|
1ad4ae2…
|
rberteig
|
246 |
`REMOTE_HOST`: Used by `fossil http` run from `stunnel` to identify |
|
1ad4ae2…
|
rberteig
|
247 |
the remote host. |
|
1ad4ae2…
|
rberteig
|
248 |
|
|
1ad4ae2…
|
rberteig
|
249 |
`REQUEST_METHOD`: If defined, included in error log messages. |
|
1ad4ae2…
|
rberteig
|
250 |
|
|
1ad4ae2…
|
rberteig
|
251 |
`REQUEST_URI`: If defined, included in error log messages. |
|
1ad4ae2…
|
rberteig
|
252 |
|
|
1ad4ae2…
|
rberteig
|
253 |
`SCRIPT_NAME`: If defined, included in error log messages. |
|
1ad4ae2…
|
rberteig
|
254 |
|
|
1ad4ae2…
|
rberteig
|
255 |
`SSH_CONNECTION`: Informs CGI processing if the remote client is SSH. |
|
85cfdd1…
|
florian
|
256 |
|
|
85cfdd1…
|
florian
|
257 |
`SSL_CERT_FILE`, `SSL_CERT_DIR`: Override the [`ssl-ca-location`] |
|
c64f28d…
|
drh
|
258 |
(/help/ssl-ca-location) setting. |
|
006afac…
|
drh
|
259 |
|
|
1ad4ae2…
|
rberteig
|
260 |
`SQLITE_FORCE_PROXY_LOCKING`: From `sqlite3.c`, 1 means force always |
|
1ad4ae2…
|
rberteig
|
261 |
use proxy, 0 means never use proxy, and undefined means use proxy for |
|
1ad4ae2…
|
rberteig
|
262 |
non-local files only. |
|
1ad4ae2…
|
rberteig
|
263 |
|
|
2e2e13b…
|
mistachkin
|
264 |
`SQLITE_TMPDIR`: Names the temporary file location for SQLite. When |
|
2e2e13b…
|
mistachkin
|
265 |
set, this will be used instead of `TMPDIR`. |
|
1ad4ae2…
|
rberteig
|
266 |
|
|
1ad4ae2…
|
rberteig
|
267 |
|
|
1ad4ae2…
|
rberteig
|
268 |
`SYSTEMROOT`: (Windows) Used to locate `notepad.exe` as a |
|
1ad4ae2…
|
rberteig
|
269 |
fall back comment editor. |
|
1ad4ae2…
|
rberteig
|
270 |
|
|
1ad4ae2…
|
rberteig
|
271 |
`TERM`: If the linenoise library is used (almost certainly not on |
|
1ad4ae2…
|
rberteig
|
272 |
Windows), it will check `TERM` to verify that the interactive terminal |
|
1ad4ae2…
|
rberteig
|
273 |
is not named on a short list on terminals known to not work with |
|
1ad4ae2…
|
rberteig
|
274 |
linenoise. Linenoise is a library that provides command history and |
|
1ad4ae2…
|
rberteig
|
275 |
command line editing to interactive programs, and can be used in the |
|
1ad4ae2…
|
rberteig
|
276 |
`fossil sqlite3` command. |
|
1ad4ae2…
|
rberteig
|
277 |
|
|
1ad4ae2…
|
rberteig
|
278 |
`TH1_DELETE_INTERP`: Set this variable to ask fossil to explicitly |
|
1ad4ae2…
|
rberteig
|
279 |
delete the TH1 interpreter, if it is loaded, then check that it |
|
1ad4ae2…
|
rberteig
|
280 |
released all of its allocated memory, when exiting fossil. This is not |
|
1ad4ae2…
|
rberteig
|
281 |
strictly necessary, but makes debugging memory leaks easier. See |
|
1ad4ae2…
|
rberteig
|
282 |
[main.c near line 386](/artifact/e75796be5338a81c?ln=386,391) for the |
|
1ad4ae2…
|
rberteig
|
283 |
code. |
|
1ad4ae2…
|
rberteig
|
284 |
|
|
1ad4ae2…
|
rberteig
|
285 |
`TH1_ENABLE_DOCS`: Override the local or global setting `tcl-docs` |
|
1ad4ae2…
|
rberteig
|
286 |
to enable TH1 documents in fossil. |
|
1ad4ae2…
|
rberteig
|
287 |
|
|
1ad4ae2…
|
rberteig
|
288 |
`TH1_ENABLE_HOOKS`: Override the local or global setting `tcl-hooks` |
|
1ad4ae2…
|
rberteig
|
289 |
to enable TH1 hooks in fossil. |
|
1ad4ae2…
|
rberteig
|
290 |
|
|
1ad4ae2…
|
rberteig
|
291 |
`TH1_ENABLE_TCL`: Override the local or global setting `tcl` to enable |
|
2e2e13b…
|
mistachkin
|
292 |
Tcl in fossil. |
|
2e2e13b…
|
mistachkin
|
293 |
|
|
5915e6f…
|
mistachkin
|
294 |
`TH1_TEST_ANON_CAPS`: Override the default anonymous permissions used |
|
5915e6f…
|
mistachkin
|
295 |
when processing the `--set-anon-caps` option for the `test-th-eval`, |
|
5915e6f…
|
mistachkin
|
296 |
`test-th-render`, and `test-th-source` test commands. |
|
5915e6f…
|
mistachkin
|
297 |
|
|
5915e6f…
|
mistachkin
|
298 |
`TH1_TEST_USER_CAPS`: Override the default user permissions used when |
|
5915e6f…
|
mistachkin
|
299 |
processing the `--set-user-caps` option for the `test-th-eval`, |
|
5915e6f…
|
mistachkin
|
300 |
`test-th-render`, and `test-th-source` test commands. |
|
2e2e13b…
|
mistachkin
|
301 |
|
|
2e2e13b…
|
mistachkin
|
302 |
`TMPDIR`: Names the temporary file location for SQLite. |
|
1ad4ae2…
|
rberteig
|
303 |
|
|
1ad4ae2…
|
rberteig
|
304 |
|
|
1ad4ae2…
|
rberteig
|
305 |
`USER`: Name of the logged in user on many Unix-like platforms. |
|
1ad4ae2…
|
rberteig
|
306 |
Used as the fossil user name if `FOSSIL_USER` is not specified. See |
|
1ad4ae2…
|
rberteig
|
307 |
the discussion of Fossil Username below for a lot more detail. |
|
1ad4ae2…
|
rberteig
|
308 |
|
|
1ad4ae2…
|
rberteig
|
309 |
`USERNAME`: Name of the logged in user on Windows platforms. |
|
1ad4ae2…
|
rberteig
|
310 |
Used as the fossil user name if `FOSSIL_USER` is not specified. See |
|
1ad4ae2…
|
rberteig
|
311 |
the discussion of Fossil Username below for a lot more detail. |
|
1ad4ae2…
|
rberteig
|
312 |
|
|
1ad4ae2…
|
rberteig
|
313 |
`VISUAL`: Name the editor to use for check-in and stash comments. |
|
1ad4ae2…
|
rberteig
|
314 |
Overrides the `EDITOR` environment variable. Overridden by the local |
|
1ad4ae2…
|
rberteig
|
315 |
or global `editor` setting. |
|
1ad4ae2…
|
rberteig
|
316 |
|
|
1ad4ae2…
|
rberteig
|
317 |
|
|
1ad4ae2…
|
rberteig
|
318 |
|
|
1ad4ae2…
|
rberteig
|
319 |
Notes on Related Values |
|
1ad4ae2…
|
rberteig
|
320 |
----------------------- |
|
1ad4ae2…
|
rberteig
|
321 |
|
|
1ad4ae2…
|
rberteig
|
322 |
### CGI and JSON Parameters |
|
1ad4ae2…
|
rberteig
|
323 |
|
|
1ad4ae2…
|
rberteig
|
324 |
|
|
1ad4ae2…
|
rberteig
|
325 |
The JSON API implementation looks up many values in the first of |
|
1ad4ae2…
|
rberteig
|
326 |
several places searched. This unifies the parameter handling logic, |
|
1ad4ae2…
|
rberteig
|
327 |
allows the caller to choose whether to prefer URL parameters, request |
|
1ad4ae2…
|
rberteig
|
328 |
headers, or the POST payload, and allows the `fossil json` command to |
|
1ad4ae2…
|
rberteig
|
329 |
share most of the same logic as the `/json` API path. The search order |
|
1ad4ae2…
|
rberteig
|
330 |
is a POST payload, GET/COOKIE/non-JSON POST, JSON POST, the system |
|
1ad4ae2…
|
rberteig
|
331 |
environment. |
|
1ad4ae2…
|
rberteig
|
332 |
|
|
1ad4ae2…
|
rberteig
|
333 |
See the comment above the implementation of [`json_getenv`][json.c] |
|
1ad4ae2…
|
rberteig
|
334 |
for some further discussion. |
|
1ad4ae2…
|
rberteig
|
335 |
|
|
1ad4ae2…
|
rberteig
|
336 |
[json.c]: /artifact/6df1d80dece8968b?ln=277,290 |
|
1ad4ae2…
|
rberteig
|
337 |
|
|
1ad4ae2…
|
rberteig
|
338 |
### Comment Editor |
|
1ad4ae2…
|
rberteig
|
339 |
|
|
1ad4ae2…
|
rberteig
|
340 |
The editor used to edit a check-in or stash comment is named by the |
|
1ad4ae2…
|
rberteig
|
341 |
local or global setting `editor`. If neither is set, then the environment |
|
1ad4ae2…
|
rberteig
|
342 |
variables `VISUAL`, and `EDITOR` are checked in that order. |
|
1ad4ae2…
|
rberteig
|
343 |
|
|
1ad4ae2…
|
rberteig
|
344 |
On Windows, if no editor is named, then Notepad is used. Note that the |
|
1ad4ae2…
|
rberteig
|
345 |
operation will be aborted if `notepad.exe` is not found in the Windows |
|
1ad4ae2…
|
rberteig
|
346 |
folder. |
|
1ad4ae2…
|
rberteig
|
347 |
|
|
1ad4ae2…
|
rberteig
|
348 |
On Unix-like platforms, if no editor is named, then a message is |
|
1ad4ae2…
|
rberteig
|
349 |
displayed on stdout, and stdin is read until a single line containing |
|
1ad4ae2…
|
rberteig
|
350 |
only a dot is seen. |
|
1ad4ae2…
|
rberteig
|
351 |
|
|
1ad4ae2…
|
rberteig
|
352 |
|
|
1ad4ae2…
|
rberteig
|
353 |
### Error logging |
|
1ad4ae2…
|
rberteig
|
354 |
|
|
1ad4ae2…
|
rberteig
|
355 |
If logging errors to a file, fossil will include the values of the |
|
1ad4ae2…
|
rberteig
|
356 |
following environment variables in the error log entry if they are |
|
1ad4ae2…
|
rberteig
|
357 |
defined: `HTTP_HOST`, `HTTP_USER_AGENT`, `PATH_INFO`, `QUERY_STRING`, |
|
1ad4ae2…
|
rberteig
|
358 |
`REMOTE_ADDR`, `REQUEST_METHOD`, `REQUEST_URI`, and `SCRIPT_NAME`. |
|
1ad4ae2…
|
rberteig
|
359 |
|
|
1ad4ae2…
|
rberteig
|
360 |
|
|
1ad4ae2…
|
rberteig
|
361 |
|
|
1ad4ae2…
|
rberteig
|
362 |
### Fossil Username |
|
1ad4ae2…
|
rberteig
|
363 |
|
|
1ad4ae2…
|
rberteig
|
364 |
In absence of any explicit setting, fossil will use the same name you |
|
1ad4ae2…
|
rberteig
|
365 |
logged in to your platform with, as the user name when interacting |
|
1ad4ae2…
|
rberteig
|
366 |
with local and remote repositories. Note that only the name is shared, |
|
1ad4ae2…
|
rberteig
|
367 |
fossil makes no attempt to share or leverage any platform's |
|
1ad4ae2…
|
rberteig
|
368 |
authentication mechanisms or passwords. |
|
1ad4ae2…
|
rberteig
|
369 |
|
|
1ad4ae2…
|
rberteig
|
370 |
When logging in to a repository, it tries a series of sources for the |
|
1ad4ae2…
|
rberteig
|
371 |
user name, and the first non-blank name that succeeds is the logged in |
|
1ad4ae2…
|
rberteig
|
372 |
user. The order is: |
|
1ad4ae2…
|
rberteig
|
373 |
|
|
1ad4ae2…
|
rberteig
|
374 |
1. The --user and -U command-line options. |
|
1ad4ae2…
|
rberteig
|
375 |
2. If running within an open checkout (the local database is open), |
|
1ad4ae2…
|
rberteig
|
376 |
check in its table of values stored per open checkout for the |
|
1ad4ae2…
|
rberteig
|
377 |
value stored by `fossil user default USERNAME`. |
|
1ad4ae2…
|
rberteig
|
378 |
3. The default user in the repository (setting `default-user`) |
|
1ad4ae2…
|
rberteig
|
379 |
4. The `FOSSIL_USER` environment variable. |
|
1ad4ae2…
|
rberteig
|
380 |
5. The `USER` environment variable. |
|
1ad4ae2…
|
rberteig
|
381 |
6. The `LOGNAME` environment variable. |
|
1ad4ae2…
|
rberteig
|
382 |
7. The `USERNAME` environment variable. |
|
1ad4ae2…
|
rberteig
|
383 |
8. Check if the user can be extracted from the remote URL, if |
|
1ad4ae2…
|
rberteig
|
384 |
there is a remote URL. |
|
1ad4ae2…
|
rberteig
|
385 |
|
|
1ad4ae2…
|
rberteig
|
386 |
Items 2 and 3 are both set by `fossil user default USERNAME`, the |
|
1ad4ae2…
|
rberteig
|
387 |
first within an open checkout, the second outside and using the `-R |
|
1ad4ae2…
|
rberteig
|
388 |
REPOSITORY` option to identify the repository. Both cases require that |
|
1ad4ae2…
|
rberteig
|
389 |
the named user be present in the repository when the default user is |
|
1ad4ae2…
|
rberteig
|
390 |
assigned. Although the default user is internally stored as if it were |
|
1ad4ae2…
|
rberteig
|
391 |
a setting named `default-user`, it is not accessible through |
|
1ad4ae2…
|
rberteig
|
392 |
the `fossil set` command. |
|
1ad4ae2…
|
rberteig
|
393 |
|
|
1ad4ae2…
|
rberteig
|
394 |
Items 5, 6, and 7 cover most of the names of an environment variable |
|
1ad4ae2…
|
rberteig
|
395 |
set automatically by the platform with the name of the platform's |
|
1ad4ae2…
|
rberteig
|
396 |
logged in user for use by programs. Historically, `USER` comes from |
|
1ad4ae2…
|
rberteig
|
397 |
Unix System-V, `LOGNAME` from BSD, and `USERNAME` from Windows, but |
|
1ad4ae2…
|
rberteig
|
398 |
many Linux distributions will set both `USER` and `LOGNAME` for broad |
|
1ad4ae2…
|
rberteig
|
399 |
compatibility. |
|
1ad4ae2…
|
rberteig
|
400 |
|
|
1ad4ae2…
|
rberteig
|
401 |
When creating a new repository, fossil needs a user name for the admin |
|
1ad4ae2…
|
rberteig
|
402 |
user granted the "s" permission. But since fossil generally expects |
|
1ad4ae2…
|
rberteig
|
403 |
that `fossil new` or `fossil clone` are used outside of any checkout |
|
1ad4ae2…
|
rberteig
|
404 |
(especially when run for the first time without any checkouts at all |
|
1ad4ae2…
|
rberteig
|
405 |
or the users's global settings database), it looks in a shorter list |
|
1ad4ae2…
|
rberteig
|
406 |
of places for a non-blank name. In the special case of a clone, |
|
1ad4ae2…
|
rberteig
|
407 |
`default-user` can be copied from the original, and so it can be set |
|
1ad4ae2…
|
rberteig
|
408 |
in the clone even before any users have been created, and in that case |
|
1ad4ae2…
|
rberteig
|
409 |
it will be the new admin user. If `default-user` is not set, then the |
|
1ad4ae2…
|
rberteig
|
410 |
first found environment variable from the list `FOSSIL_USER`, `USER`, |
|
1ad4ae2…
|
rberteig
|
411 |
`LOGNAME`, and `USERNAME`, is the user name. As a final fallback, if |
|
1ad4ae2…
|
rberteig
|
412 |
none of those are set, then the default user name is "root". |
|
1ad4ae2…
|
rberteig
|
413 |
|
|
1ad4ae2…
|
rberteig
|
414 |
|
|
4645e9b…
|
drh
|
415 |
### Configuration Database Location |
|
22f879d…
|
drh
|
416 |
|
|
22f879d…
|
drh
|
417 |
Fossil keeps some information pertinent to each user in the user's |
|
22f879d…
|
drh
|
418 |
[configuration database file][configdb]. |
|
22f879d…
|
drh
|
419 |
The configuration database file includes the global settings |
|
22f879d…
|
drh
|
420 |
and the list of repositories and checkouts used by `fossil all`. |
|
22f879d…
|
drh
|
421 |
|
|
4645e9b…
|
drh
|
422 |
The location of the configuration database file depends on the |
|
e755561…
|
danield
|
423 |
operating system and on the existence of various environment |
|
4645e9b…
|
drh
|
424 |
variables and/or files. In brief, the configuration database is |
|
4645e9b…
|
drh
|
425 |
usually: |
|
4645e9b…
|
drh
|
426 |
|
|
4645e9b…
|
drh
|
427 |
* Traditional unix → "`$HOME/.fossil`" |
|
4645e9b…
|
drh
|
428 |
* Windows → "`%LOCALAPPDATA%/_fossil`" |
|
4645e9b…
|
drh
|
429 |
* [XDG-unix][xdg] → "`$HOME/.config/fossil.db`" |
|
4645e9b…
|
drh
|
430 |
|
|
4645e9b…
|
drh
|
431 |
[xdg]: https://www.freedesktop.org/wiki/ |
|
4645e9b…
|
drh
|
432 |
|
|
4645e9b…
|
drh
|
433 |
See the [configuration database location |
|
4645e9b…
|
drh
|
434 |
algorithm][configloc] discussion for full information. |
|
1ad4ae2…
|
rberteig
|
435 |
|
|
1ad4ae2…
|
rberteig
|
436 |
### SQLite VFS to use |
|
1ad4ae2…
|
rberteig
|
437 |
|
|
1ad4ae2…
|
rberteig
|
438 |
See [the SQLite documentation](http://www.sqlite.org/vfs.html) for an |
|
1ad4ae2…
|
rberteig
|
439 |
explanation of what a VFS actually is and what it does. |
|
1ad4ae2…
|
rberteig
|
440 |
|
|
1ad4ae2…
|
rberteig
|
441 |
If the default VFS underneath SQLite is not suitable, an alternative |
|
1ad4ae2…
|
rberteig
|
442 |
can be selected with either the `--vfs VFSNAME` option or the |
|
1ad4ae2…
|
rberteig
|
443 |
`FOSSIL_VFS` environment variable. The `--vfs` option takes |
|
1ad4ae2…
|
rberteig
|
444 |
precedence. |
|
1ad4ae2…
|
rberteig
|
445 |
|
|
1ad4ae2…
|
rberteig
|
446 |
|
|
93cee1f…
|
wyoung
|
447 |
### <a id="temp"></a>Temporary File Location |
|
1ad4ae2…
|
rberteig
|
448 |
|
|
006afac…
|
drh
|
449 |
Fossil places some temporary files in the checkout directory. Most notably, |
|
1ad4ae2…
|
rberteig
|
450 |
supporting files related to merge conflicts are placed in the same |
|
1ad4ae2…
|
rberteig
|
451 |
folder as the merge result. |
|
1ad4ae2…
|
rberteig
|
452 |
|
|
006afac…
|
drh
|
453 |
Other temporary files need a different home. The rules for choosing one are |
|
006afac…
|
drh
|
454 |
complicated. |
|
006afac…
|
drh
|
455 |
|
|
006afac…
|
drh
|
456 |
Fossil-specific code uses `FOSSIL_TEMP`, `TEMP`, and `TMP`, in that |
|
006afac…
|
drh
|
457 |
order. Fossil’s own test suite prepends `FOSSIL_TEST_TEMP` to that list. |
|
006afac…
|
drh
|
458 |
|
|
006afac…
|
drh
|
459 |
The underlying SQLite code uses several different path sets for its temp |
|
006afac…
|
drh
|
460 |
files, depending on the platform type. |
|
006afac…
|
drh
|
461 |
|
|
006afac…
|
drh
|
462 |
On Unix-like platforms, excepting Cygwin, SQLite first checks the |
|
006afac…
|
drh
|
463 |
environment variables `SQLITE_TMPDIR` and `TMPDIR`, in that order. If |
|
006afac…
|
drh
|
464 |
neither is defined, it falls back to a hard-coded list of paths: |
|
006afac…
|
drh
|
465 |
`/var/tmp`, `/usr/tmp`, and `/tmp`. If all of that fails, it uses the |
|
006afac…
|
drh
|
466 |
current working directory. |
|
006afac…
|
drh
|
467 |
|
|
006afac…
|
drh
|
468 |
For Cygwin builds, SQLite instead uses the first defined variable in |
|
006afac…
|
drh
|
469 |
this list: `SQLITE_TMPDIR`, `TMPDIR`, `TMP`, `TEMP`, and `USERPROFILE`. |
|
006afac…
|
drh
|
470 |
|
|
006afac…
|
drh
|
471 |
For native Windows builds, SQLite simply calls the OS’s [`GetTempPath()` |
|
006afac…
|
drh
|
472 |
API][gtp]. See that reference page for details. |
|
1ad4ae2…
|
rberteig
|
473 |
|
|
1ad4ae2…
|
rberteig
|
474 |
[gtp]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa364992%28v=vs.85%29.aspx |
|
1ad4ae2…
|
rberteig
|
475 |
|
|
1ad4ae2…
|
rberteig
|
476 |
|
|
1ad4ae2…
|
rberteig
|
477 |
|
|
1ad4ae2…
|
rberteig
|
478 |
That said, it is not unusual for utilities on all platforms to assume |
|
1ad4ae2…
|
rberteig
|
479 |
that `TEMP` or `TMP` point somewhere safe for temporary files. |
|
1ad4ae2…
|
rberteig
|
480 |
|
|
1ad4ae2…
|
rberteig
|
481 |
If the identified temporary folder is not writable, then weird things |
|
1ad4ae2…
|
rberteig
|
482 |
will happen on all platforms. |
|
1ad4ae2…
|
rberteig
|
483 |
|
|
1ad4ae2…
|
rberteig
|
484 |
|
|
1ad4ae2…
|
rberteig
|
485 |
### Web browser |
|
1ad4ae2…
|
rberteig
|
486 |
|
|
1ad4ae2…
|
rberteig
|
487 |
Occasionally, fossil wants to launch a web browser for the user, most |
|
1ad4ae2…
|
rberteig
|
488 |
obviously as part of the `fossil ui` command. In that specific case, |
|
007fd18…
|
florian
|
489 |
the browser is launched pointing at the web server started by |
|
007fd18…
|
florian
|
490 |
`fossil ui` listening on a private TCP port. |
|
1ad4ae2…
|
rberteig
|
491 |
|
|
1ad4ae2…
|
rberteig
|
492 |
On all platforms, if the local or global settings `web-browser` is |
|
285430a…
|
drh
|
493 |
set, that is the command used to open a URL. |
|
1ad4ae2…
|
rberteig
|
494 |
|
|
1ad4ae2…
|
rberteig
|
495 |
Otherwise, the specific actions vary by platform. |
|
1ad4ae2…
|
rberteig
|
496 |
|
|
1ad4ae2…
|
rberteig
|
497 |
On Unix-like platforms other than Apple's, it looks for the first |
|
1ad4ae2…
|
rberteig
|
498 |
program from the list `xdg-open`, `gnome-open`, `firefox`, and |
|
1ad4ae2…
|
rberteig
|
499 |
`google-chrome` that it can find on the `PATH`. |
|
1ad4ae2…
|
rberteig
|
500 |
|
|
285430a…
|
drh
|
501 |
On Apple platforms, it assumes that `open` is the command to open a |
|
1ad4ae2…
|
rberteig
|
502 |
URL in the user's configured default browser. |
|
1ad4ae2…
|
rberteig
|
503 |
|
|
1ad4ae2…
|
rberteig
|
504 |
On Windows platforms, it assumes that `start` is the command to open |
|
285430a…
|
drh
|
505 |
a URL in the user's configured default browser. |
|
22f879d…
|
drh
|
506 |
|
|
22f879d…
|
drh
|
507 |
[configdb]: ./tech_overview.wiki#configdb |
|
22f879d…
|
drh
|
508 |
[configloc]: ./tech_overview.wiki#configloc |
|
c591bbe…
|
florian
|
509 |
[cgictlfile]: ./cgi.wiki |