gitbasher

The friendly git wrapper that types the boring parts for you.

In 30 seconds

What it is — a single-binary bash wrapper for git. Short interactive commands replace long flag chains.
Who it's for — developers who want clean conventional commits, smart pull/push/sync, and undo-everything safety without memorizing git plumbing.
What's different — AI commit messages that can run fully local via Ollama (no key, no network), atomic split, WIP backup across machines, full worktree menu — all in one bash file.

gitb commit push       # stage, write a conventional commit, push — in one flow
gitb commit ai         # AI-generated commit message
gitb sync              # fetch main + rebase your branch
gitb wip up            # stash WIP, push backup branch, clean working tree
gitb undo              # roll back your last commit / amend / merge / rebase / stash

Before & after

You just write what you want to do, and gitbasher will do it for you. All commands have a short alias, for example gitb c is equivalent to gitb commit.

Task	Plain `git`	With `gitb`
Start a feature off updated main	`git fetch && git checkout main && git pull --ff-only && git checkout -b feat/x`	`gitb branch newd`
Conventional commit + push	`git add -A && git commit -m "feat(x): …" && git push -u origin HEAD`	`gitb commit ai fast push`
Sync your branch with main	`git fetch && git rebase origin/main && git push --force-with-lease`	`gitb sync push`
Save WIP & clean tree across machines	`git stash -u && git push origin "HEAD:wip/$(git symbolic-ref --short HEAD)"`	`gitb wip up`
Undo last commit (keep changes staged)	`git reset --soft HEAD~1`	`gitb undo`
Tidy a messy branch into clean commits	(interactive rebase, fold by hand)	`gitb squash`

Install in 10 seconds

One-liner

curl -fsSL https://raw.githubusercontent.com/maxbolgarin/gitbasher/main/install.sh | bash

The installer drops gitb into ~/.local/bin by default — no sudo, no password prompt. It downloads the latest release, verifies its SHA-256, and prints a PATH hint if needed.

npm (easy to remember)

npm install -g gitbasher

60-second quick start

cd your-project
gitb              # see all commands
gitb cfg user     # set your name/email once
gitb cfg ai       # (optional) plug in an AI key for smart commits

gitb status       # what's changed?
gitb commit       # interactive conventional commit
gitb push         # safe push with conflict handling
gitb pull         # smart pull (rebase / merge / ff)
gitb branch new   # create a new conventionally-named branch

Every command has a short alias (gitb c, gitb p, gitb pu, gitb b, gitb s, …) and inline help (gitb commit help).

Why gitbasher

Zero memorization — no flags to remember, no man pages to grep. Interactive menus where it matters, short aliases where it doesn't.
Conventional commits, free — type/scope/summary picker built-in, with optional ticket prefixes and a multiline editor mode.
AI commit messages — gitb c ai writes the message from your diff. OpenRouter (Gemini/Claude/GPT/…), OpenAI direct, or fully local via Ollama — no key, no network, no data leaves your machine.
Safer git — push/pull detect conflicts up front, undo rolls back commit/amend/merge/rebase/stash, reset is interactive with a preview.
Whole workflows, not just commands — sync, wip, branch newd, merge to-main, squash chain the steps you'd otherwise do by hand.
One file, no deps — pure bash. Drop the binary anywhere on PATH and go. 115+ BATS tests cover sanitization, git ops, and branch logic.

All features at a glance

Group	Commands	What you get
Commit	`commit` (`c`), `edit` (`ed`)	Interactive conventional commits, fast-mode, AI messages, atomic split, fixup, amend, revert; `gitb edit` reworks the last commit message, picks any commit to reword, or renames the current branch
Sync remote	`push` (`p`), `pull` (`pu`), `fetch` (`fe`), `sync` (`sy`)	Safe push (with force/list), smart pull (rebase / merge / ff), fetch-only with prune, one-shot rebase-on-main with optional force-push
Branches	`branch` (`b`), `prev` (`-`)	List / switch / create-from-current / create-from-updated-main / delete (orphaned, merged, gone) / recent / previous / checkout-tag
Integration	`merge` (`m`), `rebase` (`r`), `squash` (`sq`), `cherry` (`ch`)	Merge into current / into main / from remote · rebase onto main / interactive / autosquash / fastautosquash / pull-commits · AI-driven squash of branch commits into changelog-ready history · cherry-pick by hash, range, or interactive
Tags & releases	`tag` (`t`)	Lightweight, annotated, from-commit, push, push-all, delete, delete-all, list, fetch-remote
Save & rollback	`wip` (`up`/`down`), `undo` (`un`), `reset` (`res`), `stash` (`st`)	Save WIP via stash / branch / worktree (auto-detected on restore) · undo last commit/amend/merge/rebase/stash · interactive reset · full stash menu
Worktrees	`worktree` (`wt`)	Add / list / remove / move / lock / prune git worktrees, with new branch from current/main or from existing/remote branches
Inspect	`status` (`s`), `diff` (`d`), `log` (`l`), `reflog` (`rl`), `last-commit` (`lc`), `last-ref` (`lr`)	Pretty repo status, overview-first diffs with a file picker + AI summary, multi-mode log + search, reflog viewer, quick last-commit / last-ref summary
Hooks	`hook` (`ho`)	List / create from templates / edit / toggle / remove / test / show — for every git hook
Repo setup	`init` (`i`), `origin` (`or`, `o`, `remote`)	`git init` from gitbasher · add/change/rename/remove the remote origin
Config	`config` (`cfg`)	User, default branch, separator, editor, ticket prefix, scopes, AI provider/key/model, proxy, completion
Lifecycle	`update` (`up`), `uninstall` (`uns`)	Self-update from latest GitHub release · one-shot uninstall (config + binary)

