An fzf wrapper around the GitHub CLI.

• gh fzf
  • Installation
    • Upgrading
  • Usage
    • issue
    • pr
    • run
    • workflow
    • release
    • label
    • milestone
    • repo
    • gist
  • Configuration
  • Related projects

1. 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

2. Authenticate with the GitHub CLI:

   gh auth login

3. Install this extension:

   gh extension install benelan/gh-fzf

4. ???

5. PROFIT

To upgrade gh-fzf to the latest commit on main (recommended):

gh extension upgrade gh-fzf

Alternatively, you can pin a tag when installing gh extensions. If you already have gh-fzf installed, you need to remove it first before pinning a version:

gh extension remove fzf && gh extension install benelan/gh-fzf --pin "v0.8.0"

There is also a stable tag, which always points to the latest release.

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

To see the version of gh-fzf 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 browser
• ctrl-y: Copy the selected item's URL to the clipboard
• ctrl-r: Reload the list to its initial filter state and fetch changes from GitHub
• alt-1 to alt-9: Change the number of items fetched from GitHub to 100, 200, ..., 900
• alt-P: Toggle the preview window display
• alt-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 via CLI prompts (see gh issue edit --help)
  • alt-o: Create/checkout a branch linked to the selected issue, prompting for the name (see gh 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 issue
  • alt-L: Open gh fzf label and remove the selected label(s) from the issue
  • alt-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 you
  • alt-A: Filter the list, showing issues authored by you
  • alt-m: Filter the list, showing issues where you are mentioned
  • alt-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\'

• 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 PR via CLI prompts (see gh pr edit --help)
  • alt-o: Checkout the HEAD branch of the selected PR (see gh 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 PR (see gh pr review --help)
  • alt-y: Copy the branch name of the selected PR
  • alt-l: Open gh fzf label and add the selected label(s) to the PR
  • alt-L: Open gh fzf label and remove the selected label(s) from the PR
  • alt-R: Mark the selected draft PR as "ready for review" (see 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 you
  • alt-A: Filter the list, showing PRs authored by you
  • alt-b: Filter the list, showing PRs from the current branch
  • alt-s: Filter the list, showing PRs in 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\'

• Usage: gh fzf run [flags]
• Aliases: r, runs, -r, --run, --runs
• Flags: See gh run list --help for available options
• Keybindings:
  • enter: Watch for status updates on the selected run (see gh run watch --help)
  • alt-l: Display logs for the selected run (see gh run view --help)
  • alt-d: Download artifacts from the selected run (see gh run download --help)
  • alt-r: Rerun 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 HEAD (see pr)
  • alt-n: Create a desktop notification with the conclusion (failed, passed, etc.) when the selected run ends. The supported notification tools (tried in order) are dunstify, notify-send, and osascript. The notification has actions for "view logs" and "open in browser" when using dunstify. There is an additional "download artifacts" or "rerun failed jobs" action depending on whether the run passed or failed, respectively.

    NOTE: The run watching process is executed in the background, so closing gh-fzf won't prevent the desktop notification from displaying. Use killall gh to end all gh processes, including the run watcher.

  • alt-b: Filter the list, showing runs from the current branch
  • alt-u: Filter the list, showing runs triggered by you
  • alt-f: Filter the list, showing failed runs
  • alt-i: Filter the list, showing in_progress 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

• Usage: gh fzf workflow [flags]
• Aliases: workflows, --workflow, --workflows
• Flags: See gh workflow list --help for available options
• Keybindings:
  • enter: Open gh fzf run filtered for the selected workflow (see run)
  • 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)
• Examples:
  • Filter the initial list to show all workflows:

    gh fzf workflow --all

• Usage: gh fzf release [flags]
• Aliases: releases, --release, --releases
• Flags: See gh release list --help for available options
• Keybindings:
  • enter: Download the assets from the selected release (see gh 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 date (defaults to descending)
• Examples:
  • Filter the initial list to exclude drafts and pre-releases:

    gh fzf release --exclude-drafts --exclude-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 label(s) to stdout
  • alt-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 label (see gh 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 order (defaults to ascending)
• Examples:
  • Filter the initial list to sort by label name in descending order

    gh fzf label --sort name --order desc

• Usage: gh fzf milestone
• Aliases: milestones, --milestone, --milestones
• Flags: N/A
• Keybindings:
  • enter: Print the name of the selected milestone to stdout
  • alt-t: Edit the title of the selected milestone
  • alt-d: Edit the description of the selected milestone
  • alt-X: Close the selected milestone
  • alt-O: Reopen the selected milestone
  • alt-s: Filter the list, showing both open and closed milestones (defaults to open)
  • alt-c: Filter the list, sorting milestones by completeness (defaults to due date)
  • alt-D: Filter the list, showing milestones in descending order (defaults to ascending)

• Usage: gh fzf repo [flags]
• Aliases: repos, --repo, --repos
• Flags: See gh repo list --help for available options
• Keybindings:
  • alt-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 repos
  • alt-s: Filter the list, showing source (non-forked) repos
• Examples:
  • Filter the initial list to your non-archived, private repos 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

• Usage: gh fzf gist [flags]
• Aliases: gists, --gist, --gists
• Flags: See gh gist list --help for available options
• Keybindings:
  • enter: Edit the selected gist (see gh gist edit --help)
  • alt-c: Clone the selected gist to the current directory (see gh gist clone --help)
  • alt-X: Delete the selected gist (see gh gist delete --help)
  • alt-s: Filter the list, showing only secret gists
  • alt-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

Environment variables are used to configure gh-fzf.

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:

• Use {1} in place of:
  • the <number> for the issue and pr commands
  • the <tag> for the release command
  • the <id> for the gist command
  • the <name> for the label command
• Use {-1} in place of:
  • the <run-id> for the run command
  • the <workflow-id> for the workflow command
  • the <number> for the milestone command

For a list of the fzf options shared by all gh-fzf commands, see the source code.

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.

• gh-f

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.

• forgit
• git-fuzzy