Fossil SCM
Rewrite the section on fossil usernames selection, fix typos and improve wording here and there.
Commit
83153a97b75636f3c76b464814af7fbc88d435e2
Parent
5de13cb19cf06c7…
1 file changed
+61
-54
+61
-54
| --- www/env-opts.md | ||
| +++ www/env-opts.md | ||
| @@ -80,11 +80,12 @@ | ||
| 80 | 80 | `--ssl-identity SSLIDENTITY`: |
| 81 | 81 | |
| 82 | 82 | `--systemtrace`: (Sets `g.fSystemTrace`.) Trace all commands launched |
| 83 | 83 | as sub processes. |
| 84 | 84 | |
| 85 | -`--user LOGIN`: Also `-U LOGIN`. Set the user name. | |
| 85 | +`--user LOGIN`: (Sets `g.zLogin`) Also `-U LOGIN`. Set the user name | |
| 86 | +used with the repository. | |
| 86 | 87 | |
| 87 | 88 | `--utc`: Override the `timeline-utc` option to explicitly use |
| 88 | 89 | UTC time. |
| 89 | 90 | |
| 90 | 91 | `--vfs VFSNAME`: Load the named VFS into SQLite. |
| @@ -276,14 +277,15 @@ | ||
| 276 | 277 | ### CGI and JSON Parameters |
| 277 | 278 | |
| 278 | 279 | |
| 279 | 280 | The JSON API implementation looks up many values in the first of |
| 280 | 281 | several places searched. This unifies the parameter handling logic, |
| 281 | -allows the caller to choose whether to prefer URL parameters or the | |
| 282 | -POST payload, and allows the `fossil json` command to share most of | |
| 283 | -the same logic as the `/json` API path. The search order is a POST | |
| 284 | -payload, GET/COOKIE/non-JSON POST, JSON POST, the system environment. | |
| 282 | +allows the caller to choose whether to prefer URL parameters, request | |
| 283 | +headers, or the POST payload, and allows the `fossil json` command to | |
| 284 | +share most of the same logic as the `/json` API path. The search order | |
| 285 | +is a POST payload, GET/COOKIE/non-JSON POST, JSON POST, the system | |
| 286 | +environment. | |
| 285 | 287 | |
| 286 | 288 | See the comment above the implementation of [`json_getenv`][json.c] |
| 287 | 289 | for some further discussion. |
| 288 | 290 | |
| 289 | 291 | [json.c]: /artifact/6df1d80dece8968b?ln=277,290 |
| @@ -300,67 +302,72 @@ | ||
| 300 | 302 | |
| 301 | 303 | On Unix-like platforms, if no editor is named, then a message is |
| 302 | 304 | displayed on stdout, and stdin is read until a single line containing |
| 303 | 305 | only a dot is seen. |
| 304 | 306 | |
| 305 | - | |
| 306 | -### Default Username | |
| 307 | - | |
| 308 | - | |
| 309 | - | |
| 310 | -When creating a new repository, fossil wants to guess a sensible user | |
| 311 | -name to make the default user granted the "s" permission. | |
| 312 | - | |
| 313 | -Fossil will use the setting `default-user` if set. Normally, a local | |
| 314 | -setting would override a global setting, but when creating a new | |
| 315 | -repository it is more than a little unlikely that there is an open | |
| 316 | -checkout to provide the local setting. | |
| 317 | - | |
| 318 | -**TODO:** Any interaction caused by nesting repositories is not | |
| 319 | -documented, but should be. Similarly for simply having the current | |
| 320 | -directory inside a checkout regardless of whether the created repo | |
| 321 | -will be nested. | |
| 322 | - | |
| 323 | -If `default-user` is not set, then the first found environment | |
| 324 | -variable from the list `FOSSIL_USER`, `USERNAME` (Windows), `USER`, | |
| 325 | -and `LOGNAME` is the user name. If none of those are set, then the | |
| 326 | -default user name is "root". | |
| 327 | - | |
| 328 | - | |
| 329 | -**TODO** Compare `db_create_default_users()` in `db.c` to | |
| 330 | -`user_select()` in `user.c` which checks in a different order... | |
| 331 | - | |
| 332 | -Figure out what user is at the controls. | |
| 333 | - | |
| 334 | - 1. Use the --user and -U command-line options. | |
| 335 | - | |
| 336 | - 2. If the local database is open, check in VVAR. ??? | |
| 337 | - | |
| 338 | - 3. Check the default user in the repository (setting | |
| 339 | - `default-user`) | |
| 340 | - | |
| 341 | - 4. Try the `FOSSIL_USER` environment variable. | |
| 342 | - | |
| 343 | - 5. Try the `USER` environment variable. | |
| 344 | - | |
| 345 | - 6. Try the `LOGNAME` environment variable. | |
| 346 | - | |
| 347 | - 7. Try the `USERNAME` environment variable. | |
| 348 | - | |
| 349 | - 8. Check if the user can be extracted from the remote URL, if | |
| 350 | - there is a remote URL. | |
| 351 | - | |
| 352 | - | |
| 353 | - | |
| 354 | 307 | |
| 355 | 308 | ### Error logging |
| 356 | 309 | |
| 357 | 310 | If logging errors to a file, fossil will include the values of the |
| 358 | 311 | following environment variables in the error log entry if they are |
| 359 | 312 | defined: `HTTP_HOST`, `HTTP_USER_AGENT`, `PATH_INFO`, `QUERY_STRING`, |
| 360 | 313 | `REMOTE_ADDR`, `REQUEST_METHOD`, `REQUEST_URI`, and `SCRIPT_NAME`. |
| 361 | 314 | |
| 315 | + | |
| 316 | + | |
| 317 | +### Fossil Username | |
| 318 | + | |
| 319 | +In absence of any explicit setting, fossil will use the same name you | |
| 320 | +logged in to your platform with, as the user name when interacting | |
| 321 | +with local and remote repositories. Note that only the name is shared, | |
| 322 | +fossil makes no attempt to share or leverage any platform's | |
| 323 | +authentication mechanisms or passwords. | |
| 324 | + | |
| 325 | +When logging in to a repository, it tries a series of sources for the | |
| 326 | +user name, and the first non-blank name that succeeds is the logged in | |
| 327 | +user. The order is: | |
| 328 | + | |
| 329 | +1. The --user and -U command-line options. | |
| 330 | +2. If running within an open checkout (the local database is open), | |
| 331 | + check in its table of values stored per open checkout for the | |
| 332 | + value stored by `fossil user default USERNAME`. | |
| 333 | +3. The default user in the repository (setting `default-user`) | |
| 334 | +4. The `FOSSIL_USER` environment variable. | |
| 335 | +5. The `USER` environment variable. | |
| 336 | +6. The `LOGNAME` environment variable. | |
| 337 | +7. The `USERNAME` environment variable. | |
| 338 | +8. Check if the user can be extracted from the remote URL, if | |
| 339 | + there is a remote URL. | |
| 340 | + | |
| 341 | +Items 2 and 3 are both set by `fossil user default USERNAME`, the | |
| 342 | +first within an open checkout, the second outside and using the `-R | |
| 343 | +REPOSITORY` option to identify the repository. Both cases require that | |
| 344 | +the named user be present in the repository when the default user is | |
| 345 | +assigned. Although the default user is internally stored as if it were | |
| 346 | +a setting named `default-user`, it is not accessible through | |
| 347 | +the `fossil set` command. | |
| 348 | + | |
| 349 | +Items 5, 6, and 7 cover most of the names of an environment variable | |
| 350 | +set automatically by the platform with the name of the platform's | |
| 351 | +logged in user for use by programs. Historically, `USER` comes from | |
| 352 | +Unix System-V, `LOGNAME` from BSD, and `USERNAME` from Windows, but | |
| 353 | +many Linux distributions will set both `USER` and `LOGNAME` for broad | |
| 354 | +compatibility. | |
| 355 | + | |
| 356 | +When creating a new repository, fossil needs a user name for the admin | |
| 357 | +user granted the "s" permission. But since fossil generally expects | |
| 358 | +that `fossil new` or `fossil clone` are used outside of any checkout | |
| 359 | +(especially when run for the first time without any checkouts at all | |
| 360 | +or the users's global settings database), it looks in a shorter list | |
| 361 | +of places for a non-blank name. In the special case of a clone, | |
| 362 | +`default-user` can be copied from the original, and so it can be set | |
| 363 | +in the clone even before any users have been created, and in that case | |
| 364 | +it will be the new admin user. If `default-user` is not set, then the | |
| 365 | +first found environment variable from the list `FOSSIL_USER`, `USER`, | |
| 366 | +`LOGNAME`, and `USERNAME`, is the user name. As a final fallback, if | |
| 367 | +none of those are set, then the default user name is "root". | |
| 368 | + | |
| 362 | 369 | |
| 363 | 370 | ### Home Directory |
| 364 | 371 | |
| 365 | 372 | Fossil keeps some information interesting to each user in the user's |
| 366 | 373 | home directory. This includes the global settings and the list of |
| 367 | 374 |
| --- www/env-opts.md | |
| +++ www/env-opts.md | |
| @@ -80,11 +80,12 @@ | |
| 80 | `--ssl-identity SSLIDENTITY`: |
| 81 | |
| 82 | `--systemtrace`: (Sets `g.fSystemTrace`.) Trace all commands launched |
| 83 | as sub processes. |
| 84 | |
| 85 | `--user LOGIN`: Also `-U LOGIN`. Set the user name. |
| 86 | |
| 87 | `--utc`: Override the `timeline-utc` option to explicitly use |
| 88 | UTC time. |
| 89 | |
| 90 | `--vfs VFSNAME`: Load the named VFS into SQLite. |
| @@ -276,14 +277,15 @@ | |
| 276 | ### CGI and JSON Parameters |
| 277 | |
| 278 | |
| 279 | The JSON API implementation looks up many values in the first of |
| 280 | several places searched. This unifies the parameter handling logic, |
| 281 | allows the caller to choose whether to prefer URL parameters or the |
| 282 | POST payload, and allows the `fossil json` command to share most of |
| 283 | the same logic as the `/json` API path. The search order is a POST |
| 284 | payload, GET/COOKIE/non-JSON POST, JSON POST, the system environment. |
| 285 | |
| 286 | See the comment above the implementation of [`json_getenv`][json.c] |
| 287 | for some further discussion. |
| 288 | |
| 289 | [json.c]: /artifact/6df1d80dece8968b?ln=277,290 |
| @@ -300,67 +302,72 @@ | |
| 300 | |
| 301 | On Unix-like platforms, if no editor is named, then a message is |
| 302 | displayed on stdout, and stdin is read until a single line containing |
| 303 | only a dot is seen. |
| 304 | |
| 305 | |
| 306 | ### Default Username |
| 307 | |
| 308 | |
| 309 | |
| 310 | When creating a new repository, fossil wants to guess a sensible user |
| 311 | name to make the default user granted the "s" permission. |
| 312 | |
| 313 | Fossil will use the setting `default-user` if set. Normally, a local |
| 314 | setting would override a global setting, but when creating a new |
| 315 | repository it is more than a little unlikely that there is an open |
| 316 | checkout to provide the local setting. |
| 317 | |
| 318 | **TODO:** Any interaction caused by nesting repositories is not |
| 319 | documented, but should be. Similarly for simply having the current |
| 320 | directory inside a checkout regardless of whether the created repo |
| 321 | will be nested. |
| 322 | |
| 323 | If `default-user` is not set, then the first found environment |
| 324 | variable from the list `FOSSIL_USER`, `USERNAME` (Windows), `USER`, |
| 325 | and `LOGNAME` is the user name. If none of those are set, then the |
| 326 | default user name is "root". |
| 327 | |
| 328 | |
| 329 | **TODO** Compare `db_create_default_users()` in `db.c` to |
| 330 | `user_select()` in `user.c` which checks in a different order... |
| 331 | |
| 332 | Figure out what user is at the controls. |
| 333 | |
| 334 | 1. Use the --user and -U command-line options. |
| 335 | |
| 336 | 2. If the local database is open, check in VVAR. ??? |
| 337 | |
| 338 | 3. Check the default user in the repository (setting |
| 339 | `default-user`) |
| 340 | |
| 341 | 4. Try the `FOSSIL_USER` environment variable. |
| 342 | |
| 343 | 5. Try the `USER` environment variable. |
| 344 | |
| 345 | 6. Try the `LOGNAME` environment variable. |
| 346 | |
| 347 | 7. Try the `USERNAME` environment variable. |
| 348 | |
| 349 | 8. Check if the user can be extracted from the remote URL, if |
| 350 | there is a remote URL. |
| 351 | |
| 352 | |
| 353 | |
| 354 | |
| 355 | ### Error logging |
| 356 | |
| 357 | If logging errors to a file, fossil will include the values of the |
| 358 | following environment variables in the error log entry if they are |
| 359 | defined: `HTTP_HOST`, `HTTP_USER_AGENT`, `PATH_INFO`, `QUERY_STRING`, |
| 360 | `REMOTE_ADDR`, `REQUEST_METHOD`, `REQUEST_URI`, and `SCRIPT_NAME`. |
| 361 | |
| 362 | |
| 363 | ### Home Directory |
| 364 | |
| 365 | Fossil keeps some information interesting to each user in the user's |
| 366 | home directory. This includes the global settings and the list of |
| 367 |
| --- www/env-opts.md | |
| +++ www/env-opts.md | |
| @@ -80,11 +80,12 @@ | |
| 80 | `--ssl-identity SSLIDENTITY`: |
| 81 | |
| 82 | `--systemtrace`: (Sets `g.fSystemTrace`.) Trace all commands launched |
| 83 | as sub processes. |
| 84 | |
| 85 | `--user LOGIN`: (Sets `g.zLogin`) Also `-U LOGIN`. Set the user name |
| 86 | used with the repository. |
| 87 | |
| 88 | `--utc`: Override the `timeline-utc` option to explicitly use |
| 89 | UTC time. |
| 90 | |
| 91 | `--vfs VFSNAME`: Load the named VFS into SQLite. |
| @@ -276,14 +277,15 @@ | |
| 277 | ### CGI and JSON Parameters |
| 278 | |
| 279 | |
| 280 | The JSON API implementation looks up many values in the first of |
| 281 | several places searched. This unifies the parameter handling logic, |
| 282 | allows the caller to choose whether to prefer URL parameters, request |
| 283 | headers, or the POST payload, and allows the `fossil json` command to |
| 284 | share most of the same logic as the `/json` API path. The search order |
| 285 | is a POST payload, GET/COOKIE/non-JSON POST, JSON POST, the system |
| 286 | environment. |
| 287 | |
| 288 | See the comment above the implementation of [`json_getenv`][json.c] |
| 289 | for some further discussion. |
| 290 | |
| 291 | [json.c]: /artifact/6df1d80dece8968b?ln=277,290 |
| @@ -300,67 +302,72 @@ | |
| 302 | |
| 303 | On Unix-like platforms, if no editor is named, then a message is |
| 304 | displayed on stdout, and stdin is read until a single line containing |
| 305 | only a dot is seen. |
| 306 | |
| 307 | |
| 308 | ### Error logging |
| 309 | |
| 310 | If logging errors to a file, fossil will include the values of the |
| 311 | following environment variables in the error log entry if they are |
| 312 | defined: `HTTP_HOST`, `HTTP_USER_AGENT`, `PATH_INFO`, `QUERY_STRING`, |
| 313 | `REMOTE_ADDR`, `REQUEST_METHOD`, `REQUEST_URI`, and `SCRIPT_NAME`. |
| 314 | |
| 315 | |
| 316 | |
| 317 | ### Fossil Username |
| 318 | |
| 319 | In absence of any explicit setting, fossil will use the same name you |
| 320 | logged in to your platform with, as the user name when interacting |
| 321 | with local and remote repositories. Note that only the name is shared, |
| 322 | fossil makes no attempt to share or leverage any platform's |
| 323 | authentication mechanisms or passwords. |
| 324 | |
| 325 | When logging in to a repository, it tries a series of sources for the |
| 326 | user name, and the first non-blank name that succeeds is the logged in |
| 327 | user. The order is: |
| 328 | |
| 329 | 1. The --user and -U command-line options. |
| 330 | 2. If running within an open checkout (the local database is open), |
| 331 | check in its table of values stored per open checkout for the |
| 332 | value stored by `fossil user default USERNAME`. |
| 333 | 3. The default user in the repository (setting `default-user`) |
| 334 | 4. The `FOSSIL_USER` environment variable. |
| 335 | 5. The `USER` environment variable. |
| 336 | 6. The `LOGNAME` environment variable. |
| 337 | 7. The `USERNAME` environment variable. |
| 338 | 8. Check if the user can be extracted from the remote URL, if |
| 339 | there is a remote URL. |
| 340 | |
| 341 | Items 2 and 3 are both set by `fossil user default USERNAME`, the |
| 342 | first within an open checkout, the second outside and using the `-R |
| 343 | REPOSITORY` option to identify the repository. Both cases require that |
| 344 | the named user be present in the repository when the default user is |
| 345 | assigned. Although the default user is internally stored as if it were |
| 346 | a setting named `default-user`, it is not accessible through |
| 347 | the `fossil set` command. |
| 348 | |
| 349 | Items 5, 6, and 7 cover most of the names of an environment variable |
| 350 | set automatically by the platform with the name of the platform's |
| 351 | logged in user for use by programs. Historically, `USER` comes from |
| 352 | Unix System-V, `LOGNAME` from BSD, and `USERNAME` from Windows, but |
| 353 | many Linux distributions will set both `USER` and `LOGNAME` for broad |
| 354 | compatibility. |
| 355 | |
| 356 | When creating a new repository, fossil needs a user name for the admin |
| 357 | user granted the "s" permission. But since fossil generally expects |
| 358 | that `fossil new` or `fossil clone` are used outside of any checkout |
| 359 | (especially when run for the first time without any checkouts at all |
| 360 | or the users's global settings database), it looks in a shorter list |
| 361 | of places for a non-blank name. In the special case of a clone, |
| 362 | `default-user` can be copied from the original, and so it can be set |
| 363 | in the clone even before any users have been created, and in that case |
| 364 | it will be the new admin user. If `default-user` is not set, then the |
| 365 | first found environment variable from the list `FOSSIL_USER`, `USER`, |
| 366 | `LOGNAME`, and `USERNAME`, is the user name. As a final fallback, if |
| 367 | none of those are set, then the default user name is "root". |
| 368 | |
| 369 | |
| 370 | ### Home Directory |
| 371 | |
| 372 | Fossil keeps some information interesting to each user in the user's |
| 373 | home directory. This includes the global settings and the list of |
| 374 |