envsync

Sync .env files between your local project and a Samba-mounted directory.

envsync helps keep environment files in sync across machines by comparing file hashes and tracking the last known synced state.

What This App Does

• Scans your project for .env files.
• Syncs them to a Samba location under a per-project folder.
• Detects local and remote changes using SHA-256 hashes.
• Resolves conflicts with a predictable rule: local version is kept.
• Tracks previous sync state in .envsync-state.json.

How It Works

At sync time, the app compares three values for each .env file path:

• local hash
• samba hash
• last known hash from .envsync-state.json

From this, it decides whether to:

• upload local to Samba
• download Samba to local
• delete from one side if removed on the other
• keep local when both changed differently (conflict)

Requirements

• Node.js (recommended: current LTS)
• A Samba share already mounted/accessible as a normal filesystem path
• Read/write permissions to that Samba path

Install

pnpm install
pnpm build

For development mode:

pnpm dev

CLI Commands

After building, use:

envsync <command>

Available commands:

• init - create .envsync.json in current directory
• smb - check if configured Samba path is reachable/readable/writable
• status - show repo status, config path, Samba status, and discovered .env files
• sync - perform two-way synchronization with conflict handling

If no command is provided, the CLI prints the command list.

Configuration

The config file is .envsync.json in your project root.

Basic config

{
  "sambaDir": "Z:/shared/envs"
}

Per-platform config

{
  "sambaDir": {
    "win32": "Z:/shared/envs",
    "linux": "/mnt/samba/envs",
    "darwin": "/Volumes/samba/envs"
  }
}

Notes:

• sambaDir can be either a string or an object keyed by platform.
• Supported platform keys come from Node.js process.platform values (for example: win32, linux, darwin).
• Missing config or invalid platform mapping will stop the app with an error.

Quick Start

1. Run envsync init in your project.
2. Edit .envsync.json and set a real sambaDir (the default value is only a placeholder).
3. Run envsync smb to verify Samba access.
4. Run envsync status to confirm .env files are discovered.
5. Run envsync sync to synchronize files.

Sync Behavior Details

• Samba files are stored in: <sambaDir>/<projectFolderName>/...
• The project folder name is your current directory name.
• State file is written locally as .envsync-state.json.

Decision summary:

• Local changed only -> upload to Samba
• Samba changed only -> download to local
• Local removed -> remove from Samba
• Samba removed -> remove local
• Both changed and different -> keep local and upload local

Typical Workflow

Machine A:

envsync sync

Machine B (same project name, same Samba root):

envsync sync

Changes made on one machine become available to others after sync.

Troubleshooting

• Config file not found:
  • Run envsync init in the project root.
• Cannot access Samba directory or Samba: NOT reachable:
  • Verify the network share is mounted and the path in .envsync.json is correct.
  • Verify user permissions.
• Suspicious sambaDir value:
  • The configured path may be too short or placeholder-like; set a full real path.

Important Notes

• This tool syncs .env files as plain files. Protect access to your Samba share.
• Project folder name must match across machines if you expect to share the same synced location.
• Review conflict logs (Conflict: ... Keeping local.) to understand overwrite decisions.

Scripts

• pnpm dev - run CLI in watch mode with tsx
• pnpm build - bundle CLI with tsup

Created with the support of AI to bridge the gap between local dev and network storage.