finddirs

README

finddirs

This is a Go package for retrieving common directories found across all operating systems.

Locations

Application Directories

Directory	Unix [1][2]	Windows [3]	macOS & iOS [5]	Plan 9
Config directory (system-wide)	/etc	C:/ProgramData	/Library/Application Support	/lib
Config directory (local)	~/.config	C:/<user>/AppData/<Local or Roaming> [4]	~/Library/Application Support	~/lib
State directory (system-wide)	/var/lib	C:/ProgramData	/Library/Application Support	/lib
State directory (local)	~/.local/state	C:/<user>/AppData/Local	~/Library/Application Support	~/lib
Cache directory (system-wide)	/var/cache	C:/ProgramData	/Library/Caches	/lib/cache
Cache directory (local)	~/.cache	C:/<user>/AppData/Local	~/Library/Caches	~/lib/cache

1. On Unix based systems, XDG environment variables $XDG_CONFIG_HOME, $XDG_STATE_HOME, and $XDG_CACHE_HOME are first tried for paths ~/.config, ~/.local/state, and ~/.cache respectively. If the particular XDG environment variable is set, it is used instead.
2. If Termux is detected on Android, system-wide directories will be under ~/../usr (of course, as an absolute path).
3. On Windows, KNOWNFOLDERID constants are used.
4. Usage of AppData\Local or AppData\Roaming depends on whether UseRoaming is set to true in Config struct.
5. System-wide directories are not supported on iOS — iOS apps are inside a sandbox, therefore system-wide directories cannot be accessed. Calling RetrieveAppDirs with systemWide argument set to true will result with an error.

User Directories

Directory	Unix [1], macOS, and Windows (Also See [2], [3], and [4])
Desktop	~/Desktop
Downloads	~/Downloads
Documents	~/Documents
Pictures	~/Pictures
Videos	~/Videos on Linux and Windows, ~/Movies on macOS
Music	~/Music
Templates	~/Templates
Fonts	$XDG_DATA_HOME/fonts, ~/.local/share/fonts, ~/.fonts, /usr/share/fonts, and /usr/local/share/fonts on Linux
	~/Library/Fonts, /Library/Fonts, /System/Library/Fonts, and /Network/Library/Fonts on macOS
	C:/WINDOWS/Fonts and C:/Users/<USER>/AppData/Local/Microsoft/Windows/Fonts on Windows
PublicShare	~/Public on Linux and macOS, C:\Users\Public on Windows

1. On Unix based systems, entries in user-dirs.dirs are read. If user-dirs.dirs cannot be found, or it's malformed, RetrieveUserDirs returns with error. If an entry is $HOME/ (that means, it is empty), it is set to an empty string (""), and no error is returned. On Unix, check for empty directories.
2. Plan 9 is not supported. RetrieveUserDirs on a Plan 9 system will return an error.
3. If Termux is detected on Android, the Desktop, Templates, Fonts, and PublicShare directories will be empty, as they don't exist on the that platform.
4. iOS is not supported. RetrieveUserDirs on an iOS system will return an error.

Usage

Very straightforward: go get -u github.com/karagenc/finddirs-go

package main

import (
	"fmt"

	"github.com/karagenc/finddirs-go"
)

func main() {
	userAppDirs, _ := finddirs.RetrieveAppDirs(false, nil)
	fmt.Println(userAppDirs)
	systemAppDirs, _ := finddirs.RetrieveAppDirs(true, nil)
	fmt.Println(systemAppDirs)

	userDirs, _ := finddirs.RetrieveUserDirs()
	fmt.Println(userDirs)
}

Remarks/Notes

• Since you're dealing with directories:

  • Let me recommend github.com/mitchellh/go-homedir. It is used by this library and is much more reliable than os.UserHomeDir().
  • For those who want to dive deep, here are platform-specific documentations:
    • XDG Base Directory Specification
    • Apple File System Programming Guide
    • Microsoft Documentation on KNOWNFOLDERID constants

• filepath.ToSlash was used for every directory returned from functions in this package. This is to prevent shellwords from interpreting backslash as escape character. To test this behavior, remove this line, and see what happens. Use filepath.FromSlash to convert slashes to OS-specific path seperators.

Documentation

Index

• Variables
• type AppConfig
• type AppDirs
  • func RetrieveAppDirs(systemWide bool, config *AppConfig) (appDirs *AppDirs, err error)
