A project backup and archival tool with selective project-type awareness, pruning, encryption, and remote synchronization.
-
Project-Type Awareness
Automatic detection and application of appropriate exclusions for Python, Node.js, LaTeX, Bash projects, with extensibility for any project with build and runtime artifacts.
-
Standard GPG, tar, and rsync core with ergonomic CLI
GPG encryption for secure transport and storage. Create context mirrors of projects (working tree without git artifacts, node_modules, build outputs) for LLM interaction or quick archival
-
Prune per-project build artifacts on archival
Can be easily configured to automatically remove disposable files and directories based on a per-project or recursive cleanup task, logging events and creating backups for recovery.
-
ilma --help. All subcommands support--help. -
Immediate Backup
By default, ilma will backup the current directory and store a copy as a sibling.
cd my-project ilma -a # archive tree -L1 .. .. ├── my-project └── my-project.tar.zst
Or, you can specify a directory to backup, archive, or encrypt.
ilma -e ~/Documents/love-letters/ tree -L1 ~/Documents ~/Documents ├── love-letters └── love-letters.tar.zst.gpg
Prune crufty project files
All the disposable files and directories can be easily removed with the prune command,
based on project type or project-local configuration files.
ilma prune ~/dissertation \
--type latex \ # remove build artifacts .aux, .toc, etc
--log \ # log to ~/dissertation.log
--bak # backup to ~/dissertation.bakSend encrypted archive to remote server
ilma --encrypt \
--remote server.local:/storage/backups \
--type latex \
~/dissertation
ssh server.local ls /storage/backups
# dissertation.tar.zst.gpgConfig Validation
ilma validate
Context Overview
Generate a token estimate of project context before and after pruning
ilma console --type [node|python|latex|bash]Clone the repository
git clone https://github.com/brege/ilma
cd ilma
./installFedora dependencies
sudo dnf install rsync tree git zstd bc pv
# compression tools (configure: you only need one)
sudo dnf install zstd gzip bzip2 xzDebian/Ubuntu dependencies
sudo apt install rsync tree git zstd bc pv
sudo apt install zstd gzip bzip2 xz-utilsValidate dependencies
ilma validate --dependenciesNote
Compression Algorithms
The default compression library used in this project is Zstandard (zstd). This is a personal choice, which I use because of good performance on Btrfs filesystems. Zstandard is also the algorithm restic uses. 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.
Sources: compression, speed, usage
ilma works out of the box with sensible defaults, but can be customized extensively.
Copy and customize the global config.ini file
cp config.example.ini config.iniCreate .ilma.conf in any project for custom strategies.
See configs/local/dot-ilma.conf.example for a kitchen sink example.
| Supported Project Types | Common Exclusions |
|---|---|
| python | __pycache__, venv, .pytest_cache, etc. |
| node | node_modules, dist, build, etc. |
| latex | .aux, .log, .pdf, etc. |
| bash | .log, .tmp, .out, backup files, etc. |
See configs/ for common language presets.
cd /path/to/project
ilma # Backup current directory
ilma [PROJECT_PATH] # Backup specified directory
ilma -a --verify # Archive and verify contents
ilma -e --verify --remote srv:/dst # Encrypt, upload, and verify remote hashCreate context mirrors for LLM interaction by excluding git history, build artifacts, and dependency directories. Snapshots current working state including uncommitted and untracked files without git ceremony.
ilma console [PROJECT_PATH] # Show detailed project statistics
ilma scan [PROJECT_PATH] # Show files that would be excluded
ilma scan --type python --pretty # Scan with specific project typeAfter customizing your configuration, you can validate your setup quickly without trial-and-error on your data.
ilma validate # Basic configuration validation
ilma validate --full # Includes remote + dependency checks
ilma validate --remote # Remote connectivity + manifest lintingOutput your current configuration at any time, in or outside of a project.
ilma config [PROJECT_PATH] # Show resolved configurationGPG encryption for secure transport to untrusted or exposed storage. Extract and decrypt commands auto-detect compression formats and use chunked processing for efficiency.
ilma extract archive.tar.zst # Auto-detects compression format
ilma decrypt file.tar.zst.gpg # Decrypts and decompresses in one passilma is an over-engineered wrapper. It is intended to backup irreplaceable things like configs, databases, pictures, presentations, etc on the go. I use ilma to quickly create archives from local and remote work, take them on the go securely, and recover them when needed. Often, I run ilma -a .git when I know I may mess something up in the Git tree or before performing a dangerous find+sed+{} on a codebase (the archive protects string replacements affecting .git/ files).
ilma is NOT intended to be a deduplication or synchronization tool. These tools offer better coverage for those tasks:
Because ilma is written as a shell wrapper for common file-handling tools, ilma-generated files are completely recoverable without needing ilma. Restic requires restic for recovery. Syncthing is synchronous, and opaque in the only place you get encryption: "untrusted device" mode.
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.
Since ilma can push to multiple destinations, additional encrypted archives can be placed in syncthing folders or backed up by restic alongside other data.
Pull 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.
ilma remote pull --job admin@server.iniThe --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:
[job]
id=admin@server.ini
...
[manifest]
+ . # sync all non-hidden files in /home/admin
- .* # ignore all hidden files in /home/admin
...
+ .config/** # but DO sync .config/
...
+ .ssh/** # and sync .ssh/
...Restic 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.