env-patch 1.1.0

Environment file generator with template + override support. Born from MochatAI team's production experience.

env-patch

Environment file generator with template + override support.

Born from MochatAI team's production experience building cross-border e-commerce and Amazonn Ads Agent.

English | 中文

Why env-patch?

Most dotenv libraries load .env files at runtime. But generating .env files can be frustrating:

• Building Docker images that need baked-in environment configs, but your project only has .env.example, not .env?
• Already have .env.example and .env.{env}, but that's not enough? Those files are committed to git, but you need to temporarily change configs for debugging without committing
• Parallel development with worktrees? Each worktree needs its own independent configuration

env-patch generates a single .env file at build time by merging .env.example (template), .env.development (environment config), and .env.development.local (local overrides).

Installation

Global CLI (recommended for most users):

# Using pipx
pipx install env-patch

# Using uv tool (if you use uv)
uv tool install env-patch

As a project dependency:

# Using pip
pip install env-patch

# Using uv
uv add env-patch

Quick Start

# 1. Create your template
cat > .env.example << 'EOF'
DATABASE_URL=postgres://localhost/myapp
REDIS_URL=redis://localhost:6379
DEBUG=false
EOF

# 2. Create environment-specific config
cat > .env.development << 'EOF'
DEBUG=true
EOF

# 3. Generate .env
env-patch -e development

# Result: .env contains DATABASE_URL, REDIS_URL from template + DEBUG=true from override

File Hierarchy

.env.example              # Template (git tracked)
.env.development          # Development config (git tracked)
.env.development.local    # Local overrides (git ignored)
.env                      # Output (git ignored)

Priority (highest to lowest):

1. .env.{env}.local - Personal machine-specific overrides
2. .env.{env} - Environment-specific config
3. .env.example - Default template values

Usage

Basic Usage

# Auto-detect env file (when only one exists)
env-patch

# Specify environment
env-patch -e development
env-patch -e production
env-patch -e staging

Aliases

Built-in aliases for common environments:

env-patch -e dev    # Same as: env-patch -e development
env-patch -e prod   # Same as: env-patch -e production
env-patch -e stage  # Same as: env-patch -e staging

Custom Environments

# Use any environment name
env-patch -e uai-prod       # Uses .env.uai-prod
env-patch -e feature-auth   # Uses .env.feature-auth

Options

env-patch -e <env>           # Environment name
env-patch -t <file>          # Template file (default: .env.example)
env-patch -o <file>          # Output file (default: .env)
env-patch -s                 # Strict mode: error on unknown keys
env-patch -h                 # Show help
env-patch -v                 # Show version

Local Overrides

Create .env.{env}.local for machine-specific settings that shouldn't be committed:

# .env.development.local (git ignored)
DATABASE_URL=postgres://localhost:5433/myapp_local
API_KEY=my-personal-api-key

These values override both the template and the environment config.

Recommended .gitignore

# Output file
.env

# Local overrides
.env.local
.env.*.local

# Keep these tracked
!.env.example

CI/CD Integration

# GitHub Actions example
steps:
  - name: Generate .env for production
    run: |
      pip install env-patch
      env-patch -e production

# Dockerfile example
FROM python:3.12
RUN pip install env-patch
COPY .env.example .env.production ./
RUN env-patch -e production

Why Not Just Use dotenv-flow?

Feature	env-patch	dotenv-flow
When it runs	Build time	Runtime
Output	Single .env file	In-memory only
Docker builds	Easy	Requires workaround
Debug visibility	Check .env directly	Add logging
Language	Python CLI	Node.js library

Use env-patch when you need a generated file. Use dotenv-flow when you want runtime loading.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE for details.

---

中文文档

env-patch： .env 文件生成器，支持模板 + 覆盖机制。

源自 MochatAI 团队在跨境电商AI(特别是亚马逊AI广告经理)开发中的实战经验。

为什么需要 env-patch？

大多数编程语言的 dotenv 库在 运行时 会加载 .env 文件。但 .env 文件的生成就搞得人很烦，比如：

• 在构建 Docker 镜像 时需要内置环境配置，但项目里只有 .env.example，没有 .env 文件？
• 有了 .env.example 和 .env.{env}(比如.env.development)，结果还不够，因为团那些文件也都是提交到 git 仓库的，所以一旦频繁修改就以为需要提交git或反复注意有没有不小心提交到git，但我们在调试时希望临时改变一下配置，但不希望提交到 git仓库
• 在 worktree 并行开发时，希望每个 worktree 都有自己独立的配置

env-patch 在 构建时 就可以将 .env.example、.env.development（环境配置）、.env.development.local（环境配置的本地覆盖）合并生成单一 .env 文件。

安装

全局 CLI（推荐大多数用户使用）：

# 使用 pipx
pipx install env-patch

# 使用 uv tool（如果你使用 uv）
uv tool install env-patch

作为项目依赖：

# 使用 pip
pip install env-patch

# 使用 uv
uv add env-patch

快速开始

# 1. 创建模板
cat > .env.example << 'EOF'
DATABASE_URL=postgres://localhost/myapp
REDIS_URL=redis://localhost:6379
DEBUG=false
EOF

# 2. 创建环境配置
cat > .env.development << 'EOF'
DEBUG=true
EOF

# 3. 生成 .env
env-patch -e development

# 结果：.env 包含模板的 DATABASE_URL、REDIS_URL + 覆盖的 DEBUG=true

文件层级

.env.example              # 模板（git 追踪）
.env.development          # 开发环境配置（git 追踪）
.env.development.local    # 本地覆盖（git 忽略）
.env                      # 输出文件（git 忽略）

优先级（从高到低）：

1. .env.{env}.local - 个人机器特定的覆盖
2. .env.{env} - 环境配置
3. .env.example - 模板默认值

使用方法

基本用法

# 自动检测环境文件（当只有一个时）
env-patch

# 指定环境
env-patch -e development
env-patch -e production
env-patch -e staging

别名

内置常用环境别名：

env-patch -e dev    # 等同于: env-patch -e development
env-patch -e prod   # 等同于: env-patch -e production
env-patch -e stage  # 等同于: env-patch -e staging

自定义环境

# 使用任意环境名
env-patch -e uai-prod       # 使用 .env.uai-prod
env-patch -e feature-auth   # 使用 .env.feature-auth

选项

env-patch -e <env>           # 环境名称
env-patch -t <file>          # 模板文件（默认: .env.example）
env-patch -o <file>          # 输出文件（默认: .env）
env-patch -s                 # 严格模式：未知键报错
env-patch -h                 # 显示帮助
env-patch -v                 # 显示版本

本地覆盖

创建 .env.{env}.local 存放不应提交的机器特定配置：

# .env.development.local（git 忽略）
DATABASE_URL=postgres://localhost:5433/myapp_local
API_KEY=my-personal-api-key

这些值会覆盖模板和环境配置。

推荐的 .gitignore

# 输出文件
.env

# 本地覆盖
.env.local
.env.*.local

# 保留这些追踪
!.env.example

CI/CD 集成

# GitHub Actions 示例
steps:
  - name: 生成生产环境 .env
    run: |
      pip install env-patch
      env-patch -e production

# Dockerfile 示例
FROM python:3.12
RUN pip install env-patch
COPY .env.example .env.production ./
RUN env-patch -e production

贡献

欢迎贡献！提交 Pull Request 为开源做贡献。

许可证

MIT License - 详见 LICENSE

---

Made with love by MochatAI Team