1[](https://github.com/magiconair/properties/releases)
2[](https://travis-ci.org/magiconair/properties)
3[](https://raw.githubusercontent.com/magiconair/properties/master/LICENSE)
4[](http://godoc.org/github.com/magiconair/properties)
5
6# Overview
7
8#### Please run `git pull --tags` to update the tags. See [below](#updated-git-tags) why.
9
10properties is a Go library for reading and writing properties files.
11
12It supports reading from multiple files or URLs and Spring style recursive
13property expansion of expressions like `${key}` to their corresponding value.
14Value expressions can refer to other keys like in `${key}` or to environment
15variables like in `${USER}`. Filenames can also contain environment variables
16like in `/home/${USER}/myapp.properties`.
17
18Properties can be decoded into structs, maps, arrays and values through
19struct tags.
20
21Comments and the order of keys are preserved. Comments can be modified
22and can be written to the output.
23
24The properties library supports both ISO-8859-1 and UTF-8 encoded data.
25
26Starting from version 1.3.0 the behavior of the MustXXX() functions is
27configurable by providing a custom `ErrorHandler` function. The default has
28changed from `panic` to `log.Fatal` but this is configurable and custom
29error handling functions can be provided. See the package documentation for
30details.
31
32Read the full documentation on [](http://godoc.org/github.com/magiconair/properties)
33
34## Getting Started
35
36```go
37import (
38 "flag"
39 "github.com/magiconair/properties"
40)
41
42func main() {
43 // init from a file
44 p := properties.MustLoadFile("${HOME}/config.properties", properties.UTF8)
45
46 // or multiple files
47 p = properties.MustLoadFiles([]string{
48 "${HOME}/config.properties",
49 "${HOME}/config-${USER}.properties",
50 }, properties.UTF8, true)
51
52 // or from a map
53 p = properties.LoadMap(map[string]string{"key": "value", "abc": "def"})
54
55 // or from a string
56 p = properties.MustLoadString("key=value\nabc=def")
57
58 // or from a URL
59 p = properties.MustLoadURL("http://host/path")
60
61 // or from multiple URLs
62 p = properties.MustLoadURL([]string{
63 "http://host/config",
64 "http://host/config-${USER}",
65 }, true)
66
67 // or from flags
68 p.MustFlag(flag.CommandLine)
69
70 // get values through getters
71 host := p.MustGetString("host")
72 port := p.GetInt("port", 8080)
73
74 // or through Decode
75 type Config struct {
76 Host string `properties:"host"`
77 Port int `properties:"port,default=9000"`
78 Accept []string `properties:"accept,default=image/png;image;gif"`
79 Timeout time.Duration `properties:"timeout,default=5s"`
80 }
81 var cfg Config
82 if err := p.Decode(&cfg); err != nil {
83 log.Fatal(err)
84 }
85}
86
87```
88
89## Installation and Upgrade
90
91```
92$ go get -u github.com/magiconair/properties
93```
94
95## License
96
972 clause BSD license. See [LICENSE](https://github.com/magiconair/properties/blob/master/LICENSE) file for details.
98
99## ToDo
100
101* Dump contents with passwords and secrets obscured
102
103## Updated Git tags
104
105#### 13 Feb 2018
106
107I realized that all of the git tags I had pushed before v1.7.5 were lightweight tags
108and I've only recently learned that this doesn't play well with `git describe` 😞
109
110I have replaced all lightweight tags with signed tags using this script which should
111retain the commit date, name and email address. Please run `git pull --tags` to update them.
112
113Worst case you have to reclone the repo.
114
115```shell
116#!/bin/bash
117tag=$1
118echo "Updating $tag"
119date=$(git show ${tag}^0 --format=%aD | head -1)
120email=$(git show ${tag}^0 --format=%aE | head -1)
121name=$(git show ${tag}^0 --format=%aN | head -1)
122GIT_COMMITTER_DATE="$date" GIT_COMMITTER_NAME="$name" GIT_COMMITTER_EMAIL="$email" git tag -s -f ${tag} ${tag}^0 -m ${tag}
123```
124
125I apologize for the inconvenience.
126
127Frank
128
View as plain text