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 Rust needed.

   brew install jedipunkz/gm/gm

   Copy

   Or build from source with Rust 1.95 or newer:

   cargo install --locked --git https://github.com/jedipunkz/gm

   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, andCtrl+L for its branches; the same key swaps it back. Going back keeps the query, the cursor and the highlights as they were. The branch list holds the local branches and the remote ones with no local namesake; branches a remote has that the last fetch did not bring join the top once git ls-remoteanswers in the background, with git's own credentials and no gh. Enter on a branch goes to its worktree, making one first when there is none — a remote branch becomes a local one that tracks it, fetched first if it has not been.Ctrl+J lists the open pull requests, drafts marked, through theGitHub CLI; Enter has gh pr checkout --worktree make the worktree. While gm waits on git or GitHub, the line under the prompt shows a spinner, what it is waiting on and the seconds so far.

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. To act on a repository you just searched for, end the query with ; and type the command after it: gm;/remove selects gm and removes 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
branch_key   = "ctrl-l"        # the finder key that lists branches
pr_key       = "ctrl-j"        # the finder key that lists pull requests
issue_key    = "ctrl-["        # the finder key that lists issues
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, branch_key, pr_key, issue_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