gitbutler-omz

April 4, 2026 · View on GitHub

An Oh My Zsh plugin for GitButler — CLI aliases, a Git protection shield, and prompt integration for standard OMZ themes and 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 with Oh My Zsh installed
but CLI installed and available in $PATH
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:

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:

plugins=(... gitbutler)

3. Reload your shell:

source ~/.zshrc

Antigen

antigen bundle batuhan0sanli/gitbutler-omz

Zinit

zinit light batuhan0sanli/gitbutler-omz

Manual

Source the plugin file directly from your ~/.zshrc:

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:

rm -rf ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/gitbutler

3. Reload your shell:

source ~/.zshrc