gitbasher 4.0.0 → 5.0.0

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 All notable changes to gitbasher are generated automatically by [semantic-release](https://github.com/semantic-release/semantic-release) from [Conventional Commits](https://www.conventionalcommits.org/) on `main`. The project follows [Semantic Versioning](https://semver.org/).
 
+## [5.0.0](https://github.com/maxbolgarin/gitbasher/compare/v4.1.0...v5.0.0) (2026-07-03)
+
+## [4.1.0](https://github.com/maxbolgarin/gitbasher/compare/v4.0.0...v4.1.0) (2026-05-29)
+
+### 🚀 Features
+
+* **edit:** add `branch` mode to rename the current branch ([30cfd07](https://github.com/maxbolgarin/gitbasher/commit/30cfd071d49e73761f7853b8ca9643d0db50d9b4))
+* **edit:** add `gitb edit` and retire the commit `last` action ([51d3ca2](https://github.com/maxbolgarin/gitbasher/commit/51d3ca2c6d1e41a7dac506d05723cb7469b7ce41))
+* **edit:** add `pick` mode to reword any recent commit ([175cbd7](https://github.com/maxbolgarin/gitbasher/commit/175cbd73d29cb14c3f436b543b150b4e7cd6fd2d))
+* **site:** add Astro marketing site for GitHub Pages ([df1c1eb](https://github.com/maxbolgarin/gitbasher/commit/df1c1eb3925bd73156abd87150638ac74d73f9df))
+* **clone:** add gitb clone command ([ac377b2](https://github.com/maxbolgarin/gitbasher/commit/ac377b2e76378742289b632e117eca07bb3b09da))
+* **commit:** allow push modifier on revert ([cdb86b4](https://github.com/maxbolgarin/gitbasher/commit/cdb86b4c643db3d4fc2c2a68f2e931670729d04c))
+* **gitb:** allow running outside a git repository for global commands ([8eeeefe](https://github.com/maxbolgarin/gitbasher/commit/8eeeefef3839a43fd009cfa3f57f8ed6628fb259))
+* **commit:** cap atomic split at a configurable number of scopes ([15103d8](https://github.com/maxbolgarin/gitbasher/commit/15103d8234a54d6b329b921b1d412cfa8b4598e3))
+* **push:** retry transient network failures with exponential backoff ([80f8d32](https://github.com/maxbolgarin/gitbasher/commit/80f8d32709aaf5759689f48be6f75979cdf40fe0))
+* **pull:** stream git fetch progress live during gitb pull ([92ed00d](https://github.com/maxbolgarin/gitbasher/commit/92ed00de9b8c4cc9ed954ad0d59a92c83361569c))
+
+### 🐛 Bug Fixes
+
+* **gitb:** escape command substitution in macOS upgrade instructions ([f61db10](https://github.com/maxbolgarin/gitbasher/commit/f61db101c97527d101d6787e4b0aca625c8f55e5))
+* **commit:** honor push modifier when amending ([f5d2664](https://github.com/maxbolgarin/gitbasher/commit/f5d26640ab4ded146fcf1231200e99a1ddb91e9a))
+* **commit:** strip leading/trailing separators from auto scopes ([3fee1c8](https://github.com/maxbolgarin/gitbasher/commit/3fee1c8456ae6a171618efbbba87d81dfc5a9c6a))
+
 ## [4.0.0](https://github.com/maxbolgarin/gitbasher/compare/v3.10.2...v4.0.0) (2026-05-04)
 
 ### ⚠ BREAKING CHANGES

package/README.md

@@ -10,6 +10,13 @@
   <a href="https://github.com/maxbolgarin/gitbasher/actions"><img src="https://github.com/maxbolgarin/gitbasher/actions/workflows/build.yml/badge.svg" alt="Build Status"></a>
 </p>
 
+<p align="center">
+  <a href="https://maxbolgarin.github.io/gitbasher/"><strong>Website</strong></a> ·
+  <a href="#install-in-10-seconds">Install</a> ·
+  <a href="#all-features-at-a-glance">Features</a> ·
+  <a href="./FAQ.md">FAQ</a>
+</p>
+
 <p align="center">
   <img src=".github/commit.gif" width="640" alt="gitb commit demo" />
 </p>
@@ -104,7 +111,7 @@ Every command has a short alias (`gitb c`, `gitb p`, `gitb pu`, `gitb b`, `gitb
 - **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.
+- **One file, no deps** — pure bash for every git operation; only the AI features need `jq` and `curl`. Drop the binary anywhere on `PATH` and go. **870+ BATS tests** cover sanitization, git ops, and branch logic.
 
 <p align="center">
   <img src=".github/push.gif" width="640" alt="gitb push demo" />
@@ -116,20 +123,20 @@ Every command has a short alias (`gitb c`, `gitb p`, `gitb pu`, `gitb b`, `gitb
 
 | Group | Commands | What you get |
 |-------|----------|--------------|
-| **Commit** | `commit` (`c`) | Interactive conventional commits, fast-mode, AI messages, atomic split, fixup, amend, last-message edit, revert |
-| **Sync remote** | `push` (`p`), `pull` (`pu`), `sync` (`sy`) | Safe push (with force/list), smart pull (rebase / merge / ff), one-shot rebase-on-main with optional force-push |
+| **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`), `log` (`l`), `reflog` (`rl`), `last-commit` (`lc`), `last-ref` (`lr`) | Pretty repo status, multi-mode log + search, reflog viewer, quick last-commit / last-ref summary |
+| **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: **24 top-level commands**, **60+ aliases**, **100+ modes**.
+Total: **31 top-level commands**, **60+ aliases**, **100+ modes**.
 
 ---
 
@@ -161,9 +168,9 @@ gitb sync merge      # use merge instead of rebase
 ### Save WIP across machines / branches
 ```bash
 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
+# … on another machine: fetch the backup branch and restore it manually …
+git fetch origin wip/<branch>
+git merge --squash --no-commit origin/wip/<branch>
 ```
 
 ### Hotfix
@@ -301,8 +308,10 @@ git config gitbasher.ai-base-url http://my-gateway:4000/v1/chat/completions
 | Command | Aliases | Description |
 |---------|---------|-------------|
 | [`commit`](#gitb-commit) | `c` `co` `com` | Create commits (interactive, fast, AI, split, fixup, amend, revert, …) |
+| [`edit`](#gitb-edit) | `ed` `ee` | Rewrite the last commit message, reword an older commit, or rename the current branch |
 | [`push`](#gitb-push) | `p` `ps` `pus` | Push with conflict handling, force, or list-only |
 | [`pull`](#gitb-pull) | `pu` `pl` `pul` | Smart pull: rebase / merge / ff / fetch-only / interactive / dry-run |
+| [`fetch`](#gitb-fetch) | `fe` | Fetch without merging: current branch, all remotes, or prune |
 | [`branch`](#gitb-branch) | `b` `br` `bran` | Switch / list / create / delete / recent / gone / checkout-tag |
 | [`tag`](#gitb-tag) | `t` `tg` | Create, push, list, delete tags (lightweight & annotated) |
 | [`merge`](#gitb-merge) | `m` `me` | Merge into current, into main, or from remote |
@@ -318,9 +327,13 @@ git config gitbasher.ai-base-url http://my-gateway:4000/v1/chat/completions
 | [`hook`](#gitb-hook) | `ho` `hk` | Manage git hooks: list, create, edit, toggle, remove, test, show |
 | [`origin`](#gitb-origin) | `or` `o` `remote` | Add, change, rename, or remove the remote origin |
 | [`init`](#gitb-init) | `i` | `git init` + optional origin setup prompt |
+| `clone` | `cl` `clo` | Clone a repository and set up gitbasher in it |
+| `update` | `up` `upd` | Self-update gitb to the latest release |
+| [`uninstall`](#uninstall) | `uns` `uni` | Remove the binary and `gitbasher.*` config keys |
 | [`config`](#gitb-config) | `cf` `cfg` `conf` | Configure user, branch, AI, scopes, ticket prefix, etc. |
-| [`log`](#gitb-log) | `l` `lg` | Pretty log: current, branch, compare, search |
+| [`log`](#gitb-log) | `l` `lg` | Interactive commit browser; also branch, compare, search, and full-dump modes |
 | [`status`](#info-commands) | `s` | Repo status and changed files |
+| [`diff`](#gitb-diff) | `d` `di` | Overview-first diffs: staged, all, branch, commit, AI summary |
 | [`reflog`](#info-commands) | `rl` `rlg` | Pretty reflog |
 | [`last-commit`](#info-commands) | `lc` `lastc` | Show the last commit |
 | [`last-ref`](#info-commands) | `lr` `lastr` | Show the last reference |
@@ -345,9 +358,9 @@ gitb commit <combined>       # compact form: ff, aifp, fastsp, ...
 | `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) |
-| `last` | `l` | Rewrite the last commit message |
 | `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.
@@ -371,16 +384,47 @@ gitb commit <combined>       # compact form: ff, aifp, fastsp, ...
 | `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, then push |
+| `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).
-- `last` and `revert` take no modifiers; `ff` only accepts `push` (as `ffp`).
+- `revert` and `ff` only accept `push` (as `revp` / `ffp`); to rewrite the last commit message use [`gitb edit`](#gitb-edit).
+
+### `gitb edit`
+
+Rewrites a **commit message** or the **current branch name** without touching the tree.
+
+```bash
+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`
 
@@ -392,10 +436,12 @@ gitb commit <combined>       # compact form: ff, aifp, fastsp, ...
 | `<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 only |
+| `list` | `log` `l` | List unpushed commits + estimated push size and large-file warnings |
 
 </details>
 
+Quick pushes stay clean — git's live progress bar appears only when a transfer runs long (same for `pull`/`fetch`). gitbasher also 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`
 
 <details>
@@ -406,7 +452,7 @@ gitb commit <combined>       # compact form: ff, aifp, fastsp, ...
 | `<empty>` | | Smart pull (strategy picker) |
 | `fetch` | `fe` | Fetch only |
 | `all` | `fa` | Fetch all branches |
-| `upd` | `u` | Update remote refs / prune |
+| `upd` | `u` | Update remote refs (`git remote update`) |
 | `ffonly` | `ff` | Fast-forward only |
 | `merge` | `m` | Always create merge commit |
 | `rebase` | `r` | Rebase current onto remote |
@@ -415,6 +461,19 @@ gitb commit <combined>       # compact form: ff, aifp, fastsp, ...
 
 </details>
 
+### `gitb fetch`
+
+<details>
+<summary>All fetch modes</summary>
+
+| 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 |
+
+</details>
+
 ### `gitb branch`
 
 <details>
@@ -427,8 +486,8 @@ gitb commit <combined>       # compact form: ff, aifp, fastsp, ...
 | `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 |
-| `newd` | `nd` `cd` | Switch to main, pull, branch off |
+| `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 |
@@ -467,6 +526,7 @@ gitb commit <combined>       # compact form: ff, aifp, fastsp, ...
 | `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) |
 
 </details>
 
@@ -483,6 +543,7 @@ gitb commit <combined>       # compact form: ff, aifp, fastsp, ...
 | `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) |
 
 </details>
 
@@ -640,7 +701,7 @@ long-running reviews, or comparing branches side-by-side.
 | `<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 |
+| `addd` | `ad` `nd` | 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) |
@@ -648,7 +709,9 @@ long-running reviews, or comparing branches side-by-side.
 | `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 $(...)`) |
+| `manage` | `m` | Pick a worktree, then move / lock / unlock / delete it |
+| `goto` | `go` `g` `cd` `switch` | Open a subshell inside a chosen worktree |
+| `path` | `sw` | Print the path to a chosen worktree (use with `cd $(...)`) |
 
 </details>
 
@@ -660,8 +723,8 @@ 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:
+By default new worktrees are created at `<repo_root>/.worktree/<branch>` (slashes
+in the branch name become dashes). Override the base directory globally or per-repo:
 
 ```bash
 git config --global gitbasher.worktreebase ~/code/worktrees
@@ -676,9 +739,11 @@ git config --global gitbasher.worktreebase ~/code/worktrees
 |------|---------|-------------|
 | `<empty>` | | Interactive action menu |
 | `list` | `l` | All hooks with status |
+| `select` | `sel` | Browse hook types with descriptions |
 | `create` | `new` `c` | New hook from templates |
 | `edit` | `e` | Edit existing hook |
-| `toggle` | `t` | Enable/disable hook |
+| `toggle` | `t` | Enable/disable hook (`enable` / `disable` force that state) |
+| `install` | `samples` | Install all available sample hooks |
 | `remove` | `rm` `r` | Delete hook(s) |
 | `test` | `run` `check` | Test hook execution |
 | `show` | `cat` `view` `s` | Display hook contents |
@@ -717,8 +782,8 @@ without a remote, rename the repo on GitHub/GitLab, or move it to a new host.
 
 </details>
 
-Each mutating mode accepts an optional URL/name as a second argument to skip
-the interactive prompt:
+The `set`, `change`, and `rename` modes accept an optional URL/name as a second
+argument to skip the interactive prompt:
 
 ```bash
 gitb origin                                      # show remotes
@@ -738,7 +803,7 @@ gitb origin remove                               # delete the remote
 | `<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 |
+| `separator` | `sep` | Branch-name separator |
 | `editor` | `ed` `e` | Commit-message editor |
 | `ticket` | `ti` `t` `jira` | Ticket prefix for commits/branches |
 | `scopes` | `sc` `s` | Common scopes |
@@ -746,6 +811,9 @@ gitb origin remove                               # delete the remote
 | `provider` | `prov` | AI provider (openrouter, openai, ollama) |
 | `model` | `m` | Default AI model |
 | `proxy` | `prx` `p` | HTTP proxy for AI calls |
+| `history` | `hist` | How many recent commits to include in AI prompts |
+| `diff` | `payload` | AI diff payload size (line and character caps) |
+| `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 |
 
@@ -753,20 +821,50 @@ gitb origin remove                               # delete the remote
 
 ### `gitb log`
 
-<details>
-<summary>All log modes</summary>
+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 |
 |------|---------|-------------|
-| `<empty>` | | Pretty log for current branch |
+| _(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:
+
+```bash
+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`.
+
+<details>
+<summary>Search sub-modes</summary>
 
 **Search sub-modes:** `message`/`msg`/`m`, `author`/`a`, `file`/`f`, `content`/`pickaxe`/`p`, `date`/`d`, `hash`/`commit`/`h`.
 
 </details>
 
+### `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 |
@@ -787,15 +885,26 @@ gitb origin remove                               # delete the remote
 | `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 |
+| `core.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-api-key-<provider>` | `gitb cfg ai` | Per-provider AI API key (or `GITB_AI_API_KEY_<PROVIDER>` env); legacy `gitbasher.ai-api-key` is read as a fallback |
 | `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.ai-proxy` | `gitb cfg proxy` | HTTP proxy for AI calls |
+| `gitbasher.ai-ollama-host` | `git config gitbasher.ai-ollama-host <url>` | Ollama server URL (default `http://localhost:11434`) |
+| `gitbasher.ai-timeout` | `git config gitbasher.ai-timeout <seconds>` | AI request timeout in seconds (default `60`, `300` for ollama) |
+| `gitbasher.ai-diff-limit` | `gitb cfg diff` | Diff lines sent to AI (default `300`) |
+| `gitbasher.ai-diff-max-chars` | `gitb cfg diff` | Character cap on the diff sent to AI (default `20000`) |
+| `gitbasher.ai-commit-history-limit` | `gitb cfg history` | Recent commits included in AI prompts (default `10`) |
+| `gitbasher.push-warn-size` | `gitb cfg push-size` | Warn before pushing more than N MB (default `50`, `0` disables) |
+| `gitbasher.worktreebase` | `git config gitbasher.worktreebase <dir>` | Base directory for new worktrees (default `.worktree` under the repo root) |
+| `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.commit-ai-grouping` | `git config gitbasher.commit-ai-grouping <never\|auto\|always>` | AI feature grouping for commit splits (default `auto`) |
+| `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):
 ```bash
@@ -831,7 +940,7 @@ GITB_DIR=/opt/bin curl -fsSL https://raw.githubusercontent.com/maxbolgarin/gitba
 
 ### Pin a release
 ```bash
-GITB_VERSION=v3.10.2 curl -fsSL https://raw.githubusercontent.com/maxbolgarin/gitbasher/main/install.sh | bash
+GITB_VERSION=v5.0.0 curl -fsSL https://raw.githubusercontent.com/maxbolgarin/gitbasher/main/install.sh | bash
 ```
 
 ## Uninstall
@@ -888,9 +997,10 @@ gitb cfg proxy        # in restricted regions
 
 If `gitb commit ai` hangs, returns `connection refused`, or times out:
 
+- **jq missing** — all AI features require `jq` (check with `command -v jq`; install via `brew install jq` / `apt install jq`). Without it every AI command aborts with an install hint.
 - **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`).
+- **Local Ollama** — confirm the daemon is running (`curl http://localhost:11434/api/tags`). The default model must be pulled first (`ollama pull qwen3:8b`).
 - **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.
 </details>
 
@@ -912,9 +1022,9 @@ Per-repo settings live in `.git/config` and need write access to that file (`chm
 <details>
 <summary><b>"Bad substitution" or bash errors</b></summary>
 
-`bash --version` must be 4.0+.
+`bash --version` must be 3.2+ — the version macOS ships as `/bin/bash` — so this is rare.
 
-- macOS: `brew install bash` (and optionally make it default: `sudo sh -c 'echo /opt/homebrew/bin/bash >> /etc/shells' && chsh -s /opt/homebrew/bin/bash`)
+- 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`
 </details>
 
@@ -923,9 +1033,11 @@ Per-repo settings live in `.git/config` and need write access to that file (`chm
 
 | OS | Bash | Git | Install |
 |----|------|-----|---------|
-| Linux | 4.0+ | 2.23+ | `apt install bash git` |
-| macOS | 4.0+ | 2.23+ | `brew install bash git` |
+| 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 |
+
+AI features additionally require `jq` (`brew install jq` / `apt install jq`); core git commands don't.
 </details>
 
 <details>
@@ -942,7 +1054,7 @@ Per-repo settings live in `.git/config` and need write access to that file (`chm
 | `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 |
+| `gpg: signing failed` on commit | export `GPG_TTY=$(tty)` or run `git config commit.gpgsign false` 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.
 </details>
@@ -954,7 +1066,6 @@ If you hit a confusing git error not listed here, run the same flow with `git` d
 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)
 ```
 </details>
 
@@ -968,7 +1079,7 @@ PRs welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) for the dev setup, BATS te
 
 ```bash
 make build               # rebuild dist/gitb
-make test                # run all 115+ tests
+make test                # run all 870+ tests
 make test-file FILE=test_sanitization.bats
 ```