Difference between revisions of "XDG user directories"

From ArchWiki
Jump to: navigation, search
m (Creating custom directories: make it clear that it is one argument)
(update interlanguage links)
(Tag: wiki-scripts)
 
(21 intermediate revisions by 11 users not shown)
Line 1: Line 1:
 
[[Category:Desktop environments]]
 
[[Category:Desktop environments]]
 +
[[ja:Xdg ユーザーディレクトリ]]
 +
[[zh-hans:XDG user directories]]
 
{{Related articles start}}
 
{{Related articles start}}
 
{{Related|xdg-menu}}
 
{{Related|xdg-menu}}
{{Related|xdg-open}}
+
{{Related|Default applications}}
 +
{{Related|XDG Base Directory support}}
 
{{Related articles end}}
 
{{Related articles end}}
User directories are a set of common user directories located within the {{ic|$HOME}} directory, including {{ic|Documents}}, {{ic|Downloads}}, {{ic|Music}}, and {{ic|Desktop}}. Identified by unique icons within a file manager, they will commonly be automatically sourced by numerous programs and applications. {{pkg|xdg-user-dirs}} is a program that will automatically generate these directories. See the [http://freedesktop.org/wiki/Software/xdg-user-dirs freedesktop.org] website for further information.
+
User directories are a set of common user directories located within the {{ic|$HOME}} directory, including {{ic|Documents}}, {{ic|Downloads}}, {{ic|Music}}, and {{ic|Desktop}}. Identified by unique icons within a file manager, they will commonly be automatically sourced by numerous programs and applications. {{pkg|xdg-user-dirs}} is a program that will automatically generate these directories. See the [https://www.freedesktop.org/wiki/Software/xdg-user-dirs freedesktop.org] website for further information.
  
{{Tip|This program will be especially helpful for those who wish to use a file manager to manage their desktop for a [[Window Manager]] such as [[Openbox]], as it will also automatically create a {{ic|~/Desktop}} directory.}}
+
{{Tip|This program will be especially helpful for those who wish to use a file manager to manage their desktop for a [[Window manager]] such as [[Openbox]], as it will also automatically create a {{ic|~/Desktop}} directory.}}
  
== Installation ==
+
== Creating default directories ==
[[Pacman|Install]] package {{pkg|xdg-user-dirs}} from [[Official Repositories]].
 
  
== Creating default directories ==
+
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:
To create a full suite of localized default user directories within the {{ic|$HOME}} directory, enter the following command:
 
  
 
  $ xdg-user-dirs-update
 
  $ xdg-user-dirs-update
Line 21: Line 22:
  
 
* 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 global {{ic|/etc/xdg/user-dirs.defaults}} configuration file: used by applications to find and use home directories generally.
 
 
* 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.
  
 
== Creating custom directories ==
 
== Creating custom directories ==
{{Note|As with any configuration file, local settings will always override global settings. It will also be necessary to manually create any new custom directories.}}
 
 
Both the local {{ic|~/.config/user-dirs.dirs}} and global {{ic|/etc/xdg/user-dirs.defaults}} configuration files use the following format to point to user directories:
 
  
XDG_DIRNAME_DIR="$HOME/''directory_name''"
+
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):
  
A complete configuration file may also contain multiple entries:
+
{{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"
 +
}}
  
  XDG_DESKTOP_DIR="$HOME/Desktop"
+
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_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"
 
  
As {{pkg|xdg-user-dirs}} will source the local configuration file to point to the appropriate user directories, it is therefore possible to edit it in order specify custom folders. For example, in the following example, a custom folder for the {{ic|XDG_DOWNLOAD_DIR}} variable has been created called {{ic|Internet}}, and {{ic|~/.config/user-dirs.dirs}} has been edited accordingly:
+
{{Note|Like with many configuration files, local settings override global settings. It will also be necessary to create any new custom directories.}}
  
XDG_DOWNLOAD_DIR="$HOME/Internet"
+
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:
 
 
When downloading files from a web-browser, the default folder used for downloading will now be {{ic|Internet}}. Alternatively, it is also possible to specify custom folders using the command line. The syntax of this command is:
 
 
 
  $ xdg-user-dirs-update --set ''XDG_NAME'' ''path/to/custom_folder''
 
 
 
For example, the following command will produce the same results as the above configuration file edit:
 
  
 
  $ xdg-user-dirs-update --set DOWNLOAD ~/Internet
 
  $ xdg-user-dirs-update --set DOWNLOAD ~/Internet
 
The names of the ''xdg'' templates are {{ic|DESKTOP}}, {{ic|DOWNLOAD}}, {{ic|TEMPLATES}}, {{ic|PUBLICSHARE}}, {{ic|DOCUMENTS}}, {{ic|MUSIC}}, {{ic|PICTURES}}, and {{ic|VIDEOS}}.
 
  
 
== Querying configured directories ==
 
== Querying configured directories ==
  
Once set, any user directory can be viewed with {{pkg|xdg-user-dir}}. For example, the following command will specify the location of the {{ic|Templates}} directory, which of course corresponds to the {{ic|XDG_TEMPLATES_DIR}} variable in the local configuration file:
+
Once set, any user directory can be viewed with {{pkg|xdg-user-dirs}}. For example, the following command will specify 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

Latest revision as of 08:31, 22 February 2017

User directories are a set of common user directories located within the $HOME directory, including Documents, Downloads, Music, and Desktop. Identified by unique icons within a file manager, they will commonly be automatically sourced by numerous programs and applications. xdg-user-dirs is a program that will automatically generate these directories. See the freedesktop.org website for further information.

Tip: This program will be especially helpful for those who wish to use a file manager to manage their desktop for a Window manager such as Openbox, as it will also automatically create a ~/Desktop directory.

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 specify 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