README.md
1# ConfigDir for Go
2
3This library provides a cross platform means of detecting the system's
4configuration directories so that your Go app can store config files in a
5standard location. For Linux and other Unixes (BSD, etc.) this means using the
6[Freedesktop.org XDG Base Directory Specification][1] (0.8), and for Windows
7and macOS it uses their standard directories.
8
9This is a simple no-nonsense module that just gives you the path names to do
10with as you please. You can either get the bare root config path, or get a
11path with any number of names suffixed onto it for vendor- or
12application-specific namespacing.
13
14For the impatient, the directories this library can return tend to be like
15the following:
16
17| | **System-wide Configuration** |
18|---------|-----------------------------------------------------|
19| Windows | `%PROGRAMDATA%` or `C:\ProgramData` |
20| Linux | `$XDG_CONFIG_DIRS` or `/etc/xdg` |
21| macOS | `/Library/Application Support` |
22| | **User-level Configuration** |
23| Windows | `%APPDATA%` or `C:\Users\%USER%\AppData\Roaming` |
24| Linux | `$XDG_CONFIG_HOME` or `$HOME/.config` |
25| macOS | `$HOME/Library/Application Support` |
26| | **User-level Cache Folder** |
27| Windows | `%LOCALAPPDATA%` or `C:\Users\%USER%\AppData\Local` |
28| Linux | `$XDG_CACHE_HOME` or `$HOME/.cache` |
29| macOS | `$HOME/Library/Caches` |
30
31## Quick Start
32
33```go
34// A common use case is to get a private config folder for your app to
35// place its settings files into, that are specific to the local user.
36configPath := configdir.LocalConfig("my-app")
37err := configdir.MakePath(configPath) // Ensure it exists.
38if err != nil {
39 panic(err)
40}
41
42// Deal with a JSON configuration file in that folder.
43configFile := filepath.Join(configPath, "settings.json")
44type AppSettings struct {
45 Username string `json:"username"`
46 Password string `json:"password"`
47}
48var settings AppSettings
49
50// Does the file not exist?
51if _, err = os.Stat(configFile); os.IsNotExist(err) {
52 // Create the new config file.
53 settings = AppSettings{"MyUser", "MyPassword"}
54 fh, err := os.Create(configFile)
55 if err != nil {
56 panic(err)
57 }
58 defer fh.Close()
59
60 encoder := json.NewEncoder(fh)
61 encoder.Encode(&settings)
62} else {
63 // Load the existing file.
64 fh, err := os.Open(configFile)
65 if err != nil {
66 panic(err)
67 }
68 defer fh.Close()
69
70 decoder := json.NewDecoder(fh)
71 decoder.Decode(&settings)
72}
73```
74
75## Documentation
76
77Package documentation is available at
78<https://godoc.org/github.com/kirsle/configdir>
79
80## Author
81
82Noah Petherbridge, [@kirsle](https://github.com/kirsle)
83
84## License
85
86MIT
87
88[1]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-0.8.html
89[2]: https://github.com/shibukawa/configdir
90