gitbasher 3.10.1 → 4.0.0

package/README.md

@@ -1,663 +1,985 @@
-# gitbasher – simple **bash** utility that makes **git** easy to use
+<h1 align="center">gitbasher</h1>
 
+<p align="center">
+  <strong>The friendly <code>git</code> wrapper that types the boring parts for you.</strong>
+</p>
 
-[![Latest Release](https://img.shields.io/github/v/release/maxbolgarin/gitbasher.svg?style=flat-square)](https://github.com/maxbolgarin/gitbasher/releases/latest)
-[![GitHub license](https://img.shields.io/github/license/maxbolgarin/gitbasher.svg)](https://github.com/maxbolgarin/gitbasher/blob/master/LICENSE)
-[![Build Status](https://github.com/maxbolgarin/gitbasher/actions/workflows/build.yml/badge.svg)](https://github.com/maxbolgarin/gitbasher/actions)
+<p align="center">
+  <a href="https://github.com/maxbolgarin/gitbasher/releases/latest"><img src="https://img.shields.io/github/v/release/maxbolgarin/gitbasher.svg?style=flat-square" alt="Latest Release"></a>
+  <a href="https://github.com/maxbolgarin/gitbasher/blob/main/LICENSE"><img src="https://img.shields.io/github/license/maxbolgarin/gitbasher.svg" alt="License"></a>
+  <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>
 
-<picture>
-    <img src=".github/commit.gif" width="600" alt="commit example">
-</picture>
+<p align="center">
+  <img src=".github/commit.gif" width="640" alt="gitb commit demo" />
+</p>
 
 ---
 
-With **gitbasher** usage of `git` becomes more simple and intuitive. It helps speeding up the development process, making it more consistent reducing mistakes. This is a wrapper around the most used git commands with a cleaner interface. It uses `bash` `git` `sed` `grep`, `curl` and some built-in utilities.
+## In 30 seconds
 
-
-### Quick Installation (recommended)
+- **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.
 
 ```bash
-GITB_PATH=/usr/local/bin/gitb && \
-sudo mkdir -p $(dirname $GITB_PATH) && \
-curl -fSL https://github.com/maxbolgarin/gitbasher/releases/latest/download/gitb | sudo tee $GITB_PATH > /dev/null && \
-sudo chmod +x $GITB_PATH
+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
 ```
 
-Or using npm:
-
-```bash
-npm install -g gitbasher
-```
+---
 
-In Windows use `wsl` (enter `wsl` in terminal, [read more](https://learn.microsoft.com/en-us/windows/wsl/setup/environment)) to enable Linux environment. Directory `/usr/local/bin/` is not mandatory. If you get `Permission denied`, use `sudo` or put it to `~/.local/bin` with adding it to `PATH` ([how](https://discussions.apple.com/thread/254226896)).
+## 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`. 
 
-## Table of Contents
-- [Quick Start Guide](#quick-start-guide)
-- [Why You Should Try This](#why-you-should-try-this)
-- [Real-World Examples](#real-world-examples)
-- [AI-Powered Commits](#ai-powered-commits)
-- [Common Workflows](#common-workflows)
-- [Complete Documentation](#complete-documentation)
-- [Troubleshooting & FAQ](#troubleshooting--faq)
-- [Contributing](#contributing)
+| 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` |
 
+---
 
-## Quick Start Guide
+## Install in 10 seconds
 
-### 1. First Steps
+### One-liner
 ```bash
-# Navigate to any git repository
-cd your-project
-
-# See all available commands
-gitb
+curl -fsSL https://raw.githubusercontent.com/maxbolgarin/gitbasher/main/install.sh | bash
 ```
 
-### 2. Your First Commit
-```bash
-# Smart commit - select files and create conventional message
-gitb commit
+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.
 
-# Fast commit - add all files with quick message
-gitb commit fast
 
-# AI-powered commit (after setting up API key)
-gitb commit ai
+### npm (easy to remember)
+```bash
+npm install -g gitbasher
 ```
 
-### 3. Essential Daily Commands
+---
+
+## 60-second quick start
+
 ```bash
-gitb status        # Check status
-gitb commit        # Make a commit
-gitb push          # Push changes
-gitb pull          # Pull changes
-gitb branch        # Switch branches
+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
 ```
 
-### 4. Set Up Your Environment
-```bash
-# Configure your identity
-gitb cfg user
+Every command has a short alias (`gitb c`, `gitb p`, `gitb pu`, `gitb b`, `gitb s`, …) and inline help (`gitb commit help`).
 
-# Set default branch (usually 'main' or 'master')
-gitb cfg default
+---
 
-# Set up AI features (optional but recommended)
-gitb cfg ai
-```
+## Table of contents
+- [Why gitbasher](#why-gitbasher)
+- [All features at a glance](#all-features-at-a-glance)
+- [Common workflows](#common-workflows)
+- [AI-powered commits](#ai-powered-commits)
+- [Command reference](#command-reference)
+- [Configuration](#configuration)
+- [Other install paths](#other-install-paths)
+- [Uninstall](#uninstall)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
 
+---
 
-## Why You Should Try This
+## Why gitbasher
 
-**gitbasher** is essential if you use `git` on the daily basis. Benefits you will get:
+- **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.
 
-* **⚡ Faster Development**: Spend almost no time on git commands
-* **🧠 No More Memorizing**: No need to remember/google exact command names and parameters
-* **📝 Better Commit Messages**: Conventional commits with manual or **AI-generated** messages
-* **🔧 Advanced Commands Made Easy**: Use `git rebase`, `git stash`, and hooks without complexity
-* **🌊 GitHub Flow**: Simplified branch management following best practices
-* **🎯 Consistent Workflow**: Standardized processes across your team
+<p align="center">
+  <img src=".github/push.gif" width="640" alt="gitb push demo" />
+</p>
 
-<picture>
-    <img src=".github/push.gif" width="600" alt="push example">
-</picture>
+---
 
+## All features at a glance
+
+| 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 |
+| **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 |
+| **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**.
 
-## Real-World Examples
+---
 
-### 🚀 Scenario 1: Starting a New Feature
+## Common workflows
 
-**Traditional Git:**
+### Daily development
 ```bash
-git switch main                   # Switch to main
-git pull origin main                # Get latest changes
-git switch -c feature/user-auth   # Create new branch
-# ... make changes ...
-git add src/auth.js src/login.js    # Stage files
-git commit -m "feat(auth): add user authentication system"
-git push -u origin feature/user-auth
+gitb status            
+gitb pull              
+gitb branch new        
+# ... code ...
+gitb commit ai fast push                    
 ```
 
-**With gitbasher:**
+### Code-review cycle
 ```bash
-gitb branch newd                   # Create new branch from updated main
-# ... make changes ...
-gitb commit push                    # Smart commit + push
+gitb commit fix          
+gitb rebase autosquash           
+gitb push force           
 ```
 
-### 🐛 Scenario 2: Quick Bug Fix
+### Sync with main mid-feature
+```bash
+gitb sync            # fetch main + rebase your branch
+gitb sync push       # …and force-push
+gitb sync merge      # use merge instead of rebase
+```
 
-**Traditional Git:**
+### Save WIP across machines / branches
 ```bash
-git status                          # Check what's changed
-git add .                          # Add all files
-git commit -m "fix: resolve login issue"
-git push
+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
 ```
 
-**With gitbasher:**
+### Hotfix
 ```bash
-gitb commit push                   # Fast commit + push (one command!)
+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
 ```
 
-### 🔀 Scenario 3: Merging Feature Branch
+### Release
+```bash
+gitb b m
+gitb pu
+gitb l               # review log
+gitb t a             # annotated tag
+gitb t p             # push tag
+```
 
-**Traditional Git:**
+### Roll back a mistake
 ```bash
-git switch main
-git pull origin main
-git merge feature/user-auth
-git push origin main
-git branch -d feature/user-auth
+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
 ```
 
-**With gitbasher:**
+### Branch hygiene
 ```bash
-gitb merge to-main             # Switch to main and merge current branch
-gitb branch delete                 # Select and delete the merged branch
+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 -)
 ```
 
-### 🤖 Scenario 4: AI-Powered Development
+---
+
+## 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](https://openrouter.ai/keys) |
+| `openai` | Direct access to GPT-5.4 family at OpenAI's own pricing | Yes — [platform.openai.com/api-keys](https://platform.openai.com/api-keys) |
+| `ollama` | **Fully local, fully private** — no key, no network, runs on your machine | No |
+
+### Setup
 
-**After making changes to multiple files:**
 ```bash
-gitb commit ai                   # AI analyzes changes and generates:
-                           # "feat(auth): implement JWT authentication with refresh tokens"
+# 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 quick fixes:**
+For the security-conscious, prefer the env var to avoid the key landing in `~/.gitconfig`:
 ```bash
-gitb commit aif                  # AI commit all files with smart message
+export GITB_AI_API_KEY='sk-...'
 ```
 
-### 🎯 Scenario 5: Code Review Preparation
+<details>
+<summary><b>Default models per provider</b> (click to expand)</summary>
+
+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 |
 
-**Clean up commits before PR:**
+**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:
 ```bash
-gitb rebase i                    # Interactive rebase to squash/reorder commits
-gitb commit fix                  # Create fixup commits for review feedback
-gitb rebase s                    # Auto-squash fixup commits
+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>
 ```
 
-### 📦 Scenario 6: Release Management
+</details>
 
-**Creating and managing releases:**
+<details>
+<summary><b>Custom OpenAI-compatible endpoints</b> (LiteLLM, vLLM, remote Ollama)</summary>
+
+Self-hosted gateways and remote Ollama hosts work via a base-URL override:
 ```bash
-gitb tag                      # Create version tag
-gitb tag push                 # Push tag to remote
-gitb log                      # Review commit history
+gitb cfg provider                                                  # pick openai or ollama as the closest match
+git config gitbasher.ai-base-url http://my-gateway:4000/v1/chat/completions
 ```
 
+</details>
+
+---
+
+## Command reference
+
+> **Tip:** every command accepts `help` (`h`) for inline help: `gitb commit help`, `gitb sync h`.
+
+| Command | Aliases | Description |
+|---------|---------|-------------|
+| [`commit`](#gitb-commit) | `c` `co` `com` | Create commits (interactive, fast, AI, split, fixup, amend, revert, …) |
+| [`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 |
+| [`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 |
+| [`rebase`](#gitb-rebase) | `r` `re` `base` | Rebase onto main / interactive / autosquash / pull-commits |
+| [`squash`](#gitb-squash) | `sq` `tidy` | AI groups branch commits into clean, changelog-ready history |
+| [`cherry`](#gitb-cherry) | `ch` `cp` | Cherry-pick by hash, range, or interactive picker |
+| [`sync`](#gitb-sync) | `sy` | Fetch main + rebase (or merge) current branch, optional push |
+| [`wip`](#gitb-wip) | `w` | Stash all + backup to remote (`up`) / restore (`down`) |
+| [`undo`](#gitb-undo) | `un` | Undo last commit / amend / merge / rebase / stash |
+| [`reset`](#gitb-reset) | `res` | Friendly `git reset` with preview, approval, and undo support |
+| [`stash`](#gitb-stash) | `st` `sta` | Full stash menu: select, all, list, pop, apply, show, drop |
+| [`worktree`](#gitb-worktree) | `wt` `tree` | Manage git worktrees: add, list, remove, move, lock, prune |
+| [`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 |
+| [`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 |
+| [`status`](#info-commands) | `s` | Repo status and changed files |
+| [`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 |
+| [`prev`](#gitb-branch) | `-` | 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.
+
+```text
+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) |
+| `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) |
+| `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, 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 |
+
+**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`).
+
+### `gitb push`
+
+<details>
+<summary>All push modes</summary>
+
+| 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 only |
+
+</details>
+
+### `gitb pull`
+
+<details>
+<summary>All pull modes</summary>
+
+| 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 |
+
+</details>
+
+### `gitb branch`
+
+<details>
+<summary>All branch modes</summary>
+
+| 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 |
+| `newd` | `nd` `cd` | Switch to main, pull, branch off |
+| `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 |
+
+</details>
+
+### `gitb tag`
+
+<details>
+<summary>All tag modes</summary>
+
+| 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 |
+
+</details>
+
+### `gitb merge`
+
+<details>
+<summary>All merge modes</summary>
+
+| 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 |
+
+</details>
+
+### `gitb rebase`
+
+<details>
+<summary>All rebase modes</summary>
+
+| 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 |
+
+</details>
+
+### `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`.
+
+<details>
+<summary>All squash modes</summary>
+
+| 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 |
+
+</details>
+
+Requires AI to be configured (`gitb cfg ai`).
+
+### `gitb cherry`
+
+<details>
+<summary>All cherry modes</summary>
+
+| 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 |
+
+</details>
+
+### `gitb sync`
+
+Fetch the default branch and update your current branch. Useful mid-feature.
 
-## AI-Powered Commits
+<details>
+<summary>All sync modes</summary>
 
-Transform your commit workflow with AI-generated messages that follow conventional commit standards.
+| 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 |
+
+</details>
+
+### `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.
 
-### Setup (One-time)
+| 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 |
 
-#### 1. Get Your API Key
-- Visit [Google AI Studio](https://aistudio.google.com/app/apikey)
-- Create a new API key
-- Copy it for the next step
+<details>
+<summary>All wip up / down modes</summary>
+
+| 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 |
+
+</details>
+
+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`
+
+<details>
+<summary>All undo modes</summary>
+
+| 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 |
+
+</details>
+
+### `gitb reset`
+
+<details>
+<summary>All reset modes</summary>
+
+| 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) |
+
+</details>
+
+### `gitb stash`
+
+<details>
+<summary>All stash modes</summary>
+
+| 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 |
+
+</details>
+
+### `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.
+
+<details>
+<summary>All worktree modes</summary>
+
+| 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 $(...)`) |
+
+</details>
 
-#### 2. Configure gitbasher
 ```bash
-gitb cfg ai
-# Enter your API key when prompted
-# Choose local (current repo) or global (all repos)
+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
 ```
 
-#### 3. Optional: Proxy Setup
-For regions with API restrictions:
+By default new worktrees are created at `../<repo>-<branch>`. Override the
+parent directory globally or per-repo:
+
 ```bash
-gitb cfg proxy
-# Examples:
-# http://proxy.example.com:8080
-# http://username:password@proxy.example.com:8080
+git config --global gitbasher.worktreebase ~/code/worktrees
 ```
 
-### AI Command Examples
+### `gitb hook`
 
-| **Scenario** | **Command** | **What It Does** |
-|--------------|-------------|------------------|
-| **Staged files ready** | `gitb c ai` | Analyzes staged changes, generates message |
-| **Quick fix needed** | `gitb c aif` | Adds all files + AI message |
-| **Ready to ship** | `gitb c aip` | AI commit + automatic push |
-| **Full workflow** | `gitb c aifp` | Add all + AI commit + push |
-| **Need control** | `gitb c ais` | AI message + manual type/scope |
-| **Detailed commit** | `gitb c aim` | Generates multiline commit message |
+<details>
+<summary>All hook modes</summary>
 
-## Common Workflows
+| 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 |
 
-### 🔄 Daily Development Workflow
+</details>
 
-```bash
-# Start your day
-gitb st                     # Check repository status
-gitb pu                     # Pull latest changes
+### `gitb init`
 
-# Work on features
-gitb b n                    # Create new feature branch
-# ... code changes ...
-gitb c ai                   # AI-powered commit
-gitb p                      # Push changes
+Initialize a new git repository and (optionally) add a remote origin.
 
-# Code review cycle
-gitb c fix                  # Create fixup commits
-gitb r a                    # Clean up with autosquash
-gitb p f                    # Force push cleaned history
+```bash
+gitb init             # git init + interactive remote prompt
+gitb origin set <url> # add origin without prompts
 ```
 
-### 🚨 Hotfix Workflow
+`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`](#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.
+
+<details>
+<summary>All origin modes</summary>
+
+| 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 |
+
+</details>
+
+Each mutating mode accepts an optional URL/name as a second argument to skip
+the interactive prompt:
 
 ```bash
-gitb b main                 # Switch to main branch
-gitb pu                     # Get latest changes
-gitb b n                    # Create hotfix branch
-# ... fix the issue ...
-gitb c aif                  # Fast AI commit
-gitb p                      # Push hotfix
-gitb m to-main             # Merge to main
+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
 ```
 
-### 🔀 Feature Integration
+### `gitb config`
 
-```bash
-# Prepare feature for merge
-gitb pu                     # Update current branch
-gitb r main                 # Rebase on main
-gitb l                      # Review commit history
-gitb c fix                  # Address review feedback
-gitb r a                    # Squash fixups
+<details>
+<summary>All config modes</summary>
 
-# Integrate
-gitb m to-main             # Merge to main
-gitb b del                 # Clean up feature branch
-```
+| 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 |
+| `completion` | `comp` | Install / uninstall bash & zsh tab completion |
+| `delete` | `unset` `del` | Remove global config |
+
+</details>
+
+### `gitb log`
 
-### 🎯 Release Workflow
+<details>
+<summary>All log modes</summary>
 
+| Mode | Aliases | Description |
+|------|---------|-------------|
+| `<empty>` | | Pretty log for current branch |
+| `branch` | `b` | Pick a branch to log |
+| `compare` | `comp` `c` | Compare two branches |
+| `search` | `s` | Search commits |
+
+**Search sub-modes:** `message`/`msg`/`m`, `author`/`a`, `file`/`f`, `content`/`pickaxe`/`p`, `date`/`d`, `hash`/`commit`/`h`.
+
+</details>
+
+### 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 `..`) |
+
+**Clear gitbasher config** (per-repo settings live with the repo and disappear with it):
 ```bash
-gitb b main                 # Switch to main
-gitb pu                     # Get latest changes
-gitb l                      # Review changes since last release
-gitb t a                    # Create annotated release tag
-gitb t push                 # Push tag to trigger CI/CD
+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
 ```
 
-### 🛠️ Maintenance Workflow
-
+**Aliases for shell users:**
 ```bash
-# Clean up old branches
-gitb b del                  # Interactive branch deletion
-
-# Manage stashes
-gitb stash                  # Interactive stash management
-
-# Check hooks
-gitb hook list              # See all git hooks status
-gitb hook create            # Set up project hooks
-```
-
-
-## Complete Documentation
-
-### Available Commands
-
-| Command                         | Short aliases       | Description                              |
-|---------------------------------|---------------------|------------------------------------------|
-| [**commit**](#gitb-commit-mode) | `c` `co` `com`    | Everything about commit creation         |
-| [**push**](#gitb-push-mode)     | `p` `ps` `ph`     | Pushing changes to a remote repository   |
-| [**pull**](#gitb-pull-mode)     | `pu` `pl` `pul`   | Pulling changes from a remote repository |
-| [**branch**](#gitb-branch-mode) | `b` `br` `bran`   | Managing branches                        |
-| [**tag**](#gitb-tag-mode)       | `t` `tg`           | Managing tags                            |
-| [**merge**](#gitb-merge-mode)   | `m` `me`           | Merge changes to the current branch      |
-| [**rebase**](#gitb-rebase-mode) | `r` `re` `base`   | Rebase current branch                    |
-| [**reset**](#gitb-reset-mode)   | `res`               | Easy to use git reset                    |
-| [**stash**](#gitb-stash-mode)   | `s` `sta`          | Manage git stashes                       |
-| [**hook**](#gitb-hook-mode)     | `ho` `hk`          | Comprehensive git hooks management with interactive menus |
-| [**config**](#gitb-config-mode) | `cf` `cfg` `conf` | Configurate gitbasher                    |
-| **status**                      | `st`                | Info about repo and changed files        |
-| [**log**](#gitb-log-mode)       | `l` `lg`           | Git log utilities and search functions   |
-| **reflog**                      | `rl` `rlg`         | Open git reflog in a pretty format       |
-| **help**                        | `h` `man`          | Show help                                |
-
-
-### `gitb commit <mode>`
-
-| **Mode**   | **Short**    | **Description** | **Example Use Case** |
-|------------|--------------|-----------------|---------------------|
-| `<empty>`  |              | Select files to commit and create conventional message | Regular feature development |
-| `msg`      | `m`          | Create multiline commit message using text editor | Detailed commit descriptions |
-| `ticket`   | `t`          | Add tracker's ticket info to commit header | JIRA/GitHub issue integration |
-| `fast`     | `f`          | Add all files and create commit without scope | Quick bug fixes |
-| `fasts`    | `fs`         | Add all files and create commit with scope | Feature additions |
-| `push`     | `pu` `p`    | Create commit and push changes | Deploy-ready commits |
-| `fastp`    | `fp`         | Fast commit and push | One-command workflow |
-| `fastsp`   | `fsp` `fps` | Fast commit with scope and push | Complete feature deployment |
-| `ai`       | `llm` `i`   | AI-generated commit message | Smart commit automation |
-| `aif`      | `llmf` `if` | Fast AI commit without confirmation | Rapid development |
-| `aip`      | `llmp` `ip` | AI commit and push | AI-powered deployment |
-| `aifp`     | `llmfp` `ifp` | Fast AI commit with push | Complete AI workflow |
-| `ais`      | `llms` `is` | AI summary with manual type/scope | Controlled AI assistance |
-| `aim`      | `llmm` `im` | AI multiline commit message | Detailed AI documentation |
-| `fixup`    | `fix` `x`   | Create fixup commit for rebase | Code review fixes |
-| `fixupp`   | `fixp` `xp` | Fixup commit and push | Remote fixup commits |
-| `fastfix`  | `fx`         | Fast fixup all files | Quick fixup workflow |
-| `fastfixp` | `fxp`        | Fast fixup and push | Complete fixup deployment |
-| `amend`    | `am` `a`    | Add files to last commit | Forgot to include files |
-| `amendf`   | `amf` `af`  | Amend with all files | Complete last commit |
-| `last`     | `l`          | Change last commit message | Fix commit message typos |
-| `revert`   | `rev`        | Revert selected commit | Undo problematic changes |
-
-### `gitb push <mode>`
-
-| **Mode**  | **Short** | **Description** | **When to Use** |
-|-----------|-----------|-----------------|-----------------|
-| `<empty>` |           | Show commits and push with conflict handling | Regular push workflow |
-| `yes`     | `y`       | Push without confirmation | Automated scripts |
-| `force`   | `f`       | Force push (use with caution) | After rebase/amend |
-| `list`    | `log` `l` | Show unpushed commits only | Review before push |
-
-### `gitb pull <mode>`
-
-| **Mode**      | **Short**  | **Description** | **Best For** |
-|---------------|------------|-----------------|--------------|
-| `<empty>`     |            | Smart pull with strategy selection | Daily workflow |
-| `fetch`       | `fe`       | Fetch only, no merge | Review changes first |
-| `all`         | `fa`       | Fetch all branches | Sync repository |
-| `upd`         | `u`        | Update all remote references | Branch cleanup |
-| `ffonly`      | `ff`       | Fast-forward only merge | Linear history |
-| `merge`       | `m`        | Always create merge commit | Feature branches |
-| `rebase`      | `r`        | Rebase current branch | Clean history |
-| `interactive` | `ri` `rs` | Interactive rebase with autosquash | Commit cleanup |
-
-### `gitb branch <mode>`
-
-| **Mode**  | **Short**  | **Description** | **Use Case** |
-|-----------|------------|-----------------|--------------|
-| `<empty>` |            | Interactive branch selection | Switch branches |
-| `list`    | `l`        | Show local branches | Branch overview |
-| `remote`  | `re` `r`  | Switch to remote branch | Work on others' branches |
-| `main`    | `def` `m` | Quick switch to main | Back to main branch |
-| `new`     | `n` `c`   | Create branch from current | Feature from current state |
-| `newd`    | `nd`       | Create branch from updated main | New feature branch |
-| `delete`  | `del` `d` | Delete local branch | Cleanup merged branches |
-
-### `gitb tag <mode>`
-
-| **Mode**     | **Short**       | **Description** | **Perfect For** |
-|--------------|-----------------|---------------------------------------------------------|-----------------|
-| `<empty>`    |                 | Create new tag from last commit | Quick releases |
-| `annotated`  | `a` `an`       | Create annotated tag with message | Official releases |
-| `commit`     | `c` `co` `cm` | Create tag from selected commit | Retrospective tagging |
-| `all`        | `al`            | Create annotated tag from selected commit | Complex releases |
-| `push`       | `ps` `ph` `p` | Push local tag to remote | Deploy releases |
-| `push-all`   | `pa`            | Push all tags to remote | Sync all releases |
-| `delete`     | `del` `d`      | Delete local tag | Fix tag mistakes |
-| `delete-all` | `da`            | Delete all local tags | Clean slate |
-| `list`       | `log` `l`      | Show local tags | Review releases |
-| `remote`     | `fetch` `r`    | Fetch and show remote tags | Check remote releases |
-
-### `gitb merge <mode>`
-
-| **Mode**  | **Short** | **Description** | **When to Use** |
-|-----------|-----------|-----------------------------------------------------------------|--------------|
-| `<empty>` |           | Select branch to merge with conflict resolution | Feature integration |
-| `main`    | `m`       | Merge main into current branch | Update feature branch |
-| `to-main` | `tm`      | Switch to main and merge current branch | Complete feature |
-
-### `gitb rebase <mode>`
-
-| **Mode**      | **Short**           | **Description** | **Best For** |
-|---------------|---------------------|-------------------------------------------------------------------------------|--------------|
-| `<empty>`     |                     | Select base branch for rebase | Branch updates |
-| `main`        | `m`                 | Rebase current branch onto main | Linear history |
-| `interactive` | `i`                 | Interactive rebase from selected commit | History editing |
-| `autosquash`  | `a` `s` `f` `ia` | Interactive rebase with fixup commits | Clean commit history |
-
-### `gitb reset <mode>`
-
-| **Mode**      | **Short** | **Description** | **Use Case** |
-|---------------|-----------|-------------------------------------------------------------------------|--------------|
-| `<empty>`     |           | Reset last commit (mixed mode) | Undo last commit, keep changes |
-| `soft`        | `s`       | Soft reset last commit | Redo commit message |
-| `undo`        | `u`       | Undo last reset operation | Recover from mistake |
-| `interactive` | `i`       | Select commit to reset to | Go back multiple commits |
-| `ref`         | `r`       | Reset to selected HEAD reference | Use reflog recovery |
-
-### `gitb stash <mode>`
-
-| **Mode**     | **Short** | **Description** | **Perfect For** |
-|--------------|-----------|-----------------|-----------------|
-| `<empty>`    |           | Interactive stash menu | Explore all options |
-| `select`     | `sel`     | Stash specific files | Partial work saving |
-| `all`        |           | Stash everything including untracked | Complete state save |
-| `list`       | `l`       | View all stashes | Find specific stash |
-| `pop`        | `p`       | Apply and remove stash | Continue work |
-| `show`       | `s`       | Preview stash contents | Check before apply |
-| `apply`      | `a`       | Apply without removing | Keep stash backup |
-| `drop`       | `d`       | Delete stash | Cleanup unused stashes |
-
-### `gitb hook <mode>`
-
-| **Mode**     | **Short**       | **Description** | **Use Case** |
-|--------------|-----------------|-----------------|--------------|
-| `<empty>`    |                 | Interactive action menu | Explore all operations |
-| `list`       | `l`             | Show all hooks with status | Audit current setup |
-| `create`     | `new` `c`       | Create new hook with templates | Set up automation |
-| `edit`       | `e`             | Edit existing hook | Modify behavior |
-| `toggle`     | `t`             | Enable/disable hook | Temporary control |
-| `remove`     | `rm` `r`        | Delete hook(s) | Cleanup |
-| `test`       | `run` `check`   | Test hook execution | Verify functionality |
-| `show`       | `cat` `view` `s`| Display hook contents | Review implementation |
-
-### `gitb config <mode>`
-
-| **Mode**    | **Short**               | **Description** | **Example** |
-|-------------|-------------------------|-------------------------------------------------------------|-------------|
-| `<empty>`   |                         | Show current gitbasher configuration | Check setup |
-| `user`      | `u` `name` `email`    | Set user name and email | Initial setup |
-| `default`   | `def` `d` `b` `main` | Set default branch name | Project standards |
-| `separator` | `sep` `s`              | Set branch name separator | Naming conventions |
-| `editor`    | `ed` `e`               | Set commit message editor | Personal preference |
-| `ticket`    | `ti` `t` `jira`       | Set ticket prefix for commits/branches | Issue tracking |
-| `scopes`    | `sc` `s`               | Set common scopes for commits | Project structure |
-| `ai`        | `llm` `key`            | Configure AI API key | Smart commits |
-| `proxy`     | `prx` `p`              | Set HTTP proxy for AI requests | Geographic restrictions |
-| `delete`    | `unset` `del`          | Remove global configuration | Reset settings |
-
-### `gitb log <mode>`
-
-| **Mode**      | **Short**     | **Description** | **Great For** |
-|---------------|---------------|-----------------------------------------------------------------------|--------------|
-| `<empty>`     |               | Pretty git log for current branch | Review recent work |
-| `branch`      | `b`           | Select branch to view log | Compare branches |
-| `compare`     | `comp` `c`    | Compare logs between two branches | Merge preparation |
-| `search`      | `s`           | Search commits with various criteria | Find specific changes |
-
-#### Log Search Options
-
-| **Search Mode** | **Short** | **Description** | **Example Use** |
-|-----------------|-----------|-----------------------------------------------------------------------|--------------|
-| `message`       | `msg` `m` | Search by commit message | Find feature commits |
-| `author`        | `a`       | Search by author name/email | Team member contributions |
-| `file`          | `f`       | Search commits affecting specific files | File history |
-| `content`       | `pickaxe` `p` | Search by added/removed content | Code archaeology |
-| `date`          | `d`       | Search within date range | Release timeframes |
-| `hash`          | `commit` `h` | Search by commit hash pattern | Specific commit lookup |
-
-
-## Troubleshooting & FAQ
-
-### 📋 Common Issues & Solutions
-
-#### ❓ "Command not found: gitb"
-```bash
-# Check if gitb is installed
-which gitb
-
-# If not found, reinstall
-GITB_PATH=/usr/local/bin/gitb && \
-curl -SL https://github.com/maxbolgarin/gitbasher/releases/latest/download/gitb -o $GITB_PATH && \
-chmod +x $GITB_PATH
-
-# Alternative: Install to user directory
-mkdir -p ~/.local/bin
-GITB_PATH=~/.local/bin/gitb && \
-curl -SL https://github.com/maxbolgarin/gitbasher/releases/latest/download/gitb -o $GITB_PATH && \
-chmod +x $GITB_PATH
-# Add to PATH: echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
-```
-
-#### ❓ "Permission denied" when installing
-```bash
-# Use sudo for system-wide installation
-sudo curl -SL https://github.com/maxbolgarin/gitbasher/releases/latest/download/gitb -o /usr/local/bin/gitb
-sudo chmod +x /usr/local/bin/gitb
-
-# Or install to user directory (no sudo needed)
-mkdir -p ~/.local/bin
-curl -SL https://github.com/maxbolgarin/gitbasher/releases/latest/download/gitb -o ~/.local/bin/gitb
-chmod +x ~/.local/bin/gitb
-```
-
-#### ❓ AI features not working
-```bash
-# Check if API key is configured
-gitb cfg
-
-# Set up API key
-gitb cfg ai
+echo 'alias gc="gitb c"'   >> ~/.bashrc
+echo 'alias gp="gitb p"'   >> ~/.bashrc
+echo 'alias gpu="gitb pu"' >> ~/.bashrc
+echo 'alias gb="gitb b"'   >> ~/.bashrc
+```
 
-# Test with a simple commit
-echo "test" >> test.txt
-git add test.txt
-gitb c ai
+**zsh tip:** if zsh autocorrects `gitb` → `git`, add `alias gitb='nocorrect gitb'` to `~/.zshrc`.
 
-# If in restricted region, set up proxy
-gitb cfg proxy
-# Example: http://proxy.example.com:8080
+---
+
+## Other install paths
+
+### System-wide install
+```bash
+# system-wide install (sudo, /usr/local/bin)
+curl -fsSL https://raw.githubusercontent.com/maxbolgarin/gitbasher/main/install.sh | bash -s -- --sudo
+```
+
+### Custom location
+```bash
+GITB_DIR=/opt/bin curl -fsSL https://raw.githubusercontent.com/maxbolgarin/gitbasher/main/install.sh | bash
 ```
 
-#### ❓ "Bad substitution" or bash errors
+
+### Pin a release
 ```bash
-# Check bash version (needs 4.0+)
-bash --version
+GITB_VERSION=v3.10.2 curl -fsSL https://raw.githubusercontent.com/maxbolgarin/gitbasher/main/install.sh | bash
+```
 
-# macOS: Install newer bash (and Homebrew if needed)
-# 1) Install Homebrew (if missing):
-/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
-# 2) Install bash:
-brew install bash
-# 3) Optional: make it your default shell (restart Terminal after):
-sudo sh -c 'echo /opt/homebrew/bin/bash >> /etc/shells' && chsh -s /opt/homebrew/bin/bash
+## Uninstall
 
-# Ubuntu/Debian: upgrade bash
-sudo apt update && sudo apt install --only-upgrade bash
+### One command (recommended)
+```bash
+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`.
 
-#### ❓ Git operations fail
+### Manual
+If `gitb` is already gone from PATH:
 ```bash
-# Check git version (needs 2.23+)
-git --version
+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
 
-# Update git
-# macOS: brew install git
-# Ubuntu: sudo apt install git
-# Or download from: https://git-scm.com/downloads
+# 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
 ```
 
-### 🔧 System Requirements
+---
 
-| **System** | **Bash** | **Git** | **Installation Method** |
-|------------|----------|---------|------------------------|
-| **Linux** | 4.0+ | 2.23+ | `apt install bash git` |
-| **macOS** | 4.0+ | 2.23+ | `brew install bash git` |
-| **Windows** | WSL | WSL | `wsl --install` then Linux steps |
+## Troubleshooting
 
-### 💡 Pro Tips
+<details>
+<summary><b>Command not found: gitb</b></summary>
 
-#### 🎯 **Workflow Optimization**
 ```bash
-# Set up aliases for even faster usage
-echo 'alias gc="gitb c"' >> ~/.bashrc
-echo 'alias gp="gitb p"' >> ~/.bashrc
-echo 'alias gpu="gitb pu"' >> ~/.bashrc
-echo 'alias gb="gitb b"' >> ~/.bashrc
+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](#install-in-10-seconds)).
+</details>
 
-### 🆘 **Still Having Issues?**
+<details>
+<summary><b>Permission denied during install</b></summary>
 
-**Ask for help**: [Open an issue](https://github.com/maxbolgarin/gitbasher/issues) or contact [@maxbolgarin](https://t.me/maxbolgarin)
+The default install goes to `~/.local/bin` (no sudo). For a system-wide install pass `--sudo`:
+```bash
+curl -fsSL https://raw.githubusercontent.com/maxbolgarin/gitbasher/main/install.sh | bash -s -- --sudo
+```
+</details>
 
-### 🗑️ **Uninstall**
+<details>
+<summary><b>AI features not working</b></summary>
 
 ```bash
-# Remove gitbasher
-sudo rm /usr/local/bin/gitb
-# or
-rm ~/.local/bin/gitb
+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.
+</details>
+
+<details>
+<summary><b>"could not lock config file" / git config permission</b></summary>
+
+`git config --global` writes to `~/.gitconfig`. If gitbasher reports `could not lock config file`:
 
-# Remove configuration (optional)
-rm -rf ~/.gitbasher
+```bash
+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).
+</details>
 
-## Roadmap for v4
+<details>
+<summary><b>"Bad substitution" or bash errors</b></summary>
 
-1. Add support of multi modes, e.g. `gitb c fastp` -> `gitb c fast push` to prevent from a lot of modes to support all combinations
-2. Add more interactive menus, because it is difficult to remember all commands and modes
-3. Add better error messages and settings for verbosity
-4. Add more AI APIs providers
+`bash --version` must be 4.0+.
 
-## Testing
+- 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`)
+- Ubuntu/Debian: `sudo apt update && sudo apt install --only-upgrade bash`
+</details>
 
-**gitbasher** includes a comprehensive test suite using [BATS (Bash Automated Testing System)](https://github.com/bats-core/bats-core) to ensure code quality and prevent regressions during refactoring.
+<details>
+<summary><b>System requirements</b></summary>
 
-### Running Tests
+| OS | Bash | Git | Install |
+|----|------|-----|---------|
+| Linux | 4.0+ | 2.23+ | `apt install bash git` |
+| macOS | 4.0+ | 2.23+ | `brew install bash git` |
+| Windows | WSL | WSL | `wsl --install` then Linux steps |
+</details>
 
-```bash
-# Run all tests
-make test
+<details>
+<summary><b>Common git errors and what to run instead</b></summary>
 
-# Run a specific test file
-make test-file FILE=test_sanitization.bats
+| 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 |
 
-# Or use the test runner directly
-cd tests
-./run_tests.sh
-```
+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>
 
-### Test Coverage
+<details>
+<summary><b>Uninstall</b></summary>
 
-- **115+ tests** across multiple test files
-- Input sanitization (security-critical)
-- Git operations (commit, push, pull, merge, rebase)
-- Branch management
-- Common utilities
+```bash
+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>
 
-See [tests/README.md](tests/README.md) for detailed testing documentation.
+**Still stuck?** [Open an issue](https://github.com/maxbolgarin/gitbasher/issues) or ping [@maxbolgarin](https://t.me/maxbolgarin) on Telegram.
 
-## Contributing
+---
 
-If you'd like to contribute to **gitbasher**, make a fork and submit a pull request. You also can open an issue or text me on Telegram: https://t.me/maxbolgarin
+## Contributing
 
-### Development Workflow
+PRs welcome. See [CONTRIBUTING.md](./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](./ARCHITECTURE.md).
 
-1. Fork the repository
-2. Create a feature branch
-3. **Write tests first** for new functionality
-4. Implement your changes
-5. Run tests: `make test`
-6. Ensure all tests pass
-7. Submit a pull request
+```bash
+make build               # rebuild dist/gitb
+make test                # run all 115+ tests
+make test-file FILE=test_sanitization.bats
+```
 
-#### Maintainers
+Workflow:
 
-* [maxbolgarin](https://github.com/maxbolgarin)
+1. Fork and create a feature branch
+2. **Write tests first** (BATS, see [tests/README.md](tests/README.md))
+3. Implement
+4. `make test` — all tests must pass
+5. Open a PR
 
-#### License
+**Maintainer:** [@maxbolgarin](https://github.com/maxbolgarin)
 
-The source code license is MIT, as described in the [LICENSE](./LICENSE) file.
+**License:** MIT — see [LICENSE](./LICENSE).