gitlo

• 🔐 Secure - Token stored locally in ~/.gitlo/config.json
• 🍴 Fork Support - Optionally backup forked repositories
• 🔒 Private Repos - Backs up private repositories with proper token
• ⏰ Auto-Schedule - Built-in cron scheduler for automatic backups
• 📊 Progress Tracking - Visual progress with spinners and stats
• 🚀 Fast - Only updates changed repos with --update flag
• 📝 Logging - Full logs of backup operations
• 🎯 Dry Run - Preview what will be backed up without downloading

GitHub accounts can be deleted, suspended, or compromised. This tool creates a local backup of all your repositories so you always have a copy of your work.

npm install -g gitlo

• Node.js >= 18.0.0
• Git installed on your system

# Clone and build
git clone https://github.com/dropocol/gitlo.git
cd gitlo
npm install
npm run build

# Link globally
npm link --global

npm install -g gitlo

gitlo works with either type of GitHub personal access token:

Classic token (simplest):

1. Go to GitHub Settings → Tokens
2. Click "Generate new token (classic)"
3. Select scopes: ☑️ repo and ☑️ read:user
4. Generate and copy the token

Fine-grained token (more control):

1. Go to GitHub Settings → Tokens
2. Click "Generate new token" → "Fine-grained token"
3. Set Repository permissions: Contents = Read and write, Metadata = Read-only
4. (Optional) Account permissions: User profile = Read-only
5. Choose repositories (or "All repositories"), then generate and copy

Note: Fine-grained tokens can't read GitHub's private-repo counter, so gitlo's "owned repos" total may look lower than expected. All your accessible private repos are still backed up — the number is just a display quirk.

gitlo

That's it. With no arguments, gitlo opens a guided menu that walks you through everything — including setting your token on the first run:

🗄️  gitlo - GitHub Backup Tool

What would you like to do?
  1. 🔄  Run a backup now
  2. ⚙️  Configure settings (token / output directory / branch strategy)
  3. 📅  Schedule automatic backups
  4. 👀  View current configuration
  5. ⬆️  Update gitlo
  6. 🚪  Exit
>

Pick "Run a backup now" and gitlo will:

• Prompt for your GitHub token if you haven't set one (and save it for next time)
• Ask your preferences (clone method, forks, private repos, dry-run, branch strategy)
• Show a summary for confirmation, then back up everything

You can return to the menu anytime to configure settings, schedule automatic backups, or update gitlo.

First run tip: If you haven't configured a token yet, the menu will offer to set one up when you pick "Run a backup now" — or you can configure it upfront via "Configure settings" → "Set GitHub token".

The easiest way to use gitlo. Run gitlo with no arguments and the menu guides you through every option with sensible defaults and inline validation:

• 🔄 Run a backup now — walks through clone method, forks/private filtering, dry-run, and branch strategy, then confirms before starting
• ⚙️ Configure settings — set/get/remove your token, output directory, and branch strategy
• 📅 Schedule automatic backups — set up, list, or remove scheduled backups with a guided frequency/time/day picker
• 👀 View current configuration — see your current token (masked), output directory, and branch strategy
• ⬆️ Update gitlo — check for and install the latest version

Tip: Any flag or subcommand skips the menu and runs directly. For example gitlo --include-forks, gitlo config list, and gitlo schedule setup all run without prompting.

Prefer the terminal? Every option in the interactive menu is also available as a CLI command. These are for power users or scripting/automation.

# Save your token
gitlo config set token ghp_xxxxxxxxxxxx

# Optional: set backup directory and branch strategy
gitlo config set output-dir ~/backups/github
gitlo config set branch-strategy all

# Back up all your repos (syncs ALL branches by default)
gitlo --update

# Include forks too
gitlo --include-forks

# Preview without downloading
gitlo --dry-run

# Daily at 3 AM
gitlo schedule setup --frequency daily --time 03:00

# Weekly on Monday at 2 AM
gitlo schedule setup --frequency weekly --day 1

Full command reference below.

Run the backup with configured settings.

Manage gitlo configuration settings (token, output directory, branch strategy).