Total: 26 top-level commands, 60+ aliases, 100+ modes.

Common workflows

Daily development

gitb status            
gitb pull              
gitb branch new        
# ... code ...
gitb commit ai fast push

Code-review cycle

gitb commit fix          
gitb rebase autosquash           
gitb push force

Sync with main mid-feature

gitb sync            # fetch main + rebase your branch
gitb sync push       # …and force-push
gitb sync merge      # use merge instead of rebase

Save WIP across machines / branches

gitb wip up          # stash changes + push backup to origin/wip/<branch>
# … on another machine …
gitb pull            # fetch the wip/<branch>
gitb wip down        # pop the wip stash and remove the remote backup

Hotfix

gitb b m             # switch to main
gitb pu              # latest changes
gitb b n             # hotfix branch
gitb c aifp          # fast AI commit + push
gitb m tm            # merge to main

Release

gitb b m
gitb pu
gitb l               # review log
gitb t a             # annotated tag
gitb t p             # push tag

Roll back a mistake

gitb undo            # undo last commit (keeps changes staged)
gitb undo amend      # restore pre-amend state via reflog
gitb undo merge      # abort or undo last merge
gitb undo rebase     # abort or undo last rebase
gitb undo stash      # re-stash a popped stash

Branch hygiene

gitb b rc            # pick from recently used branches
gitb b g             # delete local branches whose remote is gone
gitb b del           # interactive delete (orphaned / merged / pick)
gitb b -             # back to previous branch (like cd -)

AI-powered commits

Drop in an API key once (or run a local model with no key at all), then let an LLM write conventional commit messages from your diff.

Providers

gitbasher supports three providers behind the same OpenAI-style chat-completions API. Default is openrouter — existing setups keep working unchanged.

Provider	Best for	Needs key?
`openrouter` (default)	Trying many models behind one key (Gemini, Claude, GPT, DeepSeek…)	Yes — openrouter.ai/keys
`openai`	Direct access to GPT-5.4 family at OpenAI's own pricing	Yes — platform.openai.com/api-keys
`ollama`	Fully local, fully private — no key, no network, runs on your machine	No

Setup

# 1. Pick a provider (skip to use the OpenRouter default)
gitb cfg provider     # interactive — choose openrouter, openai, or ollama

# 2. For openrouter / openai: paste your key (local repo or global)
gitb cfg ai

#    For ollama: just make sure the daemon is running and the default model is pulled
ollama serve &
ollama pull qwen3:8b

# 3. Optional: HTTP proxy (for restricted regions, openrouter/openai only)
gitb cfg proxy

For the security-conscious, prefer the env var to avoid the key landing in ~/.gitconfig:

export GITB_AI_API_KEY='sk-...'

Default models per provider (click to expand)

Each task uses a model tuned for speed/cost/quality, picked per provider. Defaults (May 2026):

OpenRouter (default provider)

Task	Default model	Why
`simple` (one-line message)	`google/gemini-3.1-flash-lite-preview`	Cheapest fast tier
`subject` (after manual type/scope)	`google/gemini-3.1-flash-lite-preview`	Short structured output
`full` (header + body)	`google/gemini-3-flash-preview`	Better prose
`grouping` (atomic-split mapping)	`anthropic/claude-haiku-4.5`	Strict instruction following

OpenAI — GPT-5.4 family (released March 2026)

Task	Default model	Why
`simple` / `subject`	`gpt-5.4-nano`	Built for classification/short well-defined output, ~$0.20 / $1.25 per M tokens
`full`	`gpt-5.4-mini`	Stronger multi-condition instruction following for header + body, ~$0.75 / $4.50 per M
`grouping`	`gpt-5.4-mini`	Holds the strict TSV format under validation, far cheaper than the flagship

Ollama — fully local

Task	Default model	Why
All tasks	`qwen3:8b`	Best small instruction-follower among 7/8B models; most stable structured output (rarely drops fields in TSV); ~5 GB on disk, ~25 tok/s on a consumer laptop with GPU

Other strong local picks: llama3.3:8b (general-purpose), qwen2.5-coder:7b (code-heavy diffs).

Override per task or globally:

gitb cfg model                                          # interactive
git config gitbasher.ai-model            <model_id>     # global
git config gitbasher.ai-model-simple     <model_id>     # per-task
git config gitbasher.ai-model-subject    <model_id>
git config gitbasher.ai-model-full       <model_id>
git config gitbasher.ai-model-grouping   <model_id>

Custom OpenAI-compatible endpoints (LiteLLM, vLLM, remote Ollama)

Self-hosted gateways and remote Ollama hosts work via a base-URL override:

