|
| 1 | +# Empty States Specification |
| 2 | + |
| 3 | +The WorkGrove tree view displays contextual messages when it cannot show worktree items. These messages help users understand why the tree is empty and how to resolve it. |
| 4 | + |
| 5 | +## States |
| 6 | + |
| 7 | +The tree view has 3 possible empty states, checked in priority order: |
| 8 | + |
| 9 | +| Priority | State | Condition | Message | |
| 10 | +|---|---|---|---| |
| 11 | +| 1 | Git unavailable | `git --version` fails or times out | "Git is not available.\n[Learn More](https://git-scm.com)" | |
| 12 | +| 2 | No repository | Git works but no `.git` found in workspace | "No git repository found in the current workspace." | |
| 13 | +| 3 | No worktrees | Repository exists but `git worktree list` returns only the main worktree with no workspace files | "No worktrees found." | |
| 14 | + |
| 15 | +## View Visibility |
| 16 | + |
| 17 | +The tree view must be visible in all 3 empty states so the user can see the message. The `when` clause on the view uses both VS Code's built-in git detection and our own context key: |
| 18 | + |
| 19 | +``` |
| 20 | +"when": "gitOpenRepositoryCount > 0 || gitWorkGrove.gitUnavailable" |
| 21 | +``` |
| 22 | + |
| 23 | +Without `gitWorkGrove.gitUnavailable`, the view would be hidden when git is not installed (because VS Code's own Git extension also cannot detect repositories, leaving `gitOpenRepositoryCount` at 0). |
| 24 | + |
| 25 | +### Reachability Note |
| 26 | + |
| 27 | +The "No repository" message is a safety net for edge cases (e.g., VS Code's Git extension detects a repo but our extension's `resolveGitCwd()` does not). In the common scenario — user opens a non-git folder — `gitOpenRepositoryCount` is 0, so the view itself is hidden and no message is shown. This is intentional: showing an empty panel in a project unrelated to git would be noise. |
| 28 | + |
| 29 | +## Context Keys |
| 30 | + |
| 31 | +| Key | Type | Set when | |
| 32 | +|---|---|---| |
| 33 | +| `gitWorkGrove.gitUnavailable` | boolean | `git --version` fails or times out (5s) | |
| 34 | +| `gitWorkGrove.hasRepository` | boolean | Git is available AND `.git` found in workspace folders | |
| 35 | + |
| 36 | +Initial values (set synchronously at activation): both `false`. |
| 37 | + |
| 38 | +## Welcome Message Conditions |
| 39 | + |
| 40 | +Each welcome message has a `when` clause that ensures only one message shows at a time: |
| 41 | + |
| 42 | +| Message | `when` clause | |
| 43 | +|---|---| |
| 44 | +| Git unavailable | `gitWorkGrove.gitUnavailable` | |
| 45 | +| No repository | `!gitWorkGrove.gitUnavailable && !gitWorkGrove.hasRepository` | |
| 46 | +| No worktrees | `gitWorkGrove.hasRepository` | |
| 47 | + |
| 48 | +The priority order is enforced by the `when` clauses — only one message is visible at any time. |
| 49 | + |
| 50 | +## Detection Flow |
| 51 | + |
| 52 | +``` |
| 53 | +activate() |
| 54 | + ├─ git --version (5s timeout) |
| 55 | + │ ├─ FAIL → set gitUnavailable=true, hasRepository=false → early return |
| 56 | + │ └─ OK → walk workspace folders looking for .git |
| 57 | + │ ├─ NOT FOUND → set hasRepository=false → early return |
| 58 | + │ └─ FOUND → set hasRepository=true → continue initialization |
| 59 | + └─ (tree provider returns [] if no worktrees) |
| 60 | +``` |
| 61 | + |
| 62 | +## Message Content |
| 63 | + |
| 64 | +### Git unavailable |
| 65 | + |
| 66 | +``` |
| 67 | +Git is not available. |
| 68 | +[Learn More](https://git-scm.com) |
| 69 | +``` |
| 70 | + |
| 71 | +The link points to the official Git download page so users can install git. |
| 72 | + |
| 73 | +### No repository |
| 74 | + |
| 75 | +``` |
| 76 | +No git repository found in the current workspace. |
| 77 | +``` |
| 78 | + |
| 79 | +No link needed — the user needs to open a folder that contains a git repository. |
| 80 | + |
| 81 | +### No worktrees |
| 82 | + |
| 83 | +``` |
| 84 | +No worktrees found. |
| 85 | +``` |
| 86 | + |
| 87 | +This appears when the tree provider returns an empty array. In practice this is rare since the main worktree always exists if a repository is detected, but it covers edge cases (e.g., corrupt git state). |
| 88 | + |
| 89 | +## Output Channel Logging |
| 90 | + |
| 91 | +Each empty state logs a message to the "Git WorkGrove" output channel: |
| 92 | + |
| 93 | +| State | Log message | |
| 94 | +|---|---| |
| 95 | +| Git unavailable | `Git is not available` | |
| 96 | +| No repository | `No git repository found in workspace folders` | |
| 97 | +| No worktrees | *(no explicit log — tree simply returns empty)* | |
0 commit comments