Track checkouts and place files

Track a checkoutCopy Anchor Link

envden track /path/to/checkout

You can also pass a scan root to find several repos. Without a path, track starts in the current directory.

Approve each checkout in your terminal before envden places files there. Every worktree needs its own approval, even if its repo is already approved. --yes on setup doesn't bypass this step. Approval is stored outside the checkout, and a changed remote doesn't silently change its repo identity.

Link modeCopy Anchor Link

By default, envden places a symlink into your device's store:

~/.envden/store/<repo-id>/<path-in-repo>/<file>

Approved clones and worktrees of the same repo share that store file. In a monorepo, apps/web/.env keeps its path under the repo's store directory.

Repo identity comes from the origin remote, or the only remote if there is no origin. envden asks when the choice is ambiguous. The Repo ID is encrypted before upload.

Store directories use 0700 permissions and files use 0600, with ACLs on Windows. Before placement, envden checks git's ignore rules and adds a missing exclusion to the checkout's git exclude file. It refuses tracked files.

Copy modeCopy Anchor Link

Choose copies when a tool or container needs a regular file:

envden track /path/to/checkout --copy

Each copy has its own sync base. Edits in one checkout don't immediately change another checkout's file.

If symlinks aren't available, envden asks for consent before placing copies. It also offers copy mode once per checkout when the root contains .devcontainer/, docker-compose*.yml or Dockerfile.

Save a placement preference for a checkout:

envden config placement /path/to/checkout copy
envden config placement /path/to/checkout link

This saves the preference; it doesn't immediately convert existing files. Placement uses the choice when you track the checkout.

Keep a file localCopy Anchor Link

For a per-worktree setting such as PORT, mark the managed file local-only before editing it:

envden local-only /path/to/checkout/.env

It becomes a regular copy in that checkout. envden skips it during push and pull and suppresses sync notices for it. Other checkouts keep syncing their versions.

Stop tracking a checkoutCopy Anchor Link

envden untrack /path/to/checkout

This removes the checkout's approval and tracking records and restores regular files in place of managed links. It doesn't delete the vault's files or untrack other checkouts.

Recover a replaced linkCopy Anchor Link

An atomic editor save, sed -i or cp .env.example .env can replace a symlink with a regular file. envden relinks a file that matches the store or an older synced version.

If it differs, envden marks the checkout detached, keeps both versions and asks you what to do on the next interactive command. The shell notice doesn't repair files.

Share files with a fork or renamed repoCopy Anchor Link

When an upstream remote already has env files, envden offers to alias the fork. You can also map identities yourself:

envden alias github.com/you/fork github.com/org/original

Use the normalized Repo IDs for your repos. If the source repo already has placed files, untrack its checkouts first, then alias and track them again. Success prints Alias saved.

Use env files in Docker buildsCopy Anchor Link

Exclude env files from the build context:

.env
.env.*
!.env.example

Pass the file to the build as a BuildKit secret:

# syntax=docker/dockerfile:1
FROM node:22
WORKDIR /app
COPY . .
RUN --mount=type=secret,id=dotenv,target=/app/.env npm run build

docker build --secret id=dotenv,src=.env .

The mount exists for that RUN step. Copy mode isn't a build secret mechanism; a copied file included in the build context can land in an image layer. Your build command must also avoid embedding secret values in its output.