gitbash 1.9.1 → 2.0.1

package/README.md

@@ -17,21 +17,47 @@ npm i -g gitbash && gitbash --config
 ```bash
 gitbash --help         # Show help
 gitbash --version      # Show version
-gitbash --init         # Print shell init code
+gitbash --init         # Print shell functions (see Shell integration)
 gitbash --config       # Interactive configuration wizard
-gitbash --config-local # Configure local overrides for current repository
-gitbash --config-user  # Configure user-specific overrides (excluded from git)
+gitbash --config-local # Configure overrides for the current repository (committed)
+gitbash --config-user  # Configure personal overrides for the current repository
 ```
 
 ### Dependencies
 
 ```bash
+# Required
+git >= 2.23, bash >= 3.2
+
 # Optional (recommended)
-brew install fzf        # Interactive menus and previews
+brew install fzf        # Interactive menus and previews (fzf >= 0.36)
 brew install git-delta  # Better diff highlighting
 brew install bat        # File preview with syntax highlighting
 ```
 
+### Shell integration
+
+Add to your `.zshrc` or `.bashrc` to call the commands without the `gitbash` prefix:
+
+```bash
+eval "$(gitbash --init)"             # commit, switch, status, ...
+eval "$(gitbash --init --prefix=gb-)" # gb-commit, gb-switch, ... (avoids shadowing e.g. /usr/bin/pr)
+```
+
+This defines small wrapper functions; every command still runs in its own bash process, so nothing else is added to your shell. Individual aliases work too, e.g. `alias commit="gitbash commit"`.
+
+### Upgrading to 2.0
+
+2.0 is a security and safety release. What changes for you:
+
+- **Restart your shell** after upgrading, so `eval "$(gitbash --init)"` picks up the new wrapper functions.
+- Config files are **read, not executed**: only plain `GITBASH_*="value"` lines are used, other lines are ignored with a warning. `GITBASH_MERGE_COMMAND` is ignored in a committed `.gitbashrc`.
+- `status` no longer commits and pushes after staging. Use `Ctrl-O` to commit.
+- `stale` toggles all/stale branches with `Ctrl-T` (was `Ctrl-A`).
+- Protected branches (base branch and `GITBASH_PROTECTED_BRANCHES`) are never offered for deletion. `cleanup` and `switch` delete with `git branch -d` and ask again before force-deleting unmerged work.
+- When your branch and the remote diverged, `commit -p`, `pr -p` and `update -p` ask whether to rebase, merge or abort instead of rebasing silently.
+- fzf 0.36 or newer is required for the interactive menus.
+
 ## Commands
 
 ### branch
@@ -47,13 +73,15 @@ branch --version    # Show version
 ### create
 
 ```bash
-create [JIRA_LINK|ISSUE] [TITLE...]
+create [--feature|--bugfix|--hotfix|--release|-t] [--push|--no-push] [JIRA_LINK|ISSUE] [TITLE...]
 ```
 
-Create feature branch with optional Jira parsing. Updates main first, pushes and tracks.
+Create a branch from the latest `origin/<base>` with optional Jira parsing, then push and track it (`GITBASH_CREATE_AUTO_PUSH`, `--no-push`).
 
 **Branch Name Format:** `<type>/<custom-prefix>/<issue>-<title>` or `<type>/<custom-prefix>/<title>`
 
+Issue keys like `PROJ-123`, `AB2-45` or `proj-7`, or a Jira URL. Titles are lower-cased, umlauts and accents transliterated (`Über` → `ueber`).
+
 **Examples with custom prefix** (`GITBASH_CREATE_BRANCH_PREFIX="awesome-team"`):
 
 With issue parsing enabled (default):
@@ -75,17 +103,10 @@ create                                  # Interactive mode (no Jira prompt)
 
 **Examples with empty prefix** (`GITBASH_CREATE_BRANCH_PREFIX=""`, default):
 