• type UserDirs
  • func RetrieveUserDirs() (userDirs *UserDirs, err error)

Variables

var (
	ErrOSNotSupportedUserDirs         = fmt.Errorf("RetrieveUserDirs doesn't support this operating system")
	ErrOSNotSupportedAppDirsSystemIOS = fmt.Errorf("cannot get system-wide app directories: iOS apps are inside a sandbox, therefore iOS apps cannot have system-wide app directories")
)

Types

type AppConfig

type AppConfig struct {
	// Application directory.
	// If non-empty, it will be appended (path.Join'ed) at the end of returned paths.
	Subdir string
	// Application directory for Unix. Overrides `Subdir`.
	// If non-empty, it will be used instead of `Subdir` on Unix based systems and
	// appended (path.Join'ed) at the end of returned paths.
	SubdirUnix string
	// Application directory for macOS and iOS. Overrides `Subdir`.
	// If non-empty, it will be used instead
	// of `Subdir` on macOS & iOS and appended (path.Join'ed) at the end of returned paths.
	SubdirDarwinIOS string
	// Application directory for Windows. Overrides `Subdir`.
	// If non-empty, it will be used instead of `Subdir` on Windows and appended (path.Join'ed)
	// at the end of returned paths.
	SubdirWindows string
	// Application directory for Plan 9. Overrides `Subdir`.
	// If non-empty, it will be used instead of `Subdir` on Plan 9 and appended (path.Join'ed)
	// at the end of returned paths.
	SubdirPlan9 string

	// Don't append subdirectory if config path is (or it ends with) /etc on Unix.
	//
	// If true, returns /etc instead of /etc/subdir
	//
	// Also applies to $XDG_CONFIG_HOME. If the value of $XDG_CONFIG_HOME ends with /etc,
	// subdirectory will not be appended.
	NoEtcSubdir bool

	// Defines whether config directory should be synchronizable across devices.
	//
	// If true, instead of %USERPROFILE%\AppData\Local, %USERPROFILE%\AppData\Roaming is used (only with `ConfigDir`).
	// This doesn't have an effect on other systems and only applies to config directory.
	//
	// If you don't know what you're doing, just leave this as false.
	// This doesn't have an effect if `System` is set to true.
	UseRoaming bool

	// To prevent potential conflicts arising from the same directory being
	// returned by the `ConfigDir`, `StateDir`, and `CacheDir` methods, this variable can be used.
	//
	// If `SubdirState` is non-empty, and state path is the same path as one of the other paths,
	// `SubdirState` is appended at the end of state path to prevent overlap of files.
	//
	// `SubdirState` doesn't have an effect if `Subdir` is empty.
	SubdirState string

	// To prevent potential conflicts arising from the same directory being
	// returned by the `ConfigDir`, `StateDir`, and `CacheDir` methods, this variable can be used.
	//
	// If `SubdirCache` is non-empty, and cache path is the same path as one of the other paths,
	// `SubdirCache` is appended at the end of cache path to prevent overlap of files.
	//
	// `SubdirCache` doesn't have an effect if `Subdir` is empty.
	SubdirCache string
}

type AppDirs

type AppDirs struct {
	// For files for user to configure.
	ConfigDir string
	// For files that are needed for application to save its state and
	// continue where it left off. Files inside this directory typically
	// don't need user intervention.
	//
	// Example file: SQLite database.
	StateDir string
	// For files that are not needed to persist (just like with `TempDir`)
	// but should live longer than files in `TempDir`.
	// Apple documentation had explained this properly: "Generally speaking,
	// the application does not require cache data to operate properly,
	// but it can use cache data to improve performance."
	//
	// Since cache directory can be deleted, the app must be able to
	// re-create or download the files as needed.
	//
	// Example contents: compilation cache, downloaded packages that
	// are going to be installed, downloaded videos that are going to be
	// converted to audio format and deleted afterwards.
	CacheDir string
}

func RetrieveAppDirs

func RetrieveAppDirs(systemWide bool, config *AppConfig) (appDirs *AppDirs, err error)

type UserDirs

type UserDirs struct {
	Desktop     string
	Downloads   string
	Documents   string
	Pictures    string
	Videos      string
	Music       string
	Fonts       []string
	Templates   string
	PublicShare string
}

func RetrieveUserDirs

func RetrieveUserDirs() (userDirs *UserDirs, err error)

On Linux, XDG directories may be unset. If a directory is unset, its value within `UserDirs` struct will be empty.