# Gitwig - Panel & UI Window Directory
This document lists and describes all the user interface panels, tabs, views, overlay pickers, inputs, and modal dialogs implemented in Gitwig, along with their available keyboard shortcuts.
---
## 1. Home Screen (Repository List View)
The primary dashboard shown when Gitwig starts up.
* **Global Summary Header Bar**: Top row of four tabs showing aggregate counts: `repos │ dirty │ ahead │ stale`. Click a tab, or press `Tab` / `Shift+Tab`, to filter the repository list to that section; the active tab is drawn as a highlighted block and `Esc` clears the filter. When a label filter is active, a highlighted `● label` badge is set into the frame's top border, centered above the header (click it to reopen the label picker), and the tab counts scope to that label. If the active filters leave nothing to show, the tab strip stays visible above a message explaining which filter is empty and how to leave it.
* **Quick Label Chips**: Once a label has been viewed through the label filter, a second row under the summary bar, set off by a thin dashed rule, lists up to nine labels as `1 web │ 2 api │ …` chips styled like the summary tabs (with `show_separators = false` the rule is dropped and the chips sit directly under the summary bar). Slots fill FIFO: a label takes the next free slot the first time it is viewed and keeps that number (re-viewing never reorders), and once all nine are taken the oldest is evicted so the new label lands in slot 9. The list starts empty, is stored as `label_slots` in `state.toml` (the usage-state file beside `config.toml`), and drops labels no repository carries any more. Press the digit, or click the chip, to apply that label as the sticky filter; the active label's chip is drawn as a highlighted block, and pressing its digit again clears the filter.
* **Sort Rule**: A thin dashed rule (`┄`, or `-` in compatibility mode) closes the header directly above the repository list and carries the active sort caption (`Sort: Custom`, `Sort: Alphabetical (Rev)`, …), which used to sit in the top frame border. When the active label filter sets its own sort in Label Settings, the caption ends with the label's name (`Sort: Alphabetical · work`) to show that the label's sort, not the global one, is in effect. With `show_separators = false` the dashes are hidden and only the caption is drawn.
* **Repository List Panel**: Displays cards for all configured/scanned repositories. Supports Standard, Compact, and Tile grid layouts. Pinned repositories (`p`) stay at the top of the list, and of each label group, whatever the sort order, sorted among themselves; a faint, sparse dashed rule (`┄ ┄ ┄`, or `- - -` in compatibility mode; dimmed, indented to the card text and lighter than the header rules) is drawn under the last pinned row to set the pinned block apart. The Recent and Starred groups, ordered by visit time and by name, have no rule, and `show_separators = false` hides it everywhere.
* *Shortcuts*:
* `↑` / `k` / `up` : Move selection up
* `↓` / `j` / `down` : Move selection down
* `PgUp` / `pageup` : Jump one page up
* `PgDn` / `pagedown` : Jump one page down
* `Home` / `home` : Go to top of list
* `End` / `end` : Go to bottom of list
* `Enter` / `→` / `right` : Open repository details (in Tile view `→` moves the selection right instead of opening the repository)
* `Space` : Toggle selection for batch actions
* `p` : Toggle pin status of selected item
* `*` : Toggle Starred / Favorite status of selected item
* `y` : Yank absolute path to clipboard
* `/` : Open fuzzy Jump-to-Repo picker
* `f` : Enter repository list search query input mode
* `Tab` / `Shift+Tab` : Cycle summary-bar filter (repos → dirty → ahead → stale) forward / backward
* `L` : Open label picker to filter the list to one label ("project view"; sticky until deselected)
* `1` … `9` : Apply the label in quick slot N (the numbered chips under the summary bar) as the filter; press again to clear
* `ctrl-f` : Open global code search across all repositories
* `ctrl-p` : Open the command palette (fuzzy-find and run any home action by name)
* `R` : Refresh status of selected item manually
* `F` : Bulk fetch all repositories concurrently
* `E` : Show why the selected repository's last fetch failed
* `o` : Cycle sorting criteria (Custom → Alphabetical → Recent → Changes); acts on the active label's own sort when its Label Settings set one
* `O` : Toggle reverse sorting; acts on the active label's own direction when its Label Settings set one
* `v` : Cycle repository list layout (Normal/Compact/Tile); acts on the active label's own layout when its Label Settings set one
* `a` : Add a repository via the directory-scanner picker; the new repository is selected, and its label group is expanded if it was collapsed
* `A` : Bulk add subdirectories of a directory; the first new repository is selected
* `i` : Import / clone a remote repository
* `e` : Edit the selected repository's path; its labels, star, pin, settings and history move with it, and a path already tracked by another entry is refused
* `D` : Delete selected repository entry
* `l` : Edit custom labels of selected item
* `t` : Open the embedded terminal panel in repository path
* `T` : Open a full-screen external shell in the highlighted repository (or in each multi-selected one)
* `g` : Launch preferred external Git GUI client in the highlighted repository
* `d` : Open debug logs panel
* `V` : Open about dialog
* `h` : Show signs & symbols legend popup
* `u` : Check for updates manually
* `s` : Open settings view
* `?` : Toggle help overlay
* `ctrl-q` : Quit Gitwig
* **Grouping Sidebar (Left)**: Visible when `Show Grouping` is enabled. Groups repositories into Recent, Starred, and custom Labels. A repository can be listed under several groups at once; anything that reorders the rows — changing the sort, pinning or starring, or opening a repository (which moves it to the top of Recent) — keeps the cursor on the same repository in the same group.
* *Shortcuts*:
* `←` / `→` : Collapse / expand the selected group (when on a group header row; there is no sidebar focus toggle)
* `Space` / `Enter` : Toggle collapse / expand of label groups (when on a group header row)
* **Label Picker Overlay** (`L`): Floating fuzzy picker listing every label with its repository count, plus an "All repositories" row. Selecting a label filters the home list to it — a sticky "project view" that survives `Esc` and app restarts until deselected (re-select the active label or choose "All repositories"). The active label is marked with ● in the picker, labels holding a quick slot show their `1`-`9` key beside the name, and it is pinned as a highlighted `● label` badge centered in the frame's top border (clickable to reopen the picker), and shown as a `Label:` chip in the status bar; the summary tabs' counts scope to the selected label. Press `→` on a highlighted label to open its **Label Settings** popup (see below), where settings shared by every repository carrying that label are edited. If the active label has a theme set in its Label Settings, the home repo-list view is tinted with that theme while the filter is active.
* **Bottom Command/Status Bar**: Reflects current keyboard context, active mode, background fetches, and CPU/memory statistics.
* **Embedded Terminal Panel** (`t` on Home, `ctrl+t` anywhere): An IDE-style integrated terminal docked above the status bar, available from both the Home list and the Detail view. It runs your `$SHELL` in a PTY, starting in the selected repository's directory, and every other view shrinks to make room while it is open.
* A single shell session is kept per app run: hiding the panel (`ctrl+t`) leaves the shell and anything running in it alive; reopening shows it exactly where you left off. The session ends when the shell exits (a placeholder then invites any key to close) or when Gitwig quits.
* While the panel is focused (accent border), every key is forwarded to the shell except `ctrl+t` (hide), `ctrl+q` (quit Gitwig), and `Shift+PgUp`/`Shift+PgDn` (scrollback, 1000 lines kept; the title shows `[+N]` while scrolled back). Clicking the panel focuses it; clicking anywhere else unfocuses it while keeping it visible; the mouse wheel scrolls history.
* The environment variables `GITWIG=1` and `GITWIG_SHELL=1` are set in the shell, and `TERM` is `xterm-256color`.
---
## 2. Repository Detail / Workspace View
Triggered by opening a repository.
### Sidebar Panel (Left)
* **Tab Selector Panel**: Navigates between primary and advanced views.
* *Shortcuts*:
* `Esc` / `q` / `Q` : Close details / Return to Home Screen (in the Advanced tab group the first press steps back to the Primary tabs; an open full diff or commit search is closed first)
* `?` : Toggle detail view shortcut help overlay
* `w` : Cycle focus forward through panels
* `W` : Cycle focus backward through panels
* `+` / `-` : Grow (`+`) or shrink (`-`) the focused panel by moving its layout split (same splits the mouse can drag)
* `Tab` : Cycle tab forward
* `Shift+Tab` / `backtab` : Cycle tab backward
* `R` : Resync active tab details manually
* `ctrl-p` : Open the command palette (fuzzy-find and run any repository or active-tab action by name)
* `1` - `7` : Jump directly to Tabs 1-7 (or `1` - `5` for the five advanced tabs when the Advanced group is active)
* `Z` : Toggle Advanced Tab group (Worktrees, Submodules, Reflog, Issues, PRs)
* `O` : Show repository Overview overlay
### Main Workspace Tabs
#### Tab 0: Workspace (Commits History & Workspace Staging)
* *Commits List Panel (Left)*: Lists Git commit logs with authors, dates, and messages. Includes an "Uncommitted changes" virtual item at the very top.
* *Shortcuts*:
* `↑` / `k` / `K` : Move selection up
* `↓` / `j` / `J` : Move selection down
* `PgUp` / `PgDn` : Scroll commit list
* `Home` / `End` : Jump to top / bottom of list
* `Enter` / `→` : Inspect selected commit (enters Commit Inspection Layout)
* `t` / `T` : Create tag at selected commit
* `b` / `B` : Create new branch at selected commit
* `y` / `Y` : Yank selected commit hash
* `o` : Checkout selected commit (detached HEAD; `O` opens the Overview overlay instead)
* `v` / `V` : Revert selected commit
* `p` / `P` : Cherry-pick selected commit
* `i` / `I` : Run interactive rebase from selected commit
* `s` / `S` : Open stashing UI panel
* `c` : Open Commit message dialog
* `C` : Open Commit message dialog with Amend
* `/` : Fuzzy search commits list
* `f` : Open search column picker popup
* `l` / `L` : Open full-screen Logs view
* `G` : Load more commits
* *Commit Info Panel (Top Right)*: Metadata and descriptions of the selected commit.
* *Files List Panel (Bottom Right)*: List of changed files in the selected commit. Displays inline diff on selection.
* *Staged / Unstaged / Conflicts Panels*: Shown while the "Uncommitted changes" item is selected; the same panels as the Commit Inspection Layout, driven from the Workspace tab.
* *Shortcuts*:
* `↑` / `k` / `K` / `↓` / `j` / `J` : Navigate file lists
* `PgUp` / `PgDn` / `Home` / `End` : Page through / jump to top or bottom of the focused list
* `Enter` : Stage selected file (if in Unstaged list) or Unstage selected file (if in Staged list); in the Conflicts list, open the conflict diff in the Commit Inspection Layout
* `→` : Open the selected file's diff in the Commit Inspection Layout (Staged / Unstaged / Conflicts)
* `a` / `A` : Stage all changes (if in Unstaged) or Unstage all changes (if in Staged)
* `x` : Discard changes in selected file (Staged / Unstaged; opens confirmation dialog)
* `X` : Discard all unstaged changes in repository (opens confirmation dialog)
* `s` / `S` : Open stashing UI panel
* `c` : Start commit message dialog
* `C` : Start commit message dialog with Amend (Staged / Unstaged only)
* *Conflict Resolution Shortcuts (Conflicts panel only)*:
* `o` : Accept OURS version of conflict
* `t` : Accept THEIRS version of conflict
* `r` : Mark conflict as resolved
* `A` : Abort the merge (opens confirmation dialog)
* `C` : Continue the merge (opens confirmation dialog)
* `M` : Open external mergetool
#### Tab 1: Files Tab (Working Directory Browser)
* *File Tree Panel (Left)*: Lists all files in the current workspace directory.
* *Shortcuts*:
* `↑` / `k` / `K` : Move selection up
* `↓` / `j` / `J` : Move selection down
* `PgUp` / `PgDn` : Scroll file list
* `Home` / `End` : Jump to top / bottom of file tree
* `>` / `→` / `Enter` : Expand / toggle selected folder in tree
* `<` / `,` : Collapse selected folder in tree
* `←` : Collapse all folders in tree
* `b` / `B` : Toggle git blame panel
* `n` / `N` : Toggle line numbers in content viewer
* `e` / `o` : Open selected file in default terminal editor
* `H` : View commit history of the selected file
* `x` / `X` : Discard changes in the selected file (asks confirmation)
* `/` : Launch fuzzy file search picker
* *File Content Viewer (Right)*: Displays code content of the selected file. Supports git blame when toggled.
* *Shortcuts when focused*:
* `↑` / `k` / `K` : Scroll content up
* `↓` / `j` / `J` : Scroll content down
* `PgUp` / `PgDown` : Scroll content page up / down
* `Home` / `End` : Scroll to top / bottom of content
* `→` : Enter full-screen view mode
* `←` : Exit full-screen view mode
#### Tab 2: Graph Tab
* *Commit Graph Panel*: A full-width panel displaying a visual branch-merging history graph.
* *Shortcuts*:
* `↑` / `k` / `K` : Move selection up
* `↓` / `j` / `J` : Move selection down
* `PgUp` / `PgDn` : Scroll graph page
* `Home` / `End` : Jump to top / bottom
* `Enter` / `→` : Inspect selected commit (enters Commit Inspection Layout)
* `y` / `Y` : Yank selected commit hash
#### Tab 3: Branches Tab
* *Branches Lists (Local left, Remote right)*: Displays repository branches.
* *Shortcuts*:
* `←` / `→` : Switch focus between Local and Remote branches lists
* `↑` / `k` / `K` : Move selection up
* `↓` / `j` / `J` : Move selection down
* `PgUp` / `PgDn` / `Home` / `End` : Navigate branch lists
* `Enter` : Checkout selected branch
* `c` / `C` : Create new branch
* `D` : Delete selected branch
* `m` : Merge selected branch into current branch
* `M` : Checkout selected local branch and merge the (previously) current branch into it (Local list only; with the Remote list focused `M` falls through to a plain merge, same as `m`)
* `r` : Rebase current branch onto selected branch
* `i` / `I` : Interactive rebase of current branch onto selected branch
* `p` : Pull remote changes (for local branches)
* `P` : Push selected branch to remote (for local branches; supports `y` Push, `t` Push + Tags `--tags`)
* `f` / `F` : Fetch remote
* `a` / `A` : Add a new remote
* `/` : Fuzzy search branches
#### Tab 4: Tags Tab
* *Tags List Panel*: Lists local and remote tags.
* *Shortcuts*:
* `↑` / `k` / `K` / `↓` / `j` / `J` : Move selection
* `PgUp` / `PgDn` / `Home` / `End` : Navigate tag list
* `Enter` : Checkout selected tag
* `D` : Delete selected tag
* `p` : Push selected tag to remote (supports `y` Push, `f` Force Push `--force`)
* `P` : Push all tags to remote
* `f` / `F` : Fetch remote tags
* `/` : Fuzzy search tags
* All of the action keys above (`checkout`, `delete`, `push`, `push_all`, `fetch`, `search`) are rebindable under the `[tags]` section of `keybindings.toml` or via Settings → Keybindings; the status bar reflects the configured keys.
* *Note*: Tags are created with `t` / `T` from the Workspace tab's commits list (annotated `-m` or lightweight; Tab toggles input fields; prompts to force update `-f` if existing) — there is no create-tag key on this tab.
#### Tab 5: Remotes Tab
* *Remotes List Panel*: Lists configured remote sources.
* *Shortcuts*:
* `↑` / `k` / `K` / `↓` / `j` / `J` : Move selection
* `PgUp` / `PgDn` / `Home` / `End` : Navigate remote list
* `a` / `A` : Add a new remote
* `D` : Delete selected remote
* `f` / `F` : Fetch selected remote (opens picker if multiple remotes exist)
#### Tab 6: Stashes Tab
* *Stashes Panel (Left)*: Lists stashed changes.
* *Shortcuts*:
* `↑` / `k` / `K` / `↓` / `j` / `J` : Move selection
* `PgUp` / `PgDn` / `Home` / `End` : Navigate stashes list
* `a` / `A` : Apply selected stash
* `s` / `S` : Create a new stash (opens stash message input)
* `D` : Delete selected stash
* *Stashed Files Panel (Top Right)*: Lists files in selected stash.
* *Stash Diff Panel (Bottom Right)*: Diff preview of selected stashed files.
#### Tab 7: Worktrees Tab (Advanced Tab Group)
* *Worktrees List Panel*: Lists worktrees.
* *Shortcuts*:
* `↑` / `k` / `K` / `↓` / `j` / `J` : Move selection
* `PgUp` / `PgDn` / `Home` / `End` : Navigate worktrees list
* `Enter` : Open selected worktree in new Gitwig context (adds it to the repository list, or opens its existing entry if it is already tracked, and focuses it; the view starts on the Primary tabs)
* `a` : Add new worktree: enter a branch, tag or commit to check out (a branch that exists only on one remote becomes a local branch tracking it), or a new branch name to create it at HEAD; then the folder path
* `D` : Remove selected worktree and its folder. The status bar asks for a choice: `1` removes it only if it is clean (git refuses one with uncommitted changes or a lock, and nothing is deleted); `2` force-removes it, discarding uncommitted changes and overriding a lock. `Esc` cancels.
* `l` : Toggle lock status of selected worktree (asks for reason if locking)
* `p` : Prune stale worktree metadata
#### Tab 8: Submodules Tab (Advanced Tab Group)
* *Submodules List Panel*: Lists submodules.
* *Shortcuts*:
* `↑` / `k` / `K` / `↓` / `j` / `J` : Move selection
* `PgUp` / `PgDn` / `Home` / `End` : Navigate submodules list
* `a` : Add new submodule: enter its repository URL, then the path to check it out at; it is cloned and initialized
* `D` : Delete selected submodule (asks confirmation; the popup names its path, and its name when that differs). Deinitializes it, removes its folder, gitlink and `.gitmodules` entry, and deletes its module directory under the git dir; the removal is staged for you to commit, and the list shows the submodule as "Removal staged" until you do. Only a real submodule entry in the index is ever removed.
* `u` : Initialize / update the selected submodule (`git submodule update --init --recursive`): an Uninitialized one is cloned and checked out, a Modified one goes back to the commit the repository records. Asks confirmation first when it shows Modified; never forced, so uncommitted changes a checkout would overwrite fail the update instead
* `U` : Initialize / update every submodule the same way (asks confirmation first when any shows Modified, listing them)
#### Tab 9: Reflog Tab (Advanced Tab Group)
* *Reflog List Panel*: Lists local reference logs.
* *Shortcuts*:
* `↑` / `k` / `K` / `↓` / `j` / `J` : Move selection
* `PgUp` / `PgDn` / `Home` / `End` : Navigate reflog list
* `Enter` / `Space` : Checkout commit OID of selected reflog entry (asks confirmation, detaching HEAD)
#### Tab 10: Forge Issues Tab (Advanced Tab Group)
* *Forge Issues Panel*: Lists open GitHub issues through `gh` (assigned to you by default, or all open with `a`), with the selected issue's details below.
* *Shortcuts*:
* `↑` / `k` / `K` / `↓` / `j` / `J` : Move selection
* `PgUp` / `PgDn` / `Home` / `End` : Navigate issues list
* `Enter` : Checkout branch corresponding to selected issue (asks confirmation): the branch linked to the issue on GitHub (its Development section / `gh issue develop`) if there is exactly one and it is in this clone; otherwise the one local branch — or, failing that, the one remote-tracking branch — whose name carries the issue number as a token of its own (`issue-12-login`, `12-fix` and `fix/12` for #12; never `v1.2` or `issue-123`); otherwise a new `issue-<number>` branch. Several candidates are listed in an error instead of guessed between.
* `o` : Open selected issue in web browser
* `a` : Toggle between "Assigned to me" and all open issues
#### Tab 11: Forge PRs Tab (Advanced Tab Group)
* *Forge Pull Requests Panel*: Lists open pull requests through `gh`, with the selected PR's details below: CI/CD checks (check runs and commit statuses; running checks show their status), reviews, and line comments. If the comments fail to load, the error is shown there and `R` retries.
* *Shortcuts*:
* `↑` / `k` / `K` / `↓` / `j` / `J` : Move selection
* `PgUp` / `PgDn` / `Home` / `End` : Navigate PRs list
* `Enter` : Checkout branch corresponding to selected PR (`gh pr checkout`; asks confirmation)
* `o` : Open selected PR in web browser
* `n` : Add a line comment to the current Pull Request, in three steps: file path, line number (a whole number, 1 or more) and comment text. An empty path or comment, or an invalid line number, shows an error and keeps the step open with what you typed; `Esc` cancels.
---
## 3. Commit Inspection Layout (`Mode::Inspect`)
Workspace layout for inspecting commits and diffs in details.
* *General Shortcuts*:
* `Esc` / `q` / `Q` : Exit inspection, return to Workspace Tab
* `w` : Cycle focus forward between Staged, Unstaged, Conflicts, and Diff viewer panels
* `W` : Cycle focus backward between panels
* `?` : Toggle inspect view shortcut help
* *Staging Lists Shortcuts (Staged/Unstaged/Conflicts)*:
* `↑` / `k` / `K` / `↓` / `j` / `J` : Navigate file lists
* `Enter` : Stage selected file (if in Unstaged list) or Unstage selected file (if in Staged list)
* `a` : Stage all changes (if in Unstaged) or Unstage all changes (if in Staged)
* `x` : Discard changes in selected unstaged file (opens confirmation dialog)
* `X` : Discard all unstaged changes in repository (opens confirmation dialog)
* `c` : Start commit message dialog
* `C` : Start commit message dialog with Amend
* *Conflict Resolution Shortcuts (Conflicts Panel and Conflict Diff Viewer)*:
* `o` : Accept OURS version of conflict
* `t` : Accept THEIRS version of conflict
* `r` : Mark conflict as resolved
* `A` : Abort the merge
* `C` : Continue the merge
* `M` : Open external mergetool
* *Diff Viewer Panel Shortcuts*:
* `↑` / `k` / `K` / `↓` / `j` / `J` : Navigate lines / hunks (or scroll content)
* `PgUp` / `PgDn` / `Home` / `End` : Scroll diff viewer
* `→` : Expand diff viewer to full screen (sets `inspect_full_diff = true`)
* `←` : Exit full-screen diff viewer
* `l` / `L` : Toggle line-by-line stage/discard mode (switches between Hunk mode and Line mode)
* `Enter` / `s` : Stage selected line or hunk (when focused on Unstaged file diff)
* `Enter` / `u` : Unstage selected line or hunk (when focused on Staged file diff)
* `x` / `Delete` : Discard selected line or hunk (when focused on Unstaged file diff)
---
## 4. Conflict Resolution Panel (Inside Workspace Merge Conflict State)
Triggers when staging changes encounters merge conflicts.
* *Shortcuts (in Staging lists or Diff viewer)*:
* `o` : Accept OURS version of conflict
* `t` : Accept THEIRS version of conflict
* `r` : Mark conflict as resolved
* `A` : Abort merge (opens confirmation dialog)
* `C` : Continue merge (opens confirmation dialog)
* `M` : Open external mergetool for the selected file (Conflicts file list or ConflictDiff pane, Workspace tab or Inspect view)
---
## 5. Standalone Views (Full Screen / Dedicated Panels)
### Logs View (`Mode::Logs`)
Full-screen git commits history.
* *Shortcuts*:
* `Esc` / `q` / `Q` : Return to Workspace Tab
* `↑` / `k` / `K` / `↓` / `j` / `J` : Navigate commits
* `PgUp` / `PgDn` / `Home` / `End` : Scroll commits list
* `Enter` : Inspect selected commit (enters Commit Inspection Layout)
* `/` : Start commit fuzzy search picker
* `f` : Open search column picker popup
* `G` : Load more commits
### Per-File History View (`Mode::FileHistory`)
Commits history of selected file.
* *Shortcuts*:
* `Esc` / `q` / `Q` : Return to detail view
* `Tab` / `w` / `W` / `←` / `→` : Toggle keyboard focus between Revisions list and Diff panel
* `↑` / `k` / `K` / `↓` / `j` / `J` : Scroll list (when Revisions is focused) or scroll diff (when Diff is focused)
* `Home` / `End` : Jump to the first / last revision (Revisions focused) or to the top / bottom of the diff (Diff focused)
* `PgUp` / `PgDn` : Scroll the diff by 10 lines (Diff focused only; the Revisions list has no paging keys)
### Repository Overview Overlay (`Mode::Overview`)
Full-screen overlay summarizing the current repository (opened with `O` from the Detail view), split into an Overview pane and a Stats pane.
* *Shortcuts*:
* `Esc` / `q` / `Q` / `O` : Close overlay and return to Detail view
* `s` / `S` : Open Repository Settings popup
* `Tab` / `w` / `W` : Cycle pane focus between Overview and Stats
* `↑` / `k` / `K` / `↓` / `j` / `J` : Scroll focused pane
* `PgUp` / `PgDn` : Scroll focused pane by page
* `Home` / `End` : Jump to top / bottom of focused pane
### Stashing UI Panel (`Mode::StashingUI`)
Overlay for reviewing what will be stashed before saving (opened with `s` / `S` from the Workspace tab's commits or files list).
* *Shortcuts*:
* `s` / `S` : Save stash (opens stash message input)
* `u` / `U` : Toggle "Stash untracked files" option
* `i` / `I` : Toggle "Keep index" option
* `↑` / `k` / `K` / `↓` / `j` / `J` : Navigate the file list
* `Esc` / `q` / `Q` : Close and return to Detail view
### Debug Logs Panel (`Mode::DebugLogs`)
App logs viewer.
* *Shortcuts*:
* `Esc` / `q` / `D` / `l` / `L` : Return to Home Screen
* `↑` / `k` / `↓` / `j` : Scroll logs line-by-line
* `PgUp` / `PgDown` : Scroll logs page-by-page
* `Home` / `End` : Scroll to top / bottom of debug logs
* `/` : Enter fuzzy search query mode
* `c` / `C` / `x` : Clear all debug logs and reset scroll
### Settings View (`Mode::Settings`)
Full-screen configuration editor split into Categories and Fields.
* *Shortcuts*:
* `Esc` / `q` : Return to category sidebar (if in fields panel) or return to Home Screen (if in sidebar)
* `Q` : Return to Home Screen directly
* `1` - `5` : Jump directly to Category 1-5 (General, Sorting, Scan, Theme, Keybindings); Theme & Style holds Theme Name, View Mode, Tile Layout Columns and Show Separators
* `←` / `h` : Focus category sidebar
* `→` / `l` / `w` / `W` : Focus fields panel on the right
* `↑` / `k` / `K` / `↓` / `j` / `J` : Navigate categories (if focused on sidebar) or fields (if focused on fields)
* `PgUp` / `PgDown` : Jump selection to top / bottom of active category or fields
* `Home` / `End` : Jump to the first / last item of the active list
* `Enter` : Edit selected setting field (or toggle switch)
* *Shortcuts when editing a field*:
* `Enter` : Save and commit changes
* `Esc` : Cancel edits and revert field value
* `Backspace` / character keys : Input value
* `↑` / `k` / `↓` / `j` / `PgUp` / `PgDown` / `Home` / `End` : Navigate items (only when selecting a theme)
### Signs & Symbols Legend Popup (`Mode::Legend`)
Quick reference guide to badges, operations, and status indicators.
* *Shortcuts*:
* `Esc` / `q` / `Q` / `h` : Close legend popup
* `↑` / `k` / `↓` / `j` / `PgUp` / `PgDown` / `Home` / `End` : Scroll legend content
### About Popup (`Mode::About`)
Information about Gitwig, version details, and creator profile.
* *Shortcuts*:
* `Esc` / `q` / `Q` / `V` : Close about popup
### App Usage Stats Popup (`Mode::StatsDashboard`)
Dashboard detailing aggregated usage statistics such as session duration, total lines authored, repositories imported, branches/commits created, network activities, and a visual 52-week Activity Heatmap.
* *Shortcuts*:
* `Esc` / `Enter` / `q` / `Q` : Close stats dashboard
### Search Columns Selector Popup (`Mode::SearchColumnPicker`)
Picker to select columns to search by (SHA, Message, Author, Date) before entering fuzzy logs search.
* *Shortcuts*:
* `↑` / `k` / `↓` / `j` : Navigate search columns (SHA, Message, Author, Date)
* `Space` : Toggle selected search column checkbox
* `Enter` : Confirm and open logs search input modal
* `Esc` / `q` : Cancel and close columns selector
### Remote Picker Popup (`Mode::RemotePicker`)
Picker to select the target remote for sync/fetch operations when multiple remotes exist.
* *Shortcuts*:
* `↑` / `k` / `K` / `↓` / `j` / `J` : Navigate remotes list
* `Enter` : Confirm selected remote
* `Esc` / `q` / `Q` : Cancel and close picker
### Commit History Picker Popup (`Mode::CommitHistoryPicker`)
Picker listing historical commit messages to reuse (opened with `Ctrl+H` from the Commit Message Dialog).
* *Shortcuts*:
* `↑` / `k` / `↓` / `j` : Navigate commit messages
* `Enter` : Select message and return to the commit dialog
* `Esc` / `q` : Cancel and return to the commit dialog
### Repository Settings Popup (`Mode::RepoSettings`)
Custom per-repository config editor (Theme, Page Size, Max Commits, Resync on Tab Change, Auto Fetch interval, Editor path, custom Note, Git LFS Tracking/Pull, LFS Storage Size). Accessed via `s` on the repository Overview screen. The Auto Fetch row overrides the global `auto_fetch_interval_mins` for just that repository — leave it empty to inherit the global cadence, or set `0` to exclude the repository from background fetching.
* *Shortcuts*:
* `Esc` : Cancel text edit (if editing) or return to Detail view (if in popup)
* `q` : Return to Detail view
* `↑` / `k` / `↓` / `j` : Navigate settings rows
* `←` / `h` / `→` / `l` : Change values for option fields (Theme, Resync on Tab Change)
* `Enter` / `Space` : Edit/Toggle setting (toggles themes, enters text input for fields, runs LFS Pull, or refreshes LFS details)
### Label Settings Popup (`Mode::LabelSettings`)
Per-label config editor (Theme, Page Size, Max Commits, Resync on Tab Change, Auto Fetch interval, Editor path, Sort By, Sort Reverse, View Mode). Accessed via `→` on a highlighted label in the Label Picker Overlay. Settings chosen here apply to every repository carrying that label and are resolved between the per-repo override and the global default: a per-repo setting wins first, then the first of the repo's labels (in stored order) that defines the setting, then the global default. Each row left empty inherits the next tier down; the Auto Fetch row accepts `0` to exclude the whole label group from background fetching (handy for an `archive` label). The Theme row additionally tints the home repo-list view while that label's filter ("project view") is active — a visual cue for which project you are focused on. The Sort By and Sort Reverse rows are properties of the label view rather than of its repositories: they replace the global `sort_by` / `sort_reverse` only while that label's filter is active (the list re-sorts as soon as the row changes or the filter is entered or left, and reverts to the global order on leaving), the sort caption in the header names the label (`Sort: Alphabetical · work`), and the home `o` / `O` keys then edit the label's value instead of the global. The View Mode row (default / Normal / Compact / Tile) does the same for the list layout: the label's view is drawn in it instead of the global `view_mode`, the home `v` key then cycles the label's value, and the global layout returns on leaving the view. Label settings persist to `[label_configs.<label>]` in `config.toml`, and a label's settings are pruned automatically once no repository carries it.
* *Shortcuts*:
* `↑` / `k` / `↓` / `j` : Navigate settings rows
* `←` / `h` / `→` / `l` : Change values for option fields (Theme, Resync on Tab Change, Sort By, Sort Reverse, View Mode)
* `Enter` / `Space` : Edit/Toggle setting (toggles themes or enters text input for fields)
* `Esc` : Cancel text edit (if editing), otherwise return to the label picker
### Track Launch Directory Popup (`Mode::AddCwdRepoConfirm`)
Shown at startup when the working directory sits inside a Git repository that is not tracked yet. Walks up from the launch directory to the repository root, so starting Gitwig anywhere inside a repo offers the root. Suppressed entirely by `prompt_cwd_repo = false`.
* *Shortcuts*:
* `y` : Add the repository and return to the Home Screen
* `n` / `Esc` / `Enter` : Dismiss without adding
### Not Git Repository Popup (`Mode::NotGitRepo`)
Warning dialog shown when selecting a directory that is not a valid Git repository.
* *Shortcuts*:
* `Esc` / `Enter` / `q` : Acknowledge warning and return to Home Screen
### Help Overlay (`Mode::Help` / `Mode::DetailHelp`)
Floating keyboard shortcut reference popup shown on top of the Home Screen or Detail View.
* *Shortcuts*:
* `Esc` / `q` / `Q` / `?` : Dismiss help overlay
### Global Search View (`Mode::GlobalSearch`)
Full-screen dashboard to search for keywords/code across all tracked repositories simultaneously.
* *Shortcuts*:
* `Esc` : Clear search and return to Home Screen
* `Tab` : Toggle keyboard focus between search input and matches list
* `↑` / `↓` : Scroll/navigate matched items
* `PgUp` / `PgDn` / `Home` / `End` : Navigate matches list
* `Enter` : Trigger search (if input is focused) or open selected file match in Detail view (if list is focused)
* `Backspace` / character keys : Input query (when input is focused)
---
## 6. Interactive Search & Picker Overlays
Floating modal components with search-as-you-type inputs. Matches are ranked and updated in real time.
* *Available overlays*:
* **Command Palette**: Fuzzy action runner (`Ctrl+P` on the Home Screen or in the Repository Detail view). Lists every action available in the current view — the home actions, or the repository actions plus the active tab's own — grouped by context, each with its current key. `Enter` runs the highlighted action through the same handler its key would use, so custom bindings work too; `Esc` or `Ctrl+P` closes it. Unlike the other overlays it is not a `Mode`: it floats over the view underneath, which keeps its state and gets the keyboard back on close.
* **RepoJump**: Fuzzy repository navigator (`/` on Home Screen)
* **RepoScanPicker**: Select repository path from scanned directories (`a` on Home Screen)
* **BulkAddScanPicker**: Select directory to scan and import repositories (`A` on Home Screen)
* **BranchSearchInput**: Fuzzy branch checkout picker (`/` on Branches Tab)
* **FileSearchInput**: Fuzzy file finder (`/` on Files Tab)
* **CommitFuzzySearch**: Fuzzy commit hash/message finder (`/` on Commits Tab or Logs View)
* **TagSearchInput**: Fuzzy tag checkout picker (`/` on Tags Tab)
* **RemotePicker**: Target remote selector for sync/fetch operations (opens when multiple remotes exist)
* **CommitHistoryPicker**: Historical commit message picker (`Ctrl+H` in the Commit Message Dialog)
* *Shortcuts inside overlays*:
* `Esc` : Cancel and close overlay
* `Enter` : Confirm selection
* `↑` / `↓` : Navigate matched items list
* `Home` / `End` / `PgUp` / `PgDn` : Jump to top / bottom or page through the match list
* `Backspace` : Delete search query character
* Character keys : Input fuzzy search query
---
## 7. Input Modals & Setup Dialogs
Modal text entry boxes for setting up configurations or typing messages.
* *Available dialogs*:
* **Commit Message Dialog**: Compose/edit commit messages. Supports `Ctrl+S` (submit directly), `Ctrl+U` (clear message buffer), `Ctrl+A` (toggle amend), `Ctrl+H` (history picker), `Ctrl+D` (maximize popup), `Ctrl+K` (kill to end of line), `Ctrl+W` (delete word before cursor), `Ctrl+B`/`Ctrl+F` (cursor left/right), `Ctrl+P`/`Ctrl+N` (line up/down), and `Ctrl+C` (finish typing to enter confirm mode with `x`/`u` to clear, `a`/`Space` to toggle amend, `d`/`D`/`m`/`M` to maximize/restore, `q` to close, and `Enter` to commit).
* **Branch / Tag / Stash Creation dialogs**: Enter new names.
* **Import / Remote Setup dialogs**: Enter URLs, names, and paths.
* **Worktree / Submodule Setup dialogs**: Enter paths, branches, or lock reasons. Removing a worktree asks in the status bar instead: type `1` (remove only if clean) or `2` (force-remove, discarding uncommitted changes) and press `Enter`.
* **PR Line Comment wizard** (`n` in the PRs tab): file path, line number and comment text, one step at a time; an invalid entry shows an error and keeps the step open.
* **Label entry dialogs**: Prompt custom labels for repository grouping.
* *Shortcuts*:
* `Esc` : Cancel / close dialog (note: only `Esc` cancels modal inputs; letters like `q`/`Q` are typed as regular input text)
* `Enter` : Submit entry (for multi-line inputs like the Commit Dialog, use `Ctrl+S` to submit while editing, or `Ctrl+C` then `Enter`)
* `Backspace` : Erase character
* `Ctrl+V` / Terminal Paste : Paste text from system clipboard (single-line input dialogs automatically sanitize and strip trailing newlines)
* Character keys : Input characters
---
## 8. Warning & Confirmation Modals
Double-checks before executing hazardous or state-altering actions.
### The Safety Intercept Feature
To prevent accidental data loss due to muscle-memory `Enter` keypresses, Gitwig intercepts keystrokes on the router level. For any modal classified as a **Destructive Action**, pressing `Enter` defaults to **Cancel** (`ConfirmNo`). To confirm a destructive action, the user must explicitly press `y` or `Y`. For non-destructive actions, `Enter` acts normally to confirm.
### Destructive Actions (`Enter` acts as Cancel)
* **Discard Changes (`Mode::DiscardChangesConfirm`)**: Discarding unstaged/staged files. Only file-level discards ask for confirmation — hunk/line discards (`x` / `Delete` in the diff viewer) apply immediately without a dialog.
* **Delete Branch (`Mode::BranchDeleteConfirm`)**: Deleting a local or remote tracking branch.
* **Delete Tag (`Mode::TagDeleteConfirm`)**: Deleting a Git tag locally or remotely.
* **Delete Stash (`Mode::StashDeleteConfirm`)**: Dropping/deleting a stash entry from the stashes list.
* **Delete Remote (`Mode::RemoteDeleteConfirm`)**: Removing a configured remote repository connection.
* **Delete Submodule (`Mode::SubmoduleDeleteConfirm`)**: Deleting a submodule — its folder, gitlink, `.gitmodules` entry and module directory (the removal is staged for you to commit).
* **Remove Worktree (`Mode::WorktreeRemoveConfirm`)**: Not a popup but a status-bar prompt: type `1` (only if clean) or `2` (force) and press `Enter`; `Enter` with nothing typed removes nothing.
* **Abort Merge (`Mode::MergeAbortConfirm`)**: Aborting an active merge session (reverting resolved conflicts).
### Non-Destructive Actions (`Enter` acts as Confirm)
* **Branch Checkout (`Mode::BranchCheckoutConfirm`)**: Switching to another branch.
* **Commit Checkout (`Mode::CommitCheckoutConfirm`)**: Checking out a commit OID from the Workspace commits list or the Reflog tab.
* **Forge Checkout (`Mode::ForgeCheckoutConfirm`)**: Switching to the branch of the selected issue (Issues tab) or pull request (PRs tab).
* **Tag Checkout (`Mode::TagCheckoutConfirm`)**: Detaching HEAD to check out a tag.
* **Branch Push (`Mode::BranchPushConfirm`)**: Pushing commits to remote (supports `y` Push, `t` Push + Tags `--tags`).
* **Tag Overwrite (`Mode::TagOverwriteConfirm`)**: Force updating an existing tag (`-f`).
* **Tag Push (`Mode::TagPushConfirm` / `Mode::TagPushAllConfirm`)**: Pushing single or all tags to remote (supports `y` Push, `f` Force Push `--force`).
* **Branch Merge (`Mode::BranchMergeConfirm`)**: Merging a branch into the active branch.
* **Checkout & Merge Into (`Mode::BranchMergeIntoConfirm`)**: Checking out the selected branch and merging the previously current branch into it.
* **Rebase (`Mode::BranchRebaseConfirm` / `Mode::BranchInteractiveRebaseConfirm`)**: Rebasing the current branch.
* **Stash Apply (`Mode::StashApplyConfirm`)**: Applying a stash onto the working directory.
* **Cherry-Pick (`Mode::CherryPickConfirm`)**: Cherry-picking a commit.
* **Submodule Update (`Mode::SubmoduleUpdateConfirm`)**: Updating a submodule that shows Modified (or, with `U`, every submodule when any does), which moves its checked-out commit back to the one the repository records.
* **Revert (`Mode::RevertConfirm`)**: Creating a revert commit for a specific commit.
* **Continue Merge (`Mode::MergeContinueConfirm`)**: Continuing a merge after conflicts are resolved.
* **Self-Update (`Mode::UpdateConfirm`)**: Confirming a self-update.
### Shortcuts
* `y` / `Y` : Confirm action (required for destructive actions; works for all except Cherry-Pick, which confirms with `Enter` only)
* `f` / `F` : Force push tag (`--force`) in Tag Push confirmation dialog
* `t` / `T` : Push branch with tags (`--tags`) in Branch Push confirmation dialog
* `Esc` / `n` / `N` : Cancel action / close popup (Cherry-Pick cancels with `Esc` / `q` / `Q` instead; `n` does nothing there)
* `Enter` : Confirm action (only works for non-destructive actions; cancels for destructive actions)