explaingit

x-motemen/ghq

3,624GoAudience · developerComplexity · 2/5Setup · easy

TLDR

ghq organizes all your Git repository clones under one root directory, sorted by remote URL path, so you can find and switch between projects from the terminal without tracking where you put them.

Mindmap

mindmap
  root((repo))
    What it does
      Organize repo clones
      Structured directory
      Fast project switching
    Tech stack
      Go
      Git
      Shell integration
    Use cases
      Multi-project nav
      Terminal workflows
      Fuzzy finder pairing
    Audience
      CLI developers
      Open source contributors
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Things people build with this

USE CASE 1

Clone any GitHub repo and have it automatically placed in a predictable directory path

USE CASE 2

List all your local repositories and jump to one using fzf as a fuzzy picker

USE CASE 3

Pull updates on an already-cloned repository without remembering where it lives on disk

Tech stack

GoGit

Getting it running

Difficulty · easy Time to first run · 5min

Install with Homebrew or go install, then set GHQ_ROOT or ghq.root in git config if you want a non-default location.

In plain English

ghq is a command-line tool for organizing Git repository clones on your local machine. Instead of putting cloned repositories wherever you happen to run git clone, ghq keeps everything under a single root directory and organizes them by the host and path of the remote URL. So a repository at github.com/myname/myproject would land at ~/ghq/github.com/myname/myproject. This makes it easy to find any repository you have cloned without remembering where you put it. The main commands are get for cloning a repository, list for seeing what you have locally, and root for showing where the root directory is. The get command accepts a full URL or short forms like user/project (defaulting to GitHub) or just a project name if there is only one match. If a repository is already cloned, get does nothing by default, but adding the update flag pulls the latest changes. There are options for less common cloning needs: shallow clones for when you only need recent history, bare clones, partial clones that skip large files, cloning a specific branch, and recursive cloning for repositories with submodules. For repositories already organized differently on your machine, there is a migrate command that moves them into the ghq directory structure. ghq integrates well with fuzzy finders like fzf, which is a common pairing: you pipe ghq list into fzf, select a repository, and jump to its directory. This makes navigating between projects very fast in a terminal workflow. The tool is written in Go and can be installed with go install, through Homebrew on macOS, or via package managers on several Linux distributions. Configuration is done through a git config file rather than a separate config format.

Copy-paste prompts

Prompt 1
How do I install ghq and set up the root directory so all my GitHub clones land in ~/ghq/github.com/?
Prompt 2
Show me a shell function that combines ghq list and fzf to let me fuzzy-search and cd into any local repo
Prompt 3
How do I use ghq get to clone a repository by short name like user/project instead of a full URL?
Prompt 4
I have existing repos scattered across my home directory. How do I use ghq migrate to bring them into the ghq structure?
Open on GitHub → Explain another repo

← x-motemen on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.