{"id":34713194,"url":"https://github.com/brege/ilma","last_synced_at":"2026-04-19T23:31:24.576Z","repository":{"id":312341908,"uuid":"1047192851","full_name":"brege/ilma","owner":"brege","description":"A pure-shell over-engineered wrapper of rsync, gpg, tar, zst that works from the destination machine","archived":false,"fork":false,"pushed_at":"2026-03-10T04:10:46.000Z","size":294,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-10T12:17:17.913Z","etag":null,"topics":["archival","backup","bash","encryption","gpg","rsync","tar","zstd"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brege.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/contributing.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-29T22:40:49.000Z","updated_at":"2026-03-10T04:10:49.000Z","dependencies_parsed_at":"2025-08-30T00:25:47.379Z","dependency_job_id":"a53ba8af-05ea-487c-8470-925f831a4a89","html_url":"https://github.com/brege/ilma","commit_stats":null,"previous_names":["brege/ilma"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/brege/ilma","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brege%2Filma","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brege%2Filma/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brege%2Filma/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brege%2Filma/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brege","download_url":"https://codeload.github.com/brege/ilma/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brege%2Filma/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32026601,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T20:23:30.271Z","status":"online","status_checked_at":"2026-04-19T02:00:07.110Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["archival","backup","bash","encryption","gpg","rsync","tar","zstd"],"created_at":"2025-12-25T00:50:37.421Z","updated_at":"2026-04-19T23:31:24.567Z","avatar_url":"https://github.com/brege.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ilma\n\nA project backup and archival tool for pullable snapshots, portable archives, encryption, and remote collection.\n\n## Features\n\n- **Explicit filter control**\n\n  Use per-project `RSYNC_EXCLUDES` or remote job manifests to decide exactly what gets staged, archived, encrypted, or transferred.\n\n- **Standard GPG, tar, and rsync core with ergonomic CLI**\n\n  Build portable `tar` archives, encrypt them with GPG, and send them to remote storage with `rsync`.\n\n- **Remote Pull Jobs**\n\n  Pull selected files from remote machines by manifest, stage them locally, and archive or encrypt the result.\n\n## Usage\n\n1. [**Install**](#installation)\n\n2. `ilma --help`. All subcommands support `--help`.\n\n3. **Immediate Backup**\n\n   By default, **ilma** will backup the current directory and store a copy as a sibling.\n\n   ```bash\n   cd my-project\n   ilma -a  # archive\n   ls -1 ..\n   ..\n   ├── my-project\n   └── my-project.tar.zst\n   ```\n\n   Or, you can specify a directory to backup, archive, or encrypt.\n\n   ```bash\n   ilma -e ~/Documents/love-letters/\n   ls -1 ~/Documents\n   ~/Documents\n   ├── love-letters\n   └── love-letters.tar.zst.gpg\n   ```\n\n### More Examples\n\n**Send encrypted archive to remote server**\n```bash\nilma --encrypt \\\n     --remote server.local:/storage/backups \\\n     ~/dissertation\n\nssh server.local ls /storage/backups\n# dissertation.tar.zst.gpg\n```\n\n**Config Validation**  \n```bash\nilma validate\n\n```\n**Project litter review**  \n**ilma** no longer owns project litter review. This component has been ported to [**dil**](https://github.com/brege/dil), in Python, for disposable artifact detection and deletion.\n\n## Installation\n\nClone the repository\n```bash\ngit clone https://github.com/brege/ilma\ncd ilma\n./install\n```\n\nFedora dependencies\n```bash\nsudo dnf install rsync git zstd bc pv\n# compression tools (configure: you only need one)\nsudo dnf install zstd gzip bzip2 xz\n```\n\nDebian/Ubuntu dependencies\n```bash\nsudo apt install rsync git zstd bc pv\nsudo apt install zstd gzip bzip2 xz-utils\n```\n\nValidate dependencies\n```bash\nilma validate --dependencies\n```\n\n\u003e [!NOTE] \n\u003e **Compression Algorithms**  \n\u003e\n\u003e The default compression library used in this project is [Zstandard (`zstd`)](https://github.com/facebook/zstd). This is a personal choice, which I use because of good performance on Btrfs filesystems.  Zstandard is also [the algorithm restic uses](https://restic.readthedocs.io/en/latest/100_references.html). While `zstd` is not yet as widely supported across all platforms as `gzip`, `bzip2`, or `xz` (in that order), it is available on most modern Linux systems.\n\u003e\n\u003e Sources: [compression][1],  [speed][2], [usage][3]\n\n[1]: https://rsmith.home.xs4all.nl/miscellaneous/evaluating-zstandard-compression.html?utm_source=chatgpt.com\n[2]: https://patchwork.kernel.org/project/linux-btrfs/patch/20170629194108.1674498-4-terrelln%40fb.com/?utm_source=chatgpt.com\n[3]: https://thelinuxcode.com/enable-btrfs-filesystem-compression/?utm_source=chatgpt.com\n\n### Configuration\n\n**ilma** works out of the box with sensible defaults, but can be customized extensively.\n\n#### Global\nCopy and customize the global **`config.ini`** file\n```bash\ncp config.example.ini config.ini\n```\n#### Per-Project\n\nCreate **`.ilma.conf`** in any project for custom strategies.\nSee **[`dot-ilma.conf.example`](./dot-ilma.conf.example)** for a compact example.\n\n---\n\n## Commands\n\n### Backup Operations\n```bash\ncd /path/to/project\nilma                             # Backup current directory\nilma [PROJECT_PATH]              # Backup specified directory\nilma -a --verify                 # Archive and verify contents\nilma -e --verify --remote srv:/dst  # Encrypt, upload, and verify remote hash\n```\n\n### Validation \u0026 Troubleshooting\n\nAfter customizing your configuration, you can validate your setup quickly without trial-and-error on your data.\n\n```bash\nilma validate                    # Basic configuration validation\nilma validate --full             # Includes remote + dependency checks\nilma validate --remote           # Remote connectivity + manifest linting\n```\n\n### Configuration\n\nOutput your current configuration at any time, in or outside of a project.\n\n```bash\nilma config [PROJECT_PATH]       # Show resolved configuration\n```\n\n### Archive Management\n\nGPG encryption for secure transport to untrusted or exposed storage.\nExtract and decrypt commands auto-detect compression formats and use chunked processing for efficiency.\n\n```bash\nilma extract archive.tar.zst     # Auto-detects compression format\nilma decrypt file.tar.zst.gpg    # Decrypts and decompresses in one pass\n```\n\n---\n\n## What ilma is and is not\n\n**ilma** is a shell wrapper around common file-handling tools. It is meant to create local or pulled snapshots that can be archived, encrypted, moved, and recovered without needing a custom repository format.\n\n**ilma** is **NOT** intended to be a deduplication or synchronization tool.\nThese tools offer better coverage for those tasks:\n\n- Recommended encrypted, deduplicated backups: [**restic**](https://restic.net/)\n- Recommended synchronization tool: [**syncthing**](https://syncthing.net/)\n\nBecause **ilma** is written as a shell wrapper for common file-handling tools, `ilma`-generated files are recoverable without needing `ilma` itself. Restic requires restic for recovery. Syncthing is synchronous, and opaque in the only place you get encryption: \"untrusted device\" mode.\n\n**ilma** works in addition to restic and syncthing for a complementary purpose. Restic efficiently backs up entire home directories with deduplication and versioning. Syncthing maintains synchronized state across devices. ilma can be used to create encrypted project snapshots for transport to untrusted storage.\n\nSince ilma can push to multiple destinations, additional encrypted archives can be placed in syncthing folders or backed up by restic alongside other data.\n\n### Backing up remote configs, databases, etc\n\nPull from remote machines (NAS, Raspberry Pi, servers) without running an SSH server on your local machine. Job manifests use rsync's filter syntax for selective transfer.\n\n```bash\nilma remote pull --job admin@server.ini\n```\n\nThe `--job` file is a manifest that can be made as exclusive or inclusive as you want. It **is** better to be as exclusive as you can here. An example:\n```ini\n[job]\nid=admin@server.ini\n...\n[manifest]\n+ .          # sync all non-hidden files in /home/admin\n- .*         # ignore all hidden files in /home/admin\n...\n+ .config/** # but DO sync .config/\n...\n+ .ssh/**    # and sync .ssh/\n...\n```\n\nRestic doesn't work in this direction. Most people do not run an SSH server on their laptop, but many do on their NAS. Android phones also have small file count limits, so pure syncs of server material become impractical. `ilma`'s job mode extracts an archive from a collection of remote paths and can zip and encrypt them for agnostic portability.\n\n## Development\n\n- [Contributing](docs/contributing.md)\n\n- [Changelog](docs/changelog.md)\n\n- [Roadmap](docs/roadmap.md)\n\n## License\n\n[GPLv3](https://www.gnu.org/licenses/gpl-3.0.en.html)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrege%2Filma","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrege%2Filma","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrege%2Filma/lists"}