gitm8 is a small terminal UI for common Git workflows. It uses the installed git binary, so your existing Git configuration, SSH keys, credential helpers, hooks, aliases, and signing behavior continue to work normally.

It provides one interface: an interactive dashboard for day-to-day Git work.

Recommended install:

curl -fsSL https://raw.githubusercontent.com/b404dev/gitm8/main/scripts/install.sh | bash

The script supports apt, pacman, and brew. It installs build/runtime dependencies for you:

• Go, used to build gitm8 from source
• git
• GitHub CLI (gh)
• optional yazi support

It then builds gitm8, installs it to ~/.local/bin, and adds that directory to your shell profile if needed.

Installer options:

GITM8_INSTALL_DIR="$HOME/bin"        # install somewhere else
GITM8_MAN_DIR="$HOME/.local/share/man/man1"
GITM8_SKIP_DEPS=1                    # skip package-manager dependency install
GITM8_SKIP_PATH_UPDATE=1             # do not edit shell profile
GITM8_SKIP_MAN_INSTALL=1             # do not install the man page
GITM8_REF=main                       # branch/tag to build

The installer also installs a manual page, so the command is available through man gitm8 when your man path includes ~/.local/share/man.

If the repository is private, the raw script URL must be reachable from that machine. Authenticate GitHub first, then use the Go install fallback if the raw URL is not accessible:

gh auth login -h github.com
gh auth setup-git

Manual Go install:

If you already have Go installed, you can install directly with:

GOPRIVATE=github.com/b404dev/gitm8 go install github.com/b404dev/gitm8@latest

go install places the binary in $(go env GOPATH)/bin, usually ~/go/bin. It does not update your PATH. If gitm8 is not found after install, add Go's bin directory to your shell profile:

export PATH="$(go env GOPATH)/bin:$PATH"

If you do not have Go, install it first:

# Debian/Ubuntu
sudo apt-get update && sudo apt-get install -y golang-go

# Arch
sudo pacman -Sy --needed go

# macOS/Linux with Homebrew
brew install go

For local development:

go run .          # run the dashboard from source
go build -o gitm8 . && ./gitm8

Run gitm8 to open the dashboard.

For best results, launch gitm8 from inside the Git repository you want to work on:

cd path/to/project
gitm8

Most dashboard features expect the current directory to be part of a Git worktree. If you open gitm8 outside a repository, Git commands will fail until you cd into a project.

The layout is:

• top repository status bar
• git output bar
• changed-files panel on the left
• preview/review/log panel on the right
• footer keybinding bar

The dashboard opens on the first changed file's contents. Press d to toggle that file's diff, or 0 for the repo-wide diff review. File previews use lightweight, theme-aware syntax highlighting for common source and config files.

The top bar shows repository name, current branch, configured user, upstream, ahead/behind counts, staged/unstaged counts, last fetch time, and active viewer mode.

In the branch switcher (b):

Deleting prompts whether to remove the branch locally only (l) or locally and on the remote (r). Deletes are forced locally (-D) and stale remote-tracking refs are pruned from the branch list.

The branch list shows local branches followed by remote-only branches. Remote branches are de-duplicated and shown without their remote prefix, so switching to origin/feature appears as feature and creates a local tracking branch automatically.

In the rebase picker (R or ctrl+r), use ↑/↓ to choose a target branch and enter to rebase the current branch onto it. You cannot rebase onto the current branch. If a rebase is already in progress, use c to continue, a to abort, or s to skip the current patch.

If the rebase stops on conflicts, resolve them with normal Git commands outside gitm8, such as:

git rebase --continue
git rebase --abort

Press r or ctrl+p in the dashboard to create or show a pull request for the current branch. This workflow uses the GitHub CLI (gh):

gh auth login

gitm8 first tries to show an existing PR for the current branch. If none exists, it runs gh pr create --fill. If gh needs authentication, a pushed branch, or more information, the error appears in the git output box.

Press i to choose a configured identity profile. See Profiles.

Commit and new-branch inputs accept enter to confirm and esc to cancel.

Configuration is loaded from ~/.gitm8rc, then ~/.gitm8/credentials. Environment variables override defaults.

export GITM8_DEFAULT_BRANCH="main"
export GITM8_EDITOR="vim"
export GITM8_THEME="catppuccin"
export GITM8_CONFIRM_DESTRUCTIVE_ACTIONS="true"
export GITM8_FETCH_ON_STARTUP="false"
export GITM8_SHOW_COMMIT_GRAPH="true"

Secrets should normally stay in Git credential helpers, SSH agents, SSH keys, environment variables, or the OS keychain.

Set a theme with:

export GITM8_THEME="catppuccin"

Available themes:

amber
catppuccin
catppuccin-frappe
catppuccin-latte
catppuccin-macchiato
catppuccin-mocha
cyan
default
forest
highvis
lime
midnight
mono
ocean
rose
steel
violet

catppuccin maps to catppuccin-mocha.

Define switchable Git identities in ~/.gitm8/profiles, one per line:

Work     = Ada Lovelace <ada@work.example>
Personal = Ada <ada@personal.example>

Blank lines and lines starting with # are ignored, as are malformed lines.

When you select a profile, gitm8 runs:

git config user.name "<name>"
git config user.email "<email>"

This applies to the current repository only. Your global identity is left untouched. The active identity is marked (current) in the list, and the top bar updates after the switch completes.

Keep real names and addresses out of this repository; profiles live only on your machine.

Press y in the dashboard to launch the yazi file manager, returning to gitm8 when you quit it.

Sample yazi configuration lives under configs/yazi/.

For a maintainers' map of the layers and click-through source references, see docs/CODEBASE.md.

For explanations of the core names like Model, Runner, and custom messages, see docs/ABSTRACTIONS.md.

For concrete examples of how key presses move through the code, see docs/FLOWS.md.

MIT. See LICENSE.