yadm-git-crypt

Initialize repo to use Git Crypt

$ yadm git-crypt init

$ yadm git-crypt add-gpg-user [user_id]

$ yadm git-crypt unlock

$ yadm git-crypt export-key [path/to/key_file]

While "yadm-git-crypt" is typically a conceptual integration rather than a standalone command, interaction occurs by executing git-crypt subcommands within the yadm repository. The general form is to navigate to your yadm repository root and then execute git-crypt commands, or use yadm's pass-through functionality.

yadm git crypt <subcommand> [options]
Or, more directly, by operating within your yadm repository:
cd "$(yadm root)" && git crypt <subcommand> [options]

init
    Initializes git-crypt for the current repository. This must be done once per repository to set up the encryption key.

add-gpg-user
    Adds a GPG key to the list of authorized decryptors for the repository. This allows users with the specified GPG key to decrypt the files.

unlock [key-path]
    Decrypts files in the working directory using the primary key or a specified key file. Usually, it's automatically handled if you have the GPG key.

status
    Shows the encryption status of files in the repository, indicating which files are configured for encryption and their current state (encrypted/decrypted).

export-key
    Exports the symmetric encryption key of the repository to a file. Useful for backing up the key or sharing it securely.

help
    Displays help information for git-crypt or a specific subcommand.

The concept of "yadm-git-crypt" refers to the powerful integration of yadm (Yet Another Dotfiles Manager) with git-crypt, a tool designed for transparent encryption of files within a Git repository. Yadm leverages Git to manage your dotfiles, making it easy to synchronize configurations across multiple machines. However, dotfiles often contain sensitive information like API keys, SSH private keys, or personal tokens that should not be exposed in a public Git repository. Git-crypt addresses this by allowing you to encrypt specific files or patterns of files within your Git repository, decrypting them automatically when you git pull and encrypting them again on git push.

When used together, yadm-git-crypt enables users to securely store and synchronize sensitive dotfiles. This means you can keep your dotfiles repository public on platforms like GitHub, while ensuring that confidential data remains encrypted. The integration is typically achieved by initializing git-crypt within your yadm-managed repository and configuring a .gitattributes file to specify which files or directories need to be encrypted. Subsequent operations like yadm pull or yadm push will then handle the encryption/decryption transparently, provided the necessary decryption keys are available on the system. This setup offers a robust solution for managing sensitive configuration data while maintaining the convenience of version control.

Dependency Requirement: Both yadm and git-crypt must be installed and properly configured on the system for this integration to function.
Key Management: The security of your encrypted dotfiles heavily relies on the secure management of your GPG keys (or other chosen decryption methods). Loss of keys means permanent loss of access to encrypted data.
.gitattributes Configuration: Incorrectly configured .gitattributes files can lead to sensitive files being committed unencrypted, or important files being encrypted and becoming inaccessible if keys are lost.
Complexity: Integrating and managing git-crypt adds a layer of complexity to dotfile management, especially for new users.

For git-crypt to work correctly within your yadm repository, you must specify which files or patterns should be encrypted. This is done by adding entries to a .gitattributes file at the root of your yadm repository. For example, to encrypt a file named secrets.txt and all files within a keys/ directory, you would add the following lines:

secrets.txt filter=git-crypt diff=git-crypt
keys/** filter=git-crypt diff=git-crypt

Commit this .gitattributes file to your repository before adding or modifying the files you intend to encrypt. This ensures Git tracks the files as encrypted from the start.

A common workflow for setting up yadm-git-crypt involves:

1. Initialize yadm: If you haven't already, set up your dotfiles with yadm (e.g., yadm init).
2. Initialize git-crypt: Navigate to your yadm repository root (cd "$(yadm root)") and run git crypt init.
3. Add GPG User: Add your GPG key(s) to allow decryption: git crypt add-gpg-user <your-gpg-key-id>.
4. Configure .gitattributes: Create or edit .gitattributes in your yadm root to mark sensitive files for encryption (e.g., private_key.txt filter=git-crypt diff=git-crypt). Make sure to add and commit this file before adding the sensitive files themselves.
5. Add Sensitive Files: Add your sensitive files to yadm (e.g., yadm add private_key.txt). They will be automatically encrypted when committed and pushed.
6. Push to Remote: yadm push will push the encrypted files to your remote repository.

The concept of encrypting sensitive files within version control systems predates both yadm and git-crypt. Git-crypt was created by Andrew Ayer to provide transparent encryption for Git repositories, gaining popularity for its ease of use compared to manual encryption or external tools. Yadm (Yet Another Dotfiles Manager) emerged as a robust tool for managing dotfiles using Git, offering features like alternate files and templates. The integration of git-crypt with yadm is a natural evolution driven by user needs to securely manage sensitive configuration data (like API tokens or SSH keys) within publicly shared dotfiles repositories. While no specific "yadm-git-crypt" project exists as a distinct entity, the pattern of using these two tools in conjunction has become a standard best practice for secure dotfile management.

yadm(1): Yet Another Dotfiles Manager, the core tool for managing dotfiles., git-crypt: A transparent file encryption tool for Git repositories., git(1): The distributed version control system that both yadm and git-crypt rely upon., gpg(1): GNU Privacy Guard, often used by git-crypt for managing access to encrypted data.