gitb cfg provider                                                  # pick openai or ollama as the closest match
git config gitbasher.ai-base-url http://my-gateway:4000/v1/chat/completions

Command reference

Tip: every command accepts help (h) for inline help: gitb commit help, gitb sync h.

Command	Aliases	Description
`commit`	`c` `co` `com`	Create commits (interactive, fast, AI, split, fixup, amend, revert, …)
`edit`	`ed` `ee`	Rewrite the last commit message, reword an older commit, or rename the current branch
`push`	`p` `ps` `pus`	Push with conflict handling, force, or list-only
`pull`	`pu` `pl` `pul`	Smart pull: rebase / merge / ff / fetch-only / interactive / dry-run
`fetch`	`fe`	Fetch without merging: current branch, all remotes, or prune
`branch`	`b` `br` `bran`	Switch / list / create / delete / recent / gone / checkout-tag
`tag`	`t` `tg`	Create, push, list, delete tags (lightweight & annotated)
`merge`	`m` `me`	Merge into current, into main, or from remote
`rebase`	`r` `re` `base`	Rebase onto main / interactive / autosquash / pull-commits
`squash`	`sq` `tidy`	AI groups branch commits into clean, changelog-ready history
`cherry`	`ch` `cp`	Cherry-pick by hash, range, or interactive picker
`sync`	`sy`	Fetch main + rebase (or merge) current branch, optional push
`wip`	`w`	Stash all + backup to remote (`up`) / restore (`down`)
`undo`	`un`	Undo last commit / amend / merge / rebase / stash
`reset`	`res`	Friendly `git reset` with preview, approval, and undo support
`stash`	`st` `sta`	Full stash menu: select, all, list, pop, apply, show, drop
`worktree`	`wt` `tree`	Manage git worktrees: add, list, remove, move, lock, prune
`hook`	`ho` `hk`	Manage git hooks: list, create, edit, toggle, remove, test, show
`origin`	`or` `o` `remote`	Add, change, rename, or remove the remote origin
`init`	`i`	`git init` + optional origin setup prompt
`config`	`cf` `cfg` `conf`	Configure user, branch, AI, scopes, ticket prefix, etc.
`log`	`l` `lg`	Pretty log: current, branch, compare, search
`status`	`s`	Repo status and changed files
`diff`	`d` `di`	Overview-first diffs: staged, all, branch, commit, AI summary
`reflog`	`rl` `rlg`	Pretty reflog
`last-commit`	`lc` `lastc`	Show the last commit
`last-ref`	`lr` `lastr`	Show the last reference
`prev`	`-`	Switch to previous branch (`cd -`)

`gitb commit`

A commit invocation is one action plus zero or more modifiers. Words can be combined freely (ai fast push) or written as a single compact token (aifp). Aliases are interchangeable.

gitb commit [<flag> ...]     # space-separated, any order
gitb commit <combined>       # compact form: ff, aifp, fastsp, ...

Actions — pick one; default is a regular commit.

Action	Aliases	Description
`<empty>`		Interactive commit: choose files, type, scope, and summary
`split`	`sp` `sl`	Split staged changes into one commit per detected scope
`fixup`	`x` `fix`	Create a `--fixup` commit against an older commit
`amend`	`a` `am`	Add changes into the last commit (no message edit)
`revert`	`rev`	Revert a commit (`git revert --no-edit`)
`ff`		Ultrafast: `ai + split + fast` with no prompts (use `ffp` to also push)
`sff`	`ffst`	Like `ff` but on already-staged files (no `git add .`); use `sffp` to also push
`help`	`h` `--help` `-h`	Show inline help

Modifiers — stack with an action, any order.

Flag	Aliases	Description
`fast`	`f`	Stage all changes (`git add .`) before committing
`staged`	`st`	Use already-staged files (skip the add step)
`push`	`p` `pu`	Push after the commit succeeds
`scope`	`s`	Force a scope: `type(scope): message` (useful with fast mode)
`no-split`	`nsp` `nsl`	Disable automatic split detection for this commit
`ai`	`i` `llm`	Generate the commit message with AI
`msg`	`m`	Open `$EDITOR` for a multiline message body
`ticket`	`t` `j` `jira`	Append ticket info to the header

Examples

Command	What it does
`gitb commit`	Interactive commit
`gitb commit fast`	`git add .` then enter a message
`gitb commit ai fast push`	AI message + add all + commit + push
`gitb commit aifp`	Same as above (compact form)
`gitb commit ai split push`	AI groups staged files into commits by feature, then push
`gitb commit fixup push`	Pick an older commit, fixup it, then push
`gitb commit amend fast`	Add all current changes into the last commit
`gitb commit ff`	Full auto: AI splits and writes everything
`gitb commit sffp`	Full auto on already-staged files: AI splits, writes, pushes

How modes combine

