Skip to content
30 changes: 30 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,36 @@

All notable changes to the Git Integration plugin are documented in this file. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## 0.2.1

### Added

- **Branch management from the panel.** A **Branches** section in the panel shows the branch the project is on — with its upstream and how far it has drifted from it (`↑2 ↓1`) — and lists the local branches together with the remote ones Git already knows about. The branches arrive together with the file lists in one background pass, so the list is always the one the repository actually has. Typing in the filter box narrows the list down; the filter only changes what is shown and runs no command.
- **Switching branches.** Clicking a branch selects it — the selected branch is marked with an arrow — and the actions below the list apply to it. **Checkout** switches to it with `git checkout`. The switch runs on a worker thread, so the panel stays responsive even in a large repository.
- **Creating a branch from the panel.** A row at the bottom of the section takes a new branch name and creates it from the current `HEAD`, then switches to it. The name is checked with `git check-ref-format --branch` before it is used, so Git itself decides what a valid branch name is, and a name starting with `-` is refused before it can reach a command line.
- **Deleting a branch.** **Delete** removes the selected branch and lets git refuse a branch whose commits were never merged. **Force delete** removes it anyway, and git's reflog still keeps those commits.
- **Renaming a branch.** **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.
- **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. The log is fetched in the background, so a branch with a long history does not stall the frame.
- **A failure dialog that points at the Console.** A failed branch operation opens a modal with one sentence about what went wrong, a note that the full message was written to the Console, and three buttons: *Open Console*, *Copy details*, and *Close*. The common Git 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, and a branch that another worktree holds.

### Changed

- **Every git command now runs on a worker thread.** Status collection, staging, unstaging, committing, `git init`, the branch listing, the branch log, and the checkout itself all happen off the render thread, which only draws the last snapshot it received. A large repository no longer stalls the Editor, and a checkout that takes a while no longer freezes the frame.
- **The status comes from `git status --porcelain=v2 -z --branch`.** One call now returns the branch name, the upstream, the ahead/behind counters, and the file list, instead of the file list alone. The `-z` form keeps a path that is not plain ASCII literal, where the older format quoted it as an octal escape.
- **Git output is decoded as UTF-8 on purpose.** The panel no longer depends on the console code page of the machine it runs on, so Chinese commit messages and Chinese file names survive on a Windows that is not running in UTF-8.
- Every call to `git` now lives in the new `package/editor/wokrlie/git_integration/git.py` module, so the panel no longer talks to `subprocess` itself. That module never touches the Engine API, which is what makes it safe to call from a worker thread.
- **The panel runs no git command on the render thread 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.

### Fixed

