Fossil

Check-in [4de54b1d]
Login

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

Overview
Comment:Look in the XDG_CONFIG_HOME environment variable before looking in HOME for the location of the ".fossil" configuration database.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | xdg-aware-config-db
Files: files | file ages | folders
SHA3-256: 4de54b1d98cd264cec4dcaae757dcb7e02e90093fe586deb4a12dd6081089ad3
User & Date: drh 2020-04-18 00:12:23
Context
2020-04-18
18:55
Change the name of the configuration database to "fossil.db" if the database is found in the XDG_CONFIG_HOME directory. Otherwise, the configdb is still called ".fossil" on unix systems. ... (Leaf check-in: 09a21409 user: drh tags: xdg-aware-config-db)
00:12
Look in the XDG_CONFIG_HOME environment variable before looking in HOME for the location of the ".fossil" configuration database. ... (check-in: 4de54b1d user: drh tags: xdg-aware-config-db)
2020-04-17
15:00
Previous check-in broken the forum post edit function. Attempts to edit a forum post were disallowed. This check-in should fix the problem. ... (check-in: 3684c58b user: drh tags: trunk)
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to src/db.c.

1433
1434
1435
1436
1437
1438
1439



1440
1441
1442
1443
1444
1445
1446

1447
1448
1449
1450
1451
1452
1453
  if( zHome==0 ){
    if( isOptional ) return 0;
    fossil_panic("cannot locate home directory - please set the "
                 "FOSSIL_HOME, LOCALAPPDATA, APPDATA, USERPROFILE, "
                 "or HOMEDRIVE / HOMEPATH environment variables");
  }
#else



  if( zHome==0 ){
    zHome = fossil_getenv("HOME");
  }
  if( zHome==0 ){
    if( isOptional ) return 0;
    fossil_panic("cannot locate home directory - please set the "
                 "FOSSIL_HOME or HOME environment variables");

  }
#endif
  if( file_isdir(zHome, ExtFILE)!=1 ){
    if( isOptional ) return 0;
    fossil_panic("invalid home directory: %s", zHome);
  }
#if defined(_WIN32) || defined(__CYGWIN__)







>
>
>





|
|
>







1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
  if( zHome==0 ){
    if( isOptional ) return 0;
    fossil_panic("cannot locate home directory - please set the "
                 "FOSSIL_HOME, LOCALAPPDATA, APPDATA, USERPROFILE, "
                 "or HOMEDRIVE / HOMEPATH environment variables");
  }
#else
  if( zHome==0 ){
    zHome = fossil_getenv("XDG_CONFIG_HOME");
  }
  if( zHome==0 ){
    zHome = fossil_getenv("HOME");
  }
  if( zHome==0 ){
    if( isOptional ) return 0;
    fossil_panic("cannot locate home directory - please set one of the "
                 "FOSSIL_HOME, XDG_CONFIG_HOME, or HOME environment "
                 "variables");
  }
#endif
  if( file_isdir(zHome, ExtFILE)!=1 ){
    if( isOptional ) return 0;
    fossil_panic("invalid home directory: %s", zHome);
  }
#if defined(_WIN32) || defined(__CYGWIN__)

Changes to www/env-opts.md.

111
112
113
114
115
116
117
118
119
120
121


122
123
124
125
126
127
128
129
130
131
132
133
`--vfs VFSNAME`: Load the named VFS into SQLite.


Environment Variables
---------------------

On most platforms, the location of the user’s account-wide `.fossil`
file is either `FOSSIL_HOME` or `HOME`, in that order. This ordering
lets you put this file somewhere other than at the top of your user’s
home directory by defining `FOSSIL_HOME` to mask the always-defined
`HOME`.



For native Windows builds and for Cygwin builds, the file is called
`_fossil` instead to avoid problems with old programs that assume file
names cannot begin with a dot, as was true in old versions of Windows
and in MS-DOS. (Newer Microsoft OSes and file systems don’t have a
problem with such files, but still we take the safe path in case you’re
on a system with software that can’t cope.) We start our search with
`FOSSIL_HOME` again, but instead of falling back to `HOME`, we instead
try `USERPROFILE`, then `LOCALAPPDATA`, then `APPDATA`, and finally we
concatenate `HOMEDRIVE` + `HOMEPATH`.

`EDITOR`: Name the editor to use for check-in and stash comments.







|
|
|
|
>
>


|
|
|







111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
`--vfs VFSNAME`: Load the named VFS into SQLite.


Environment Variables
---------------------

