@dotenvx/dotenvx 2.17.1 → 2.17.3

package/CHANGELOG.md

@@ -2,7 +2,19 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
-[Unreleased](https://github.com/dotenvx/dotenvx/compare/v2.17.1...main)
+[Unreleased](https://github.com/dotenvx/dotenvx/compare/v2.17.3...main)
+
+## [2.17.3](https://github.com/dotenvx/dotenvx/compare/v2.17.2...v2.17.3) (2026-07-23)
+
+### Changed
+
+* Exempt `.env.example` in subdirectories from precommit ([#920](https://github.com/dotenvx/dotenvx/pull/920))
+
+## [2.17.2](https://github.com/dotenvx/dotenvx/compare/v2.17.1...v2.17.2) (2026-07-22)
+
+### Added
+
+* Add support for `DOTENV_CONFIG_IGNORE` global convenience ([#919](https://github.com/dotenvx/dotenvx/pull/919))
 
 ## [2.17.1](https://github.com/dotenvx/dotenvx/compare/v2.17.0...v2.17.1) (2026-07-21)
 

package/README.md

@@ -955,24 +955,6 @@ $ dotenvx encrypt --stdout > .env.encrypted
 > If your organization's compliance department requires [NIST approved curves](https://csrc.nist.gov/projects/elliptic-curve-cryptography) or other curves like `curve25519`, please reach out at [security@dotenvx.com](mailto:security@dotenvx.com).
 
 </details>
-<details><summary>agents</summary><br>
-
-After encryption, `DOTENV_PUBLIC_KEY` lives in your encrypted `.env` file. This means agents and automation can keep running `dotenvx set` and `dotenvx encrypt` without reading `.env.keys`.
-
-```sh
-$ chmod a-r .env.keys
-
-$ dotenvx set HELLO World
-◈ encrypted HELLO (.env)
-
-$ dotenvx encrypt
-◈ encrypted (.env)
-```
-
-Keep `.env.keys` unreadable by agents, while still letting them safely update encrypted values.
-
-</details>
-
 &nbsp;
 
 ## Advanced
@@ -1586,6 +1568,11 @@ $ dotenvx run -f .env.missing --ignore=MISSING_ENV_FILE -- node index.js
 ...
 ```
 
+You can also set `DOTENV_CONFIG_IGNORE="MISSING_ENV_FILE"`. It is parsed as a comma-separated list.
+
+```sh
+$ DOTENV_CONFIG_IGNORE="MISSING_ENV_FILE,OTHER_ERROR_CODE" dotenvx run -f .env.missing -- node index.js
+```
 </details>
 <details><summary>`run --convention=nextjs`</summary><br>
 
@@ -2016,8 +2003,6 @@ $ dotenvx set HELLO World
 set HELLO with encryption (.env)
 ```
 
-Works with unreadable `.env.keys` when `.env` already contains `DOTENV_PUBLIC_KEY`.
-
 </details>
 <details><summary>`set KEY value -f`</summary><br>
 
@@ -2129,8 +2114,6 @@ $ dotenvx encrypt
 ⮕  next run [DOTENV_PRIVATE_KEY='122...0b8' dotenvx run -- yourcommand] to test decryption locally
 ```
 
-Works with unreadable `.env.keys` when `.env` already contains `DOTENV_PUBLIC_KEY`.
-
 </details>
 <details><summary>`encrypt -f`</summary><br>
 
@@ -2596,6 +2579,27 @@ Use `-f` and `-fk` to validate a specific env file and keys file. The command ex
 $ dotenvx validate -f .env.production -fk .env.keys
 ```
 
+</details>
+<details><summary>`validate --ignore`</summary><br>
+
+Ignore specific validation error codes.
+
+```sh
+$ dotenvx validate --ignore=MISSING_ENV_EXAMPLE
+```
+
+Ignore multiple error codes by separating them with spaces.
+
+```sh
+$ dotenvx validate --ignore=MISSING_ENV_FILE MISSING_ENV_EXAMPLE
+```
+
+You can also set `DOTENV_CONFIG_IGNORE`. Its value is a comma-separated list.
+
+```sh
+$ DOTENV_CONFIG_IGNORE=MISSING_ENV_FILE,OTHER dotenvx validate
+```
+
 </details>
 <details><summary>`genexample`</summary><br>
 
@@ -3039,6 +3043,8 @@ X.X.X
 
 </details>
 
+&nbsp;
+
 ### Library 📦
 
 Use dotenvx directly in code.
@@ -3491,6 +3497,29 @@ Set `mask: 0` to fully mask values.
 
 &nbsp;
 
+### Settings ⚙️
+
+There are global settings available that can be configured as environment variables.
+
+<details><summary>Environment variables</summary><br>
+
+```ini
+# dotenvx native settings
+DOTENV_CONFIG_CONVENTION= # set to a default convention like 'nextjs' or 'flow'
+DOTENV_CONFIG_IGNORE= # MISSING_ENV_FILE,OTHER
+DOTENV_CONFIG_QUIET= # set to "true" to default to --quiet
+DOTENVX_NO_ARMOR= # set to "true" to turn off Armor support
+DOTENVX_NO_1PASSWORD= # set to "true" to turn off 1Password support
+DOTENVX_NO_BITWARDEN= # set to "true" to turn off Bitwarden support
+
+# other machine settings respected by dotenvx
+BW_SESSION= # set to bitwarden session token to bypass password prompt
+```
+
+</details>
+
+&nbsp;
+
 ## Armor ⛨
 
 [![dotenvx-armor](https://dotenvx.com/dotenvx-armor-banner.png?v2)](https://dotenvx.com/armor)
@@ -3513,6 +3542,7 @@ Set `mask: 0` to fully mask values.
 * [Claude](https://dotenvx.com/docs/secrets-in-claude)
 * [Codex](https://dotenvx.com/docs/secrets-in-codex)
 * [1Password](https://dotenvx.com/docs/secrets-in-1password)
+* [Bitwarden](https://dotenvx.com/docs/secrets-in-bitwarden)
 * [Node.js](https://dotenvx.com/docs/secrets-in-nodejs)
 * [Next.js](https://dotenvx.com/docs/secrets-in-nextjs)
 * [Express](https://dotenvx.com/docs/secrets-in-express)

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.17.1",
+  "version": "2.17.3",
   "name": "@dotenvx/dotenvx",
   "description": "a secure dotenv–from the creator of `dotenv`",
   "author": "@motdotla",

package/src/cli/actions/get.js

@@ -6,13 +6,14 @@ const createSpinner = require('../../lib/helpers/createSpinner')
 const Session = require('../../db/session')
 const getResolver = require('./../../lib/resolvers/get')
 const normalizeDotenvConfigConvention = require('../../lib/helpers/normalizeDotenvConfigConvention')
+const normalizeDotenvConfigIgnore = require('../../lib/helpers/normalizeDotenvConfigIgnore')
 const buildCommandEnvs = require('../../lib/helpers/buildCommandEnvs')
 const resolveEnvKeysFile = require('../../lib/helpers/resolveEnvKeysFile')
 const mask = require('../../lib/helpers/mask')
 const filterKeys = require('../../lib/helpers/filterKeys')
 
 async function get (key) {
-  const options = normalizeDotenvConfigConvention(this.opts())
+  const options = normalizeDotenvConfigIgnore(normalizeDotenvConfigConvention(this.opts()))
   const spinnerOptions = typeof this.optsWithGlobals === 'function' ? this.optsWithGlobals() : options
   const spinner = await createSpinner({ ...spinnerOptions, ...options, text: 'decrypting' })
 

package/src/cli/actions/run.js

@@ -8,6 +8,7 @@ const createSpinner = require('../../lib/helpers/createSpinner')
 const Session = require('../../db/session')
 const normalizeDotenvConfigQuiet = require('../../lib/helpers/normalizeDotenvConfigQuiet')
 const normalizeDotenvConfigConvention = require('../../lib/helpers/normalizeDotenvConfigConvention')
+const normalizeDotenvConfigIgnore = require('../../lib/helpers/normalizeDotenvConfigIgnore')
 const buildCommandEnvs = require('../../lib/helpers/buildCommandEnvs')
 const resolveEnvKeysFile = require('../../lib/helpers/resolveEnvKeysFile')
 const mask = require('../../lib/helpers/mask')
@@ -53,7 +54,7 @@ function uniqueInjectedKeys (processedEnvs) {
 }
 
 async function run () {
-  const options = normalizeDotenvConfigConvention(normalizeDotenvConfigQuiet(this.opts()))
+  const options = normalizeDotenvConfigIgnore(normalizeDotenvConfigConvention(normalizeDotenvConfigQuiet(this.opts())))
   const spinnerOptions = typeof this.optsWithGlobals === 'function' ? this.optsWithGlobals() : options
   const maskEnabled = options.mask !== undefined
   const redactEnabled = options.redact === true

package/src/cli/actions/validate.js

@@ -6,6 +6,7 @@ const createSpinner = require('../../lib/helpers/createSpinner')
 const Session = require('../../db/session')
 const normalizeDotenvConfigQuiet = require('../../lib/helpers/normalizeDotenvConfigQuiet')
 const normalizeDotenvConfigConvention = require('../../lib/helpers/normalizeDotenvConfigConvention')
+const normalizeDotenvConfigIgnore = require('../../lib/helpers/normalizeDotenvConfigIgnore')
 const buildCommandEnvs = require('../../lib/helpers/buildCommandEnvs')
 const resolveEnvKeysFile = require('../../lib/helpers/resolveEnvKeysFile')
 const validateEnvExample = require('../../lib/helpers/validateEnvExample')
@@ -13,7 +14,7 @@ const validateEnvExample = require('../../lib/helpers/validateEnvExample')
 const { determine } = require('./../../lib/helpers/envResolution')
 
 async function validate () {
-  const options = normalizeDotenvConfigConvention(normalizeDotenvConfigQuiet(this.opts()))
+  const options = normalizeDotenvConfigIgnore(normalizeDotenvConfigConvention(normalizeDotenvConfigQuiet(this.opts())))
   const spinnerOptions = typeof this.optsWithGlobals === 'function' ? this.optsWithGlobals() : options
   const spinner = await createSpinner({ ...spinnerOptions, ...options, text: 'validating' })
   const ignore = options.ignore || []

package/src/lib/helpers/normalizeDotenvConfigConvention.js

@@ -1,4 +1,6 @@
-function normalizeDotenvConfigConvention (options) {
+function normalizeDotenvConfigConvention (
+  /** @type {import('../main').DotenvConfigOptions} */ options
+) {
   if (!options.convention && process.env.DOTENV_CONFIG_CONVENTION) {
     options.convention = process.env.DOTENV_CONFIG_CONVENTION
   }

package/src/lib/helpers/normalizeDotenvConfigIgnore.js

@@ -0,0 +1,17 @@
+function normalizeDotenvConfigIgnore (
+  /** @type {import('../main').DotenvConfigOptions} */ options
+) {
+  const configIgnore = (process.env.DOTENV_CONFIG_IGNORE || '')
+    .split(',')
+    .map(code => code.trim())
+    .filter(Boolean)
+
+  if (configIgnore.length < 1) return options
+
+  return {
+    ...options,
+    ignore: [...(options.ignore || []), ...configIgnore]
+  }
+}
+
+module.exports = normalizeDotenvConfigIgnore

package/src/lib/helpers/normalizeDotenvConfigQuiet.js

@@ -1,4 +1,6 @@
-function normalizeDotenvConfigQuiet (options) {
+function normalizeDotenvConfigQuiet (
+  /** @type {import('../main').DotenvConfigOptions} */ options
+) {
   if (process.env.DOTENV_CONFIG_QUIET === 'true') {
     options.quiet = true
   }

package/src/lib/main.js

@@ -26,6 +26,7 @@ const decryptKeyValue = require('./helpers/cryptography/decryptKeyValue')
 const Errors = require('./helpers/errors')
 const normalizeDotenvConfigQuiet = require('./helpers/normalizeDotenvConfigQuiet')
 const normalizeDotenvConfigConvention = require('./helpers/normalizeDotenvConfigConvention')
+const normalizeDotenvConfigIgnore = require('./helpers/normalizeDotenvConfigIgnore')
 const mask = require('./helpers/mask')
 const maskProcessedEnvs = require('./helpers/maskProcessedEnvs')
 
@@ -43,6 +44,7 @@ function uniqueInjectedKeys (processedEnvs) {
 const config = function (options = {}) {
   options = normalizeDotenvConfigQuiet(options)
   options = normalizeDotenvConfigConvention(options)
+  options = normalizeDotenvConfigIgnore(options)
 
   // allow user to set processEnv to write to
   let processEnv = process.env
@@ -318,6 +320,7 @@ const set = async function (key, value, options = {}) {
 /* @type {import('./main').get} */
 const get = async function (key, options = {}) {
   options = normalizeDotenvConfigConvention(options)
+  options = normalizeDotenvConfigIgnore(options)
 
   const envs = buildEnvs(options)
   const noArmor = resolveNoArmor(options)

package/src/lib/resolvers/envs.js

@@ -301,6 +301,8 @@ async function envs (options = {}) {
   const readableFilepaths = new Set()
   const processEnv = options.processEnv || process.env
   const envKeysFilepath = options.envKeysFilepath || options.envKeysFile || null
+  const no1Password = options.no1Password === true || process.env.DOTENVX_NO_1PASSWORD === 'true'
+  const noBitwarden = options.noBitwarden === true || process.env.DOTENVX_NO_BITWARDEN === 'true'
   const provider = await providers(options)
   const decryptor = await decryptors(options)
   for (const env of options.envs || []) {
@@ -313,8 +315,8 @@ async function envs (options = {}) {
         provider,
         decryptor,
         readableFilepaths,
-        no1Password: options.no1Password,
-        noBitwarden: options.noBitwarden,
+        no1Password,
+        noBitwarden,
         onStatus: options.onStatus
       }))
     } else if (env.type === TYPE_ENV) {
@@ -325,8 +327,8 @@ async function envs (options = {}) {
         envKeysFilepath,
         provider,
         decryptor,
-        no1Password: options.no1Password,
-        noBitwarden: options.noBitwarden,
+        no1Password,
+        noBitwarden,
         onStatus: options.onStatus
       }))
     }
@@ -343,6 +345,8 @@ function envsSync (options = {}) {
   const readableFilepaths = new Set()
   const processEnv = options.processEnv || process.env
   const envKeysFilepath = options.envKeysFilepath || options.envKeysFile || null
+  const no1Password = options.no1Password === true || process.env.DOTENVX_NO_1PASSWORD === 'true'
+  const noBitwarden = options.noBitwarden === true || process.env.DOTENVX_NO_BITWARDEN === 'true'
   const provider = providers.sync(options)
   const decryptor = decryptors.sync(options)
 
@@ -356,8 +360,8 @@ function envsSync (options = {}) {
         provider,
         decryptor,
         readableFilepaths,
-        no1Password: options.no1Password,
-        noBitwarden: options.noBitwarden
+        no1Password,
+        noBitwarden
       }))
     } else if (env.type === TYPE_ENV) {
       processedEnvs.push(injectEnvSync({
@@ -367,8 +371,8 @@ function envsSync (options = {}) {
         envKeysFilepath,
         provider,
         decryptor,
-        no1Password: options.no1Password,
-        noBitwarden: options.noBitwarden
+        no1Password,
+        noBitwarden
       }))
     }
   }

package/src/lib/services/precommit.js

@@ -54,12 +54,13 @@ class Precommit {
         count += 1
 
         const file = path.join(this.directory, _file) // to handle when directory argument passed
+        const filename = path.basename(file) // exemptions match on filename, so they apply at any depth
 
         // check if file is going to be committed
         if (this._isFileToBeCommitted(file)) {
           // check if that file is being ignored
           if (ig.ignores(file)) {
-            if (file === '.env.example' || file === '.env.x') {
+            if (filename === '.env.example' || filename === '.env.x') {
               const warning = new Errors({
                 message: `${file} ignored (should not be)`,
                 help: `fix: [dotenvx gitignore --pattern !${file}]`
@@ -67,7 +68,7 @@ class Precommit {
               warnings.push(warning)
             }
           } else {
-            if (file !== '.env.example' && file !== '.env.x') {
+            if (filename !== '.env.example' && filename !== '.env.x') {
               const src = fsx.readFileXSync(file)
               const encrypted = sealed(src)