github.com/asinglebit/guitar @v1.0.4

                              :GG~        .?Y.                                
    ....        ..      ..   .....      . ^BG: ..       .....                 
 .7555YY7JP^   ~PJ     ~PJ  ?YY5PP~    7YY5BGYYYYJ.   J555YY557.              
.5B?.  :JBB~   !#5     !#5  ...PB~     ...^BG:....    ~:.   .7#5           :^^
7#5     .GB~   !B5     !B5     PB~        :BG.        .~7??J?JBG:      .~JPPPY
?#Y      PB~   !B5     !B5     PB~        :BG.       7GP7~^^^!BG:     ~5GY!:. 
^GB~    7BB~   ^BG.   .YB5     5#7        :BB:       P#!     JBG:    ^GG7     
 ^5G5JJYJPB~    JBP???YYB5     ^5GYJJ?.    7GPJ???.  ~PGJ77?5J5B!    JG5      
   .^~^..GB:     :~!!~. ^^       :~~~~      .^~~~~    .^!!!~. .^:    JG5      
 .?!^^^!5G7                                                          YB5      
 .!?JJJ?!:                                                           75?      



terminal based cross-platform git client 
made with ♡
  

guita╭, distributed as guitar, is a Rust terminal UI for working with Git history from a topology-first point of view. It is built with ratatui, crossterm, and libgit2, and is designed for exploring, filtering, and operating on large repositories without leaving the terminal.

guita╭ lets you instantly travel to prehistoric times in BIG repositores (500k+ commits)

Contents

• Status And Warning
• Demo
• Requirements
• Install
• Run
• Mental Model
• Interface Sections
• Navigation
• File Search
• Inputs And Keymaps
• Git Operations
• Authentication
• Settings
• Persistence
• Configuration Files
• Development
• Graph Internals
• Known Limitations
• Roadmap
• Screenshots

Status And Warning

This is a hobby project with sharp Git tools. It can stage, unstage, commit, force checkout, force push, delete branches, reset, stash, pop, drop, rebase, merge, cherry-pick, revert, prune worktrees, update submodules, sync submodule URLs, and discard file changes.

Use it carefully on important repositories. Keep backups, understand what the selected row and focused pane mean before using action mode, and report issues when behavior is surprising.

Demo

the complete rundown of features of the v1.0.0:

https://m.youtube.com/watch?v=0oyqviuKFXI

Older recording of the v0.1.12 feature set and some technical breakdown of the core walker:

https://www.youtube.com/watch?v=oERA8MYlHjQ

The recording is still useful as a tour. This README and the in-app settings/help view are the current source of truth for shortcuts and behavior.

Requirements

• Rust and Cargo when building from source.
• A non-bare Git repository. Bare repositories are not supported by the UI.
• user.name and user.email configured in Git before opening a repository. guitar reads these on repository load and uses them when creating commits.
• Terminal mouse support for pane dragging and wheel scrolling.
• SSH or HTTPS credentials for private remotes when using network operations.

Set identity globally:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

Or set identity per repository:

git config user.name "Your Name"
git config user.email "you@example.com"

Install

Prebuilt binaries are published on the releases page:

Important! Im not bothering myself with config migrations. So if you are trying out a new version, make sure to run guitar --reset. You might want to backup your .config/guitar folder before doing so. This is a temporary measure because im lazy.

https://github.com/asinglebit/guitar/releases

Build from source:

git clone https://github.com/asinglebit/guitar.git
cd guitar
cargo build --release

The release binary is written to:

target/release/guitar

Run

Run from inside a repository, a repository subdirectory, or with an explicit path:

guitar
guitar ../path/to/repository

The first non-flag argument is treated as the repository path. If no path is provided, . is used. The path is canonicalized and then resolved to the Git repository root when possible.

Meta flags:

guitar --version
guitar -v
guitar --reset

--version and -v print the version and exit. --reset deletes the saved guitar config directory, then starts the app with regenerated defaults.

If the path cannot be opened as a Git repository, guitar falls back to the splash screen and shows saved recent repositories.

Mental Model

guitar is built around a few core ideas:

