Skip to main content
Run plannotator review inside an active GitButler workspace. Plannotator detects GitButler and opens the Workspace view, which shows all applied committed work, working-tree changes, and untracked files.
Plannotator GitButler Workspace view showing all applied committed and working-tree changes in the file tree and diff.
Plannotator reviews local GitButler state. It does not use GitButler’s older cloud Butler Review feature, which GitButler says is currently paused.

​
Requirements and automatic detection

Use Plannotator v0.24.0 or newer and put the GitButler but CLI v0.21.0 or newer on PATH. GitButler documents the CLI as its terminal interface for managing, inspecting, and diffing branches in the GitButler CLI overview. Plannotator selects GitButler only when both checks pass:
  1. Symbolic HEAD is refs/heads/gitbutler/workspace. Plannotator also accepts the legacy refs/heads/gitbutler/integration ref.
  2. The repository has a local gitbutler.project.targetref value that starts with refs/.
The reserved branch name alone is not enough. A stale GitButler database does not trigger detection by itself. Neither does a normal branch merely named gitbutler/workspace without the local target-ref configuration. GitButler explains why its client maintains the synthetic workspace commit in Workspace Branch. If Plannotator detects the workspace ref and target configuration but cannot use but, it stops with a clear error. It does not fall back to a plain Git diff of GitButler’s synthetic workspace commit.

​
Choose Workspace, Stack, or Branch

Open the comparison picker to move between the GitButler views available for the current workspace.
Plannotator comparison picker listing Workspace, Stack, and Branch views for an active GitButler workspace.
GitButler defines stacked branches as dependent branches that build on the branches below them. See Stacked Branches for GitButler’s branch model. Assigned but uncommitted changes appear only in Workspace. GitButler does not expose one authoritative combined patch for a stack plus those assigned changes, so Plannotator does not guess.

​
Know the limits of GitButler sessions

GitButler assignments are not the Git index. Plannotator therefore hides stage and unstage controls, Git-status sections, and the commits panel in GitButler sessions. Committed Stack and Branch views describe Git objects that may not match the live working tree. Other stacks or later layers can be applied at the same time. In these two views, Plannotator disables:
  • Opening a file in an editor or another app
  • Code navigation
  • Semantic diff
  • VS Code annotations
When you expand a file, Plannotator still reads it from the exact committed comparison, not from the live workspace. When you start a multi-repository review from a parent folder, a GitButler child repository participates only in the aggregate Current changes view. Staged, unstaged, and last-change aggregate modes are unavailable when a GitButler child is present.

​
Force GitButler or plain Git

Force the GitButler provider when automatic detection is unavailable or when you want a clear setup error:
Force the plain Git provider when you intentionally want Git’s view of the repository:
Plain Git can expose the synthetic workspace commit and union index that GitButler maintains. Use the Git escape hatch only when that is the comparison you want.

​
Keep annotations tied to the right comparison

Each annotation records the GitButler view, label, merge base, and exact diff snapshot that supplied its line numbers. If you annotate a branch, switch to another view, and then send feedback, Plannotator labels the annotation with the branch comparison where you made it.
GitButler Branch view selector with an annotation badge on token.ts in the Plannotator file tree.
Ask AI and launched agent reviews receive the comparison currently open in Plannotator. For committed Stack and Branch views, the prompt includes the displayed patch and tells the agent to treat it as authoritative. Ordinary filesystem reads or git diff can include other applied stacks or later branch layers. See Run agent reviews for the read-only agent workflow.

​
Troubleshoot GitButler review

​
but is missing

Plannotator reports:
Install GitButler’s CLI, or expose the but command installed with GitButler Desktop, then confirm it is available in the same shell:

​
but is too old

For an installed v0.20.0 CLI, Plannotator reports:
Update GitButler until but --version reports v0.21.0 or newer. A prerelease such as 0.21.0-beta.1 does not satisfy the minimum.

​
Automatic detection does not trigger

Check the two values Plannotator uses:
The first command should print the GitButler workspace ref. The second should print a configured ref such as refs/remotes/origin/main. If either is absent, return to an active GitButler workspace or use plannotator review --gitbutler to get the direct provider error.

​
Assigned changes are absent from Stack or Branch

This is expected. Select Workspace to review assigned or unassigned working-tree changes and untracked files. Stack and Branch remain committed-only. GitButler support shipped in Plannotator OSS v0.24.0 through PR #1067. This page was verified against v0.24.2 on July 22, 2026; v0.24.2 was published on July 21, 2026. Maintained by the Plannotator project.
Last modified on July 22, 2026