GitHub Replicant (Rust CLI)

GitHub Replicant is a high-performance Rust CLI for bulk GitHub repository backup and sync. It can clone or pull a user's own public repositories, starred repositories, watched repositories, and repositories discovered through followers or following lists.

This development repository is named GitHub-Replicant-rs, and the compiled CLI executable is github-backup-rs.

Start here in 30 seconds

git clone https://github.com/ThalesMMS/GitHub-Replicant-rs.git
cd GitHub-Replicant-rs
cargo run -- torvalds

That first run:

• syncs torvalds non-fork repositories by default
• writes them under output/torvalds/
• uses unauthenticated GitHub API requests unless you export GITHUB_TOKEN

If you want a release binary instead of cargo run, build it with cargo build --release and use ./target/release/github-backup-rs.

Example output layout after a successful run:

output/
└── torvalds/
    ├── linux/
    ├── subsurface/
    └── uemacs/

Features

• Async & Concurrent: Uses tokio and futures to perform multiple git operations simultaneously (cloning/pulling).
• Smart Sync: Automatically detects if a repository exists to decide between git clone and git pull.
• Filtration: Option to include or exclude forked repositories (excludes forks by default).
• Visual Feedback: Real-time progress bar using indicatif.
• Starred/Network Backup: Sync repositories you starred, watching, from the accounts you follow, or from your followers.

Installation

Ensure you have Rust and Cargo installed.

git clone https://github.com/ThalesMMS/GitHub-Replicant-rs.git
cd GitHub-Replicant-rs
cargo build --release

The binary will be available at target/release/github-backup-rs.

Quickstart

./target/release/github-backup-rs torvalds

Running ./target/release/github-backup-rs torvalds downloads torvalds repositories into the local output/torvalds/ directory.

Usage

You can run the tool directly via cargo run or using the compiled binary.

⚠️ Unauthenticated GitHub API calls are limited (60 requests/hour) and may fail on large syncs. Use GITHUB_TOKEN for authenticated requests to avoid 403 rate limit errors.

cargo run -- <USERNAME> [OPTIONS]
./target/release/github-backup-rs <USERNAME> [OPTIONS]

Common options:

Flag	Description
--stars	Sync repositories the user has starred
--following	Sync repositories from users this profile follows
--followers	Sync repositories from this profile's followers
--watching	Sync repositories the user is watching
--include-forks	Include forked repositories in synchronization
--token <TOKEN>	GitHub token for authenticated API requests
-c, --concurrency <N>	Maximum number of concurrent git operations
--output-dir <PATH>	Base directory for sync output
--exact-mirror	Remove local repos not returned by the current GitHub query within the selected destination tree
--force	Force update existing repositories, discarding local changes and divergent history

Basic Usage

Backup all non-forked repositories for a user (for example, torvalds):

cargo run -- torvalds
# or
./target/release/github-backup-rs torvalds

Starred Repositories

Backup all repositories a user has starred:

cargo run -- torvalds --stars

Repositories from Following

Backup repositories from every account a user follows:

cargo run -- torvalds --following

Repositories from Followers

Backup repositories from every account that follows the user:

cargo run -- torvalds --followers

Watched Repositories

Backup all repositories a user is watching (subscriptions):

cargo run -- torvalds --watching

Include Forks

To also backup forked repositories:

cargo run -- torvalds --include-forks

Adjust Concurrency

By default, the tool processes 8 repositories in parallel. You can adjust this with --concurrency (or -c):

cargo run -- torvalds -c 16

Custom Output Directory

By default, repositories are written under output/<mode-specific-name>:

cargo run -- torvalds
# writes to output/torvalds/

Use --output-dir to choose a different absolute or relative base directory. The mode-specific subfolder is still appended to that base path:

cargo run -- torvalds --output-dir /Volumes/Backups/github
# writes to /Volumes/Backups/github/torvalds/

cargo run -- torvalds --output-dir backups/github
# writes to backups/github/torvalds/

Authenticated Requests (avoid rate limits)

1. Create a GitHub token (fine-grained or classic) with at least public_repo or no scopes for public data.
2. Export it so the CLI picks it up automatically:

   export GITHUB_TOKEN=<your-token>

   Or pass inline:

   cargo run -- torvalds --token <your-token>

3. Run your command (example with following):

   cargo run -- torvalds --following

   Authenticated mode raises the rate limit and avoids 403 Forbidden when syncing many users.

Force Update Divergent Repos

If a repository has diverged or has local changes, force-reset to the upstream branch:

cargo run -- torvalds --force

Exact Mirror (remove stale repos)

To delete local repositories not returned in the current query (e.g., stars you unstarred), opt into exact mirroring:

cargo run -- torvalds --stars --exact-mirror

When used with --output-dir, exact mirroring only removes stale repositories inside the selected destination tree. For example, cargo run -- torvalds --stars --exact-mirror --output-dir /Volumes/Backups/github only prunes under /Volumes/Backups/github/torvalds-stars/.

Output

Repositories are downloaded to an output directory relative to the directory from which you run the command unless you pass --output-dir <PATH> to override this default. Folder naming depends on the mode you run:

• Own repositories: output/<username>
• Starred: output/<username>-stars
• Following: output/<username>-following
• Followers: output/<username>-followers
• Watching: output/<username>-watching

With --output-dir /Volumes/Backups/github, those same mode-specific folders are created under /Volumes/Backups/github/, such as /Volumes/Backups/github/torvalds/ or /Volumes/Backups/github/torvalds-stars/.

When cloning repositories that belong to other owners (e.g., starred repos or repos from followers/following), they are organized under a nested owner folder to avoid name collisions:

output/<username>/<owner>/<repo-name>

Repositories belonging to <username> stay in output/<username>/<repo-name> as before.

Notes & Edge Cases

• DMCA takedown: repositories blocked by GitHub are skipped with a warning and do not fail the run.
• Default branch changes: if the remote default branch renamed and a pull fails, the tool automatically re-clones that repo to match the new default branch.

---

Folder Compression Tool

A separate binary to compress backed-up folders into individual .zip files.

Usage

Compress immediate child folders:

cargo run --bin compress-folders -- --input output/ThalesMMS

This compresses each folder directly inside output/ThalesMMS into its own .zip file.

Compress at a deeper level (recursive):

cargo run --bin compress-folders -- --input output/ThalesMMS-following --recursive 1

This compresses folders one level deeper — e.g., all folders inside output/user-following/user1/, all folders inside output/user-following/user2/, etc.

Options

Flag	Description
-i, --input <PATH>	Target folder containing directories to compress (required)
-r, --recursive <N>	Depth level: 0 = immediate children (default), 1 = grandchildren, etc.

License

This project is licensed under the MIT License - see the LICENSE file for details.