• The graph is the primary view. Commits, refs, stashes, worktrees, and optional HEAD reflog entries are projected onto one topology-oriented list.
• Row 0 is a synthetic uncommitted-work row above HEAD. It represents staged files, unstaged files, and conflicts in the working tree.
• Commit history loads incrementally on a background worker. The app becomes usable while more history is still being walked.
• Focus controls what keys operate on. The same key can scroll the graph, a side pane, a status pane, settings, a modal, or the file viewer depending on focus.
• Scope navigation is horizontal: h widens outward, l narrows inward.
• Dangerous commands are gated behind action mode. By default, press Ctrl+a, then the action key.

Interface Sections

Splash

The splash screen appears when no repository is open or when you back out of the graph. It lists recent repositories from recent.json.

• Enter or l opens the selected recent repository.
• d removes the selected recent repository from recent.json.
• Shift+K and Shift+J move the selected recent repository up or down.
• Esc returns to the graph when a repository is already loaded.
• q exits.

Graph

The graph is the central history view. It can render:

• The synthetic uncommitted-work row.
• Commits in topology order.
• Local and remote branch labels.
• Lightweight and annotated tags resolved to commits.
• Stash commits placed near their base commits.
• Worktree badges for commits checked out in main or linked worktrees.
• Optional HEAD reflog labels and roots.
• Optional abbreviated SHA column.

Graph row details are loaded by window, so large repositories can stay responsive.

Branches

The branch pane lists local branches first and remote branches after them, sorted by name inside each group.

• Filled circle: visible local branch.
• Hollow circle: hidden local branch.
• Filled diamond: visible remote branch.
• Hollow diamond: hidden remote branch.

Branch visibility affects graph roots and filtering. Branches are visible by default unless their exact local or remote name is saved in the hidden-branch layer. Hidden branch names are saved per repository, pruned when refs disappear, and new branches are visible until explicitly hidden.

Tags

The tag pane lists local tags sorted by name. Tags are shown in the graph at the commit they resolve to. The app can create and delete local lightweight tags.

Stashes

The stash pane lists stash commits. Stashes are real commits and are rendered in the graph near their first parent.

Reflogs

The reflog pane lists recent HEAD reflog entries. Reflog rows can jump to commits that are visible in the graph. If the reflog commit is hidden, enable graph reflogs with ) so the walker includes HEAD reflog roots.

Worktrees

The worktree pane lists the main worktree and linked worktrees.

Rows include:

• Worktree name.
• Branch name, detached HEAD short SHA, or no-head state.
• Current-worktree marker.
• Dirty marker.
• Locked marker.
• Invalid marker.

Valid worktrees can be opened from the pane. Linked worktrees can be locked, unlocked, removed, or pruned through the worktree actions.

Submodules

The submodule pane lists immediate Git submodules for the current repository.

Rows include:

• Submodule path.
• Current branch, detached HEAD short SHA, or not-initialized state.
• Staged pointer marker.
• New-commits marker.
• Modified-content marker.
• Untracked-content marker.
• Not-open marker.

Initialized submodules can be opened from the pane, which reloads guitar at the submodule repository path. Opened submodules are tracked in a session-only stack, rendered in the left status bar as a ▣ breadcrumb before the current branch or HEAD. Uninitialized submodules can be updated and initialized through the submodule action.

Status

The status area is on the right.

On the uncommitted row:

• The top status pane shows conflicts and staged changes.
• The bottom status pane shows conflicts and unstaged changes.
• Conflicts appear in both panes and are highlighted.

On a commit row:

• The top status pane shows files changed by the selected commit compared with its first parent.
• The bottom status pane is not used.

Status symbols:

• ! conflict.
• ~ modified.
• + added.
• - deleted.
• → renamed.

Inspector

The inspector shows selected commit metadata:

• Commit SHA.
• Parent SHAs.
• Featured branch labels.
• Author.
• Committer.
• Summary.
• Body.

When the selected row is uncommitted, the inspector appears if there are conflicts.

Viewer

The viewer opens from a selected status row. It can show:

• Working tree file contents and diff for the uncommitted row.
• Commit file contents and diff for selected commits.
• Conflict files with conflict-marker highlighting.
• Unified diff style.
• Hunk-only mode.
• Side-by-side split diff mode.
• Line numbers.
• Wrapped long lines.

For merge commits, file lists and file diffs compare against the first parent.

Settings

The settings/help view is opened with ?. It shows version and the commit heatmap above tabbed settings sections for general, display, auth, repo, and shortcuts. Recent repository rows, performance rows, remote rows, theme rows, layout rows, and keybinding rows are selectable.

Navigation

Scope

h and l are the most important navigation keys.

• In the graph, l narrows into details. On a commit row it focuses the inspector; on the uncommitted row it focuses staged or unstaged status.
• In the inspector, l moves to status.
• In status, l opens the selected file in the viewer.
• In the viewer, h returns to status.
• In status, h moves outward to inspector or graph.
• In the graph, h opens/focuses the branch pane.
• In branch, tag, stash, reflog, worktree, and submodule panes, l jumps into the selected item.
• In settings, h returns to the graph.
• In the splash screen, l opens the selected recent repository.

Focus

Tab and Ctrl+n move to the next focusable pane. Shift+Tab and Ctrl+p move to the previous focusable pane.

Ctrl+h, Ctrl+j, Ctrl+k, and Ctrl+l move focus to the nearest pane in that direction when one is visible. Ctrl+Left, Ctrl+Down, Ctrl+Up, and Ctrl+Right are equivalent arrow-key alternatives.

Focusable panes are ordered:

graph/viewer, inspector, staged/commit status, unstaged status, search, submodules, worktrees, reflogs, stashes, tags, branches

Hidden panes are skipped. The unstaged status pane is focusable only on the uncommitted row.

Selection

Enter means "open/select" for the current focus:

• Splash: open selected recent repository.
• Settings theme: activate and save theme.
• Settings remote: open the remote action chooser.
• Settings add remote: open the add-remote prompts.
• Settings keybinding: open key capture.
• Settings layout row: toggle that layout option or reset layout.
• Settings graph lane limit row: open a numeric prompt. In normal mode, - and + shrink or grow the graph lane limit by one.
• Graph: open a worktree badge if the selected commit has valid worktree candidates.
• Branch/tag/stash/reflog panes: jump to the corresponding graph row and center it when possible.
• Worktree pane: open the selected valid worktree.
• Submodule pane: open the selected initialized submodule as the current repository.
• Status panes: open the selected file in the viewer.
• Choice modals: confirm the selected row.

Back

Esc cancels modals or widens back to the graph.

• From graph: opens the splash screen when the history worker is idle.
• From splash: returns to graph when a repository is loaded.
• From viewer/settings/side panes/status/inspector: returns to graph.
• From text-entry modals: clears input and returns to the relevant view.
• From auth prompt: cancels the pending network operation.

Scrolling

All scroll commands act on the focused pane or viewport:

• j / Down: one row down.
• k / Up: one row up.
• Ctrl+d: half page down.
• Ctrl+u: half page up.
• PageDown: page down.
• PageUp: page up.
• Ctrl+Alt+d: jump halfway toward the end of the focused graph/side pane list.
• Ctrl+Alt+u: jump halfway toward the beginning of the focused graph/side pane list.
• g / Home: beginning.
• Shift+G / End: end.

In full viewer mode, Ctrl+d and Ctrl+u jump between diff hunk edges. In hunk and split viewer modes, they scroll by half pages.

Resizing

Ctrl+Alt+h, Ctrl+Alt+j, Ctrl+Alt+k, and Ctrl+Alt+l resize the focused pane one cell or row at a time. Ctrl+Alt+Left, Ctrl+Alt+Down, Ctrl+Alt+Up, and Ctrl+Alt+Right are equivalent arrow-key alternatives.

• Left panes: Ctrl+Alt+l widens the left column; Ctrl+Alt+h narrows it.
• Right panes: Ctrl+Alt+h widens the right column; Ctrl+Alt+l narrows it.
• Graph/viewer focus: Ctrl+Alt+h grows the cente