Difference between revisions of "XDG user directories"

From ArchWiki
Jump to: navigation, search
m (Corrected part about disabling directories)
(quote more from website)
 
(51 intermediate revisions by 16 users not shown)
Line 1: Line 1:
[[Category:Desktop environments]]
+
[[Category:Freedesktop.org]]
User directories are a set of common directories such as downloads directory, music directory, documents directory, and so on. These directories can have special identifying icons and used internally by many applications such as [[GNOME#Nautilus|Nautilus]] and [[Thunar]] to determine where to look for files to be passed to the ''Create Document'' context menu, whereas the desktop directory is used by Xfdesktop to find ''.desktop'' files to be shown on the Desktop.
+
[[ja:XDG ユーザーディレクトリ]]
 +
[[pt:XDG user directories]]
 +
[[zh-hans:XDG user directories]]
 +
{{Related articles start}}
 +
{{Related|xdg-menu}}
 +
{{Related|Default applications}}
 +
{{Related|XDG Base Directory support}}
 +
{{Related articles end}}
  
== Installation ==
+
From [https://www.freedesktop.org/wiki/Software/xdg-user-dirs/ freedesktop.org]:
[[Pacman|install]] package {{pkg|xdg-user-dirs}} from [[Official Repositories]].
+
: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.  
  
== Configuration ==
+
: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 config file in {{ic|$XDG_CONFIG_HOME/user-dirs.dirs}} (XDG_CONFIG_HOME defaults to ~/.config) that applications can read to find these directories.
=== The config file ===
 
{{ic|xdg-user-dirs}} uses two files for configuration:
 
* For all users : {{ic|/etc/xdg/user-dirs.defaults}}.
 
* For one specific user: {{ic|~/.config/user-dirs.dirs}}.  
 
  
Its format is as follows:
+
Most [[file manager]]s indicate XDG user directories with special icons.
  XDG_DIRNAME_DIR="$HOME/Dirname"
 
  
A complete file might contain multiple entries:
+
== Creating default directories ==
  
  XDG_DESKTOP_DIR="$HOME/Desktop"
+
Creating a full suite of localized default user directories within the {{ic|$HOME}} directory can be done automatically using {{pkg|xdg-user-dirs}} and running:
  XDG_DOWNLOAD_DIR="$HOME/Downloads"
 
  XDG_TEMPLATES_DIR="$HOME/Templates"
 
  XDG_PUBLICSHARE_DIR="$HOME/Public"
 
  XDG_DOCUMENTS_DIR="$HOME/Documents"
 
  XDG_MUSIC_DIR="$HOME/Music"
 
  XDG_PICTURES_DIR="$HOME/Pictures"
 
  XDG_VIDEOS_DIR="$HOME/Videos"
 
  
Pointing any of the above variables to {{ic|$HOME}} disables the respective directory (it won't be automatically created).
+
$ 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.}}
'''xdg-user-dirs-update''' is a desktop-independent tool for configuring the location of certain user directories. It 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 config file in $(XDG_CONFIG_HOME)/user-dirs.dirs (XDG_CONFIG_HOME defaults to ~/.config) that applications can read to find these directories.
 
  
As an example, command
+
When executed, it will also automatically:
  
xdg-user-dirs-update --set TEMPLATES ~/.templates
+
* 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.
  
will set the {{ic|template}} directory to the specified directory with respect to the current user's {{ic|$HOME}}:
+
== Creating custom directories ==
  
  XDG_TEMPLATES_DIR="$HOME/.templates"
+
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 will/may likely look like this (these are all the template directories):
  
== xdg-user-dir ==
+
{{hc|1=~/.config/user-dirs.dirs|2=
 +
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"
 +
}}
  
Once set, any user directory can be viewed with {{ic|xdg-user-dir}}. For example:
+
As {{pkg|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 {{ic|XDG_DOWNLOAD_DIR}} variable has named {{ic|1=$HOME/Internet}} in {{ic|~/.config/user-dirs.dirs}} any application that uses this variable will use this directory.
  
  $ xdg-user-dir TEMPLATES
+
{{Note|Like with many configuration files, local settings override global settings. It will also be necessary to create any new custom directories.}}
 +
 
 +
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 ==
  
will show the template directory, which of course corresponds to the {{ic|XDG_TEMPLATES_DIR}} variable in the config file.
+
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:
  
== External Resource ==
+
$ xdg-user-dir TEMPLATES
* [http://freedesktop.org/wiki/Software/xdg-user-dirs xdg-user-dirs] - freedesktop.org
 

Latest revision as of 13:05, 24 April 2018

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

Creating default directories

Creating a full suite of localized default user directories within the $HOME directory can be done automatically using xdg-user-dirs and running:

$ xdg-user-dirs-update
Tip: To force the creation of English-named directories, LC_ALL=C xdg-user-dirs-update 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.

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 will/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.

Note: Like with many configuration files, local settings override global settings. It will also be necessary to create any new custom directories.

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