Skip to content

feat: manage branches from the panel - #5

Merged
Wokrlie merged 10 commits into
mainfrom
feat/branch-switch
Nov 15, 2026
Merged

Wokrlie merged 10 commits into
mainfrom
feat/branch-switch

Conversation

@Wokrlie

@Wokrlie Wokrlie commented Nov 8, 2026

Copy link
Copy Markdown
Owner

Summary

The panel now manages branches without leaving the Editor. A Branches section shows the branch the project is on with its upstream and how far it has drifted, and lists the local and the remote branches Git already knows about. Filtering the list runs no command; picking a branch marks it as the target of the actions below the list — Checkout, Rename, Delete, and Force delete — and a row at the bottom creates a branch from the current HEAD. The selected branch also shows its commit log.

Every git command moved to a worker thread, the status format changed to porcelain v2, unstaging works again, and the Console became the one place where a failure survives.

This release also carries the Console error-reporting fix that was planned as a separate patch release. A bugfix on its own is a hotfix, so both land together as 0.2.1.

  • Base: main (ef823b5, already contains v0.1.5)
  • Head: feat/branch-switch (42529e3)
  • Commits: 10
  • Diffstat: 21 files changed, 2274 insertions(+), 234 deletions(-)

What's changed

Branch management in the panel

  • The Branches section sits above the file lists: the branch the project is on, the list of local and remote branches with a filter, the actions, the log of the selected branch, and the row that creates a new one. The section opens the first time the panel is shown and can be folded away like the file lists.
  • A detached HEAD is shown in orange with the short sha in the tooltip, so it is obvious that the repository is not on a branch. A repository without any commit still shows its branch name.
  • The branches arrive together with the file lists in one background pass, so the list is always the one the repository actually has — no second process, no second chance of showing a stale list.
  • Clicking a branch selects it; the selected branch is marked with an arrow and the current one with a dot. The actions below the list apply to the selection, and Checkout switches to it. The branch the project is on cannot be deleted, so the actions need a target of their own.
  • Rename opens a field for the new name. The name is checked with git check-ref-format --branch first, so a name Git would refuse never reaches the command, and the selection follows the branch to its new name.
  • Delete lets Git refuse a branch whose commits were never merged. Force delete removes it anyway, and the commits stay in Git's reflog.
  • Typing in the filter box narrows the list down. The filter only changes what is shown; it runs no command.
  • The last row creates a branch from the current HEAD and switches to it.

The commit log of a branch

  • The Branch log section lists the last 50 commits of the selected branch, newest first, each with its short hash and its subject.
  • It is fetched on a worker thread, so a branch with a long history does not stall the frame, and it is fetched again after a commit, so the commit you just made shows up right away.

Every git command moved off the render thread

  • All of it — status, staging, unstaging, committing, git init, the branch listing, the branch log, and the checkout — now runs on a worker thread. The render thread only draws the last snapshot it received, so a large repository no longer stalls the Editor and a slow checkout no longer freezes a frame.
  • The render thread runs no git command at all: whether Git is usable is answered by the exit code of the status command instead of a separate git --version probe, and a branch name is validated on the worker thread instead of while the frame is being drawn.
  • The commands live in a new package/editor/wokrlie/git_integration/git.py. That module never touches the Engine API, which is what makes it safe to call from a worker thread.
  • Every background action takes a callable, so a command and a function can never be confused for one another again.

Unstaging works again

  • The unstage action passed a function where the command factory expects the argument list of a git command. The factory reads the first argument to name the worker thread, so the call raised TypeError: 'function' object is not subscriptable and the file was never unstaged.
  • git reset HEAD -- <path> unstages the file on its own, and it also works in a repository that has no commit yet: git falls back to the empty tree and the file returns to being untracked. The two-step fallback that was there for that case is not needed.
  • A contract test now checks the shape of every background action, so this cannot slip through a review again.

The status format changed

  • git status --porcelain=v2 -z --branch replaces the v1 porcelain format. One call returns the branch name, the upstream, the ahead/behind counters, and the file list together.
  • -z keeps a path that is not plain ASCII literal. The v1 format quoted it as an octal escape, so a file called 文档/说明.md appeared as "\346\226\207..." — that is fixed.
  • Git output is decoded as UTF-8 explicitly, so the panel no longer depends on the console code page of the machine it runs on.

A failure dialog that points at the Console

  • The Console stays the one place where an error survives: the full Git message is written there with Debug.log_error(...) and tagged with the plugin's source, so the Engine can group and clear the plugin's entries on their own. The entry quotes the command line, the exit code, and Git's own message, so the failure can be reproduced by hand.
  • The dialog only points the way. It states what went wrong in one sentence, says that the full message was written to the Console, and offers Open Console, Copy details, and Close. The common failures each get their own sentence — local changes that the switch would overwrite, a branch that no longer exists, an invalid name, a name that is already taken, a branch that another worktree holds, and a branch with commits that were never merged.

The Console reporting fix that came with it

  • Every failure path used to call Debug.error(...), which is not an Engine API — the Engine provides Debug.log_error. The call raised AttributeError before the Git message could be logged, so the reason a commit, a stage, or git init failed never reached the Console. That has been true since the first implementation (v0.1.3, commit 72c2527).
  • tests/test_engine_api_usage.py scans the plugin sources and fails on any Debug.* or ctx.* method the Engine does not provide. Debug.error looks perfectly reasonable in a review, and no human reliably catches that; the test does.

Root cause of the reporting bug

The Engine's Debug class exposes log, log_warning, log_error, log_exception, log_suppressed, log_assert, clear_console, log_internal, log_debug and the report_* family. There is no error, and the module-level aliases are only log, log_warning, log_error and log_exception.

