Docs

Reference

How to do things with gm, and what each command, key and setting does. To install it, seeInstall.

Finder

Ctrl-G in the shell (after gm shell) or gm opens it. The best match is the bottom row, next to the prompt; details of the selected row are on the right. While gm waits on git or GitHub, the line under the prompt says what it is waiting on.

Lists

• The other lists belong to the repository selected when they were opened. Going back restores the query and cursor.
• In the pull request list, #42 finds number 42.
• In the issue list, #42 finds number 42; Enter opens its text full screen — the description and each comment in their own frame, headings, code, lists and links drawn — , q or Esc goes back, Space pages, Shift-Space or b pages back (b works everywhere; Shift-Space needs a terminal that reports keys — Ghostty, kitty, WezTerm, foot, recent Windows Terminal), j k go a line, Ctrl-B opens it in a browser, Ctrl-Y copies its URL (OSC52: tmux needs set-clipboard, and some terminals ask to be allowed).
• Picking a remote branch makes a local branch that tracks it.

Keys

Ctrl-W Ctrl-L Ctrl-J Ctrl-[ Ctrl-Alt-B can be changed: see Key bindings.

Slash commands

• Type / in an empty box to start a command; Tab completes it, Enter runs it.
• To act on a search result, end the query with ;: gm;/remove selects gm and removes it.
• /create, /remove and /expire show what will happen, uncommitted changes included, and ask first: y goes ahead, n or Esc cancels.

Commands

<repo> to clone or create is a URL or a shorthand: see Repository references.remove and wt take a query instead: an exact name, user/repo orhost/user/repo, else a substring; more than one match is an error listing them.

gm get [flags] <repo>...

Clones each repository under the first root, submodules included. One already cloned is skipped unless -u is given.

-u fetches and fast-forwards the checked-out branch. It never merges: a dirty tree or a diverged branch is left alone, with a skip line saying why.

gm list [flags] [<query>]

Prints host/user/repo for every repository whose path contains the query (case-sensitive).

gm status [flags]

Lists repositories and worktrees with uncommitted changes or unpushed commits, e.g.3 changed files, 2 unpushed. It never fetches, so it works offline; behind counts are as of the last fetch.

gm create [--ssh] <repo>

Makes the directory under the first root, runs git init, sets origin (SSH with--ssh), and prints the path. Refused if the repository already exists or the directory is not empty.

gm remove [--dry-run] [-y] <repo>...

Removes each repository and every worktree checked out of it. Before asking, it lists what would be lost: uncommitted changes in the repository and in each worktree.

gm wt create | remove | expire

The finder's worktree actions, for scripts. remove and expire take --dry-run and -y.

gm migrate [--dry-run] [-y] [-r] <directory>...

Moves existing clones to the path their origin says, asking for each, and repairs their worktrees.-r searches each directory for repositories instead and skips the ones it cannot move (noorigin, destination exists, already cloned under another root, a worktree or submodule).

gm root / gm shell / gm version

• gm root prints the first root, where new repositories go; --all prints every root.
• gm shell <fish|zsh|bash> prints the launch_key binding: it runs gm and cds to the result. Re-run it after changing launch_key.
• gm version prints the version; gm help the usage.

Scripting

• Paths go to stdout (the finder's choice, create, wt create, migrate); progress, warnings and prompts go to stderr. cd "$(gm)" works.
• Exit status: 0 success (quitting the finder and answering no included), 1 error, 2 wrong usage.
• Prompts read [y/N]; a closed stdin answers no. Pass -y to skip them.
• Flags go before the arguments; -b main and --branch=main are the same.

Where repositories go

Repository references

A <repo> to clone or create becomes a URL, and its host/user/repo is the directory under the root.

Directory layout

~/ghq/github.com/jedipunkz/gm/                            repository
~/ghq/.worktrees/github.com/jedipunkz/gm/feat/login       worktree of branch feat/login
~/ghq/.worktrees/github.com/jedipunkz/gm/.forks/bob/main  worktree of a pull request from bob's fork

• Worktrees live under <root>/.worktrees/. gm never looks inside dot-directories, so they are not listed as repositories.
• Mercurial and Subversion working copies are listed, but gm only clones with git.

Configuration

gm.toml

~/.config/gm/gm.toml (or $XDG_CONFIG_HOME/gm/gm.toml), optional. Every key is optional too. A typo, an unknown key or a wrong type is an error naming the file, so a setting is never silently ignored.

root         = "~/ghq"         # or ["~/ghq", "~/src"], searched in order
theme        = "tokyonight"
launch_key   = "ctrl-g"
worktree_key = "ctrl-w"
branch_key   = "ctrl-l"
pr_key       = "ctrl-j"
issue_key    = "ctrl-["
remote_key   = "ctrl-alt-b"

Roots

The first source that is set wins, so an existing ghq setup works untouched:

~ expands to your home directory; every root must be absolute. New clones go to the first root; all roots are listed and searched.

Key bindings

Write a chord as Ctrl, optionally Alt and Shift, plus one letter: ctrl-g, ctrl-alt-b(Ctrl+Alt+B, c-a-b and ^b also work). An invalid chord is an error.

• launch_key must be a plain Ctrl chord, and not ctrl-m ctrl-i ctrl-j (terminals send them as Enter, Tab, newline).
• The five finder keys must differ from each other, and cannot take ctrl-m ctrl-i or, as plain chords, ctrl-c ctrl-n ctrl-p ctrl-g. issue_key may also be ctrl-[, the byte Esc is sent as.
• Avoid what the shell keeps for itself: ctrl-r, ctrl-c, ctrl-d, ctrl-z.

Themes

tokyonight catppuccin-frappe catppuccin-latte catppuccin-macchiato catppuccin-mocha dracula kanagawa-wave rose-pine solarized-dark solarized-light

The default is tokyonight. See the palettes on the home page.

Ranking

• Typing keeps repositories whose host/user/repo holds the typed characters in order, ignoring case.
• Better matches go lower: a literal substring beats scattered characters, and a match in the repository name counts more than one in the user name or host.
• Ties, and the list before you type, are ordered by frecency: how often and how recently you visited.
• A visit is choosing a row in the finder, or cloning, creating or moving a repository with gm.

Requirements and environment

• macOS or Linux (WSL2 included), git on $PATH, and a true-color terminal for the themes.
• The pull request and issue lists need gh, logged in. The branch list uses git's own credentials.
• Network calls never prompt for a password and give up after a deadline (20 s for the branch list, 30 s for pull requests and issues), saying what timed out.