ghq-gh-wiki-clone

June 16, 2026 · View on GitHub

A zsh plugin that, after ghq get / ghq clone fetches a repository, automatically clones its GitHub Wiki (when the wiki has pages) into a .wiki subdirectory of that repository.

How it works

ghq has no native post-get hook. This plugin wraps the zsh ghq function and adds post-processing only for the get / clone subcommands (the real binary is always invoked via command ghq, so there is no recursion).

  1. Diff ghq list --full-path before and after the get to find newly cloned repositories.
  2. For each repo whose origin is on github.com, derive the wiki URL (<repo>.wiki.git).
  3. Use git ls-remote to detect a wiki that actually has pages, then clone it into <repo>/.wiki.
  4. Append .wiki/ to the parent repo's .git/info/exclude so the wiki does not show up in git status (the tracked .gitignore is left untouched).

The wiki check does not rely on the GitHub API has_wiki flag: has_wiki can be true while the wiki has no pages, so the plugin verifies that the wiki is actually clonable with git ls-remote.

Requirements

Installation

zinit

zinit load shmokmt/ghq-gh-wiki-clone

antigen

antigen bundle shmokmt/ghq-gh-wiki-clone

oh-my-zsh

git clone https://github.com/shmokmt/ghq-gh-wiki-clone \
  "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/plugins/ghq-gh-wiki-clone"
# Add ghq-gh-wiki-clone to plugins=(...) in your .zshrc

Manual

source /path/to/ghq-gh-wiki-clone/ghq-gh-wiki-clone.plugin.zsh

Usage

Just use ghq as usual.

ghq get github.com/nvbn/thefuck
# => ghq-gh-wiki-clone: cloning wiki -> <ghq root>/github.com/nvbn/thefuck/.wiki

Nothing happens for repositories without a wiki (or with an empty one). Subcommands other than get / clone (e.g. ghq list) are passed straight through.

Syncing an existing repository's wiki

The get / clone wrapper only fires on fresh clones. For a repository you already have, use ghq-wiki-sync to clone the wiki if it is missing, or pull the latest pages if it is already there:

ghq-wiki-sync nvbn/thefuck
# first run  => ghq-gh-wiki-clone: cloning wiki -> <ghq root>/github.com/nvbn/thefuck/.wiki
# later runs => ghq-gh-wiki-clone: updating wiki -> <ghq root>/github.com/nvbn/thefuck/.wiki
#               (git pull --ff-only)

The argument is resolved with ghq list --exact, so a bare project name that exists under multiple owners is reported as ambiguous rather than acting on the wrong repo. Qualify it as host/user/project to disambiguate:

ghq-wiki-sync thefuck
# => ghq-wiki-sync: 'thefuck' is ambiguous; qualify it as <host/user/project>:
#      /path/to/ghq/github.com/nvbn/thefuck
#      /path/to/ghq/github.com/other/thefuck

Note: ghq-wiki-sync is a one-way (remote → local), read-only sync. It only clones or pulls (fast-forward only) and never pushes, so any local edits to the wiki are not sent back to GitHub. Treat the cloned wiki as a read-only mirror; if you edit it locally, the next --ff-only pull may fail.

Limitations

  • ghq get -u (updating an existing repository) produces no diff in ghq list, so the wiki check does not run (it only runs on fresh clones). Use ghq-wiki-sync to backfill wikis for repositories you already have.
  • An empty wiki (enabled but with 0 pages) returns no refs from git ls-remote, so it is not cloned (by design).
  • Only github.com is supported.

License

MIT