Quick answers to questions that come up often. For detailed flow docs, see README.md. For security details, see SECURITY.md.
Only if you pick a hosted provider (OpenAI, OpenRouter). Gitbasher sends the staged diff plus a short system prompt to the provider's API; the provider's data-retention policy then applies. Pick ollama to keep everything local — the diff never leaves your machine. The claude provider runs through your local Claude Code CLI, so the diff goes to Anthropic under your own Claude account.
brew install ollama # or follow https://ollama.com for your OS
ollama serve # daemon, leave running
ollama pull qwen3:8b # or any model you prefer
gitb cfg ai # wizard: choose ollama, pick from your pulled modelsAfter that, gitb commit ai runs against http://localhost:11434 and never makes an outbound call.
By default in git config gitbasher.ai-api-key-<provider> (per-repo). Repo-local config files are not pushed to remotes, but they are readable by anything with filesystem access to your repo. For shared machines or anything sensitive, prefer environment variables — gitbasher checks them first:
export GITB_AI_API_KEY_OPENAI=sk-...
export GITB_AI_API_KEY_OPENROUTER=...Bare gitb cfg shows which slot each key resolves from; gitb cfg ai shows the configured key in masked form. The mask_api_key helper masks keys in any diagnostic output gitbasher prints.
The active provider has no key in any of the slots gitbasher checks (env var → per-provider config → legacy config, local then global). Run gitb cfg ai and pick the right provider, or export GITB_AI_API_KEY_<PROVIDER>=....
Bash 3.2 or newer. That's the version macOS still ships as /bin/bash (frozen at 3.2 for license reasons), so gitbasher runs out of the box on a stock Mac — no brew install bash required.
Bash 4-only features (mapfile, associative arrays, ${var,,} case-folding, read -i) were removed in favor of bash 3.2-compatible equivalents: a small portable map/set shim in scripts/common.sh, tr-based case folding, and a graceful read fallback. Installing a newer bash is still nice-to-have — on bash 4+, prompts that come pre-filled with a value (editing an AI-suggested commit message, renaming a branch) let you edit the text in place; on bash 3.2 you retype the line or press Enter to keep the current value.
Only genuinely ancient shells (bash < 3.2) are unsupported; for those, gitbasher tries to re-exec under a newer bash before printing an install hint.
Inside WSL, yes — treat it as Linux. Native Windows (cmd, PowerShell, Git Bash) is not supported.
Yes for non-interactive subcommands (gitb status, gitb pull dry, etc.). Anything that prompts (gitb commit with no flags, gitb merge) will block waiting on stdin. Pipe answers in, or use the explicit modes that accept arguments (gitb commit fast, gitb push yes).
In git config under the gitbasher.* namespace. Per-repo by default (in .git/config); every gitb cfg setter then asks whether to set the value globally — answering yes moves it to ~/.gitconfig (one copy, no local shadow that would hide later global changes). The keys you'll see most:
| Key | What it controls |
|---|---|
gitbasher.scopes |
Conventional-Commit scope list shown by gitb commit |
gitbasher.ai-provider |
openai, openrouter, ollama, claude |
gitbasher.ai-model-<provider> |
Model for that provider — one model for all tasks, remembered per provider |
gitbasher.ai-api-key-<provider> |
Per-provider key |
gitbasher.ai-proxy |
Outbound proxy for AI calls |
gitbasher.worktreebase |
Base directory for worktrees (gitb worktree, gitb wip up worktree) |
Touch them through gitb cfg ... rather than git config directly so you get the same precedence rules gitbasher uses internally.
For per-repo settings, copy .git/config (or just the [gitbasher] section). For global settings, copy ~/.gitconfig. Don't sync API keys this way — set them via env vars on the new machine.
# self-update (recommended)
gitb update
# or rerun the installer
curl -fsSL https://raw.githubusercontent.com/maxbolgarin/gitbasher/main/install.sh | bash
# pin a specific version
GITB_VERSION=v5.0.0 curl -fsSL https://raw.githubusercontent.com/maxbolgarin/gitbasher/main/install.sh | bashThe installer detects an existing install and replaces it in place; downloads are SHA-256-verified when the release's checksum asset and a sha256 tool are available (otherwise it warns and continues).
gitb uninstall # removes the binary and local + global gitbasher.* config keys
git config --global --remove-section gitbasher 2>/dev/null # only if you skipped gitb uninstallFor npm installs: npm uninstall -g gitbasher. For system-wide installs: sudo rm /usr/local/bin/gitb.
The npm package ships the same dist/gitb Bash binary plus a bin entry. Node.js is only needed to run npm install itself, not to run gitb — gitbasher is pure Bash at runtime. If you don't want Node, use the curl installer.
It saves your in-progress changes so you can switch contexts safely. Three backends:
- stash (default) —
git stash pushwith metadata gitbasher tracks sogitb wip downrestores cleanly; by default it also force-pushes awip/<branch>backup branch to the remote (skip withnopush). - branch — commits to a sidekick branch named after your current branch with a
wip/prefix; restored viagit merge --squash --no-commit. - worktree — moves the dirty tree into a separate
git worktreeso the original branch stays clean. Best when you need to run two contexts side-by-side.
Pick a backend explicitly with gitb wip up <backend> (e.g. gitb wip up worktree); plain gitb wip up prompts for one each time.
gitb undo reverses your last Git operation — you pick which kind, and it targets the most recent action of that type (there is no reflog picker):
gitb undo/undo commit— undoes the last commit viagit reset --soft HEAD~1, keeping its changes staged.undo amend— restores the pre-amend commit (located via reflog).undo merge/undo rebase— aborts one in progress, or rolls a finished one back toORIG_HEAD.undo stash— re-stashes changes you just popped or applied.
Everything except undo rebase (which is a --hard reset) and undo merge (a git reset --merge, which discards the merge's changes) preserves your changes. And because Git keeps a reflog, even a mistaken undo is recoverable — gitb reset ref lets you jump HEAD to any recent state (reflog retention defaults to 90 days for reachable commits, 30 days for unreachable).
They overlap but answer different questions:
gitb resetis position-based — "move my branch back to a point." You choose the destination: the last commit (gitb reset, orreset softto keep changes staged), any older commit (reset interactive), or a reflog entry (reset ref). It never uses--hard, so your file changes are always preserved.gitb undois operation-based — "reverse the last thing I did" (commit, amend, merge, rebase, or stash), with the right git command picked for you.
They meet in one spot: gitb undo and gitb reset soft both soft-reset the last commit. Reach for undo as the quick one-liner; reach for reset when you want to go back further or choose mixed-vs-soft.
Neither removes a single commit from the middle of history. Resetting to the 5th of 10 commits moves HEAD there and drops the four newer commits too (their changes land back in your working tree). To excise or edit just one older commit, use gitb rebase interactive (base = a branch) or gitb rebase autosquash (pick a base commit, then set that commit's line to drop/edit in the todo list). If the commit is already pushed and shared, prefer gitb commit revert, which adds a new commit that undoes the target without rewriting history.
Run gitb sync. It shows the divergence and rebases by default (use gitb sync merge to merge instead); gitb sync dry previews incoming commits before touching your local refs.
Bare gitb log is now an interactive browser: a numbered, paginated commit list where picking a commit shows it and offers actions (diff, stat, copy hash, revert, cherry-pick, fixup, restore a file). The old full dump is still there as gitb log all (alias dump). Piping still works — non-interactive runs print a plain git log-style listing and exit. You can also pass an argument directly: a number (gitb log 20), a file path, a ref or range, or words to search commit messages. Page size: git config gitbasher.log-count 30.
Fetches, pushes, pulls, branch switches, merges, stashes, worktree creation and AI requests show a spinner with elapsed seconds once they take longer than about a second. If a fetch, push, or checkout runs past ~10s, git's own progress (Receiving objects: 45%, Updating files: 80%) takes over. Quick commands print nothing extra. Set GITBASHER_NO_SPINNER=1 to turn the spinner off; it is also off automatically when output is not a terminal, and for network commands where git may ask for a password.
Open an issue from the Bug Report template at https://github.com/maxbolgarin/gitbasher/issues. Include gitb --version, the exact command, and the output. For security-sensitive issues, see SECURITY.md — there's a private reporting path.
Start with ARCHITECTURE.md. It covers the single-process sourcing model, the build pipeline that produces dist/gitb, and the test harness conventions. CONTRIBUTING.md has the day-to-day dev setup.