-With parsing enabled:
-
 ```bash
 create PROJ-123 fix bug                 # → feature/PROJ-123-fix-bug
 create fix bug                          # → feature/NOISSUE-fix-bug
-```
-
-With parsing disabled:
-
-```bash
-create enhance login screen             # → feature/enhance-login-screen
+create enhance login screen             # → feature/enhance-login-screen (parsing disabled)
 ```
 
 ### switch
@@ -94,7 +115,9 @@ create enhance login screen             # → feature/enhance-login-screen
 switch [FILTER...]
 ```
 
-Switch branches with fzf. Shows local first, then remotes (deduped). Preview shows commit history.
+Switch branches with fzf. Shows local branches (`merged:` = fully merged into the base branch), then remote branches without a local copy. Preview shows commit history. If exactly one branch name matches the filter, switches directly. After switching, offers to fast-forward a branch that is behind.
+
+- `Del` deletes the selected local branch (asks first, default no; unmerged commits need a second confirmation)
 
 ```bash
 switch              # Browse all branches
@@ -104,28 +127,40 @@ switch captcha      # Pre-filter for "captcha"
 ### commit
 
 ```bash
-commit [MESSAGE] [-p|--push] [-s|--staged]
+commit [-p] [-s] [-a] [-t] [-y] [--force-with-lease] [MESSAGE...] [-- MESSAGE...]
 ```
 
-Commit with optional push. Smart staging: prompts if both staged/unstaged exist.
+Commit with optional push.
+
+- Only staged changes → commits them. Only unstaged/new files → stages everything (lists new files first).
+- Both staged and unstaged → asks `[s]taged only` (default) or `[a]ll`.
+- `-p` pushes; new branches get tracking. If the remote diverged, asks: rebase, merge or abort.
+- `--amend` without a message keeps the old one; with `-p` it asks before `push --force-with-lease`.
 
 ```bash
-commit fix bug           # Commit all
+commit fix bug           # Commit
 commit -s fix bug        # Commit staged only
 commit -p add feature    # Commit and push
+commit -t add endpoint   # Conventional commit type menu (feat, fix, ...)
+commit --amend           # Amend, keep message
 ```
 
 ### status
 
-Interactive staging with fzf. Toggle files with Enter, ESC to exit. Shows diffs in preview.
+Interactive staging with fzf and diff previews.
+
+- `Enter` stages the selected files (unstages fully staged ones)
+- `Ctrl-R` discards changes (asks first)
+- `Ctrl-O` commits the staged changes, then asks whether to push
+- `ESC` exits
 
 ### pr
 
 ```bash
-pr [-p|--push]
+pr [-p|--push] [--print]
 ```
 
-Open PR in browser. `-p` pushes first.
+Open the pull request in the browser: the existing PR via the GitHub CLI when available, otherwise the create page (GitHub, GitHub Enterprise, GitLab, Bitbucket, Azure DevOps). Offers to commit local changes and to push a branch that is not on the remote yet. `-p` pushes first, `--print` prints the URL.
 
 ### update
 
@@ -133,21 +168,20 @@ Open PR in browser. `-p` pushes first.
 update [-p|--push]
 ```
 
-Merge latest main/master into current branch. Opens merge tool on conflicts.
+Merge the latest `origin/<base>` into the current branch. With local changes, asks to commit, stash (restored afterwards) or abort. Lists conflicts and opens the merge tool (`GITBASH_MERGE_COMMAND`). On the base branch itself, fast-forwards it.
 
 ### stale
 
 ```bash
