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
9Load environment variables dynamically in Go.
10
11## Usage
12
13Put the gotenv package on your `import` statement:
14
15```go
16import "github.com/subosito/gotenv"
17```
18
19To modify your app environment variables, `gotenv` expose 2 main functions:
20
21- `gotenv.Load`
22- `gotenv.Apply`
23
24By default, `gotenv.Load` will look for a file called `.env` in the current working directory.
25
26Behind 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
28Once loaded you can use `os.Getenv()` to get the value of the variable.
29
30Let's say you have `.env` file:
31
32```
33APP_ID=1234567
34APP_SECRET=abcdef
35```
36
37Here's the example of your app:
38
39```go
40package main
41
42import (
43	"github.com/subosito/gotenv"
44	"log"
45	"os"
46)
47
48func init() {
49	gotenv.Load()
50}
51
52func main() {
53	log.Println(os.Getenv("APP_ID"))     // "1234567"
54	log.Println(os.Getenv("APP_SECRET")) // "abcdef"
55}
56```
57
58You 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
61gotenv.Load(".env.production", "credentials")
62```
63
64While `gotenv.Load` loads entries from `.env` file, `gotenv.Apply` allows you to use any `io.Reader`:
65
66```go
67gotenv.Apply(strings.NewReader("APP_ID=1234567"))
68
69log.Println(os.Getenv("APP_ID"))
70// Output: "1234567"
71```
72
73Both `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
77Besides above functions, `gotenv` also provides another functions that overrides existing:
78
79- `gotenv.OverLoad`
80- `gotenv.OverApply`
81
82
83Here's the example of this overrides behavior:
84
85```go
86os.Setenv("HELLO", "world")
87
88// NOTE: using Apply existing value will be reserved
89gotenv.Apply(strings.NewReader("HELLO=universe"))
90fmt.Println(os.Getenv("HELLO"))
91// Output: "world"
92
93// NOTE: using OverApply existing value will be overridden
94gotenv.OverApply(strings.NewReader("HELLO=universe"))
95fmt.Println(os.Getenv("HELLO"))
96// Output: "universe"
97```
98
99### Throw a Panic
100
101Both `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
104err := gotenv.Load(".env-is-not-exist")
105fmt.Println("error", err)
106// error: open .env-is-not-exist: no such file or directory
107
108gotenv.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
115Just 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
120pairs := gotenv.Parse(strings.NewReader("FOO=test\nBAR=$FOO"))
121// gotenv.Env{"FOO": "test", "BAR": "test"}
122
123err, 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
131The 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.
132