** it is convenient for the ~/.fossil to be attached to the main database
** connection so that we can join between the various databases.  In that
** case, invoke this routine with useAttach as 1.
*/
int db_open_config(int useAttach, int isOptional){
  char *zDbName;
  char *zHome;
  const char *zRoot;
  if( g.zConfigDbName ){
    int alreadyAttached = db_database_slot("configdb")>0;
    if( useAttach==alreadyAttached ) return 1; /* Already open. */
    db_close_config();
  }
  zHome = fossil_getenv("FOSSIL_HOME");
#if defined(_WIN32) || defined(__CYGWIN__)
  zRoot = "_fossil";
  if( zHome==0 ){
    zHome = fossil_getenv("LOCALAPPDATA");
    if( zHome==0 ){
      zHome = fossil_getenv("APPDATA");
      if( zHome==0 ){
        zHome = fossil_getenv("USERPROFILE");
        if( zHome==0 ){

  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
  zRoot = ".fossil";
  if( zHome==0 ){
    zHome = fossil_getenv("XDG_CONFIG_HOME");
    if( zHome ){
      zRoot = "fossil.db";
    }else{
      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__)
  /* . filenames give some window systems problems and many apps problems */
  zDbName = mprintf("%//%s", zHome, zRoot);
#else
  zDbName = mprintf("%s/%s", zHome, zRoot);
#endif
  if( file_size(zDbName, ExtFILE)<1024*3 ){
    if( file_access(zHome, W_OK) ){
      if( isOptional ) return 0;
      fossil_panic("home directory %s must be writeable", zHome);
    }
    db_init_database(zDbName, zConfigSchema, (char*)0);

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


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

On most platforms, the location of the user’s account-wide
[configuration database][configdb]
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 as an alternative location for
configuration files.  If the `XDG_CONFIG_HOME` location is used, then
the name of the configuration database is `fossil.db` instead of
`.fossil`.  See the [configuration database location][configloc] discussion
for additional information.

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.

`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 [configuration database][configdb].



See the [configuration database location][configloc] description
for additional information.

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


`FOSSIL_USER`: Name of the default user account if the checkout, local

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

`HOME`: Potential location of the [configuration database][configdb].



See the [configuration database location][configloc] description for details.

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

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 pertinent to each user in the user's
[configuration database file][configdb]. 
The configuration database file includes the global settings
and the list of repositories and checkouts used by `fossil all`.

On Unix systems, the configuration database is called by one of the
following names (in order):

  * `$FOSSIL_HOME/.fossil`
  * `$XDG_CONFIG_HOME/fossil.db`
  * `$HOME/.fossil`

The name used is the first in the above list for which the corresponding
environment varible is defined. On most systems, the third name is the
one that is used.

On Windows, the configuration database is called one of these (in order)

  *  `%FOSSIL_HOME%/_fossil`
  *  `%LOCALAPPDATA%/_fossil`
  *  `%APPDATA%/_fossil`
  *  `%USERPROFILES%/_fossil`
  *  `%HOMEDRIVE%%HOMEPATH%/_fossil`


As before, the first case in when the corresponding environment variables
exist is the one used.  This is ususally the second case.  Note that the
`FOSSIL_HOME` environment variable can always be set to determine the 
location of the configuration database.  Note also that the configuration
database file itself is called `.fossil` or `fossil.db` on unix but
`_fossil` on windows.

You can run the "[fossil info](/help?cmd=info)" command from an open
check-out to see the location of the configuration database.


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

`google-chrome` that it can find on the `PATH`.

On Apple platforms, it assumes that `open` is the command to open an
URL in the user's configured default browser.

On Windows platforms, it assumes that `start` is the command to open
an URL in the user's configured default browser.

[configdb]: ./tech_overview.wiki#configdb
[configloc]: ./tech_overview.wiki#configloc

The chart below provides a quick summary of how each of these
database files are used by Fossil, with detailed discussion following.

<table border="1" width="80%" cellpadding="0" align="center">
<tr>
<td width="33%" valign="top">
<h3 align="center">Configuration Database<br>"~/.fossil" or<br>
"~/.config/fossil.conf"</h3>
<ul>
<li>Global [/help/settings |settings]
<li>List of active repositories used by the [/help/all | all] command
</ul>
</td>
<td width="34%" valign="top">
<h3 align="center">Repository Database<br>"<i>project</i>.fossil"</h3>
<ul>
<li>[./fileformat.wiki | Global state of the project]
    encoded using delta-compression
<li>Local [/help/settings|settings]
<li>Web interface display preferences
<li>User credentials and permissions
<li>Metadata about the global state to facilitate rapid
    queries
</ul>
</td>
<td width="33%" valign="top">
<h3 align="center">Checkout Database<br>"_FOSSIL_" or ".fslckout"</h3>
<ul>
<li>The repository database used by this checkout
<li>The version currently checked out
<li>Other versions [/help/merge | merged] in but not
    yet [/help/commit | committed]
<li>Changes from the [/help/add | add], [/help/delete | delete],
    and [/help/rename | rename] commands that have not yet been committed

a way to change settings for all repositories with a single command, rather
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.

<a name='configloc'></a>
<h4>2.1.1 Location Of The Configuration Database</h4>

On Unix systems, the configuration database is called by one of the
following names (in order):

  *  $FOSSIL_HOME/.fossil
  *  $XDG_CONFIG_HOME/fossil.db
  *  $HOME/.fossil

The name used is the first in the above list for which the corresponding
environment varible is defined. On most systems, the third name is the
one that is used.

On Windows, the configuration database is called one of these
names (in order):

  *  %FOSSIL_HOME%/_fossil
  *  %LOCALAPPDATA%/_fossil
  *  %APPDATA%/_fossil
  *  %USERPROFILES%/_fossil
  *  %HOMEDRIVE%%HOMEPATH%/_fossil

As before, the first case in when the corresponding environment variables
exist is the one used.  This is ususally the second case.  Note that the
FOSSIL_HOME environment variable can always be set to determine the 
location of the configuration database.  Note also that the configuration
database file itself is called ".fossil" or "fossil.db" on unix but
"_fossil" on windows.

You can run the [/help?cmd=info|fossil info] command from an open
check-out to see the location of the configuration database.

<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