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.