Open Source · CLI

workbranch

Task-based Git worktrees, made easy.

Create isolated task folders, keep base branches fresh, and move branch work from start to finish with commands you can remember.

Install workbranchGitHub

Install

Choose Homebrew for released builds, or run the install script directly.

HomebrewRecommended · installs published releases
$brew install tkhwang/tap/workbranch

How workbranch organizes your repos

Keep shared base worktrees in _base/, then create one folder per task with linked worktrees for each repo.

  • base main worktree

    Shared base checkout for each repo, usually tracking main.

  • task linked worktree

    Per-task linked checkout for each repo and task branch.

repo layout
my-project/├─ _base/│  ├─ frontend    main│  └─ backend     main│├─ feat-login/│  ├─ frontend    feat/login│  └─ backend     feat/login│└─ fix-api/   ├─ frontend    fix/api   └─ backend     fix/api

What workbranch does

Four small workflows for task workspaces, branch sync, combined flows, and local tools.

Workspace lifecycle

Set up the worktree environment.

  • workbranch init

    Create or clone the shared base worktrees from project config.

  • workbranch add

    Create one task folder with linked worktrees for every configured repo.

  • workbranch remove

    Remove a task workspace, its worktrees, and local task branches.

Each task becomes a small mono-repo workspace, so an AI agent can use frontend and backend in the same session.

Branch workflow

Pull fresh base branches, update task branches, push work, and land finished changes without memorizing worktree plumbing.

  • workbranch push

    Push base branches or a specific task branch to origin.

  • workbranch pull

    Pull remote base branches into the local _base repos.

  • workbranch update

    Merge local base changes into one task workspace or every task workspace.

  • workbranch land

    Fast-forward finished task work back into local base branches.

Combined flow

Run the common multi-step flows — refresh, finalize, prune — with one command.

  • workbranch refresh

    Pull base branches, then update every task workspace.

  • workbranch refresh <task>

    Pull base branches, then update one task workspace.

  • workbranch finalize <task>

    Pull base branches, update one task, then land it into local base branches.

  • workbranch prune

    Remove clean task workspaces already merged into local base branches.

Tool commands

Open the whole task workspace in your editor or terminal without finding each repo by hand.

  • workbranch ide <task>

    Open the task repo worktrees in the configured IDE.

  • workbranch terminal <task>

    Open the task repo worktrees in the configured terminal.