Schedule automatic backups with cron (built-in scheduler).

Update gitlo to the latest version from npm. Runs npm install -g gitlo@latest for you.

gitlo automatically checks for new versions in the background (at most once per day) and shows a banner when an update is available. You'll never be left on an outdated version without knowing it.

# Update to the latest version
gitlo update

# Or manually
npm install -g gitlo@latest

You can also update from the interactive menu — run gitlo (no args) and choose "⬆️ Update gitlo".

The update check is non-blocking, cached daily, and only displays in an interactive terminal (never in CI/scripts). It queries the public npm registry directly — no new dependencies.

gitlo [options]

Options:

• -t, --token <token> - GitHub personal access token
• -o, --output-dir <dir> - Output directory for backups
• -m, --method <method> - Clone method: https or ssh (default: https)
• --include-private - Include private repositories (default: true)
• --exclude-private - Exclude private repositories
• --include-forks - Include forked repositories (default: false)
• --dry-run - Show what would be backed up without cloning
• --update - Update existing repositories with git pull
• -b, --branch-strategy <strategy> - When updating: default (sync default branch only) or all (sync every branch). (default: all)
• -v, --verbose - Show detailed progress and filtering information
• -V, --version - Display the installed gitlo version
• -h, --help - Display help

When a repo already exists locally and you run with --update, gitlo fetches all branches' history either way (nothing is lost). The branch strategy controls how much of that is synced into the working tree:

• **all** (default) — Checks out and fast-forwards every branch so each one's files are up to date on disk. Most complete; recommended for backups since the whole point is to never lose access to your code.
• **default** — Fast-forwards only the repo's default branch (e.g. main). Faster; useful if you have repos with many branches and only care about the main one.

# Update existing repos — syncs ALL branches by default
gitlo --update

# Sync only the default branch (faster)
gitlo --update --branch-strategy default

# Set it permanently via config
gitlo config set branch-strategy all

First-time clones always fetch every branch and the full history, regardless of strategy. The strategy only affects how existing repos are updated.

By default, gitlo does not backup forked repositories. If you have forks you want to backup, use --include-forks:

# Backup everything including forks
gitlo --include-forks

# Backup only your own repos (no forks) - this is the default
gitlo

Set a configuration value.

gitlo config set token <github-token>
gitlo config set output-dir <path>
gitlo config set branch-strategy <default|all>

Examples:

# Set your GitHub token
gitlo config set token ghp_xxxxxxxxxxxx

# Set default backup directory
gitlo config set output-dir ~/backups/github-repos

# Use ~ for home directory (automatically expanded)
gitlo config set output-dir ~/Documents/GitHub-Backups

# Set branch strategy for updating existing repos
gitlo config set branch-strategy all

View a specific configuration value.

gitlo config get token
gitlo config get output-dir
gitlo config get branch-strategy

Output:

• Token is masked for security (shows: ghp_****xxxx)
• Output-dir shows the full path
• Branch-strategy shows default or all

List all configuration values.

gitlo config list

Output:

📋 gitlo Configuration

  token: ghp_****xxxx
  output-dir: /Users/username/backups/github-repos
  branch-strategy: all

Config file: /Users/username/.gitlo/config.json

Remove a configuration value.

gitlo config remove token
gitlo config remove output-dir
gitlo config remove branch-strategy   # resets to default

Schedule automatic backups with cron.

# Weekly on Sunday at 2 AM (default, updates existing repos)
gitlo schedule setup

# Daily at 3 AM
gitlo schedule setup --frequency daily --time 03:00

# Weekly on Monday at 2 AM
gitlo schedule setup --frequency weekly --day 1

# Monthly on the 1st at 2 AM
gitlo schedule setup --frequency monthly

# Full backup (clone all repos, don't just update)
gitlo schedule setup --full

View scheduled backup jobs.

gitlo schedule list

Remove automatic backup schedule.

gitlo schedule remove

1. CLI argument: gitlo -t TOKEN
2. Environment variable: GITHUB_TOKEN
3. Config file: gitlo config set token TOKEN

