ghq

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

$ ghq get [repository_url]

$ ghq get [user]/[project]

$ ghq get [repository_url] --look

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

$ ghq get [repository_url] -u

$ ghq list

$ ghq list --full-path

$ ghq rm [user]/[project]

ghq [global_options] <subcommand> [subcommand_options] [arguments]

global_options
    Options that can be applied before any subcommand.

--help
    Display help information for ghq or a specific subcommand.

--version
    Show the ghq version number.

--debug
    Enable verbose debug output.

subcommand
    The action to perform, such as get, list, look, or root.

arguments
    Additional arguments required by the subcommand (e.g., a repository URL for get).

get
    Clones a repository into the ghq root directory, following its structured hierarchy. Accepts a URL (e.g.,
https://github.com/user/repo) or a partial path (e.g.,
github.com/user/repo).

get --update | -u
    When using get, update the repository if it already exists locally.

get --shallow
    When using get, perform a shallow clone (depth 1) of the repository.

list [pattern]
    Lists all managed repositories. An optional pattern can filter the results.

list --full-path | -f
    When using list, display the full path to each repository.

look
    Changes the current directory to the specified repository. Accepts a partial path (e.g.,
user/repo).

look --ghq-path
    When using look, print the repository's path instead of changing directory.

root
    Prints the path to the ghq root directory where repositories are stored.

ghq is a command-line tool designed to simplify the management and organization of Git repositories on your local machine. Unlike simply cloning repositories anywhere, ghq establishes a structured directory hierarchy, typically under a base path like
~/ghq///. This systematic approach makes it effortless to locate, navigate, and manage your projects, especially when dealing with numerous repositories from various sources (e.g., GitHub, GitLab, Bitbucket).

The primary function, ghq get, clones a repository into this predefined structure, automatically inferring the host and user from the provided URL or path. Other crucial subcommands include ghq list to display all locally managed repositories, ghq look to quickly change into a repository's directory, and ghq root to show the base directory where repositories are stored.

ghq promotes a consistent development environment, reducing the cognitive load of remembering where each project is located. It is widely adopted by developers who frequently work on multiple projects or contribute to open source, offering a clean and predictable way to organize their code.

ghq is not a standard Linux utility; it must be installed separately, typically via a package manager (like
Homebrew on macOS or a custom
Go installation on Linux). It relies on
Git being installed and configured on the system. While highly structured, manually moving or modifying repositories within the
ghq root directory without using ghq commands can lead to inconsistencies. Its primary benefit comes from consistent usage.

ghq is typically installed via package managers like
Homebrew on macOS, or through
Go's own tooling (e.g.,
go install github.com/x-motemen/ghq@latest) on Linux and other systems. It is not part of standard Linux distributions by default and requires a working Go environment for `go install`.

The base directory for ghq repositories can be configured using the
GHQ_ROOT environment variable. By default, it's
~/.ghq or
~/ghq. Multiple roots can be defined by separating paths with
: (colon). This allows for even more flexible organization across different storage locations, e.g.,
GHQ_ROOT="~/ghq:~/work/ghq".

ghq was created by Motohiko Kubota (motemen) as a tool to organize Git repositories in a standardized, language-agnostic way. Its design principles are heavily influenced by the structured repository management seen in
Go workspaces (specifically, how
go get used to place repositories). While not exclusively for
Go, it gained significant traction within that community due to its consistency with
Go's workspace philosophy. It aims to solve the common developer problem of having scattered projects by imposing a predictable hierarchy.

git(1), go(1), fzf(1), find(1)