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-notifyTo use gh notify interactively, install these tools as well:
- Fuzzy Finder (fzf) - This allows for interaction with listed data.
- Python - In cases where
ghcan't open theURLin 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 5You 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 notifyOr, switch the binding for toggling a notification and toggling the preview.
GH_NOTIFY_TOGGLE_KEY="tab" GH_NOTIFY_TOGGLE_PREVIEW_KEY="ctrl-y" gh notifyNOTE: The assigned key must be a valid key listed in the fzf man page:
man --pager='less -p "^\s AVAILABLE_KEYS"' fzfIn 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