A gh extension to view your GitHub notifications from the command line.
demo.mp4
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 theURL
in your browser, this one-liner is used as a cross-platform solution:python -m webbrowser <URL>
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 |
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 |
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 |
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'"
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
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
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