- **The panel reported Git failures as Python tracebacks instead of the real error.** Every failure path called `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. The errors are now written with `Debug.log_error(...)` and tagged with the plugin's source, so the Console can group and clear them. The entry quotes the command line, the exit code, and Git's own message, so the failure can be reproduced by hand.
- **Unstaging a file raised `TypeError: 'function' object is not subscriptable`.** The action passed a function where the command factory expects the argument list of a git command, and the factory reads the first argument to name the worker thread, so the file was never unstaged. `git reset HEAD -- <path>` unstages it 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.
- **Non-ASCII file names were shown as octal escapes.** The old parser read the v1 porcelain format, in which Git quotes a path that is not plain ASCII, so a file called `文档/说明.md` appeared as `"\346\226\207..."`. The panel now reads the `-z` format, where the path is written literally.

### 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; any current distribution is well past them.

## 0.1.5

### Added
Expand Down
30 changes: 30 additions & 0 deletions CHANGELOG.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,36 @@

Git 集成插件的所有重要变更都记录在本文件中。格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/),版本号遵循[语义化版本](https://semver.org/lang/zh-CN/)。

## 0.2.1

### 新增

- **在面板里管理分支。** 面板的**分支**分组显示项目当前所在的分支——连同它的上游和与上游的偏差(`↑2 ↓1`)——并列出本地分支和 Git 已知的远端分支。分支和文件列表在同一次后台任务里一起取回来,所以列表始终和仓库实际情况一致。在过滤框里输入内容可以缩小列表范围;过滤只是改变显示内容,不会执行任何命令。
- **切换分支。** 点击某个分支会选中它——选中的分支前面有一个箭头标记——下方的操作都作用于它。**切换**用 `git checkout` 切过去。切换在工作线程上执行,即使在大仓库里面板也不会卡住。
- **在面板里新建分支。** 分组底部有一行输入框,填入新分支名即可从当前 `HEAD` 创建并切换过去。分支名在使用前会先交给 `git check-ref-format --branch` 校验,由 Git 自己决定什么才是合法分支名;以 `-` 开头的名字在进入命令行之前就会被拒绝。
- **删除分支。** **删除**会移除选中的分支,并让 git 拒绝删除还有未合并提交的分支。**强制删除**则照样删掉,那些提交仍留在 git 的 reflog 里。
- **重命名分支。** **重命名**会展开一个输入框让你填新名字。新名字会先经过 `git check-ref-format --branch` 校验,git 不接受的名字根本不会进入命令。
- **分支的提交日志。** **分支日志**分组按时间倒序列出所选分支最近 50 个提交,每条带短哈希和提交信息。日志在后台获取,历史再长的分支也不会卡住那一帧。
- **指向 Console 的失败弹窗。** 分支操作失败时会弹出模态框,用一句话说明出了什么问题,并提示完整信息已写入 Console,同时提供「打开 Console」「复制详情」「关闭」三个按钮。常见的 Git 失败各有对应的说法——切换会覆盖本地修改、分支已不存在、名字不合法、同名分支已存在、分支被另一个 worktree 占用。

### 变更

- **所有 Git 命令都改到后台线程执行。** 状态采集、暂存、取消暂存、提交、`git init`、分支列举、分支日志以及切换本身都在渲染线程之外完成,渲染线程只画它收到的上一份快照。大仓库不再拖慢编辑器,切换耗时较久时也不会卡住那一帧。
- **状态改用 `git status --porcelain=v2 -z --branch` 采集。** 一次调用就能同时拿到分支名、上游、领先/落后计数和文件列表,而不再只有文件列表。`-z` 形式让非 ASCII 路径保持字面量,旧格式则会把它写成八进制转义。
- **Git 输出显式按 UTF-8 解码。** 面板不再依赖运行机器的代码页,中文提交信息和中文文件名在非 UTF-8 的 Windows 上也能正确显示。
- 所有 `git` 调用都集中到了新增的 `package/editor/wokrlie/git_integration/git.py` 模块,面板不再直接调用 `subprocess`。该模块不触碰任何引擎 API,这正是它能在工作线程里安全运行的前提。
- **面板在渲染线程上一个 Git 命令都不跑了。** git 到底能不能用,改由状态命令的退出码回答,不再单独探一次 `git --version`;分支名的校验也挪到了工作线程上,而不是在绘制这一帧时顺手做掉。

### 修复

- **面板把 Git 失败报成了 Python 堆栈,而不是真正的错误。** 所有失败分支都调用了 `Debug.error(...)`,但引擎没有这个 API——引擎提供的是 `Debug.log_error`。调用在错误信息写入前就抛了 `AttributeError`,所以提交、暂存、`git init` 失败的真实原因从来没进过 Console。现在改用 `Debug.log_error(...)` 写入,并带上插件来源标记,Console 里可以按来源分组和清除。条目里会写明完整命令行、退出码和 Git 自己的报错,可以照着手动复现。
- **取消暂存文件时抛 `TypeError: 'function' object is not subscriptable`。** 那个操作把函数传给了本该接收命令参数列表的工厂,而工厂要读第一个参数来给工作线程命名,于是文件根本没被取消暂存。`git reset HEAD -- <path>` 一条命令就够:仓库还没有提交时 git 会退回空树,文件回到未跟踪状态。
- **非 ASCII 文件名显示成了八进制转义。** 旧解析器读的是 v1 porcelain 格式,Git 在该格式里会给非纯 ASCII 路径加引号并转义,于是 `文档/说明.md` 显示为 `"\346\226\207..."`。现在改读 `-z` 格式,路径是字面量。

### 环境要求

- **需要 Git 2.13 或更新版本。** `git status --porcelain=v2` 需要 Git 2.11,`git for-each-ref` 的 `%(upstream:short)` 字段需要 Git 2.13。两者分别来自 2016 年和 2017 年,当前任何发行版都已远超。

## 0.1.5

### 新增
Expand Down
2 changes: 2 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,9 @@ python package.py build dist/plugin.inxpkg && python package.py verify dist/plug
## Code conventions

- The Editor half of the plugin lives in `package/editor/`, the player-facing half in `package/runtime/`. Runtime code must not import Editor modules; the validator enforces that boundary.
- Every `git` call lives in `package/editor/wokrlie/git_integration/git.py`. The panel must not run a git command itself — that module is the only place that knows how git is invoked, how its output is decoded, and how its output is parsed.
- Every `git` call must pass `cwd=` explicitly so the panel always operates on the folder open in the Editor.
- Git commands run on a worker thread, never on the render thread. `GitCommand` in `git.py` starts one and the render thread only polls it for the result. A module in `git.py` must never touch the Engine API, because it also runs off the render thread.
- Use `subprocess.run` with a timeout. The render thread must never block indefinitely.
- Panel state that survives a render lives on the instance; it is never stored in a module-level global.

Expand Down
5 changes: 4 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,16 +18,19 @@ A source control panel for the [Infernux Engine](https://github.com/ChenlizheMe/
- Vector icons for the stage, unstage, stage-all, and refresh controls, plus a status icon and a coloured status code on every file row.
- Localized panel UI in English and Simplified Chinese.
- The plugin's own licence and the notices for the bundled icon artwork ship with the plugin and are shown on the **License** page of the plugin information.
- Branch management from the panel: a **Branches** section shows the current branch with its upstream, lists the local and remote branches, and switches, creates, renames, and deletes them. The selected branch also shows its commit log. Failures are reported in the Console.

## Requirements

| Requirement | Version |
| --- | --- |
| Infernux Engine | `>=0.4.1,<0.5` |
| Git | A recent version available on your `PATH` |
| Git | `>=2.13` available on your `PATH` |

Git is a **runtime requirement**. The panel shells out to the `git` executable; when it is missing, the panel shows a short notice instead of the file lists.

Git 2.13 is the floor because the panel reads `git status --porcelain=v2` (needs 2.11) and the `%(upstream:short)` field of `git for-each-ref` (needs 2.13). Both are from 2016 and 2017, so any current distribution is well past them.

The icons are vector artwork that the Editor rasterizes at runtime. That relies on the Engine's LunaSVG-backed texture loader, which is not part of the documented plugin API — if a future Engine release drops it, the panel falls back to text-only controls and everything else keeps working.

## Installation
Expand Down
5 changes: 4 additions & 1 deletion README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,16 +18,19 @@
- 暂存、取消暂存、暂存全部和刷新按钮使用矢量图标;每个文件行还带有状态图标和带颜色的状态码。
- 面板界面支持英文与简体中文。
- 插件自身的许可证和内置图标素材的第三方声明随插件一起分发,可在插件信息的**许可证**页面查看。
- 在面板里管理分支:**分支**分组显示当前分支和它的上游,列出本地与远端分支,可以切换、新建、重命名和删除它们;选中分支还能查看它的提交日志。失败信息会写进 Console。

## 环境要求

| 依赖 | 版本 |
| --- | --- |
| Infernux 引擎 | `>=0.4.1,<0.5` |
| Git | `PATH` 中可用的较新版本 |
| Git | `PATH` 中可用的 `>=2.13` 版本 |

Git 是**运行时依赖**。面板通过 `git` 可执行文件完成所有操作;Git 缺失时,面板会显示一条简短提示而不是文件列表。

之所以要求 Git 2.13,是因为面板要读 `git status --porcelain=v2`(需要 2.11)以及 `git for-each-ref` 的 `%(upstream:short)` 字段(需要 2.13)。两者分别来自 2016 年和 2017 年,当前任何发行版都已远超。

## 安装

### 从发布页安装
Expand Down
8 changes: 4 additions & 4 deletions RELEASING.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Releases are produced by GitHub Actions. No artifact is uploaded by hand.
| Engine compatibility | `package/inx_package.json` → `engine` |
| Release notes | `CHANGELOG.md` and `CHANGELOG.zh-CN.md` |

The release tag must match the manifest version exactly — `v0.1.5` for version `0.1.5`. `package.py release-manifest` fails on any mismatch, so a mistyped tag stops the release instead of publishing a mislabelled archive.
The release tag must match the manifest version exactly — `v0.2.1` for version `0.2.1`. `package.py release-manifest` fails on any mismatch, so a mistyped tag stops the release instead of publishing a mislabelled archive.

## Procedure

Expand All @@ -19,8 +19,8 @@ The release tag must match the manifest version exactly — `v0.1.5` for version
3. Tag the merge commit and push the tag:

```bash
git tag v0.1.5
git push origin v0.1.5
git tag v0.2.1
git push origin v0.2.1
```

4. The `release` job runs on the tag. It builds the archive, verifies it, checks that two independent builds are byte-identical, generates `infernux-plugin-release.json`, and publishes both files as GitHub Release assets.
Expand All @@ -44,7 +44,7 @@ Because of this, a fix for a published version needs a **new** version number. N
python package.py build dist/wokrlie.git_integration.inxpkg
python package.py verify dist/wokrlie.git_integration.inxpkg
python package.py release-manifest dist/wokrlie.git_integration.inxpkg \
--tag v0.1.5 --output dist/infernux-plugin-release.json
--tag v0.2.1 --output dist/infernux-plugin-release.json
```

