XDG user directories: Difference between revisions
(add chinese translate page) |
(Add a troubleshooting section mentioning how to fix Dolphin) |
||
(35 intermediate revisions by 17 users not shown) | |||
Line 1: | Line 1: | ||
[[Category: | [[Category:Freedesktop.org]] | ||
[[ja: | [[ca:XDG user directories]] | ||
[[zh-hans: | [[ja:XDG ユーザーディレクトリ]] | ||
[[pt:XDG user directories]] | |||
[[ru:XDG user directories]] | |||
[[zh-hans:XDG user directories]] | |||
{{Related articles start}} | {{Related articles start}} | ||
{{Related|xdg-menu}} | {{Related|xdg-menu}} | ||
Line 7: | Line 10: | ||
{{Related|XDG Base Directory support}} | {{Related|XDG Base Directory support}} | ||
{{Related articles end}} | {{Related articles end}} | ||
{{ | From [https://www.freedesktop.org/wiki/Software/xdg-user-dirs/ freedesktop.org]: | ||
:xdg-user-dirs is a tool to help manage "well known" user directories like the desktop folder and the music folder. It also handles localization (i.e. translation) of the filenames. | |||
:The way it works is that {{man|1|xdg-user-dirs-update}} is run very early in the login phase. This program reads a configuration file, and a set of default directories. It then creates localized versions of these directories in the users home directory and sets up a configuration file in {{ic|$XDG_CONFIG_HOME/user-dirs.dirs}} ({{ic|XDG_CONFIG_HOME}} defaults to {{ic|~/.config}}) that applications can read to find these directories. | |||
Most [[file manager]]s indicate XDG user directories with special icons. | |||
== Installation == | |||
[[Install]] {{Pkg|xdg-user-dirs}}. | |||
{{Tip|Some [[desktop environments]] might have it installed already, e.g. [[GNOME]].}} | |||
== Creating default directories == | == Creating default directories == | ||
Creating a full suite of localized default user directories within the {{ic|$HOME}} directory can be done automatically | Creating a full suite of localized default user directories within the {{ic|$HOME}} directory can be done automatically by running: | ||
$ xdg-user-dirs-update | $ xdg-user-dirs-update | ||
{{Tip|To force the creation of English-named directories, {{ic|1=LC_ALL=C xdg-user-dirs-update}} can be used.}} | {{Tip|To force the creation of English-named directories, {{ic|1=LC_ALL=C.UTF-8 xdg-user-dirs-update --force}} can be used.}} | ||
When executed, it will also automatically: | When executed, it will also automatically: | ||
Line 23: | Line 36: | ||
* Create a local {{ic|~/.config/user-dirs.dirs}} configuration file: used by applications to find and use home directories specific to an account. | * Create a local {{ic|~/.config/user-dirs.dirs}} configuration file: used by applications to find and use home directories specific to an account. | ||
* Create a local {{ic|~/.config/user-dirs.locale}} configuration file: used to set the language according to the locale in use. | * Create a local {{ic|~/.config/user-dirs.locale}} configuration file: used to set the language according to the locale in use. | ||
The user service {{ic|xdg-user-dirs-update.service}} will also be installed and enabled by default, in order to keep your directories up to date by running this command at the beginning of each login session. | |||
== Creating custom directories == | == Creating custom directories == | ||
Both the local {{ic|~/.config/user-dirs.dirs}} and global {{ic|/etc/xdg/user-dirs.defaults}} configuration files use the following environmental variable format to point to user directories: {{ic|1=XDG_DIRNAME_DIR="$HOME/directory_name"}} An example configuration file | Both the local {{ic|~/.config/user-dirs.dirs}} and global {{ic|/etc/xdg/user-dirs.defaults}} configuration files use the following environmental variable format to point to user directories: {{ic|1=XDG_DIRNAME_DIR="$HOME/directory_name"}} An example configuration file may likely look like this (these are all the template directories): | ||
{{hc|1=~/.config/user-dirs.dirs|2= | {{hc|1=~/.config/user-dirs.dirs|2= | ||
Line 49: | Line 64: | ||
== Querying configured directories == | == Querying configured directories == | ||
Once set, any user directory can be viewed with {{pkg|xdg-user-dirs}}. For example, the following command will | Once set, any user directory can be viewed with {{pkg|xdg-user-dirs}}. For example, the following command will show the location of the {{ic|Templates}} directory, which of course corresponds to the {{ic|XDG_TEMPLATES_DIR}} variable in the local configuration file: | ||
$ xdg-user-dir TEMPLATES | $ xdg-user-dir TEMPLATES | ||
{{warning|{{ic|xdg-user-dir}} should not receive its argument from unchecked input, since it simply passes it to {{ic|eval}} without performing any sanity checks, in a line that looks like this: | |||
eval echo \${XDG_${1}_DIR:-$HOME} | |||
This means that {{ic|xdg-user-dir}} facilitates arbitrary code execution from unsanitized input. Unless this terrible implementation is fixed upstream, {{ic|xdg-user-dir}} should only ever be used with a hard-coded or strictly audited argument.}} | |||
== Troubleshooting == | |||
=== Dolphin === | |||
After updating {{ic|~/.config/user-dirs.dirs}}, [[Dolphin]] will continue pointing to the old directories. This is because it stores them separately in {{ic|~/.local/share/user-places.xbel}}. You can either edit the file manually, or delete it and let Dolphin re-create it. Note that deleting it will clear any edits that have been made to the locations sidebar. |
Latest revision as of 05:41, 26 March 2024
From freedesktop.org:
- xdg-user-dirs is a tool to help manage "well known" user directories like the desktop folder and the music folder. It also handles localization (i.e. translation) of the filenames.
- The way it works is that xdg-user-dirs-update(1) is run very early in the login phase. This program reads a configuration file, and a set of default directories. It then creates localized versions of these directories in the users home directory and sets up a configuration file in
$XDG_CONFIG_HOME/user-dirs.dirs
(XDG_CONFIG_HOME
defaults to~/.config
) that applications can read to find these directories.
Most file managers indicate XDG user directories with special icons.
Installation
Creating default directories
Creating a full suite of localized default user directories within the $HOME
directory can be done automatically by running:
$ xdg-user-dirs-update
LC_ALL=C.UTF-8 xdg-user-dirs-update --force
can be used.When executed, it will also automatically:
- Create a local
~/.config/user-dirs.dirs
configuration file: used by applications to find and use home directories specific to an account. - Create a local
~/.config/user-dirs.locale
configuration file: used to set the language according to the locale in use.
The user service xdg-user-dirs-update.service
will also be installed and enabled by default, in order to keep your directories up to date by running this command at the beginning of each login session.
Creating custom directories
Both the local ~/.config/user-dirs.dirs
and global /etc/xdg/user-dirs.defaults
configuration files use the following environmental variable format to point to user directories: XDG_DIRNAME_DIR="$HOME/directory_name"
An example configuration file may likely look like this (these are all the template directories):
~/.config/user-dirs.dirs
XDG_DESKTOP_DIR="$HOME/Desktop" XDG_DOCUMENTS_DIR="$HOME/Documents" XDG_DOWNLOAD_DIR="$HOME/Downloads" XDG_MUSIC_DIR="$HOME/Music" XDG_PICTURES_DIR="$HOME/Pictures" XDG_PUBLICSHARE_DIR="$HOME/Public" XDG_TEMPLATES_DIR="$HOME/Templates" XDG_VIDEOS_DIR="$HOME/Videos"
As xdg-user-dirs will source the local configuration file to point to the appropriate user directories, it is therefore possible to specify custom folders. For example, if a custom folder for the XDG_DOWNLOAD_DIR
variable has named $HOME/Internet
in ~/.config/user-dirs.dirs
any application that uses this variable will use this directory.
Alternatively, it is also possible to specify custom folders using the command line. For example, the following command will produce the same results as the above configuration file edit:
$ xdg-user-dirs-update --set DOWNLOAD ~/Internet
Querying configured directories
Once set, any user directory can be viewed with xdg-user-dirs. For example, the following command will show the location of the Templates
directory, which of course corresponds to the XDG_TEMPLATES_DIR
variable in the local configuration file:
$ xdg-user-dir TEMPLATES
xdg-user-dir
should not receive its argument from unchecked input, since it simply passes it to eval
without performing any sanity checks, in a line that looks like this:
eval echo \${XDG_${1}_DIR:-$HOME}This means that
xdg-user-dir
facilitates arbitrary code execution from unsanitized input. Unless this terrible implementation is fixed upstream, xdg-user-dir
should only ever be used with a hard-coded or strictly audited argument.Troubleshooting
Dolphin
After updating ~/.config/user-dirs.dirs
, Dolphin will continue pointing to the old directories. This is because it stores them separately in ~/.local/share/user-places.xbel
. You can either edit the file manually, or delete it and let Dolphin re-create it. Note that deleting it will clear any edits that have been made to the locations sidebar.