README.md
1# GoDotEnv [](https://travis-ci.org/joho/godotenv) [](https://ci.appveyor.com/project/joho/godotenv) [](https://goreportcard.com/report/github.com/joho/godotenv)
2
3A Go (golang) port of the Ruby dotenv project (which loads env vars from a .env file)
4
5From the original Library:
6
7> Storing configuration in the environment is one of the tenets of a twelve-factor app. Anything that is likely to change between deployment environments–such as resource handles for databases or credentials for external services–should be extracted from the code into environment variables.
8>
9> But it is not always practical to set environment variables on development machines or continuous integration servers where multiple projects are run. Dotenv load variables from a .env file into ENV when the environment is bootstrapped.
10
11It can be used as a library (for loading in env for your own daemons etc) or as a bin command.
12
13There is test coverage and CI for both linuxish and windows environments, but I make no guarantees about the bin version working on windows.
14
15## Installation
16
17As a library
18
19```shell
20go get github.com/joho/godotenv
21```
22
23or if you want to use it as a bin command
24```shell
25go get github.com/joho/godotenv/cmd/godotenv
26```
27
28## Usage
29
30Add your application configuration to your `.env` file in the root of your project:
31
32```shell
33S3_BUCKET=YOURS3BUCKET
34SECRET_KEY=YOURSECRETKEYGOESHERE
35```
36
37Then in your Go app you can do something like
38
39```go
40package main
41
42import (
43 "github.com/joho/godotenv"
44 "log"
45 "os"
46)
47
48func main() {
49 err := godotenv.Load()
50 if err != nil {
51 log.Fatal("Error loading .env file")
52 }
53
54 s3Bucket := os.Getenv("S3_BUCKET")
55 secretKey := os.Getenv("SECRET_KEY")
56
57 // now do something with s3 or whatever
58}
59```
60
61If you're even lazier than that, you can just take advantage of the autoload package which will read in `.env` on import
62
63```go
64import _ "github.com/joho/godotenv/autoload"
65```
66
67While `.env` in the project root is the default, you don't have to be constrained, both examples below are 100% legit
68
69```go
70_ = godotenv.Load("somerandomfile")
71_ = godotenv.Load("filenumberone.env", "filenumbertwo.env")
72```
73
74If you want to be really fancy with your env file you can do comments and exports (below is a valid env file)
75
76```shell
77# I am a comment and that is OK
78SOME_VAR=someval
79FOO=BAR # comments at line end are OK too
80export BAR=BAZ
81```
82
83Or finally you can do YAML(ish) style
84
85```yaml
86FOO: bar
87BAR: baz
88```
89
90as a final aside, if you don't want godotenv munging your env you can just get a map back instead
91
92```go
93var myEnv map[string]string
94myEnv, err := godotenv.Read()
95
96s3Bucket := myEnv["S3_BUCKET"]
97```
98
99... or from an `io.Reader` instead of a local file
100
101```go
102reader := getRemoteFile()
103myEnv, err := godotenv.Parse(reader)
104```
105
106... or from a `string` if you so desire
107
108```go
109content := getRemoteFileContent()
110myEnv, err := godotenv.Unmarshal(content)
111```
112
113### Command Mode
114
115Assuming you've installed the command as above and you've got `$GOPATH/bin` in your `$PATH`
116
117```
118godotenv -f /some/path/to/.env some_command with some args
119```
120
121If you don't specify `-f` it will fall back on the default of loading `.env` in `PWD`
122
123### Writing Env Files
124
125Godotenv can also write a map representing the environment to a correctly-formatted and escaped file
126
127```go
128env, err := godotenv.Unmarshal("KEY=value")
129err := godotenv.Write(env, "./.env")
130```
131
132... or to a string
133
134```go
135env, err := godotenv.Unmarshal("KEY=value")
136content, err := godotenv.Marshal(env)
137```
138
139## Contributing
140
141Contributions are most welcome! The parser itself is pretty stupidly naive and I wouldn't be surprised if it breaks with edge cases.
142
143*code changes without tests will not be accepted*
144
1451. Fork it
1462. Create your feature branch (`git checkout -b my-new-feature`)
1473. Commit your changes (`git commit -am 'Added some feature'`)
1484. Push to the branch (`git push origin my-new-feature`)
1495. Create new Pull Request
150
151## Releases
152
153Releases should follow [Semver](http://semver.org/) though the first couple of releases are `v1` and `v1.1`.
154
155Use [annotated tags for all releases](https://github.com/joho/godotenv/issues/30). Example `git tag -a v1.2.1`
156
157## CI
158
159Linux: [](https://travis-ci.org/joho/godotenv) Windows: [](https://ci.appveyor.com/project/joho/godotenv)
160
161## Who?
162
163The original library [dotenv](https://github.com/bkeepers/dotenv) was written by [Brandon Keepers](http://opensoul.org/), and this port was done by [John Barton](https://johnbarton.co/) based off the tests/fixtures in the original library.
164
){kind=link}