Fossil

Check-in [3b5ff98c]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Checkpoint after a first pass through every call to ...getenv() in src/*.c to list environment variables mentioned. Every variable has a very rough draft description. Every global command option is listed, but not all have even a rough draft description yet.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | ross-doc-env
Files: files | file ages | folders
SHA1:3b5ff98cf04e1e64297144832560783c6c376f24
User & Date: rberteig 2016-02-28 02:46:21
Context
2016-02-29
01:16
Minor correction for FOSSIL_TCL_PATH. check-in: afe7b547 user: mistachkin tags: ross-doc-env
2016-02-28
02:46
Checkpoint after a first pass through every call to ...getenv() in src/*.c to list environment variables mentioned. Every variable has a very rough draft description. Every global command option is listed, but not all have even a rough draft description yet. check-in: 3b5ff98c user: rberteig tags: ross-doc-env
2016-02-27
07:06
Fix incorrect build instruction at the top of mkindex.tcl. check-in: 4e89aee8 user: rberteig tags: ross-doc-env
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to www/env-opts.md.

18
19
20
21
22
23
24
25
26




27
28


29
30
31
32
33
34
35
..
74
75
76
77
78
79
80













81
82
83
84
85
86
87
88
89
90
91
92




93
94
95
96
97
98
99
...
106
107
108
109
110
111
112




113
114
115
116
117
118
119
...
141
142
143
144
145
146
147
148







149
150
151
152
153
154
155
...
166
167
168
169
170
171
172








173
174
175
176
177
178


179
180
181
182
183
184
185
...
236
237
238
239
240
241
242


243
244
245
246
247
248
249
...
254
255
256
257
258
259
260



























261
262
263
264
265
266
267
...
273
274
275
276
277
278
279








280
281
282
283
284
285
286
...
294
295
296
297
298
299
300
301



302
303
304
305
306
307
308
309
310
311
312


313
314
315
316
317
318
319
`--args FILENAME`: Read the file `FILENAME` and replace these two
arguments with its content. Each line of the file is assumed to be an
argument unless it starts with '-' and contains a space, in which case
it is assumed to be another flag and is treated as such. `--args
FILENAME` may be used in conjunction with any other flags.

`--case-sensitive BOOL`: Override the `case-sensitive` setting, which
can override the native preferences of the platform: insensitive on
WIndows, sensitive on Unix.





`--chdir DIRECTORY`:



`--comfmtflags NUMBER`:


`--errorlog ERRLOG`:

`--help`: If `--help` is found anywhere on the command line, translate
................................................................................
`FOSSIL_HOME`, `LOCALAPPDATA` (Windows), `APPDATA` (Windows),
`HOMEDRIVE` and `HOMEPATH` (Windows, used together), and `HOME` is
used as the location of the `~/.fossil` file. 

`EDITOR`: Name the editor to use for check-in and stash comments.
Overridden by the local or global `editor` setting or the `VISUAL`
environment variable.














`FOSSIL_HOME`: Location of the `~/.fossil` file. The first environment
variable found in the environment from the list `FOSSIL_HOME`,
`LOCALAPPDATA` (Windows), `APPDATA` (Windows), `HOMEDRIVE` and
`HOMEPATH` (Windows, used together), and `HOME` is used as the
location of the `~/.fossil` file. 

`FOSSIL_USER`: Name of the default user account if the local or global
`default-user` setting is not present. The first environment variable
found in the environment from the list `FOSSIL_USER`, `USERNAME`
(Windows), `USER`, and `LOGNAME` is the user name. If none of those
are set, then the default user name is "root".





`FOSSIL_VFS`: Name a VFS to load into SQLite. 

`GATEWAY_INTERFACE`: If present and the `--nocgi` option is not, assume
fossil is invoked from a web server as a CGI command, and act
accordingly.

................................................................................
`HOMEDRIVE`, `HOMEPATH`: (Windows) Location of the `~/.fossil` file.
The first environment variable found in the environment from the list
`FOSSIL_HOME`, `LOCALAPPDATA` (Windows), `APPDATA` (Windows),
`HOMEDRIVE` and `HOMEPATH` (Windows, used together), and `HOME` is
used as the location of the `~/.fossil` file. 

`HTTP_HOST`: If defined, included in error log messages.





`HTTP_USER_AGENT`: If defined, included in error log messages.


`LOCALAPPDATA`: (Windows) Location of the `~/.fossil` file. The first
environment variable found in the environment from the list
`FOSSIL_HOME`, `LOCALAPPDATA` (Windows), `APPDATA` (Windows),
................................................................................

`REQUEST_METHOD`: If defined, included in error log messages.

`REQUEST_URI`: If defined, included in error log messages.

`SCRIPT_NAME`: If defined, included in error log messages.

`SSH_CONNECTION`:








`SYSTEMROOT`: (Windows) Used to locate `notepad.exe` as a
fall back comment editor.

`TEMP`: On Windows, the location of temporary files. The first
environment variable found in the environment that names an existing
directory from the list `TMP`, `TEMP`, `USERPROFILE`, the Windows
................................................................................
`TH1_DELETE_INTERP`: Set this variable to ask fossil to explicitly
delete the TH1 interpreter, if it is loaded, then check that it
released all of its allocated memory, when exiting fossil. This is not
strictly necessary, but makes debugging memory leaks easier. See
[main.c near line 386](/artifact/e75796be5338a81c?ln=386,391) for the
code.










`TMP`: On Windows, the location of temporary files. The first
environment variable found in the environment that names an existing
directory from the list `TMP`, `TEMP`, `USERPROFILE`, the Windows
directory (usually `C:\WINDOWS`), `TEMP`, `TMP`, and the current
directory (aka `.`) is the temporary folder. 




`USER`: Name of the default user account if the local or global
`default-user` setting is not present. The first environment variable
found in the environment from the list `FOSSIL_USER`, `USERNAME`
(Windows), `USER`, and `LOGNAME` is the user name. If none of those
are set, then the default user name is "root".
................................................................................

On Unix-like platforms, if no editor is named, then a message is
displayed on stdout, and stdin is read until a single line containing
only a dot is seen.


### Default Username



When creating a new repository, fossil wants to guess a sensible user
name to make the default user granted the "s" permission.

Fossil will use the setting `default-user` if set. Normally, a local
setting would override a global setting, but when creating a new
repository it is more than a little unlikely that there is an open
................................................................................
directory inside a checkout regardless of whether the created repo
will be nested.

If `default-user` is not set, then the first found environment
variable from the list `FOSSIL_USER`, `USERNAME` (Windows), `USER`,
and `LOGNAME` is the user name. If none of those are set, then the
default user name is "root".




























### Error logging

If logging errors to a file, fossil will include the values of the
following environment variables in the error log entry if they are
defined: `HTTP_HOST`, `HTTP_USER_AGENT`, `PATH_INFO`, `QUERY_STRING`,
`REMOTE_ADDR`, `REQUEST_METHOD`, `REQUEST_URI`, and `SCRIPT_NAME`. 
................................................................................
home directory. This includes the global settings and the list of
repositories and checkouts used by `fossil all`.

The user's home directory is specified by the first environment
variable found in the environment from the list `FOSSIL_HOME`,
`LOCALAPPDATA` (Windows), `APPDATA` (Windows), `HOMEDRIVE` and
`HOMEPATH` (Windows, used together), and `HOME`. 









### SQLite VFS to use

See [the SQLite documentation](http://www.sqlite.org/vfs.html) for an
explanation of what a VFS actually is and what it does.

If the default VFS underneath SQLite is not suitable, an alternative
................................................................................
Fossil places some temporary files in the current directory, notably
supporting files related to merge conflicts are placed in the same
folder as the merge result.

Other temporary files need a home. On Unix-like systems, the first
folder from the hard coded list `/var/tmp`, `/usr/tmp`, `/tmp`,
`/temp`, and `.` that is found to exist in the file system is used by
fossil. 




On Windows, fossil calls [`GetTempPath`][gtp], and also queries the
environment variables `TEMP`, and `TMP`. If none of those three places
exist, then it uses `.`. Notice that `GetTempPath` itself used `TMP`,
`TEMP`, `USERPROFILE`, and the Windows folder (named in the variable
`SystemRoot`). Since the Windows folder always exists, but in modern
versions of Windows is generally *not* writable by the logged in user,
not having `TEMP`, `TMP`, or `USERPROFILE` set is almost guaranteed to
cause trouble.

[gtp]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa364992%28v=vs.85%29.aspx 



That said, it is not unusual for utilities on all platforms to assume
that `TEMP` or `TMP` point somewhere safe for temporary files.

If the identified temporary folder is not writable, then weird things
will happen on all platforms.








|
|
>
>
>
>

|
>
>







 







>
>
>
>
>
>
>
>
>
>
>
>
>












>
>
>
>







 







>
>
>
>







 







|
>
>
>
>
>
>
>







 







>
>
>
>
>
>
>
>






>
>







 







>
>







 







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







 







>
>
>
>
>
>
>
>







 







|
>
>
>











>
>







18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
..
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
...
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
...
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
...
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
...
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
...
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
...
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
...
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
`--args FILENAME`: Read the file `FILENAME` and replace these two
arguments with its content. Each line of the file is assumed to be an
argument unless it starts with '-' and contains a space, in which case
it is assumed to be another flag and is treated as such. `--args
FILENAME` may be used in conjunction with any other flags.

`--case-sensitive BOOL`: Override the `case-sensitive` setting, which
can override the native preferences of the platform for case sensitive
file names: insensitive on Windows, sensitive on Unix. There are
probably odd interactions possible if you mix case sensitive and case
insensitive file systems on any single platform. This option or the
global setting should be used to force the case sensitivity to the
most sensible condition. 

`--chdir DIRECTORY`: 



`--comfmtflags NUMBER`:


`--errorlog ERRLOG`:

`--help`: If `--help` is found anywhere on the command line, translate
................................................................................
`FOSSIL_HOME`, `LOCALAPPDATA` (Windows), `APPDATA` (Windows),
`HOMEDRIVE` and `HOMEPATH` (Windows, used together), and `HOME` is
used as the location of the `~/.fossil` file. 

`EDITOR`: Name the editor to use for check-in and stash comments.
Overridden by the local or global `editor` setting or the `VISUAL`
environment variable.

`FOSSIL_FORCE_TICKET_MODERATION`: If set, *ALL* changes for tickets
will be required to go through moderation (even those performed by the
local interactive user via the command line).  This can be useful for
local (or remote) testing of the moderation subsystem and its impact
on the contents and status of tickets.

`FOSSIL_FORCE_WIKI_MODERATION`: If set, *ALL* changes for wiki pages
will be required to go through moderation (even those performed by the
local interactive user via the command line).  This can be useful for
local (or remote) testing of the moderation subsystem and its impact
on the contents and status of wiki pages.


`FOSSIL_HOME`: Location of the `~/.fossil` file. The first environment
variable found in the environment from the list `FOSSIL_HOME`,
`LOCALAPPDATA` (Windows), `APPDATA` (Windows), `HOMEDRIVE` and
`HOMEPATH` (Windows, used together), and `HOME` is used as the
location of the `~/.fossil` file. 

`FOSSIL_USER`: Name of the default user account if the local or global
`default-user` setting is not present. The first environment variable
found in the environment from the list `FOSSIL_USER`, `USERNAME`
(Windows), `USER`, and `LOGNAME` is the user name. If none of those
are set, then the default user name is "root".

`FOSSIL_TCL_PATH`: When Tcl stubs support is configured, point to a
specific folder containing the version of Tcl to load at run time.


`FOSSIL_VFS`: Name a VFS to load into SQLite. 

`GATEWAY_INTERFACE`: If present and the `--nocgi` option is not, assume
fossil is invoked from a web server as a CGI command, and act
accordingly.

................................................................................
`HOMEDRIVE`, `HOMEPATH`: (Windows) Location of the `~/.fossil` file.
The first environment variable found in the environment from the list
`FOSSIL_HOME`, `LOCALAPPDATA` (Windows), `APPDATA` (Windows),
`HOMEDRIVE` and `HOMEPATH` (Windows, used together), and `HOME` is
used as the location of the `~/.fossil` file. 

`HTTP_HOST`: If defined, included in error log messages.

`http_proxy`: If the global or local settings `proxy` is not set, this
is used as the default value for the `proxy` setting.


`HTTP_USER_AGENT`: If defined, included in error log messages.


`LOCALAPPDATA`: (Windows) Location of the `~/.fossil` file. The first
environment variable found in the environment from the list
`FOSSIL_HOME`, `LOCALAPPDATA` (Windows), `APPDATA` (Windows),
................................................................................

`REQUEST_METHOD`: If defined, included in error log messages.

`REQUEST_URI`: If defined, included in error log messages.

`SCRIPT_NAME`: If defined, included in error log messages.

`SSH_CONNECTION`: Informs CGI processing if the remote client is SSH.

`SQLITE_FORCE_PROXY_LOCKING`: From `sqlite3.c`, 1 means force always
use proxy, 0 means never use proxy, and undefined means use proxy for
non-local files only.

`SQLITE_TMPDIR`: Names the temporary file location to SQLite. 


`SYSTEMROOT`: (Windows) Used to locate `notepad.exe` as a
fall back comment editor.

`TEMP`: On Windows, the location of temporary files. The first
environment variable found in the environment that names an existing
directory from the list `TMP`, `TEMP`, `USERPROFILE`, the Windows
................................................................................
`TH1_DELETE_INTERP`: Set this variable to ask fossil to explicitly
delete the TH1 interpreter, if it is loaded, then check that it
released all of its allocated memory, when exiting fossil. This is not
strictly necessary, but makes debugging memory leaks easier. See
[main.c near line 386](/artifact/e75796be5338a81c?ln=386,391) for the
code.

`TH1_ENABLE_DOCS`: Override the local or global setting `tcl-docs`
to enable TH1 documents in fossil.

`TH1_ENABLE_HOOKS`: Override the local or global setting `tcl-hooks`
to enable TH1 hooks in fossil.

`TH1_ENABLE_TCL`: Override the local or global setting `tcl` to enable
TCL in fossil.

`TMP`: On Windows, the location of temporary files. The first
environment variable found in the environment that names an existing
directory from the list `TMP`, `TEMP`, `USERPROFILE`, the Windows
directory (usually `C:\WINDOWS`), `TEMP`, `TMP`, and the current
directory (aka `.`) is the temporary folder. 

`TMPDIR`: Names the temporary file location to SQLite.


`USER`: Name of the default user account if the local or global
`default-user` setting is not present. The first environment variable
found in the environment from the list `FOSSIL_USER`, `USERNAME`
(Windows), `USER`, and `LOGNAME` is the user name. If none of those
are set, then the default user name is "root".
................................................................................

On Unix-like platforms, if no editor is named, then a message is
displayed on stdout, and stdin is read until a single line containing
only a dot is seen.


### Default Username



When creating a new repository, fossil wants to guess a sensible user
name to make the default user granted the "s" permission.

Fossil will use the setting `default-user` if set. Normally, a local
setting would override a global setting, but when creating a new
repository it is more than a little unlikely that there is an open
................................................................................
directory inside a checkout regardless of whether the created repo
will be nested.

If `default-user` is not set, then the first found environment
variable from the list `FOSSIL_USER`, `USERNAME` (Windows), `USER`,
and `LOGNAME` is the user name. If none of those are set, then the
default user name is "root".


**TODO** Compare `db_create_default_users()` in `db.c` to
`user_select()` in `user.c` which checks in a different order...

Figure out what user is at the controls.

   1.  Use the --user and -U command-line options.

   2.  If the local database is open, check in VVAR.   ???

   3.  Check the default user in the repository (setting
   `default-user`)

   4.  Try the `FOSSIL_USER` environment variable.

   5.  Try the `USER` environment variable.

   6.  Try the `LOGNAME` environment variable.

   7.  Try the `USERNAME` environment variable.

   8.  Check if the user can be extracted from the remote URL, if
   there is a remote URL.




### Error logging

If logging errors to a file, fossil will include the values of the
following environment variables in the error log entry if they are
defined: `HTTP_HOST`, `HTTP_USER_AGENT`, `PATH_INFO`, `QUERY_STRING`,
`REMOTE_ADDR`, `REQUEST_METHOD`, `REQUEST_URI`, and `SCRIPT_NAME`. 
................................................................................
home directory. This includes the global settings and the list of
repositories and checkouts used by `fossil all`.

The user's home directory is specified by the first environment
variable found in the environment from the list `FOSSIL_HOME`,
`LOCALAPPDATA` (Windows), `APPDATA` (Windows), `HOMEDRIVE` and
`HOMEPATH` (Windows, used together), and `HOME`. 

SQLite has its own notion of the user's home directory, which is only
exposed if the interactive SQL shell is run with the "fossil
sqlite3" command. Being a separate library, SQLite uses many of the
same variables to find the home directory, but uses them in a
different order, and does not use the `FOSSIL_HOME` variable at all.



### SQLite VFS to use

See [the SQLite documentation](http://www.sqlite.org/vfs.html) for an
explanation of what a VFS actually is and what it does.

If the default VFS underneath SQLite is not suitable, an alternative
................................................................................
Fossil places some temporary files in the current directory, notably
supporting files related to merge conflicts are placed in the same
folder as the merge result.

Other temporary files need a home. On Unix-like systems, the first
folder from the hard coded list `/var/tmp`, `/usr/tmp`, `/tmp`,
`/temp`, and `.` that is found to exist in the file system is used by
fossil. The SQLite library has its own code for finding a safe place for
temporary files. It checks the environment variables `SQLITE_TMPDIR`
and `TMPDIR` ahead of the hard coded list `/var/tmp`, `/usr/tmp`,
`/tmp`, and `.` for the first directory that exists.

On Windows, fossil calls [`GetTempPath`][gtp], and also queries the
environment variables `TEMP`, and `TMP`. If none of those three places
exist, then it uses `.`. Notice that `GetTempPath` itself used `TMP`,
`TEMP`, `USERPROFILE`, and the Windows folder (named in the variable
`SystemRoot`). Since the Windows folder always exists, but in modern
versions of Windows is generally *not* writable by the logged in user,
not having `TEMP`, `TMP`, or `USERPROFILE` set is almost guaranteed to
cause trouble.

[gtp]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa364992%28v=vs.85%29.aspx 



That said, it is not unusual for utilities on all platforms to assume
that `TEMP` or `TMP` point somewhere safe for temporary files.

If the identified temporary folder is not writable, then weird things
will happen on all platforms.