# gitbutler-omz > An [Oh My Zsh](https://ohmyz.sh/) plugin for [GitButler](https://gitbutler.com/) — CLI aliases, a Git protection shield, and prompt integration for standard OMZ themes and Powerlevel10k. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![Oh My Zsh](https://img.shields.io/badge/Oh%20My%20Zsh-compatible-brightgreen)](https://ohmyz.sh/) [![Powerlevel10k](https://img.shields.io/badge/Powerlevel10k-supported-blueviolet)](https://github.com/romkatv/powerlevel10k) --- ## Features - **50+ CLI Aliases** — Short, memorable shortcuts for all `but` commands, grouped by workflow - **Git Protection Shield** — Intercepts destructive `git` commands when on the `gitbutler/workspace` branch and prompts for confirmation - **Prompt Integration** — Replaces the default branch name with live GitButler workspace metrics (active branch count, dirty state, pending pushes) in standard OMZ themes - **Powerlevel10k Support** — Patches `my_git_formatter` to display GitButler-aware status in the p10k prompt --- ## Requirements - [Zsh](https://www.zsh.org/) with [Oh My Zsh](https://ohmyz.sh/) installed - [`but` CLI](https://gitbutler.com/) installed and available in `$PATH` - [`jq`](https://jqlang.github.io/jq/) — required for prompt integration (aliases still work without it) --- ## Installation ### Oh My Zsh (recommended) **1.** Clone this repository into your Oh My Zsh custom plugins directory: ```zsh git clone https://github.com/batuhan0sanli/gitbutler-omz \ ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/gitbutler ``` **2.** Add `gitbutler` to the plugins list in your `~/.zshrc`: ```zsh plugins=(... gitbutler) ``` **3.** Reload your shell: ```zsh source ~/.zshrc ``` ### Antigen ```zsh antigen bundle batuhan0sanli/gitbutler-omz ``` ### Zinit ```zsh zinit light batuhan0sanli/gitbutler-omz ``` ### Manual Source the plugin file directly from your `~/.zshrc`: ```zsh source /path/to/gitbutler-omz/gitbutler.plugin.zsh ``` --- ## Aliases ### Inspection | Alias | Command | Description | |--------|-----------------------|--------------------------------------------------| | `bst` | `but status` | Show workspace state | | `bstv` | `but status -f -v` | Show status with committed files (verbose) | | `bstu` | `but status -u` | Show unintegrated upstream commits | | `bd` | `but diff` | Show diff of current changes | | `bsh` | `but show` | Show details of a commit or branch | ### Branch Management | Alias | Command | Description | |---------|---------------------------|--------------------------------------------------| | `bb` | `but branch` | List branches | | `bbl` | `but branch list` | List all branches with search | | `bbn` | `but branch new` | Create a new parallel branch | | `bbns` | `but branch new --anchor` | Create a new stacked branch | | `bbr` | `but branch reword` | Rename a branch | | `bbd` | `but branch delete` | Delete a branch | | `bbm` | `but branch move` | Move / restack a branch | | `bbs` | `but branch show` | Show commits ahead of base for a branch | | `bba` | `but apply` | Apply a branch to the workspace | | `bbua` | `but unapply` | Unapply a branch from the workspace | ### Committing | Alias | Command | Description | |---------|---------------------|--------------------------------------------------| | `bcm` | `but commit -m` | Commit with a message | | `bcai` | `but commit --ai` | Commit with an AI-generated message | | `bcc` | `but commit -c` | Create a new branch and commit to it | | `bco` | `but commit --only` | Commit only already-staged changes | | `bsg` | `but stage` | Stage a file or hunk to a branch | | `bab` | `but absorb` | Absorb changes into appropriate commits | | `buc` | `but uncommit` | Uncommit changes back to unstaged area | | `bam` | `but amend` | Amend a file change into a specific commit | ### Remote & Pull Requests | Alias | Command | Description | |---------|--------------------------|-------------------------------------------------| | `bp` | `but push` | Push all branches with unpushed commits | | `bpf` | `but push --with-force` | Force push a branch | | `bl` | `but pull` | Pull and integrate all active branches | | `blc` | `but pull --check` | Preview what a pull would do | | `bpr` | `but pr` | Manage pull requests | | `bprn` | `but pr new` | Create a new pull request | | `bprd` | `but pr set-draft` | Set a PR as draft | | `bprr` | `but pr set-ready` | Set a PR as ready to review | ### Commit Editing | Alias | Command | Description | |---------|-----------------|-----------------------------------------------------| | `brw` | `but reword` | Edit a commit message | | `bsq` | `but squash` | Squash commits together | | `bmv` | `but move` | Move a commit or branch | | `bdc` | `but discard` | Discard uncommitted changes | | `bcp` | `but pick` | Cherry-pick a commit into an applied branch | | `brb` | `but rub` | Combine two commits or branches | ### Operation Log | Alias | Command | Description | |----------|--------------------------|------------------------------------------------| | `bundo` | `but undo` | Undo the last operation | | `bol` | `but oplog` | Show operation history | | `bols` | `but oplog snapshot` | Create an on-demand snapshot | | `bolr` | `but oplog restore` | Restore to a specific snapshot | ### Conflict Management | Alias | Command | Description | |---------|---------------|-----------------------------------------------------| | `brs` | `but resolve` | Enter conflict resolution mode | | `bmrg` | `but merge` | Merge a branch into a local target branch | ### Auto-Assignment | Alias | Command | Description | |---------|---------------|-----------------------------------------------------| | `bmk` | `but mark` | Mark a branch or commit for auto-stage/commit | | `bumk` | `but unmark` | Remove all marks from workspace | ### Workspace | Alias | Command | Description | |---------|----------------|----------------------------------------------------| | `bgui` | `but gui` | Open the GitButler GUI | | `bcl` | `but clean` | Remove empty branches | | `bsu` | `but setup` | Set up GitButler in current repository | | `btd` | `but teardown` | Return to vanilla git branch management | --- ## Git Protection Shield When you are on the `gitbutler/workspace` branch, the plugin wraps the `git` command and intercepts potentially destructive operations: ``` add, commit, push, checkout, merge, rebase, stash, cherry-pick, branch ``` Running any of these will display a warning and prompt for confirmation before proceeding: ``` [GitButler Protection] Using git commit in GitButler mode will break the structure. Please use 'but' commands (e.g.: but commit, but branch new, but stage). Are you sure you want to continue with the standard git command? [y/N] ``` All other `git` commands (e.g. `git log`, `git diff`) pass through unmodified. --- ## Prompt Integration ### Standard Oh My Zsh Themes When on the `gitbutler/workspace` branch the plugin overrides `git_prompt_info()` to show live workspace metrics instead of the raw branch name: ``` [but 3 ⇡2 ✗] ▲ ▲ ▲ │ │ └─ dirty indicator (theme's CLEAN/DIRTY symbol) │ └──── pending pushes (branches with unpushed commits) └─────── active branch count ``` The `git` prefix in the theme's prompt is automatically replaced with `but`. ### Powerlevel10k The plugin patches `my_git_formatter` (the recommended customization point in p10k) on the first `precmd` call after sourcing. The workspace segment becomes: ``` ⧓ 3 ⇡2 * ▲ ▲ ▲ │ │ └─ dirty indicator │ └──── pending pushes └─────── active branch count ``` > **Note:** The p10k patch only activates if `my_git_formatter` is already defined when the plugin loads (i.e. your `~/.p10k.zsh` must be sourced before or alongside the plugin). --- ## Uninstall **1.** Remove `gitbutler` from the plugins list in `~/.zshrc`. **2.** Delete the plugin directory: ```zsh rm -rf ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/gitbutler ``` **3.** Reload your shell: ```zsh source ~/.zshrc ``` --- ## License MIT © [Batuhan Sanli](https://github.com/batuhan0sanli)