$$$$$$\  $$\   $$\ $$$$$$$\   $$$$$$\  $$\   $$\  $$$$$$\           $$$$$$\   $$$$$$\  
$$  __$$\ $$ |  $$ |$$  __$$\ $$  __$$\ $$$\  $$ |$$  __$$\         $$  __$$\ $$  __$$\ 
$$ /  \__|$$ |  $$ |$$ |  $$ |$$ /  $$ |$$$$\ $$ |$$ /  $$ |        $$ /  $$ |$$ /  \__|
$$ |      $$$$$$$$ |$$$$$$$  |$$ |  $$ |$$ $$\$$ |$$ |  $$ |$$$$$$\ $$ |  $$ |\$$$$$$\  
$$ |      $$  __$$ |$$  __$$< $$ |  $$ |$$ \$$$$ |$$ |  $$ |\______|$$ |  $$ | \____$$\ 
$$ |  $$\ $$ |  $$ |$$ |  $$ |$$ |  $$ |$$ |\$$$ |$$ |  $$ |        $$ |  $$ |$$\   $$ |
\$$$$$$  |$$ |  $$ |$$ |  $$ | $$$$$$  |$$ | \$$ | $$$$$$  |         $$$$$$  |\$$$$$$  |
 \______/ \__|  \__|\__|  \__| \______/ \__|  \__| \______/          \______/  \______/ 
 

chrono-os backup-io

chrono-os backup-io is a Linux-first backup assistant that helps users scan selected home folders, archive files to a local backup device, and keep a metadata trail in a private GitHub repository. It is built in Go with a Bubble Tea TUI and focuses on safe, repeatable backups and restores across common Linux distributions.

Project aims

• Make backups fast to configure and repeat for everyday Linux users.
• Keep sensitive file data on local devices by default.
• Preserve enough metadata for reliable, auditable restores.
• Provide a consistent workflow across major Linux distributions.

Features

• Select which home folders are included in scans and backups.
• Ignore file types by extension (stored and reused).
• Optional archive compression (.tar or .tar.gz).
• External drive detection and free-space checks before backup.
• Package inventory capture by distro and optional restore selection.
• Private GitHub metadata publishing via the GitHub CLI.
• Restore workflow with overwrite policy.

Requirements

• Linux (x86_64 recommended)
• Go 1.22+
• GitHub CLI (gh) for metadata publishing
• lsblk for drive detection
• git for metadata repository creation

Install

go mod tidy

Run

go run ./cmd/backup-io

How it works

1. Select folders to scan (home directory only).
2. Run a scan to build a file manifest.
3. Select a backup drive.
4. Run a backup to create an archive on the drive.
5. Publish metadata to a private GitHub repo (optional).
6. Restore by selecting a backup and confirming overwrite policy.

Metadata and storage

• Archives are written to the selected drive under mcbackup/.
• Metadata lives in ~/.mcbackup and is included in each archive.
• GitHub publishing uploads only metadata and configuration files, not archives.

Configuration files

~/.mcbackup contains:

• scan.json (latest manifest)
• history.json (backup history)
• packages.json (installed package list)
• packages-selected.json (explicit restore selection)
• ignore.json (ignored file extensions)
• folders.json (selected home folders)

Restore behavior

• Restore unarchives to the original relative paths under your home directory.
• You choose whether to overwrite existing files.
• Package restore uses only the explicitly selected list.
• On Arch Linux, restore auto-installs yay and configures chaotic-aur.

Security model

• File data stays on local backup media unless you choose to upload it separately.
• GitHub metadata repositories are created as private.
• sudo is required only for package install operations during restore.

Troubleshooting

• GitHub auth errors: run gh auth login and retry.
• Repo creation fails: ensure git is installed and gh is logged in.
• No drives detected: verify the drive is mounted and lsblk is available.
• Package restore fails: check your distro package manager and sudo access.

FAQ

Does GitHub store my backup archives? No. GitHub stores only metadata and configuration files.

Can I back up only specific folders? Yes. Use “Select folders to scan” in the TUI.

What happens if the drive is too small? Backups will be blocked before writing if free space is insufficient.

Can I restore without a backup drive? Only metadata can be fetched from GitHub. The archive must be available locally.

Contributing

Issues and pull requests are welcome. Please include a clear description of changes and any relevant testing notes.

Support

Open an issue with logs and your distro/version details.