termux-sync 1.1.0__tar.gz

termux_sync-1.1.0/CHANGELOG.md

@@ -0,0 +1,72 @@
+# Changelog
+
+All notable changes to termux-sync will be documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+Version numbers follow [Semantic Versioning](https://semver.org/).
+
+---
+
+## [Unreleased]
+
+### Planned
+
+- Archive encryption using a user-provided password
+- Selective restore (restore individual components instead of the full backup)
+- Backup rotation by date in addition to count-based pruning
+- Support for rclone remotes beyond Google Drive
+
+---
+
+## [1.1.0] - 2026-04-28
+
+### Added
+
+- `termux-sync check` — disk usage overview for Termux root, `~`, and `$PREFIX`; accepts an optional path argument (`check ~`, `check $PREFIX`, `check /custom/path`) with per-subfolder size breakdown
+- `termux-sync clear-cache` — interactive cache cleaner with two confirmation prompts before removing `$PREFIX/tmp`, `~/.cache`, `~/.npm`, `~/.cargo/registry`, and `~/.cargo/git`
+- `tsctl status` — show current installation status (script path, launcher, config directory, commit hash)
+- PyPI packaging support — `termux-sync` can now be installed via `pip install termux-sync` using the new `pyproject.toml`
+- GitHub Actions workflows: `ci.yml`, `codeql.yml`, `dependabot.yml`, `release-pypi.yml`
+- Automated PyPI publish on GitHub release via OIDC trusted publishing
+
+### Changed
+
+- GitHub storage chunk size increased from 20 MB to 200 MB per part, reducing the number of split files for large backups
+- `_write_daemon_script()` now resolves the script path dynamically using `__file__` instead of a hardcoded path — fixes daemon boot script when installed via `tsctl`
+- `tsctl install` now purges stale `termux-sync` aliases from `.bashrc` / `.zshrc` before writing the launcher, preventing conflicts with previous installations
+- `tsctl` shell configuration step no longer adds an alias — the `$PREFIX/bin` launcher is sufficient
+
+### Fixed
+
+- `termux-sync check` previously reported total Android filesystem size instead of Termux directory sizes
+- Stale alias from a previous install overriding the correct launcher in active shell sessions
+- Daemon boot script pointing to hardcoded development path (`~/files/project/termux-sync/termux-sync.py`)
+
+---
+
+## [1.0.0] - 2026-04-18
+
+Initial public release.
+
+### Added
+
+- `termux-sync backup` — creates a full backup of packages, home directory, `/usr/etc`, and shared libraries
+- `termux-sync restore` — interactive backup picker with SHA-256 integrity verification before extraction
+- `termux-sync list` — table view of all available backups with size and date
+- `termux-sync setup` — interactive configuration wizard for storage backend and credentials
+- `termux-sync schedule` — configure a daily auto-backup at a user-defined time
+- `termux-sync daemon` — background process that triggers scheduled backups
+- `termux-sync status` — shows current configuration and environment tool availability
+- `termux-sync logs` — displays recent log entries with color coding by level
+- Storage backend support: local filesystem, Google Drive (via rclone), GitHub private repository
+- Backup manifest (`manifest.json`) with checksums, package list, timestamp, and source paths
+- Compression options: `gz` (fast), `bz2` (balanced), `xz` (best compression)
+- Default exclusion patterns for cache directories, build artifacts, and media files
+- Configurable maximum backup count with automatic pruning of oldest backups
+- Persistent log file at `~/.config/termux-sync/sync.log`
+- Rich terminal UI with progress bars, panels, and tables
+- `install.sh` — local installer for manual setup from a cloned repository
+- `tsctl` — control tool for system-wide install, update, and uninstall via git clone
+- Termux:Boot integration via auto-generated daemon script at `~/.termux/boot/termux-sync-daemon.sh`
+- Graceful handling of Ctrl+C with cleanup of partial temporary files
+- Auto-install of `rich` dependency if not present on first run

termux_sync-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 termux-sync contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

termux_sync-1.1.0/PKG-INFO

@@ -0,0 +1,373 @@
+Metadata-Version: 2.4
+Name: termux-sync
+Version: 1.1.0
+Summary: Backup and restore your entire Termux environment across devices
+Project-URL: Homepage, https://github.com/djunekz/termux-sync
+Project-URL: Repository, https://github.com/djunekz/termux-sync
+Project-URL: Changelog, https://github.com/djunekz/termux-sync/blob/main/CHANGELOG.md
+Project-URL: Bug Tracker, https://github.com/djunekz/termux-sync/issues
+Author: djunekz
+License: MIT License
+        
+        Copyright (c) 2026 termux-sync contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: android,backup,restore,sync,termux
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Archiving :: Backup
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Requires-Dist: rich>=13.0.0
+Description-Content-Type: text/markdown
+
+# termux-sync
+
+Backup and restore your entire Termux environment across devices.
+
+[![Python 3.8+](https://img.shields.io/badge/python-3.8%2B-blue?style=flat-square)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green?style=flat-square)](LICENSE)
+[![Termux](https://img.shields.io/badge/Termux-compatible-brightgreen?style=flat-square)](https://termux.dev)
+
+termux-sync captures your installed packages, home directory, and configuration files into a portable backup that can be fully restored on any device. Backups can be stored locally, uploaded to Google Drive via rclone, or pushed to a private GitHub repository.
+
+---
+
+## Features
+
+| Feature | Description |
+|---|---|
+| Full backup | Packages, home directory, `/usr/etc` config, shared libraries |
+| Full restore | Archive extraction and package reinstallation in one command |
+| Local storage | Save backups on-device or to any mounted path |
+| Google Drive | Upload and retrieve via rclone |
+| GitHub private repo | Push and pull using a Personal Access Token (200 MB per part) |
+| Auto-backup | Built-in daily scheduler at a configurable time |
+| Disk check | View storage usage for any path with per-folder breakdown |
+| Cache cleaner | Interactive two-step confirmation before removing cache |
+| Checksum verification | SHA-256 integrity check performed on every restore |
+| Rich terminal UI | Colored progress bars, tables, and status panels |
+| Persistent logging | Full log written to `~/.config/termux-sync/sync.log` |
+
+---
+
+## Requirements
+
+```
+Python 3.8+
+python-pip
+tar (included in Termux)
+```
+
+Optional dependencies depending on which storage backend you use:
+
+- `rclone` — required for Google Drive (`pkg install rclone`)
+- `git` — required for GitHub storage (`pkg install git`)
+- `Termux:Boot` — required for auto-backup on device start (install from F-Droid)
+
+---
+
+## Installation
+
+### Option 1 — tsctl (recommended)
+
+`tsctl` is the control tool that handles installation, updates, and removal. It clones the repository to a stable location and sets up the `termux-sync` command system-wide.
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/djunekz/termux-sync/main/tsctl -o tsctl
+chmod +x tsctl
+bash tsctl install
+```
+
+> After installation, you can run `termux-sync` from anywhere
+
+### Option 2 — Manual (git clone)
+
+```bash
+pkg install python python-pip
+git clone https://github.com/djunekz/termux-sync ~/termux-sync
+cd ~/termux-sync
+pip install rich
+bash install.sh
+```
+
+> After installation, you can run `termux-sync` from anywhere
+
+---
+
+## Setup
+
+Run the interactive setup wizard before using termux-sync for the first time:
+
+```bash
+termux-sync setup
+```
+
+The wizard will ask you to choose a storage backend and provide any required credentials.
+
+### GitHub private repo (recommended)
+
+1. Create a private GitHub repository, for example `my-termux-backup`
+2. Go to Settings > Developer Settings > Personal Access Tokens > Tokens (classic)
+3. Generate a token with the `repo` scope
+4. Run `termux-sync setup` and select option 3 (GitHub)
+5. Enter your token and repository name in the format `username/repo`
+
+---
+
+## Command Usage
+
+### Run the setup wizard
+```bash
+termux-sync setup
+```
+
+### Create a backup
+```bash
+termux-sync backup
+termux-sync backup --label "before-new-phone"
+```
+
+### List all available backups
+```bash
+termux-sync list
+```
+
+### Restore from backup (interactive picker)
+```bash
+termux-sync restore
+```
+
+### Restore a specific backup by name
+```bash
+termux-sync restore --name termux_backup_20240415_143000
+```
+
+### Configure daily auto-backup
+```bash
+termux-sync schedule
+```
+
+### Check configuration and environment
+```bash
+termux-sync status
+```
+
+### View recent log entries
+```bash
+termux-sync logs
+termux-sync logs --lines 100
+```
+
+### Check disk usage
+```bash
+termux-sync check                              # overview: Termux root, ~, $PREFIX
+termux-sync check ~                            # home directory + subfolder breakdown
+termux-sync check $PREFIX                      # $PREFIX + subfolder breakdown
+termux-sync check /data/data/com.termux/files  # custom path
+```
+
+### Clear cache
+```bash
+termux-sync clear-cache
+```
+
+Removes: `$PREFIX/tmp`, `~/.cache`, `~/.npm`, `~/.cargo/registry`, `~/.cargo/git`
+
+> Two confirmation prompts before anything is deleted.
+
+---
+
+## Auto-Backup
+
+Configure a daily automatic backup:
+
+```bash
+termux-sync schedule
+```
+
+To run automatically when your device boots, install [Termux:Boot](https://f-droid.org/en/packages/com.termux.boot/) from F-Droid. The setup wizard writes the required boot script automatically:
+
+### View the generated boot script
+```bash
+cat ~/.termux/boot/termux-sync-daemon.sh
+```
+Or start the daemon manually in the current session
+
+```bash
+termux-sync daemon &
+```
+
+---
+
+## What Gets Backed Up
+
+| Component | Path | Description |
+|---|---|---|
+| Package list | `dpkg --get-selections` | All installed packages |
+| Home directory | `~` | Dotfiles, scripts, projects |
+| Termux config | `$PREFIX/etc` | sources.list, motd, and other config files |
+| Shared libraries | `$PREFIX/lib` | Libraries installed by Termux packages |
+
+The following paths are excluded from the home directory backup by default:
+
+`.cache`, `.npm`, `__pycache__`, `node_modules`, `.gradle`, `.android`, `.thumbnails`, `DCIM`, `Movies`, `Music`, `.local/share/Trash`, `.local/lib`, `.java`, `.m2`, `.ivy2`, `go/pkg`, `.rustup/toolchains`, `.cargo/registry`, `.cargo/git`
+
+You can add or remove exclusions in `~/.config/termux-sync/config.json`.
+
+---
+
+## Configuration File
+
+Location: `~/.config/termux-sync/config.json`
+
+```json
+{
+  "storage": "github",
+  "local_path": "~/termux-backups",
+  "gdrive_folder_id": "",
+  "github_token": "ghp_...",
+  "github_repo": "username/my-termux-backup",
+  "github_branch": "main",
+  "compression": "gz",
+  "exclude_patterns": [
+    ".cache", ".npm", "__pycache__", "node_modules", ".gradle",
+    ".android", ".thumbnails", "DCIM", "Movies", "Music",
+    ".local/share/Trash", ".local/lib", ".java",
+    ".m2", ".ivy2", "go/pkg", ".rustup/toolchains",
+    ".cargo/registry", ".cargo/git"
+  ],
+  "max_backups": 5,
+  "encrypt": false,
+  "encrypt_password": ""
+}
+```
+
+| Key | Default | Description |
+|---|---|---|
+| `storage` | `local` | Storage backend: `local`, `gdrive`, or `github` |
+| `local_path` | `~/termux-backups` | Path for local backups |
+| `gdrive_folder_id` | *(empty)* | Google Drive folder ID (leave empty for root) |
+| `github_token` | *(empty)* | GitHub Personal Access Token with `repo` scope |
+| `github_repo` | *(empty)* | Repository in `owner/repo` format |
+| `github_branch` | `main` | Branch to push backups to |
+| `compression` | `gz` | Compression type: `gz` (fast), `bz2` (balanced), `xz` (best) |
+| `max_backups` | `5` | Maximum number of backups to keep before pruning |
+| `encrypt` | `false` | Enable archive encryption (not yet implemented) |
+
+---
+
+## Backup Structure
+
+Each backup is a directory containing four files:
+
+```
+backups/
+└── termux_backup_20240415_143000/
+    ├── manifest.json       metadata, checksums, package list, source paths
+    ├── packages.txt        plain text package list for reference
+    ├── home.tar.gz         home directory archive
+    └── usr_etc.tar.gz      Termux config archive (/usr/etc)
+```
+
+The `manifest.json` file is read by the restore command to verify archive integrity via SHA-256 checksums before extracting anything.
+
+---
+
+## Migrating to a New Device
+
+On the old device, create a labeled backup:
+
+```bash
+termux-sync backup --label "migration"
+```
+
+### On the new device, install termux-sync and restore:
+
+Download and run tsctl
+```bash
+curl -fsSL https://raw.githubusercontent.com/djunekz/termux-sync/main/tsctl -o tsctl
+chmod +x tsctl
+bash tsctl install
+```
+
+Run setup with the same credentials as the old device
+```bash
+termux-sync setup
+```
+
+Restore the latest backup
+```bash
+termux-sync restore
+```
+
+The restore process will verify checksums, extract the archives, and reinstall all packages.
+
+---
+
+## Troubleshooting
+
+| Problem | Solution |
+|---|---|
+| `rclone not found` | Run `pkg install rclone` then `rclone config` to authenticate |
+| GitHub 401 error | Check that your token has the `repo` scope and has not expired |
+| Archive too large | Add paths to `exclude_patterns` in `config.json` |
+| Restore overwrites wrong path | Check the `source` field in the backup's `manifest.json` |
+| `termux-sync: command not found` | Run `tsctl install` or re-run `install.sh` |
+| Daemon does not start on boot | Verify that Termux:Boot is installed and has permission to run |
+| GitHub upload fails on large backup | Default chunk is 200 MB per part — add paths to `exclude_patterns` to reduce size |
+| Cache not cleared | Run `termux-sync clear-cache` and confirm both prompts |
+
+---
+
+## Project Structure
+
+```
+termux-sync/
+├── termux-sync.py    Main application (backup, restore, schedule, daemon, check, clear-cache)
+├── install.sh        Local installer for manual setup
+├── tsctl             Control tool (install, updater, uninstall, status via git clone)
+└── README.md         This file
+```
+
+---
+
+## Contributing
+
+Contributions are welcome. Please read [CONTRIBUTING](CONTRIBUTING.md) before opening a pull request.
+
+For bug reports and feature requests, use the GitHub issue tracker and follow the provided templates.
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for the full text.