On most platforms, the location of the user’s account-wide `.fossil`
file is either `FOSSIL_HOME`, `XDG_CONFIG_HOME`, or `HOME`, in that order. 
This ordering lets you put this file somewhere other than at the top 
of your user’s home directory by defining `FOSSIL_HOME` to mask 
the always-defined `HOME`.  The `XDG_CONFIG_HOME` setting is defined
by some desktop environments to be the preferred "modern" directory
in which to store configuration files.

For native Windows builds and for Cygwin builds, the file is called
`_fossil` instead of `.fossil` to avoid problems with old programs that 
assume file names cannot begin with a dot, as was true in old versions 
of Windows and in MS-DOS. (Newer Microsoft OSes and file systems don’t have a
problem with such files, but still we take the safe path in case you’re
on a system with software that can’t cope.) We start our search with
`FOSSIL_HOME` again, but instead of falling back to `HOME`, we instead
try `USERPROFILE`, then `LOCALAPPDATA`, then `APPDATA`, and finally we
concatenate `HOMEDRIVE` + `HOMEPATH`.

`EDITOR`: Name the editor to use for check-in and stash comments.
150
151
152
153
154
155
156
157

158
159
160
161
162
163
164
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_USE_SEE_TEXTKEY`: If set, treat the encryption key string for
SEE as text to be hashed into the actual encryption key.  This has no
effect if Fossil was not compiled with SEE support enabled.








|
>







152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
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), `XDG_CONFIG_HOME` (unix) and 
`HOME` is used as the
location of the `~/.fossil` file.


`FOSSIL_USE_SEE_TEXTKEY`: If set, treat the encryption key string for
SEE as text to be hashed into the actual encryption key.  This has no
effect if Fossil was not compiled with SEE support enabled.

196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
`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.

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

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








|
|







199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
`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.

`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), `XDG_CONFIG_HOME` (unix)
and `HOME` is used as the location of the `~/.fossil` file.

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

400
401
402
403
404
405
406
407
408
409
410
411

412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
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`.


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.








|


|
|
>

|


|

|
|


|
|







403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
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".


### Configuration Directory (often the Home Directory)

Fossil keeps some information interesting to each user in the user's
configuration file directory. This includes the global settings and the list of
repositories and checkouts used by `fossil all`.  On many,
but not all, systems the configuration file directory is the home directory

The user's configuration file 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), `XDG_CONFIG_HOME` (unix), and `HOME`.

SQLite has its own notion of the user's configuration file 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` nor
`XDG_CONFIG_HOME` variables.


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

Changes to www/tech_overview.wiki.

123
124
125
126
127
128
129


130
131
132
133


134
135
136

137
138
139
140
141
142
143
than having to change the setting individually on each repository.

The configuration database also maintains a list of repositories.  This
list is used by the [/help/all | fossil all] command in order to run various
operations such as "sync" or "rebuild" on all repositories managed by a user.

On Unix systems, the configuration database is named ".fossil" and is


located in the user's home directory.  On Windows, the configuration
database is named "_fossil" (using an underscore as the first character
instead of a dot) and is located in the directory specified by the
LOCALAPPDATA, APPDATA, or HOMEPATH environment variables, in that order.



You can override this default location by defining the environment
variable FOSSIL_HOME pointing to an appropriate (writable) directory.


<h3>2.2 Repository Databases</h3>

The repository database is the file that is commonly referred to as
"the repository".  This is because the repository database contains,
among other things, the complete revision, ticket, and wiki history for
a project.  It is customary to name the repository database after then







>
>
|



>
>



>







123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
than having to change the setting individually on each repository.

The configuration database also maintains a list of repositories.  This
list is used by the [/help/all | fossil all] command in order to run various
operations such as "sync" or "rebuild" on all repositories managed by a user.

On Unix systems, the configuration database is named ".fossil" and is
located in the user's configuration file directory, which on most older
unix systems is the user's home directory but on some "desktop" linux
environments is the "~/.config" directory.  On Windows, the configuration
database is named "_fossil" (using an underscore as the first character
instead of a dot) and is located in the directory specified by the
LOCALAPPDATA, APPDATA, or HOMEPATH environment variables, in that order.
You can run the [/help?cmd=info|fossil info] command from an open
check-out to see the location of the configuration database.

You can override this default location by defining the environment
variable FOSSIL_HOME pointing to an appropriate (writable) directory.


<h3>2.2 Repository Databases</h3>

The repository database is the file that is commonly referred to as
"the repository".  This is because the repository database contains,
among other things, the complete revision, ticket, and wiki history for
a project.  It is customary to name the repository database after then