gitvaulty
Browse documentation
Command reference

gitvaulty edit

Edit an encrypted file through a private temporary plaintext copy.

View source ↗

Edit an encrypted file through a private temporary plaintext copy.

Usage

npx gitvaulty edit <path>

Examples:

npx gitvaulty edit .env
npx gitvaulty edit config/secrets.yaml

Use the logical plaintext path without .gitvaulty.

If <path>.gitvaulty already exists as an unregistered zero-byte regular file, edit initializes it as a new encrypted file before opening it. The file receives the repository's default group access, just like gitvaulty create, so your registered user must belong to that group.

What it does

  1. Initializes an eligible zero-byte encrypted placeholder, if necessary.
  2. Confirms that your registered user can access the file.
  3. Decrypts the ciphertext into a private system-temporary directory.
  4. Opens the normal plaintext filename with $VISUAL, $EDITOR, or the platform default editor.
  5. If the bytes changed, encrypts them, decrypts the result for verification, and atomically replaces <path>.gitvaulty.
  6. Removes the temporary directory when the editor closes.

If nothing changed, the ciphertext is left untouched. GitVaulty refuses to overwrite ciphertext that changes unexpectedly during guarded editing operations. Non-empty unregistered files and empty files that are already registered are never reinitialized.

Materialized plaintext conflicts

If a persistent plaintext copy exists and still matches the ciphertext, edit updates it after a successful save. If it has independent local changes, the command asks you to choose:

  • Use <path> changes: encrypt them, then edit: make the materialized plaintext authoritative, update the encrypted file, and then open the plaintext in the editor.
  • Discard <path> changes: restore it from <path>.gitvaulty, then edit: overwrite the materialized plaintext with the encrypted version and then open it in the editor.
  • Cancel: make no changes.

Git-tracked plaintext, symlinks, directories, and other unsafe destinations are rejected.

Temporary plaintext boundary

The temporary file has private permissions and is normally deleted immediately. A crash or forced termination can prevent cleanup. Every later GitVaulty command checks for abandoned gitvaulty-edit-* directories and removes only conservative matches after a grace period.

The editor and its extensions can read the decrypted content. See the VS Code guide or JetBrains plugin guide for the security boundary of native editing.

Git behavior

The updated ciphertext is not automatically staged or committed.