How to keep local development secrets out of Git

First, find out whether Git already knows the file.

Before moving anything, check the current repository rather than assuming .gitignore has always protected it:

git ls-files --error-unmatch .env
git check-ignore -v .env
git log --all -- .env

If the first command prints the filename, Git is tracking it. If the history command shows earlier commits, assume the contained credentials may have escaped. Remove the file from tracking, revoke or rotate reusable credentials, then decide separately whether repository history must be rewritten.

Deleting the current file or adding a new ignore rule cannot make a disclosed credential secret again.

Move one non-production value first.

Choose a credential which is easy to exercise and safe to rotate. Keep its application-facing name, such as DATABASE_URL. Initialize the local encrypted vault once, if needed, then store the concrete value:

kimen vault init
kimen secret set dev.database_url

kimen secret set uses a hidden prompt, so the value does not need to become a command-line argument or shell-history entry.

Commit the requirement, not the value.

Add a profile which connects the name expected by the application to the local vault key:

# .kimen/profiles/dev.kmap
env DATABASE_URL=dev.database_url

This file is safe to review and commit. It names the requirement and the developer's local binding, but it does not contain the database URL.

Validate before deleting the old copy.

Ask Kimen to validate the map, unlock the vault and confirm that every referenced key exists:

kimen doctor --profile dev

Then verify availability without printing the value:

kimen run --profile dev -- \
  sh -c 'test -n "$DATABASE_URL" && echo "DATABASE_URL is available"'

Finally, start the real application through Kimen and exercise the code path which uses the credential:

kimen run --profile dev -- ./app

With no active session, Kimen asks for the vault passphrase for each doctor or run invocation. During a short migration session, use kimen session start --ttl 15m and close it with kimen session lock.

Only after the application works should you delete the plaintext project copy. Keep the filename ignored if local tools may recreate it.

Repeat deliberately, not all at once.

Move the next value only after the first path is stable. Some credentials may be used by tests, background workers, migration scripts or editor tooling in addition to the main application.

Kimen Core does not distribute shared values or rotate every developer's vault. A team still needs a trusted provisioning channel, such as an existing password or secret manager. Kimen changes how the local value is stored and how the project consumes it.

For environment variables, temporary files, stdin and persistent output, continue with the runtime projection guide.