Getting started

Requirements

Go 1.27+
git 2.30+
A terminal with truecolor

Mouse support and the kitty keyboard protocol are used where available. Without them things degrade cleanly.

Install

bubblegit is in early beta: it works, but commands and keybindings can still change between releases. The latest tagged build is v0.1.1, marked a pre-release on GitHub.

With Go

go install github.com/f3xp/bubblegit/cmd/bubblegit@v0.1.1

Go puts the binary in $(go env GOPATH)/bin, which is ~/go/bin unless you changed it. If your shell answers bubblegit: command not found, that directory is not on your PATH yet. Add it and open a new terminal:

echo 'export PATH="$PATH:$(go env GOPATH)/bin"' >> ~/.zshrc   # or ~/.bashrc

macOS and Linux

Download the archive for your system and install the binary to /usr/local/bin:

os=$(uname -s | tr A-Z a-z); arch=$(uname -m)
[ "$arch" = x86_64 ] && arch=amd64; [ "$arch" = aarch64 ] && arch=arm64
curl -fsSL "https://github.com/f3xp/bubblegit/releases/download/v0.1.1/bubblegit_v0.1.1_${os}_${arch}.tar.gz" | tar xz
sudo install "bubblegit_${os}_${arch}/bubblegit" /usr/local/bin/

If you download the archive in a browser instead, macOS quarantines the unsigned binary. Clear that once before running it:

xattr -d com.apple.quarantine ./bubblegit

Windows

In PowerShell, this unpacks the binary into your user programs folder and adds that folder to your PATH:

$dir = "$env:LOCALAPPDATA\Programs\bubblegit"
Invoke-WebRequest https://github.com/f3xp/bubblegit/releases/download/v0.1.1/bubblegit_v0.1.1_windows_amd64.zip -OutFile "$env:TEMP\bubblegit.zip"
Expand-Archive "$env:TEMP\bubblegit.zip" "$env:TEMP\bubblegit" -Force
New-Item -ItemType Directory -Force $dir | Out-Null
Copy-Item "$env:TEMP\bubblegit\bubblegit_windows_amd64\bubblegit.exe" $dir
[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";$dir", "User")

Open a new terminal afterwards so it picks up the new PATH.

Every archive and its SHA-256 is also on the releases page, in checksums.txt.

From a clone

go run ./cmd/bubblegit

Run

Check that your shell finds it:

command -v bubblegit   # PowerShell: Get-Command bubblegit

Then run it from anywhere inside a git repository:

cd path/to/your/repo
bubblegit

The four views

Each view is a pair of panes: the document on the left, the list on the right.

Key	View
`1`	Working tree: the diff of the selected file on the left, files on the right
`2`	Log: the selected commit on the left, commits with a graph column on the right
`3`	Branches: the tip commit of the selected branch on the left, local branches on the right
`4`	Stashes: the selected stash’s patch on the left, the stash list on the right

Moving around

Key	Action
`j` `k`	move the cursor
`G` `home` `end`	jump to the ends
`ctrl+d` `ctrl+u`	half-page
`tab`	switch pane
`R`	re-read the view now
`?`	show every keybinding in a popup
`q` `ctrl+c`	quit

The full list is on the keybindings page.