🥔 Farmore

"Mirror every repo you own — in one command."

Farmore is a comprehensive Python CLI tool for backing up GitHub repositories and their associated data. Clone repositories, export issues, download releases, backup wikis, and more — all with a single command.

Version: 0.10.1 License: MIT Python: 3.10+

---

✨ Features

🔄 Repository Management

• Bulk backups - Clone all repos for a user or organization in one command
• Single repo backups - Backup individual repositories with the repo command
• Repository search - Search GitHub and clone matching repositories by keyword
• Smart updates - Automatically pulls updates for existing repositories
• Parallel processing - Fast backups with configurable worker threads
• SSH/HTTPS support - Tries SSH first, falls back to HTTPS with token
• Bare/Mirror clones - Use --bare flag for true 1:1 repository backups
• Git LFS support - Use --lfs flag for repositories with large files
• Name regex filtering - Filter repositories by name pattern with --name-regex
• Incremental backups - Track backup state with --incremental flag

📊 Data Export

• Issues export - Export all issues to JSON/YAML with optional comments
• Pull requests export - Export PRs with metadata and comments
• Workflows backup - Backup GitHub Actions workflows and run history
• Releases download - Download releases with metadata and binary assets
• Wiki backup - Clone repository wikis as git repositories
• Labels export - Backup repository labels with colors
• Milestones export - Backup milestone configuration and progress
• Gists backup - Clone all your GitHub gists
• Attachments download - Download images/files from issues and PRs

🔐 Access & Security

• Private repository support - Full access with GitHub Personal Access Tokens
• Organization repos - Backup all organization repositories
• Starred & watched repos - Mirror repositories you've starred or are watching
• Secrets export - Export repository secret names (values are never exposed)
• Followers/Following - Export user's social connections
• Webhooks export - Backup webhook configurations

🎯 Advanced Features

• Flexible filtering - By visibility (public/private/all), forks, archived status
• Rate limit handling - Automatic retries with exponential backoff
• Organized structure - Clean directory organization separating code from data
• Cross-platform - Works on Linux, macOS, and Windows
• Beautiful CLI - Powered by Typer and Rich with progress bars
• GitHub Enterprise - Support for custom API endpoints via --api-url / GITHUB_API_URL
• Discussions backup - Export repository discussions (GraphQL API)
• Projects backup - Export Projects v2 data (GraphQL API)

---

📦 Installation

Requirements

Python Version: 3.10 or higher is required.

Additional Requirements:

• Git installed and available in PATH
• GitHub Personal Access Token (for private repos and higher rate limits)

---

🎯 From PyPI (Recommended)

The easiest way to install Farmore is from the Python Package Index (PyPI):

pip install farmore

This is the recommended method for end users. Once installed, the farmore command will be available globally.

Verify installation:

farmore --version
farmore --help

---

🧪 From TestPyPI (Pre-release Testing)

To test pre-release versions before they're published to PyPI:

pip install --index-url https://test.pypi.org/simple/ farmore

When to use this:

• Testing new features before official release
• Helping with beta testing
• Verifying bug fixes in development versions

Note: TestPyPI packages may not have all dependencies available. You might need to install dependencies from regular PyPI separately.

---

📥 From GitHub Releases (Specific Versions)

Download a specific version from the GitHub Releases page:

1. Download the .whl file from the release you want (e.g., farmore-0.3.0-py3-none-any.whl)
2. Install the downloaded file:

pip install farmore-0.3.0-py3-none-any.whl

When to use this:

• You need a specific version
• You want to verify package integrity
• You're installing in an offline environment (download first, install later)

Alternative - Source distribution:

# Download the .tar.gz file instead
pip install farmore-0.3.0.tar.gz

---

🔧 From Source (Development)

For developers who want to contribute or modify the code:

# Clone the repository
git clone https://github.com/miztizm/farmore.git
cd farmore

# Install in editable mode (changes to code take effect immediately)
pip install -e .

# Or install with development dependencies (recommended for contributors)
pip install -e ".[dev]"

Development dependencies include:

• pytest - Testing framework
• pytest-cov - Code coverage
• ruff - Linting and formatting
• mypy - Type checking
• Additional testing utilities

Verify installation:

farmore --version
farmore --help

---

🔄 Upgrading

To upgrade to the latest version:

# From PyPI
pip install --upgrade farmore

# From TestPyPI
pip install --upgrade --index-url https://test.pypi.org/simple/ farmore

---

🗑️ Uninstalling

To remove Farmore:

pip uninstall farmore

---

🚀 Quick Start

# Backup all repos for a user
farmore user miztizm

# Backup a single repository
farmore repo microsoft/vscode

# Search and clone repositories by keyword
farmore search "nuxt laravel" --limit 10

# Backup with issues and pull requests
farmore repo miztizm/hello-world --include-issues --include-pulls

# Backup everything for a repository
farmore repo python/cpython --all

# Backup all repos for an organization
farmore org github --include-issues --include-pulls

# With authentication (recommended)
export GITHUB_TOKEN=ghp_your_token_here
farmore user miztizm

"They say privacy is dead. Prove them wrong. Use a token." — schema.cx

---

🔑 Authentication

Farmore uses GitHub Personal Access Tokens (PAT) for authentication. Tokens provide:

• Access to private repositories
• Higher rate limits (5,000 vs 60 requests/hour)
• Organization repository access

Creating a Token

⭐ Recommended: Use Classic Personal Access Token

1. Create a Classic PAT: https://github.com/settings/tokens

   • Click "Tokens (classic)" → "Generate new token (classic)"
   • Give it a name: farmore-backup
   • Select scope: ✅ repo (required for private repositories)
   • Optional: ✅ delete_repo (only if using farmore delete command)
   • Click "Generate token" and copy it immediately

2. Set environment variable:

# Linux/macOS
export GITHUB_TOKEN=ghp_your_token_here

# Windows PowerShell
$env:GITHUB_TOKEN="ghp_your_token_here"

# Or create a .env file in the project directory
echo "GITHUB_TOKEN=ghp_your_token_here" > .env

Why Classic PAT?

• ✅ Simple setup (just check repo scope)
• ✅ Works with all repository types (personal + organization)
• ✅ Proven reliability
• ✅ Broader API compatibility

Rate Limits

| Mode | Requests/Hour | Use Case | |------|---------------|----------| | ❌ Unauthenticated | 60 | Small public repos only | | ✅ Authenticated | 5,000 | Production, private repos |

Security Best Practices

• ✅ Use environment variables or .env files
• ✅ Set token expiration (90 days recommended)
• ✅ Use minimal required permissions
• ❌ Never commit tokens to version control
• ❌ Avoid --token flag (exposes in shell history)

---

🏢 GitHub Enterprise Support

Farmore supports GitHub Enterprise Server and GitHub Enterprise Cloud with custom data residency.

Using Custom API Endpoint

For GitHub Enterprise instances with local data residency (e.g., https://api.orgname.ghe.com):

# Using environment variable (recommended)
export GITHUB_API_URL="https://api.orgname.ghe.com"
export GITHUB_TOKEN="ghp_your_token_here"
farmore user myusername

# Or using CLI flag
farmore user myusername --api-url "https://api.orgname.ghe.com"

Legacy Hostname Support (Deprecated)

The --github-host flag is still supported for backward compatibility but is deprecated:

# This is deprecated, use --api-url instead
farmore user myusername --github-host "github.mycompany.com"

Configuration Priority

When both options are provided, the priority is:

1. --api-url / GITHUB_API_URL (preferred)
2. --github-host / GITHUB_HOST (legacy, auto-constructs API URL)
3. Default: https://api.github.com

Examples

# GitHub Enterprise Cloud with data residency
export GITHUB_API_URL="https://api.acme.ghe.com"
export GITHUB_TOKEN="ghp_enterprise_token"
farmore org acme-corp --include-all

# GitHub Enterprise Server
farmore user john --api-url "https://github.internal.company.com/api/v3"

# All commands support the --api-url option
farmore gists --api-url "https://api.enterprise.ghe.com"
farmore search "machine learning" --api-url "https://api.enterprise.ghe.com"

SSH Setup for GitHub Enterprise

When using SSH with GitHub Enterprise, ensure the host key is in your known_hosts:

# Add the GitHub Enterprise host key
ssh-keyscan -H acme.ghe.com >> ~/.ssh/known_hosts

# Or manually clone once to accept the host key
ssh -T git@acme.ghe.com

If you encounter "Host key verification failed", you can either:

1. Add the host key as shown above
2. Use HTTPS instead of SSH with --use-ssh=false

---

📚 Commands

Farmore provides 14 commands organized into 4 categories:

🔄 Repository Backup

farmore user <username>

Backup all private and public repositories for a GitHub user.

# Backup all repos
farmore user miztizm

# Backup with data exports
farmore user miztizm --include-issues --include-pulls

# Filter b