{"id":23131901,"url":"https://github.com/theobrigitte/trk","last_synced_at":"2026-04-29T23:07:24.706Z","repository":{"id":268248053,"uuid":"903543724","full_name":"TheoBrigitte/trk","owner":"TheoBrigitte","description":"Git wrapper with encryption and dotfiles capabilities","archived":false,"fork":false,"pushed_at":"2025-02-16T18:31:19.000Z","size":66,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-04T07:34:08.888Z","etag":null,"topics":["bash","dotfiles","dotfiles-manager","encryption-decryption","git","git-filter","gitattributes","openssl"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TheoBrigitte.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-14T21:46:09.000Z","updated_at":"2025-02-16T18:31:23.000Z","dependencies_parsed_at":"2024-12-15T14:34:25.711Z","dependency_job_id":"dc24dd10-6388-4f1f-9ef2-e0d16643cb66","html_url":"https://github.com/TheoBrigitte/trk","commit_stats":null,"previous_names":["theobrigitte/trk"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/TheoBrigitte/trk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheoBrigitte%2Ftrk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheoBrigitte%2Ftrk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheoBrigitte%2Ftrk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheoBrigitte%2Ftrk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TheoBrigitte","download_url":"https://codeload.github.com/TheoBrigitte/trk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheoBrigitte%2Ftrk/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263331774,"owners_count":23450155,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","dotfiles","dotfiles-manager","encryption-decryption","git","git-filter","gitattributes","openssl"],"created_at":"2024-12-17T11:16:15.901Z","updated_at":"2026-04-29T23:07:24.701Z","avatar_url":"https://github.com/TheoBrigitte.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg src=\"assets/trk.jpg\" alt=\"trk\" height=\"100px\"\u003e\n\u003c/p\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n  [![GitHub Release](https://img.shields.io/github/v/release/TheoBrigitte/trk)](https://github.com/TheoBrigitte/trk)\n  [![test](https://github.com/TheoBrigitte/trk/actions/workflows/test.yaml/badge.svg)](https://github.com/TheoBrigitte/trk/actions/workflows/test.yaml)\n  ![GitHub Downloads](https://img.shields.io/github/downloads/TheoBrigitte/trk/total)\n\n\u003c/div\u003e\n\n# trk\n\nTrk (or track) is a Git wrapper to managed repositories, with encryption and permissions tracking capabilities.\n\nIt can be used to manage regular Git repositories or to manage a global repository like a [dotfiles](https://wiki.archlinux.org/title/Dotfiles) repository.\n\nEncryption is delegated to [git-crypt](https://github.com/AGWA/git-crypt) which provides transparent encryption using [Git clean/smudge filters](https://git-scm.com/book/ms/v2/Customizing-Git-Git-Attributes#filters_a) to encrypt and decrypt files seamlessly, meaning that encrypted files are stored in the repository and decrypted on the fly when checked out.\n\nPermissions tracking is done using `getfacl` and `setfacl` to store and restore full file permissions and ownership, not just the executable bit like Git does by default.\n\nBoth encryption and permissions tracking are opt-in mechanisms, you have to choose which files to encrypt and which files to track permissions for.\n\n# Why trk ? Another dotfiles manager ?\n\nTrk is more than a dotfiles manager, it can be used to manage any Git repository with encryption capabilities. There are many solutions out there for managing dotfiles and encryption in Git but none of them felt right:\n\n- git-crypt is great and does the encryption job well, but it is not very pratical when it comes to actually managing encrypted files and handling of .gitattributes which must be done manually.\n- chezmoi seems like a good tool overall but does not support transparent encryption of files.\n- yadm is also very powerfull but does not provide anything on top of git-crypt and handle permissions in a very specific way.\n\nIn the end I needed a solutions which woudld provide:\n\n- Transparent and seamless encryption of files in Git repositories.\n- Easy management of which files are encrypted.\n- Global dotfiles like repository for a given worktree, not necessarily the home directory.\n- Permissions tracking for files in the repository.\n\nThat's why I created trk.\n\n## Quick start\n\nGrab the script and install it in your path:\n\n```\nwget https://raw.githubusercontent.com/TheoBrigitte/trk/refs/heads/main/trk\ninstall -D -m 755 trk ~/.local/bin/trk\n```\n\n### From scratch\n\n```\ntrk init\n```\n\n### From existing repository\n\n```\ntrk setup\n```\n\n### From a remote repository\n\n```\ntrk clone \u003curl\u003e\n```\n\n## Encryption\n\nTrk provides **transparent encryption** for sensitive files in your repository using [git-crypt](https://github.com/AGWA/git-crypt). Files are automatically encrypted when committed and decrypted when checked out, making the process seamless.\n\n### How It Works\n\nTrk uses a **selective encryption** approach where you explicitly mark which files or patterns should be encrypted:\n\n1. **Mark files** for encryption using `trk mark \u003cfile\u003e` or `trk mark '\u003cpattern\u003e'`\n2. **Add and commit**: Files are automatically encrypted via Git clean/smudge filters\n3. **Checkout/pull**: Encrypted files are transparently decrypted when checked out\n4. **Share keys**: Export encryption key to share repository access with others\n\nThe encryption key is automatically generated during `trk init` and stored in `.git/git-crypt/`.\n\n### Enable Encryption\n\nEncryption is **enabled by default**. You can explicitly control it during initialization:\n\n```bash\n# For new repositories\ntrk init --with-crypt     # Enable (default)\ntrk init --without-crypt  # Disable\n\n# For existing repositories\ntrk setup --with-crypt\n```\n\n### Marking Files for Encryption\n\nUse `trk mark` to specify which files should be encrypted:\n\n```bash\n# Mark a specific file\ntrk mark secrets.env\n\n# Mark all files matching a pattern (quote to prevent shell expansion)\ntrk mark '*.key'\ntrk mark 'config/secrets/*'\n\n# Mark a directory\ntrk mark secrets/\n\n# View which patterns are marked for encryption\ncat .gitattributes\n```\n\nMarked patterns are stored in `.gitattributes` using git-crypt filter rules and should be committed to the repository.\n\n### Key Management\n\nThe recommended way to share repository access is using **GPG keys** rather than sharing symmetric keys. Each collaborator uses their own GPG key:\n\n```bash\n# Add a collaborator's GPG key (they can now decrypt the repository)\ntrk crypt add-gpg-user user@example.com\n\n# Collaborator clones and unlocks repository with their GPG key\ntrk clone \u003curl\u003e\ntrk crypt unlock\n```\n\n**Symmetric key backup (fallback option):**\n\nFor backup purposes or when GPG is not available, you can export a symmetric key:\n\n```bash\n# Export symmetric key for backup\ntrk crypt export-key keyfile\n\n# Clone repository with symmetric key\ntrk clone --key-file keyfile \u003curl\u003e\n\n# Setup existing repository with symmetric key\ntrk setup --key-file keyfile\n```\n\n**Important**: Keep your encryption keys secure! Anyone with access can decrypt your files.\n\n### Verify Encryption\n\nYou can verify that files are actually encrypted in Git:\n\n```bash\n# View raw encrypted content in repository\ngit rev-list --objects -g --no-walk --all\ngit cat-file -p \u003chash\u003e\n\n# Or check if git-crypt is working\ngit-crypt status\n```\n\n### Example Workflow\n\n```bash\n# Initialize repository with encryption\ntrk init\n\n# Mark sensitive files for encryption\ntrk mark '.env'\ntrk mark 'secrets/*.key'\ntrk mark 'config/database.yml'\n\n# Verify patterns are set\ncat .gitattributes\n\n# Add and commit files (automatically encrypted)\ntrk add .env config/database.yml secrets/\ntrk commit -m \"Add encrypted configuration files\"\n\n# Push to remote\ntrk push\n\n# Add a team member using their GPG key\ntrk crypt add-gpg-user alice@example.com\ntrk add .git-crypt/\ntrk commit -m \"Add Alice's GPG key\"\ntrk push\n\n# Team member clones and unlocks with their GPG key\ntrk clone https://example.com/repo.git\ntrk crypt unlock\n# Files automatically decrypted on checkout\n\n# Verify encryption is working\ngit-crypt status\n```\n\n## Global / dotfile repository\n\nTrk can be used to manage a global repository, like a dotfiles repository. This happens with you use the `--worktree` option with the `init` and `clone` commands.\n\nGlobal repository is created in a unique location and can be used to manage all files in the given worktree without having to create the Git repository there. For example creating a Git directory in your home directory is probably not a good idea as it will clutter your home directory with Git files and you may accidentally commit files that you don't want to when working on other projects where you forgot to initialize a Git repository.\n\n### From scratch\n\n```\ntrk init --worktree \u003cpath\u003e\n```\n\n### From a remote repository\n\n```\ntrk clone --worktree \u003cpath\u003e \u003curl\u003e\n```\n\nYou can then work with the repository using `trk` as you would with a regular Git repository, encryption works the same way.\n\n## Permission Management\n\nGit only tracks the executable bit for files, not full file permissions or ownership. Trk provides comprehensive permission tracking using `getfacl`/`setfacl` to preserve complete file metadata across different systems.\n\n### How It Works\n\nTrk uses a **selective tracking** approach where you explicitly mark which files or directories should have their permissions tracked:\n\n1. **Mark files** for permission tracking using `trk permissions mark \u003cpath\u003e`\n2. **Before commit** (pre-commit hook): Automatically captures permissions for marked paths using `getfacl` and stores them in `.trk/permissions`\n3. **After checkout** (post-checkout hook): Automatically restores permissions using `setfacl` from `.trk/permissions`\n\nThe system is optimized to only update permissions when tracked files actually change, minimizing overhead.\n\n### Enable Permission Tracking\n\nPermission tracking is **enabled by default**. You can explicitly control it during initialization:\n\n```bash\n# For new repositories\ntrk init --with-permissions     # Enable (default)\ntrk init --without-permissions  # Disable\n\n# For existing repositories\ntrk setup --with-permissions\n```\n\n### Marking Files for Permission Tracking\n\nUnlike automatic tracking of all files, you must explicitly mark which paths should be tracked:\n\n```bash\n# Mark a specific file\ntrk permissions mark bin/script.sh\n\n# Mark a directory (will track all files recursively)\ntrk permissions mark config/\n\n# View which paths are being tracked\ntrk permissions list\n\n# Remove a path from tracking\ntrk permissions unmark bin/script.sh\n```\n\nMarked paths are stored in `.trk/permissions_list` and should be committed to the repository.\n\n### Manual Commands\n\n```bash\n# Mark a file/directory for permission tracking\ntrk permissions mark \u003cpath\u003e\n\n# Remove a file/directory from permission tracking\ntrk permissions unmark \u003cpath\u003e\n\n# List all paths tracked for permissions\ntrk permissions list\n\n# Refresh permissions file with current state (runs pre-commit hook)\ntrk permissions refresh\n\n# Apply stored permissions to files\ntrk permissions apply\n\n# Check differences between stored and actual permissions\ntrk permissions status\n```\n\n### File Structure\n\nTrk uses two files for permission management:\n\n1. **`.trk/permissions_list`**: Lists paths tracked for permissions (one per line)\n   ```\n   bin/trk\n   config/\n   ```\n\n2. **`.trk/permissions`**: Stores actual permissions in standard ACL format (output from `getfacl`)\n   ```\n   # file: bin/trk\n   user::rwx\n   group::r-x\n   other::r-x\n\n   # file: config/app.conf\n   user::rw-\n   group::r--\n   other::---\n   ```\n\n### Best Practices\n\n1. **Mark files selectively**: Only track files that need specific permissions (executables, config files)\n2. **Review `.trk/permissions`** before committing to ensure correct permissions are captured\n3. **Commit `.trk/permissions_list`** so others know which files are tracked\n4. **Run `trk permissions status`** periodically to detect drift\n5. **Use with encryption** for sensitive system files with restricted permissions\n\n### Example Workflow\n\n```bash\n# Enable permissions on existing repo\ntrk setup --with-permissions\n\n# Mark executable files for permission tracking\ntrk permissions mark bin/trk\ntrk permissions mark bin/deploy.sh\n\n# Verify they're marked\ntrk permissions list\n\n# Commit the tracking list\ntrk add .trk/permissions_list\ntrk commit -m \"Track permissions for bin/ scripts\"\n\n# Add files with specific permissions\nchmod 755 bin/deploy.sh\ntrk add bin/deploy.sh\ntrk commit -m \"Add deployment script\"  # Permissions automatically captured\n\n# Clone on another system\ntrk clone --key-file key https://example.com/repo.git\n# Permissions automatically restored for marked files\n\n# Check if permissions match\ntrk permissions status\n```\n\n### Credits and alternatives\n\nIt is shamelessly inspired from [yadm](https://github.com/yadm-dev/yadm) and [transcrypt](https://github.com/elasticdog/transcrypt).\n\n- https://github.com/AGWA/git-crypt\n- https://github.com/elasticdog/transcrypt\n- https://github.com/sobolevn/git-secret\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheobrigitte%2Ftrk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftheobrigitte%2Ftrk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheobrigitte%2Ftrk/lists"}