CandyGit
Terminal Git client — staging, branching, log, diff, stash, worktrees, rebase
Terminal Git client on the SugarCraft stack — a TUI for staging, branching, log, diff, stash, worktrees and rebase. Status, branches and log panes cycle with tab; P opens the diff viewer with per-hunk staging, and u / Ctrl+r undo and redo the last mutations through a 100-entry history. Every verb shells out to the user's own git — no reimplementation — so your existing hooks, GPG signing and credentials ride along; the plumbing verbs never consult git aliases, though, so they run git's built-ins exactly as typed.
Install
composer require sugarcraft/candy-git
Quickstart
# Run from any git working tree:
vendor/bin/candy-git
// Or wire your own driver in PHP:
use SugarCraft\Core\Program;
use SugarCraft\Core\ProgramOptions;
use SugarCraft\Git\App;
use SugarCraft\Git\Git;
$git = new Git(getcwd());
(new Program(App::start($git), new ProgramOptions(useAltScreen: true)))->run();
What's in the box
git status --porcelain=v1 -b with per-row index / work flags and a branch-summary header.git for-each-ref driven; current branch is highlighted + bold.s toggles staging via git add / git restore --staged, a stages all, d discards working-tree changes.P renders per-file diffs with syntax-highlighted hunks and per-hunk stage / unstage.c and A commit through your git, so hooks and signing config apply as they always do.S creates, applies, pops and drops stash entries via git stash.n creates a branch, D deletes one; space checks out.w lists worktrees and adds new ones via git worktree.M merges, r opens the sequencer menu (continue / abort; skip on a rebase) when stopped, V cherry-picks a typed ref, and i previews the interactive-rebase todo — the mutating rebase keys are parked and refuse with a notice.u / Ctrl+r step back and forward through HistoryManager (capped at MAX_HISTORY = 100 entries).GitDriver interface lets tests inject a fixture-backed driver without staging real repos.R reloads from disk; cursors are clamped if the row count shrinks.Lang::t() — key hints, error labels, empty-state messages, git error text.Trust boundary
Opening a repository executes its configuration unless told otherwise, and git has several config keys that name executables. CandyGit runs every git call through a fixed argument prelude — -c core.quotepath=off -c core.fsmonitor=false plus --no-ext-diff on diffs — that disarms the repo-controlled execution channels it can neutralize without breaking legitimate tooling; merge drivers are enumerated on the merged config scope and each overridden with false (resolved to the inert coreutils binary) before any merge-capable command, and a driver shape that cannot be re-expressed refuses the merge outright. Filter drivers (clean / smudge / process) are detected and announced on stderr rather than silently disarmed — git-lfs-class tooling depends on them working — with CANDY_GIT_STRICT_FILTERS=1 turning the posture into a refusal. Children spawn through a single proc_open site with a pinned environment. A hostile clone can still reach a trusted global git-lfs driver through its .gitattributes: operate only repositories you trust. The full disclosure lives in the README's Trust boundary section.
Internationalization
User-facing strings use SugarCraft\Git\Lang::t(). The keys live in lang/en.php with the git prefix inside the file — pass the file key verbatim: Lang::t('git.timeout'). The facade bakes the library namespace into every lookup, so the core registry sees git.git.timeout: namespace git, file key git.timeout. Lang::t('timeout') does NOT resolve — it asks for a file key the prefixed file never registers, and echoes the raw string back. Always call through SugarCraft\Git\Lang, never the raw registry.
| Key | Default | Parameters |
|---|---|---|
| git.spawn_failed | git: failed to spawn: {reason} | {reason} |
| git.error | git: {stderr} | {stderr} |
| git.timeout | git: command timed out after {seconds}s | {seconds} |
| cli.not_a_repo | candy-git: not a git repository: {cwd} | {cwd} |
| ui.error_prefix | error: | — |
| status.clean | clean working tree | — |
| branches.empty | (no branches) | — |
| log.empty | (empty log) | — |
| help.keyhints | S stash · V cherry-pick · i rebase-i · w worktrees · tab switch pane · j/k move · s stage/unstage · a stage all · d discard · enter diff · f fetch · p pull · P push · space checkout · c commit · A amend · n new branch · R refresh · u undo · M merge · r rebase · ? help · q quit | — |
The table above is an excerpt; lang/en.php is the full roster of 201 keys. To localize, copy lang/en.php to lang/<code>.php and translate the values.
The cli.not_a_repo refusal fires when git rev-parse --absolute-git-dir fails for the working directory — linked worktrees, where .git is a file rather than a directory, are accepted.
Source & demos
- Source on GitHub
- Full README
- Runnable examples
- Design antecedent: lazygit (Go); SugarCraft is developed as a native PHP project.
Key Classes
| Class | Method | Description |
|---|---|---|
| Git | new(cwd) | Create the shell-out git driver |
| Git | status() | Get working tree status |
| Git | branches() | List branches |
| Git | log() | Get commit log |
| Git | stage(path) | Stage file |
| Git | unstage(path) | Unstage file |
| GitDriver | interface | Driver contract the App consumes; tests inject a fixture-backed implementation |
| DiffViewer | currentHunkPatch() / hunkCount() | Per-file diff surface with per-hunk stage / unstage |
| StashManager | fuzzyFilter(query) | Smith-Waterman-ranked stash list via sugar-fuzzy |
| HistoryManager | push(entry) | Undo / redo lane, capped at MAX_HISTORY = 100 |
| App | start(git) | Create app model |
Demos.
VHS-recorded GIF demos. play.tape drives examples/play.php — a hermetic, fixture-backed build of the TUI that renders identically on every machine — while stage.tape drives the real ./bin/candy-git against the CI checkout, so its rows are environment-dependent.
Play
Pane tour — status / branches / log, cursor movement, stage / unstage.