-stale [-a|--all] [--age=N] [--json] [FILTER...]
+stale [-a|--all] [-m|--my] [--age=N] [--json] [FILTER...]
 ```
 
-List remote branches >3 months old (oldest first). Multi-select with TAB to delete.
+List remote branches older than 3 months (oldest first). Multi-select with TAB, Enter deletes them from the remote after confirmation. Protected branches are never listed.
 
-- By default, pre-filters by your git username (from `git config user.name`)
-- `-a|--all` shows all branches without username filter
-- `--age=N` sets stale threshold in months (default: 3, or `GITBASH_STALE_MONTHS`)
-- `Ctrl-A` toggles showing all branches (including recent ones)
-- `--json` outputs JSON for scripting (same format as cleanup)
+- `-a|--all` starts with all branches (not only stale ones); `Ctrl-T` toggles
+- `-m|--my` pre-fills the filter with your git username
+- `--age=N` sets the threshold in months (default: 3, or `GITBASH_STALE_MONTHS`)
+- `--json` outputs JSON for scripting
 
 ### stashes
 
@@ -163,7 +197,7 @@ Create named stash (includes untracked files).
 
 ### unstash
 
-Apply stash with fzf picker. Optionally drop after applying.
+Apply stash with fzf picker. Drops it afterwards unless you say no.
 
 ### cleanstash
 
@@ -172,16 +206,17 @@ Delete stashes (multi-select with TAB).
 ### cleanup
 
 ```bash
-cleanup [--json]
+cleanup [--dry-run] [--days=N] [-y|--yes] [--json]
 ```
 
-Find and delete leftover local branches. Shows all local branches categorized:
+Find and delete leftover local branches:
 
-- **[MERGED]** - Remote was deleted (pre-selected)
-- **[STALE]** - No commits in 7+ days (pre-selected)
+- **[MERGED]** - Changes are in the base branch (also squash merges). Pre-selected if the remote branch is gone or it is older than N days.
+- **[STALE]** - No commits in 7+ days. Pre-selected only if everything is pushed.
+- **[GONE]** - Remote branch deleted but changes not merged (not selected)
 - **[RECENT]** - Recent activity (not selected)
 
-Switches to main/master first if current branch is selected for deletion.
+Unpushed commits are shown per branch. Deletes with `git branch -d`; force-deleting unmerged work needs a second confirmation. Switches to the base branch first if the current branch is deleted. `--dry-run` lists and `--yes` deletes the pre-selected branches without the picker.
 
 `--json` outputs non-interactive JSON for scripting:
 
@@ -192,7 +227,10 @@ Switches to main/master first if current branch is selected for deletion.
     "author_email": "dev@example.com",
     "author_name": "Dev",
     "name": "feature/old",
-    "last_change_relative": "2 weeks ago"
+    "last_change_relative": "2 weeks ago",
+    "category": "merged",
+    "preselected": true,
+    "unpushed_commits": 0
   }
 ]
 ```
@@ -203,93 +241,66 @@ Switches to main/master first if current branch is selected for deletion.
 commits [COUNT]
 ```
 
-List recent commits with option to revert. Multi-select with TAB to revert multiple.
+List recent commits with option to revert. Multi-select with TAB; selected commits are reverted newest first.
 
 ```bash
 commits        # Show last 20 commits
 commits 50     # Show last 50 commits
 ```
 
-### Configuration
+## Configuration
 
-gitbash reads configuration from `~/.gitbashrc` if it exists. You can set the following variables:
+gitbash reads `~/.gitbashrc`. Run `gitbash --config` to set it up interactively, or write it by hand:
 
 ```bash
 # Branch prefix inserted between type and issue number (default: "")
-# No trailing slash needed - it's added automatically
-# Format: <type>/<prefix>/<issue>-<title> or <type>/<prefix>/<title>
-# Examples: "awesome-team" or "" for no prefix
 GITBASH_CREATE_BRANCH_PREFIX=""
 
-# Merge tool command invoked by 'update' when conflicts occur (default: "fork")
-GITBASH_MERGE_COMMAND="fork"
-
 # Disable Jira issue number parsing in branch names: yes or no (default: "no")
 GITBASH_CREATE_NO_ISSUE_PARSING="no"
 
 # Fallback prefix when no issue number is provided (default: "NOISSUE")
-# Only used when GITBASH_CREATE_NO_ISSUE_PARSING="no"
 GITBASH_CREATE_ISSUE_PARSING_FALLBACK="NOISSUE"
 
