An fzf wrapper around the GitHub CLI
MIT License
An fzf wrapper around the GitHub CLI.
Install gh
and
fzf
if you don't already
have them. For example:
Homebrew
brew install gh fzf
DNF
sudo dnf install gh fzf
... see the links above for other package managers
Authenticate with the GitHub CLI:
gh auth login
Install this extension:
gh extension install benelan/gh-fzf
PROFIT
To upgrade gh-fzf
to the latest commit on main
:
gh extension upgrade gh-fzf
Alternatively, you can pin a tag when installing gh
extensions. A convenience
command is provided for upgrading to the latest version (recommended):
gh fzf upgrade
You can check which version of gh-fzf
you currently have installed:
gh fzf version
The changelog contains a list of features and fixes released in each version. You can also view the release notes on the command line with:
gh fzf changelog
gh fzf <command> [flags]
This extension adds a new command that wraps GitHub's list
subcommands with
fzf to make them fuzzy findable. All of the arguments after <command>
are
passed directly to gh
. Because of the way shell works, you need to escape
quotes required by GitHub, e.g. strings with whitespace.
There are usage examples for each command in the sections below.
A preview of the current selection is displayed when navigating through the
resulting list. Each command has keybindings to further filter the list or to
call other gh
subcommands on the item. There are also a few global keybindings
that can be used with any gh fzf
command:
ctrl-o
: Open the selected item in the browserctrl-y
: Copy the selected item's URL to the clipboardctrl-r
: Reload the list to its initial filter state and fetch changes fromalt-1
to alt-9
: Change the number of items fetched from GitHub to 100,alt-P
: Toggle the preview window displayalt-H
: Toggle the header display, where the keybinding hints are locatedissue
gh fzf issue [flags]
i
, issues
, -i
, --issue
, --issues
gh issue list --help
for available optionsenter
: Edit the selected issue via CLI promptsgh issue edit --help
)alt-o
: Create/checkout a branch linked to the selected issue, promptinggh issue develop --help
)alt-c
: Add a comment to the selected issue (see gh issue comment --help
)alt-l
: Open gh fzf label
and add the selected label(s) to the issuealt-L
: Open gh fzf label
and remove the selected label(s) from the issuealt-X
: Close the selected issue (see gh issue close --help
)alt-O
: Reopen the selected issue (see gh issue reopen --help
)alt-a
: Filter the list, showing issues assigned to youalt-A
: Filter the list, showing issues authored by youalt-m
: Filter the list, showing issues where you are mentionedalt-s
: Filter the list, showing issues with any state (open or closed)gh fzf issue --assignee @me --milestone "v1.33.7" --state all
gh fzf i -S \'no:assignee label:\"good first issue\" milestone:backburner\'
pr
gh fzf pr [flags]
p
, prs
, -p
, --pr
, --prs
gh pr list --help
for available optionsenter
: Edit the selected PR via CLI prompts (see gh pr edit --help
)alt-o
: Checkout the HEAD branch of the selected PRgh pr checkout --help
)alt-c
: Add a comment to the selected PR (see gh pr comment --help
)alt-d
: Show the diff for the selected PR (see gh pr diff --help
)alt-r
: Start/continue/finish a review for the selected PRgh pr review --help
)alt-y
: Copy the branch name of the selected PRalt-l
: Open gh fzf label
and add the selected label(s) to the PRalt-L
: Open gh fzf label
and remove the selected label(s) from the PRalt-R
: Mark the selected draft PR as "ready for review"gh pr ready --help
)alt-M
: Merge the selected PR (see gh pr merge --help
)alt-X
: Close the selected PR (see gh pr close --help
)alt-O
: Reopen the selected PR (see gh pr reopen --help
)alt-C
: Open gh fzf run
filtered for the selected PR (see run)alt-a
: Filter the list, showing PRs assigned to youalt-A
: Filter the list, showing PRs authored by youalt-b
: Filter the list, showing PRs from the current branchalt-s
: Filter the list, showing PRs in any state (open, closed, or merged)gh fzf pr --state merged --author @me --label \"breaking change\"
gh fzf p -S \'merged:">=2023-01-01" \"breaking change\" in:body author:@me\'
run
gh fzf run [flags]
r
, runs
, -r
, --run
, --runs
gh run list --help
for available optionsenter
: Watch for status changes or view logs, depending on whether thegh run watch --help
and gh run view --help
)alt-l
: Display logs for the selected run (deprecated, use enter
instead)alt-d
: Download artifacts from the selected rungh run download --help
)alt-r
: Rerun the selected run (see gh run rerun --help
)alt-R
: Rerun only failed jobs of the selected run (see gh run rerun --help
)alt-x
: Cancel the selected run (see gh run cancel --help
)alt-p
: Open gh fzf pr
filtered for the selected run's branch as HEADpr
)alt-n
: Create a desktop notification with the conclusion (failed, passed,dunstify
, notify-send
, and osascript
. The notification hasdunstify
. There is an additionalNOTE: The run watching process is executed in the background, so closing
gh-fzf
won't prevent the desktop notification from displaying. Usekillall gh
to end allgh
processes, including the run watcher.
alt-w
: Filter the list, showing runs for the selected item fromgh fzf workflow
(see workflow
)alt-b
: Filter the list, showing runs from the current branchalt-u
: Filter the list, showing runs triggered by youalt-f
: Filter the list, showing failed runsalt-i
: Filter the list, showing in_progress runsgh fzf run --workflow tests
gh fzf r -b main -s failure
workflow
gh fzf workflow [flags]
workflows
, --workflow
, --workflows
gh workflow list --help
for available optionsenter
: Open gh fzf run
filtered for the selected workflowrun
)alt-d
: Dispatch the selected workflow (see gh workflow run --help
)alt-X
: Disable the selected workflow (see gh workflow disable --help
)alt-E
: Enable the selected workflow (see gh workflow enable --help
)alt-a
: Filter the list, showing all workflows (including disabled ones)gh fzf workflow --all
release
gh fzf release [flags]
releases
, --release
, --releases
gh release list --help
for available optionsenter
: Download the assets from the selected releasegh release download --help
)alt-X
: Delete the selected release (see gh release delete --help
)alt-s
: Filter the list, showing stable releases (exclude pre-releases)alt-p
: Filter the list, showing published releases (exclude drafts)alt-a
: Filter the list, showing releases in ascending order by dategh fzf release --exclude-drafts --exclude-pre-releases
label
gh fzf label [flags]
labels
, --label
, --labels
gh label list --help
for available optionsenter
: Print the name of the selected label(s) to stdoutalt-n
: Edit the name of the most recently selected label (see gh label edit --help
)alt-d
: Edit the description of the most recently selected labelgh label edit --help
)alt-c
: Edit the color of the mostly recently selected label (see gh label edit --help
)alt-X
: Delete the most recently selected label (see gh label delete --help
)alt-N
: Filter the list, sorting labels by name (defaults to creation date)alt-D
: Filter the list, showing labels in descending ordergh fzf label --sort name --order desc
milestone
gh fzf milestone
milestones
, --milestone
, --milestones
enter
: Print the name of the selected milestone to stdoutalt-t
: Edit the title of the selected milestonealt-d
: Edit the description of the selected milestonealt-X
: Close the selected milestonealt-O
: Reopen the selected milestonealt-s
: Filter the list, showing both open and closed milestonesalt-c
: Filter the list, sorting milestones by completenessalt-D
: Filter the list, showing milestones in descending orderrepo
gh fzf repo [flags]
repos
, --repo
, --repos
gh repo list --help
for available optionsalt-i
: Run gh fzf issue
on the selected repo (see issue
)alt-p
: Run gh fzf pr
on the selected repo (see pr
)alt-r
: Run gh fzf run
on the selected repo (see run
)enter
: Edit the selected repo's settings (see gh repo edit --help
)alt-C
: Clone the selected repo (see gh repo clone --help
)alt-F
: Fork the selected repo (see gh repo fork --help
)alt-c
: Filter the list, showing private repos (i.e. closed source)alt-o
: Filter the list, showing public repos (i.e. open source)alt-f
: Filter the list, showing forked reposalt-s
: Filter the list, showing source (non-forked) reposgh fzf repo --no-archived --visibility private --topic cli
gh fzf repo google --archived --language typescript
gist
gh fzf gist [flags]
gists
, --gist
, --gists
gh gist list --help
for available optionsenter
: Edit the selected gist (see gh gist edit --help
)alt-c
: Clone the selected gist to the current directorygh gist clone --help
)alt-X
: Delete the selected gist (see gh gist delete --help
)alt-s
: Filter the list, showing only secret gistsalt-p
: Filter the list, showing only public gistsgh fzf gist --public
Environment variables are used to configure gh-fzf
.
Variable | Description | Default |
---|---|---|
GH_FZF_DEFAULT_LIMIT |
The initial number of items to request from GitHub. The number of items can be changed at runtime with the alt-1 to alt-9 commands, see the Usage section for more info. |
75 |
GH_FZF_TRUNCATE_FIELDS |
Set the variable to any value to make gh truncate text to ensure all fields fit on the screen. When set, truncated text is not fuzzy findable. When unset, fields may be cut off, but all text is still fuzzy findable. |
unset |
GH_FZF_HIDE_HINTS |
Set the variable to any value to hide the header (where the keybinding hints are) on startup. The header can still be toggled with the alt-H keybinding. |
unset |
GH_FZF_BRANCH_PREFIX |
A string to prepend to the branch name entered for the pr command's alt-o keybinding. Spaces are replaced with hyphens. See the commit message for examples. |
unset |
GH_FZF_BRANCH_ADD_ISSUE_NUMBER |
When set, the issue number is added after the prefix (if specified) for the pr command's alt-o keybinding. The variable's value is added after the number, unless it is a space. See the commit message for examples. |
unset |
GH_FZF_NOTIFY_ICON |
A path to an icon for the desktop notification displayed by the run command's alt-n keybinding. Only supported by dunstify and notify-send for now. |
unset |
GH_FZF_COPY_CMD |
The command used by your operating system to copy an item's URL to the clipboard. Expects the URL from stdin. This only needs to be set if the default doesn't work on your machine. | see code |
You can also set the FZF_DEFAULT_OPTS
environment variable to add/change fzf
options used by gh-fzf
commands.
For example, create aliases in the gh
config file that add new keybindings to
the issue
, pr
, run
, and milestone
commands:
# ~/.config/gh/config.yml
aliases:
i: |
!FZF_DEFAULT_OPTS="$FZF_DEFAULT_OPTS
--bind='alt-+:execute(gh issue edit --add-assignee @me {1})'
--bind='alt--:execute(gh issue edit --remove-assignee @me {1})'
--bind='alt-@:execute(
selected=\"\$(gh fzf milestone)\"
[ -n \"\$selected\" ] && gh issue edit --milestone \"\$selected\" {1}
)'
" gh fzf issue $*
p: |
!FZF_DEFAULT_OPTS="$FZF_DEFAULT_OPTS
--bind='alt-+:execute(gh pr review --approve --body \":+1:\" {1})'
--bind='alt--:execute(gh pr review --request-changes {1})'
--bind='alt-m:execute(gh pr merge --delete-branch --squash {1})'
" gh fzf pr $*
r: |
!FZF_DEFAULT_OPTS="$FZF_DEFAULT_OPTS
--bind='alt-e:execute(gh run view --log-failed {-1})'
--bind='alt-q:reload(eval \"\$FZF_DEFAULT_COMMAND --status queued\")'
" gh fzf run $*
m: |
!FZF_DEFAULT_OPTS="$FZF_DEFAULT_OPTS
--bind='alt-bspace:execute(
gh api --silent --method DELETE /repos/{owner}/{repo}/milestones/{-1}
)+reload(eval \"\$FZF_DEFAULT_COMMAND\")'
" gh fzf milestone
When adding or modifying fzf keybindings:
{1}
in place of:
{-1}
in place of:
For a list of the fzf options shared by all gh-fzf
commands, see the
source code.
[!WARNING] If any of the shared keybindings set by
gh-fzf
don't work, you may be overriding them in your shell's start up scripts (e.g.~/.bashrc
) by setting the$FZF_DEFAULT_OPTS
environment variable.
There is another fzf
wrapper around gh
that also provides some git
functionality. However, it doesn't provide as many gh
commands, keybindings,
or configuration options.
The main focus of gh-fzf
is providing keybindings to run gh
subcommands on
the selected item, so git
functionality is left to other tools. The
following fzf
wrappers around git
are good options to bridge that gap.