if ci_badges.map(&:color).detect { it != "green"} ☝️ let me know, as I may have missed the discord notification.

if ci_badges.map(&:color).all? { it == "green"} 👇️ send money so I can do more of this. FLOSS maintenance is now my full-time job.

Dotenv::Merge intelligently merges two versions of a dotenv (.env) file. It is built on ast-merge and tree_haver, and keeps dotenv-specific ownership rules separate from the parser/backend substrate.

• Dotenv-Aware: Understands dotenv file format (KEY=value, comments, exports)
• Intelligent: Matches environment variables by key name
• Comment-Preserving: Comments and blank lines are preserved in their context
• Freeze Block Support: Respects freeze markers (default: dotenv-merge:freeze / dotenv-merge:unfreeze) for merge control - customizable to match your project's conventions
• Full Provenance: Tracks origin of every line
• StructuredMerge Native: Depends on ast-merge and tree_haver, matching the rest of the Ruby merge family
• Customizable:
  • signature_generator - callable custom signature generators
  • preference - setting of :template, :destination, or a Hash for per-node-type preferences
  • node_splitter - Hash mapping node types to callables for per-node-type merge customization (see ast-merge docs)
  • add_template_only_nodes - setting to retain variables that do not exist in destination
  • freeze_token - customize freeze block markers (default: "dotenv-merge")

require "dotenv/merge"

template = File.read("template.env")
destination = File.read("destination.env")

merger = Dotenv::Merge::SmartMerger.new(template, destination)
result = merger.merge

File.write("merged.env", result.to_s)

Tokens to Remember
Works with MRI Ruby 4
Support & Community
Source
Documentation
Compliance
Style
Maintainer 🎖️
... 💖	🧊 🐙 🛖 🧪

Compatible with MRI Ruby 4.0.0+, and concordant releases of JRuby, and TruffleRuby. CI workflows and Appraisals are generated for MRI Ruby 4.0.0+. This test floor is configured by ruby.test_minimum in .kettle-jem.yml and may be higher than the gem's runtime compatibility floor when legacy Rubies are not practical for the current toolchain.

The amazing test matrix is powered by the kettle-dev stack.

How kettle-dev manages complexity in tests

Gem	Source	Role	Daily download rank
appraisal2	GitHub	multi-dependency Appraisal matrix generation
appraisal2-rubocop	GitHub	RuboCop Appraisal generator integration
kettle-dev	GitHub	development, release, and CI workflow tooling
kettle-jem	GitHub	Appraisals & CI workflow templates
kettle-soup-cover	GitHub	SimpleCov coverage policy and reporting
kettle-test	GitHub	standard test runner and coverage harness
rubocop-lts	GitHub	Ruby-version-aware linting
turbo_tests2	GitHub	parallel test execution

Install the gem and add to the application's Gemfile by executing:

bundle add dotenv-merge

If bundler is not being used to manage dependencies, install the gem by executing:

gem install dotenv-merge

merger = Dotenv::Merge::SmartMerger.new(
  template,
  destination,
  # When conflicts occur, prefer template or destination values
  preference: :template,            # or :destination (default)
  # Add entries that only exist in template
  add_template_only_nodes: true,    # default: false
)

Control which source wins when both files have the same key:

• :template - Template values replace destination values

  • Version files (VERSION=2.0.0 should replace VERSION=1.0.0)
  • API endpoint updates (API_URL=https://new-api.example.com)

• :destination (default) - Destination values are preserved

  • Local development settings
  • Project-specific customizations

Control whether to add entries that only exist in the template:

• true - Add new entries from template

  • New required environment variables
  • New configuration options

• false (default) - Skip template-only entries

  • Template has placeholder values
  • Destination is authoritative

require "dotenv/merge"

template = File.read("template.env")
destination = File.read("destination.env")

merger = Dotenv::Merge::SmartMerger.new(template, destination)
result = merger.merge

File.write("merged.env", result)

Freeze blocks protect sections of your .env file from being modified during merges:

# << FREEZE: project_secrets
DATABASE_URL=postgresql://localhost/myapp_dev
SECRET_KEY_BASE=my_local_secret_key_value
# >> FREEZE: project_secrets

# These entries can be updated by template
API_VERSION=v2

# Template introduces a new required variable
template = <<~ENV
  DATABASE_URL=postgresql://localhost/template_db
  NEW_FEATURE_FLAG=enabled
ENV

destination = <<~ENV
  DATABASE_URL=postgresql://localhost/myapp_dev
ENV

merger = Dotenv::Merge::SmartMerger.new(
  template,
  destination,
  add_template_only_nodes: true,
)
result = merger.merge
# Result includes DATABASE_URL from destination + NEW_FEATURE_FLAG from template

See SECURITY.md.

If you need some ideas of where to help, you could work on adding more code coverage, or if it is already 💯 (see below) check issues or PRs, or use the gem and think about how it could be better.

We so if you make changes, remember to update it.

See CONTRIBUTING.md for more detailed instructions.

This library follows for its public API where practical. For most applications, prefer the Pessimistic Version Constraint with two digits of precision.

For example:

spec.add_dependency("dotenv-merge", "~> 7.0")

See CHANGELOG.md for a list of releases.

The gem is available under the following licenses: AGPL-3.0-only, PolyForm-Small-Business-1.0.0. See LICENSE.md for details.

If none of the available licenses suit your use case, please contact us to discuss a custom commercial license.