gitm8.1

.TH GITM8 1 "June 2026" "gitm8" "User Commands"
.SH NAME
gitm8 \- terminal dashboard for common Git workflows
.SH SYNOPSIS
.SY gitm8
.YS
.SH DESCRIPTION
.B gitm8
is a small terminal user interface for day-to-day Git work.
It opens an interactive dashboard for reviewing changes, staging and unstaging
files, committing, fetching, pulling, pushing, switching branches,
rebasing, viewing logs, opening pull requests, and switching repository-local
Git identity profiles.
.PP
.B gitm8
does not reimplement Git storage or transport.
It shells out to the installed
.BR git (1)
binary, so existing Git configuration, hooks, SSH keys, credential helpers,
commit signing, aliases used by Git itself, and repository settings remain in
effect.
.PP
Run
.B gitm8
from inside the repository you want to work on.
If launched outside a Git worktree, Git-backed actions fail in the same way the
corresponding
.BR git (1)
command would fail.
.SH DASHBOARD
The screen contains a repository status bar, a Git output area, a changed-files
panel, a preview/review/log panel, and a footer with key bindings.
The top bar shows repository name, current branch, configured Git user,
upstream, ahead/behind counts, staged and unstaged counts, last fetch time, and
the active viewer mode.
.PP
The dashboard opens on the first changed file when changes are present.
Press
.B d
to toggle the selected file between content preview and diff preview.
Press
.B 0
to show the repository-wide review.
File previews include lightweight theme-aware syntax highlighting for common
source and configuration file types.
Press
.B /
while viewing file contents to search and highlight matches in place, then use
.B Up
and
.B Down
to move between matches.
The output bar shows the search input, match count, and search keys while the
viewer keeps file context.
Plain searches match full words; use
.B *
or
.B ?
wildcards to match partial words.
The changed-files panel marks removed tracked paths with
.B DEL
and renames with
.BR REN ,
displayed as
.BR "old/path -> new/path" .
.SS Keys
.TP
.B Up, Down
Move the file, branch, profile, or picker selection.
.TP
.B Enter
Open the viewed file in the configured editor, accept the selected picker item,
or confirm an active text input.
.TP
.B 0
Show repository-wide review.
.TP
.B d
Toggle the selected file between diff and content preview.
.TP
.B /
Search and highlight inside the viewed file contents.
.TP
.B x
Discard all changes to the selected file.
This uses
.BR "git restore"
for tracked changes and
.BR "git clean -fd"
for untracked files.
When
.B GITM8_CONFIRM_DESTRUCTIVE_ACTIONS
is enabled, confirmation is required first.
.TP
.B s, S
Stage the selected file, or stage all changes.
.TP
.B u, U
Unstage the selected file, or unstage all changes.
.TP
.B c
Commit staged changes.
Inside the commit prompt,
.B Ctrl-g
asks the configured AI CLI to generate a commit message from staged changes and
populate the input.
This shortcut is hidden when the configured AI provider is not installed.
.TP
.B f
Fetch all remotes and prune stale remote-tracking refs.
.TP
.B p, P
Pull with fast-forward only mode, or push.
When the current branch has no upstream,
.B P
uses
.BR "git push -u <remote> <branch>"
when a remote is configured.
.TP
.B z
Open the in-TUI squash picker for commits on this branch since the merge-base
with
.BR GITM8_DEFAULT_BRANCH .
Use
.B S
to mark the highlighted commit for squashing,
.B K
to keep it separate, and
.B B
to choose the highlighted commit as the base.
Pick a base after marking the commits you want to squash, then press enter to
apply.
It applies the squash without opening an external editor.
This rewrites local branch history, refuses detached branches, the default
branch, and dirty worktrees, and does not push.
.TP
.B b
Open the branch switcher.
.TP
.B C
Open conflict mode for unmerged files.
.TP
.B t
Open the stash panel.
.TP
.B n
Stash the selected file from the main viewer.
.TP
.B l
View recent commit logs.
.TP
.B r, Ctrl-p
Open pull request options for the current branch using
.BR gh (1) .
Choose
.B g
to generate a title and body with the configured AI provider when it is
installed, or
.B m
to write the pull request yourself in
.BR "gh pr create" .
.B gitm8
does not push while creating a pull request; push the branch first.
.TP
.B R, Ctrl-r
Open the rebase picker.
.TP
.B i
Switch repository-local Git identity profile.
.TP
.B h
Open help.
.TP
.B o
Expand or collapse the Git output box.
.TP
.B Tab
Hide or show the footer key bar.
.TP
.B y
Open
.BR yazi (1),
if installed.
.TP
.B w
Open the workspace project picker. Existing repositories can be opened without
restarting gitm8; use
.B c
to clone through GitHub CLI or
.B n
to initialize a local repository.
.TP
.B j, k
Scroll the viewer line by line.
.TP
.B PageDown, PageUp, Ctrl-f, Ctrl-b
Scroll the viewer by a page.
.TP
.B g, G
Jump the viewer to the top or bottom.
.TP
.B q, Ctrl-c
Quit.
.SH BRANCHES
In the branch switcher, use
.B Up
and
.B Down
to choose a branch,
.B Enter
to switch to it,
.B W
to switch while carrying current changes through stash/pop,
.B n
to create a branch,
.B D
to delete the selected branch, and
.B Esc
to return to review mode.
.PP
The branch list shows local branches followed by remote-only branches.
Remote branches are de-duplicated and shown without their remote prefix.
.SH REBASE
In the rebase picker, use
.B Up
and
.B Down
to choose a target branch and
.B Enter
to rebase the current branch onto it.
If a rebase is already in progress, use
.B c
to continue,
.B a
to abort, or
.B s
to skip the current patch.
.PP
If the rebase stops on conflicts, resolve them with normal Git commands outside
.BR gitm8 ,
then continue from the dashboard or by running
.BR "git rebase --continue" .
.SH CONFLICTS
Conflict mode lists files Git reports as unmerged.
Use
.B Up
and
.B Down
to choose a file,
.B Enter
to open it in the configured editor, and
.B m
to stage it after resolving conflicts.
The selected file preview shows line numbers for
.BR "<<<<<<<" ,
.BR "=======" ,
and
.BR ">>>>>>>"
conflict markers.
The same screen supports
.B c
to continue a rebase,
.B a
to abort, and
.B s
to skip the current patch.
.SH STASHES
Use
.B n
from the main viewer to stash the selected file only.
The stash panel lists
.BR "git stash list"
entries and previews the selected stash diff.
Use
.B n
inside the stash panel to stash from there too,
.B a
to apply,
.B p
to pop, and
.B D
to drop the selected stash.
.SH CONFIGURATION
On first launch, when the configured workspace directory (initially
.IR ~/Github )
does not exist, gitm8 shows a setup wizard for the workspace path, global Git
identity, initial branch, editor, and optional GitHub CLI authentication.
The wizard shows a review before writing changes. Declining is remembered.
.PP
Configuration is loaded from
.IR ~/.gitm8/.gitm8rc ,
then
.IR ~/.gitm8/gitm8rc ,
then legacy
.IR ~/.gitm8rc ,
then
.IR ~/.gitm8/credentials .
Environment variables override defaults.
.B gitm8
creates
.IR ~/.gitm8/
and a default
.IR ~/.gitm8/.gitm8rc
when no config file exists.
Existing config files are not replaced.
For first-run config generation,
.B gitm8
uses
.B codex
when installed, falls back to
.B claude
when only Claude is installed, and otherwise writes an AI unavailable comment.
Existing configs keep their selected provider; generated AI actions are disabled
when that provider is not installed.
.TP
.B GITM8_WORKSPACE_DIR
Directory checked by the first-run setup wizard.
Default:
.IR ~/Github .
.TP
.B GITM8_FIRST_RUN_DISMISSED
Whether the first-run setup prompt has been declined.
.TP
.B GITM8_DEFAULT_BRANCH
Default branch name.
Default:
.BR main .
.TP
.B GITM8_EDITOR
Editor used by workflows that need one.
Default:
.B EDITOR
or
.BR vi .
.TP
.B GITM8_THEME
Dashboard color theme.
.TP
.B GITM8_CONFIRM_DESTRUCTIVE_ACTIONS
Whether destructive actions should ask for confirmation where applicable.
.TP
.B GITM8_FETCH_ON_STARTUP
Fetch from all remotes with pruning before the dashboard opens.
.TP
.B GITM8_SHOW_COMMIT_GRAPH
Show graph lines in the commit log view.
.TP
.B GITM8_KEY_REFERENCE
Comma-separated action ID allow-list for labels shown in the main key bar.
Press
.B h
to edit it interactively.
The selector opens in browse mode. Press / to search, Enter to browse the
results, or Escape to clear the search. Browse line by line with
.B up/down
or
.BR j/k ,
Space to toggle the highlighted shortcut, Enter to save, and Escape to cancel.
For example:
.B move-files,edit-file,stage-files,commit,quit .
Hiding a label does not disable its keyboard shortcut. See the README for the
complete list of action IDs.
Unset uses compact, width-dependent defaults. Set to none to hide all main
footer labels, including Help and Quit; their keyboard shortcuts remain active.
Other screens retain their contextual action hints.
.TP
.B GITM8_AI_PROVIDER
AI CLI used for generated commit messages and pull request text.
Supported values:
.B codex
,
.B claude
and
.BR ollama .
The first-run default is
.B codex
when installed,
.B claude
when Codex is missing and Claude is installed, otherwise
.BR codex
with AI marked unavailable.
.TP
.B GITM8_OLLAMA_URL
Ollama API base URL used when
.B GITM8_AI_PROVIDER
is
.BR ollama .
Default:
.BR http://localhost:11434 .
.TP
.B GITM8_LOG_ENABLED
Enable syslog-style file logging.
Default:
.BR true .
.TP
.B GITM8_LOG_LEVEL
Minimum log level.
Supported values:
.B DEBUG ,
.B INFO ,
.B WARN ,
and
.BR ERROR .
Default:
.BR INFO .
.TP
.B GITM8_LOG_FILE
Path for application logs.
Default:
.IR ~/.gitm8/gitm8.log .
The
.B ~/
and
.B $HOME/
prefixes are expanded.
When the active log reaches 100 MB,
.B gitm8
compresses it and keeps up to five
.B .gz
backups beside the active log.
.SH THEMES
Built-in themes:
.PP
.EX
amber
catppuccin
catppuccin-frappe
catppuccin-latte
catppuccin-macchiato
catppuccin-mocha
cyan
default
forest
highvis
lime
midnight
mono
ocean
rose
steel
violet
.EE
.PP
.B catppuccin
maps to
.BR catppuccin-mocha .
.SH PROFILES
Define switchable Git identities in
.IR ~/.gitm8/profiles ,
one per line:
.PP
.EX
Work     = Ada Lovelace <ada@work.example>
Personal = Ada <ada@personal.example>
.EE
.PP
Selecting a profile runs
.B git config user.name
and
.B git config user.email
for the current repository only.
The global Git identity is left untouched.
.SH DEPENDENCIES
.TP
.BR git (1)
Required. All repository operations use the installed Git binary.
.TP
.BR gh (1)
Required for pull-request creation and viewing.
Authenticate with
.B gh auth login
before using the dashboard pull-request key.
.TP
.BR codex (1)
Optional. Preferred first-run AI provider for generated commit messages and pull
request text.
.TP
.BR claude (1)
Optional. Used when selected automatically on first run or when
.B GITM8_AI_PROVIDER
is set to
.BR claude .
.TP
.BR ollama (1)
Optional. Local AI provider for generated commit messages and pull request text
when
.B GITM8_AI_PROVIDER
is set to
.BR ollama .
Requires an Ollama server reachable through
.BR GITM8_OLLAMA_URL .
.TP
.BR yazi (1)
Optional. Used only when pressing
.B y
in the dashboard.
.SH EXIT STATUS
.TP
.B 0
The dashboard exited successfully.
.TP
.B 2
Unsupported command-line arguments were provided.
.TP
.B non-zero
The dashboard failed to start or exited with an error.
.SH EXAMPLES
.TP
Open the dashboard in the current repository:
.EX
cd path/to/project
gitm8
.EE
.TP
Open the dashboard with a specific theme:
.EX
GITM8_THEME=catppuccin gitm8
.EE
.SH SEE ALSO
.BR git (1),
.BR gh (1),
.BR codex (1),
.BR claude (1),
.BR ollama (1),
.BR yazi (1)
.SH BUGS
Report issues at
.UR https://github.com/b404dev/gitm8/issues
.UE .