251
|
1 |
# gotenv |
|
2 |
|
|
3 |
[![Build Status](https://travis-ci.org/subosito/gotenv.svg?branch=master)](https://travis-ci.org/subosito/gotenv) |
|
4 |
[![Build status](https://ci.appveyor.com/api/projects/status/wb2e075xkfl0m0v2/branch/master?svg=true)](https://ci.appveyor.com/project/subosito/gotenv/branch/master) |
|
5 |
[![Coverage Status](https://badgen.net/codecov/c/github/subosito/gotenv)](https://codecov.io/gh/subosito/gotenv) |
|
6 |
[![Go Report Card](https://goreportcard.com/badge/github.com/subosito/gotenv)](https://goreportcard.com/report/github.com/subosito/gotenv) |
|
7 |
[![GoDoc](https://godoc.org/github.com/subosito/gotenv?status.svg)](https://godoc.org/github.com/subosito/gotenv) |
|
8 |
|
|
9 |
Load environment variables dynamically in Go. |
|
10 |
|
|
11 |
## Usage |
|
12 |
|
|
13 |
Put the gotenv package on your `import` statement: |
|
14 |
|
|
15 |
```go |
|
16 |
import "github.com/subosito/gotenv" |
|
17 |
``` |
|
18 |
|
|
19 |
To modify your app environment variables, `gotenv` expose 2 main functions: |
|
20 |
|
|
21 |
- `gotenv.Load` |
|
22 |
- `gotenv.Apply` |
|
23 |
|
|
24 |
By default, `gotenv.Load` will look for a file called `.env` in the current working directory. |
|
25 |
|
|
26 |
Behind the scene, it will then load `.env` file and export the valid variables to the environment variables. Make sure you call the method as soon as possible to ensure it loads all variables, say, put it on `init()` function. |
|
27 |
|
|
28 |
Once loaded you can use `os.Getenv()` to get the value of the variable. |
|
29 |
|
|
30 |
Let's say you have `.env` file: |
|
31 |
|
|
32 |
``` |
|
33 |
APP_ID=1234567 |
|
34 |
APP_SECRET=abcdef |
|
35 |
``` |
|
36 |
|
|
37 |
Here's the example of your app: |
|
38 |
|
|
39 |
```go |
|
40 |
package main |
|
41 |
|
|
42 |
import ( |
|
43 |
"github.com/subosito/gotenv" |
|
44 |
"log" |
|
45 |
"os" |
|
46 |
) |
|
47 |
|
|
48 |
func init() { |
|
49 |
gotenv.Load() |
|
50 |
} |
|
51 |
|
|
52 |
func main() { |
|
53 |
log.Println(os.Getenv("APP_ID")) // "1234567" |
|
54 |
log.Println(os.Getenv("APP_SECRET")) // "abcdef" |
|
55 |
} |
|
56 |
``` |
|
57 |
|
|
58 |
You can also load other than `.env` file if you wish. Just supply filenames when calling `Load()`. It will load them in order and the first value set for a variable will win.: |
|
59 |
|
|
60 |
```go |
|
61 |
gotenv.Load(".env.production", "credentials") |
|
62 |
``` |
|
63 |
|
|
64 |
While `gotenv.Load` loads entries from `.env` file, `gotenv.Apply` allows you to use any `io.Reader`: |
|
65 |
|
|
66 |
```go |
|
67 |
gotenv.Apply(strings.NewReader("APP_ID=1234567")) |
|
68 |
|
|
69 |
log.Println(os.Getenv("APP_ID")) |
|
70 |
// Output: "1234567" |
|
71 |
``` |
|
72 |
|
|
73 |
Both `gotenv.Load` and `gotenv.Apply` **DO NOT** overrides existing environment variables. If you want to override existing ones, you can see section below. |
|
74 |
|
|
75 |
### Environment Overrides |
|
76 |
|
|
77 |
Besides above functions, `gotenv` also provides another functions that overrides existing: |
|
78 |
|
|
79 |
- `gotenv.OverLoad` |
|
80 |
- `gotenv.OverApply` |
|
81 |
|
|
82 |
|
|
83 |
Here's the example of this overrides behavior: |
|
84 |
|
|
85 |
```go |
|
86 |
os.Setenv("HELLO", "world") |
|
87 |
|
|
88 |
// NOTE: using Apply existing value will be reserved |
|
89 |
gotenv.Apply(strings.NewReader("HELLO=universe")) |
|
90 |
fmt.Println(os.Getenv("HELLO")) |
|
91 |
// Output: "world" |
|
92 |
|
|
93 |
// NOTE: using OverApply existing value will be overridden |
|
94 |
gotenv.OverApply(strings.NewReader("HELLO=universe")) |
|
95 |
fmt.Println(os.Getenv("HELLO")) |
|
96 |
// Output: "universe" |
|
97 |
``` |
|
98 |
|
|
99 |
### Throw a Panic |
|
100 |
|
|
101 |
Both `gotenv.Load` and `gotenv.OverLoad` returns an error on something wrong occurred, like your env file is not exist, and so on. To make it easier to use, `gotenv` also provides `gotenv.Must` helper, to let it panic when an error returned. |
|
102 |
|
|
103 |
```go |
|
104 |
err := gotenv.Load(".env-is-not-exist") |
|
105 |
fmt.Println("error", err) |
|
106 |
// error: open .env-is-not-exist: no such file or directory |
|
107 |
|
|
108 |
gotenv.Must(gotenv.Load, ".env-is-not-exist") |
|
109 |
// it will throw a panic |
|
110 |
// panic: open .env-is-not-exist: no such file or directory |
|
111 |
``` |
|
112 |
|
|
113 |
### Another Scenario |
|
114 |
|
|
115 |
Just in case you want to parse environment variables from any `io.Reader`, gotenv keeps its `Parse` and `StrictParse` function as public API so you can use that. |
|
116 |
|
|
117 |
```go |
|
118 |
// import "strings" |
|
119 |
|
|
120 |
pairs := gotenv.Parse(strings.NewReader("FOO=test\nBAR=$FOO")) |
|
121 |
// gotenv.Env{"FOO": "test", "BAR": "test"} |
|
122 |
|
|
123 |
err, pairs = gotenv.StrictParse(strings.NewReader(`FOO="bar"`)) |
|
124 |
// gotenv.Env{"FOO": "bar"} |
|
125 |
``` |
|
126 |
|
|
127 |
`Parse` ignores invalid lines and returns `Env` of valid environment variables, while `StrictParse` returns an error for invalid lines. |
|
128 |
|
|
129 |
## Notes |
|
130 |
|
|
131 |
The gotenv package is a Go port of [`dotenv`](https://github.com/bkeepers/dotenv) project with some additions made for Go. For general features, it aims to be compatible as close as possible. |