PM: merge M4.9 git stash
Some checks are pending
ci / ci (macos-15) (push) Waiting to run
ci / ci (ubuntu-24.04) (push) Waiting to run
ci / ci (windows-2025) (push) Waiting to run

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
danny 2026-10-30 17:59:54 +01:00
commit dc4a00ea0b
23 changed files with 2681 additions and 13 deletions

View file

@ -1,6 +1,6 @@
# Architecture
> **Status:** M0 decisions recorded, M1 workspace, desktop bridge, tabs and editor, message catalog, engine construction, settings, themes, the recovery journal, notifications, UI commands, the palette, the settings dialog, the app icon and the syntax layer documented; M2 highlighting and `editor.reveal`, plus the search backend, the Find tool window, the symbol index, the Structure tool window and the go-to popup; M3 CLI and single instance, LSP client library, toolchain (PHP detection, Phpactor download), the app menu, MCP server, autosave and `flushDirty`, integrated terminal; engine ↔ Phpactor wiring and diagnostics (M3.3), pending outcomes (M3.5), completion, hover and signature help (M3.4); C5 child process groups (H1), settings dialog string and path controls and assist settings (H4), the banner-aligned themes and diagnostic/VCS tokens (H5), Phpactor UX: fast tick, messages, progress, `php -l` (H3); Git backend (M4.1), Changes tool window (M4.2); line changes, gutter markers and status colours (M4.4), diff viewer (M4.3), branches (M4.5); remotes: fetch, pull, push, clone and remote management (M4.10) · **Last updated:** 2026-10-28
> **Status:** M0 decisions recorded, M1 workspace, desktop bridge, tabs and editor, message catalog, engine construction, settings, themes, the recovery journal, notifications, UI commands, the palette, the settings dialog, the app icon and the syntax layer documented; M2 highlighting and `editor.reveal`, plus the search backend, the Find tool window, the symbol index, the Structure tool window and the go-to popup; M3 CLI and single instance, LSP client library, toolchain (PHP detection, Phpactor download), the app menu, MCP server, autosave and `flushDirty`, integrated terminal; engine ↔ Phpactor wiring and diagnostics (M3.3), pending outcomes (M3.5), completion, hover and signature help (M3.4); C5 child process groups (H1), settings dialog string and path controls and assist settings (H4), the banner-aligned themes and diagnostic/VCS tokens (H5), Phpactor UX: fast tick, messages, progress, `php -l` (H3); Git backend (M4.1), Changes tool window (M4.2); line changes, gutter markers and status colours (M4.4), diff viewer (M4.3), branches (M4.5); remotes: fetch, pull, push, clone and remote management (M4.10); stash (M4.9) · **Last updated:** 2026-10-28
## Overview
@ -707,10 +707,32 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
- **Not yet:** an "ignore" action, a compare menu, reverting a resolution, prefilling the commit message from `MERGE_MSG`, rebase and cherry-pick conflicts, synchronised scrolling.
- **Tests:** `crates/vcs/tests/merge.rs` (5 against real temp repositories: clean merge, fast-forward, up to date, a content conflict with its versions, resolve and commit, add/add and modify/delete, abort, refusals); unit and property tests in `merge.rs`; `crates/engine/tests/git_merge.rs` (2: the command shapes, `gitChanged`, bad params, no project); Vitest `ui/tests/vcs/Merge.test.ts` (22: the merge on fixed and 300 random texts, layout, parsing, merging after `flushDirty`, the dialog's branches, list, resolve view, apply through the buffer, deleted and binary files, abort, the Changes entry point, registration).
### Stash (M4.9)
- **Backend** (`crates/vcs/src/stash.rs`, an append; `Repo::lock` became `pub(crate)`, as for M4.8): `stash`, `stash_list`, `stash_apply` and `stash_drop` on `Repo`, run through the M4.1 runner. The stash belongs to the repository, so `git stash push` takes every change of the work tree, also outside the project folder. Changes hold the repository's mutex; the entry is checked under it.
- **List:** `stash list --format=%x1e%H%x00%gs%x00%cI`, at most 1,000 entries; the position is the index. The reflog subject is split into the branch and the message (`On <branch>: <message>`, `WIP on <branch>: <hash> <subject>` for an entry without a message, flagged `wip`); another form keeps the whole subject.
- **Stash:** `stash push [--include-untracked] [--message=…]` with the 120 s timeout. The message loses control characters (line breaks become spaces) and is cut at 1,000 characters. Whether an entry was made is read from `refs/stash` before and after, not from git's text (git exits 0 with "No local changes to save").
- **`--literal-pathspecs` workaround:** every call runs with it, and under it git's `stash push --include-untracked` stores the untracked files but leaves them in the work tree (its internal clean uses a magic pathspec; found by the integration test, reproduced with git 2.47.1 by hand). So after such a stash the files listed in `stash@{0}^3` go through `git clean -f -- <paths>` (it removes untracked files only; arguments in chunks of 16 KiB, as `clean` has no `--pathspec-from-file`), and folders left empty are removed.
- **Apply, pop, drop:** `stash apply|pop|drop --quiet stash@{n}` with the 120 s timeout for apply and pop. An optional `hash` (as listed) must match the entry at `index`, so a stash changed in between (another tool, another window) is refused instead of applying the wrong entry.
- **Refusals** (`VcsError::Git`, so `failed` with the text): a sentence that says what to do, then git's own message where there is one. Decided structurally, so they hold whatever language git speaks: no commit yet (`HEAD^{commit}`), nothing to stash (`refs/stash` did not move; without `includeUntracked` the text adds that untracked files need it), unmerged files before stash or apply (`ls-files --unmerged`), a missing entry (the list's length), a changed entry (the hash), conflicts after a failed apply or pop (unmerged entries now exist: "applied with conflicts in N files … the stash entry was kept"). Two hints read git's English text and fall back to git's message alone: local changes that would be overwritten, untracked files already in the work tree.
- **Commands** (`crates/engine/src/cmd/git_stash.rs`, through M4.6's `start_with` hook; pending outcomes; `gitChanged` after stash, apply and drop):
- `git.stash {message?, includeUntracked?}` → `{entry: {index, hash, branch, message, wip, date}}`.
- `git.stashList` → `{stashes: [{index, hash, branch|null, message, wip, date}]}` newest first.
- `git.stashApply {index, pop?, hash?}` → `{}`; `git.stashDrop {index, hash?}` → `{}`.
- The result shapes and the optional `hash` are additions to the C6 contract, which named the params only. A bad hash or an index over 100,000 is `invalid_params`.
- A conflicted apply is `failed` but changed the work tree; the `.git` watch reports it as `gitChanged` within about 300 ms. `refs/stash` is not watched, so a stash made outside Lutra shows the next time the list is read.
- **UI** (`ui/src/components/vcs/stash/`): `stash.ts` is the Pinia store, `StashDialog.vue` the dialog, mounted once in `MainLayout.vue`. It supplies the UI commands `vcs.stash` (Git › Stash Changes…) and `vcs.showStashes` (Git › Stashes…), enabled with `git.stash` (an open project), without default shortcuts. The Changes window's bar has a button for each, next to refresh.
- **Form:** message (optional), "Include untracked files" (kept between uses), a note that every change of the repository is set aside. Enter or Stash runs `flushDirty()` first, so git stashes what the editor shows and the reset files reload instead of keeping unsaved edits on top; a failed save does nothing and says so. A refusal shows under the form (`role="alert"`) and the dialog stays; success closes it with an info toast.
- **List:** read with `git.stashList` each time it shows and after every change; rows show `stash@{n}`, the message ("WIP: …" for an entry without one), the branch and the local date. Up/Down/Home/End move, Enter or Apply applies, Pop applies and drops, Delete or Drop asks inline ("Drop stash@{n}? It cannot be restored.") before `git.stashDrop`. Apply and pop save dirty buffers first. Every call passes the listed hash. Refusals (conflicts, overwritten files) show under the list, which is read again.
- **Modal:** an exclusive modal (`ModalId` `stash`); Escape cancels a drop question first, then closes; the focus goes back where it was. The answer is untrusted: entries without an index or hash are dropped, at most 1,000.
- **Checked in the app** (debug build with the bundled UI, Windows 11, git 2.47.1, control port 7949, a demo repository with two stashes on two branches and a modified file; commands and screenshots only, no input): `git.stashList` 143–157 ms, `git.stash` 640 ms, a pop 366 ms, each including the control round trip. The refusals came back as written above: applying onto a modified file ("would be overwritten" with git's text), nothing to stash (with the untracked hint), a missing entry. Screenshots of the list (`stash@{n}`, WIP text, branch, date; Drop, Pop, Apply) and of the form, plus the two new buttons in the Changes bar, read in the dark theme.
- **Tests:** `crates/vcs/tests/stash.rs` (6 tests against real temp repositories: stash with and without a message, list order and hashes, apply, pop by an abbreviated hash, drop; untracked files only with the flag, including a nested folder and a name starting with `-`; no commit and nothing to stash; a missing and a changed entry, a bad hash; overwritten local changes and untracked files in the way, both leaving the work tree and the entry alone; a conflicted pop keeping the entry and blocking the next stash and apply); unit and property tests in `stash.rs` (list and subject parsing, message cleaning, unmerged counting, hints, chunking); `crates/engine/tests/git_stash.rs` (the command shapes, `gitChanged` only after changes, a changed hash, an empty stash, bad params); Vitest `ui/tests/vcs/Stash.test.ts` (13 tests: parsing, the form with `flushDirty` first, a blank message, a refusal, a failed save, Escape and focus, the list with keyboard and apply, a conflicted pop, the drop question, an empty stash, a failed read, the commands' registration, the Changes window's buttons).
## Decisions (M0)
| Question | Decision | Why |
|---|---|---|
| 2026-10-30 | minor | M4.9: stash backend (`git.stash`, `git.stashList`, `git.stashApply`, `git.stashDrop`), the `--literal-pathspecs` workaround for untracked files, the stash dialog |
| 2026-10-30 | minor | F2b: screenshot timeouts say whether the main thread was blocked or the page hidden; `--control` start can still take the foreground |
| Highlighting | A Lezer grammar (`@lezer/php`, MIT) in CodeMirror highlights instantly on the UI thread. tree-sitter in `crates/syntax` stays the structural source (outline, folding, index) and later adds semantic tokens on top. | The keystroke-to-highlight budget (< 16 ms) leaves no room for an IPC round trip per keystroke; Lezer is incremental inside CodeMirror. tree-sitter gives the core one parser for every structural feature. |
| Git library | `gix` (MIT OR Apache-2.0) for reading: status, log, diff, blame, refs. Writes the library doesn't cover well (push, pull, rebase, merge, hooks, signing) run the user's `git` executable. `git2`/libgit2 is not used. | gix is pure Rust and permissively licensed; libgit2 is GPL-2.0 with a linking exception, outside the permitted licences. Shelling out for writes keeps the user's hooks, credential helpers and config working. |