git-crypt lets you transparently encrypt files in a Git repository. Encrypted files are decrypted automatically when checked out, and encrypted when committed — so you can keep secrets (API keys, credentials, configs) right alongside your code without exposing them.

Install

1
2
3
4
5

# macOS
brew install git-crypt

# Ubuntu / Debian
sudo apt install git-crypt

Initialize git-crypt in a Repository

1
2

cd your-repo
git-crypt init

This generates a symmetric encryption key stored inside .git/git-crypt/.

Configure Which Files to Encrypt

Create (or edit) a .gitattributes file at the root of your repo to specify which paths should be encrypted:

1
2
3
4

# .gitattributes

secrets/* filter=git-crypt diff=git-crypt
*.secret filter=git-crypt diff=git-crypt

• secrets/* — encrypts everything under the secrets/ directory.
• *.secret — encrypts any file ending with .secret.

Commit the attributes file:

1
2

git add .gitattributes
git commit -m "Add git-crypt encryption rules"

From now on, any file matching these patterns will be automatically encrypted when pushed and automatically decrypted when pulled (as long as git-crypt is unlocked).

Add Sensitive Files

1
2
3
4

echo "DB_PASSWORD=super-secret-123" > secrets/db.env
git add secrets/db.env
git commit -m "Add encrypted database credentials"
git push

On GitHub / GitLab the file will appear as binary gibberish. Locally it’s plain text — seamless.

Export the Key

You need the key to unlock the repo on another machine or share with teammates:

1

git-crypt export-key git-crypt-key

⚠️ Keep this key safe! Anyone with the key can decrypt your secrets. Consider storing it in a password manager like Bitwarden.

Unlock a Cloned Repository

On a new machine, clone the repo then unlock with the exported key:

1
2
3

git clone [email protected]:you/your-repo.git
cd your-repo
git-crypt unlock /path/to/git-crypt-key

All encrypted files are now readable in plain text.

Lock the Repository

When you’re done working and want to re-encrypt files on disk:

1

git-crypt lock

This turns the encrypted files back into unreadable binary locally. Useful on shared machines or before handing off a laptop.

Verify Encryption Status

Check which files are being encrypted:

1

git-crypt status

Example output:

1
2
3

    encrypted: secrets/db.env
not encrypted: .gitattributes
not encrypted: README.md

Cheat Sheet

Tips

• Don’t commit the key file — add git-crypt-key to .gitignore.
• One key per repo — each git-crypt init creates a unique key.
• GPG users — you can also add collaborators via GPG keys with git-crypt add-gpg-user <GPG-KEY-ID>, avoiding the need to share a symmetric key file.
• CI/CD — base64-encode the key and store it as a CI secret, then decode and unlock during pipeline runs.

That’s it — git-crypt is one of the simplest ways to keep secrets in Git without leaking them. 🔐