This is my current sponsorship goal
Reaching this goal would help me spend more time on my projects and hopefully 🤞🏽
become a full time OSS maintainer one day.
_This is my dream_, to build projects sponsored by individuals with the sole focus on its users - no investors, no line go
up.
## How to Donate?
To become a sponsor go to:
```
/* Detailed source-code truncated for AI context efficiency. */
```
## Theming Example
The color palette in this example is inspired by the [Monokai Pro Spectrum Filter][01] palette.
```yaml
theme:
colors:
text:
primary: "#F7F1FF"
secondary: "#5AD4E6"
inverted: "#F7F1FF"
faint: "#3E4057"
warning: "#FC618D"
success: "#7BD88F"
background:
selected: "#535155"
border:
primary: "#948AE3"
secondary: "#7BD88F"
faint: "#3E4057"
```
[01]: https://www.vscolors.com/themes/f5d7ffda-c1d6-4070-ba80-803c705a1ee6-3ed72ace
## Custom Keybindings Example
Utilizing `tmux` we can launch other TUIs:
```yaml
keybindings:
universal:
- key: g
name: lazygit
command: >
cd {{.RepoPath}} && lazygit
prs:
- key: O
builtin: checkout
- key: m
command: gh pr merge --admin --repo {{.RepoName}} {{.PrNumber}}
- key: C
name: code review
command: >
tmux new-window -c {{.RepoPath}} '
nvim -c ":silent Octo pr edit {{.PrNumber}}"
'
- key: a
name: lazygit add
command: >
cd {{.RepoPath}} && git add -A && lazygit
- key: v
name: approve
command: >
gh pr review --repo {{.RepoName}} --approve --body "$(gum input --prompt='Approval Comment: ')" {{.PrNumber}}
```
## Repo Paths Example
Configure [`repoPaths`](/configuration/repo-paths) in order to check out PRs in
the right git directory.
```yaml
repoPaths:
dlvhdr/*: ~/code/personal/*
my-work-org/*: ~/code/my-work-org/*
charmbracelet/*: ~/code/charm/*
dlvhdr/dotfiles: ~/dotfiles
```
---
### Src Content Docs Configuration Issue Section (`docs/src/content/docs/configuration/issue-section.mdx`)
---
title: Issue Sections
---
# Issues Section Options (`issuesSections`)
Defines a section in the dashboard's issues view.
- Every section must define a [`title`] and [`filters`].
- When you define [`limit`] for a section, that value overrides the
[`defaults.issuesLimit`] setting.
- When you define [`layout`] for a section, that value overrides the
[`defaults.layout.issue`] setting.
[`title`]: #issues-title-title
[`filters`]: #issues-filters-filters
[`limit`]: #issues-fetch-limit-limit
[`layout`]: #issues-section-layout-layout
[`defaults.issuesLimit`]: /configuration/defaults/#issue-fetch-limit-issueslimit
[`defaults.layout.issue`]: /configuration/defaults/#layout-options-layout
## Issues Title (`title`)
This setting defines the section's name. The dashboard displays this value in the tabs for
the issues view.
## Issues Filters (`filters`)
This setting defines the [GitHub search filters][01] for the Issues in the section's table.
Don't specify `is:issue` for this setting. The dashboard always adds that filter for Issues
sections.
Note issues from archived repositories are excluded by default with `archived:false`.
You can define any combination of search filters. To make it easier to read and maintain
your filters, we recommend using the `>-` syntax after the `filter` key and writing one
filter per line.
For example:
```yaml
- # Involved
filter: >-
is:open
involves:@me
-author:@me
updated:>={{ nowModify "-2w" }}
```
For more information about writing filters for searching GitHub, see [Searching].
[Searching]: /configuration/searching
## Issues Section Layout (`layout`)
You can define how a Issues section displays items in its table by setting options for the
available columns. You can define a column's width, whether it grows to fill available space,
and whether the column should be visible at all.
Note that if the length of a column's text exceeds the defined column [`width`], the view
truncates the column's text to two characters shorter than the column's width. For example, if
the width is `6`, `gh-dash` displays as `gh-d`.
Column headings have their color defined by the [`theme.colors.text.issueimary`] setting.
[`width`]: /configuration/layout/options#layout-options-width
[`theme.colors.text.issueimary`]: /configuration/theme
## Issues Fetch Limit (`limit`)
| Type | Minimum | Default |
| :------ | :-----: | :-----: |
| Integer | 1 | 20 |
This setting defines how many Issues the dashboard should fetch for the section when:
- The dashboard first loads.
- The [fetch interval] elapses.
- You navigate to the next issue in a table without another fetched issue to display.
- You use the [refresh current section] or [refresh all sections] commands.
This setting overrides the [`defaults.issuesLimit`] setting.
[01]: https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests
[fetch interval]: /configuration/defaults/#refetch-interval-in-minutes-refetchintervalminutes
[refresh current section]: /getting-started/keybindings/global/#r---refresh-current-section
[refresh all sections]: /getting-started/keybindings/global/#r---refresh-all-sections
[`defaults.issuesLimit`]: /configuration/defaults/#issue-fetch-limit
---
### Src Content Docs Configuration Notification Section (`docs/src/content/docs/configuration/notification-section.mdx`)
---
title: Notification Sections
---
# Notification Section Options (`notificationsSections`)
Defines sections in the dashboard's Notifications view.
- Every section must define a [`title`] and [`filters`].
- When you define [`limit`] for a section, that value overrides the
[`defaults.notificationsLimit`] setting.
[`title`]: #notification-title-title
[`filters`]: #notification-filters-filters
[`limit`]: #notification-fetch-limit-limit
[`defaults.notificationsLimit`]: /configuration/defaults/#notifications-fetch-limit-notificationslimit
## Search Section
The Notifications view includes a search section (indicated by a magnifying glass icon) as the first tab. This serves as a scratchpad for one-off searches without modifying your configured sections.
- Default filter: `archived:false`
- Respects `smartFilteringAtLaunch`: when enabled and running from a git repository, the search automatically scopes to that repo
- Use the `/` key to focus the search bar and enter custom queries
## Default Sections
By default, the dashboard includes these notification sections:
```yaml
notificationsSections:
- title: All
filters: ""
- title: Created
filters: "reason:author"
- title: Participating
filters: "reason:participating"
- title: Mentioned
filters: "reason:mention"
- title: Review Requested
filters: "reason:review-requested"
- title: Assigned
filters: "reason:assign"
- title: Subscribed
filters: "reason:subscribed"
- title: Team Mentioned
filters: "reason:team-mention"
```
You can customize these by defining your own `notificationsSections` in your config file.
## Notification Title (`title`)
This setting defines the section's name. The dashboard displays this value in the tabs for
the Notifications view.
## Notification Filters (`filters`)
This setting defines the filters for notifications in the section's table. Notification filters differ from PR and Issue filters because they use client-side filtering.
### Available Filters
#### Read State Filters
| Filter | Description |
|--------|-------------|
| `is:unread` | Show only unread notifications |
| `is:read` | Show only read notifications |
| `is:all` | Show both read and unread notifications |
| `is:done` | Show archived/done notifications |
#### Reason Filters
| Filter | Description |
|--------|-------------|
| `reason:author` | Activity on threads you created |
| `reason:comment` | Someone commented on a thread you're subscribed to |
| `reason:mention` | You were @mentioned |
| `reason:review-requested` | Your review was requested on a PR |
| `reason:assign` | You were assigned |
| `reason:subscribed` | Activity on threads you're watching |
| `reason:team-mention` | Your team was @mentioned |
| `reason:state-change` | Thread state changed (merged, closed, etc.) |
| `reason:ci-activity` | CI workflow activity |
| `reason:participating` | Meta-filter that expands to: author, comment, mention, review-requested, assign, state-change |
#### Repository Filters
| Filter | Description |
|--------|-------------|
| `repo:owner/name` | Show notifications only from the specified repository |
### Filter Examples
```yaml
# Show only notifications where you were mentioned
- title: Mentioned
filters: "reason:mention"
# Show unread notifications from a specific repo
- title: My Project
filters: "is:unread repo:myorg/myproject"
# Show notifications where you're actively participating
- title: Participating
filters: "reason:participating"
# Combine multiple reason filters
- title: Review & Mentions
filters: "reason:review-requested reason:mention"
```
### Filter Behavior
- **Default behavior**: With no filters or empty filters, the section shows all notifications (both read and unread), matching GitHub's default behavior. To show only unread notifications by default, set `includeReadNotifications: false` in your config.
- **Explicit `is:unread`**: Shows only unread notifications, excluding bookmarked read notifications. This overrides the `includeReadNotifications` setting.
- **Reason filters**: Applied client-side after fetching from GitHub's API
## Notification Fetch Limit (`limit`)
| Type | Minimum | Default |
| :------ | :-----: | :-----: |
| Integer | 1 | 20 |
This setting defines how many notifications the dashboard should fetch for the section when:
- The dashboard first loads.
- You navigate to the next notification in a table without another fetched notification to display.
- You use the [refresh current section] or [refresh all sections] commands.
This setting overrides the [`defaults.notificationsLimit`] setting.
[refresh current section]: /getting-started/keybindings/global/#r---refresh-current-section
[refresh all sections]: /getting-started/keybindings/global/#r---refresh-all-sections
[`defaults.notificationsLimit`]: /configuration/defaults/#notifications-fetch-limit-notificationslimit
---
### Src Content Docs Configuration Pr Section (`docs/src/content/docs/configuration/pr-section.mdx`)
---
title: PR Sections
---
# PR Section Options (`prSections`)
Defines a section in the dashboard's PRs view.
- Every section must define a [`title`] and [`filters`].
- When you define [`limit`] for a section, that value overrides the
[`defaults.prsLimit`] setting.
- When you define [`layout`] for a section, that value overrides the
[`defaults.layout.pr`] setting.
[`title`]: #pr-title-title
[`filters`]: #pr-filters-filters
[`limit`]: #pr-fetch-limit-limit
[`layout`]: #pr-section-layout-layout
[`defaults.prsLimit`]: /configuration/defaults/#pr-fetch-limit
[`defaults.layout.pr`]: /configuration/defaults/#layout-options-layout
## PR Title (`title`)
This setting defines the section's name. The dashboard displays this value in the tabs for
the PRs view.
## PR Filters (`filters`)
This setting defines the [GitHub search filters][01] for the PRs in the section's table.
Don't specify `is:pr` for this setting. The dashboard always adds that filter for PR
sections.
Note pull requests from archived repositories are excluded by default with `archived:false`.
You can define any combination of search filters. To make it easier to read and maintain
your filters, we recommend using the `>-` syntax after the `filter` key and writing one
filter per line.
For example:
```yaml
- # Involved
filter: >-
is:open
involves:@me
-author:@me
updated:>={{ nowModify "-2w" }}
```
For more information about writing filters for searching GitHub, see [Searching].
[Searching]: /configuration/searching
## PR Section Layout (`layout`)
You can define how a PR section displays items in its table by setting options for the
available columns. You can define a column's width, whether it grows to fill available space,
and whether the column should be visible at all.
Note that if the length of a column's text exceeds the defined column [`width`], the view
truncates the column's text to two characters shorter than the column's width. For example, if
the width is `6`, `gh-dash` displays as `gh-d`.
Column headings have their color defined by the [`theme.colors.text.primary`] setting.
[`width`]: /configuration/layout/options#layout-options-width
[`theme.colors.text.primary`]: /configuration/theme
## PR Fetch Limit (`limit`)
| Type | Minimum | Default |
| :------ | :-----: | :-----: |
| Integer | 1 | 20 |
This setting defines how many PRs the dashboard should fetch for the section when:
- The dashboard first loads.
- The [fetch interval] elapses.
- You navigate to the next issue in a table without another fetched issue to display.
- You use the [refresh current section] or [refresh all sections] commands.
This setting overrides the [`defaults.prsLimit`] setting.
[01]: https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests
[fetch interval]: /configuration/defaults/#refetch-interval-in-minutes-refetchintervalminutes
[refresh current section]: /getting-started/keybindings/global/#r---refresh-current-section
[refresh all sections]: /getting-started/keybindings/global/#r---refresh-all-sections
[`defaults.prsLimit`]: /configuration/defaults/#pr-fetch-limit
---
### Src Content Docs Configuration Repo Paths (`docs/src/content/docs/configuration/repo-paths.mdx`)
---
title: Repo Paths
---
You can use the `repoPaths` setting to map repository names (as keys) to local paths
(as values). This map configures 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.
## Examples
### Matching Repositories
```yaml
repoPaths:
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.
---
### Src Content Docs Configuration Reusing (`docs/src/content/docs/configuration/reusing.mdx`)
---
title: Reusing Settings
---
`DASH` supports defining global settings that will always be applied, and lets you override them with a per-repo or one-time basis.
This lets you set your [theme](./theme), [keybindings](./keybindings) and any other setting by defining them once.
## The Global Config
The global config is usually under `$HOME/.config/gh-dash/config.yml` - but that follows the XDG spec. See [How to Configure](/configuration) for more details.
The global config is loaded first, with the option to override anything it defines.
Here you'd usually want to define stuff like your theme, keybindings etc.
## Per-Repo / One-Time Overrides
`DASH` supports passing ad-hoc or per-repo config files by:
- Creating a `.gh-dash.yml` file in a git repo's root directory.
- Passing a path to a `.yml` file you supplied with the `--config` flag or the `GH_DASH_CONFIG` environment variable.
Any settings defined here will override your global config settings.
## Example
Your global config under `~/.config/gh-dash/config.yml` could look like this:
```yaml
pager:
diff: diffnav
theme:
colors:
text:
primary: "#E2E1ED"
secondary: "#666CA6"
inverted: "#242347"
# ...
keybindings:
universal:
- key: g
name: lazygit
command: cd {{.RepoPath}} && lazygit
```
Then in a git repo you could create a `.gh-dash.yml` file defining just the
sections:
```yaml
prSections:
- title: Bugs
filters: is:open author:@me [BUG]
- title: Our Packages
filters: is:open review-requested:@me repo:work-org/our-pkg
```
Starting `DASH` from the git repo, the final config used will have the `pager`, `theme` and `keybindings`
from your global config and the `prSections` from your repo's config.
## Including Other Config Files
Any config file can pull in other config files with the `include` directive, which
takes a list of paths to other config files:
```yaml
include:
- /var/lib/gh-dash/system-shared.yml
- ~/.config/gh-dash/themes/tokyonight.yml
- ./shared-keybindings.yml
prSections:
- title: Bugs
filters: is:open author:@me [BUG]
```
Included files are merged in using the same rules as the global/override merge:
the file doing the including takes precedence over the files it includes, and
included files are merged in the order they're listed (later ones overriding
earlier ones). `keybindings` are unioned across all files, and `sections` are
taken from the file that defines them.
Paths are resolved relative to the file declaring the `include`, and a leading
`~` is expanded to your home directory. Included files may declare their own
`include` directives, which are resolved recursively.
---
### Src Content Docs Configuration Schema (`docs/src/content/docs/configuration/schema.mdx`)
---
title: Schema
---
The `dash` configuration schema is published here:
[`https://gh-dash.dev/schema.json`][02]
## Using the Schema in Neovim
1. Install the [yaml-language-server](https://github.com/redhat-developer/yaml-language-server) LSP
2. Follow the guide in [nvim-lspconfig](https://github.com/neovim/nvim-lspconfig/blob/master/doc/configs.md#yamlls) to set it up
3. Add the following line to the top of your configuration file:
```
# yaml-language-server: $schema=https://gh-dash.dev/schema.json
```
With the directive comment at the top of your configuration or the VS Code settings file, you can
then open your configurations and edit them with support for validation. When you hover on an
option in your configuration file, you'll get a brief synopsis of the option and a link to its
documentation on this site.
## Using the Schema in VS Code
You can get edit-time feedback, validation, and IntelliSense for your configurations in VS Code by
following these steps:
1. Install [Red Hat's YAML extension for VS Code][03].
1. Open your `dash` configuration file.
1. Add the following line to the top of your configuration file:
```
# yaml-language-server: $schema=https://gh-dash.dev/schema.json
```
1. Instead of adding a comment to your configuration file, you could create the
`.vscode/settings.json` file in your `dash` configuration folder and add this setting:
```json
{
"yaml.schemas": {
"https://gh-dash.dev/schema.json": "*.yml"
}
}
```
[01]: /getting-started/usage#--config
[02]: /schema.json
[03]: https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml
---
### Src Content Docs Configuration Searching (`docs/src/content/docs/configuration/searching.mdx`)
---
title: Searching
linkTitle: >-
Searching
summary: >-
How to search and filter issues and prs
weight: 3
---
# Searching
Searching for prs and issues is done by defining sections and their filters.
Search filters are defined using [GitHub search filters][01].
For example, this section, shows open PRs authored by anyone but me, which were updated in the last 2 weeks.
```yaml
prsSections:
- title: Review
filter: >-
is:open
-author:@me
updated:>={{ nowModify "-2w" }}
```
Note: don't specify `is:pr` for this setting. The dashboard always adds that filter for PR
sections. Results from archived repositories are excluded by default with `archived:false`.
You can define any combination of search filters. To make it easier to read and maintain
your filters, we recommend using the `>-` syntax after the `filter` key and writing one
filter per line.
For more information about writing filters for searching GitHub, see [Searching issues and pull requests][02].
## Search Templates
In addition to GitHub's filters, gh-dash adds templating functions.
### `nowModify`
The `nowModify` function helps you calculate relative dates in the ISO-8601 format (which is what GitHub expects).
Given the date today is 2025-02-02, a search filter of `updated:>={{ nowModify "-1mo" }}` will output `updated:>=2025-01-02`.
A duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as `1w`, `-8h` or `1mo2w`.
The available units are:
- [Go's builtin durations](https://pkg.go.dev/time#ParseDuration) - `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`
- Additionally:
- `d`/`D` for days
- `w`/`W` for weeks
- `M`/`mo` for months
- `y`/`Y` for years
## Smart Filtering
By default, if the directory you launch `dash` from is a clone of a remote GitHub repo (or if you
have the `GH_REPO` environment variable set to a particular remote), then for any of your PR
sections and issue sections with `filters` values in your [configuration](/configuration) that don’t
have an explicit `repo:` field, `dash` adds a `repo:
## ❤️ Sponsoring
If you enjoy `DASH` and want to help, consider supporting the project with a
donation at the [sponsors page](https://github.com/sponsors/dlvhdr).
Thank you to all past and existing sponsors! 🙏🏽
## Sponsors
