envdrift hook¶

Manage pre-commit hook integration.

Synopsis¶

envdrift hook [OPTIONS]

Description¶

The hook command helps integrate envdrift with pre-commit. It can:

Show configuration - Display the pre-commit config snippet
Install hooks - Automatically add hooks to your project

Pre-commit hooks ensure that:

Schema validation runs before every commit
Unencrypted secrets are blocked from being committed
Environment drift is caught early

Options¶

`--config`¶

Show the pre-commit configuration snippet to copy into your .pre-commit-config.yaml.

envdrift hook --config

`--install`, `-i`¶

Automatically install the hooks into your .pre-commit-config.yaml.

envdrift hook --install

Requires pyyaml to be installed.

Examples¶

View Configuration¶

envdrift hook

Output:

# Add to .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: envdrift-validate
        name: Validate env files
        entry: envdrift validate --ci
        language: system
        files: ^\.env\.(production|staging|development)$
        pass_filenames: true

      - id: envdrift-encryption
        name: Check env encryption
        entry: envdrift encrypt --check
        language: system
        files: ^\.env\.(production|staging)$
        pass_filenames: true

Show Config Snippet Only¶

envdrift hook --config

Install Hooks¶

envdrift hook --install

This modifies your .pre-commit-config.yaml directly.

Manual Setup¶

If you prefer manual setup:

Create .pre-commit-config.yaml:

repos:
  - repo: local
    hooks:
      - id: envdrift-validate
        name: Validate env schema
        entry: envdrift validate --ci --schema config.settings:Settings
        language: system
        files: ^\.env\.(production|staging|development)$
        pass_filenames: true

Install pre-commit:

pip install pre-commit
pre-commit install

Test the hook:

pre-commit run envdrift-validate --all-files

Hook Configuration¶

Validation Hook¶

- id: envdrift-validate
  name: Validate env schema
  entry: envdrift validate --ci --schema config.settings:Settings
  language: system
  files: ^\.env\.(production|staging|development)$
  pass_filenames: true

Option	Description
`entry`	Command to run (customize schema path)
`files`	Regex matching .env files to validate
`pass_filenames`	Pass matched files as arguments

Encryption Hook¶

- id: envdrift-encryption
  name: Check env encryption
  entry: envdrift encrypt --check
  language: system
  files: ^\.env\.(production|staging)$
  pass_filenames: true

This blocks commits with unencrypted secrets in production/staging files.

Customization¶

Different Schemas per Environment¶

repos:
  - repo: local
    hooks:
      - id: envdrift-validate-prod
        name: Validate production env
        entry: envdrift validate --ci --schema config.settings:ProductionSettings
        language: system
        files: ^\.env\.production$
        pass_filenames: true

      - id: envdrift-validate-dev
        name: Validate development env
        entry: envdrift validate --ci --schema config.settings:DevelopmentSettings
        language: system
        files: ^\.env\.development$
        pass_filenames: true

Skip Encryption Check for Development¶

- id: envdrift-encryption
  name: Check env encryption
  entry: envdrift encrypt --check
  language: system
  files: ^\.env\.(production|staging)$  # Excludes development
  pass_filenames: true

Add Service Directory¶

- id: envdrift-validate
  name: Validate env schema
  entry: envdrift validate --ci --schema config.settings:Settings --service-dir ./backend
  language: system
  files: ^\.env\..*$
  pass_filenames: true

Workflow¶

Developer Experience¶

Developer adds a new required field to the schema
Developer tries to commit without updating .env
Pre-commit hook runs envdrift validate
Commit is blocked with clear error message
Developer adds the missing variable
Commit succeeds

Example Blocked Commit¶

$ git commit -m "Add new feature"
Validate env schema.....................................................Failed
- hook id: envdrift-validate
- exit code: 1

Validation FAILED for .env.production

MISSING REQUIRED VARIABLES:
  * NEW_API_KEY - API key for external service

Summary: 1 error(s), 0 warning(s)

Troubleshooting¶

Hook Not Running¶

Ensure pre-commit is installed:

pre-commit install

Schema Import Errors¶

Add --service-dir to point to your project root:

entry: envdrift validate --ci --schema config.settings:Settings --service-dir .

Skip Hook Temporarily¶

git commit --no-verify -m "WIP"

Use sparingly!