Comply with the XDG Base Directory Specification #16733

Should $XDG_DATA_HOME be taken into account when determining the default datadir location?

http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html

Reopen of issue #1390

What is wrong with $HOME?

There is nothing wrong with home, this is just a standard that many packages follow. It is in the same spirit of the FHS.

On my machine $HOME isn't set but $HOME is. I prefer to stick with $HOME

@emilengler I don't see how your personal anecdotal evidence is relevant when talking about compliance with a standard.

I just want say that the standard isn't really established

@emilengler XDG does not specify that XDG_DATA_HOME has to be set.

Now that it's possible to have the various things (config file, block directory, wallets) in different places, maybe they fall into different XDG categories, so instead of moving the default data directory, maybe the best way to comply would be to split it up.

I don't think anything in the datadir qualifies as "cache", so at most we could split it up between XDG_CONFIG_HOME and XDG_DATA_HOME.

I see db.log, debug.log, .lock and .walletlock, these could go on XDG_CACHE_HOME. Both blocks and chainstate technically belong to cache but the idea is that one should be able to delete XDG_CACHE_HOME at will and in this particular case it is more problematic as it implies a ~200gb download.

Obs: bitcoin-qt already uses ~/.config/Bitcoin to store its config.

What is wrong with $HOME?

It's my home, and I want to organize it according to my own preferences. I don't want arbitrary subdirectory trees being sprayed around for every piece of software I use. For example, it's not scalable or reasonable to configure backup tools or cache cleanup tools when each application takes it upon itself to decide on a unique place to put configuration, caches, or shared files. Users have either already gone out of their way to tell apps where they prefer things to go by setting the XDG environment variables, or they don't care and won't mind them going there by default.

Apps that respect the XDG standard allow me to say "back up $XDG_CONFIG_HOME, a single directory, thereby ignoring binaries, shared files, or cached data that can be recreated by the app if it's not there" instead of specifying a snowflake path for every application I use.

There isn't any downside to respecting users' preferences. If you personally want everything in $HOME, the standard allows you to do that, but I don't see why anyone prefers that except by sheer weight of historical momentum.

i found this issue while researching how the XDG_CONFIG_HOME environment variable affects the location of the bitcoin-qt config file. by default, when this env var is not set, that conf file gets written outside of the bitcoin data directory as $HOME/.config/Bitcoin/Bitcoin-Qt.conf. this happens in BitcoinApplication::createOptionsModel which eventually calls down into OptionsModel::checkAndMigrate which then calls into Qt code that actually writes the Bitcoin/Bitcoin-Qt.conf file, if there are sufficient permissions. maybe we should set this env var, if it's not set so that that conf file goes into the bitcoin data directory too? if not, maybe we should mention this env var and conf file location in the docs somewhere.

Was thinking about this myself, here's an example of what we could do for the config file:

1. Check for config files in the following order (first hit is applied, warn if multiple found)
   1. -conf command line parameter
   2. $datadir/bitcoin.conf
   3. $XDG_CONFIG_HOME/.config/bitcoin/bitcoin.conf
   4. $HOME/.config/bitcoin/bitcoin.conf
   5. $HOME/.bitcoin/bitcoin/bitcoin.conf (current non-XDG directory)

A question: should we use $XDG_DATA_HOME ($HOME/.local/share) or $XDG_STATE_HOME ($HOME/.local/state) for the datadir?

I don't think anything in the datadir qualifies as "cache", so at most we could split it up between XDG_CONFIG_HOME and XDG_DATA_HOME.

This is a great place to start because Bitcoin-Qt already uses $XDG_CONFIG_HOME/{Bitcoin/Bitcoin-Qt.conf,autostart/bitcoin.desktop}.

I see db.log, debug.log, ...

These go in $XDG_STATE_HOME.

The $XDG_STATE_HOME contains state data that should persist between (application) restarts, but that is not important or portable enough to the user that it should be stored in $XDG_DATA_HOME. It may contain:

• actions history (logs, history, recently used files, …)
• current state of the application that can be reused on a restart (view, layout, open files, undo history, …)

.lock and .walletlock, these could go on XDG_CACHE_HOME.

These go in $XDG_RUNTIME_DIR.

