Transcrypt Cheat Sheet

Overview

Transcrypt is a script that transparently encrypts sensitive files stored in a Git repository. It uses OpenSSL symmetric encryption combined with Git’s clean/smudge filter mechanism to automatically encrypt files on commit and decrypt them on checkout. Files appear as plaintext in the working directory but are encrypted in the repository.

Transcrypt is ideal for storing secrets like configuration files, credentials, and certificates directly in Git repositories without exposing them in plaintext to anyone without the encryption key. It works with any Git hosting service and requires only OpenSSL and a Bash shell.

Installation

# macOS
brew install transcrypt

# Linux (from source)
git clone https://github.com/elasticdog/transcrypt.git
cd transcrypt
sudo ln -s $(pwd)/transcrypt /usr/local/bin/transcrypt

# Or download directly
curl -O https://raw.githubusercontent.com/elasticdog/transcrypt/main/transcrypt
chmod +x transcrypt
sudo mv transcrypt /usr/local/bin/

# Verify
transcrypt --version

Core Commands

Command	Description
transcrypt	Initialize encryption in repository
transcrypt -c <cipher> -p <pass>	Init with specific cipher and password
transcrypt -d	Display current configuration
transcrypt -r	Re-encrypt all files
transcrypt -u	Uninstall transcrypt from repo
transcrypt -l	List encrypted files
transcrypt -s	Show raw encrypted content
transcrypt -e	Export credentials
transcrypt -f	Flush credentials and re-checkout

Setup

Initialize Repository

cd my-repo

# Interactive setup (prompts for cipher and password)
transcrypt

# Non-interactive setup
transcrypt -c aes-256-cbc -p 'my-secret-password'

# With specific cipher
transcrypt -c aes-256-gcm -p 'my-secret-password'

Configure .gitattributes

# .gitattributes — specify which files to encrypt
secrets/*.yaml filter=crypt diff=crypt merge=crypt
config/production.env filter=crypt diff=crypt merge=crypt
*.secret filter=crypt diff=crypt merge=crypt
certs/*.pem filter=crypt diff=crypt merge=crypt
.env.production filter=crypt diff=crypt merge=crypt

# After editing .gitattributes, commit it
git add .gitattributes
git commit -m "Configure transcrypt encryption patterns"

Add Encrypted Files

# Create a secret file
echo "DATABASE_URL=postgres://user:pass@db/prod" > config/production.env

# Git add and commit — file is automatically encrypted
git add config/production.env
git commit -m "Add production secrets"

# File appears as plaintext locally but encrypted in repo
cat config/production.env  # readable plaintext

Usage

View Encrypted Files

# List all encrypted files
transcrypt -l

# Show raw encrypted content of a file
transcrypt -s config/production.env

# Show current transcrypt configuration
transcrypt -d
# Output:
#   Cipher: aes-256-cbc
#   Password: my-secret-password
#   Git clean filter: set
#   Git smudge filter: set

Clone and Decrypt

# Clone repository (files will be encrypted/garbled)
git clone https://github.com/user/repo.git
cd repo

# Initialize transcrypt with the same credentials
transcrypt -c aes-256-cbc -p 'my-secret-password'

# Files are now decrypted in working directory
cat config/production.env  # readable!

Export and Share Credentials

# Export credentials for team members
transcrypt -e
# Output: transcrypt -c aes-256-cbc -p 'my-secret-password'

# Team member runs the exported command in their clone
transcrypt -c aes-256-cbc -p 'my-secret-password'

Configuration

Supported Ciphers

# List available OpenSSL ciphers
openssl list -cipher-algorithms

# Commonly used ciphers
transcrypt -c aes-256-cbc -p 'password'   # AES-256-CBC (default)
transcrypt -c aes-256-gcm -p 'password'   # AES-256-GCM (authenticated)
transcrypt -c chacha20 -p 'password'       # ChaCha20

Changing Password

# Uninstall current configuration
transcrypt -u

# Reinitialize with new password
transcrypt -c aes-256-cbc -p 'new-password'

# Re-encrypt all files
transcrypt -r

CI/CD Integration

# In CI pipeline, set up transcrypt before using secrets
# Store password as CI secret variable

# GitHub Actions
echo "$TRANSCRYPT_PASSWORD" | transcrypt -c aes-256-cbc -p - -y

# GitLab CI
transcrypt -c aes-256-cbc -p "$TRANSCRYPT_PASSWORD" -y

# The -y flag skips confirmation prompts

# .github/workflows/deploy.yml
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Decrypt secrets
        run: |
          sudo apt-get install -y transcrypt
          transcrypt -c aes-256-cbc -p "${{ secrets.TRANSCRYPT_PASSWORD }}" -y
      - name: Deploy
        run: ./deploy.sh

Advanced Usage

Multiple Encryption Contexts

# Different patterns for different sensitivity levels
secrets/high/*.yaml filter=crypt diff=crypt merge=crypt
secrets/medium/*.yaml filter=crypt diff=crypt merge=crypt

Git Diff of Encrypted Files

# Transcrypt configures diff=crypt so diffs work on plaintext
git diff config/production.env

# View diff of encrypted content
git diff --no-textconv config/production.env

Re-Encrypting Files

# After password change, re-encrypt all files
transcrypt -r

# Force re-checkout of encrypted files
transcrypt -f

Verifying Encryption

# Show that file is encrypted in Git
git show HEAD:config/production.env  # encrypted binary

# Verify locally decrypted
cat config/production.env  # plaintext

# Check file is in encrypted list
transcrypt -l | grep production.env

Troubleshooting

Issue	Solution
Files not encrypting	Check .gitattributes patterns match file paths
Garbled text after clone	Run transcrypt -c <cipher> -p <password>
Merge conflicts on encrypted files	Resolve in plaintext; transcrypt handles re-encryption
Wrong password	Run transcrypt -u then reinitialize with correct password
OpenSSL not found	Install OpenSSL: apt install openssl or brew install openssl
CI can’t decrypt	Verify CI secret variable is set; add -y flag

# Debug: check git filter config
git config --list | grep filter.crypt
git config --list | grep diff.crypt

# Verify .gitattributes
git check-attr filter -- config/production.env

# Reset transcrypt state
transcrypt -u
transcrypt -c aes-256-cbc -p 'password'
transcrypt -f  # Force re-checkout