x-motemen/ghq: cloning remote repositories into a predictable directory tree

The problem ghq solves: clone targets drift apart

Cloning with plain git puts the repository wherever your shell happens to be. Repeat that over a few years and you get clones in ~/src, ~/work, ~/tmp and the home directory itself, with no way to answer "where did I put that repository" except by searching. ghq's answer is a fixed layout: every clone goes under a root directory, and the path mirrors the remote URL's host and path. The README's own example is `ghq get https://github.com/x-motemen/ghq`, which the documentation says runs `git clone https://github.com/x-motemen/ghq ~/ghq/github.com/x-motemen/ghq`. The target is not a choice you make each time; it is derived from the URL.

The audience is narrow and specific. This is a tool for people who clone a lot of repositories and want to find them later without thinking. If you mostly work in one repository, or your editor manages its own project list, the convention buys you little. The payoff arrives when the tree is the index: ghq list walks it and prints what is there, and because the path encodes host, user and project, a query like `ghq list motemen` filters without a database.

How the root, the URL parser and the VCS backends fit together

The repository layout is small and readable: cmd_get.go, cmd_list.go, cmd_rm.go, cmd_root.go and cmd_create.go hold the commands, remote_repository.go and local_repository.go model the two sides, url.go parses repository specifications, and vcs.go holds the backend definitions. The flow for ghq get is: parse the argument into a remote repository, ask the VCS layer how to clone it, compute the destination under the ghq root, then shell out to the underlying tool. The documentation is explicit that for Git this means `git clone`, so Git's own configuration still applies. The README names `clone.defaultRemoteName` as an example, noting that it needs Git 2.30 or higher.

Configuration lives in git-config variables rather than a file of ghq's own. ghq.root can appear multiple times, and the documentation states that the last value becomes the primary root, so new clones land there while existing clones are searched across all roots first. GHQ_ROOT overrides everything: the README says that when it is set, that path is used as the only root regardless of other ghq.root settings. Per-URL settings use git's urlmatch mechanism, so a [ghq "https://git.example.com/repos/"] block can pin vcs and root for one host, and the documentation notes that urlmatch requires Git 1.8.5 or higher. That is a deliberate trade: you get git's matching rules for free, and you inherit git's version requirements.

Installing ghq and running a first clone

The module is github.com/x-motemen/ghq and go.mod declares go 1.26.0, so a Go toolchain is the straightforward path. The Makefile has an install target, and the README's installing section is where the project documents distribution. The repository also ships shell completions under misc/bash/_ghq and misc/zsh/_ghq, which the crossbuild target includes in release archives.

make install

After that, confirm the root before cloning anything, because every later path depends on it. The root command prints the primary root, and --all prints every configured one.

ghq root
ghq root --all

A first clone is one line. The README gives this exact example, and the result is a directory whose path mirrors the URL.

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

To see what you have, list the tree. With no query it prints every local repository; with a query it filters by name, and -p prints full paths instead of relative ones, which is what you want when piping into another command.

ghq list
ghq list -p motemen

The short forms are worth knowing early. `ghq get motemen/ghq` resolves the host and the owner for you, and `ghq get ghq` alone triggers owner completion, which the README says defaults to the USER environment variable (USERNAME on Windows) unless ghq.user is set.

Where ghq gets in the way

The clone flags are not free. The README warns that a shallow clone, produced by --shallow, cannot be pushed to remote, which makes it a read-mostly option rather than a general speedup. The --bare flag produces a bare clone, so there is no working tree to edit. The --partial flag maps to Git's partial clone filters, blobless or treeless, and those change what is present locally in ways that surface later as fetches. None of these are wrong, but they are choices that trade convenience for a constraint you have to remember.

The bigger limitation is coverage. The README states that Git and Mercurial repositories are currently supported, and the VCS configuration lists subversion, git-svn, darcs, fossil and bazaar as accepted values, but the feature flags are unevenly spread: --shallow, --bare and --partial are documented as Git only. The command synopsis also shows that ghq get has grown a long flag list, and the README does not document rollback for ghq rm or ghq migrate. The --dry-run option exists on both, and that is the only safety net the documentation describes, so the wrong tool for a cautious migration is ghq migrate without first reading what --dry-run prints.

There is also an ordering subtlety worth stating plainly. When multiple roots are configured, the documentation says existing local clones are searched first and a new clone is created under the primary root only if none is found. That means adding a root later does not move anything; it changes where the next clone lands.

ghq against plain git and against a project manager

The honest comparison is with the shell alias or function most people already have. A one-line alias that clones into a fixed directory gives you a root too, and it costs nothing to maintain. The difference is what happens after the clone. ghq derives the path from the full URL, so github.com/x-motemen/ghq and gitlab.com/x-motemen/ghq land in different subtrees instead of colliding on the basename, and ghq list can then answer questions across the whole tree. An alias has no list, no rm, and no migrate. That is the real gap, and it is a gap in inventory rather than in cloning.

The other comparison is with editor-managed project lists or a workspace file. Those tools keep a curated set of repositories you have explicitly opened, which is a different data model: curated and small versus discovered and complete. ghq list reflects whatever is on disk under the root, including repositories you cloned a year ago and forgot. If you want a curated list, a workspace file is the better fit. If you want to know what is actually on the machine, the tree is the source of truth.

For existing clones, ghq migrate is the bridge. The README says it detects the VCS backend, retrieves the remote URL, and moves the repository to the appropriate location under ghq root. That is the command that makes adoption incremental rather than a re-clone of everything.

Maintenance, releases and what the MIT licence leaves you

The repository is not archived, and the last push was on 2026-09-21. Recent releases are v1.10.1 on 2026-04-11, v1.10.0 on 2026-04-09 and v1.9.4 on 2026-02-17. The release process is scripted in the Makefile: godzil computes the version, ghr uploads the artifacts, and crossbuild produces archives with CGO_ENABLED=0 plus a SHASUMS file. That means upgrades are a matter of replacing a static binary, and there is no daemon or database to migrate. The dependency list in go.mod is short and mostly golang.org/x packages plus urfave/cli, so the supply chain surface is small.

The upgrade cost that actually bites is behavioural, not mechanical. The tool shells out to git for Git repositories, so the Git version on the machine sets the floor for some features: urlmatch needs Git 1.8.5 or higher and clone.defaultRemoteName needs Git 2.30 or higher, per the README. The licence is MIT, which permits commercial and private use and modification; the LICENSE file is the authoritative text, and this is not legal advice. The one thing to check on your own is whether the shell completions you install match the binary version, since they ship alongside releases.

Editorial conclusion

Adopt ghq if you clone many repositories from a terminal and want one predictable root instead of a folder full of ad hoc clone targets; the ghq get, ghq list and ghq rm trio is small enough to learn in one sitting. Skip it if your work lives inside one IDE-managed workspace or if you depend on Subversion or darcs checkouts that ghq only partly covers. Verify two things before committing: where ghq root points on your machine, and whether your existing clones can be moved with ghq migrate --dry-run before you run it for real.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. x-motemen/ghq on GitHub