Word order doesn't matter: ai fast push == push fast ai == aifp.
Modifiers stack on actions: ai+fixup, fast+amend, split+push, ai+staged, …
fast and staged are mutually exclusive (one stages all, the other uses what's staged).
revert and ff only accept push (as revp / ffp); to rewrite the last commit message use gitb edit.

`gitb edit`

Rewrites a commit message or the current branch name without touching the tree.

gitb edit                       # reword the LAST commit (git commit --amend)
gitb edit pick                  # choose any recent commit and reword it via rebase
gitb edit branch                # rename the current branch (interactive)
gitb edit branch feat/new-name  # rename the current branch to feat/new-name
gitb edit help                  # show inline help

Modes:

Mode	Aliases	Description
`<empty>`		Reword the last commit (`git commit --amend`)
`pick`	`p` `c` `choose`	Pick any recent commit, reword via non-interactive rebase
`branch`	`b` `br` `rename` `ren`	Rename the current branch (`git branch -m`); optional remote sync
`help`	`h` `--help` `-h`	Show inline help

Notes:

pick requires a clean working tree (the rebase replays subsequent commits).
Merge commits and the root commit cannot be reworded this way.
If the commit was already pushed, run gitb push force afterwards.
branch offers to push the new name and delete the old one on the remote when an upstream exists.
To add staged changes into the last commit, use gitb commit amend instead.
To undo the change, use gitb undo amend (for plain edit) or gitb undo rebase (for pick).

`gitb push`

All push modes

Mode	Aliases	Description
`<empty>`		Show commits, push with conflict handling
`yes`	`y`	Push without confirmation
`force`	`f`	Force push (use after rebase/amend)
`list`	`log` `l`	List unpushed commits + estimated push size and large-file warnings

Large pushes stream git's live progress bar (like clone/fetch), and gitbasher estimates the transfer size first — warning you before you push a stray non-code object (e.g. a build artifact or dataset). Tune the threshold with gitb cfg push-size (default 50 MB, 0 disables).

`gitb pull`

All pull modes

Mode	Aliases	Description
`<empty>`		Smart pull (strategy picker)
`fetch`	`fe`	Fetch only
`all`	`fa`	Fetch all branches
`upd`	`u`	Update remote refs / prune
`ffonly`	`ff`	Fast-forward only
`merge`	`m`	Always create merge commit
`rebase`	`r`	Rebase current onto remote
`interactive`	`ri` `rs`	Interactive rebase + autosquash
`dry`	`d` `dr`	Preview incoming commits without modifying local refs

`gitb fetch`

All fetch modes

Mode	Aliases	Description
`<empty>`		Fetch the current branch without merging
`all`	`a` `fa`	Fetch every remote branch without merging
`prune`	`p` `pr`	Fetch and drop branches deleted on the remote

`gitb branch`

All branch modes

Mode	Aliases	Description
`<empty>`		Pick a local branch to switch
`list`	`l`	List local branches
`remote`	`re` `r`	Fetch and switch to a remote branch
`main`	`def` `m`	Quick-switch to default branch
`tag`	`t`	Checkout to a specific tag
`new`	`n` `c`	Create branch from current (offers to push it to the remote)
`newd`	`nd` `cd`	Switch to main, pull, branch off (offers to push it to the remote)
`delete`	`del` `d`	Delete branches (orphaned, merged, or selected)
`prev`	`p` `-`	Switch to previous branch (`cd -`)
`recent`	`rc`	Pick from recently checked-out branches
`gone`	`g`	Delete locals whose remote tracking branch is gone

`gitb tag`

All tag modes

Mode	Aliases	Description
`<empty>`		Lightweight tag from `HEAD`
`annotated`	`a` `an`	Annotated tag with message
`commit`	`c` `co` `cm`	Tag from a selected commit
`all`	`al`	Annotated tag from selected commit
`push`	`p` `ps` `ph`	Push a tag
`push-all`	`pa`	Push all tags
`delete`	`del` `d`	Delete a local tag
`delete-all`	`da`	Delete all local tags
`list`	`log` `l`	List local tags
`remote`	`fetch` `r`	Fetch and list remote tags

`gitb merge`

All merge modes

Mode	Aliases	Description
`<empty>`		Pick a branch to merge into current
`main`	`master` `m`	Merge default branch into current
`to-main`	`to-master` `tm`	Switch to main, merge current branch in
`remote`	`r`	Fetch + select a remote branch to merge
`push`	`p`	Push the branch after a successful merge (combine with any mode)

`gitb rebase`

All rebase modes

Mode	Aliases	Description
`<empty>`		Pick a base branch
`main`	`master` `m`	Rebase current onto default
`interactive`	`i`	Interactive rebase from picked commit
`autosquash`	`a` `s` `ia`	Interactive rebase with `--autosquash`
`fastautosquash`	`fast` `sf` `f`	Autosquash without interaction
`pull`	`p`	Take commits from selected branch into current
`push`		Force-push the branch after a successful rebase (combine with any mode)

`gitb squash`

Ask the AI to read commits in the current branch's range and propose a clean, changelog-ready history (e.g. fold five fix typo/wip commits into the one feature commit they belong to). Range is auto-detected:

On the default branch — commits since the last tag.
On any other branch — commits since the merge-base with the default branch.

The plan is shown for confirmation before any history is rewritten. If you don't like the result, recover with gitb undo rebase.

All squash modes

Mode	Aliases	Description
`<empty>`		Generate plan, confirm, then interactive rebase
`preview`	`p` `dry` `show`	Show the AI plan only — don't touch history
`yes`	`y` `fast`	Apply without the confirmation prompt
`push`	`ps`	After rebase, force-push with `--force-with-lease`
`help`	`h`	Show usage

Requires AI to be configured (gitb cfg ai).

`gitb cherry`

All cherry modes

Mode	Aliases	Description
`<empty>`		Pick commits from a branch interactively
`<commit-hash>`		Shorthand for cherry-pick by hash
`hash`	`hs`	Cherry-pick a specific hash
`range`	`r`	Cherry-pick a range (`A..B`)
`abort`	`a`	Abort current cherry-pick
`continue`	`cont` `c`	Continue after resolving conflicts

`gitb sync`

Fetch the default branch and update your current branch. Useful mid-feature.

All sync modes

Mode	Aliases	Description
`<empty>`		Fetch main + rebase current onto it
`push`	`p`	…then force-push
`merge`	`m`	Use merge instead of rebase
`mergep`	`mp` `pm`	Merge + push
`dry`	`d` `dr`	Preview commits sync would bring in from main without modifying local refs

`gitb wip`

Save work-in-progress through one of three backends and restore it later. Pick the one that fits the situation — wip up prompts when the backend isn't specified, and wip down auto-detects which backend was used.

Backend	What it does	When to use
`stash`	`git stash --include-untracked` + force-push `wip/<branch>` to remote as backup	Quick context switch, default
`branch`	Commits all changes onto a `wip/<branch>` branch, leaves current branch clean, optionally pushes	Want history / share work / open a draft PR
`worktree`	Same as branch, but the WIP lives in a sibling worktree so you can keep working on it side-by-side	Long-running parallel work

All wip up / down modes

Command	Aliases	Description
`gitb wip up`	`u`	Save WIP — prompts which backend to use
`gitb wip up stash`	`u s`	Stash + push backup branch
`gitb wip up branch`	`u b`	Commit onto `wip/<branch>` + push
`gitb wip up worktree`	`u w` `u wt`	Move WIP into a sibling worktree
`gitb wip up <mode> nopush`	`np` `n`	Skip the push step (works with any backend)
`gitb wip up nopush`	`u np` `u n`	Legacy: stash + no push (same as `up stash nopush`)
`gitb wip down`	`d`	Restore — auto-detects backend, prompts if ambiguous
`gitb wip down stash`	`d s`	Restore from the stash
`gitb wip down branch`	`d b`	Restore from `wip/<branch>` (squash-merge into working tree)
`gitb wip down worktree`	`d w` `d wt`	Restore from the wip worktree, then remove it

For branch and worktree, wip down brings everything (committed + uncommitted) back as plain modifications and deletes the wip branch / worktree (and remote wip/<branch> if present).

`gitb undo`

All undo modes

Mode	Aliases	Description
`<empty>` / `commit`	`c`	Undo last commit (`reset --soft HEAD~1`) — keeps changes staged
`amend`	`a`	Restore pre-amend state via reflog
`merge`	`m`	Abort or undo last merge
`rebase`	`r`	Abort or undo last rebase (`ORIG_HEAD`)
`stash`	`s`	Re-stash a popped/applied stash

`gitb reset`

All reset modes

Mode	Aliases	Description
`<empty>`		Preview and reset last commit (mixed)
`soft`	`s`	Preview and soft reset last commit
`undo`	`u`	Preview and undo last reset
`interactive`	`i`	Pick commit to reset to, then approve
`ref`	`r`	Reset to a `HEAD` reference with approval (reflog recovery)

`gitb stash`

All stash modes

Mode	Aliases	Description
`<empty>`		Interactive stash menu
`select`	`sel`	Stash specific files
`all`		Stash everything including untracked
`list`	`l`	List all stashes
`pop`	`p`	Apply and remove
`show`	`s`	Preview stash
`apply`	`a`	Apply without removing
`drop`	`d`	Delete stash

`gitb worktree`

Run multiple branches in parallel without stashing or switching: each worktree is a real working directory linked to the same .git. Great for hotfixes, long-running reviews, or comparing branches side-by-side.

All worktree modes

Mode	Aliases	Description
`<empty>`		Show existing worktrees + interactive menu
`list`	`l` `ls`	List all worktrees with branch and lock state
`add`	`a` `new` `n` `c`	Create worktree with a new branch from current `HEAD`
`addd`	`ad` `nd` `cd`	Fetch, then create worktree with new branch from default branch
`addb`	`ab` `from` `b`	Create worktree from an existing local branch
`addr`	`ar` `remote` `r`	Fetch + create worktree tracking a remote branch
`remove`	`rm` `del` `d`	Pick a worktree to remove (force-prompt on dirty trees)
`move`	`mv`	Move a worktree to a new path
`lock`		Lock a worktree (with optional reason)
`unlock`	`ul`	Unlock a worktree
`prune`	`pr` `p`	Clean up stale worktree records (dry-run preview first)
`path`	`cd` `switch` `sw`	Print the path to a chosen worktree (use with `cd $(...)`)

gitb wt add                # new branch + new worktree from current HEAD
gitb wt addd               # new branch + new worktree from updated main
gitb wt addr               # check out a remote branch into a fresh worktree
gitb wt remove             # interactive removal (with force prompt if dirty)
cd "$(gitb wt path)"       # cd into a chosen worktree

By default new worktrees are created at ../<repo>-<branch>. Override the parent directory globally or per-repo:

git config --global gitbasher.worktreebase ~/code/worktrees

`gitb hook`

All hook modes

Mode	Aliases	Description
`<empty>`		Interactive action menu
`list`	`l`	All hooks with status
`create`	`new` `c`	New hook from templates
`edit`	`e`	Edit existing hook
`toggle`	`t`	Enable/disable hook
`remove`	`rm` `r`	Delete hook(s)
`test`	`run` `check`	Test hook execution
`show`	`cat` `view` `s`	Display hook contents

`gitb init`

Initialize a new git repository and (optionally) add a remote origin.

gitb init             # git init + interactive remote prompt
gitb origin set <url> # add origin without prompts

gitb init runs git init in the current directory. If the repo has no configured remote, gitbasher offers to add one interactively. Use gitb origin for non-interactive remote management.

`gitb origin`

Add, change, rename, or remove the remote origin. Useful when you create a repo without a remote, rename the repo on GitHub/GitLab, or move it to a new host.

All origin modes

Mode	Aliases	Description
`<empty>`	`show` `info`	List configured remotes and their URLs
`set`	`add` `new` `a`	Add a new origin (errors if origin already set)
`change`	`update` `c` `u` `set-url`	Change the existing origin URL (after rename/move)
`rename`	`mv` `ren`	Rename a remote (e.g. `origin` → `upstream`)
`remove`	`rm` `del` `d`	Remove the remote
`help`	`h`	Show help

Each mutating mode accepts an optional URL/name as a second argument to skip the interactive prompt:

gitb origin                                      # show remotes
gitb origin set git@github.com:me/proj.git       # add origin
gitb origin change https://github.com/me/new.git # update URL after rename
gitb origin rename upstream                      # origin → upstream
gitb origin remove                               # delete the remote

`gitb config`

All config modes

Mode	Aliases	Description
`<empty>`		Show current configuration
`user`	`u` `name` `email`	Set name and email
`default`	`def` `d` `b` `main`	Set default branch
`separator`	`sep` `s`	Branch-name separator
`editor`	`ed` `e`	Commit-message editor
`ticket`	`ti` `t` `jira`	Ticket prefix for commits/branches
`scopes`	`sc` `s`	Common scopes
`ai`	`llm` `key`	AI API key
`provider`	`prov`	AI provider (openrouter, openai, ollama)
`model`	`m`	Default AI model
`proxy`	`prx` `p`	HTTP proxy for AI calls
`push-size`	`ps` `pushsize`	Warn before pushing more than N MB (0 disables)
`completion`	`comp`	Install / uninstall bash & zsh tab completion
`delete`	`unset` `del`	Remove global config

`gitb log`

An interactive commit browser instead of a wall of text. Bare gitb log shows a paginated, numbered commit list (with branch/tag decorations and ↑ on unpushed commits) — pick a number to open the commit and act on it: view the diff or stat, copy the hash, revert, cherry-pick, fix up staged changes into it, or restore a single file from it.

Mode	Aliases	Description
(none)		Interactive commit browser for the current branch
`all`	`dump`	Classic full log dump through the pager
`branch`	`b`	Pick a branch to log
`compare`	`comp` `c`	Compare two branches
`search`	`s`	Search commits
`ai`		Summarize a commit range in plain English (needs `gitb cfg ai`)
`help`	`h`	Show inline help

Anything else after gitb log is resolved automatically:

gitb log 20                  # browse the last 20 commits
gitb log scripts/gitb.sh     # browse one file's history (follows renames)
gitb log main..feature       # browse a range (plain refs work too)
gitb log broken teapot       # search commit messages for the phrase

gitb log ai summarizes what happened since the last tag; gitb log ai 30, gitb log ai unpushed and gitb log ai main..feature narrow the range. Page size is configurable: git config gitbasher.log-count 30.

Search sub-modes

Search sub-modes: message/msg/m, author/a, file/f, content/pickaxe/p, date/d, hash/commit/h.

`gitb diff`

Overview-first diffs built for the gitbasher workflow — no flag memorization. Bare gitb diff shows a colorized stat of your uncommitted changes, then lets you pick a file to view its full patch.

Mode	Aliases	Description
(none)		Stat overview of uncommitted changes, then pick a file to view its full patch
`staged`	`s` `cached`	Show staged changes (`git diff --cached`)
`all`	`a`	Show all uncommitted changes — staged and unstaged (`git diff HEAD`)
`branch`	`b`	Compare the current branch against another, chosen interactively
`commit`	`c`	Show a chosen commit's diff, chosen interactively
`ai`		Summarize uncommitted changes in plain English (needs `gitb cfg ai`)
`help`	`h`	Show inline help

Info commands

Command	Aliases	Description
`status`	`s`	Repo info and changed files
`reflog`	`rl` `rlg`	Pretty reflog
`last-commit`	`lc` `lastc`	Show the last commit
`last-ref`	`lr` `lastr`	Show the last reference

Configuration

gitb cfg (no args) prints the active configuration. Settings live in standard git config, so they're per-repo by default — use --global for everywhere.

Key	Set via	Purpose
`user.name` / `user.email`	`gitb cfg user`	Your identity
`gitbasher.branch`	`gitb cfg default`	Default branch (`main`, `master`, …)
`gitbasher.sep`	`gitb cfg separator`	Branch-name separator (`/`, `-`, …)
`gitbasher.editor`	`gitb cfg editor`	Editor for messages
`gitbasher.ticket`	`gitb cfg ticket`	Ticket prefix (`PROJ-`)
`gitbasher.scopes`	`gitb cfg scopes`	Suggested commit scopes
`gitbasher.ai-api-key`	`gitb cfg ai`	AI provider API key (or `GITB_AI_API_KEY` env)
`gitbasher.ai-provider`	`gitb cfg provider`	`openrouter` (default), `openai`, or `ollama`
`gitbasher.ai-base-url`	`git config`	Custom OpenAI-compatible endpoint (LiteLLM, vLLM, remote Ollama)
`gitbasher.ai-model[-task]`	`gitb cfg model`	AI model overrides (per provider)
`gitbasher.proxy`	`gitb cfg proxy`	HTTP proxy for AI calls
`gitbasher.worktreebase`	`git config gitbasher.worktreebase <dir>`	Parent directory for new worktrees (defaults to `..`)
`gitbasher.commit-auto-split`	`git config gitbasher.commit-auto-split <ask\|always\|never>`	Offer to split a commit per scope (default `ask`)
`gitbasher.commit-max-split-groups`	`git config gitbasher.commit-max-split-groups <2..20>`	Cap on split commits per run (default `7`)
`gitbasher.commit-split-order`	`git config gitbasher.commit-split-order <auto\|alpha>`	Order split commits by dependency (`auto`, default) or alphabetically (`alpha`)
`gitbasher.log-count`	`git config gitbasher.log-count <n>`	Commits per page in the `gitb log` browser (default `20`)

Clear gitbasher config (per-repo settings live with the repo and disappear with it):

git config --global --remove-section gitbasher 2>/dev/null
git config --global --unset core.editor 2>/dev/null   # only if you set it via gitb cfg editor

Aliases for shell users:

echo 'alias gc="gitb c"'   >> ~/.bashrc
echo 'alias gp="gitb p"'   >> ~/.bashrc
echo 'alias gpu="gitb pu"' >> ~/.bashrc
echo 'alias gb="gitb b"'   >> ~/.bashrc

zsh tip: if zsh autocorrects gitb → git, add alias gitb='nocorrect gitb' to ~/.zshrc.

Other install paths

System-wide install

# system-wide install (sudo, /usr/local/bin)
curl -fsSL https://raw.githubusercontent.com/maxbolgarin/gitbasher/main/install.sh | bash -s -- --sudo

Custom location

GITB_DIR=/opt/bin curl -fsSL https://raw.githubusercontent.com/maxbolgarin/gitbasher/main/install.sh | bash

Pin a release

GITB_VERSION=v3.10.2 curl -fsSL https://raw.githubusercontent.com/maxbolgarin/gitbasher/main/install.sh | bash

Uninstall

One command (recommended)

gitb uninstall

Lists every gitbasher.* key it will remove from your local + global git config and the binary path it will delete, then asks for confirmation. Detects npm installs and prints the right npm uninstall -g gitbasher command instead of touching node_modules.

Manual

If gitb is already gone from PATH:

rm -f ~/.local/bin/gitb                # default install location
sudo rm -f /usr/local/bin/gitb         # if installed with --sudo
npm uninstall -g gitbasher             # if installed via npm

# Wipe leftover gitbasher.* keys from git config
git config --global --remove-section gitbasher 2>/dev/null
git config --local  --remove-section gitbasher 2>/dev/null   # per repo

Troubleshooting

Command not found: gitb

which gitb                    # check install location
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc   # if installed to ~/.local/bin

Reinstall via npm (npm install -g gitbasher) or curl (see install).

Permission denied during install

The default install goes to ~/.local/bin (no sudo). For a system-wide install pass --sudo:

curl -fsSL https://raw.githubusercontent.com/maxbolgarin/gitbasher/main/install.sh | bash -s -- --sudo

AI features not working

gitb cfg              # check config
gitb cfg ai           # set API key
gitb cfg proxy        # in restricted regions

If gitb commit ai hangs, returns connection refused, or times out:

Network reachability — test the provider directly: curl -fsSL https://api.openai.com/v1/models -H "Authorization: Bearer $OPENAI_API_KEY" (or the equivalent for OpenRouter/Ollama). If that fails, gitbasher will too.
Corporate proxy / restricted region — gitb cfg proxy accepts host:port or protocol://host:port. Verify with curl -x "$proxy" https://api.openai.com.
Local Ollama — confirm the daemon is running (curl http://localhost:11434/api/tags). The default model must be pulled first (ollama pull llama3).
Stale or rotated key — gitb cfg ai re-prompts; prefer the env-var path (export GITB_AI_API_KEY_OPENAI=...) over git config so a leaked repo doesn't carry the secret.

"could not lock config file" / git config permission

git config --global writes to ~/.gitconfig. If gitbasher reports could not lock config file:

ls -la ~/.gitconfig            # check ownership and permissions
sudo chown "$USER" ~/.gitconfig
chmod u+w ~/.gitconfig
rm -f ~/.gitconfig.lock        # stale lock from a crashed git process

Per-repo settings live in .git/config and need write access to that file (chmod u+w .git/config if mounted read-only).

"Bad substitution" or bash errors

bash --version must be 3.2+ — the version macOS ships as /bin/bash — so this is rare.

macOS: already ships bash 3.2; gitbasher runs on it natively (a newer bash via brew install bash only improves in-place line editing of prefilled prompts)
Ubuntu/Debian: sudo apt update && sudo apt install --only-upgrade bash

System requirements

OS	Bash	Git	Install
Linux	3.2+	2.23+	`apt install bash git`
macOS	3.2+ (system)	2.23+	`brew install git`
Windows	WSL	WSL	`wsl --install` then Linux steps

Common git errors and what to run instead

git complains	gitbasher path
`error: failed to push some refs ... non-fast-forward`	`gitb pull` (rebase or merge interactively), then `gitb push`
`Your branch and 'origin/<branch>' have diverged`	`gitb sync` — rebase onto the remote tip after picking strategy
`error: Your local changes ... would be overwritten`	`gitb wip up` (stash / branch / worktree backend), pull, then `gitb wip down`
`fatal: refusing to merge unrelated histories`	`gitb merge` and confirm the unrelated-history prompt, or pick a different base
`fatal: Not possible to fast-forward, aborting.`	`gitb sync` and pick rebase, or `gitb merge` to create a merge commit
`error: cannot rebase: You have unstaged changes`	`gitb wip up` first, rebase, then `gitb wip down`
`Another git process seems to be running ... index.lock`	gitbasher detects this at startup and prompts to remove the stale lock
`error: pathspec '<branch>' did not match any file(s) known to git`	`gitb pull` to fetch, or `gitb b new <branch>` to create a fresh branch with a conventional name
`fatal: detached HEAD` after checkout	gitbasher warns before destructive ops in detached HEAD; use `gitb b` to switch to a real branch first
`gpg: signing failed` on commit	export `GPG_TTY=$(tty)` or run `gitb config` to disable signing per-repo

If you hit a confusing git error not listed here, run the same flow with git directly first — gitbasher passes git's stderr through unchanged, so the underlying message is the source of truth.

Uninstall

npm uninstall -g gitbasher           # if installed via npm
sudo rm /usr/local/bin/gitb          # if installed system-wide
rm -f ~/.local/bin/gitb              # if installed per-user
rm -rf ~/.gitbasher                  # remove config (optional)

Still stuck? Open an issue or ping @maxbolgarin on Telegram.

Contributing

PRs welcome. See CONTRIBUTING.md for the dev setup, BATS test patterns, and commit-message conventions. Curious how the bundle is built or how scripts get sourced into one process? See ARCHITECTURE.md.

make build               # rebuild dist/gitb
make test                # run all 115+ tests
make test-file FILE=test_sanitization.bats

Workflow:

Fork and create a feature branch
Write tests first (BATS, see tests/README.md)
Implement
make test — all tests must pass
Open a PR

Maintainer: @maxbolgarin

License: MIT — see LICENSE.

Name		Name	Last commit message	Last commit date
Latest commit History 761 Commits
.github		.github
dist		dist
scripts		scripts
site		site
tests		tests
.gitignore		.gitignore
.releaserc.json		.releaserc.json
ARCHITECTURE.md		ARCHITECTURE.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
FAQ.md		FAQ.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
SECURITY.md		SECURITY.md
install.sh		install.sh
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

gitbasher

In 30 seconds

Before & after

Install in 10 seconds

One-liner

npm (easy to remember)

60-second quick start

Table of contents

Why gitbasher

All features at a glance

Common workflows

Daily development

Code-review cycle

Sync with main mid-feature

Save WIP across machines / branches

Hotfix

Release

Roll back a mistake

Branch hygiene

AI-powered commits

Providers

Setup

Command reference

gitb commit

gitb edit

gitb push

gitb pull

gitb fetch

gitb branch

gitb tag

gitb merge

gitb rebase

gitb squash

gitb cherry

gitb sync

gitb wip

gitb undo

gitb reset

gitb stash

gitb worktree

gitb hook

gitb init

gitb origin

gitb config

gitb log

gitb diff

Info commands

Configuration

Other install paths

System-wide install

Custom location

Pin a release

Uninstall

One command (recommended)

Manual

Troubleshooting

Contributing

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 23

Uh oh!

Contributors

Uh oh!

Languages

`gitb commit`

`gitb edit`

`gitb push`

`gitb pull`

`gitb fetch`

`gitb branch`

`gitb tag`

`gitb merge`

`gitb rebase`

`gitb squash`

`gitb cherry`

`gitb sync`

`gitb wip`

`gitb undo`

`gitb reset`

`gitb stash`

`gitb worktree`

`gitb hook`

`gitb init`

`gitb origin`

`gitb config`

`gitb log`

`gitb diff`