repo-do

A unified CLI tool for managing git repositories with a structured directory layout. Organize all your repositories in a consistent domain-based structure. Fast search, clipboard integration, and cross-platform support.

English · 简体中文

Overview

repo-do helps you organize all your git repositories in a consistent, domain-based directory structure. It automatically clones repositories to organized paths and provides fast search capabilities to find and navigate to your projects.

Features

• Structured Organization: Clone repositories to {baseDir}/{domain}/{group}/{repo} structure
• Fast Repository Search: Quickly find repositories by name or path fragments
• Clipboard Integration: Automatically copy cd commands to clipboard
• Cache-Based Performance: Fast repository listing without repeated directory scans
• Existing Repository Detection: Track existing clones by remote URL and reuse them before cloning duplicates
• Multi-Location Tracking: Keep multiple local directories for the same remote repository when needed
• Cross-Platform: Works on Windows, macOS, and Linux
• Git Clone Pass-through: Support all git clone arguments (--depth, --branch, etc.)

Installation

npm install -g repo-do

Command aliases: rpd and repo-do are equivalent. The examples below prefer the shorter rpd alias.

Quick Start

1. Initialize Configuration

rpd init

This prompts you to set a base directory for storing repositories (default: ~/.repo-do/repo).

2. Clone a Repository

rpd add [email protected]:STDSuperman/super-image-cropper.git

The repository will be cloned to:

{baseDir}/github.com/STDSuperman/super-image-cropper

The cd command is automatically copied to your clipboard!

3. Find a Repository

rpd find super-image

Output:

Found 1 repository:
1. D:\Code\github.com\STDSuperman\super-image-cropper

4. List All Repositories

rpd list

Output:

github.com/STDSuperman/super-image-cropper
github.com/STDSuperman/NanoBanana-PPT-Skills
gitlab.com/myorg/internal-tool

Total: 3 repositories

Commands

rpd init / repo-do init

Initialize configuration and set the base directory for repositories.

rpd init

rpd add <repo_url> [git-clone-args...] / repo-do add <repo_url> [git-clone-args...]

Clone a repository to the structured directory.

Supported URL formats:

• HTTPS: https://github.com/user/repo.git or https://github.com/user/repo
• SSH: [email protected]:user/repo.git or ssh://[email protected]/user/repo.git

Examples:

# Basic clone
rpd add [email protected]:STDSuperman/super-image-cropper.git

# Shallow clone
rpd add https://github.com/STDSuperman/super-image-cropper.git --depth 1

# Clone specific branch
rpd add https://github.com/STDSuperman/super-image-cropper.git --branch develop

# SSH clone
rpd add [email protected]:STDSuperman/NanoBanana-PPT-Skills.git

# JSON output (for scripts and AI models)
rpd add https://github.com/user/repo.git --json

# Force a new clone even if the same remote is already tracked
rpd add https://github.com/user/repo.git --force-clone

# Use an already tracked local repository without prompting
rpd add https://github.com/user/repo.git --use-existing

Before cloning, repo-do checks the global repository configuration for the same remote repository. SSH and HTTPS remotes such as [email protected]:user/repo.git and https://github.com/user/repo are treated as the same repository. If a matching repository already exists in another local directory, interactive mode asks whether to use the existing directory. --json mode uses the existing directory automatically unless --force-clone is provided.

--json output:

When using --json, the command outputs a single line of JSON to stdout with no spinner, color, or clipboard side effects:

{"success":true,"path":"/path/to/repo","alreadyExists":false,"message":""}

| Field | Type | Description | |-------|------|-------------| | success | boolean | true if the repo path is available (cloned or already exists) | | path | string | Absolute path to the local repository | | alreadyExists | boolean | true if the repository was already cloned | | adoptedExisting | boolean | true if an existing repository in a different location was used | | message | string | Error or status message |

On failure, the process exits with code 1 and outputs:

{"success":false,"path":"","alreadyExists":false,"message":"error details"}

Directory structure:

{baseDir}/
├── github.com/
│   └── STDSuperman/
│       ├── super-image-cropper/
│       └── NanoBanana-PPT-Skills/
└── gitlab.com/
    └── myorg/
        └── internal-tool/

rpd find <query> / repo-do find <query>

Search for repositories by name, group, or path fragment (case-insensitive).

rpd find super-image
rpd find STDSuperman
rpd find github.com

Output format:

Found 2 repositories:
1. D:\Code\github.com\STDSuperman\super-image-cropper
2. D:\Code\github.com\STDSuperman\NanoBanana-PPT-Skills

Each result is prefixed with a number, followed by the absolute path.

rpd list [--refresh] / repo-do list [--refresh]

List all managed repositories.

# List from cache (fast)
rpd list

# Force rebuild cache
rpd list --refresh

When --refresh is used, repo-do scans the configured base directory, records detected Git repositories in configuration, and rebuilds the fast repository cache.