The build is deterministic: running it twice over the same source must produce byte-identical archives, which is what CI asserts before it publishes anything.
5 changes: 2 additions & 3 deletions ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,13 @@ Planned work for the Git Integration plugin. Delivered changes are recorded in [

## Next

- **Branch display and switching** — show the current branch, and let the user switch or create branches from the panel.
- **Discard changes** — revert the unstaged modifications of a single file.
- **Push / Pull controls** — fetch, pull, and push without leaving the Editor.
- **Diff preview** — show the content diff of a tracked file.
- **Asynchronous `git status`** — move status collection off the render thread so large repositories do not stall the Editor.
- **Migrate the Git worker to an editor preload** — the panel starts daemon threads today, and the Engine cannot stop those deterministically. The plugin authoring guide recommends that long-lived background work lives in `editor/` and is owned by an `InxPreload`, with a registered cleanup that stops the worker and joins it within a bound; it shows that shape with a Flask service bound to loopback on an operating-system allocated port, with the development reloader disabled. The HTTP service itself is only worth building if something outside the Editor has to drive Git — the panel should keep talking to its worker in process.

## Notes

Every item above has to keep the render thread responsive. The panel currently shells out to `git` synchronously during rendering, with a one-second throttle between refreshes. Asynchronous status collection is listed last because it is the change that makes the rest cheap to add: once status collection no longer blocks the frame, per-file operations can follow the same pattern.
Every item above has to keep the render thread responsive. Since 0.2.1 the panel runs every git command on a worker thread and draws the last snapshot it received, so the per-file operations follow the same pattern instead of blocking the frame. The status refresh is still throttled to one call per second, because a snapshot that is one second old is already too old to act on.

Adding an item to this file is welcome — open a pull request that describes the user problem it solves, not just the API it would use.
Loading
Loading