1. CLI argument: gitlo -o ~/my-backups
2. Config file: gitlo config set output-dir ~/backups
3. Default: your GitHub username as folder name

Don't want to save anything? Pass the token inline:

# Using environment variable
export GITHUB_TOKEN=your_token_here
gitlo

# Using CLI argument
gitlo -t your_token_here

# Dry run to preview what will be backed up
gitlo --dry-run

# Backup to specific directory (overrides config)
gitlo -o ~/backups/my-github-repos

# Use SSH for cloning (requires SSH key setup)
gitlo -m ssh

# Only public repos, no forks
gitlo --exclude-private

# Include forks
gitlo --include-forks

# Update existing backups (syncs ALL branches by default)
gitlo --update

If you want to contribute or modify the code:

# Install all dependencies (including dev)
npm install

# Build TypeScript to JavaScript
npm run build

# Run in development mode
npm run dev

# Clean build artifacts
npm run clean

# Test local changes globally
npm link --global

When you're ready to publish to npm:

# The prepublishOnly script automatically builds before publishing
npm publish

• ✅ All your repositories (public by default)
• ✅ Private repositories (if --include-private)
• ✅ Forks (if --include-forks)
• ✅ Full git history and all branches
• ⚠️ Issues, PRs, and wiki pages are NOT included (only git repos)

your-backup-directory/
├── repo-1/
│   └── .git/
├── repo-2/
│   └── .git/
└── repo-3/
    └── .git/

gitlo has a built-in scheduler to automatically backup your repos:

# Setup weekly backups (default: Sundays at 2 AM)
# By default, updates existing repos (faster)
gitlo schedule setup

# Setup daily backups at 3 AM
gitlo schedule setup --frequency daily --time 03:00

# Setup weekly on Mondays at 2 AM
gitlo schedule setup --frequency weekly --day 1 --time 02:00

# Full backup (clone all repos including new ones)
gitlo schedule setup --full

# View scheduled jobs
gitlo schedule list

# Remove scheduled backups
gitlo schedule remove

• -f, --frequency <freq> - hourly, daily, weekly, monthly (default: weekly)
• -t, --time <time> - Time in HH:MM format (default: 02:00)
• -d, --day <day> - Day of week 0-6 for weekly (0=Sunday, default: 0)
• --full - Clone all repos instead of just updating existing (default: update)
• -l, --log <path> - Log file path (default: ~/.gitlo/backup.log)

Note: By default, scheduled backups update existing repositories for faster execution. Use --full to clone all repositories including new ones.

If you prefer manual setup:

# Edit crontab
crontab -e

# Add line to backup weekly (Sundays at 2 AM)
0 2 * * 0 /usr/local/bin/gitlo --update >> /var/log/gitlo.log 2>&1

npm install -g gitlo && gitlo config set token YOUR_TOKEN && gitlo

cd ~ && git clone https://github.com/dropocol/gitlo.git && cd gitlo && npm install && npm run build && npm link --global && echo "Setup complete. Run: gitlo config set token YOUR_TOKEN"

• Your GitHub token is stored in ~/.gitlo/config.json on your local machine
• The token is masked when displayed (shows: ghp_****xxxx)
• Keep your config file secure - it contains your GitHub token!
• Use file permissions to protect the config: chmod 600 ~/.gitlo/config.json

If gitlo reports fewer repositories than you have on GitHub, it's likely due to filtering:

1. Forks are excluded by default

# Check if you have forks being skipped
gitlo --dry-run

# Include forks in backup
gitlo --include-forks

2. Private repos might be excluded

# By default, private repos ARE included
# But if you used --exclude-private:
gitlo --include-private

3. Use verbose mode to see what's being filtered

# See detailed information about fetching and filtering
gitlo -v

Your token is invalid or expired. Generate a new one at https://github.com/settings/tokens

Make sure you have SSH keys set up:

ssh-keygen -t ed25519 -C "your@email.com"
ssh-add ~/.ssh/id_ed25519
# Add public key to GitHub: https://github.com/settings/keys

The tool handles pagination automatically. If you have 1000+ repos, it may take a while.

MIT