GitHub: appotry/PTtool
Pure Shell / Python hardlink tools. Works on Linux, BSD, macOS, Synology, QNAP and any OS with a standard POSIX shell.
This project was fully refactored with opencode, implementing an AI Agent-driven dev-test loop: requirements → architecture → coding → Docker testing → knowledge base archiving, all completed autonomously by the Agent. See AGENTS.md and docs/.
- Language Selection
- Design Rationale
- Problems Solved
- Usage Guide
- mklink.sh
- dirlink.sh
- Adjusting the Size Threshold
- autolink.sh
- Caveats
- Disclaimer
- Contributing
Script output language is controlled by the SCRIPT_LANG environment variable (defaults to system LANG):
# English output
SCRIPT_LANG=en_US ./dirlink.sh /src /dst
# Chinese output (default)
./dirlink.sh /src /dstrename_episodes.py also supports SCRIPT_LANG.
Allow PT users to hardlink files, saving maximum space while keeping torrents seeding. Files < 1MB are copied directly (lets scrapers like emby/tmm modify nfo files). Files > 1MB are hardlinked to the destination (renameable but read-only).
Example:
/share/Download/src — PT download directory
/share/Download/dst — Scraper directory (point emby/tmm here)
After downloading, run chmod +x mklink.sh. Set SRC and DST in the script or pass as arguments, then run.
SRC="/share/Download/src"
DST="/share/Download/dst"Note:
SRC and DST must be on the same filesystem — hardlinks cannot cross partitions.
Use
mvon hardlinked files, notcp—cpduplicates storage.
When tmm/emby scrape metadata, they modify nfo files and download different cover images per source. Small files are copied so modifications don't affect the originals. Large files are hardlinked to save space — multiple paths point to the same underlying data, which is only freed when ALL hardlinks are deleted.
Use /share/Download as the download root. qBittorrent saves categorized torrents to subdirectories under /share/Download/src/ (tv, anime, movie, 4k, etc.).
Create /share/Download/dst/ and use src and dst as script inputs.
Small files are copied (allows tmm to modify nfo). Large files are hardlinked (one copy of data, two file entries — renameable and movable). Seeding and emby work simultaneously.
/share/Download/src # Default BT download directory
/share/Download/dst # Hardlink destination for Emby/tmm
Create subdirectories under src (movie, music, anime, tv, 4k), configure them as qBittorrent categories. After download, run the hardlink scripts. Point emby/tmm to dst for scraping.
- Move torrent save location: Right-click a torrent in the qBittorrent web UI → Save location
- Set category directories: Right-click → Category → New category → set name and path. For multi-file torrents, enable automatic management. For single-file torrents, add subdirectories manually.
One-shot hardlink from source to destination. Files < 1MB are copied (allows scraper modifications). Files > 1MB are hardlinked (saves space, two file entries share one data copy).
No idempotency check. Best for fresh, unlinked directories.
# mklink.sh sourcedir dstdir
mklink.sh /share/Download/tmp/src /share/Download/tmp/dstIdempotent hardlink per subdirectory, tracked via islinked.lk marker files.
If a marker exists, the subdirectory is skipped. If not, files are hardlinked and the marker is created.
Set SRC and DST in the script or pass as command-line arguments ($1, $2).
SRC="/share/Download/tmp/src/movie"
DST="/share/Download/tmp/dst/movie"Note: Source content must be organized in subdirectories (e.g., src/anime/anime1, src/tv/tv2) for islinked.lk to work correctly.
# dirlink.sh sourcedir dstdir
dirlink.sh /share/Download/tmp/src /share/Download/tmp/dstfind /share/Download/tmp -name "islinked.lk" | xargs rm -fReplace the path with your own. Be extremely careful — mistakes with rm are costly!
Example in link.sh:
#!/bin/sh
/path/to/dirlink.sh /share/Download/src/anime /share/Download/dst/anime
/path/to/dirlink.sh /share/Download/src/movie /share/Download/dst/movie
/path/to/dirlink.sh /share/Download/src/tv /share/Download/dst/tvSet FILEGIG in the script (default 1000000c = 1 MB). In find's -size option: c = bytes, k = kilobytes, M = megabytes, G = gigabytes.
Size conversions: 1 KB = 1024 bytes, 1 MB = 1024 KB, 1 GB = 1024 MB.
FILEGIG=2000000c # 2 MB
FILEGIG=10M # 10 MB
FILEGIG=100M # 100 MBqBittorrent completion hook. Auto-hardlinks newly completed torrents by category. For existing torrents, use link.sh instead.
- Set target directory: Edit
your_pathin the script. - Configure qBittorrent: Tools → Options → Downloads → "Run external program on torrent completion"
/path/to/autolink.sh "%N" "%D" "%L"
autolink.shanddirlink.shmust be in the same directory.
All categories are linked automatically — no need to edit category lists in the script. To exclude specific categories, set EXCLUDE_CATEGORIES in the script.
- Check file permissions if errors occur. The target directory must be writable!
Data is precious, operate with care. These scripts (except autolink.sh) only use mkdir and cp — no rm. At worst you may clutter your filesystem. Do not set the destination to a system directory. Use at your own risk.
- Fork it (https://github.com/appotry/PTtool/fork)
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - Create a new Pull Request