git-worktrees-4-idea

Imported from DevDengChao/git-worktrees-4-idea (AGENTS.md). Install upstream with npx skills add DevDengChao/git-worktrees-4-idea. Copyright stays with the author.

Project Notes for Agents

• Follow ~/AGENTS.md before working in this repository.
• Check for .mcp.json before starting; this repository currently has no project-level MCP config.
• For Git Worktrees panel selection changes, keep single-target data keys (CURRENT_REPOSITORY, SELECTED_WORKTREE) available only for exactly one selected row. Use SELECTED_WORKTREES when actions need to handle multiple selected worktree rows, and ignore repository header rows for bulk operations.
• For Git Worktrees panel list context menus, resolve GitWorktrees.ToolWindow.Popup to an ActionGroup during panel setup and install it with the direct ActionGroup PopupHandler.installPopupMenu overload; the string-id overload can resolve to null when the menu is invoked in the 2025.2 runtime.
• The Git Worktrees panel now uses a table, not JBList: UI robot tests should locate JBTable/JTable, and popup installation tests should install against a table-like JComponent.
• For the table panel, keep repository rows as grouping context only. Worktree displays WorktreeInfo.name; Branch displays branchName ?: "detached"; sort and filter are applied within each repository group.
• Repository/root table rows can be collapsed or expanded only within the current GitWorktreesPanel instance. Double-click root rows to toggle them, single-click only the left chevron hit area to toggle them, keep single-click root text selecting only, keep double-click worktree rows opening that worktree, and keep the popup toggle action visible only for exactly one selected root row.
• For Git Worktrees table Speed Search, install TableSpeedSearch on the JBTable, return search text only for worktree rows, and use a ColoredTableCellRenderer plus SpeedSearchUtil.appendFragmentsForSpeedSearch for visible match highlighting. Tests that assert the supply is installed before the popup is active should call SpeedSearchSupply.getSupply(table, true).
• When adding interactive controls to the Git Worktrees table header, keep them inside a custom JTableHeader and set that same header as the scroll pane column header view. Do not null out the table header renderer; Swing's BasicTableHeaderUI still reads it for sizing.
• When wrapping the Git Worktrees panel toolbar in another component to add right-side content, explicitly call ActionToolbar.setOrientation(SwingConstants.HORIZONTAL) before setToolbar(...); SimpleToolWindowPanel only auto-adjusts orientation when the toolbar component itself is the direct ActionToolbar.
• For bulk worktree deletion, do not refresh the repository or synchronously clean leftover directories after every individual worktree/branch command. Batch Git operations first, refresh each affected repository once, and defer physical leftover cleanup when possible because Windows directory cleanup can dominate the perceived delete time.
• Deferred leftover directory cleanup after bulk deletion should not create another visible Deleting Worktree Task.Backgroundable; keep the user-visible delete task scoped to Git unregister/branch deletion, and run leftover file cleanup as best-effort pooled work with de-duplicated paths.
• For single Git Log branch deletion that first removes a linked worktree, also run branch deletion before leftover directory cleanup. If git worktree remove --force reports Directory not empty or Filename too long after unregistering the worktree, defer the physical cleanup outside the visible delete task so the branch menu action does not appear stuck on Windows. Cleanup should use Windows long-path-safe IO for local absolute paths.
• To open the Worktrees panel from the Git/Version Control tool window, register the entry action under Vcs.Log.ToolWindow.TabActions.DropDown and have it create or select a closable Content in ToolWindowId.VCS; keep the standalone Git Worktrees tool window only as a fallback. Keep the standalone GitWorktreesToolWindowFactory implementation minimal and Java-based on the 2025.2 baseline; Kotlin implementations can emit verifier-sensitive default-method bridges such as isApplicable, isDoNotActivateOnStart, getAnchor, getIcon, and manage.
• For right-side helper text in IntelliJ action popup menus, set ActionUtil.SECONDARY_TEXT on the action Presentation; do not append spacing or suffixes into the main action text.
• For checkout candidates in the Git Worktrees popup, keep actions visible when exactly one worktree row is selected. If checkout is not currently possible, disable the action, put the reason in Presentation.description, and copy that reason onto the disabled menu item's Swing tooltip when the popup opens.
• Do not register a separate Checkout Here action in the Git Worktrees panel popup; keep the popup focused on repository expand/collapse plus the single Checkout candidate, Open, Delete, and Refresh.
• Checkout actions should stay available for a selected non-current worktree even when its branch name already matches the repository's current branch; Git can still surface useful status/errors with checkout --ignore-other-worktrees, while hiding the action makes duplicate same-branch worktrees look unresponsive.
• Checkout actions must queue checkout work in a background task through GitWorktreesOperationsService.checkout*Async; do not run git checkout or GitRepository.update() synchronously from action handlers/EDT. If local changes require confirmation, show only the confirmation dialog on EDT, then run the force checkout in the background task.
• For Git Log branch checkout/delete worktree-conflict handling on the 2025.2 baseline, install ActionManager.replaceAction(...) wrappers for Git.CheckoutGroup, Git.BranchOperationGroup, and the single-ref Git.Branch group at app startup and keep Git4Idea-native children as fallback. Do not subclass GitSingleCommitActionGroup / GitCheckoutActionGroup; they are Kotlin internal in this runtime.
• Register AppLifecycleListener entries as a root-level <applicationListeners> block in plugin.xml, not inside <extensions defaultExtensionNs="com.intellij">. If it is nested under extensions, sandbox logs report an unresolved com.intellij.applicationListeners extension and startup action replacement will never run.
• For Git.Branch replacement children, keep checkout/delete replacements as git4idea.actions.ref.GitSingleRefAction subclasses. Git4Idea wraps only GitSingleRefAction children with GitBranchActionWrapper, which is what provides Git.Selected.Ref, Git.Selected.Repository, and Git.Repositories in the Git Log branch-label menu.
• For Git Log branch actions, do not match worktree-conflict branches only by visible menu text. Git4Idea may truncate or wrap branch labels, especially names with /; prefer wrapped action DataSnapshotProvider keys (Git.Selected.Ref, Git.Selected.Repository, Git.Repositories) for branch operation actions, and native action fields such as hashOrRefName as checkout fallback.
• In the table, the left checkmark marks the current repository/worktree location by path. After checking out a linked worktree branch into the current repository location, the checkmark should remain on that current location row while its Branch column updates to the selected branch.
• Plugin logo files should live at src/main/resources/META-INF/pluginIcon.svg and, when needed, pluginIcon_dark.svg; JetBrains expects 40x40 SVG icons there. Promotional variants and previews can live under design/plugin-icons/.
• Marketing screenshots and bilingual promotional copy should live under design/marketing/. Keep screenshots text-clean when possible, and put English + Chinese copy in the same Markdown file so README and Marketplace material stay reusable.
• For Marketplace description screenshots that use raw.githubusercontent.com, point URLs at the repository's actual default branch (master in this repository), not an assumed main branch. Before release, validate each raw image URL with HTTP HEAD and expect 200 plus Content-Type: image/png.
• Keep README and design/marketing/ promotional copy organized as a full English section first, then a full Chinese section. In README, keep the <!-- Plugin description --> block around the public user-facing description only, so Marketplace metadata includes the bilingual intro but not development commands.
• For Marketplace releases, keep gradle.properties pluginVersion, CHANGELOG.md, the Git tag, and the GitHub Release title aligned as the same plain SemVer value, for example 1.0.0 without a v prefix. Publish through the GitHub Release workflow using repository secrets; if JetBrains Marketplace rejects the first automated upload because the plugin is new, use the signed ZIP for the initial manual Marketplace upload.
• Date-style release versions such as 2026.0509.0 need the custom changelog.headerParserRegex in build.gradle.kts; the Gradle Changelog Plugin default SemVer parser rejects the zero-padded 0509 segment.
• This machine may not expose CERTIFICATE_CHAIN, PRIVATE_KEY, and PRIVATE_KEY_PASSWORD in the local shell. When those environment variables are absent, produce the signed ZIP through the GitHub Release workflow, which reads the repository secrets and uploads build/distributions/* back to the GitHub Release.
• If verifyPlugin appears stuck with low CPU while resolving verifier dependencies or remote repositories, stop the Gradle daemon and rerun it with Gradle offline mode after the IDE artifacts are cached: set JAVA_HOME to C:\Users\Admin\.jdks\jbr-21.0.10-1, set GRADLE_OPTS='-Xmx768m -Dorg.gradle.jvmargs=-Xmx768m', then run ./gradlew.bat --offline --no-daemon verifyPlugin --console=plain. Do not pass --args="-offline" to this Gradle task on the current plugin setup; it can shift Plugin Verifier arguments so the plugin ZIP is parsed as an IDE directory.
• On the first Marketplace upload, keep the signed ZIP available even if publishPlugin returns Cannot find plugin; let the release workflow upload build/distributions/* with --clobber, then fail the job so the GitHub Release asset can be used for the manual Marketplace "Add new plugin" flow.
• When current master has moved past the latest release tag and the task is a follow-up marketing/release refresh, compare current HEAD with the latest tag first, update README plus design/marketing/ around user-visible plugin behavior, then bump gradle.properties and CHANGELOG.md to the next unused release version before building and verifying.
• In .github/workflows/build.yml, keep releaseDraft.needs limited to jobs that actually exist, and skip draft creation when gh release view "$VERSION" already finds a release. Otherwise push checks can fail before any job logs exist, or fail after an already-published release tries to create a duplicate draft.
• For Git branch menu actions across 2025.2/2025.3+ IDEs, do not statically reference the GitSingleRefActions holder class from one package. Use stable DataKey.create(...) names for Git.Selected.Ref, Git.Selected.Repository, and Git.Repositories instead, and keep tests pinning those key names.
• With IntelliJ Platform Gradle Plugin 2.16.0 / Plugin Verifier 1.403, delegated Git action wrappers must not call ActionGroup.getChildren(e) directly; the verifier reports OVERRIDE_ONLY_API_USAGES. Use the event update session, for example e.updateSession.children(group), and give lightweight TestActionEvent helpers a minimal UpdateSession implementation when tests need to expand native groups.
• Avoid Kotlin stdlib helpers that may compile to newer runtime overloads inside IntelliJ test actions, especially sequenceOf(singleValue). Linux CI can load the IDE-bundled Kotlin stdlib before Gradle's test dependency and fail with NoSuchMethodError; prefer simple lists, arrays, or loops in action code that runs under the platform test harness.
• For IntelliJ action data exposed by Swing panels, prefer UiDataProvider.uiDataSnapshot(DataSink) over legacy DataProvider.getData(String); keep tests using a small DataSink helper so production code does not reintroduce deprecated UiCompatibleDataProvider.getData(String) usage.
• For panel/action/service changes, run the targeted suite with: ./gradlew.bat test --tests dev.dengchao.idea.plugin.git.worktrees.GitWorktreesPanelTest --tests dev.dengchao.idea.plugin.git.worktrees.GitWorktreesActionsTest --tests dev.dengchao.idea.plugin.git.worktrees.GitWorktreesOperationsServiceTest
• Before merging feature work, run ./gradlew.bat test.