ghq

TLDR

Clone a repository under the ghq root directory (default is ~/ghq)

$ ghq get [repository_url]

Clone a repository from a user/project format (defaults to GitHub)

$ ghq get [user]/[project]

Clone a repository and cd into it

$ ghq get [repository_url] --look

Clone a repository via SSH

$ ghq get [user]/[project] -p

Update an existing repository to the latest version

$ ghq get [repository_url] -u

List all locally cloned repositories

$ ghq list

List locally cloned repositories with full paths

$ ghq list --full-path

Remove a locally cloned repository

$ ghq rm [user]/[project]

get [-u|--update] [-p|--shallow] [--depth=N] [-f|--force] [-b|--base=BASE] [-r|--remote=URL] [-v|--verbose]
    Clone or update repository(ies); supports shorthand URLs like github.com/user/repo

list [-p|--full-path]
    List installed repositories; -p shows full paths

show REPO
    Print full path to repository for cd usage

root [-u|--update]
    Print $GHQ_ROOT; -u migrates legacy config

version
    Display ghq version

-v, --verbose
    Enable verbose output (global)

DESCRIPTION

ghq is a lightweight command-line tool for managing remote repositories, primarily Git but also supporting Mercurial and Bazaar. It clones repositories into a consistent directory structure under $GHQ_ROOT (default ~/ghq), organized as {git,hg,bzr}/{owner}/{repo}. This enables easy navigation and integration with fuzzy finders like peco or fzf via aliases such as cd $(ghq list | peco | ghq show).

The core workflow starts with ghq get to fetch repos using shorthands like github.com/user/repo or full URLs. It handles updates, shallow clones, and forcing overwrites. ghq list enumerates installed repos, ghq show prints the path to a repo for cd, and ghq root displays the root directory.

ghq emphasizes simplicity, shell completions (bash, zsh, fish), and portability. Set GHQ_ROOT to customize the base directory. It's ideal for developers juggling multiple projects, avoiding scattered clones.

CAVEATS

Requires Git (or Hg/Bzr for respective repos); $GHQ_ROOT must be writable; shallow clones lack full history; no built-in search/filtering (use with peco/fzf).

ENVIRONMENT VARIABLES

GHQ_ROOT: base directory (default ~/ghq).
GHQ_BASEGIT: Git repos subdir (default github for shorthands).

EXAMPLE WORKFLOW

ghq get motemen/ghq # clone
ghq list | peco | xargs ghq show | cd # fuzzy cd to repo.

INSTALLATION

Go: go install github.com/x-motemen/ghq/cmd/ghq@latest
Brew: brew install ghq
Requires Go 1.18+.

HISTORY

Created by Syohei YOSHIDA (motemen) in 2013; written in Go for cross-platform use. Gained popularity in Japanese dev community via integrations with dotfiles. Actively maintained on GitHub (x-motemen/ghq); v1.3+ added shallow depth control and better VCS detection.

ghq