251
|
1 |
# gotenv |
|
2 |
|
260
|
3 |
[![Build Status](https://github.com/subosito/gotenv/workflows/Go%20workflow/badge.svg)](https://github.com/subosito/gotenv/actions) |
251
|
4 |
[![Coverage Status](https://badgen.net/codecov/c/github/subosito/gotenv)](https://codecov.io/gh/subosito/gotenv) |
|
5 |
[![Go Report Card](https://goreportcard.com/badge/github.com/subosito/gotenv)](https://goreportcard.com/report/github.com/subosito/gotenv) |
|
6 |
[![GoDoc](https://godoc.org/github.com/subosito/gotenv?status.svg)](https://godoc.org/github.com/subosito/gotenv) |
|
7 |
|
260
|
8 |
Load environment variables from `.env` or `io.Reader` in Go. |
251
|
9 |
|
|
10 |
## Usage |
|
11 |
|
|
12 |
Put the gotenv package on your `import` statement: |
|
13 |
|
|
14 |
```go |
|
15 |
import "github.com/subosito/gotenv" |
|
16 |
``` |
|
17 |
|
|
18 |
To modify your app environment variables, `gotenv` expose 2 main functions: |
|
19 |
|
|
20 |
- `gotenv.Load` |
|
21 |
- `gotenv.Apply` |
|
22 |
|
|
23 |
By default, `gotenv.Load` will look for a file called `.env` in the current working directory. |
|
24 |
|
|
25 |
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. |
|
26 |
|
|
27 |
Once loaded you can use `os.Getenv()` to get the value of the variable. |
|
28 |
|
|
29 |
Let's say you have `.env` file: |
|
30 |
|
260
|
31 |
```sh |
251
|
32 |
APP_ID=1234567 |
|
33 |
APP_SECRET=abcdef |
|
34 |
``` |
|
35 |
|
|
36 |
Here's the example of your app: |
|
37 |
|
|
38 |
```go |
|
39 |
package main |
|
40 |
|
|
41 |
import ( |
|
42 |
"github.com/subosito/gotenv" |
|
43 |
"log" |
|
44 |
"os" |
|
45 |
) |
|
46 |
|
|
47 |
func init() { |
|
48 |
gotenv.Load() |
|
49 |
} |
|
50 |
|
|
51 |
func main() { |
|
52 |
log.Println(os.Getenv("APP_ID")) // "1234567" |
|
53 |
log.Println(os.Getenv("APP_SECRET")) // "abcdef" |
|
54 |
} |
|
55 |
``` |
|
56 |
|
|
57 |
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.: |
|
58 |
|
|
59 |
```go |
|
60 |
gotenv.Load(".env.production", "credentials") |
|
61 |
``` |
|
62 |
|
|
63 |
While `gotenv.Load` loads entries from `.env` file, `gotenv.Apply` allows you to use any `io.Reader`: |
|
64 |
|
|
65 |
```go |
|
66 |
gotenv.Apply(strings.NewReader("APP_ID=1234567")) |
|
67 |
|
|
68 |
log.Println(os.Getenv("APP_ID")) |
|
69 |
// Output: "1234567" |
|
70 |
``` |
|
71 |
|
|
72 |
Both `gotenv.Load` and `gotenv.Apply` **DO NOT** overrides existing environment variables. If you want to override existing ones, you can see section below. |
|
73 |
|
|
74 |
### Environment Overrides |
|
75 |
|
|
76 |
Besides above functions, `gotenv` also provides another functions that overrides existing: |
|
77 |
|
|
78 |
- `gotenv.OverLoad` |
|
79 |
- `gotenv.OverApply` |
|
80 |
|
|
81 |
Here's the example of this overrides behavior: |
|
82 |
|
|
83 |
```go |
|
84 |
os.Setenv("HELLO", "world") |
|
85 |
|
|
86 |
// NOTE: using Apply existing value will be reserved |
|
87 |
gotenv.Apply(strings.NewReader("HELLO=universe")) |
|
88 |
fmt.Println(os.Getenv("HELLO")) |
|
89 |
// Output: "world" |
|
90 |
|
|
91 |
// NOTE: using OverApply existing value will be overridden |
|
92 |
gotenv.OverApply(strings.NewReader("HELLO=universe")) |
|
93 |
fmt.Println(os.Getenv("HELLO")) |
|
94 |
// Output: "universe" |
|
95 |
``` |
|
96 |
|
|
97 |
### Throw a Panic |
|
98 |
|
|
99 |
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. |
|
100 |
|
|
101 |
```go |
|
102 |
err := gotenv.Load(".env-is-not-exist") |
|
103 |
fmt.Println("error", err) |
|
104 |
// error: open .env-is-not-exist: no such file or directory |
|
105 |
|
|
106 |
gotenv.Must(gotenv.Load, ".env-is-not-exist") |
|
107 |
// it will throw a panic |
|
108 |
// panic: open .env-is-not-exist: no such file or directory |
|
109 |
``` |
|
110 |
|
|
111 |
### Another Scenario |
|
112 |
|
|
113 |
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. |
|
114 |
|
|
115 |
```go |
|
116 |
// import "strings" |
|
117 |
|
|
118 |
pairs := gotenv.Parse(strings.NewReader("FOO=test\nBAR=$FOO")) |
|
119 |
// gotenv.Env{"FOO": "test", "BAR": "test"} |
|
120 |
|
260
|
121 |
pairs, err := gotenv.StrictParse(strings.NewReader(`FOO="bar"`)) |
251
|
122 |
// gotenv.Env{"FOO": "bar"} |
|
123 |
``` |
|
124 |
|
|
125 |
`Parse` ignores invalid lines and returns `Env` of valid environment variables, while `StrictParse` returns an error for invalid lines. |
|
126 |
|
|
127 |
## Notes |
|
128 |
|
|
129 |
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. |