Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/adrg/xdg
Go implementation of the XDG Base Directory Specification and XDG user directories
https://github.com/adrg/xdg
cross-platform go golang golang-library golang-package known-folders library linux macos plan9 specification unix windows xdg xdg-basedir xdg-compliance xdg-specs xdg-user-dirs
Last synced: 5 days ago
JSON representation
Go implementation of the XDG Base Directory Specification and XDG user directories
- Host: GitHub
- URL: https://github.com/adrg/xdg
- Owner: adrg
- License: mit
- Created: 2014-08-22T08:23:40.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2024-10-29T13:32:03.000Z (about 1 month ago)
- Last Synced: 2024-10-29T14:58:20.135Z (about 1 month ago)
- Topics: cross-platform, go, golang, golang-library, golang-package, known-folders, library, linux, macos, plan9, specification, unix, windows, xdg, xdg-basedir, xdg-compliance, xdg-specs, xdg-user-dirs
- Language: Go
- Homepage: https://pkg.go.dev/github.com/adrg/xdg
- Size: 232 KB
- Stars: 701
- Watchers: 9
- Forks: 29
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- fucking-awesome-go - xdg - Go implementation of the 🌎 [XDG Base Directory Specification](specifications.freedesktop.org/basedir-spec/latest/) and 🌎 [XDG user directories](wiki.archlinux.org/index.php/XDG_user_directories). (Configuration / Standard CLI)
- awesome-go - xdg - Go implementation of the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/latest/) and [XDG user directories](https://wiki.archlinux.org/index.php/XDG_user_directories). (Configuration / Standard CLI)
- awesome-go - xdg - Go implementation of the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) and [XDG user directories](https://wiki.archlinux.org/index.php/XDG_user_directories). (Configuration / Standard CLI)
- awesome-go-extra - xdg - 08-22T08:23:40Z|2022-08-06T23:09:49Z| (Configuration / Advanced Console UIs)
- awesome-go-with-stars - xdg - Go implementation of the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/latest/) and [XDG user directories](https://wiki.archlinux.org/index.php/XDG_user_directories). (Configuration / Standard CLI)
- awesome-go - xdg - Go implementation of the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/latest/) and [XDG user directories](https://wiki.archlinux.org/index.php/XDG_user_directories). (Configuration / Standard CLI)
- awesome-go-cn - xdg - spec/latest/) and [XDG user directories](https://wiki.archlinux.org/index.php/XDG_user_directories). [![近一周有更新][G]](https://github.com/adrg/xdg) [![godoc][D]](https://godoc.org/github.com/adrg/xdg) (é…Ťç˝® / ć ‡ĺ‡†CLI)
- awesome-go-plus - xdg - Go implementation of the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/latest/) and [XDG user directories](https://wiki.archlinux.org/index.php/XDG_user_directories).  (Configuration / Standard CLI)
README
Go implementation of the XDG Base Directory Specification and XDG user directories.
Provides an implementation of the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html).
The specification defines a set of standard paths for storing application files,
including data and configuration files. For portability and flexibility reasons,
applications should use the XDG defined locations instead of hardcoding paths.
The package also includes the locations of well known [user directories](https://wiki.archlinux.org/index.php/XDG_user_directories),
support for the non-standard `XDG_BIN_HOME` directory, as well as other common directories such as fonts and applications.
The current implementation supports **most flavors of Unix**, **Windows**, **macOS** and **Plan 9**.
On Windows, where XDG environment variables are not usually set, the package uses [Known Folders](https://docs.microsoft.com/en-us/windows/win32/shell/known-folders)
as defaults. Therefore, appropriate locations are used for common [folders](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid) which may have been redirected.
See usage [examples](#usage) below. Full documentation can be found at https://pkg.go.dev/github.com/adrg/xdg.
## Installation
go get github.com/adrg/xdg
## Default locations
The package defines sensible defaults for XDG variables which are empty or not
present in the environment.
- On Unix-like operating systems, XDG environment variables are typically defined.
Appropriate default locations are used for the environment variables which are not set.
- On Windows, XDG environment variables are usually not set. If that is the case,
the package relies on the appropriate [Known Folders](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid).
Sensible fallback locations are used for the folders which are not set.
### XDG Base Directory
Unix-like operating systems
| ![]()
| ![]()
Unix
| ![]()
macOS
| ![]()
Plan 9
|
| :------------------------------------------------------------: | :-----------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------: |
| XDG_DATA_HOME | ~/.local/share | ~/Library/Application Support | $home/lib |
| XDG_DATA_DIRS | /usr/local/share
/usr/share | /Library/Application Support~/.local/share | /lib |
| XDG_CONFIG_HOME | ~/.config | ~/Library/Application Support | $home/lib |
| XDG_CONFIG_DIRS | /etc/xdg | ~/Library/Preferences
/Library/Application Support
/Library/Preferences
~/.config | /lib |
| XDG_STATE_HOME | ~/.local/state | ~/Library/Application Support | $home/lib/state |
| XDG_CACHE_HOME | ~/.cache | ~/Library/Caches | $home/lib/cache |
| XDG_RUNTIME_DIR | /run/user/$UID | ~/Library/Application Support | /tmp |
| XDG_BIN_HOME | ~/.local/bin | ~/.local/bin | $home/bin |
Microsoft Windows
| ![]()
| ![]()
Known Folder(s)
| ![]()
Fallback(s)
|
| :------------------------------------------------------------: | :---------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------: |
| XDG_DATA_HOME | LocalAppData | %LOCALAPPDATA% |
| XDG_DATA_DIRS | RoamingAppData
ProgramData | %APPADATA%
%ProgramData% |
| XDG_CONFIG_HOME | LocalAppData | %LOCALAPPDATA% |
| XDG_CONFIG_DIRS | ProgramData
RoamingAppData | %ProgramData%
%APPDATA% |
| XDG_STATE_HOME | LocalAppData | %LOCALAPPDATA% |
| XDG_CACHE_HOME | LocalAppData\cache | %LOCALAPPDATA%\cache |
| XDG_RUNTIME_DIR | LocalAppData | %LOCALAPPDATA% |
| XDG_BIN_HOME | UserProgramFiles | %LOCALAPPDATA%\Programs |
### XDG user directories
XDG user directories environment variables are usually **not** set on most
operating systems. However, if they are present in the environment, they take
precedence. Appropriate fallback locations are used for the environment
variables which are not set.
- On Unix-like operating systems (except macOS and Plan 9), the package reads the [user-dirs.dirs](https://man.archlinux.org/man/user-dirs.dirs.5.en) config file.
- On Windows, the package uses the appropriate [Known Folders](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid).
Lastly, default locations are used for any user directories which are not set,
as shown in the following tables.
Unix-like operating systems
| ![]()
| ![]()
Unix
| ![]()
macOS
| ![]()
Plan 9
|
| :--------------------------------------------------------------: | :-------------------------------------------------------------------------: | :---------------------------------------------------------------------------: | :---------------------------------------------------------------------------: |
| XDG_DESKTOP_DIR | ~/Desktop | ~/Desktop | $home/desktop |
| XDG_DOWNLOAD_DIR | ~/Downloads | ~/Downloads | $home/downloads |
| XDG_DOCUMENTS_DIR | ~/Documents | ~/Documents | $home/documents |
| XDG_MUSIC_DIR | ~/Music | ~/Music | $home/music |
| XDG_PICTURES_DIR | ~/Pictures | ~/Pictures | $home/pictures |
| XDG_VIDEOS_DIR | ~/Videos | ~/Movies | $home/videos |
| XDG_TEMPLATES_DIR | ~/Templates | ~/Templates | $home/templates |
| XDG_PUBLICSHARE_DIR | ~/Public | ~/Public | $home/public |
Microsoft Windows
| ![]()
| ![]()
Known Folder(s)
| ![]()
Fallback(s)
|
| :--------------------------------------------------------------: | :-----------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------: |
| XDG_DESKTOP_DIR | Desktop | %USERPROFILE%\Desktop |
| XDG_DOWNLOAD_DIR | Downloads | %USERPROFILE%\Downloads |
| XDG_DOCUMENTS_DIR | Documents | %USERPROFILE%\Documents |
| XDG_MUSIC_DIR | Music | %USERPROFILE%\Music |
| XDG_PICTURES_DIR | Pictures | %USERPROFILE%\Pictures |
| XDG_VIDEOS_DIR | Videos | %USERPROFILE%\Videos |
| XDG_TEMPLATES_DIR | Templates | %APPDATA%\Microsoft\Windows\Templates |
| XDG_PUBLICSHARE_DIR | Public | %PUBLIC% |
### Other directories
Unix-like operating systems
| ![]()
| ![]()
Unix
| ![]()
macOS
| ![]()
Plan 9
|
| :-----------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------: |
| Home | $HOME | $HOME | $home |
| Applications | $XDG_DATA_HOME/applications
~/.local/share/applications
/usr/local/share/applications
/usr/share/applications
$XDG_DATA_DIRS/applications | /Applications | $home/bin
/bin |
| Fonts | $XDG_DATA_HOME/fonts
~/.fonts
~/.local/share/fonts
/usr/local/share/fonts
/usr/share/fonts
$XDG_DATA_DIRS/fonts | ~/Library/Fonts
/Library/Fonts
/System/Library/Fonts
/Network/Library/Fonts | $home/lib/font
/lib/font |
Microsoft Windows
| ![]()
| ![]()
Known Folder(s)
| ![]()
Fallback(s)
|
| :-----------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| Home | Profile | %USERPROFILE% |
| Applications | Programs
CommonPrograms
ProgramFiles
ProgramFilesCommon
UserProgramFiles
UserProgramFilesCommon | %APPDATA%\Microsoft\Windows\Start Menu\Programs
%ProgramData%\Microsoft\Windows\Start Menu\Programs
%ProgramFiles%
%ProgramFiles%\Common Files
%LOCALAPPDATA%\Programs
%LOCALAPPDATA%\Programs\Common|
| Fonts | Fonts | %SystemRoot%\Fonts
%LOCALAPPDATA%\Microsoft\Windows\Fonts |
## Usage
#### XDG Base Directory
```go
package main
import (
"log"
"github.com/adrg/xdg"
)
func main() {
// XDG Base Directory paths.
log.Println("Home data directory:", xdg.DataHome)
log.Println("Data directories:", xdg.DataDirs)
log.Println("Home config directory:", xdg.ConfigHome)
log.Println("Config directories:", xdg.ConfigDirs)
log.Println("Home state directory:", xdg.StateHome)
log.Println("Cache directory:", xdg.CacheHome)
log.Println("Runtime directory:", xdg.RuntimeDir)
log.Println("Home binaries directory:", xdg.BinHome)
// Other common directories.
log.Println("Home directory:", xdg.Home)
log.Println("Application directories:", xdg.ApplicationDirs)
log.Println("Font directories:", xdg.FontDirs)
// Obtain a suitable location for application config files.
// ConfigFile takes one parameter which must contain the name of the file,
// but it can also contain a set of parent directories. If the directories
// don't exist, they will be created relative to the base config directory.
// It is recommended for files to be saved inside an application directory
// relative to the base directory rather than directly inside the base
// directory (e.g. `appname/config.yaml` instead of `appname-config.yaml`).
configFilePath, err := xdg.ConfigFile("appname/config.yaml")
if err != nil {
log.Fatal(err)
}
log.Println("Save the config file at:", configFilePath)
// For other types of application files use:
// xdg.DataFile()
// xdg.StateFile()
// xdg.CacheFile()
// xdg.RuntimeFile()
// Finding application config files.
// SearchConfigFile takes one parameter which must contain the name of
// the file, but it can also contain a set of parent directories relative
// to the config search paths (xdg.ConfigHome and xdg.ConfigDirs).
configFilePath, err = xdg.SearchConfigFile("appname/config.yaml")
if err != nil {
log.Fatal(err)
}
log.Println("Config file was found at:", configFilePath)
// For other types of application files use:
// xdg.SearchDataFile()
// xdg.SearchStateFile()
// xdg.SearchCacheFile()
// xdg.SearchRuntimeFile()
}
```
#### XDG user directories
```go
package main
import (
"log"
"github.com/adrg/xdg"
)
func main() {
// XDG user directories.
log.Println("Desktop directory:", xdg.UserDirs.Desktop)
log.Println("Download directory:", xdg.UserDirs.Download)
log.Println("Documents directory:", xdg.UserDirs.Documents)
log.Println("Music directory:", xdg.UserDirs.Music)
log.Println("Pictures directory:", xdg.UserDirs.Pictures)
log.Println("Videos directory:", xdg.UserDirs.Videos)
log.Println("Templates directory:", xdg.UserDirs.Templates)
log.Println("Public directory:", xdg.UserDirs.PublicShare)
}
```
## Stargazers over time
[](https://starchart.cc/adrg/xdg)
## Contributing
Contributions in the form of pull requests, issues or just general feedback,
are always welcome.
See [CONTRIBUTING.MD](CONTRIBUTING.md).
**Contributors**:
[adrg](https://github.com/adrg),
[wichert](https://github.com/wichert),
[bouncepaw](https://github.com/bouncepaw),
[gabriel-vasile](https://github.com/gabriel-vasile),
[KalleDK](https://github.com/KalleDK),
[nvkv](https://github.com/nvkv),
[djdv](https://github.com/djdv),
[rrjjvv](https://github.com/rrjjvv),
[GreyXor](https://github.com/GreyXor),
[Rican7](https://github.com/Rican7),
[nothub](https://github.com/nothub).
## References
For more information see:
* [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html)
* [XDG user directories](https://wiki.archlinux.org/index.php/XDG_user_directories)
* [Windows Known Folders](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid)
## License
Copyright (c) 2014 Adrian-George Bostan.
This project is licensed under the [MIT license](https://opensource.org/licenses/MIT).
See [LICENSE](LICENSE) for more details.