📁 gclone

🚀 Smart Git Repository Cloner - Clone repositories into organized directory structures with parallel processing

✨ Why gclone?

Ever tired of manually creating nested directories for your Git repositories? gclone automatically organizes your repos into a clean, predictable structure that mirrors the repository's URL path, with blazing-fast parallel processing.

~/src/
├── github.com/
│   ├── golang/go/
│   ├── kubernetes/kubernetes/
│   └── juev/gclone/
├── gitlab.com/
│   └── company/project/
└── bitbucket.org/
    └── team/service/

🚀 Key Features

⚡ Parallel Processing - Clone multiple repositories simultaneously with configurable workers
🎯 Zero Configuration - Works out of the box with sensible defaults
📂 Organized Structure - Mirrors repository URLs in your filesystem
🔒 Security First - Comprehensive URL validation and path sanitization
💾 Smart Caching - Intelligent directory existence checking with LRU cache
🌊 Shallow Clones - Optional --depth=1 for faster clones
🛡️ Graceful Shutdown - Handles interrupts cleanly with signal handling
🤫 Quiet Mode - Suppress output when needed
🐚 Shell Integration - Perfect for scripts and aliases

📦 Installation

go install github.com/juev/gclone@latest

🔧 Quick Start

Basic Usage

# Set your preferred projects directory
export GIT_PROJECT_DIR="$HOME/src"

# Clone a single repository
gclone https://github.com/golang/go.git
# Result: ~/src/github.com/golang/go/

# Clone multiple repositories in parallel
gclone https://github.com/golang/go.git \
       https://github.com/kubernetes/kubernetes.git \
       https://gitlab.com/company/project.git

# Fast shallow clone
gclone --shallow https://github.com/large/repository.git

Advanced Usage

# Use 8 parallel workers for faster cloning
gclone -w 8 \
  https://github.com/repo1/project.git \
  https://github.com/repo2/project.git \
  https://github.com/repo3/project.git

# Quiet mode for scripts
gclone --quiet --shallow https://github.com/user/repo.git

# Chain with other commands
cd "$(gclone https://github.com/user/repo.git)"
code "$(gclone --quiet https://github.com/user/repo.git)"

💡 Command Line Options

gclone [-h] [-v] [-q] [-s] [-w WORKERS] [REPOSITORY...]

Options:
  -h, --help         Show this help message and exit
  -v, --version      Show the version number and exit
  -q, --quiet        Suppress output
  -s, --shallow      Perform shallow clone with --depth=1
  -w, --workers      Number of parallel workers (default: 4, max: 32)

Environment Variables:
  GIT_PROJECT_DIR    Directory to clone repositories (default: current dir)

Examples:
  GIT_PROJECT_DIR="$HOME/src" gclone https://github.com/user/repo
  gclone -w 8 https://github.com/user/repo1 https://github.com/user/repo2

🎨 Shell Integration

Bash/Zsh Functions

# Clone and cd into repository
gcd() {
    cd "$(gclone "$1")"
}

# Clone and open in VS Code
gcode() {
    code "$(gclone "$1")"
}

# Clone and open in your editor
gedit() {
    $EDITOR "$(gclone "$1")"
}

# Bulk clone with parallel processing
gbulk() {
    gclone -w 8 "$@"
}

Fish Shell Functions

function gcd --argument repo
    test -n "$repo"; or return 1
    cd (gclone $repo)
end

function gcode --argument repo
    test -n "$repo"; or return 1
    code (gclone $repo)
end

function gbulk
    gclone -w 8 $argv
end

PowerShell Functions

function gcd($repo) {
    Set-Location (gclone $repo)
}

function gcode($repo) {
    code (gclone $repo)
}

function gbulk {
    gclone -w 8 @args
}

🏗️ How It Works

Parse & Validate - Security validation of repository URLs
Normalize - Convert URLs to filesystem paths (with caching)
Parallel Process - Distribute work across configurable workers
Smart Check - Cache-optimized directory existence checking
Secure Clone - Timeout-protected git operations
Signal Handling - Graceful shutdown on interrupts

🔒 Security Features

URL Validation - Comprehensive security checks against malicious URLs
Path Sanitization - Protection against directory traversal attacks
Command Safety - No shell interpretation, direct git execution
Timeout Protection - 10-minute timeout per repository
Safe Defaults - Conservative permissions (0750) for created directories

⚡ Performance Features

Parallel Workers - Configurable concurrent cloning (1-32 workers)
Smart Caching - LRU cache for directory existence checks
Sequential Fallback - Automatic optimization for single repositories
Memory Efficient - Streaming directory reads, minimal allocations

🎯 Use Cases

📚 Learning - Quickly clone course materials and tutorials
🔧 Development - Maintain consistent project structure across teams
🤖 CI/CD - Bulk repository setup in automation pipelines
🔍 Research - Rapidly explore multiple open source projects
📋 Backup - Mirror repositories locally with organized structure
🏢 Enterprise - Standardized repository organization

📊 Status & Monitoring

The tool provides detailed feedback during operation:

# Progress indicators for multiple repositories
gclone repo1.git repo2.git repo3.git
# processed 3 repositories: 2 successful, 1 failed

# Existing repositories are detected
gclone https://github.com/existing/repo.git
# repository already exists: /home/user/src/github.com/existing/repo

# Graceful interrupt handling
^C Received signal interrupt, initiating graceful shutdown...
Graceful shutdown completed.

🤝 Contributing

Contributions are welcome! The codebase features:

Dependency Injection - Clean interfaces for testability
Comprehensive Testing - Full test coverage with mocks
Security Focus - Multiple layers of validation
Performance Optimization - Caching and parallelization

📄 License

MIT License - see LICENSE file for details.

Made with ❤️ by developers, for developers

⭐ Star this repo if it helps you stay organized and productive!

Gclone

Install / Use

README