Git Hub for herdr

A keyboard-first Git command center for herdr. Open one menu to review worktrees, compare branches, inspect agent changes, browse history, resolve conflicts, or launch your favorite Git tools—without leaving the current workspace.

Press prefix+g, choose an action by mnemonic, review the result, then press q to return to your work.

Highlights

• One-key workflow: an fzf command palette puts every review action behind a single herdr binding.
• Purpose-built reviews: inspect worktrees, branches, agents, history, and merge conflicts with codediff.nvim.
• Workspace-aware: actions retain the repository and pane that opened the menu, even while the overlay has focus.
• Isolated by default: the bundled Neovim runtime never loads or modifies ~/.config/nvim.
• Theme-native: the menu and diff views derive their colors from herdr's active palette, with optional hue-nvim integration.
• Controlled transparency: preserve native theme behavior or force transparent/opaque plugin surfaces from one setting.
• Built-in settings: configure every supported option in a themed Neovim dashboard without editing TOML by hand.
• Extensible: add lazygit or any custom terminal command to the same menu.

Requirements

• herdr 0.7.3 or newer
• Neovim 0.8 or newer; Neovim 0.9 or newer for the optional hue-nvim layer
• Git
• fzf for the menu; direct review actions work without it
• curl or wget for codediff.nvim's first-use binary download
• macOS or Linux

Quick start

1. Install the plugin

herdr plugin install crafts69guy/herdr-git-hub

For local development, link the checkout instead:

herdr plugin link ~/Developments/github.com/crafts69guy/herdr-git-hub

2. Add the recommended keybinding

Copy the following into ~/.config/herdr/config.toml:

# herdr uses prefix+g for `goto` by default, so move it first.
[keys]
goto = "prefix+alt+g"

[[keys.command]]
key = "prefix+g"
type = "plugin_action"
command = "git-hub.menu"
description = "Git menu"

Additional direct bindings are available in examples/keybindings.toml.

3. Reload and open Git Hub

herdr server reload-config

From a project pane, press prefix+g. Type a mnemonic letter or fuzzy-search for an action, then press Enter. Press c at any time to open Settings immediately.

On its first self-contained launch, Git Hub installs pinned releases of lazy.nvim and codediff.nvim. Later launches reuse the data in ~/.local/share/herdr-git-hub, or the equivalent XDG data directory.

Showcase

Browse commit history

Inspect commits, metadata, and changed files together in a managed herdr pane.

Review changes side by side

Select a commit or file and keep its surrounding history visible while you review the diff.

The review UI is powered by codediff.nvim. Git Hub provides the herdr-native workflow, pane lifecycle, context handling, and theme integration around it.

Open the full repository view

Launch lazygit from the same command palette for repository-wide navigation, branch operations, staging, and other workflows beyond focused reviews.

Actions

Menu key	Plugin action	Result
—	git-hub.menu	Open the Git command palette.
d	git-hub.review-worktree	Review staged and unstaged changes.
b	git-hub.review-branch	Compare the current branch with its merge base.
h	git-hub.history	Browse repository and file history.
a	git-hub.review-agent	Review the selected or most recent agent worktree.
x	git-hub.resolve-conflicts	Open unresolved files in merge mode.
c	git-hub.settings	Open Settings immediately, without pressing Enter.
l	—	Launch lazygit when it is available on PATH.

Branch review automatically checks main, master, origin/main, and origin/master unless base_branch is configured. Conflict review opens a single unresolved file directly or the repository explorer when several files need attention.

Configuration

Open the Git Hub menu and press c to edit settings immediately in a themed Neovim dashboard. Use j/k to move, Enter or h/l to change a value, r to reset one setting, R to reset all settings, and s to save. Pressing q with an unsaved draft offers Save, Discard, and Continue editing.

The dashboard discovers branches from the originating repository, validates a custom base branch when possible, and writes changes atomically. It preserves comments and settings it does not manage. Changes apply to the next review; no herdr config reload is required.

You can also invoke the dashboard directly:

herdr plugin action invoke settings --plugin git-hub

Edit the file directly

Find the stable configuration directory for the installed plugin:

herdr plugin config-dir git-hub

Create config.toml in that directory. The file uses a deliberately simple, flat TOML structure:

nvim = "self"
placement = "overlay"
base_branch = "main"
layout = "side-by-side"
transparency = "auto"
notifications = true
notification_position = "top-right"

Setting	Default	Supported values
nvim	"self"	"self" or "user"
placement	"overlay"	"overlay", "split", "tab", or "zoomed"
base_branch	Auto-detected	Any local or remote branch that resolves to a commit
layout	"side-by-side"	"side-by-side" or "inline"
transparency	"auto"	"auto", "enabled", or "disabled"
notifications	true	true or false
notification_position	"top-right"	Any corner: top-left, top-right, bottom-left, or bottom-right

Git Hub leaves notification sounds under herdr's control. Disabling its notifications does not hide stderr, plugin logs, or Neovim errors.

Extend the menu

Create menu.conf in the same plugin configuration directory. Each entry uses the format key|icon|label|shell command:

# key|icon|label|shell command
k||git graph (keifu)|keifu
s||git status|git status --short; read -r _

Keys must be single characters. Built-in mnemonics—including c for configuration—take precedence over custom entries. Custom commands run through sh -c in the originating repository and replace the menu pane until they exit, so only configure commands you trust.

Neovim runtime

Self-contained mode

The default nvim = "self" mode launches Neovim with an isolated NVIM_APPNAME=herdr-git-hub. Git Hub owns and pins its lazy.nvim and codediff.nvim versions, keeping both configuration and plugin data separate from your normal Neovim setup.

User mode

Set nvim = "user" to load your regular Neovim configuration. In this mode, you must install and configure esmuellert/codediff.nvim yourself so that the :CodeDiff command is available. Git Hub adds only its small mode and pane-exit adapter to that Neovim process.

The Settings dashboard always uses a separate minimal Neovim runtime. It does not load the user's configuration, lazy.nvim, or CodeDiff, regardless of the selected nvim mode.

Theming

Git Hub reads [theme.custom] from ${HERDR_CONFIG_PATH:-~/.config/herdr/config.toml} and maps the palette to the fzf menu, Neovim, CodeDiff, and conflict highlights.

When ${XDG_STATE_HOME:-~/.local/state}/hue-theme/current contains mua, huong, or cung, Git Hub loads hue-nvim first and uses its semantic palette. Set HUE_THEME_HOME to a hue-theme checkout to test a local Neovim plugin during development.

The transparency setting controls every surface owned by Git Hub:

• "auto" preserves the existing behavior: the fzf menu stays transparent, while self-contained Neovim surfaces follow the active theme—transparent for Hue moods and opaque for the generic herdr palette.
• "enabled" clears the base background in the menu, Settings, and the self-contained CodeDiff runtime.
• "disabled" gives all plugin-owned surfaces an explicit background.

Diff hunks, selections, cursor lines, and modal pickers retain a tinted background for readability. With nvim = "user", the user's colorscheme owns Neovim transparency; Git Hub does not overwrite it. Actual window opacity still depends on the terminal, because herdr theme colors do not carry alpha values.

Operational behavior

• Clean worktrees, empty branch diffs, and repositories without conflicts show a concise herdr notification instead of opening an empty review pane.
• Menu cancellation and successful launches remain quiet.
• Startup, action, pane, and CodeDiff errors appear as herdr notifications; technical details remain in the pane or plugin log.
• Transient notification failures during popup focus changes are retried once.
• Pressing q in codediff.nvim closes both the review and its temporary herdr pane.

Development

Static and headless checks do not require a running herdr session:

nvim -l tests/theme_spec.lua
nvim -l tests/notification_spec.lua
nvim -l tests/settings_spec.lua
bash tests/manifest_spec.sh
bash tests/notification_spec.sh
bash -n bin/*.sh tests/*.sh tests/fixtures/*.sh
shellcheck -e SC2054 bin/*.sh tests/*.sh tests/fixtures/*.sh

The action launcher can be smoke-tested with a stub HERDR_BIN_PATH. Avoid starting a second herdr server because it would share live session state.

License

Git Hub is available under the MIT License.