godotenv

godotenv is a small, dependency-free Go library that ports Ruby’s dotenv to the Go ecosystem, reading key-value pairs from a .env file and loading them into the process environment so twelve-factor apps can keep configuration and secrets out of source control. It exposes both a mutating API (Load, Overload) for wiring env vars into os.Getenv and a pure API (Read, Parse, Unmarshal) for callers who want a plain map[string]string instead, plus Write/Marshal for serializing a map back to .env format.

Beyond the library, the module ships an autoload subpackage for zero-code side-effect loading and a standalone godotenv CLI (cmd/godotenv) that runs another command with an env file preloaded. The parser supports comments, quoted values, variable expansion (${VAR}), export prefixes, and YAML-style key: value syntax, and the project has explicitly declared itself feature-complete, focusing further contributions on compatibility fixes and bug fixes rather than new functionality.

What You Get

• A one-line godotenv.Load() call that reads .env from the working directory into os.Getenv
• Non-destructive Load/Read and destructive Overload variants for controlling whether existing env vars are preserved or replaced
• Pure functions (Parse, Unmarshal, UnmarshalBytes) that return a map[string]string instead of mutating global state, for callers who want isolation
• Write/Marshal helpers to serialize a map[string]string back into a correctly quoted and escaped .env file
• An autoload subpackage for import-only side-effect loading (import _ "github.com/joho/godotenv/autoload")
• A standalone godotenv CLI binary that runs an arbitrary command with env vars preloaded from one or more files

Common Use Cases

• Loading local development secrets (API keys, DB URLs) from a .env file that’s excluded from version control
• Bootstrapping environment-specific configuration by chaining .env, .env.{ENV}, and .env.local loads in a defined precedence order
• Running a process with an injected environment via the CLI without modifying shell profile or CI job configuration
• Reading env vars into an isolated map (via Read/Parse) for testing or for merging with other config sources instead of mutating the real process environment

Under The Hood

Architecture

The module is a flat, single-purpose Go package: godotenv.go exposes the public API (Load, Overload, Read, Parse, Unmarshal, Write, Exec), while parser.go isolates the actual parsing logic (parseBytes, getStatementStart, locateKeyName, extractVarValue) behind that surface. There’s no dependency injection or interface abstraction — it’s straightforward procedural Go built around a byte-slice “cutset” technique, where each parse step consumes a prefix of the remaining bytes and returns what’s left, avoiding per-line allocations. Two satellite packages extend the core without touching it: autoload wraps Load() in an init() for side-effect-only imports, and cmd/godotenv is a thin CLI wrapping Exec(). Because every public entry point (Parse, Unmarshal, UnmarshalBytes, file loading) ultimately funnels through parseBytes, that function is the single point where a change would ripple across the entire public API.

Tech Stack

Zero third-party runtime dependencies — the entire library is built on the Go standard library (bytes, os, os/exec, regexp, sort, strings, unicode, errors), targeting go 1.13 per go.mod. The CLI uses the stdlib flag package rather than a third-party CLI framework. Tooling is plain go build/go install; CI runs standard go test/vet plus a CodeQL security scan, and Dependabot keeps GitHub Actions versions current. Distribution is purely as an importable module (and an installable CLI via go install), with no runtime services or external integrations.

Code Quality

The test file is substantially larger than the combined source it covers, and is driven by dedicated fixture .env files exercising comments, quoting, exports, variable substitution, hyphenated keys, and deliberately invalid syntax. Parse failures return typed sentinel errors (ErrZeroLengthString, ErrUnexpectedChar, ErrUnterminatedQuote) wrapped with fmt.Errorf("%w ...") rather than being swallowed or panicking. Naming follows idiomatic Go conventions throughout (exported PascalCase API, unexported camelCase internals), and CI plus CodeQL static analysis run on every change. No dedicated linter config file was found, but the codebase is small enough that this has limited practical impact.

API Design The public surface favors minimal boilerplate: godotenv.Load() with no arguments loads .env from the current directory in one line, matching the ergonomics of Ruby’s and Node’s dotenv equivalents. Verb naming is consistent and orthogonal rather than one overloaded function with flags — Load/Overload mutate process env, Read/Parse/Unmarshal/UnmarshalBytes return a plain map without side effects, and Write/Marshal invert the process for serialization. Every exported symbol carries a godoc comment with a runnable usage snippet, and the autoload subpackage reduces the common case to a single blank import with zero application code required.