ghq

You can install ghq using various package managers depending on your operating system and environment:

• macOS: brew install ghq
• Void Linux: xbps-install -S ghq
• GNU Guix: guix install ghq
• Windows (Scoop): scoop install ghq
• Go: go install github.com/x-motemen/ghq@latest
• Conda: conda install -c conda-forge go-ghq
• asdf: asdf plugin add ghq followed by asdf install ghq latest
• mise: mise install ghq followed by mise use ghq
• Nix: nix profile install nixpkgs#ghq
• Build from source:

  git clone https://github.com/x-motemen/ghq .
  make install

You can customize where ghq stores its repositories using git-config variables or the GHQ_ROOT environment variable.

Git Configuration

• ghq.root: The path to the directory where repositories are placed. Defaults to ~/ghq. You can specify multiple roots; the last one becomes the primary root for new clones.
• ghq.<url>.root: Specify a repository-specific root directory for URLs matching <url> (using git config --get-urlmatch).

Environment Variable

• GHQ_ROOT: If set, this path is used as the only root directory, overriding all ghq.root settings in git config.

Customize how ghq resolves repository names when the host or user is omitted.

Git Configuration

• ghq.user: The default owner used when specifying only a project name (e.g., ghq get {{Project}}). Defaults to the value of the USER (or USERNAME on Windows) environment variable.
• ghq.completeUser: If set to false, ghq will attempt to complete the owner with the same name as the repository (e.g., ruby becomes github.com/ruby/ruby) instead of using the default user.
• ghq.defaultHost: The default host used when the repository specification omits the host (e.g., ghq get owner/project would use this host instead of github.com).

For repositories that are not on github.com, you can explicitly specify the Version Control System (VCS) using git-config.

Configuration: Use ghq.<url>.vcs = <vcs> where <url> is matched via git config --get-urlmatch.

Supported values:

• git (or github)
• subversion (or svn)
• git-svn
• mercurial (or hg)
• darcs
• fossil
• bazaar (or bzr)

[ghq "https://git.example.com/repos/"]
vcs = git
root = ~/myproj

The ghq tool determines where local repositories are stored using the following priority:

1. Environment Variable: Use the GHQ_ROOT environment variable. If set, it can contain multiple paths separated by the OS path list separator.
2. Git Configuration: Use the value of ghq.root from your git configuration. ghq also supports specific roots via ghq.<name>.root patterns.
3. Default: Fallback to ~/.ghq (the user's home directory plus /ghq).

Remove a repository

Use ghq rm <repository> to remove a local repository. Use --dry-run to see which path would be removed without actually deleting it.

Create a new repository

Use ghq create <repository> to initialize a new repository.

Migrate existing repositories

Use ghq migrate <local repository path> to move an existing directory into the ghq managed directory structure. The command detects the VCS backend, retrieves the remote URL, and moves the repository to the correct location under the ghq root.

Use ghq list to view your locally cloned repositories managed by ghq.

Options:

• <query>: Filter repositories by a name containing the query text.
• -e, --exact: Force the query to match the repository name exactly.
• -p, --full-path: Print the full absolute paths to the repository roots instead of relative ones.

Use ghq get to clone a remote repository into your ghq root directory (default ~/ghq). The directory structure is organized by the remote repository's host and path.

Common flags:

• -u, --update: If the repository is already cloned, update it (performs git pull --ff-only).
• -p: Clone via SSH protocol.
• --shallow: Perform a shallow clone (git clone --depth 1). Note: shallow clones cannot be pushed to remote.
• --branch <branch>: Clone a specific branch (supports Git, Mercurial, Subversion, and git-svn).
• --no-recursive: Prevent recursive cloning of submodules/repositories.
• --bare: Perform a bare clone (Git only).
• --partial <mode>: Perform a partial clone (Git only). Modes: blobless or treeless.

ghq get https://github.com/x-motemen/ghq

Use NewRemoteRepository to instantiate a RemoteRepository implementation based on the provided URL. The function automatically detects the host (e.g., github.com, gist.github.com, hub.darcs.net, nest.pijul.com, chiselapp.com) and returns the appropriate concrete type. If the URL is invalid for its detected type, it returns an error.

Supported host-based types:

• github.com -> GitHubRepository
• gist.github.com -> GitHubGistRepository
• hub.darcs.net -> DarksHubRepository
• nest.pijul.com -> NestPijulRepository
• chiselapp.com -> ChiselRepository
• codecommit://... -> CodeCommitRepository
• All others -> OtherRepository

The GitBackend supports several advanced Git features via vcsGetOption:

• Shallow Clones: Uses --depth 1 if shallow is true.
• Branching: Uses --branch <branch> --single-branch if a branch is specified.
• Recursion: Uses --recursive for submodules.
• Bare Repositories: Uses --bare if bare is true.
• Partial Clones: Supports --filter=blob:none (for blobless) and --filter=tree:0 (for treeless).
• Update Logic: Performs a git fetch and git pull --ff-only. If recursive is true, it also runs git submodule update --init --recursive.