diff --git a/.changeset/add-readme-usage-docs.md b/.changeset/add-readme-usage-docs.md new file mode 100644 index 0000000..a877f9b --- /dev/null +++ b/.changeset/add-readme-usage-docs.md @@ -0,0 +1,5 @@ +--- +"git-work-grove": patch +--- + +Add screenshot and comprehensive usage documentation to README diff --git a/CLAUDE.md b/CLAUDE.md index ca5f791..ed29da4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -36,6 +36,16 @@ Design specs live in `docs/spec/`. These are the **source of truth** for how fea With favorites, these become 8 item types (4 normal + 4 favorite). Never conflate repository workspace with worktree workspace — they have different available template variables and may display different information. +## Documentation Maintenance + +When modifying features or behavior, **always update the corresponding documentation in the same work session**: + +- **README.md** — Update the Usage, Settings, Commands, or Features sections if user-facing behavior changes +- **docs/templates.md** — Update if template variables, syntax, or defaults change +- **docs/spec/*.md** — Update the relevant spec (per Spec Maintenance Rules above) + +All three layers (README, user docs, specs) must stay in sync with the code. + ## Code Conventions - **ESLint**: Uses `@antfu/eslint-config` with `perfectionist/sort-named-imports` — named imports MUST be alphabetically sorted diff --git a/README.md b/README.md index 7b2143e..65a6c7e 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,8 @@ Git WorkGrove provides first-class `.code-workspace` support for git worktrees. It appears in the Source Control view, letting you browse worktrees and directly open their workspace files. +![Git WorkGrove tree view](https://raw.githubusercontent.com/vp-tw/vscode-extension-git-work-grove/main/docs/images/screenshot.png) + ## Why This Extension Exists Git worktrees are powerful for parallel development — but VS Code and its extensions don't handle `.code-workspace` files well in worktree workflows. @@ -37,15 +39,108 @@ If VS Code or GitLens ever ships proper `.code-workspace` support for worktrees, - **Prune** — Clean up stale worktree records - **Live updates** — FileSystemWatcher detects worktree changes automatically +## Usage + +### Tree View + +Git WorkGrove adds a **WORKGROVE** panel in the Source Control sidebar. It shows: + +1. **Favorites** — Pinned items at the top (if any exist) +2. **Repository** — The main worktree (collapsible, with workspace files as children) +3. **Linked worktrees** — All other worktrees (alphabetically sorted, each with workspace files) + +Click a workspace file to open it. Click a worktree to expand/collapse its children. + +### Context Menu (Right-Click) + +Right-click any item in the tree to access: + +| Action | Description | +|--------|-------------| +| **Open in New Window** | Opens the worktree or workspace file in a new VS Code window | +| **Open in Current Window** | Opens in the current VS Code window | +| **Reveal in Finder** | Opens the item's location in your OS file manager | + +Favorite-specific actions appear as inline buttons: + +| Button | Description | +|--------|-------------| +| **Add Favorite** (star outline) | Pin this item to the Favorites section | +| **Remove Favorite** (filled star) | Unpin from Favorites | +| **Move Up / Move Down** (chevrons) | Reorder within Favorites | + +You can also drag and drop favorites to reorder them. + +### View Title Actions + +The WORKGROVE panel header provides: + +| Action | Location | Description | +|--------|----------|-------------| +| **Refresh** | Header icon | Re-scan worktrees and workspace files | +| **Prune Worktrees** | `...` overflow menu | Run `git worktree prune` to clean up stale records | +| **Clean Stale Favorites** | `...` overflow menu | Remove favorites that no longer exist on disk | + +### Open Behavior + +When you click a workspace file, the behavior depends on the `openBehavior` setting: + +- **`ask`** (default) — Shows a picker with options: _Open in New Window_, _Open in Current Window_, plus "Always" variants that persist your choice +- **`newWindow`** — Always opens in a new window +- **`currentWindow`** — Always opens in the current window + +### Current Indicator + +The currently open workspace or worktree is highlighted with: + +- A **green-tinted icon** +- A **green dot badge** (●) + +Clicking the current item does nothing (it's already open). + ## Settings +Open VS Code Settings (`Cmd+,` / `Ctrl+,`) and search for `git-work-grove`: + | Setting | Type | Default | Description | |---------|------|---------|-------------| | `git-work-grove.openBehavior` | `ask` \| `newWindow` \| `currentWindow` | `ask` | Default action when opening a workspace | | `git-work-grove.workspaceFile.include` | `string[]` | `["*.code-workspace"]` | Glob patterns for workspace file scanning | | `git-work-grove.workspaceFile.exclude` | `string[]` | `[]` | Glob patterns to exclude from scanning | | `git-work-grove.template.*` | `string` | *(varies)* | Display templates — see [Template Customization](https://github.com/vp-tw/vscode-extension-git-work-grove/blob/main/docs/templates.md) | -| `git-work-grove.favorites` | `string[]` | `[]` | Ordered list of favorited item paths | +| `git-work-grove.favorites` | `string[]` | `[]` | Ordered list of favorited item paths (managed via the UI) | + +### Template Customization + +All tree item labels and descriptions are customizable. Templates support variables like `{name}`, `{branch}`, `{ref}`, fallback syntax (`{branch|detached}`), and conditional sections (`{?branch}({branch}){/branch}`). + +See [Template Customization](https://github.com/vp-tw/vscode-extension-git-work-grove/blob/main/docs/templates.md) for all 8 item types, available variables, and examples. + +## Commands + +All commands use the `Git WorkGrove:` prefix. Some are available via the Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`), while others appear only in the tree view context menu or inline buttons. + +### Command Palette + +| Command | Description | +|---------|-------------| +| Refresh | Re-scan worktrees and workspace files | +| Prune Worktrees | Run `git worktree prune` to clean up stale records | +| Show Output | Open the extension's output channel for debugging | +| Clean Stale Favorites | Remove favorites pointing to deleted items | + +### Context Menu Only + +These commands appear when right-clicking items in the tree view: + +| Command | Description | +|---------|-------------| +| Open in New Window | Open worktree or workspace file in a new VS Code window | +| Open in Current Window | Open in the current VS Code window | +| Reveal in Finder | Open the item's location in your OS file manager | +| Add Favorite | Pin this item to the Favorites section | +| Remove Favorite | Unpin from Favorites | +| Move Favorite Up / Down | Reorder within Favorites | ## Documentation @@ -62,6 +157,7 @@ Design documents for contributors and AI-assisted development: - [Commands](https://github.com/vp-tw/vscode-extension-git-work-grove/blob/main/docs/spec/commands.md) — All commands, menu placement, behaviors - [Workspace Scanning](https://github.com/vp-tw/vscode-extension-git-work-grove/blob/main/docs/spec/workspace-scanning.md) — File discovery, include/exclude patterns - [Open Behavior](https://github.com/vp-tw/vscode-extension-git-work-grove/blob/main/docs/spec/open-behavior.md) — Open modes, URI resolution, click handling +- [Empty States](https://github.com/vp-tw/vscode-extension-git-work-grove/blob/main/docs/spec/empty-states.md) — Git unavailable, no repository, no worktrees messages ## Requirements diff --git a/docs/images/screenshot.png b/docs/images/screenshot.png new file mode 100644 index 0000000..895aa7d Binary files /dev/null and b/docs/images/screenshot.png differ