Dashboard Configuration (gh-dash
)
Settings for the GitHub Dashboard.
JSON Schema
Definition
{
"$id": "https://dlvhdr.github.io/gh-dash/configuration/gh-dash/schema.json",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "Settings for the GitHub Dashboard.\n\nhttps://dlvhdr.github.io/gh-dash/configuration/gh-dash/",
"properties": {
"defaults": {
"$ref": "https://dlvhdr.github.io/gh-dash/configuration/defaults/schema.json"
},
"issuesSections": {
"default": [
{
"filters": "is:open author:@me",
"title": "My Issues"
},
{
"filters": "is:open assignee:@me",
"title": "Assigned"
},
{
"filters": "is:open involves:@me -author:@me",
"title": "Involved"
}
],
"description": "Define sections for the dashboard's Issues view.\n\nhttps://dlvhdr.github.io/gh-dash/configuration/gh-dash/#issuesSections",
"items": {
"$ref": "https://dlvhdr.github.io/gh-dash/configuration/issue-section/schema.json"
},
"title": "Issue Sections",
"type": "array"
},
"keybindings": {
"description": "Define keybindings to run shell commands.\n\nhttps://dlvhdr.github.io/gh-dash/configuration/gh-dash/#keybindings",
"examples": [
{
"issues": [
{
"command": "gh issue pin {{ .IssueNumber }} --repo {{ .RepoName }}",
"key": "P"
}
]
},
{
"prs": [
{
"command": "tmux new-window -c {{.RepoPath}} '\n gh pr checkout {{.PrNumber}} \u0026\u0026\n nvim -c \":DiffviewOpen master...{{.HeadRefName}}\"\n'\n",
"key": "c"
},
{
"command": "cd {{.RepoPath}} \u0026\u0026 code . \u0026\u0026 gh pr checkout {{.PrNumber}}\n",
"key": "v"
}
]
}
],
"properties": {
"issues": {
"$ref": "https://dlvhdr.github.io/gh-dash/configuration/keybindings/issues/schema.json"
},
"prs": {
"$ref": "https://dlvhdr.github.io/gh-dash/configuration/keybindings/prs/schema.json"
}
},
"title": "Keybindings",
"type": "object"
},
"pager": {
"description": "Specify the pager settings to use in the dashboard.\n\nhttps://dlvhdr.github.io/gh-dash/configuration/gh-dash/#pager",
"properties": {
"diff": {
"anyOf": [
{
"type": "string"
},
{
"enum": [
"less",
"delta"
]
}
],
"default": "less",
"description": "Specifies the pager to use when diffing.\n\nhttps://dlvhdr.github.io/gh-dash/configuration/gh-dash/#diff",
"title": "Diff Pager",
"type": "string"
}
},
"title": "Pager",
"type": "object"
},
"prSections": {
"default": [
{
"filters": "is:open author:@me",
"title": "My Pull Requests"
},
{
"filters": "is:open review-requested:@me",
"title": "Needs My Review"
},
{
"filters": "is:open involves:@me -author:@me",
"title": "Involved"
}
],
"description": "Define sections for the dashboard's PR view.\n\nhttps://dlvhdr.github.io/gh-dash/configuration/gh-dash/#prSections",
"items": {
"$ref": "https://dlvhdr.github.io/gh-dash/configuration/pr-section/schema.json"
},
"title": "Pull Request Sections",
"type": "array"
},
"repoPaths": {
"description": "Key-value pairs that match repositories to local file paths.\n\nhttps://dlvhdr.github.io/gh-dash/configuration/gh-dash/#repoPaths",
"examples": [
{
"dlvhdr/*": "~/code/repos/*",
"dlvhdr/gh-dash": "~/code/gh-dash"
}
],
"patternProperties": {
"\\*$": {
"description": "If the repo name (key) includes an asterisk, the path (value) must too.\n\nhttps://dlvhdr.github.io/gh-dash/configuration/gh-dash/#\\*$",
"pattern": "\\*$",
"title": "With a Wildcard",
"type": "string"
},
"^[^\\*]+$": {
"description": "If the repo name (key) doesn't include an asterisk, the path (value) can't either.\n\nhttps://dlvhdr.github.io/gh-dash/configuration/gh-dash/#^[^\\*]+$",
"pattern": "^[^\\*]+$",
"title": "Without a Wildcard",
"type": "string"
}
},
"title": "Repo Path Map",
"type": "object"
},
"theme": {
"$ref": "https://dlvhdr.github.io/gh-dash/configuration/theme/schema.json"
}
},
"title": "Dashboard Configuration",
"type": "object"
}
Pull Request Sections (prSections
)
The prSections
setting defines one or more sections to display in the dashboard’s PRs
view as tabs. Each section needs a title, which is displayed as the tab name for the
section, and a GitHub search filter. The dashboard queries GitHub with the search filter
to populate the list of PRs to display for that section.
For more information about defining a PR section, see PR Section Options.
<h3 id="prsections.default">Default Value</h3>
- filters: is:open author:@me
title: My Pull Requests
- filters: is:open review-requested:@me
title: Needs My Review
- filters: is:open involves:@me -author:@me
title: Involved
By default, the PRs view on the dashboard has three sections:
The
section fetches open PRs authored by you.The
section fetches open PRs where you are a requested reviewer.The
section fetches open PRs authored by someone else and that meet at least one of the following criteria:- The PR is assigned to you.
- The PR's body, a comment on the PR, or one of the PR's commit messages mentions you.
- You commented on the PR.
Issue Sections (issuesSections
)
The issueSections
setting defines one or more sections to display in the dashboard’s
Issues view as tabs. Each section needs a title, which is displayed as the tab name for the
section, and a GitHub search filter. The dashboard queries GitHub with the search filter
to populate the list of issues to display for that section.
For more information about defining an issue section, see Issue Section Options.
<h3 id="issuessections.default">Default Value</h3>
- filters: is:open author:@me
title: My Issues
- filters: is:open assignee:@me
title: Assigned
- filters: is:open involves:@me -author:@me
title: Involved
By default, the Issues view on the dashboard has three sections:
The
section fetches open issues authored by you.The
section fetches open issues assigned to you.The
section fetches open issues authored by someone else and that meet at least one of the following criteria:- The issue is assigned to you.
- The issue's body or a comment on the issue mentions you.
- You commented on the issue.
Default Options (defaults
)
These settings define the default behavior for the dashboard. You can override many of these settings on a per-section basis.
For more information, see Default Options
Repo Path Map (repoPaths
)
You can use the repoPaths
setting to map repository names (as keys) to local paths
(as values). This map coonfigures where to locate repositories when checking out PRs.
The mappings can be exact matches, like the full name or path of a repository, or wildcard
matches using the owner
and a partial path.
An exact match for the full repository name to a full path takes priority over a matching wildcard. Wildcard keys must match to a wildcard path.
The RepoName
and RepoPath
keybinding arguments are fully expanded when sent to the
command.
<h3 id="repopaths.examples">Examples</h3>
<h4 id="repopaths.examples.matching-repositories">Matching Repositories</h4>
dlvhdr/*: ~/code/repos/*
dlvhdr/gh-dash: ~/code/gh-dash
In this example, the first key is defined with a wildcard (*
) as dlvhdr/*
, so the
dashboard will use this entry to resolve the path for any repo in the dlvhdr
namespace, like [dlvhdr/jb
] or [dlvhdr/harbor
]. Note that the value for this key
also uses a wildcard. If the key specifies a wildcard, the value must specify one too.
If a repository in the dlvhdr
namespace has been cloned into the ~/code/repos
folder, the dashboard will be able to checkout PRs for that repository locally.
If the repository isn't found, the [checkout command] raises an error.
The second key defines an exact mapping between the dlvhdr/gh-dash
repository and the
~/code/gh-dash
folder. Because this is a non-wildcard mapping, the dashboard will use
this value to resolve the repository path for dlvhdr/gh-dash
even though there's also
an entry for dlvhdr/*
.
Pattern Properties
With a Wildcard
If the key for an repoPath
entry ends with a wildcard (*
), its value must also have
a wildcard. If a key ends with a wildcard but the value doesn’t, gh-dash
won’t be
able to correctly map repositories to folders.
Without a Wildcard
If the key for an repoPath
entry doesn’t have a wildcard (*
), its value must not
have a wildcard. If a key ends without a wildcard but the value does, gh-dash
won’t
be able to correctly map repositories to folders.
Keybindings (keybindings
)
Define your own custom keybindings to run shell commands using [Go templates]. You can define your keybindings for the PRs and Issues views separately.
<h3 id="keybindings.examples">Examples</h3>
<h4 id="keybindings.examples.pin-an-issue">Pin an Issue</h4>
issues:
- command: gh issue pin {{ .IssueNumber }} --repo {{ .RepoName }}
key: P
This example binds P in the Issues view of the dashboard to the
gh issue pin
command to pin the selected issue in the repository.
<h4 id="keybindings.examples.review-prs">Review PRs</h4>
prs:
- command: |
tmux new-window -c {{.RepoPath}} '
gh pr checkout {{.PrNumber}} &&
nvim -c ":DiffviewOpen master...{{.HeadRefName}}"
'
key: c
- command: |
cd {{.RepoPath}} && code . && gh pr checkout {{.PrNumber}}
key: v
This example binds c and v in the PRs view of the dashboard to checkout the selected PR and open the repository in Neovim and VS Code respectively.
The Neovim keybinding opens the editor in another tmux
window.
PRs Commands (prs
)
Define any number of keybindings for the PRs view.
The available arguments are:
Argument | 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 |
For more information, see PRs Commands
Issues Commands (issues
)
Define any number of keybindings for the Issues view.
The available arguments are:
Argument | 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 |
IssueNumber | The Issue number |
For more information, see Issues Commands
Theme Options (theme
)
This setting defines the dashboard’s theme. It only effects the presentation of the dashboard,
not the data. Currently, the theme only defines colors. To control how table columns and
preview pane display for the views, use the defaults
, prSections
, and
issueSections
settings.
The default colors for the theme in the schema are for dark mode terminals. The dashboard actually has different defaults for light mode terminals, but the schema can’t represent a dynamic default. The informational text for each color also enumerates the light mode color.
To define any color for your dashboard, you must define every color. All properties are
required properties. Every color for the dashboard’s theme must be a valid hex color, like
#a3c
or #aa33cc
.
To find hex colors to use in your dashboard, visit color-hex.com
. You can browse colors,
inspect a given color, get alternate shades and tints for a color, derive a color palette, and
more.
For more information, see Theme Options
Pager (pager
)
Specify the pager settings to use in the dashboard.
Diff Pager (diff
)
Specifies the pager to use when diffing.