git-crypt-guide.md

Git-crypt Setup Guide for Secure Repositories

For developers using git with sensitive data who need better security than just a private repository. Here's a guide to transparent git encryption with git-crypt that ensures data-at-rest and data-in-transit encryption. Perfect for use with note taking apps like Obsidian and Logseq.

Key Benefits

• Transparent encryption: Files are automatically encrypted when pushed, decrypted when pulled
• Selective encryption: Choose which files or directories to encrypt
• Cloud-provider agnostic: Works with any git host (GitHub, GitLab, Bitbucket, etc.)
• Perfect for note-taking apps: Seamlessly encrypt Obsidian vaults, Logseq graphs, or any markdown-based notes
• Collaboration-friendly: Share access with specific users via keys or GPG

Common Use Cases

• Personal knowledge bases and notes (Obsidian, Logseq, etc.)
• Configuration files with sensitive data
• Private documentation
• Development notebooks with sensitive analysis
• Project files containing intellectual property

Prerequisites

• Basic familiarity with git and command line
• A git repository that needs encryption
• Admin access to install software on your machine

Installation

macOS

brew install git-crypt

Ubuntu/Debian

sudo apt-get install git-crypt

Basic Setup

Initialize in your repository:

cd your-repository
git init
git-crypt init

Generate a key file for backup

git-crypt export-key ~/Desktop/repository-key

Caution

Store your key somewhere secure outside of the repository!

Create .gitattributes to specify which files to encrypt:

# Encrypt all markdown files
*.md filter=git-crypt diff=git-crypt

# Encrypt all files in these directories
private/** filter=git-crypt diff=git-crypt

# Don't encrypt .gitattributes
.gitattributes !filter !diff

Commit your initia git-crypt setup:

git add .
git commit -m "chore: add initial get-crypt setup"
git push

Usage on Additional Machines

Clone and unlock the repository:

git clone your-repository-url
cd repository-name
git-crypt unlock /path/to/repository-key

Adding Users

If using GPG keys:

git-crypt add-gpg-user USER_ID

Verification

Check encryption status:

# Should show encrypted binary data when locked
git-crypt status
cat your-file.md  # When locked
git-crypt unlock /path/to/repository-key
cat your-file.md  # When unlocked

Common Gotchas and Tips

1. IMPORTANT: Always backup your key file (.git/git-crypt/keys/default)
2. New files matching .gitattributes patterns are automatically encrypted
3. Use git-crypt status to show which files are/should be encrypted
4. If a file should be encrypted but isn't, remove it from git's cache:

   git rm --cached sensitive-file.md
   git add sensitive-file.md

5. Check if repository is locked/unlocked:

   git-crypt status | grep -q "not encrypted" && echo "unlocked" || echo "locked"

Best Practices

1. Never commit your key file to any repository
2. Use specific patterns in .gitattributes to avoid accidentally encrypting the wrong files
3. Consider using pre-commit hooks to prevent accidental commits of sensitive data
4. Regularly verify that sensitive files are being encrypted properly
5. Keep a secure backup of your encryption key - if you lose it, you cannot decrypt your files

Security Considerations

• git-crypt uses AES-256 encryption
• Encrypted files are binary in the repository but transparent locally
• File names and directory structures remain visible
• Commit messages and history remain visible