Revision as of 08:25, 17 April 2018

Configuration Locations

This article describes the configuration file locations as they related to GnuCash v3.0. Originally posted by Geert in a mailing list thread.

XDG_* Variables

The XDG_* variables come from a free desktop specification [1] that defines a number standard directories and paths that each system that claims to follow this standard should adhere to. Most desktop environments (kde, gnome, xfce,...) on linux do adhere to this so they can interoperate properly. Many programs rely on this, and gnucash is no exception as it's based on gtk (which underpins the gnome desktop environment as well).

There are two that gnucash uses as of gnucash 3.0 and related to user data:

XDG_DATA_HOME

(defaults to ~/.local/share on linux)

XDG_CONFIG_HOME

(defaults to ~/.config on linux)

On systems that follow the XDG specification, users can override either by setting environment variables with these names. In practice this is everywhere except on Windows and in the Quarz version of gnucash. Both of these instead use the platform specific default paths and will ignore the XDG_* settings [2].

As you may observe neither path is specific to gnucash. These directories are shared by all applications adherering to the above specification. So in order to keep these directories tidy, most applications make an application specific subdirectory in there. For gnucash on linux these are (predictably)

~/.local/share/gnucash
~/.config/gnucash

The former can be overridden by setting GNC_DATA_HOME, the latter can't be overridden (that's an oversight, not intentional).

Lastly, the 2.6 .gnucash dir has no one to one mapping to a directory under 3.0. In fact it's content has been distributed over the two directories above. The rationale is this:

Any configuration file we expect the user to tweak manually should go in config/gnucash. GnuCash will never alter any file in there (except for the one-time initial migration. Any file we don't expect the user to tweak manually (as it's written and maintained by gnucash itself) should go into local/share/gnucash. We expect users to not touch these files directly and gnucash can overwrite these at any time.

Files that should go in .config are things like a customized css file, a config file with custom scheme code, ...

Files that still go in .local/share are saved reports (gnucash manages these), state files, style sheets,...

Currently the accelerator-maps are also still stored in there, but I believe this is a mistake as well that should be corrected at some point.