git-secret

Initialize git-secret in a local repository

Grant access to the current Git user's email
Grant access by email
Revoke access by email
List emails with access to secrets
Register a secret file
Encrypt secrets
Decrypt secret files

git secret [options] [arguments]

Common commands include:
git secret init
git secret tell <gpg-id>...
git secret hide
git secret reveal
git secret add <file-path>...
git secret remove <file-path>...

init
    Initializes a Git repository for git-secret management. This creates the .gitsecret directory and its essential configuration files.

tell ...
    Adds one or more GPG public key IDs to the list of authorized users who can encrypt and decrypt the repository's secrets.

hide
    Encrypts all files currently tracked by git-secret and prepares their encrypted versions for committing to Git. The plaintext files are removed (unless configured otherwise).

reveal
    Decrypts all tracked secret files, making their plaintext content available in the working directory for use.

add ...
    Marks specified files or directories to be managed as secrets by git-secret. Their paths are added to the .gitsecret/paths file.

remove ...
    Unmarks specified files or directories from git-secret management. They will no longer be encrypted/decrypted by the tool.

whoknows
    Displays a list of GPG key IDs for all users who are authorized to decrypt the secrets in the current repository.

whoami
    Shows the GPG key ID that git-secret will use for the current user to encrypt or decrypt files.

clean
    Removes all plaintext versions of secret files from the working directory, leaving only their encrypted counterparts.

status
    Shows the current encryption status of tracked secret files (e.g., encrypted, unencrypted, or unknown).

diff [file-path]
    Displays a diff between the plaintext and encrypted versions of a secret file. If no path is given, it shows diffs for all tracked secrets.

git-secret is a powerful bash tool that leverages gpg (GNU Privacy Guard) to securely manage sensitive files within a Git repository. It enables development teams to store confidential data like API keys, database credentials, or configuration files directly alongside their codebase without exposing the plaintext in version control history. The fundamental principle is that only the encrypted versions of these files are committed to Git, while developers can locally decrypt and access the plaintext content using their personal GPG keys. This ensures that sensitive data remains encrypted at rest and during transit through Git operations. git-secret supports collaborative environments by allowing multiple users to be authorized, each identified by their GPG public key ID, granting them decryption capabilities. It offers intuitive commands to initialize a repository for secret management, specify which files to track as secrets, encrypt (hide) them, and decrypt (reveal) them, seamlessly integrating into typical Git workflows to prevent accidental plaintext commits and streamline secure collaboration.

git-secret relies heavily on a properly installed and configured gpg environment, including users having their GPG keys set up and trusted. Key management (generation, revocation, distribution) is external to git-secret. Users must be diligent to avoid accidentally committing plaintext files; while git-secret includes protective measures, manual overrides like git add -f can bypass them. It does not provide integrity checks beyond what Git offers for version control. Diffing encrypted binary files can be unhelpful as the encrypted output is itself binary.

git-secret uses two primary files within the .gitsecret/ directory to manage secrets:

• .gitsecret/paths: This file lists all the relative paths to the files that git-secret is currently tracking and managing as secrets.
• .gitsecret/keys: This file stores the GPG public key IDs of all authorized users who have the ability to encrypt and decrypt the secrets in the repository.

Both of these files are designed to be committed to the Git repository, allowing the secret configuration to be version-controlled and shared among collaborators.

git-secret is designed to integrate smoothly into a standard Git development workflow. After adding files to be managed with git secret add and encrypting them with git secret hide, the encrypted versions are ready to be staged and committed using standard git add and git commit commands. When a new developer clones the repository, they can run git secret reveal (after being added to the .gitsecret/keys file and having their GPG key imported) to decrypt the files for local development. This approach ensures that only the encrypted versions of sensitive data are ever pushed to remote repositories, significantly reducing the risk of accidental data leaks.

git-secret emerged as an open-source solution to the persistent challenge of securely storing sensitive configuration data within Git repositories. It offers a straightforward and Git-native approach to managing secrets using the well-established GPG standard. Its development has consistently emphasized simplicity, seamless integration into existing Git workflows, and robust encryption. Over the years, it has gained popularity among developers seeking a lightweight, command-line tool to keep secrets out of their plaintext Git history, benefiting from regular updates and community contributions.

git(1), gpg(1), ansible-vault(1), sops(1), blackbox(1)