How joho/godotenv works
Purpose and Delivery Forms
GoDotEnv is a Go library and command-line tool for parsing dotenv-format configuration and applying it to process environment variables. It supports file, reader, and string inputs; preserves existing variables by default; and can serialize environment maps back to dotenv format. Core library API: godotenv.go; module definition: go.mod.
Entry Points
Library consumers call load/read/parse/marshal APIs in godotenv.go. The import-side-effect variant initializes default .env loading through autoload/autoload.go. The executable entry point is cmd/godotenv/cmd.go, built as the godotenv command under cmd/godotenv.
Parse and Representation Stage
The parser converts dotenv text into map[string]string, handling assignments, comments, export, quoted values, YAML-like separators, supported key characters, and variable substitution. Parsing logic is concentrated in parser.go; representative compatibility inputs are in fixtures/comments.env, fixtures/substitutions.env, and fixtures/hyphen.env.
Environment Application Semantics
Load-oriented APIs read one or more files, parse each into a map, then apply values through the Go process environment. Normal loading does not replace already-defined process variables; overload mode explicitly permits replacement. This is the key boundary between untrusted/configuration-file content and global process state. Implementation API and mutation behavior reside in godotenv.go.
Input and Output Boundaries
The library accepts local filesystem paths, generic io.Reader streams, and strings, allowing callers to source configuration outside the filesystem without coupling parsing to transport. Conversely, write/marshal APIs encode maps into escaped dotenv syntax for files or strings. Parsing internals remain separated in parser.go, while file/stream orchestration and serialization are in godotenv.go.
CLI Execution Flow
The CLI accepts a dotenv file path (defaulting to .env) and an override flag, loads configuration using the library, then runs a supplied command with the resulting environment. Thus it is a thin process-launching adapter rather than a separate parser implementation. Its command wiring is in cmd/godotenv/cmd.go; shared semantics come from godotenv.go.
Runtime and Automation
The project is a Go module intended for Go 1.24+ tool installation. It relies primarily on the Go standard library and OS filesystem/environment/process facilities, with no application server, database, or network service dependency. GitHub Actions provides CI, CodeQL analysis, and release automation in .github/workflows/ci.yml, .github/workflows/codeql-analysis.yml, and .github/workflows/release.yml.
Components 16
Go library
Public dotenv parsing, loading, and serialization APIs.
- Go module · Go 1.24+ module with standard-library runtime dependencies.
go.mod - Load, read, parse APIs · Accepts file paths, readers, and strings.
godotenv.go - File and stream I/O · Coordinates filesystem reads and dotenv writes.
godotenv.go - Dotenv parser · Converts dotenv text into map[string]string.
parser.go - Environment map
- Process environment · Normal loads preserve existing variables; overload replaces them.
godotenv.go - Marshal and write · Escapes environment maps as dotenv syntax.
godotenv.go - Import-side-effect loader · Loads the default .env during package initialization.
autoload/autoload.go
Command-line tool
Thin adapter that loads dotenv files before launching a command.
- godotenv command · Accepts dotenv path and override flag.
cmd/godotenv/cmd.go - Supplied command · Runs with the resulting environment.
Automation
Repository quality and release workflows.
- CI workflow
.github/workflows/ci.yml - CodeQL analysis
.github/workflows/codeql-analysis.yml - Release workflow
.github/workflows/release.yml
Other components
- Local dotenv files
- Reader and string inputs
- Compatibility fixtures · Cover comments, substitutions, and hyphenated keys.
fixtures/comments.env
Connections 17
- Go module → Load, read, parse APIs: defines library
- Load, read, parse APIs → File and stream I/O: loads and reads
- Local dotenv files → File and stream I/O: file paths
- Reader and string inputs → Load, read, parse APIs: reader/string APIs
- File and stream I/O → Dotenv parser: dotenv text
- Load, read, parse APIs → Dotenv parser: parse APIs
- Dotenv parser → Environment map: produces
- Environment map → Process environment: load or overload
- Environment map → Marshal and write: marshal/write
- Marshal and write → Local dotenv files: writes dotenv
- Import-side-effect loader → Load, read, parse APIs: initializes default load
- godotenv command → Load, read, parse APIs: uses load semantics
- godotenv command → Supplied command: launches with environment
- Compatibility fixtures → Dotenv parser: compatibility cases
- CI workflow → Go module: builds and verifies
- CodeQL analysis → Go module: analyzes
- Release workflow → Go module: releases