git-crypt-guardian

Professional automation and management tool for git-crypt with background file watching, whole-codebase encryption, and comprehensive reporting.

What is this?

git-crypt is excellent for selectively encrypting a few files in a repository (secrets, credentials, etc.). However, if you need to encrypt your entire codebase (or most of it) to protect intellectual property, git-crypt-guardian provides the automation, validation, and background processing to make this practical and performant.

Features

✅ Three encryption modes

• all - Encrypt everything in the repository
• exclude-dirs - Encrypt everything except specified directories
• include-only - Encrypt only specified directories

✅ Background file watching

• Monitors filesystem for changes
• Automatically stages modified files (triggering git-crypt encryption)
• Smart hash tracking prevents redundant operations

✅ Comprehensive validation

• Pre-flight directory existence checks
• Encryption status verification
• Detects already-encrypted files
• Warning system for potential issues

✅ Rich reporting

• Pre-encryption scan reports
• Post-operation summaries (files encrypted, skipped, errors)
• Live status dashboard
• Export reports in JSON and Markdown

✅ Professional CLI

• Clean, intuitive command structure
• Beautiful terminal output (powered by Rich)
• Progress bars and status indicators

Relationship to git-crypt

This is a companion tool that works alongside git-crypt (required dependency). We handle:

• .gitattributes generation
• Background file watching
• Auto-staging
• Validation and reporting

While git-crypt handles the actual encryption/decryption. This tool is designed for a use case outside git-crypt's intended scope (encrypting entire codebases vs. a few secret files).

Installation

Prerequisites

1. git-crypt must be installed:

   # macOS
   brew install git-crypt
   
   # Ubuntu/Debian
   apt-get install git-crypt
   
   # Other platforms: https://github.com/AGWA/git-crypt/blob/master/INSTALL.md

2. Python 3.10+ required

Install git-crypt-guardian

pip install git-crypt-guardian

Or install from source:

git clone https://github.com/code-of-kai/git-crypt-guardian.git
cd git-crypt-guardian
pip install -e .

Quick Start

1. Initialize git-crypt in your repository (if not already done):

   cd your-repo
   git-crypt init

2. CRITICAL: Export your encryption key immediately:

   git-crypt export-key ~/safe-location/repo-name.key
   # Store this key securely! You'll need it to unlock later.

3. Initialize git-crypt-guardian:

   git-crypt-guardian init

   This creates a .gitcrypt-guardian.yml configuration file.

4. Edit configuration to specify what to encrypt:

   # .gitcrypt-guardian.yml
   version: 1
   mode: exclude-dirs
   
   exclude:
     - .git
     - node_modules
     - _build

5. Validate your configuration:

   git-crypt-guardian validate

6. Apply encryption (generates .gitattributes):

   git-crypt-guardian apply

7. Start background watcher (optional):

   git-crypt-guardian start

Commands

git-crypt-guardian init          # Initialize in repository
git-crypt-guardian config        # Interactive configuration setup
git-crypt-guardian validate      # Pre-flight checks
git-crypt-guardian apply         # Apply encryption (generate .gitattributes)
git-crypt-guardian start         # Start background daemon
git-crypt-guardian stop          # Stop background daemon
git-crypt-guardian status        # Show encryption status
git-crypt-guardian report        # Generate detailed report

Configuration

See examples/ directory for complete configuration examples.

Basic Configuration

version: 1
mode: all  # Encrypt everything

watch:
  enabled: true
  debounce_ms: 500
  auto_stage: true

report:
  format: both  # terminal | file | both
  output_dir: .gitcrypt-reports
  verbose: true

Exclude Directories

version: 1
mode: exclude-dirs

exclude:
  - .git
  - node_modules
  - __pycache__
  - "*.log"
  - _build/

watch:
  enabled: true

Include Only Specific Directories

version: 1
mode: include-only

include:
  - src/
  - lib/
  - config/
  - "*.secret"

watch:
  enabled: false

Performance

For a typical medium-sized project (500 files, ~50MB):

• Initial encryption setup: ~500ms-2s
• Background auto-staging per file: <100ms
• Minimal overhead for daily workflows

See our performance documentation for detailed benchmarks.

Use Cases