icons.py used the correct Debug.log_suppressed(...) throughout, which is why only the panel's error paths were affected.

Requirements

Git 2.13 or newer. git status --porcelain=v2 needs Git 2.11, and the %(upstream:short) field of git for-each-ref needs Git 2.13. Both are from 2016 and 2017.

Commits

  • d133d41 — fix: report Git failures in the Console instead of raising AttributeError
  • 40d6a4b — feat: switch and create branches from the panel
  • 2757bef — docs: describe the branch workflow and the version the panel needs
  • 147eaab — chore: prepare the 0.2.0 release
  • ef1d751 — fix: unstage a file with one git command
  • 1f0ed15 — feat: move the branches into their own section
  • ee69216 — feat: delete and rename branches from the panel
  • e9f9fa0 — feat: show the commit log of the selected branch
  • b33d6d9 — chore: fold the development versions back into 0.2.0
  • 42529e3 — chore: raise the release version to 0.2.1

The middle commits are the development steps towards this release: the branch list moved into its own section, the select-and-act model replaced switch-on-click, rename and delete arrived, and the branch log came last. b33d6d9 folds them back into a single version and a single changelog section, so nothing from that work has to ship as a separate patch release; it also drops two context methods from the contract test's allowlist that the Engine no longer declares, so a call to a method that does not exist cannot slip past the test. 42529e3 raises the version to 0.2.1, because the Engine only accepts a package whose version is higher than the one already installed.

…rror

Every failure path called Debug.error(...), which is not an Engine API.
The Engine exposes Debug.log_error, so each call raised AttributeError
before the Git message could be logged, and the real reason a commit, a
stage, or git init failed never reached the Console.

The errors now go through Debug.log_error(...) and carry the plugin's
source, so the Console can group and clear them. A contract test scans
the plugin sources and fails on any Engine method that does not exist.
The header now shows the current branch, its upstream, and how far the
branch has drifted from it. Clicking it opens a picker that lists the
local and the remote branches, filters as you type, and switches with
`git checkout`. The last row creates a branch from the current HEAD.

Every git command now runs on a worker thread and lives in a new `git.py`
module, so the render thread only draws the last snapshot it received.
The status comes from `git status --porcelain=v2 -z --branch`, which
returns the branch state together with the file list and keeps a path
that is not plain ASCII literal instead of quoting it as an octal escape.

A failed branch operation opens a modal that states what went wrong in
one sentence and points at the Console, which keeps the full Git message.
The branch name is validated with `git check-ref-format --branch` before
it is used.
The usage pages gain a "Switching branches" section in both languages,
and the licence page now names the three icons that come from Feather
rather than counting them.

The README states the Git version the panel needs and why, the roadmap
moves the finished branch and asynchronous status items out of "Next",
and the contributing guide records that every git call belongs in
`git.py` and runs on a worker thread.
The Console error reporting fix ships with the branch workflow instead
of as a separate patch release, so the version moves to 0.2.0 and the
changelog replaces the 0.1.6 section with one that covers both.
The unstage action passed a function where the command factory expects
the argument list of a git command. The factory reads the first
argument to name the worker thread, so the call raised
`TypeError: 'function' object is not subscriptable` and the file was
never unstaged.

`git reset HEAD -- <path>` unstages the file on its own, and it also
works in a repository that has no commit yet: git falls back to the
empty tree and the file returns to being untracked. The two step
fallback that was there for that case is not needed.

A contract test now checks that every background action starts with an
argument tuple, so this shape cannot slip through a review again.
The branch list lived behind a popup that the branch name in the header
opened. It is now a Branches section in the panel, above the file lists:
the branch the project is on, the list of local and remote branches with
a filter, and the row that creates a new one. The section opens the
first time the panel is shown and folds away like the file lists.

The branch list no longer needs a process of its own. The background
status pass collects the branches together with the file lists now, so
the list is always the one the repository actually has.
Pick a branch in the list and the actions below it apply to that branch:
Checkout switches to it, Rename gives it a new name, and Delete removes
it. The plain Delete lets git refuse a branch whose commits were never
merged; Force delete removes it anyway.

The list selects instead of switching now. The branch the project is on
cannot be deleted, so the actions need a target of their own.

Every background action now takes a job — a callable that runs the
command on the worker thread — instead of an argument list. The name a
new branch is created with is checked on the worker thread too, so the
render thread no longer spawns a process: creating a branch used to run
`git check-ref-format` while the frame was being drawn, and the panel
used to probe `git --version` when it opened. Whether git is usable at
all is now answered by the exit code of the status command.
The Branches section now lists the commits of the selected branch, newest first, with the short hash and the subject of each one. The log is fetched on a worker thread, so a branch with a long history does not stall the frame.

Fixes along the way: an empty log no longer starts a git process on every frame, the entries of the previously selected branch are dropped when the selection changes, the log is fetched again after a commit, and the selection follows a branch that was renamed or forgets one that was deleted.
The 0.2.0.1, 0.2.0.2, and 0.2.0.3 builds were stepping stones towards this release. The manifest goes back to 0.2.0 and the changelog becomes a single 0.2.0 section that describes the panel as it ships.

The Engine API allowlist in the contract test was checked against the upstream master branch: input_uint and push_id_str are gone upstream, so they were dropped rather than left to let a call to a method that does not exist pass.
The Engine only accepts a plugin package whose version is higher than the one already installed, and a 0.2.0 build was installed locally before the branch work was finished. The release therefore moves to 0.2.1, and the changelog heading follows it.
@Wokrlie
Wokrlie merged commit 2142e13 into main Nov 15, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant