Skip to content

Latest commit

 

History

History
149 lines (120 loc) · 7.56 KB

readme.md

File metadata and controls

149 lines (120 loc) · 7.56 KB
Raw

GitHub CLI Notification Extension

A gh extension to view your GitHub notifications from the command line.

demo.mp4

Install

Make sure you have GitHub CLI (gh) installed.

# install
gh ext install meiji163/gh-notify
# upgrade
gh ext upgrade meiji163/gh-notify
# uninstall
gh ext remove meiji163/gh-notify

To use gh notify interactively, install these tools as well:

  • Fuzzy Finder (fzf) - This allows for interaction with listed data.
  • Python - In cases where gh can't open the URL in your browser, this one-liner is used as a cross-platform solution: python -m webbrowser <URL>

Usage

gh notify [Flags]
Flags Description Example
show all unread notifications gh notify
-a show all (read/ unread) notifications gh notify -a
-e exclude notifications matching a string (REGEX support) gh notify -e "MyJob"
-f filter notifications matching a string (REGEX support) gh notify -f "Repo"
-h show the help page gh notify -h
-n NUM max number of notifications to show gh notify -an 10
-p show only participating or mentioned notifications gh notify -ap
-r mark all notifications as read gh notify -r
-s print a static display gh notify -an 10 -s
-u URL (un)subscribe a URL, useful for issues/prs of interest gh notify -u https://github.com/cli/cli/issues/659
-w display the preview window in interactive mode gh notify -an 10 -w

Key Bindings fzf

Keys Description Customization Environment Variable
? toggle help GH_NOTIFY_TOGGLE_HELP_KEY
enter view the selected notification in the 'less' pager GH_NOTIFY_VIEW_KEY
tab toggle notification preview GH_NOTIFY_TOGGLE_PREVIEW_KEY
shifttab resize the preview window GH_NOTIFY_RESIZE_PREVIEW_KEY
shift↑↓ scroll the preview up/ down
ctrla mark all displayed notifications as read and reload GH_NOTIFY_MARK_ALL_READ_KEY
ctrlb browser GH_NOTIFY_OPEN_BROWSER_KEY
ctrld view diff GH_NOTIFY_VIEW_DIFF_KEY
ctrlp view diff in patch format GH_NOTIFY_VIEW_PATCH_KEY
ctrlr reload GH_NOTIFY_RELOAD_KEY
ctrlt mark the selected notification as read and reload GH_NOTIFY_MARK_READ_KEY
ctrlx write a comment with the editor and quit GH_NOTIFY_COMMENT_KEY
ctrly toggle the selected notification GH_NOTIFY_TOGGLE_KEY
esc quit

Table Format

Field Description
unread symbol indicates unread status
time time of last read for unread; otherwise, time of last update
repo related repository
type notification type
number associated number
reason trigger reason
title notification title

Customizations

Fuzzy Finder (fzf)

You can customize the fzf key bindings by exporting ENVIRONMENT VARIABLES to your .bashrc or .zshrc. For AVAILABLE KEYS/ EVENTS, refer to the fzf man page or visit junegunn/fzf#environment-variables on GitHub.

# ~/.bashrc or ~/.zshrc
# The examples below enable you to clear the input query with alt+c,
# jump to the first/last result with alt+u/d, refresh the preview window with alt+r
# and scroll the preview in larger steps with ctrl+w/s.
export FZF_DEFAULT_OPTS="
--bind 'alt-c:clear-query'
--bind 'alt-u:first,alt-d:last'
--bind 'alt-r:refresh-preview'
--bind 'ctrl-w:preview-half-page-up,ctrl-s:preview-half-page-down'"

GH_NOTIFY_FZF_OPTS

This environment variable lets you specify additional options and key bindings to customize the search and display of notifications. Unlike FZF_DEFAULT_OPTS, GH_NOTIFY_FZF_OPTS specifically applies to the gh notify extension.

# --exact: Enables exact matching instead of fuzzy matching.
GH_NOTIFY_FZF_OPTS="--exact" gh notify -an 5
# With the height flag and ~, fzf adjusts its height based on input size without filling the entire screen.
# Requires fzf +0.34.0
GH_NOTIFY_FZF_OPTS="--height=~100%" gh notify -an 5

Modifying Keybindings

You can also customize the keybindings created by this extension to avoid conflicts with the ones defined by fzf. For example, change ctrl-p to ctrl-u:

GH_NOTIFY_VIEW_PATCH_KEY="ctrl-u" gh notify

Or, switch the binding for toggling a notification and toggling the preview.

GH_NOTIFY_TOGGLE_KEY="tab" GH_NOTIFY_TOGGLE_PREVIEW_KEY="ctrl-y" gh notify

NOTE: The assigned key must be a valid key listed in the fzf man page:

man --pager='less -p "^\s+AVAILABLE_KEYS"' fzf

GitHub Command Line Tool (gh)

In the gh tool's config file, you can specify your preferred editor. This is particularly useful when you use the ctrlx hotkey to comment on a notification.

# To see more details
gh config
# For example, you can set the editor to Visual Studio Code or Vim.
gh config set editor "code --wait"
gh config set editor vim