An fzf wrapper around the GitHub CLI.
-
Install
gh
andfzf
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
You can also pin a version tag when installing an extension. If you already have
gh-fzf
installed, you need to remove it first before pinning a version:
gh extension remove gh-fzf &&
gh extension install benelan/gh-fzf --pin "v0.7.0"
There is also a stable
tag, which always points to the latest release.
See the changelog for a list of features and fixes released in each version.
To check which version you currently have installed:
gh fzf -v
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 from GitHubalt-1
toalt-9
: Change the number of items fetched from GitHub to 100, 200, ..., 900alt-P
: Toggle the preview windowalt-H
: Toggle the header display, where the keybinding hints are located
- Usage:
gh fzf issue [flags]
- Aliases:
i
,issues
,-i
,--issue
,--issues
- Flags: See
gh issue list --help
for available options - Keybindings:
enter
: Edit the selected issue in the CLI via prompts (seegh issue edit --help
)alt-o
: Checkout the linked branch of the selected issue, creating one if necessary (seegh issue develop --help
)alt-c
: Add a comment to the selected issue (seegh issue comment --help
)alt-l
: Opengh fzf label
and add the label to the selected issue (seegh issue edit --help
)alt-L
: Opengh fzf label
and remove the label from the selected issue (seegh issue edit --help
)alt-X
: Close the selected issue (seegh issue close --help
)alt-O
: Reopen the selected issue (seegh 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)
- Examples:
- Filter the initial list to open and closed issues assigned to you in the
"v1.33.7" milestone:
gh fzf issue --assignee @me --milestone "v1.33.7" --state all
- Filter the initial list to issues with the "good first issue" label, no
assignee, and in the "backburner" milestone. Uses GitHub's search syntax:
gh fzf i -S \'no:assignee label:\"good first issue\" milestone:backburner\'
- Filter the initial list to open and closed issues assigned to you in the
"v1.33.7" milestone:
- Usage:
gh fzf pr [flags]
- Aliases:
p
,prs
,-p
,--pr
,--prs
- Flags: See
gh pr list --help
for available options - Keybindings:
enter
: Edit the selected pull request in the CLI via prompts (seegh pr edit --help
)alt-o
: Checkout the branch of the selected pull request (seegh pr checkout --help
)alt-c
: Add a comment to the selected pull request (seegh issue comment --help
)alt-d
: Show the diff for the selected pull request (seegh pr diff --help
)alt-r
: Start/continue/finish a review for the selected pull request (seegh pr review --help
)alt-l
: Opengh fzf label
and add the label to the selected pull request (seegh issue edit --help
)alt-L
: Opengh fzf label
and remove the label from the selected pull request (seegh issue edit --help
)alt-R
: Mark the selected draft pull request as "ready for review" (seegh pr ready --help
)alt-M
: Merge the selected pull request (seegh pr merge --help
)alt-X
: Close the selected pull request (seegh pr close --help
)alt-O
: Reopen the selected pull request (seegh pr reopen --help
)alt-C
: Opengh fzf run
filtered for the selected pull request (see run)alt-a
: Filter the list, showing pull requests assigned to youalt-A
: Filter the list, showing pull requests authored by youalt-b
: Filter the list, showing pull requests from the current branchalt-s
: Filter the list, showing pull requests with any state (open, closed, or merged)
- Examples:
- Filter the initial list to your merged pull requests with the
"breaking change" label:
gh fzf pr --state merged --author @me --label \"breaking change\"
- Filter the initial list to your pull requests merged since the beginning
of 2023 that have "breaking change" in the body. Uses
GitHub's search syntax:
gh fzf p -S \'merged:">=2023-01-01" \"breaking change\" in:body author:@me\'
- Filter the initial list to your merged pull requests with the
"breaking change" label:
- Usage:
gh fzf run [flags]
- Aliases:
r
,runs
,-r
,--run
,--runs
- Flags: See
gh run list --help
for available options - Keybindings:
enter
: Watch the status updates for the selected run (seegh run watch --help
)alt-l
: Display the logs for the selected run (seegh run view --help
)alt-d
: Download artifacts from the selected run (seegh run download --help
)alt-r
: Rerun the selected run (seegh run rerun --help
)alt-x
: Cancel the selected run (seegh run cancel --help
)alt-p
: Opengh fzf pr
filtered for the selected run's branch as head (seepr
)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 runs
- Examples:
- Filter the initial list to runs for the "tests" workflow:
gh fzf run --workflow tests
- Filter the initial list to failed runs on the main branch:
gh fzf r -b main -s failure
- Filter the initial list to runs for the "tests" workflow:
- Usage:
gh fzf workflow [flags]
- Aliases:
workflows
,--workflow
,--workflows
- Flags: See
gh workflow list --help
for available options - Keybindings:
enter
: Opengh fzf run
filtered for the selected workflow (seerun
)alt-d
: Create aworkflow_dispatch
event for the selected workflow (seegh workflow run --help
)alt-X
: Disable the selected workflow (seegh workflow disable --help
)alt-E
: Enable the selected workflow (seegh workflow enable --help
)alt-a
: Filter the list, showing all workflows (including disabled ones)
- Examples:
- Filter the initial list to show all workflows:
gh fzf workflow --all
- Filter the initial list to show all workflows:
- Usage:
gh fzf release [flags]
- Aliases:
releases
,--release
,--releases
- Flags: See
gh release list --help
for available options - Keybindings:
enter
: Download the assets for the selected release (seegh release download --help
)alt-X
: Delete the selected release (seegh release delete --help
)alt-s
: Filter the list, showing stable releases (i.e. excluding pre-releases)alt-p
: Filter the list, showing published releases (i.e. excluding drafts)alt-a
: Filter the list, showing releases in ascending order by release date (defaults to descending)
- Examples:
- Filter the initial list to exclude drafts and pre-releases:
gh fzf release --exclude-drafts --exclude-pre-releases
- Filter the initial list to exclude drafts and pre-releases:
- Usage:
gh fzf label [flags]
- Aliases:
labels
,--label
,--labels
- Flags: See
gh label list --help
for available options - Keybindings:
enter
: Print the name of the selected labelalt-n
: Edit the name of the selected label (seegh label edit --help
)alt-d
: Edit the description of the selected label (seegh label edit --help
)alt-c
: Edit the color of the selected label (seegh label edit --help
)alt-X
: Delete the selected label (seegh 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 order (defaults to ascending)
- Examples:
- Filter the initial list to sort by label name in descending order
gh fzf label --sort name --order desc
- Filter the initial list to sort by label name in descending order
- Usage:
gh fzf repo [flags]
- Aliases:
repos
,--repo
,--repos
- Flags: See
gh repo list --help
for available options - Keybindings:
alt-i
: Rungh fzf issue
on the selected repo (seeissue
)alt-p
: Rungh fzf pr
on the selected repo (seepr
)alt-r
: Rungh fzf run
on the selected repo (seerun
)enter
: Edit the selected repo's settings (seegh repo edit --help
)alt-C
: Clone the selected repo (seegh repo clone --help
)alt-F
: Fork the selected repo (seegh repo fork --help
)alt-c
: Filter the list, showing private reposalt-o
: Filter the list, showing public reposalt-f
: Filter the list, showing forked reposalt-s
: Filter the list, showing source (non-forked) repos
- Examples:
- Filter the initial list to non-archived, private repos created by you with
the "cli" topic:
gh fzf repo --no-archived --visibility private --topic cli
- Filter the initial list to archived repos created by the "google"
organization where the primary language was "typescript":
gh fzf repo google --archived --language typescript
- Filter the initial list to non-archived, private repos created by you with
the "cli" topic:
- Usage:
gh fzf gist [flags]
- Aliases:
gists
,--gist
,--gists
- Flags: See
gh gist list --help
for available options - Keybindings:
enter
: Edit the selected gist (seegh gist edit --help
)alt-c
: Clone the selected gist to the current directory (seegh gist clone --help
)alt-X
: Delete the selected gist (seegh gist delete --help
)alt-s
: Filter the list, showing only secret gistsalt-p
: Filter the list, showing only public gists
- Examples:
- Filter the initial list to only show public gists (excluding secret ones):
gh fzf gist --public
- Filter the initial list to only show public gists (excluding secret ones):
Environment variables are used to configure different options in 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. |
69 |
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_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 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 and pr 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})'
" 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 $*
When adding or modifying fzf keybindings:
- Use
{1}
in place of:- the
<number>
for theissue
andpr
commands - the
<tag>
for therelease
command - the
<id>
for thegist
command - the
<name>
for thelabel
command
- the
- Use
{-1}
in place of:- the
<run-id>
for therun
command - the
<workflow-id>
for theworkflow
command
- the
For a list of the fzf options shared by all gh-fzf
commands, see the
source code.
NOTE: If any of the 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.
gh-f
: anotherfzf
wrapper aroundgh
that also provides somegit
functionality.
NOTE: gh-fzf
leaves git
functionality to other tools, and instead
focuses on providing keybindings to run gh
subcommands on the selected item.
The following fzf
wrappers around git
are both good options to bridge that
gap: