docs: GitLens v17.0.0–v19.0.1 audit — prose updates + 31 regenerated images - #157
docs: GitLens v17.0.0–v19.0.1 audit — prose updates + 31 regenerated images#157Roberto-Vizcarra wants to merge 17 commits into
Conversation
12 pages updated across the GitLens help center. Images and ref rewrites deferred to run --apply.
Automated capture run for GitLens v17.0.0..v19.0.1 backfill audit. 135 new image assets written (screenshots regenerated from shot specs). 197 image references rewritten across 19 documentation pages. 11 items deferred (10 alt-text backfill, 1 assemble retry needed). Pages updated: - gitlens-features.md, gitlens-faq.md, gitlens-settings.md, gitlens-home.md - GL-Commit-Graph.md, GL-GK-AI.md, GL-Integrations.md, GL-Launchpad.md - GL-Cloud-Patches.md, GL-Code-Suggest.md, GL-Visual-File-History.md - GL-Workflow-Cleanup-prepare-for-review.md, GL-Workspaces.md, GL-Worktrees.md - GL-Agent-Generated-work-end-to-end.md, GL-Branch-Prep-to-ship.md - GL-Parallel-dev-workflow.md, home-view.md, side-bar.md
- Delete 30 unreferenced older image versions (v2 when v3 exists, etc.) - Crop ~40 images to remove excessive whitespace/empty editor space - Add purple highlight annotations to 6 images (stash AI icon, Jira integration, delete cloud patch, status bar blame, gutter heatmap, pull request icon) 12 images flagged for recapture (wrong content or static PNG with .gif extension): gl-agent-kanban, gl-ai-branch-summary, gl-ai-generate-changelog, gl-ai-generated-commit-message (x2), gl-auto-rebase-resolve, gl-code-suggest, gl-commits-view-merge, gl-commits-view-rebase, gl-convert-workspace-to-cloud, gl-create-vs-workspace-from-gl, gl-create-workspace
run --apply rewrote refs to new versioned filenames (e.g. gl-agent-kanban-01-v2@2x.png) but the captures were incorrect and never uploaded to WordPress. Reverting to the original filenames that still exist on the WordPress server. These 12 images are deferred as manualCaptureOnly in gk-docs-automation and will be recaptured in a follow-up PR.
Round 2 visual verification found 51 incorrect captures (39% failure rate). 48 refs reverted to originals still on WordPress. 3 new-section images (graph-sidebar, graph-details-panel, rich-commit-search) have no original to revert to and will be fixed in recapture. Failure categories: Get Started panel visible (~6), wrong view/panel (~15), generic commit graph with no feature (~9), empty panels (~6), wrong state (~15).
Recaptured all 33 previously failed specs plus 2 newly automated specs (gl-file-history-view-merge-conflict-01, gl-revision-navigation-01). Fixes: onboarding dismiss in all spec setups, subscription simulation removal, correct command names for PR creation and Settings webview, xdotoolClick for hover dismissal in Tags view.
Replaces the 13 images the 2026-09-04 visual audit flagged as showing the wrong content, and deletes one orphaned regeneration. Each replacement was captured from a corrected spec and visually verified. Per-image findings and root causes are in gk-docs-automation/docs/visual-audit-findings.md. - gl-commits-view-01-v2@2x: hover tooltip overlay removed - gl-rich-commit-search-02-v2@2x: full graph webview with highlighted results - gl-access-composer-1-17-4-01-v3@2x: labeled Compose entry point - gl-worktrees-view-01-v2@2x: current worktree expanded (upstream, compare, commits) - gl-column-settings: current v19 column settings menu (was a plain graph) - gl-connect-to-remote-ghe-01-v2@2x: unlinked GHE remote with the Connect plug - gl-graph-details-panel-01-v2: populated details panel for the selected commit - gl-graph-sidebar-01-v2: expanded sidebar branches tree - gl-commit-graph-compact-graph-01-v2@2x: real compact toggle (avatars -> dots) - gl-hide-refs-01-v2@2x: scope popover hiding remote-only refs - gl-agent-working-01-v2@2x: Agents section with a live working session - gl-ai-generated-commit-message-01-v2: real GitKraken AI commit message - gl-ai-stash-01-v2@2x: AI-generated stash message
|
This is a thick one boys. the prose edits are likely all fine, but the images are hit and miss. I haven't gone through all of them, and I'm going to have it do another review/polishing pass for all of them to validate they are all showing the right thing, and if they need annotations, etc. This is an example of what one of the automated HC updates would be like (just much bigger than the subsequent ones). |
These files were regenerated in cbfa0e1, failed the 2026-09-03 round-2 visual verification, and had their page refs reverted to the original WordPress filenames in 4672836 and d62474c — but the files stayed in _images/. None is on main and none is referenced by any file in the repo at HEAD (verified before deletion). Post-merge WordPress upload would otherwise create 57 useless media items. Full list: gk-docs-automation/docs/capture-review/gitlens-pr157-2026-09-08/lists/01-referenced-updated-images.md (Orphans).
…ures in place Manual Pillow post-processing per gk-docs-automation docs/capture-review/gitlens-pr157-2026-09-08/lists/05-remediation-plan.md §Stage 1 (D2 manual, D3 HOUSE-1 ring #a855f7 12px/28px, D4 keep 2x — crop only, no resampling). Untouched captures kept in gk-docs-automation out/capture-review/.../pre-polish/. Page refs unchanged (D1); the @2x renames wait for the final ref pass. gl-connect-to-remote-ghe and gl-column-settings were moved to Stages 3/2 (not fixable by cropping) and are untouched here. Every image is re-judged in the closing review run before merge.
Prose and alt text only — no image refs changed (D1: refs move in one pass at the end).
- Commit Graph: hide refs via the pill context menu; compact layout via the column gear ("Use Compact Graph Column"); scope labels All / Current / Smart Branches; layout switch via the More Actions menu ("Prefer Commit Graph in Editor" / "as a View"); minimap options via the minimap gear
- FAQ: sign out via the Home account chip popover; "Enable Debug (Trace) Logging"; proxy = VS Code http.proxy settings
- Settings: nav groups (no "Setup"); Commits view category = format templates
- Integrations: Cloud Integrations lives in the GitLens Settings editor
- Workspaces: green dot indicator; Inspect Overview alt without PR context; current-line changes hover alt/caption
- alt attributes added to 29 images that had none
…hip, graph header, terminal links alt) Prose and alt text only — no image refs changed. - GL-GK-AI.md: v19 has no "Generate Commits with AI" command (Commit Composer / Automatic Rebase instead); SCM entry point is the GitLens sparkle menu → Generate Commit Message; alt describes the SCM view - GL-Integrations.md / gitlens-features.md: "GitKraken Account section → Integrations" → the Home view's integrations chip and its Integrations popover; alts and figcaptions follow - GL-Commit-Graph.md / gitlens-features.md: graph header bullets — repository shown as the provider icon/tab title, last fetched beside Fetch and in its hover; setting is gitlens.graph.autoFetch.enabled; alts describe the capture - gitlens-features.md: terminal-links alt describes the underlined SHA with the Show Commit hover
…, alts, one new figure The single reference pass of the PR #157 remediation. Every image referenced by the audit pages now points at the file the closing review signed off, and every <img> carries the alt its spec validated. Images - 57 captures replaced under a bumped basename (vN -> vN+1, @2x where the capture is 2x); the superseded files are deleted. - 2 Stage-1 edits renamed to @2x (gl-graph-details-panel-01-v2, gl-settings-hovers-01-v2). - gl-current-line-blame-01-v4@2x.png ships the Stage-2 recapture (the Stage-1 crop carried a ring drawn at the wrong offset). - gl-create-cloud-patch-example reverts to the original: the Create Cloud Patch view never receives its create state headlessly (documented in the spec, manual capture). - gl-gutter-changes-01@2x.png is NEW: the "File Changes" figure had been reusing the File Blame capture (as main did with gutter-blame.png). - gl-ai-generated-commit-message-01-v2.gif is the polished 2-frame Source Control recording; its duplicate figure under "AI Generate Commits" is removed (that section describes the Commit Composer in v19). - gl-home-view-v16.png restored: it was deleted while side-bar.md still referenced it. Pages - 29 missing alt attributes added; alts rewritten wherever they described UI the capture does not show (gutter blame has no author, autolinks resolve to a chip, the Repositories view has no Stashes node by default, the Remotes view's branches are collapsed, the PR pill shows an icon and not "#7", the account popover's rows are blanked for privacy). - Prose corrected against GitLens v19: hide a ref from the ref pill's context menu, the graph layout commands live in the editor's More Actions menu, "Enable Debug (Trace) Logging", the integrations chip in the Home header, the wand on the Working Changes row, search Settings for `http.proxy`, compact layout via "Use Compact Graph Column", the workspace indicator is a green dot. - Broken ref fixed: gl-ai-branch-summary.png -> ai-branch-summary.png. Every shipped image was judged by an adversarial reviewer against the page's intent and compared against the image it replaces: 80 images, 0 FAIL, 80 keep-new. Review run: gk-docs-automation/docs/capture-review/gitlens-pr157-remediation-2026-09-10.
…mber 2026 gitlens-faq.md and gitlens-features.md were rewritten with CRLF earlier on this branch while main has them as LF, so GitHub's PR view showed both files as changed end to end (2926 lines for features.md, 208 for the FAQ). The repo has no .gitattributes and core.autocrlf is unset, so nothing normalises them. Converted both back to LF: the PR diff for features.md drops to 404 lines and the FAQ to 26, all real changes. GitKraken Desktop was already showing the true diff because it ignores whitespace-only changes. Last updated bumped to September 2026 on the 14 pages this PR touches that carry the tag. Three touched pages have no tag at all and were left alone: GL-GK-AI.md, GL-Workflow-Cleanup-prepare-for-review.md, gitlens-start-here.md.
…d one GL-GK-AI.md, GL-Workflow-Cleanup-prepare-for-review.md and gitlens-start-here.md are touched by this PR but carried no <kbd>Last updated:</kbd> tag. Added in the house format — blank line, tag, blank line, directly after the front matter, as on gitlens-home.md and GL-Agents.md — dated September 2026 like the rest of the PR. gitlens-start-here.md keeps the horizontal rule that followed its front matter; the tag now sits above it, matching its sibling gitlens-home.md. All 17 pages this PR touches now carry a September 2026 tag.
There was a problem hiding this comment.
The substance looks strong this is a useful accuracy and coverage pass. These comments are messaging and clarity refinements: strengthen Commit Graph-as-workbench positioning, use Working Changes consistently, clarify Community versus Pro access, keep developer control explicit in AI workflows, and connect agent activity to Git context. The existing home-view.md opening is a good benchmark for the rest of these updates.
Please also review the standalone Commit Graph PRO heading and the AI Auto Rebase wording in gitlens-features.md: the access model should make Community/public-repository availability unmistakable, and Auto Rebase should explain the confidence threshold, stop behavior, and undo path rather than promise end-to-end autonomy.
| ## Commit Graph <code>PRO</code> | ||
|
|
||
| The GitLens Commit Graph provides an interactive view of your repository history. It shows commits, branches, and collaborators in one place, helping you understand contributions and make faster decisions. | ||
| The GitLens Commit Graph is the main view in the GitLens sidebar, providing an interactive visualization of your repository history. Built on a high-performance rendering engine, it shows commits, branches, and collaborators in one place, helping you understand contributions and make faster decisions. |
There was a problem hiding this comment.
Could we lead with the Commit Graph as the workbench for getting work ready to merge? “Main view” and “interactive visualization” describe the surface, but undersell the workflow. The opening in home-view.md is a strong model.
Suggested copy:
The Commit Graph is the starting point for working in GitLens. It brings repository history, branches, worktrees, Working Changes, pull requests, and supported agent activity into one connected workbench, so you can understand what’s happening and move changes toward merge without rebuilding context across tools.
The rendering-performance detail can follow that introduction. Please carry the same positioning into the matching intro in gitlens-features.md.
|
|
||
| --- | ||
|
|
||
| ### WIP Bar |
There was a problem hiding this comment.
Could we use Working Changes for customer-facing references to uncommitted work, consistent with the GitLens 19 UI and the screenshots in this PR? For this section, consider Worktree Overview as the descriptive heading, and “Working Changes row” instead of “WIP row.”
Suggested description:
See branch state, uncommitted changes, and unpushed commits across your worktrees. Each worktree has a pill above the Graph; select it to jump to that worktree’s Working Changes row.
Please apply the terminology consistently to nearby prose, captions/alt text, and the Compose description in gitlens-features.md. Preserve literal command/setting names and any shipping UI labels that actually say WIP. Also check whether “Overview Bar” and “WIP Bar” describe the same surface; if so, one section would be clearer.
|
|
||
| - **Compare mode**: Opens comparisons directly within the graph, showing Ahead, Behind, and All views between branches or commits. This replaces navigating to the standalone Search and Compare view for graph comparisons. | ||
| - **Compose mode**: Provides an integrated commit composition experience, letting you craft commit messages and select files to commit without leaving the graph. You can also access Compose from the graph context menu. | ||
| - **Recompose**: Restructures the commit history on a branch using AI. Available from the graph context menu, Recompose can operate on an entire branch, from a specific commit, or on selected commits. It analyzes your changes and reorganizes them into cleaner, more logical commits. |
There was a problem hiding this comment.
Could we describe Recompose as preparing a proposed history that the developer reviews and applies? “Restructures … using AI” makes the action sound immediate and hides the drafting/control step already described in the Composer docs.
Suggested opening:
Recompose: Helps clean up existing branch history by reorganizing selected commits into a clearer, more intentional sequence. GitKraken AI can propose the new structure and commit messages for you to review and refine before applying the result.
Keep the supported branch/commit selection scopes after this. Please align the “Recompose Branch” command description in gitlens-features.md with the same framing.
| - **Compare mode**: Opens comparisons directly within the graph, showing Ahead, Behind, and All views between branches or commits. This replaces navigating to the standalone Search and Compare view for graph comparisons. | ||
| - **Compose mode**: Provides an integrated commit composition experience, letting you craft commit messages and select files to commit without leaving the graph. You can also access Compose from the graph context menu. | ||
| - **Recompose**: Restructures the commit history on a branch using AI. Available from the graph context menu, Recompose can operate on an entire branch, from a specific commit, or on selected commits. It analyzes your changes and reorganizes them into cleaner, more logical commits. | ||
| - **Review mode**: Uses AI to analyze commits or working changes and surfaces severity-tagged insights such as potential bugs, security issues, or style concerns. You can configure separate AI models for compose and review using per-feature model scoping, and customize review behavior with the `gitlens.ai.reviewChanges.customInstructions` setting. |
There was a problem hiding this comment.
Could we make the review workflow primary and AI assistance secondary, with developer judgment explicit?
Suggested opening:
Review mode: Helps you inspect commits or Working Changes before they move forward. GitKraken AI can surface potential bugs, security issues, and other areas that deserve attention, while you decide what needs to change.
The model-selection and custom-instructions details can follow. This keeps the useful capabilities without making AI sound like the final reviewer.
- Lead the Commit Graph intros with the workbench positioning from home-view.md; move the rendering-performance detail after it - Merge the duplicate Overview Bar and WIP Bar sections into one Worktree Overview section - Use "Working Changes" for customer-facing references to uncommitted work in prose, captions, and alt text; preserve literal setting/command names and shipping UI labels - Reframe Recompose as proposing a structure the developer reviews and applies; align the Recompose Branch/from Commit/Selected Commits command descriptions - Reframe Review mode so the review workflow is primary and AI assistance secondary - Drop the misleading PRO badge from the standalone Commit Graph headings and state Community/public-repository availability explicitly - Rewrite AI Auto Rebase to explain the confidence threshold, stop behavior, summary sheet, and undo path instead of end-to-end autonomy
|
@SpaceMerlin33 Thanks for the review — all five points are addressed in cfa6270 (5 files changed). Commit Graph as workbench Working Changes terminology
Developer control in AI workflows
Community vs Pro access AI Auto Rebase One thing to confirm: I merged Overview Bar and WIP Bar on the assumption they describe the same surface — both were documented as a horizontal strip above the graph with one pill per worktree. If they are actually two distinct surfaces in GitLens 19, let me know and I will split them back out. |
2 participants
Generated by
gkdocs run gitlensforv17.0.0..v19.0.1.Summary
Automated documentation audit covering 3,312 commits across 22 releases (v17.0.0 through v19.0.1). This PR includes:
Prose updates
Regenerated images (31)
Deferred (not in this PR)
Automation repo
Spec fixes, findings, and prose records: gk-docs-automation