XDG is your ticket to a clean and robust solution for locating user specific and system wide configuration and support files.

What is this all about?

The XDG Base Directory Standard provides a common means for specifying one or more base directories relative to which support files can be located. Using the XDG standard, applications can find and store application specific support files (eg. config files, data caches, etc.) in a universal, clean and robust fashion. The advantages of this standard is that all such files will be found in central locations easily discernible by man and machine. And, if widely adopted, XDG can clear up our HOME directories of all those pesky hidden files.

See XDG Base Directory Standard Specification.

Who's using the XDG Standard?


Why should I use the XDG standard?

If your program depends on user-relative or system-wide support files, it will be much improved by using the XDG Base Directory Standard. Not only does it provide a clean yet flexible standard, it also makes your life easier. The #find and #select methods make it a snap to locate support files.

XDG make it easy to enable your application's users to create user-centric or system-centric configuration and support files, and store those files where they see fit --whether in the standard locations or locations of personal preference.

What can XDG standard ultimately do?

How about turning this:

    $ ls -a ~/

    .ICEauthority     .gconf                .qt                    
    .Xauthority       .gconfd               .rdoc                  Documents
    .Xsession         .gem                  .recently-used         Download
    .adobe            .gftp                 .recently-used.xbel    EMail
    .aptitude         .gimp-2.4             .ri                    Friends
    .aspell.en.prepl  .gitconfig            .ruby_inline           Jobs
    .aspell.en.pws    .gksu.lock            .rubyrc                Mail
    .bash_history     .gnome                .sane                  Manifest.txt
    .bash_logout      .gnome2               .shoes                 Media
    .bashrc           .gnome2_private       .ssh                   Memento
    .bogofilter       .gnupg                .subversion            Music
    .cache            .gstreamer-0.10       .themes                Notebook
    .camel_certs      .gtk-bookmarks        .thumbnails            Personal
    .compiz           .gtk-recordmydesktop  .tremulous             Photos
    .config           .gtkrc-1.2-gnome2     .update-manager-core   Pics
    .dbus             .gvfs                 .update-notifier       Pictures
    .dbus-keyrings    .icons                .vim                   PonyArchive
    .dia              .irb_history          .viminfo               Public
    .diakonos         .irbrc                .vimrc                 Sort
    .dmrc             .local                .vlc                   Templates
    .dvdcss           .macromedia           .w3m                   Videos
    .dvdrip           .metacity             .wapi                  current
    .dvdrip-master    .mozilla              .xine                  dvdrip-data
    .dvdriprc         .mplayer              .xinitrc               links.xml
    .eee              .mysql_history        .xsession-errors       programs
    .esd_auth         .nautilus             Archive                projects
    .etc              .openoffice.org2      Art                    ruby
    .evolution        .pgadmin3             Bookmarks              sandbox
    .fastri-index     .pgpass               Books                  tags
    .fehbg            .profile              Company                tigerops
    .fehrc            .pulse                Contacts
    .fontconfig       .pulse-cookie         Desktop
    .fr-KVIe0s        .purple               Diff.txt
    

Into this:

    $ ls -a ~/

    .cache            Diff.txt              Music                  Videos
    .config           Documents             Notebook               current
    .local            Download              Personal               dvdrip-data
    Archive           EMail                 Photos                 links.xml
    Art               Friends               Pics                   programs
    Bookmarks         Jobs                  Pictures               projects
    Books             Mail                  PonyArchive            ruby
    Company           Manifest.txt          Public                 sandbox
    Contacts          Media                 Sort                   tags
    Desktop           Memento               Templates              tigerops
    

How to Install the XDG Ruby Library

Using RubyGems

      $ gem install xdg
      

How to Use the XDG Ruby Library

It's really quite easy:

      require 'xdg'

      XDG['CONFIG']
      XDG['CONFIG_HOME']
      XDG['CONFIG_DIRS']

      XDG['DATA']
      XDG['DATA_HOME']
      XDG['DATA_DIRS']

      XDG['CACHE']
      XDG['CACHE_HOME']
      XDG['CACHE_DIRS']
      

All of these base directory reference provide access to a variety of useful methods, e.g.

      XDG['CONFIG'].to_s
      XDG['CONFIG'].to_a
      XDG['CONFIG'].glob(pattern)
      XDG['CONFIG'].find(pattern){ |path| ... }
      XDG['CONFIG'].select(pattern){ |path| ... }
      

You can also include XDG base directory mixin into a class and you will get methods to reference the directories as well. And by defining #subdirectory the can be tailored specifically to your application.

      class X
        include XDG::BaseDir::Mixin

        def subdirectory
          "foo"
        end
      end
      x = X.new
      x.config.home.list  #=> ["~/.config/foo"]
      

See the API documentation for more details.