-# Theme for delta/bat diff highlighting: auto, dark, or light (default: "light")
-GITBASH_THEME="light"
+# Push new branches right after 'create': yes or no (default: "yes")
+GITBASH_CREATE_AUTO_PUSH="yes"
 
-# Stale branch threshold in months for 'stale' command (default: 3)
-GITBASH_STALE_MONTHS=3
+# Merge tool invoked by 'update' on conflicts (default: "fork")
+GITBASH_MERGE_COMMAND="fork"
 
-# Cleanup threshold in days - branches merged more than this many days ago (default: 7)
-GITBASH_CLEANUP_DAYS=7
-```
+# Theme for delta/bat: auto, dark or light (default: "auto")
+GITBASH_THEME="auto"
 
-You can create this file manually or use `gitbash --config` to configure interactively.
+# Stale thresholds: 'stale' in months, 'cleanup' in days (defaults: 3, 7)
+GITBASH_STALE_MONTHS="3"
+GITBASH_CLEANUP_DAYS="7"
 
-#### Local Configuration
+# Branches never offered for deletion, space-separated globs
+GITBASH_PROTECTED_BRANCHES="main master develop release/*"
+
+# Base branch (default: detected from origin/HEAD, then main, then master)
+GITBASH_BASE_BRANCH=""
 
-gitbash also supports repository-specific configuration overrides. Run `gitbash --config-local` inside a git repository to create a `.gitbashrc` file in the repository root.
+# Remote name (default: "origin")
+GITBASH_REMOTE="origin"
+```
 
-Local settings override the global `~/.gitbashrc` for that repository only. This is useful for:
+Config files are **read, never executed**. Only `GITBASH_*="value"` lines are used (double, single or no quotes, optional `export`, `# comments`). Values cannot contain `$`, backticks, backslashes or quotes; anything else is ignored with a warning.
 
-- Different branch prefixes per project (e.g., team names)
-- Project-specific issue parsing settings
-- Different stale/cleanup thresholds per repository
+#### Local Configuration
 
-The interactive wizard will show each setting's current global value and ask if you want to override it locally. Only overridden values are written to the local config.
+Run `gitbash --config-local` inside a repository to create a committed `.gitbashrc` with overrides for everyone working on it (e.g. a team branch prefix or different thresholds). For security, a committed `.gitbashrc` cannot set `GITBASH_MERGE_COMMAND`.
 
 #### User Configuration
 
-For personal settings that should not be committed to version control, run `gitbash --config-user` to create a `.gitbashrc-user` file in the repository root.
-
-User settings override both global (`~/.gitbashrc`) and local (`.gitbashrc`) settings. The file is automatically added to `.gitignore`.
+Run `gitbash --config-user` to create `.gitbashrc-user` for personal overrides in one repository. It is excluded from git via `.git/info/exclude`.
 
 **Configuration priority (highest to lowest):**
 
-1. `.gitbashrc-user` - User-specific settings (not committed)
-2. `.gitbashrc` - Repository settings (can be committed)
+1. `.gitbashrc-user` - Personal settings for this repository (not committed)
+2. `.gitbashrc` - Repository settings (committed)
 3. `~/.gitbashrc` - Global settings
 
-### Individual aliases
-
-Instead of adding every command via `eval "$(gitbash --init)"` in `.zshrc` or `.bashrc`
-direct usage with `gitbash [command]` is also possible. Or if desired, individual aliases
-can be made.
-
-```bash
-alias branch="gitbash branch"
-alias cleanstash="gitbash cleanstash"
-alias cleanup="gitbash cleanup"
-alias commit="gitbash commit"
-alias commits="gitbash commits"
-alias create="gitbash create"
-alias pr="gitbash pr"
-alias stale="gitbash stale"
-alias stash="gitbash stash"
-alias stashes="gitbash stashes"
-alias status="gitbash status"
-alias switch="gitbash switch"
-alias unstash="gitbash unstash"
-alias update="gitbash update"
-```
-
 ## License
 
 See [LICENSE](LICENSE) file for details.