Jump to any repository.
Or any of its worktrees.

Why gm

What it does beyond ghq

An existing ghq tree works untouched. gm adds the parts you would otherwise glue together yourself.

Not implemented, deliberately: Mercurial / Subversion / Darcs cloning (they are still listed), bare clones, partial clones, parallel import, --vcs, and per-URL ghq.<url>.root roots.

Get started

Install in three steps

1. 1

   Install the binary

   Homebrew on macOS or Linux downloads a prebuilt binary; no Go needed.

   brew install jedipunkz/gm/gm

   Copy

   Or build from source with Go 1.25 or newer:

   go install github.com/jedipunkz/gm@latest

   Copy
2. 2

   Bind it to your shell

   gm prints the chosen path, so it composes with $(...). One line in your rc file turns that into a cd on Ctrl+G.

   fish — ~/.config/fish/config.fish

   gm shell fish | source

   Copy

   zsh — ~/.zshrc

   eval "$(gm shell zsh)"

   Copy

   bash — ~/.bashrc

   eval "$(gm shell bash)"

   Copy
3. 3

   Clone and jump

   Clones land under the root; press Ctrl+G anywhere to jump.

   gm get jedipunkz/gm
   # then press Ctrl-G and type gm

   Copy

Requirements: git on $PATH, and a true-color terminal for the themes to look as intended.gm version says which version you have.

Usage

Keys

Ctrl+W swaps the repository list for the git worktrees of the repository under the cursor, and swaps it back. Going back keeps the query, the cursor and the highlights as they were.

Everything else is ordinary text editing (Ctrl-A, Ctrl-E, Ctrl-U…), exceptCtrl-W, which no longer deletes the word before the cursor. Esc undoes one layer of narrowing at a time — the worktree list, then the query, then the filter — and only quits once there is nothing left to undo.

Slash commands

A / at the start of the input types a command instead of a filter; Tab completes it./create and /remove ask first, in a panel over the list, and do the work without leaving the finder.

~/gm/github.com/jedipunkz/gm/            the repository
~/gm/.worktrees/github.com/jedipunkz/gm/feat/login

Subcommands

<repo> accepts a full URL, git@host:user/repo.git, host/user/repo,user/repo, or a bare repo (resolved against git config github.user).

Configuration

One optional file

~/.config/gm/gm.toml (or $XDG_CONFIG_HOME/gm/gm.toml). A file that cannot be parsed, or that holds a key gm does not know, is an error rather than a file half ignored.

root         = "~/ghq"         # or ["~/ghq", "~/src"], searched in order
theme        = "tokyonight"
launch_key   = "ctrl-g"        # the shell key that opens gm
worktree_key = "ctrl-w"        # the finder key that lists worktrees
remote_key   = "ctrl-alt-b"    # the finder key that opens the remote

Key bindings

launch_key is the chord gm shell binds and must be a plain Ctrl chord;worktree_key and remote_key are the finder's own and also take alt andshift. Ctrl is written ctrl-, ctrl+, c- or ^. After changing launch_key, re-run gm shell <shell>.

Themes

Set theme in gm.toml. An unknown name is an error listing the valid ones. The palettes below are read from gm's source when this site is built.

• github.com/acme/alpha

  ▸ github.com/jedipunkz/gm

  main clean 3 changed
  tokyonightdefault
• github.com/acme/alpha

  ▸ github.com/jedipunkz/gm

  main clean 3 changed
  catppuccin-frappe
• github.com/acme/alpha

  ▸ github.com/jedipunkz/gm

  main clean 3 changed
  catppuccin-lattelight
• github.com/acme/alpha

  ▸ github.com/jedipunkz/gm

  main clean 3 changed
  catppuccin-macchiato
• github.com/acme/alpha

  ▸ github.com/jedipunkz/gm

  main clean 3 changed
  catppuccin-mocha
• github.com/acme/alpha

  ▸ github.com/jedipunkz/gm

  main clean 3 changed
  dracula
• github.com/acme/alpha

  ▸ github.com/jedipunkz/gm

  main clean 3 changed
  kanagawa-wave
• github.com/acme/alpha

  ▸ github.com/jedipunkz/gm

  main clean 3 changed
  rose-pine
• github.com/acme/alpha

  ▸ github.com/jedipunkz/gm

  main clean 3 changed
  solarized-dark
• github.com/acme/alpha

  ▸ github.com/jedipunkz/gm

  main clean 3 changed
  solarized-lightlight

Ranking

Match quality first, frecency second