Corral

Automatically clone and organise repositories from GitHub, GitLab, Gitea, Forgejo, Codeberg and Bitbucket using Finder-friendly collections, ecosystems, and metadata.

Contents

Getting started

• Install — mise, Homebrew, Arch, Nix, Go, or from source
• Quick Start — clone and organise in one command

Features & Capabilities

• Features — structured layout, concurrency, and security
• Architecture — end-to-end flow from API fetch to per-repo dispatch
• Interactive TUI Mode — keybindings, commands, and autocomplete
• Layout Customization — Apple-style collections, ecosystems, and custom templates
• Smart Syncing — network-optimised incremental updates
• Exec Mode — concurrent batch execution of Git commands
• MCP Server — expose your local workspace to AI coding agents
• Cross-repository symbol lookup — find where anything is defined, across every clone

Reference & Operational

• Usage & Flags — complete CLI parameter reference
• Examples — index of runnable programmatic examples
• Troubleshooting — quick solutions to common errors
• Frequently Asked Questions — design decisions and Windows/WSL support

Project

• Documentation — manual, API reference, developer docs
• When not to use Corral — honest limits
• Requirements & toolchain policy — the Go floor and when it moves
• Stability guarantees — what a breaking change means here
• Security & hardening — reporting, posture, fuzzing
• License

Install

mise (macOS / Linux)

mise use -g github:sebastienrousseau/corral

This installs the latest released corralctl binary and keeps it managed with the rest of your mise tools.

Homebrew (macOS)

brew install sebastienrousseau/tap/corralctl

Homebrew here is a cask, which is a macOS-only mechanism — brew install on Linux will refuse it. On Linux use the .deb/.rpm packages or the tarballs attached to each release, or install with mise or the Go toolchain.

Arch Linux (AUR)

yay -S corralctl-bin    # or: paru -S corralctl-bin

Nix (any platform)

nix run github:sebastienrousseau/corral -- --help   # run without installing
nix profile install github:sebastienrousseau/corral # install

The flake ships the binary with its manpages and shell completions, and nix develop gives a shell with every tool the project's CI gates need, pinned by flake.lock.

Go toolchain

go install github.com/sebastienrousseau/corral/cmd/corralctl@latest

Installs into $(go env GOPATH)/bin (or $GOBIN when set). Note that a binary built this way reports corralctl version dev: the real version is stamped by the release pipeline through -ldflags, which go install does not apply. Use a release artefact if you need --version to be meaningful.

Build from source

Requires Go 1.26+ and Git:

git clone https://github.com/sebastienrousseau/corral.git
cd corral
make install            # installs ~/.local/bin/corralctl

Platform Prerequisites

brew install go git gh

sudo apt install golang git

sudo dnf install golang git gh

Quick Start

Run Corral with an owner name (GitHub username or organization) to clone and automatically sort all repositories into a clean local directory hierarchy:

# Log in to GitHub CLI first (or set GITHUB_TOKEN)
gh auth login

# Run Corral for your profile
./corralctl my-username

This converges your local directory structure into a structured mirror:

~/Code/
├── Public/
│   ├── Go/
│   │   └── corral/
│   ├── Rust/
│   │   └── my-crate/
│   └── Web/
│       └── project.github.io/
├── Private/
│   └── Python/
│       └── internal-tool/
├── Forks/
│   └── Rust/
│       └── upstream-project/
└── Work/

On macOS, Corral also writes native Finder Tags to repository folders while preserving tags you added yourself. This keeps the physical hierarchy shallow and makes Finder searches and Smart Folders useful across ecosystems.

Features

Architecture

A single run resolves git, fetches every repository concurrently from the forge (GitHub, GitLab, Gitea, Forgejo, Codeberg or Bitbucket), optionally lets you pick a subset interactively, then dispatches clone / smart-sync / skip decisions across a worker pool. Smart sync consults a per-repository .corral-state.json sidecar to skip a git pull when the upstream pushed_at is unchanged.

graph TD
    A[User Shell] --> B{corralctl}
    B --> C[Pre-flight: exec.LookPath git]
    C -- Missing --> Z1[Exit: git not found on PATH]
    C -- OK --> D[Resolve auto/token/gh auth]
    D --> E[Forge API: list repos]
    E --> E1["First page<br/>+ resp.LastPage"]
    E1 --> E2{LastPage > 1?}
    E2 -- Yes --> E3["Concurrent fetch<br/>pages 2..N (max 5)"]
    E2 -- No --> F
    E3 --> F[Filtered repository set]
    F --> F1{TUI selector?}
    F1 -- "--select" --> F2[Interactive TUI<br/>/sort, /all, /none, search]
    F1 -- No --> G
    F2 --> G[Layout template render<br/>Collection/Bucket/Name]
    G --> H["Worker pool<br/>(--concurrency)"]
    H --> I{Already cloned?}
    I -- No --> J["git clone (+ blobless/<br/>depth/single-branch)"]
    I -- "Yes (--no-sync)" --> K[SKIP]
    I -- Yes --> L{Smart sync:<br/>pushed_at advanced?}
    L -- No --> M[SKIP up-to-date]
    L -- "Yes (or --force-sync)" --> N[git pull --rebase --autostash]
    N --> N1["+ optional submodule update<br/>(--ignore-submodule-failures)"]
    J & N1 --> O[Stamp .corral-state.json]
    O & K & M --> P{All workers done?}
    P -- No --> H
    P -- Yes --> Q[Cleanup empty legacy dirs]
    Q --> R{--orphans?}
    R -- Yes --> S[Walk baseDir<br/>parse .git/config]
    R -- No --> T[Print summary]
    S --> T

Interactive TUI Mode

By passing the -i or --interactive flag, you can launch the selection dashboard:

./corralctl -i my-username

Keybindings