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

Overview
Comment:Rewrite the section on fossil usernames selection, fix typos and improve wording here and there.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | ross-doc-env
Files: files | file ages | folders
SHA1:83153a97b75636f3c76b464814af7fbc88d435e2
User & Date: rberteig 2016-03-02 01:57:30
Context
2016-03-02
02:21
Tweak descriptions of FOSSIL_USER, LOGNAME, USER, and USERNAME environment variables. Closed-Leaf check-in: 809e80a1 user: rberteig tags: ross-doc-env
01:57
Rewrite the section on fossil usernames selection, fix typos and improve wording here and there. check-in: 83153a97 user: rberteig tags: ross-doc-env
01:56
Add new test-usernames command to dump all of the various sources of the current user name in the order tested. check-in: 5de13cb1 user: rberteig tags: ross-doc-env
Changes

Changes to www/env-opts.md.

78
79
80
81
82
83
84
85

86
87
88
89
90
91
92
...
274
275
276
277
278
279
280
281
282
283
284

285
286
287
288
289
290
291
...
298
299
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
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361





362
363
364
365
366
367
368
`--sshtrace`: (Sets `g.fSshTrace`.)

`--ssl-identity SSLIDENTITY`:

`--systemtrace`: (Sets `g.fSystemTrace`.) Trace all commands launched
as sub processes.

`--user LOGIN`: Also `-U LOGIN`. Set the user name.


`--utc`: Override the `timeline-utc` option to explicitly use
UTC time.

`--vfs VFSNAME`: Load the named VFS into SQLite.


................................................................................
-----------------------

### CGI and JSON Parameters


The JSON API implementation looks up many values in the first of
several places searched. This unifies the parameter handling logic,
allows the caller to choose whether to prefer URL parameters or the
POST payload, and allows the `fossil json` command to share most of
the same logic as the `/json` API path. The search order is a POST
payload, GET/COOKIE/non-JSON POST, JSON POST, the system environment.


See the comment above the implementation of [`json_getenv`][json.c]
for some further discussion.

[json.c]: /artifact/6df1d80dece8968b?ln=277,290

### Comment Editor
................................................................................
operation will be aborted if `notepad.exe` is not found in the Windows
folder.

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
checkout to provide the local setting.

**TODO:** Any interaction caused by nesting repositories is not
documented, but should be. Similarly for simply having the current
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

Fossil keeps some information interesting to each user in the user's
home directory. This includes the global settings and the list of
repositories and checkouts used by `fossil all`.








|
>







 







|
|
|
|
>







 







|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
>
>
>
>
>







78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
...
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
...
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
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
`--sshtrace`: (Sets `g.fSshTrace`.)

`--ssl-identity SSLIDENTITY`:

`--systemtrace`: (Sets `g.fSystemTrace`.) Trace all commands launched
as sub processes.

`--user LOGIN`: (Sets `g.zLogin`) Also `-U LOGIN`. Set the user name
used with the repository.

`--utc`: Override the `timeline-utc` option to explicitly use
UTC time.

`--vfs VFSNAME`: Load the named VFS into SQLite.


................................................................................
-----------------------

### CGI and JSON Parameters


The JSON API implementation looks up many values in the first of
several places searched. This unifies the parameter handling logic,
allows the caller to choose whether to prefer URL parameters, request
headers, or the POST payload, and allows the `fossil json` command to
share most of the same logic as the `/json` API path. The search order
is a POST payload, GET/COOKIE/non-JSON POST, JSON POST, the system
environment.

See the comment above the implementation of [`json_getenv`][json.c]
for some further discussion.

[json.c]: /artifact/6df1d80dece8968b?ln=277,290

### Comment Editor
................................................................................
operation will be aborted if `notepad.exe` is not found in the Windows
folder.

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.


### 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`.



### Fossil Username

In absence of any explicit setting, fossil will use the same name you
logged in to your platform with, as the user name when interacting
with local and remote repositories. Note that only the name is shared,
fossil makes no attempt to share or leverage any platform's
authentication mechanisms or passwords.

When logging in to a repository, it tries a series of sources for the
user name, and the first non-blank name that succeeds is the logged in
user. The order is:

1.  The --user and -U command-line options.
2.  If running within an open checkout (the local database is open),
    check in its table of values stored per open checkout for the
    value stored by `fossil user default USERNAME`.
3.  The default user in the repository (setting `default-user`)
4.  The `FOSSIL_USER` environment variable.
5.  The `USER` environment variable.
6.  The `LOGNAME` environment variable.
7.  The `USERNAME` environment variable.
8.  Check if the user can be extracted from the remote URL, if
    there is a remote URL.

Items 2 and 3 are both set by `fossil user default USERNAME`, the
first within an open checkout, the second outside and using the `-R
REPOSITORY` option to identify the repository. Both cases require that
the named user be present in the repository when the default user is
assigned. Although the default user is internally stored as if it were
a setting named `default-user`, it is not accessible through
the `fossil set` command.

Items 5, 6, and 7 cover most of the names of an environment variable
set automatically by the platform with the name of the platform's
logged in user for use by programs. Historically, `USER` comes from
Unix System-V, `LOGNAME` from BSD, and `USERNAME` from Windows, but
many Linux distributions will set both `USER` and `LOGNAME` for broad
compatibility.

When creating a new repository, fossil needs a user name for the admin
user granted the "s" permission. But since fossil generally expects
that `fossil new` or `fossil clone` are used outside of any checkout
(especially when run for the first time without any checkouts at all
or the users's global settings database), it looks in a shorter list
of places for a non-blank name. In the special case of a clone,
`default-user` can be copied from the original, and so it can be set
in the clone even before any users have been created, and in that case
it will be the new admin user. If `default-user` is not set, then the
first found environment variable from the list `FOSSIL_USER`, `USER`,
`LOGNAME`, and `USERNAME`, is the user name. As a final fallback, if
none of those are set, then the default user name is "root".


### Home Directory

Fossil keeps some information interesting to each user in the user's
home directory. This includes the global settings and the list of
repositories and checkouts used by `fossil all`.