pigit 2.6.1

 ____ ___ ____ ___ _____
|  _ \_ _/ ___|_ _|_   _|
| |_) | | |  _ | |  | |
|  __/| | |_| || |  | |
|_|  |___\____|___| |_|

🚀 Quick Start

$ pip install -U pigit

$ pigit                 # launch the TUI
$ pigit cmd -l          # list short commands
$ pigit repo add ~/dev/foo ~/dev/bar
$ pigit repo ll         # summary across repos
$ pigit open            # open remote in browser

💡 The TUI opens on the first pigit run — 1/2/3/4 switch panels, ; opens the command palette (type a command, then space to complete branch/file arguments), ? shows every key binding.

📦 Installation

From source

git clone https://github.com/zlj-zz/pigit.git --depth=1
cd pigit
make install
# or on Windows
python setup.py install

Development (editable install)

pip install -e ".[dev]"

Optional short aliases

pigit only installs the pigit command. If you want one-letter shortcuts, add them to your shell yourself (they are intentionally not registered globally, since names like g collide with common user aliases):

alias g='pigit cmd'
alias r='pigit repo'

🖥️ TUI Mode

Pigit's primary interface is a terminal UI. Simply run pigit to enter it — four core panels plus a global command palette:

Key bindings

Press ? for the full per-panel list. Every key is remappable via [app.keybindings] — see Keybindings.

For operations that are cumbersome on the command line—such as staging individual hunks, browsing commit history with inline graphs, or resolving merge conflicts—the TUI is the recommended workflow.

[!NOTE] The TUI runs on macOS / Linux and requires an interactive terminal (both stdin and stdout must be TTYs). It will not launch in CI pipelines, scripts, or when piped. On Windows, only the CLI sub-commands are available.

⌨️ CLI Usage

For scripting, CI, or quick tasks, Pigit exposes sub-commands and flags.

usage: pigit [-h] [-i] [-f] [-r] [-v] [-c [PATH]] [--create-ignore TYPE]
             [--init [SHELL]] [--create-config] [--with-keybindings]
             {cmd,repo,open} ...

Pigit TUI is called automatically if no parameters are followed.

cmd — short commands

Short aliases for common git operations.

Discovery

• pigit cmd -l — list all short commands with help text and underlying git lines.
• pigit cmd -s <query> / --search <query> — filter by keyword.
• pigit cmd -t <category> — filter by category (branch, commit, index, etc.).
• pigit cmd -p / --pick — interactive picker (TTY only): j/k to move, Enter to run, / to filter, q to quit.

Example output from pigit cmd -l:

These are short commands that can replace git operations:
    b        lists, creates, renames, and deletes branches.
             git branch
    bc       creates a new branch.
             git checkout -b
    bl       lists branches and their commits.
             git branch -vv
    bd       delete a local branch by name.
             git branch -d
......

repo — multi-repo management

Manage multiple repositories at once.

• pigit repo add <path> — add repo(s) to the managed list.
• pigit repo rm <name> — remove repo(s).
• pigit repo ll — display summary of all repos.
• pigit repo cd <name> — print the path of a managed repo.
• pigit repo cd -p — open the interactive picker to choose a repo.
• pigit repo cd --output-file <path> — write the selected path to a file instead (for scripts/CI).
• pigit repo fetch|pull|push [<name>...] — run git operations across repos in parallel.

open — open remote in browser

Open the current repository's remote URL in a web browser.

pigit open              # open current branch
pigit open <branch>     # open specific branch
pigit open -c           # open at current commit
pigit open -i <number>  # open a specific issue
pigit open -p           # print URL instead of opening

Other flags

🔌 Shell Integration

pigit --init generates shell completion scripts and a pigit wrapper function.

[!TIP] Run --init once: it sets up both tab-completion and the repo cd auto-cd wrapper. You do not need a separate completion-only step.

Add it to your shell configuration:

# ~/.bashrc or ~/.zshrc
eval "$(pigit --init)"

Supports bash, zsh, and fish. If no shell is specified, it auto-detects from $SHELL.

Auto cd with repo cd

After sourcing the init script, pigit repo cd -p automatically changes your shell's working directory when you pick a repo. The wrapper intercepts pigit repo cd, runs the picker, and cds into the selected path.

For scripts and CI, use --output-file <path> to write the selected directory to a file instead.

🛠️ Configuration

Create a template config with pigit --create-config. The config lives at:

• Linux/macOS: ~/.config/pigit/pigit.toml
• Windows: %USERPROFILE%\pigit\pigit.toml

See examples/pigit.toml for a full template.

Keybindings

Remap app actions with an [app.keybindings] section. Keys are semantic strings ("c", "down", "ctrl c", " " for space); use an array for multiple keys.

To list every configurable action with its default key, regenerate the config with:

pigit --create-config --with-keybindings

This appends a commented [app.keybindings] block to the generated file (existing overrides are preserved as active lines). For example:

[app.keybindings.branch]
checkout = "C"  # default: "c"
# next = ["j", "down"]  # Navigate branch list

Actions are scoped by namespace: universal, status, diff, rebase, branch, commit, stash, recent.

🧩 Custom Commands

Define aliases and scripts in pigit.cmds.toml inside the pigit home directory.

Aliases

[cmd_new.aliases]
mybl = "bl"
mylog = "log --oneline --graph"

Scripts

[cmd_new.scripts.myscript]
steps = ["status", "log --oneline"]
help = "Show status then log"
category = "script"

# concise form for simple step lists
[cmd_new.scripts]
quick-check = ["status", "diff --cached"]

User-defined entries appear in pigit cmd -l, search, and --pick with [alias] or [script] prefixes.

✨ Features

🖥️ TUI

• Session history / undo ↩️ — one-key reversal with confirmation (u), a browsable undo stack (U), and undo for merge, rebase, and cherry-pick.
• Command palette 🎯 — ; opens a filterable command list; parameterized commands (checkout/merge/stage/gitignore) complete branch/file arguments.
• Hunk staging 🔪 — stage or unstage individual hunks directly in the diff viewer (H).
• Inline commit editor ✍️ — subject/body fields with lint bar inside the TUI.
• Stash management 🗄️ — push, pop, and drop stashes from the status panel.
• Auto refresh 🔄 — periodic background refresh of the active panel while the TUI is idle.
• Syntax highlighting 🎨 — diff and file-history views tokenize source code by language (word-diff included).
• Adaptive layout 📐 — side-by-side preview panel on large terminals.
• Inspector sheet 🔍 — I opens a frozen selection snapshot as a top overlay (not a layout column).

⌨️ CLI

• Short commands ⚡ — aliases like pigit cmd st for git status --short.
• Command correction 🔧 — suggests the right command when you typo.
• Code statistics 📊 — count lines/files by type with table or simple output.
• .gitignore templates 🧹 — generate from common types.
• Quick open remote 🌐 — open repo/commit/issue in browser.

📚 Multi-repo & shell

• Multi-repo management 🗂️ — repo sub-commands for bulk operations across projects.
• Shell completion 🐚 — bash/zsh/fish with pigit --init.
• Auto cd 📁 — shell wrapper enables pigit repo cd -p to change directory after picking.

🎛️ Customization

• Custom keybindings 🎹 — remap any app action via [app.keybindings]; dump defaults with --create-config --with-keybindings.