• Protecting intellectual property in private repositories
• Encrypting proprietary algorithms or business logic
• Securing entire codebases before pushing to cloud git hosts
• Compliance requirements for source code encryption
• Educational/research projects with sensitive implementations

Important Caveats

⚠️ What git-crypt DOESN'T encrypt:

• File names (visible in git log)
• Directory structure (visible)
• Commit messages (visible)
• File sizes (approximate, visible)
• Git metadata

⚠️ Merge conflicts: Encrypted files appear as binary blobs, making conflicts harder to resolve manually.

⚠️ Team collaboration: All team members need git-crypt keys (GPG keys or symmetric key file) to decrypt and work with the repository.

Key Management Best Practices

CRITICAL: Export Your Key First!

Before locking your repository for the first time, export your encryption key:

# Export symmetric key (REQUIRED)
git-crypt export-key ~/safe-location/project-name.key

# Store this key securely:
# - Password manager (1Password, LastPass, etc.)
# - Encrypted backup drive
# - Company secrets vault

Why this matters:

• Running git-crypt lock without exporting the key first will lock you out permanently
• You cannot decrypt your files without the key
• Re-running git-crypt init generates a NEW key - old encrypted data becomes inaccessible

Unlocking a Repository

# With symmetric key
git-crypt unlock /path/to/project-name.key

# With GPG (if you've added GPG users)
git-crypt unlock  # Uses your GPG key automatically

Team Collaboration Options

Option 1: Symmetric Key (Simple, Single User)

git-crypt init
git-crypt export-key team-key.key
# Share team-key.key securely with collaborators

Option 2: GPG Keys (Better for Teams)

git-crypt init
git-crypt add-gpg-user user1@example.com
git-crypt add-gpg-user user2@example.com
# Each team member can decrypt with their own GPG key

Backup Strategy

1. Export key immediately after git-crypt init
2. Store in multiple secure locations
3. Share with team securely (never commit key to repository!)
4. Document key location in team wiki/docs
5. Test unlocking on another machine before deleting your working copy

How .gitattributes Pattern Matching Works

Understanding how git-crypt uses .gitattributes patterns is crucial for proper encryption.

Pattern Matching Rules

Last matching pattern wins:

# WRONG - exclusions don't work
*.log !filter !diff         # Exclude logs
** filter=git-crypt          # But ** comes last, so logs get encrypted!

# CORRECT - exclusions come last
** filter=git-crypt          # Encrypt everything first
*.log !filter !diff          # Then exclude logs (overrides **)

git-crypt-guardian generates patterns in the correct order automatically.

Pattern Types

# Encrypt specific file
secret.txt filter=git-crypt diff=git-crypt

# Encrypt file pattern
*.secret filter=git-crypt diff=git-crypt

# Encrypt directory and all contents
secrets/** filter=git-crypt diff=git-crypt

# EXCLUDE from encryption
logs/** !filter !diff
*.log !filter !diff

Verification

Always verify your patterns work correctly:

# Check what will be encrypted
git-crypt status

# Files show as:
# encrypted: file.txt              # Will be encrypted
# not encrypted: file.log          # Will NOT be encrypted

Files Committed Before .gitattributes

Important: Files committed before .gitattributes remain unencrypted in git history:

# This is normal and expected:
git-crypt status
encrypted: file.txt *** WARNING: staged/committed version is NOT ENCRYPTED! ***

To properly encrypt existing files:

1. Ensure .gitattributes is committed
2. Re-stage files: git rm --cached -r . && git add .
3. Commit: git commit -m "Encrypt existing files"
4. Old unencrypted versions remain in git history (use git filter-branch if needed)

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details.

Acknowledgments

• git-crypt by Andrew Ayer - the underlying encryption tool
• Built with: Click, GitPython, watchfiles, Rich, and PyYAML

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

Roadmap

• v0.1.0: MVP with init, validate, apply commands
• v0.2.0: Background file watcher daemon
• v0.3.0: System service installation (systemd/launchd)
• v0.4.0: Advanced reporting and analytics
• v1.0.0: Stable release with comprehensive documentation

---

Note: This project is in active development. We're dogfooding it on real-world projects to ensure reliability and performance. Star and watch for updates!