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