rpd scan [paths...] / repo-do scan [paths...]

Scan existing Git repositories and track them in configuration.

# Scan the configured base directory
rpd scan

# Scan one or more custom directories
rpd scan ~/Code ~/work

Detected repositories are grouped by normalized remote URL. If the same remote exists in multiple local directories, all directories are stored as locations for that repository.

rpd remove <repo> / repo-do remove <repo>

Remove a repository from tracking (does not delete files).

rpd remove super-image

If multiple matches are found, you'll be prompted to select which one to remove.

rpd config [options] / repo-do config [options]

View or modify configuration.

# Show current config
rpd config

# Get base directory
rpd config --get baseDirectory

# Set base directory
rpd config --set baseDirectory /path/to/repos

Directory Structure

All repositories are organized in a consistent structure:

{baseDirectory}/{domain}/{group}/{repository}

Examples:

| Git URL | Cloned Path | |---------|-------------| | [email protected]:STDSuperman/super-image-cropper.git | {baseDir}/github.com/STDSuperman/super-image-cropper | | [email protected]:myorg/myrepo.git | {baseDir}/gitlab.com/myorg/myrepo | | https://github.com/STDSuperman/NanoBanana-PPT-Skills.git | {baseDir}/github.com/STDSuperman/NanoBanana-PPT-Skills |

Configuration

Configuration is stored in ~/.repo-do/config.json:

{
  "baseDirectory": "D:\\Code",
  "version": "1.0.0",
  "repositories": [
    {
      "id": "github.com/STDSuperman/super-image-cropper",
      "canonicalRemote": "github.com/STDSuperman/super-image-cropper",
      "displayUrl": "[email protected]:STDSuperman/super-image-cropper.git",
      "domain": "github.com",
      "group": "STDSuperman",
      "name": "super-image-cropper",
      "preferredPath": "D:\\Code\\github.com\\STDSuperman\\super-image-cropper",
      "locations": [
        {
          "path": "D:\\Code\\github.com\\STDSuperman\\super-image-cropper",
          "remoteUrl": "[email protected]:STDSuperman/super-image-cropper.git",
          "remoteName": "origin",
          "source": "clone",
          "firstSeenAt": "2026-01-11T12:00:00.000Z",
          "lastSeenAt": "2026-01-11T12:00:00.000Z"
        }
      ]
    }
  ]
}

Cache System

To improve performance, repo-do maintains a repository cache at ~/.repo-do/repo_cache.json.

Cache is automatically updated when:

• Adding a new repository (rpd add / repo-do add)
• Removing a repository (rpd remove / repo-do remove)
• Forcing refresh (rpd list --refresh / repo-do list --refresh)

Cache format:

{
  "repositories": [
    {
      "name": "super-image-cropper",
      "fullPath": "D:\\Code\\github.com\\STDSuperman\\super-image-cropper",
      "gitUrl": "[email protected]:STDSuperman/super-image-cropper.git",
      "domain": "github.com",
      "group": "STDSuperman",
      "lastUpdated": "2026-01-11T12:00:00.000Z"
    }
  ],
  "lastUpdated": "2026-01-11T12:00:00.000Z"
}

Cross-Platform Support

Clipboard Support

• macOS: Uses pbcopy
• Linux: Uses xclip or xsel (may require installation)
• Windows: Uses clip command

If clipboard fails, the path is still displayed in the terminal.

Path Handling

All paths are handled using Node.js path module for cross-platform compatibility.

Requirements

• Node.js >= 18.0.0
• Git installed and available in PATH

Error Handling

repo-do provides clear error messages for common issues:

• INVALID_URL: Git URL format not recognized
• CLONE_FAILED: Git clone operation failed
• CONFIG_ERROR: Configuration file read/write error
• NOT_FOUND: Repository not found in cache
• PERMISSION_DENIED: File system permission error
• GIT_NOT_INSTALLED: Git is not installed
• PATH_CONFLICT: Target path exists but is not the requested repository

Development

# Clone the repository
git clone https://github.com/your-username/repo-do.git
cd repo-do

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build
npm run build

# Run tests
npm test

Project Structure

repo-do/
├── src/
│   ├── commands/        # CLI command implementations
│   ├── core/            # Core business logic
│   ├── utils/           # Utility functions
│   ├── types/           # TypeScript type definitions
│   ├── constants/       # Constants
│   └── index.ts         # CLI entry point
├── bin/
│   └── repo-do.js         # Executable entry
├── dist/                # Compiled output
└── tests/               # Test files

Dependencies

• chalk: Terminal text styling
• clipboardy: Cross-platform clipboard operations
• commander: CLI framework
• inquirer: Interactive command line prompts
• ora: Elegant terminal spinner

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Changelog

1.0.0

• Initial release
• Core functionality: init, add, list, find, remove, config
• Cross-platform support
• Cache system for fast repository listing