worktree-env-sync

A CLI tool for syncing environment files across git worktrees. It generates .env files by combining a shared template with worktree-specific input variables, and creates symlinks to distribute the env file to multiple locations within each worktree.

Installation

npm install -g worktree-cli

Usage

# Using default config file (worktree-env-sync.json)
worktree-env-sync

# Using a custom config file
worktree-env-sync my-config.json

Config File

The config file is a JSON file with the following structure:

{
  "template": ".env.template",
  "inputFilesToFolders": {
    ".env.worktree1": "../worktree1",
    ".env.worktree2": "../worktree2",
    ".env.worktree3": "../worktree3"
  },
  "outputFile": ".env.local",
  "symlinksToOuputFile": [
    "apps/web/.env.local",
    "apps/docs/.env.local",
    "packages/db/.env.local"
  ]
}

| Field | Description | |-------|-------------| | template | Path to the template env file containing shared variables and interpolation references | | inputFilesToFolders | Map of input env files to their target worktree folders | | outputFile | Output filename for the generated env file (relative to each target folder) | | symlinksToOuputFile | Paths where symlinks to the generated env file should be created (relative to each target folder) |

How It Works

1. Input Files

Create an input env file for each worktree containing worktree-specific variables:

# .env.worktree1
DATABASE_URL=postgres://localhost/worktree1_db
API_KEY=dev-key-123

# .env.worktree2
DATABASE_URL=postgres://localhost/worktree2_db
API_KEY=dev-key-456

2. Template File

Create a template file with shared variables. Use ${VAR_NAME} syntax to reference variables from the input files:

# .env.template
APP_NAME=myapp
APP_URL=http://localhost:3000
DATABASE_CONNECTION=${DATABASE_URL}?pool=5
API_KEY=${API_KEY}

Note: All ${VAR} references in the template must exist in the input files or the tool will fail, since missing variables would result in broken output. If input files contain variables not referenced in the template, a warning will be displayed but processing will continue, since the output is still valid.

3. Generated Output

Running worktree-env-sync generates an env file in each target folder with interpolated values:

# ../worktree1/.env.local
API_KEY="dev-key-123"
APP_NAME="myapp"
APP_URL="http://localhost:3000"
DATABASE_CONNECTION="postgres://localhost/worktree1_db?pool=5"

Note: Output values are quoted and variables are sorted alphabetically.

4. Symlinks

Symlinks are created at each path specified in symlinks, pointing to the generated env file. This allows monorepo packages to share the same env file:

worktree1/
├── .env.local                      # Generated env file
├── apps/
│   ├── web/.env.local              # Symlink → ../../.env.local
│   └── docs/.env.local             # Symlink → ../../.env.local
└── packages/
    └── db/.env.local               # Symlink → ../../.env.local

Validation

The tool validates that:

• All input files have the same set of keys
• Template and input files don't have conflicting keys
• All ${VAR} references in the template exist in the input files (fails if missing)
• Input variables not used in the template trigger a warning (but processing continues)