jackwiy / gh-dash

A beautiful CLI dashboard for GitHub 🚀

gh-dash

✨ A GitHub (gh) CLI extension to display a dashboard with pull requests and issues by filters you care about.

Installation

1. Install the gh CLI - see the installation

   Installation requires a minimum version (2.0.0) of the the GitHub CLI that supports extensions.

2. Install this extension:

   gh extension install dlvhdr/gh-dash

3. To get the icons to render properly you should download and install a Nerd font from https://www.nerdfonts.com/. Then, select that font as your font for the terminal.

Installing Manually

If you want to install this extension manually, follow these steps:

1. Clone the repo

   # git
   git clone https://github.com/dlvhdr/gh-dash
   
   # GitHub CLI
   gh repo clone dlvhdr/gh-dash

2. Cd into it

   cd gh-dash

3. Install it locally

   gh extension install .

🌈 How do I get these exact colors and font?

I'm using Alacritty with the tokyonight theme and the Fira Code Nerd Font. For my full setup check out my dotfiles.

Configuring

Configuration is provided within a config.yml file under the extension's directory (usually ~/.config/gh-dash/)

An example config.yml file contains:

prSections:
  - title: My Pull Requests
    filters: is:open author:@me
  - title: Needs My Review
    filters: is:open review-requested:@me
  - title: Subscribed
    filters: is:open -author:@me repo:cli/cli repo:dlvhdr/gh-dash
    limit: 50 # optional limit per section
issuesSections:
  - title: Created
    filters: is:open author:@me
  - title: Assigned
    filters: is:open assignee:@me
  - title: Subscribed
    filters: is:open -author:@me repo:microsoft/vscode repo:dlvhdr/gh-dash
defaults:
  prsLimit: 20 # global limit
  issuesLimit: 20 # global limit
  preview:
    open: true
    width: 60
repoPaths:
  dlvhdr/*: ~/code/repos/*       # will match dlvhdr/repo-name to ~/code/repos/repo-name
  dlvhdr/gh-dash: ~/code/gh-dash # will not match wildcard and map to specified path
keybindings: # optional
  prs:
    - key: c
      command: cd {{.RepoPath}}; gh pr checkout {{.PrNumber}}

Adding a PR or issue section is as easy as adding to the list of prSections or issueSections respectively:

• title - shown in the TUI
• filters - how the repo's PRs should be filtered - these are plain github filters

Keybindings

Define your own custom keybindings to run bash commands using Go Templates. The available arguments are:

Arguement	Description
RepoName	The full name of the repo (e.g. dlvhdr/gh-dash)
RepoPath	The path to the Repo, using the config.yml repoPaths key to get the mapping
PrNumber	The PR number
HeadRefName	The PR's remote branch name

Repo Path Matching

Repo name to path mappings can be exact match (full name, full path) or wildcard matched using the owner and partial path.

An exact match for the full repo name to a full path takes priority over a matching wildcard, and wildcard matches must match to a wildcard path.

repoPaths:
  dlvhdr/*: ~/code/repos/*       # will match dlvhdr/repo-name to ~/code/repos/repo-name
  dlvhdr/gh-dash: ~/code/gh-dash # will not match wildcard and map to specified path

The RepoName and RepoPath keybinding arguments are fully expanded when sent to the command.

Keybindings Examples

To review a PR with either Neovim or VSCode, include this in your config.yml file:

repoPaths:
  dlvhdr/gh-dash: ~/code/gh-dash

keybindings:
  prs:
    - key: c
      command: >
        tmux new-window -c {{.RepoPath}} '
          gh pr checkout {{.PrNumber}} &&
          nvim -c ":DiffviewOpen master...{{.HeadRefName}}"
        '
    - key: v
      command: >
        cd {{.RepoPath}} &&
        code . &&
        gh pr checkout {{.PrNumber}}

Custom Themes

To override the default set of terminal colors and instead create your own color scheme, you can define one in your config.yml file. If you choose to go this route, you need to specify all of the following keys as colors in hex format (#RRGGBB), otherwise validation will fail.

theme:
  colors:
    text:
      primary: "#E2E1ED"
      secondary: "#666CA6"
      inverted: "#242347"
      faint: "#3E4057"
      warning: "#F23D5C"
      success: "#3DF294"
    background:
      selected: "#39386B"
    border:
      primary: "#383B5B"
      secondary: "#39386B"
      faint: "#2B2B40"

Usage

Run:

gh dash

Then press ? for help.

Author

Dolev Hadar [email protected]