GHRapt

Rapture your files in to the github cloud ☁️✨

Because your files deserve a one-way trip to Microsoft's finest servers

📦 Installation

pip install ghrapt

☕ Support

If you find this project helpful, consider supporting me:

🚀 Quick Start

# Set your GitHub token
export GH_TOKEN=your_github_token

# Push files to a repository
ghrapt --repo username/repo-name ./path/to/files

# Or with a commit message
ghrapt --repo username/repo-name --message "My backup" ./docs

🎯 Why GHRapt?

• One-way backup to the cloud - perfect for backups
• No Git commands needed - just push your files
• No .git folder - keeps your working directory clean
• Minimal disk writes - no local Git database to maintain
• Directory overlay support - merge multiple directories

⚠️ Limitations

• GitHub API rate limits apply
• Optimized for small files
• Not a replacement for full Git version control

Features

• 📁 Tree-based file management - Work with files and directories as a hierarchical tree structure
• ☁️ GitHub as storage backend - Store files using GitHub's Git Data API
• 🔄 Push & Pull - Upload local files to GitHub or download existing trees
• 📝 Commit support - Create commits with custom messages and parent references
• 🚫 Gitignore integration - Respect .gitignore patterns during upload
• 🔗 Symbolic link handling - Configurable strategies for symlinks (keep/follow/safe)
• 📊 File filtering - Filter by size, ignore patterns, and more

Installation

pip install ghrapt

Configuration

GHRapt requires GitHub authentication. Set the following environment variables:

export GH_REPO="owner/repository-name"
export GH_TOKEN="your_github_token"
export GH_USER="your_username"        # optional
export GH_EMAIL="your_email@example.com"  # optional

Or use a config file at ~/.config/ghrapt.conf or ~/ghrapt.conf:

[owner/repo]
token = your_github_token
email = your_email@example.com

Usage

Command Line Interface

# Upload files to GitHub
ghrapt --repo owner/repo --act /path/to/files

# Upload with commit message
ghrapt -R owner/repo -a -m "Initial commit" ./docs

# Dry run (default)
ghrapt -R owner/repo ./src

# Upload with size filter
ghrapt -R owner/repo --maxsize 1048576 ./files

# Control symlink behavior
ghrapt -R owner/repo --links safe --dir-links follow ./data

Python API

from ghrapt import GHRapt

# Initialize client
api = GHRapt()
api.set_repo("owner/repo")
api.use_logging()

# Place local files into the tree
api.place("./myfiles", root="project")

# Push to GitHub
api.push(dry_run=False)

# Commit changes
api.commit(message="Added my files", dry_run=False)

# Pull existing content
api.pull(ref="master")
api.ls()  # List contents

File Operations

# Remove files
api.rm("file.txt", "old_dir/")

# Rename/move
api.ren("old_name.txt", "new_name.txt")

# List tree contents
api.ls()

# Place files at specific root
api.place("./assets", root="static/images")

How It Works

GHRapt builds an in-memory tree structure representing your files, then pushes them to GitHub using the Git Data API:

1. Walk - Scan local directories and build a GHNode tree
2. Push - Upload blobs, trees, and symlinks to GitHub
3. Commit - Create a commit referencing the root tree SHA
4. Update ref - Update the branch reference to point to the new commit

Tree Structure

• GHNode - Tree node containing name and data
• GHDirData - Directory node with children
• BlobData - File content (supports streaming for large files)
• SymlData - Symbolic link
• GHObject - Remote GitHub object for pulling

Commands Reference

Command	Description
pull(ref)	Download tree from GitHub
push()	Upload local tree to GitHub
place(paths)	Add local files to tree
commit(message)	Create commit from current tree
ls()	List tree contents
rm(paths)	Remove files from tree
ren(old, new)	Rename/move files

Advanced Options

Push Options

• stream=True - Stream large files instead of loading into memory
• pause_sec=N - Add delay between uploads (rate limiting)
• dry_run=False - Actually push (default is dry run)

Place Options

• follow_links="keep/follow/safe" - How to handle file symlinks
• follow_dir_links="keep/follow/safe" - How to handle directory symlinks
• gitignore_ancestors=True - Respect parent .gitignore files
• maxsize=N - Skip files larger than N bytes
• overwrite=True - Overwrite existing files

Commit Options

• parent_commit_sha - Specify parent commit
• ref_path - Branch reference (e.g., refs/heads/main)
• create_ref - Create new branch if it doesn't exist

Status

Alpha - Under active development. APIs may change.

Dependencies

• requests - HTTP client for GitHub API
• PyYAML - YAML output formatting