Fossil SCM

fossil-scm / www / env-opts.md
Source Blame History 509 lines
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

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button