= ghq(1) image:https://github.com/x-motemen/ghq/workflows/test/badge.svg?branch=master["Build Status", link="https://github.com/x-motemen/ghq/actions?workflow=test"] image:https://coveralls.io/repos/motemen/ghq/badge.svg?branch=master["Coverage", link="https://coveralls.io/r/motemen/ghq?branch=master"]
== NAME
ghq - Manage remote repository clones
== DESCRIPTION
'ghq' provides a way to organize remote repository clones, like +go get+ does. When you clone a remote repository by +ghq get+, ghq makes a directory under a specific root directory (by default +~/ghq+) using the remote repository URL's host and path.
$ ghq get https://github.com/x-motemen/ghq
# Runs `git clone https://github.com/x-motemen/ghq ~/ghq/github.com/x-motemen/ghq`
You can also list local repositories (+ghq list+).
== SYNOPSIS
[verse]
ghq get [-u] [-p] [--shallow] [--vcs ] [--look] [--silent] [--branch] [--no-recursive] , //, /,
ghq list [-p] [-e] []
ghq create [--vcs ] , //, /,
ghq root [--all]
== COMMANDS
get::
Clone a remote repository under ghq root directory (see
<<directory-structures,DIRECTORY STRUCTURES>> below). If the repository is
already cloned to local, nothing will happen unless '-u' ('--update')
flag is supplied, in which case the local repository is updated ('git pull --ff-only' eg.).
When you use '-p' option, the repository is cloned via SSH protocol. +
If there are multiple +ghq.root+ s, existing local clones are searched
first. Then a new repository clone is created under the primary root if
none is found. +
With '--shallow' option, a "shallow clone" will be performed (for Git
repositories only, 'git clone --depth 1 ...' eg.). Be careful that a
shallow-cloned repository cannot be pushed to remote.
Currently Git and Mercurial repositories are supported. +
With '--branch' option, you can clone the repository with specified
repository. This option is currently supported for Git, Mercurial,
Subversion and git-svn. +
The 'ghq' gets the git repository recursively by default. +
We can prevent it with '--no-recursive' option.
list::
List locally cloned repositories. If a query argument is given, only
repositories whose names contain that query text are listed. '-e'
('--exact') forces the match to be an exact one (i.e. the query equals to
project, user/project or host/user/project)
If '-p' ('--full-path') is given, the full paths to the repository root are
printed instead of relative ones.
root::
Prints repositories' root (i.e. ghq.root). Without '--all' option, the
primary one is shown.
create::
Creates new repository.
== CONFIGURATION
Configuration uses 'git-config' variables.
ghq.root::
The path to directory under which cloned repositories are placed. See
<<directory-structures,DIRECTORY STRUCTURES>> below. Defaults to +~/ghq+. +
This variable can have multiple values. If so, the last one becomes
primary one i.e. new repository clones are always created under it. You may
want to specify "$GOPATH/src" as a secondary root (environment variables
should be expanded.)
ghq..vcs::
ghq tries to detect the remote repository's VCS backend for non-"github.com"
repositories. With this option you can explicitly specify the VCS for the
remote repository. The URL is matched against '' using 'git config --get-urlmatch'. +
Accepted values are "git", "github" (an alias for "git"), "subversion",
"svn" (an alias for "subversion"), "git-svn", "mercurial", "hg" (an alias for "mercurial"),
"darcs", "fossil", "bazaar", and "bzr" (an alias for "bazaar"). +
To get this configuration variable effective, you will need Git 1.8.5 or higher. +
For example in .gitconfig:
ghq..root::
The "ghq" tries to detect the remote repository-specific root directory. With this option,
you can specify a repository-specific root directory instead of the common ghq root directory. +
The URL is matched against '' using 'git config --get-urlmatch'.
....
[ghq "https://git.example.com/repos/"]
vcs = git
root = ~/myproj
....
== ENVIRONMENT VARIABLES
GHQ_ROOT::
If set to a path, this value is used as the only root directory regardless
of other existing ghq.root settings.
== DIRECTORY STRUCTURES
Local repositories are placed under 'ghq.root' with named github.com/user/repo.
....
~/ghq, -- code.google.com/, -- p/, -- vim/
-- github.com/, -- google/, -- go-github/, -- motemen/, -- ghq/ -- urfave/
`-- cli/
....
== INSTALLATION
=== homebrew
brew install ghq
=== go get
go get github.com/x-motemen/ghq
=== build
git clone https://github.com/x-motemen/ghq .
make install
Built binaries are available from GitHub Releases.
https://github.com/x-motemen/ghq/releases
== HANDBOOK
You can buy "ghq-handbook" from Leanpub for more detailed usage.
https://leanpub.com/ghq-handbook (Currently Japanese Only)
The source Markdown files of this book are also available for free from the following repository.
https://github.com/Songmu/ghq-handbook
== AUTHOR