Git(Hub)-Box Agent (ghb)

A lightweight Box-like file synchronization agent that uses Git as the backend for version control and remote synchronization with automatic file compression capabilities.

Note

This was mostly "vibe coded using free tools", but it is functional. Impressive what AI can do! 😀

⚡ Quick Start (5 Minutes)

For experienced users or those who want to get started immediately:

# 1. Install Git (if not already installed)
git --version

# 2. Install .NET SDK and build the app (outputs into bin folder)
dotnet build -c Release

# 3. Start watching a folder (auto-commit + push)
ghb autocommit "C:\Your\Folder"

# That's it! Your files are now syncing automatically.

For GitHub sync (recommended):

# Automatically creates a new private repository on GitHub
# and connect it to the MyGitbox folder, and then start watching...
# NOTE: createrepo requires GitHub CLI (gh) to be installed!

ghb createrepo MyGitbox
ghb autocommit MyGitbox

For complete beginners: Read the detailed guide below.

🚀 Getting Started (Complete Beginner's Guide)

This guide will walk you through setting up Box Agent from scratch, even if you've never used Git or GitHub before.

What You'll Need

1. .NET SDK (to build this application)
2. Git(Hub) Box Agent (this application; a.k.a. ghb)
3. Git (for version control)
4. GitHub Account (optional, for remote backup and sync)

• GitHub CLI (gh) (recommended for easier creation of GitHub repositories - enables ghb createrepo)

Step 1: Install Git

Windows

1. Download Git from git-scm.com/download/win
2. Run the installer with default settings
3. Open Command Prompt and verify installation:

   git --version

GitHub CLI (Optional but Recommended)

For easier creation of GitHub repositories directly from the tool:

On Windows:

1. Download from cli.github.com
2. Or install via winget: winget install --id GitHub.cli
3. Authenticate: gh auth login

On macOS:

brew install gh
gh auth login

On Linux:

# Ubuntu/Debian
sudo apt install gh

# Fedora
sudo dnf install gh

# Then authenticate
gh auth login

For macOS

1. Install Git via Homebrew:

   brew install git

2. Or download from git-scm.com

For Linux

# Ubuntu/Debian
sudo apt update && sudo apt install git

# Fedora/CentOS
sudo dnf install git

Step 2: Create a GitHub Account (Optional but Recommended)

GitHub provides free cloud storage for your repositories and allows you to:

• Access your files from anywhere
• Share files with others
• Keep automatic backups
• Sync across multiple devices

Creating a GitHub Account

1. Sign up for GitHub
2. Choose the free plan (perfect for personal use)
3. Complete the registration process
4. Verify your email address

Benefits of GitHub Free Plan

• Unlimited public repositories - Share with anyone
• Unlimited private repositories - Keep files private
• Unlimited collaborators - Work with others
• 2000 free CI/CD minutes per month - For advanced users

Step 3: Install Box Agent

1. Download or clone this project:

   git clone https://github.com/Cheatoid/ghb
   cd ghb

2. Build the application:

   dotnet build -c Release

3. Verify installation (run from bin folder):

   ghb
   
   # OR
   
   dotnet run -- --help

   Note: Remember to add C:\path\to\gbh\bin folder to your system's PATH environment variable - this would allow you to run ghb directly on command-line:

   On Windows, you can do this by using this command:

• setx /M PATH "%PATH%;C:\path\to\gbh\bin"

On Unix, you can do this by using this command:

• export PATH=$PATH:/path/to/gbh/bin

Step 4: Set Up Your First Repository

Option A: Local Repository Only (No GitHub)

Perfect for personal file synchronization on one computer.

1. Choose a folder you want to sync:

   # Example: Documents folder
   cd C:\Users\YourName\Documents

2. Initialize with Box Agent:

   # Replace with your actual Box Agent path
   ghb init "C:\Users\YourName\Documents"

3. Start watching the folder:

   ghb autocommit "C:\Users\YourName\Documents"

That's it! Your files are now being tracked and will sync automatically.

Option B: GitHub Repository (Recommended)

Perfect for accessing files from anywhere and automatic cloud backup.

Recommended: Use ghb createrepo (requires GitHub CLI)

The easiest way — creates a GitHub repo and sets up your local folder in one step:

# Create private repo on GitHub, initialize local folder, and connect them
ghb createrepo my-documents

# Start watching a folder (auto-commit + push)
ghb autocommit my-documents

See the createrepo command section for more options (public/private, descriptions, etc.).

Alternative: Manual setup via GitHub website

If you prefer not to install GitHub CLI, you can create the repository manually:

1. Create a new repository on GitHub:

• Go to github.com and log in
• Click the "+" icon in the top-right corner
• Select "New repository"
• Repository name: Choose a descriptive name (e.g., "my-documents")
• Description: Optional but helpful (e.g., "Personal documents and files")
• Visibility: Choose "Private" for personal files
• Don't initialize with README, .gitignore, or license (Box Agent will handle this)
• Click "Create repository"

2. Copy the repository URL:

• GitHub will show you options like "HTTPS" or "SSH"
• Copy the HTTPS URL (it looks like: https://github.com/username/repo-name)

3. Set up your local folder:

   # Navigate to the folder you want to sync
   cd C:\Users\YourName\Documents

4. Initialize with Box Agent and connect to GitHub:

   # Initialize the folder
   ghb init "C:\Users\YourName\Documents"
   
   # Add the GitHub remote using git
   git remote add origin "https://github.com/username/repo-name"

5. Start watching (auto-commit + push):

   ghb autocommit "C:\Users\YourName\Documents"

Step 5: Verify Everything Works

1. Create a test file in your watched folder:

• Open your Documents folder
• Create a new text file called "test.txt"
• Write something in it and save

2. Check the output - Box Agent should show:

   File changed: test.txt
   Changes pushed to remote.
   

3. Verify on GitHub (if using GitHub):

• Go to your repository on github.com
• You should see "test.txt" in your repository

Step 6: Advanced Setup (Optional)

Multiple Folders

Use separate repository folders for different locations:

# Initialize and watch multiple folders as separate repos
ghb init "C:\Users\YourName\Pictures"
ghb autocommit "C:\Users\YourName\Pictures"

ghb init "C:\Users\YourName\Projects"
ghb autocommit "C:\Users\YourName\Projects"

# List tracked files in a repository
ghb list

System Tray (Windows Only)

Not currently implemented. Run ghb autocommit in a terminal or use ghb monitor to watch for unpushed commits.

Symlink Folders

Not currently implemented. Use git clone to sync folders across different locations.

📁 What Happens Behind the Scenes

When you set up Box Agent:

1. Git Repository: Creates a hidden .git folder for version control
2. Initial Commit: Commits all current files to the repository
3. Remote Connection: If using GitHub, connects your local folder to cloud storage
4. File Watcher: Monitors folder for changes
5. Auto Sync: Automatically commits and pushes changes

🔧 Troubleshooting Common Issues

"Git not found" Error

Solution: Install Git from Step 1 and restart your terminal. Verify with:

git --version

"Authentication failed" when pushing to GitHub

Solution: Set up GitHub authentication:

# Method 1: Use GitHub CLI (recommended)
gh auth login

# Method 2: Use Git credential manager
git config --global credential.helper manager

"Permission denied" Error

Solution: Check folder permissions and run as administrator if needed

📱 Using on Multiple Devices

To sync the same folder across multiple computers:

1. Set up GitHub repository (Step 4B)
2. On each computer:

   # Clone the repository
   git clone https://github.com/username/repo-name
   cd repo-name
   
   # Start watching
   ghb autocommit .

3. Files will sync automatically across all devices

🎯 Next Steps

Now that you're set up:

1. Explore commands: Try ghb --help to see all options
2. Set up multiple folders: Add other important folders as separate repos
3. Use monitor: Watch for unpushed commits with ghb monitor

🆘 Need Help?

• Check logs: Look in %AppData%\ghb\logs for detailed error messages
• Verify Git: Run git --version to ensure Git is installed
• Test connection: Try git push manually to test GitHub connectivity
• Check permissions: Ensure Box Agent can read/write to your folders

Features

• File System Watching: Uses Windows FileSystemWatcher API for efficient file change detection
• Git Integration: Automatic commits and pushes to keep files synchronized
• Command Line Interface: Simple CLI for managing the watcher and repository
• Debounced Changes: Prevents excessive commits during rapid file changes
• Smart Filtering: Ignores temporary files and Git metadata

Installation

1. Clone or download this project

2. Build the application:

   dotnet build

   Note: The ghb executable is built into the bin\ folder in the project root.

3. Run the application:

   # From the bin folder
   .\bin\ghb.exe [command] [options]
   
   # Or add to PATH and run directly
   ghb [command] [options]

Usage

Commands

init

Initialize a git repository.

ghb init [path]

• path: Path to initialize repository (default: current directory)

Example:

# Initialize current directory
ghb init

# Initialize specific folder
ghb init "C:\MyGitbox"

clone

Clone a repository (recursive by default).

ghb clone <url> [path]

• url: Repository URL to clone (required)
• path: Destination path (default: repo name from URL)

Example:

# Clone to folder named after repo
ghb clone https://github.com/user/repo.git

# Clone to specific folder
ghb clone https://github.com/user/repo.git "C:\MyGitbox"

createrepo

Create a GitHub repository (smart: new folder or existing). Requires GitHub CLI (gh).

ghb createrepo <name> [--public] [--description <description>]

• --public: Create a public repository (default: private)
• --description: Repository description

Examples:

# Create a private repository (default)
ghb createrepo my-project

# Create a public repository
ghb createrepo my-project --public

# Create with description
ghb createrepo my-project --public --description "My awesome project"

autocommit

Start watching a folder for changes and automatically commit and push to Git.

ghb autocommit [path]

• path: Directory to watch (default: current directory)

Example:

# Watch current directory
ghb autocommit

# Watch a specific folder
ghb autocommit "C:\MyGitbox"

watch

Start watching a folder for changes (legacy simple watcher, does not auto-push).

ghb watch [path]

• path: Directory to watch (default: current directory)

Example:

# Watch current directory
ghb watch

# Watch a specific folder
ghb watch "C:\MyGitbox"

Note: For auto-commit and push functionality, use ghb autocommit instead.

monitor

Monitor for unpushed commits and notify when commits need to be pushed.

ghb monitor [path]

• path: Directory to monitor (default: current directory)

Example:

# Monitor current directory
ghb monitor

# Monitor specific folder
ghb monitor "C:\MyGitbox"

sync

Manually synchronize with the remote repository (pull, commit, push).

ghb sync [path]

• path: Directory to sync (default: current directory)

status

Show the current repository status.

ghb status [path]

• path: Directory to check status (default: current directory)

list

List tracked files in the repository.

ghb list [path]

• path: Directory to list files (default: current directory)

How It Works

1. Initialization: If the target folder isn't a Git repository, use ghb init to create one
2. File Watching: ghb autocommit monitors the specified folder for file changes (create, modify, delete, rename)
3. Debouncing: Groups rapid file changes to avoid excessive commits
4. Auto-Commit: When changes are detected, it automatically stages and commits them
5. Auto-Push: Pushes commits to the remote repository if configured

File Filtering

The agent automatically ignores:

• Git files (.git, .gitignore, .gitattributes)
• Temporary files (*.tmp, *.temp)
• Editor files (*.swp, *.swo, *~)
• System files (.DS_Store, Thumbs.db)
• Files in .git directories

Examples

Basic Usage

# Start watching current directory with auto-commit + push
ghb autocommit

# Watch a specific folder
ghb autocommit "C:\Documents\SyncFolder"

# Simple watch without auto-push (legacy mode)
ghb watch "C:\Documents\SyncFolder"

# Check repository status
ghb status

# List tracked files
ghb list

Setup Remote Repository

# Initialize repository
ghb init

# Add GitHub repository as remote using git
git remote add origin "https://github.com/user/my-sync-repo.git"

# Initial sync
ghb sync

# Start auto-commit watching
ghb autocommit

Clone and Watch

# Clone repository
git clone https://github.com/user/my-sync-repo.git
cd my-sync-repo

# Start watching
ghb autocommit

System Tray Feature

Note: System tray feature is not currently implemented. Use ghb autocommit to run the watcher in a terminal window, or ghb monitor to watch for unpushed commits.

Requirements

• .NET 10.0
• Windows (uses Windows FileSystemWatcher API)
• Git (for version control)
• GitHub CLI (optional, for creating GitHub repositories with ghb createrepo)

Notes

• The agent requires proper Git credentials to be configured for push/pull operations
• Large files may take longer to sync depending on network speed
• The agent handles Git conflicts gracefully but may require manual resolution in some cases
• Press Ctrl+C to stop the watcher when running in autocommit or watch mode

Security

• The agent uses your configured Git credentials for authentication
• Ensure your remote repository has proper access controls
• Consider using SSH keys for more secure authentication