This directory is designed for storing runtime files such as sockets, named pipes, and lock files. The files in this directory are usually ephemeral and should be deleted when the user session ends.

XDG_CACHE_HOME is for non-essential files that should persist restart.

maybe we should set [$XDG_CONFIG_HOME], if it's not set so that that conf file goes into the bitcoin data directory too?

NACK, Bitcoin-Qt needs to know where to look for a custom Data directory (on a removable drive for instance), if you move Bitcoin-Qt.conf to the custom Datadir it will ask for its location every start up.

if not, maybe we should mention this env var and conf file location in the docs somewhere.

ACK, we technically do (if you dig through the links) but not directly enough to quickly find all the default locations Bitcoin-Qt makes files from our doc/files.md.

$XDG_CONFIG_HOME/bitcoin/bitcoin.conf

Should we capitalize Bitcoin/ to avoid creating a new folder by matching capitalization of the existing folder Bitcoin-Qt?

$XDG_CONFIG_HOME/Bitcoin/bitcoin.conf is a great place to look for an unspecified -conf file. This would tidy up my systems quite a lot. As is, I have to make a ~/.bitcoin folder with my bitcoin.conf simply to direct the application to my custom datadir. Cluttering my home folder.

settings.json also belongs in $XDG_CONFIG_HOME/bitcoin

A question: should we use $XDG_DATA_HOME ($HOME/.local/share) or $XDG_STATE_HOME ($HOME/.local/state) for the datadir?

$XDG_STATE_HOME is intended for storing state information that is specific to a user and should persist restarts...

but that is not important or portable enough to the user that it should be stored in $XDG_DATA_HOME.

The datadir goes in $XDG_DATA_HOME because it is portable and important: wallets.

Regarding whether blocks and chainstate are $XDG_CACHE_HOME or $XDG_DATA_HOME:

$XDG_CACHE_HOME is analogous to /var/cache/ from FHS:

/var/cache is intended for cached data from applications. Such data is locally generated as a result of time-consuming I/O or calculation. The application must be able to regenerate or restore the data. Unlike /var/spool, the cached files can be deleted without data loss. The data must remain valid between invocations of the application and rebooting the system.

Files located under /var/cache may be expired in an application specific manner, by the system administrator, or both. The application must always be able to recover from manual deletion of these files (generally because of a disk space shortage). No other requirements are made on the data format of the cache directories.

I see the argument they can be recreated or fetched for chainstate but I do NOT see this argument for blocks. We would lose all our bitcoins if everyone deleted their blocks folder, since this is peer-to-peer software we all need to back it up. However, if everyone deleted their chainstate folder, a full node can recreate the data rather quickly.

$XDG_CACHE_HOME/bitcoin/chainstate and $XDG_DATA_HOME/bitcoin/blocks is my vote. However for pruned nodes it should be $XDG_DATA_HOME/bitcoin/chainstate as the Software can no longer recreate this folder.

And for AssumeUTXO with prune=0 put the snapshot chainstate in $XDG_CACHE_HOME/bitcoin/ and the snapshot blocks in `$XDG_DATA_HOME/bitcoin/.

The /var/cache directory contains cached files, i.e. files that were generated and can be re-generated any time, but they are worth storing to save time of recomputing them.

Any application can create a file or directory here. It is assumed that files stored here are not critical, so the system can delete the contents of /var/cache either periodically, or when its contents get too large.

Any application should take into account that the file stored here can disappear any time, and be ready to recompute its contents (with some time penalty).

I believe chainstate belongs in $XDG_CACHE_HOME when prune=0 it best fits these requirements. With prune set, it must go in $XDG_DATA_HOME as it cannot be locally regenerated.

Should our subdir be Bitcoin or bitcoin?

Bitcoin is consistent with the current $XDG_CONFIG_HOME/Bitcoin/Bitcoin-qt.conf but bitcoin matches our current $HOME/.bitcoin datadir and .desktop files and is easier to type.

This issue hasn’t attracted much interest from other contributors in quite some time.

Given that, it doesn’t seem important enough to keep open indefinitely. I’m going to close it for now due to lack of activity, but pull requests or renewed discussion are always welcome.

Comment here if you think this should be re-opened.