How to Use BeeBranch: The Beginner's Guide
CodexFuse Team · 2026-11-03T19:31:27.222Z · 8 min read min read
What Is BeeBranch, Exactly?
Learning how to use BeeBranch starts with a plain-English definition: BeeBranch is a local-first desktop Git client that is honest about what it can undo. This BeeBranch git client tutorial takes you from your first install to your first safe undo — and, more importantly, shows you the irreversible line the app refuses to cross. It is open-source (AGPL-3.0-only), built for teams working with GitLab and GitHub, and it runs entirely on your machine: no proprietary cloud, no vendor account, no telemetry, and no AI.
The maker's own one-line pitch says it best: "The local-first desktop Git client." The Product Hunt listing (published October 29, 2026 by @jcbuilds, updated November 2, 2026) describes BeeBranch as "an open-source alternative to commercial Git clients, built for teams working with GitLab and GitHub." The GitHub repo confirms the stack — Rust, Tauri 2, React 19 — and the release on the day this was written is v1.5.0. Listed price on Product Hunt: 0 USD.
If you are brand-new to Git itself rather than to this client, keep CodexFuse's Git beginner guide open in another tab — this guide assumes you know what a commit, a branch, and a reset are, and focuses on the BeeBranch side of the workflow.
How Do I Install BeeBranch?
The BeeBranch install path is refreshingly old-fashioned: there are no package-manager recipes and no app-store wrapper — you download a release artifact for your operating system from the GitHub releases and run it. As of November 3, 2026, the build matrix covers macOS on Apple Silicon (a signed and notarised .dmg), Windows x64 (an NSIS .exe, with an Authenticode signature only when the certificate is configured), and Linux (.AppImage, .deb, and .rpm). macOS on Intel is not in the build matrix, so Intel-Mac users build from source with Rust 1.85 or newer and Node 22 or newer.
Two requirements before you launch it. First, Git 2.34 or newer must already be installed on the machine — BeeBranch drives your real Git, it does not bundle one. Second, updates are delivered in-app through Settings → Updates, are minisign-verified, and the previous version stays installable through rollback.json, so a bad update never strands you.
- Install Git 2.34 or newer and verify with
git --version. - Download the release artifact for your OS (Apple-Silicon .dmg, Windows x64 .exe, or a Linux .AppImage/.deb/.rpm) from the BeeBranch GitHub releases.
- Install it the normal way for your OS and launch BeeBranch.
- Open your first repository — any local clone — and the commit history appears as virtualised rows that stay fast even at 200,000 commits.
- Open Settings → Updates once so you know where verified updates land.
What Is the BeeBranch Undo-Stack Rule?
The BeeBranch undo stack is the feature the whole product is built around, and its rule is deliberately narrow: the stack only contains typed inverses that Git can actually execute — reset --soft/--mixed, read-tree, update-ref, switch, and the stash, worktree, tag, and remote refs. That is the maker's verbatim list from the launch discussion. Everything on that list is a reversible operation, so every entry on the stack is an undo you can trust.
The rest of Git's destructive operations never enter the stack at all. Discard, reset --hard, stash drop, stash apply, stash pop, fetch, push, and submodule update are all labelled irreversible rather than wrapped in a hopeful button — those are the maker's exact words. Saying it once clearly: BeeBranch's undo cannot restore what it refuses to touch, and that refusal is the feature.
| Operation | How BeeBranch treats it |
|---|---|
| reset --soft / --mixed | Enters the undo stack (typed inverse Git can execute) |
| read-tree | Enters the undo stack |
| update-ref | Enters the undo stack |
| switch | Enters the undo stack |
| stash, worktree, tag, remote refs | Enters the undo stack |
| discard, reset --hard | Never enters the stack — labelled irreversible |
| stash drop / apply / pop | Never enters the stack — labelled irreversible |
| fetch, push, submodule update | Never enters the stack — labelled irreversible |
What Does the Journal & Recovery View Show Me?
Every restoration step is written to a SQLite database in WAL mode before it runs, with the exact command and the SHA — again, verbatim from the maker. If the process dies mid-undo, that record becomes restoreInterrupted, shows up in the Journal & recovery view, and is never retried automatically. You get to decide what happens next instead of the app guessing.
The same design covers crashes mid-rebase. Git's own state is the source of truth: on relaunch, BeeBranch restores the repository tab, re-runs read-only detection against .git/rebase-merge and .git/rebase-apply, and the in-progress banner comes back with the rebase variant, the conflict set, and continue/skip/abort. The journal is a separate timeline — crash-interrupted operations and destructive actions — not a synthetic replay of Git's sequencer.
How Does BeeBranch Work with GitLab and GitHub?
BeeBranch is built for teams on GitLab and GitHub, but it never asks you to create an account with BeeBranch itself. There is no vendor account anywhere in the design, which is why the "local-first" claim holds up: the network is only ever used for Git itself, for the GitLab and GitHub APIs, and for the update manifest. The repo's no-telemetry statement is unambiguous: "Zero telemetry, zero AI. The network is only used for Git, the GitLab/GitHub APIs and the update manifest."
That makes the GitHub side of the workflow a natural companion: our GitHub beginner guide covers branches, pull requests, and remotes that this client will be pushing to and pulling from. If your team is on GitLab instead, the GitLab beginner guide covers the same workflow on that platform.
BeeBranch vs BranchBay: Which One Should I Pick?
The one commercial rival worth knowing by name is BranchBay, a native macOS/Windows/Linux Git client at branchbay.dev. BranchBay charges $20 for a license covering two computers — 14 days free, then the one-time payment, no subscription — and v1.0.9 asks for Git 2.50 or newer. BeeBranch is free and AGPL-3.0-only open source; BranchBay is a commercial one-time purchase. That is the whole decision in one line: if you want an open, self-hostable client with an undo stack that admits what it cannot reverse, BeeBranch is the pick; if you prefer a polished commercial client with a one-time license, BranchBay is the lane's other option.
Naming it once, on purpose: BranchBay is a different product, not a BeeBranch feature, and nothing else in this guide depends on it. Run BeeBranch inside your normal development setup the same way — our Docker beginner guide covers keeping that environment reproducible if you want the client and the code on the same page.
Where Is the Irreversible Line?
A BeeBranch review would be dishonest if it skipped the limits, so here is the complete list from the project's own docs. Discard and reset --hard permanently lose uncommitted work — those are the project's own words, and no journal entry can bring it back. The undo stack is capped at 50 operations per repository, and an undo is refused if the repository changed since the operation was recorded. On the plus side, the application never deletes untracked files, so a discard cannot sweep away files Git never saw.
Two things are explicitly not shipped yet. Bitbucket, Azure DevOps, Gitflow, LFS, an integrated terminal, and WSL 2 all sit in the P4 backlog — planned, not available. And the performance figures in the architecture docs are explicitly marked as hypotheses in ADR-0003, so treat any speed claim as aspirational until a release proves it. As of November 3, 2026, the young project (v1.5.0, days after its Product Hunt launch) is exactly what it says on the label: a fast, honest, local-first Git client that knows where its undo ends.
Sources
- Product Hunt — BeeBranch: The local-first desktop Git client (published October 29, 2026; updated November 2, 2026; maker's undo-stack comment on the undo list, irreversible list, SQLite WAL restoration log, 200k-commit virtualisation, and rebase recovery)
- GitHub — Methamorphe/beebranch (AGPL-3.0-only; Rust · Tauri 2 · React 19; v1.5.0; "Zero telemetry, zero AI" statement; release-artifact install matrix)
- BeeBranch docs — ADR-0008 (no application backups) and 04-undo-redo.md (stack cap of 50 ops/repo, undo refused on repo change, never deletes untracked files, P4 backlog)
- BeeBranch docs — ADR-0003 (performance figures marked as hypotheses)
- BranchBay — branchbay.dev ($20 for two computers, 14-day free trial, v1.0.9, Git 2.50+ requirement)
Frequently Asked Questions
Is BeeBranch free?
Yes. The Product Hunt listing shows a price of 0 USD, and the product is released under the AGPL-3.0-only open-source license. There is no paid tier, no proprietary cloud, and no vendor account.
Is BeeBranch open source?
Yes — AGPL-3.0-only, hosted publicly at github.com/Methamorphe/beebranch. That license matters for commercial users: any modified version you distribute must share its source under the same license.
Does BeeBranch send any telemetry?
No. The project states "Zero telemetry, zero AI. The network is only used for Git, the GitLab/GitHub APIs and the update manifest." Updates are minisign-verified, and the previous version stays installable via rollback.json.
Can BeeBranch undo a reset --hard, a discard, or a push?
No — and it tells you so up front. Discard, reset --hard, stash drop/apply/pop, fetch, push, and submodule update never enter the undo stack; they are labelled irreversible. The stack only holds operations Git can truly invert: reset --soft/--mixed, read-tree, update-ref, switch, and stash/worktree/tag/remote refs.
Which operating systems does BeeBranch support?
At v1.5.0: macOS on Apple Silicon (signed, notarised .dmg), Windows x64 (NSIS .exe), and Linux (.AppImage, .deb, .rpm). macOS on Intel is not in the build matrix — build from source with Rust 1.85+ and Node 22+. Git 2.34 or newer is required on every platform.
