Polishes walkthroughs and includes images in vsix

.vscodeignore

@@ -6,7 +6,7 @@
 .yarn/**
 dist/webviews/*.css
 emoji/**
-images/docs/**
+images/docs/gitlens-preview.gif
 images/originals/**
 node_modules/**
 out/**

package.json

@@ -10815,7 +10815,7 @@
 					{
 						"id": "gitlens.welcome.experience",
 						"title": "Get setup quickly",
-						"description": "Use the Quick Setup to easily configure frequently used GitLens features.\n\n[Open Quick Setup](command:gitlens.showWelcomePage \"Opens the GitLens Quick Setup\")",
+						"description": "Use the Quick Setup to easily configure frequently used GitLens features.\n\n[Open Quick Setup](command:gitlens.showWelcomePage?%22quick-setup%22 \"Opens the GitLens Quick Setup\")",
 						"media": {
 							"markdown": "walkthroughs/getting-started/1-setup.md"
 						}
@@ -10831,14 +10831,14 @@
 					{
 						"id": "gitlens.welcome.currentLineBlame",
 						"title": "See who made what changes at a glance",
-						"description": "Current line blame provides historical context about line changes.",
+						"description": "Current line and status bar blame provide historical context about line changes.",
 						"media": {
 							"markdown": "walkthroughs/getting-started/3-current-line-blame.md"
 						}
 					},
 					{
 						"id": "gitlens.welcome.gitCodeLens",
-						"title": "View Git Authorship Via CodeLens",
+						"title": "View Git authorship via CodeLens",
 						"description": "CodeLens adds contextual authorship information and links at the top of each file and at the beginning of each block of code.",
 						"media": {
 							"markdown": "walkthroughs/getting-started/4-git-codelens.md"
@@ -10854,8 +10854,8 @@
 					},
 					{
 						"id": "gitlens.welcome.fileAnnotations",
-						"title": "Customize file annotations",
-						"description": "File annotations place visual indicators in the gutter and status bar that provide additional context about changes. ",
+						"title": "See more context with file annotations",
+						"description": "Whole file annotations place visual indicators in the gutter and scroll bar that provide additional context about changes.",
 						"media": {
 							"markdown": "walkthroughs/getting-started/6-file-annotations.md"
 						}
@@ -10863,7 +10863,7 @@
 					{
 						"id": "gitlens.welcome.gitSideBarViews",
 						"title": "View more source control details in the side bar",
-						"description": "Additional views expose even more Git functionality in your side bar.",
+						"description": "Additional views expose even more Git functionality in your side bar.\n\n[Set Views Layout](command:gitlens.setViewsLayout)",
 						"media": {
 							"markdown": "walkthroughs/getting-started/7-git-side-bar-views.md"
 						}
@@ -10871,7 +10871,7 @@
 					{
 						"id": "gitlens.welcome.hostingServiceIntegrations",
 						"title": "Integrate with Git hosting services",
-						"description": "Quickly gain insights from pull requests and issues without leaving your codebase.",
+						"description": "Quickly gain insights from pull requests and issues without leaving your editor.",
 						"media": {
 							"markdown": "walkthroughs/getting-started/8-hosting-service-integrations.md"
 						}
@@ -10879,7 +10879,7 @@
 					{
 						"id": "gitlens.welcome.gitCommandPalette",
 						"title": "Work faster with Git Command Palette",
-						"description": "",
+						"description": "Now you don't have to remember all those Git commands.\n\n[Open Git Command Palette](command:gitlens.gitCommands)",
 						"media": {
 							"markdown": "walkthroughs/getting-started/9-git-command-palette.md"
 						}
@@ -10887,7 +10887,7 @@
 					{
 						"id": "gitlens.welcome.interactiveRebaseEditor",
 						"title": "Visualize interactive rebase operations",
-						"description": "",
+						"description": "A user-friendly interactive rebase editor to easily configure an interactive rebase session",
 						"media": {
 							"markdown": "walkthroughs/getting-started/10-interactive-rebase-editor.md"
 						}
@@ -10895,7 +10895,7 @@
 					{
 						"id": "gitlens.welcome.terminal",
 						"title": "Jump to git details from the terminal",
-						"description": "Using ctrl+click on autolinks in the integrated terminal will quickly jump to more details for commits, branches, tags, and more.",
+						"description": "Using ctrl/cmd+click on autolinks in the integrated terminal will quickly jump to more details for commits, branches, tags, and more.",
 						"media": {
 							"markdown": "walkthroughs/getting-started/11-terminal.md"
 						}
@@ -10903,7 +10903,7 @@
 					{
 						"id": "gitlens.welcome.premium",
 						"title": "Premium GitLens Features",
-						"description": "New premium features like Worktrees and Visual File History are now available in GitLens.\n\n[Learn About Premium Features](command:gitlens.openWalkthrough?%22gitlens.premium%7Cgitlens.premium%22 \"Opens the GitLens Premium Features Walkthrough\")",
+						"description": "New premium features like Worktrees and Visual File History are now available in GitLens.\n\n[Learn About Premium Features](command:gitlens.premium.learn?false \"Opens the GitLens Premium Features Walkthrough\")",
 						"media": {
 							"markdown": "walkthroughs/getting-started/12-premium-features.md"
 						}
@@ -10926,7 +10926,7 @@
 					{
 						"id": "gitlens.premium.worktrees",
 						"title": "Do more with Worktrees",
-						"description": "Create Worktrees that allow multiple branches to be checked-out at once on the same repository.",
+						"description": "Create Worktrees that allow multiple branches to be checked-out at once on the same repository.\n\n[Open Worktrees View](command:gitlens.showWorktreesView)",
 						"media": {
 							"markdown": "walkthroughs/premium-features/2-worktrees.md"
 						}
@@ -10934,7 +10934,7 @@
 					{
 						"id": "gitlens.premium.visualFileHistory",
 						"title": "Visualize file history",
-						"description": "A more visual way to analyze and explore changes made to a file.",
+						"description": "A more visual way to analyze and explore changes made to a file.\n\n[Open Visual File History](command:gitlens.showTimelineView)",
 						"media": {
 							"markdown": "walkthroughs/premium-features/3-visual-file-history.md"
 						}
@@ -10942,7 +10942,7 @@
 					{
 						"id": "gitlens.premium.comingSoon",
 						"title": "More coming soon",
-						"description": "",
+						"description": "Stay tuned!",
 						"media": {
 							"markdown": "walkthroughs/premium-features/4-coming-soon.md"
 						}
@@ -10952,7 +10952,7 @@
 						"title": "Try premium features now",
 						"description": "Try premium features now, without an account, for 3 days.\n\n[Try Premium GitLens Features](command:gitlens.premium.startPreviewTrial)",
 						"media": {
-							"markdown": "walkthroughs/premium-features/5-try-premium-now.md"
+							"markdown": "walkthroughs/premium-features/5-try-now.md"
 						}
 					}
 				]

src/premium/subscription/subscriptionService.ts

@@ -158,7 +158,7 @@ export class SubscriptionService implements Disposable {
 		void this.container.viewCommands;
 
 		return [
-			commands.registerCommand(Commands.PremiumLearn, () => this.learn()),
+			commands.registerCommand(Commands.PremiumLearn, openToSide => this.learn(openToSide)),
 			commands.registerCommand(Commands.PremiumLogin, () => this.loginOrSignUp()),
 			commands.registerCommand(Commands.PremiumLoginOrSignUp, () => this.loginOrSignUp()),
 			commands.registerCommand(Commands.PremiumSignUp, () => this.loginOrSignUp()),
@@ -182,8 +182,8 @@ export class SubscriptionService implements Disposable {
 	}
 
 	@debug()
-	learn(): void {
-		void openWalkthrough(this.container.context.extension.id, 'gitlens.premium');
+	learn(openToSide: boolean = true): void {
+		void openWalkthrough(this.container.context.extension.id, 'gitlens.premium', undefined, openToSide);
 	}
 
 	@gate()

src/system/utils.ts

@@ -120,7 +120,12 @@ export async function openEditor(
 	}
 }
 
-export async function openWalkthrough(extensionId: string, walkthroughId: string, stepId?: string): Promise<void> {
+export async function openWalkthrough(
+	extensionId: string,
+	walkthroughId: string,
+	stepId?: string,
+	openToSide: boolean = true,
+): Promise<void> {
 	// Takes the following params: walkthroughID: string | { category: string, step: string } | undefined, toSide: boolean | undefined
 	void (await executeCoreCommand(
 		CoreCommands.OpenWalkthrough,
@@ -128,7 +133,7 @@ export async function openWalkthrough(extensionId: string, walkthroughId: string
 			category: `${extensionId}#${walkthroughId}`,
 			step: stepId ? `${extensionId}#${walkthroughId}#${stepId}` : undefined,
 		},
-		true,
+		openToSide,
 	));
 }
 

walkthroughs/getting-started/1-setup.md

@@ -6,4 +6,4 @@
 
 GitLens is powerful, feature rich, and highly customizable to meet your needs. Do you find code lens intrusive or the current line blame annotation distracting — no problem, quickly turn them off or change how they behave using the Quick Setup.
 
-It can be accessed via the [_GitLens: Welcome (Quick Setup)_](command:gitlens.showWelcomePage) command from the [_Command Palette_](command:workbench.action.quickOpen?%22GitLens%3A%Welcome%22).
+💡 Use the [GitLens: Welcome (Quick Setup)](command:gitlens.showWelcomePage?%22quick-setup%22) command from the [Command Palette](command:workbench.action.quickOpen?%22>GitLens%3A%20Welcome%22) to open it.

walkthroughs/getting-started/10-interactive-rebase-editor.md

@@ -4,4 +4,13 @@
   <img src="../../images/docs/rebase.gif" alt="Interactive rebase editor"/>
 </p>
 
-A user-friendly editor to easily configure an interactive rebase session. Simply drag & drop to reorder commits and select which ones you want to edit, squash, or drop.
+Simply drag & drop to reorder commits and select which ones you want to edit, squash, or drop.
+
+To use this directly from your terminal, e.g. when running `git rebase -i`,
+
+- set VS Code as your default Git editor
+  - `git config --global core.editor "code --wait"`
+- or, to only affect rebase, set VS Code as your Git rebase editor
+  - `git config --global sequence.editor "code --wait"`
+
+> To use the Insiders edition of VS Code, replace `code` in the above with `code-insiders`

walkthroughs/getting-started/11-terminal.md

@@ -1,5 +1,7 @@
-## Git Details in Your Terminal
+## Git Autolinks in Your Terminal
 
 <p align="center">
   <img src="../../images/docs/terminal-links.gif" alt="Links in VS Code Terminal"/>
 </p>
+
+Autolinks are added for branches, tags, and commit ranges in the integrated terminal to quickly explore their commit history. While autolinks for commits will open a quick pick menu with commit details and actions.

walkthroughs/getting-started/12-premium-features.md

@@ -4,4 +4,4 @@
   <img src="../../images/docs/visual-file-history-hover.png" alt="Visual File History View"/>
 </p>
 
-Even more features are coming soon, like a visual commit graph and integrations for GitHub Enterprise and GitLab Self-Managed repositories.
+Even more features are coming soon, like a visual commit graph and integrations for GitHub Enterprise and GitLab repositories.

walkthroughs/getting-started/2-customize.md

@@ -6,6 +6,6 @@
   </figure>
 </p>
 
-GitLens provides a rich **interactive settings editor**, an easy-to-use interface, to configure many of GitLens' powerful features.
+GitLens provides a rich interactive settings editor, an easy-to-use interface, to configure many of GitLens' powerful features.
 
-It can be accessed via the [_GitLens: Open Settings_](command:gitlens.showSettingsPage) command from the [_Command Palette_](command:workbench.action.quickOpen?%22GitLens%3A%20Open%20Settings%22).
+💡 Use the [GitLens: Open Settings](command:gitlens.showSettingsPage) command from the [Command Palette](command:workbench.action.quickOpen?%22>GitLens%3A%20Open%20Settings%22) to open it.

walkthroughs/getting-started/3-current-line-blame.md

@@ -1,16 +1,31 @@
-## Current Line Blame
-
-Adds a [customizable](command:gitlens.showSettingsPage?%22current-line%22 'Jump to the Current Line Blame settings') unobtrusive **blame annotation** at the end of the current line
-
-- Contains the author, date, and message of the current line's most recent commit (by default)
-- Adds a [_Toggle Line Blame Annotations_](command:gitlens.toggleLineBlame) command to toggle the blame annotation on and off
+## Current Line Blame []()
 
 <p align="center">
   <img src="../../images/docs/current-line-blame.png" alt="Current Line Blame" />
 </p>
 
-Hovering over these blame annotaions will reveal more details and links to explore more about the commit.
+GitLens adds an unobtrusive Git blame annotation at the end of the current line, which shows the author, date, and message of the current line's most recent commit.
+
+💡 Use the [Toggle Line Blame](command:workbench.action.quickOpen?%22>GitLens%3A%20Toggle%20Line%20Blame%22) command from the Command Palette to turn the annotation on and off.
+
+⚙️ Use the settings editor to customize the [current line annotations](command:gitlens.showSettingsPage?%22current-line%22 'Jump to the Current Line Blame settings').
+
+## Hovers
 
 <p align="center">
   <img src="../../images/docs/hovers-current-line.png" alt="Current Line Blame Hover" />
 </p>
+
+Hovering over these blame annotations will reveal more details and links to explore. The **details** hover (the top section) provides many commit details and actions, including autolinks in commit messages, while the **changes** hover (the bottom section) shows a diff of the current line with its previous version and related actions.
+
+⚙️ Use the settings editor to customize the [hovers](command:gitlens.showSettingsPage?%22hovers%22 'Jump to the Hover settings').
+
+## Status Bar Blame
+
+<p align="center">
+  <img src="../../images/docs/status-bar.png" alt="Status Bar Blame" />
+</p>
+
+GitLens also adds Git blame information about the current line to the status bar.
+
+⚙️ Use the settings editor to customize the [status bar](command:gitlens.showSettingsPage?%22status-bar%22 'Jump to the Status Bar settings').

walkthroughs/getting-started/4-git-codelens.md

@@ -4,22 +4,10 @@
   <img src="../../images/docs/code-lens.png" alt="Git CodeLens" />
 </p>
 
-Adds Git authorship **CodeLens** to the top of the file and on code blocks
+GitLens adds Git authorship CodeLens to the top of the file and on code blocks. The **recent change** CodeLens shows the author and date of the most recent commit for the code block or file, while the **authors** CodeLens shows the number of authors of the code block or file and the most prominent author (if there is more than one).
 
-- **Recent Change** &mdash; author and date of the most recent commit for the file or code block
-  - Click the CodeLens to show a **commit file details quick pick menu** with commands for comparing, navigating and exploring commits, and more (by [default](#git-codelens-settings- 'Jump to the Git CodeLens settings'))
-- **Authors** &mdash; number of authors of the file or code block and the most prominent author (if there is more than one)
+Clicking on the CodeLens performs a [customizable](command:gitlens.showSettingsPage?%22code-lens%22 'Jump to the Git CodeLens settings') action. For example, the **recent change** CodeLens will open a quick pick menu with the commit's file details and actions, where as the **authors** will toggle the whole file Git blame annotations.
 
-  - Click the CodeLens to toggle the file Git blame annotations on and off of the whole file (by [default](#git-codelens-settings- 'Jump to the Git CodeLens settings'))
-  - Will be hidden if the author of the most recent commit is also the only author of the file or block, to avoid duplicate information and reduce visual noise
+💡 Use the [Toggle Git CodeLens](command:workbench.action.quickOpen?%22>GitLens%3A%20Toggle%20Git%20CodeLens%22) command to turn the CodeLens on and off.
 
-- Provides [customizable](command:gitlens.showSettingsPage?%22code-lens%22 'Jump to the Git CodeLens settings') click behavior for each CodeLens &mdash; choose between one of the following
-
-  - Toggle file blame annotations on and off
-  - Compare the commit with the previous commit
-  - Show a quick pick menu with details and commands for the commit
-  - Show a quick pick menu with file details and commands for the commit
-  - Show a quick pick menu with the commit history of the file
-  - Show a quick pick menu with the commit history of the current branch
-
-- Adds a _Toggle Git CodeLens_ command (`gitlens.toggleCodeLens`) with a shortcut of `shift+alt+b` to toggle the CodeLens on and off
+⚙️ Use the settings editor to customize the [Git CodeLens](command:gitlens.showSettingsPage?%22code-lens%22 'Jump to the Git CodeLens settings').

walkthroughs/getting-started/6-file-annotations.md

@@ -1,18 +1,43 @@
-## Customizable File Annotations
+## File Annotations
 
-See customizable file annotations in the editor's status bar and in the gutter, the space beside the line number. Choose between:
+<p align="center">
+  <img src="../../images/docs/gutter-toggle.png" alt="Toggle File Annotations" />
+</p>
+
+GitLens adds on-demand annotations for the whole file directly to the editor's scroll bar and in the gutter area, the space beside the line number, to help you gain more insights into your code.
+
+### File Blame
 
-**Blame** – showing the commit and author for each line.
 <p align="center">
   <img src="../../images/docs/gutter-blame.png" alt="Gutter Blame" />
 </p>
 
-**Changes** – highlighting any local, unpublished, changes or lines changed by the most recent commit.
+When activated, GitLens expands the gutter area to show the commit and author for each line of the file, similar to the current line blame. On the right edge of the gutter, an age indicator (heatmap) is shown to provide an easy, at-a-glance way to tell how recently lines were changed (see the Heatmap below for more details). An additional indicator, which highlights other lines that were also changed as part of the current line's commit, is shown both the far left edge and on the scrollbar.
+
+💡 On an active file, use the [Toggle File Blame](command:workbench.action.quickOpen?%22>GitLens%3A%20Toggle%20File%20Blame%22) command from the Command Palette to turn the annotation on and off.
+
+⚙️ Use the settings editor to customize the [file blame](command:gitlens.showSettingsPage?%22blame%22 'Jump to the Gutter Blame settings').
+
+### File Changes
+
 <p align="center">
   <img src="../../images/docs/gutter-changes.png" alt="Gutter Changes" />
 </p>
 
-**Heatmap** – to show how recently lines were changed relative to all the other changes in the file.
+When activated, indicators are shown on the left edge of the gutter to highlight any local, unpublished, changes or lines changed by the most recent commit.
+
+💡 On an active file, use the [Toggle File Changes](command:workbench.action.quickOpen?%22>GitLens%3A%20Toggle%20File%20Changes%22) command from the Command Palette to turn the annotation on and off.
+
+⚙️ Use the settings editor to customize the [file changes](command:gitlens.showSettingsPage?%22changes%22 'Jump to the Gutter Changes settings').
+
+### Heatmap
+
 <p align="center">
   <img src="../../images/docs/gutter-heatmap.png" alt="Gutter Heatmap" />
 </p>
+
+When activated, a color-coded indicator line is shown on the left edge of the gutter to show how recently lines were changed relative to all the other changes in the file. The colors range from hot, orange, to cold, blue, based on the age of the most recent change. Changes are considered cold after 90 days.
+
+💡 On an active file, use the [Toggle File Heatmap](command:workbench.action.quickOpen?%22>GitLens%3A%20Toggle%20File%20Heatmap%22) command from the Command Palette to turn the annotation on and off.
+
+⚙️ Use the settings editor to customize the [file heatmap](command:gitlens.showSettingsPage?%22heatmap%22 'Jump to the Gutter Heatmap settings').

walkthroughs/getting-started/7-git-side-bar-views.md

@@ -5,6 +5,8 @@
   <img src="../../images/docs/views-layout-scm.png" alt="Source Control Side Bar Views" width="45%" />
 </p>
 
-GitLens adds side bar views for Commits, File History, Branches, Remotes, Stashes, Tags, Contributors, and the Search & Compare that provide rich source control details and functionality.
+GitLens adds side bar views for Commits, File History, Branches, Remotes, Stashes, Tags, Contributors, Search & Compare, and more that provide rich source control details and functionality.
 
-These views can be displayed in either the **GitLens** side bar or on the **Source Control** side bar.
+By default, these views can be displayed in either the [GitLens side bar](command:gitlens.views.home.focus 'Open GitLens side bar') or on the [Source Control side bar](command:workbench.scm.focus 'Open Source Control side bar').
+
+💡 Use the [GitLens: Set Views Layout](command:gitlens.setViewsLayout) command from the [Command Palette](command:workbench.action.quickOpen?%22>GitLens%3A%20Set%20Views%20Layout%22) to change the layout, or drag & drop the views individually.

walkthroughs/getting-started/9-git-command-palette.md

@@ -4,4 +4,6 @@
   <img src="../../images/docs/git-command-palette.png" alt="Git command palette"/>
 </p>
 
-The Git Command Palette provides guided, step-by-step access to many common Git commands, as well as quick access to commits (history and search), stashes, and status (current branch and working tree).
+The [Git Command Palette](command:gitlens.gitCommands) provides guided, step-by-step access to many common Git commands, as well as quick access to commits (history and search), stashes, and status (current branch and working tree).
+
+You can quickly navigate and safely execute Git commands through easy-to-use menus where each command can require an explicit confirmation step before executing.

walkthroughs/premium-features/1-intro.md

@@ -1,11 +1,11 @@
 ## Introducing GitLens Premium Features
 
-New premium features like Worktrees and Visual File History can be unlocked with a GitLens Free+ account. Additional premium features like a visual commit graph, and integrations for GitHub Enterprise and GitLab Self-Managed repositories are coming soon.
+New premium features like Worktrees and Visual File History can be unlocked with a GitLens Free+ account. Additional premium features like a visual commit graph, and integrations for GitHub Enterprise and GitLab are coming soon.
 
-**Does this affect existing features?**
+## Does this affect existing features?
 
-No, the introduction of premium features has no impact on GitLens features that existed prior to v12.0, so you won't lose access to any of the GitLens features you know and love. Creating an account simply gives you access to new, premium features that will enable you to get even more out of Git in VS Code!
+No, the introduction of premium features has no impact on existing GitLens features, so you won't lose access to any of the GitLens features you know and love. Creating an account simply gives you access to new, premium features that will enable you to get even more out of Git in VS Code!
 
-Free+ accounts will be able to access premium features on all public repostories, and a paid account will be required to access premium features on private repositories.
+Free+ accounts will be able to access premium features on public repos, and a paid account will be required to access premium features on private repos. All non-premium features will continue to be free without an account.
 
-[Learn More About Premium GitLens Features](https://gitkraken.com/gitlens/premium-features)
+[**Learn More About Premium GitLens Features**](https://gitkraken.com/gitlens/premium-features 'Learn more')

walkthroughs/premium-features/2-worktrees.md

@@ -4,6 +4,6 @@
   <img src="../../images/docs/worktrees-view.png" alt="Worktrees View in Side Bar"/>
 </p>
 
-Worktrees make developing on and testing multiple branches easier, by minimizing the context switching between branches.
+Worktrees make developing on and testing multiple branches easier, by minimizing the context switching between branches. Worktrees allow you to easily work on different branches of a repository simultaneously. You can create multiple working trees, each of which can be opened in individual windows or all together in a single workspace.
 
-*Note: Worktrees do not yet work with VS Code on the web.*
+_Note: Worktrees do not yet work with VS Code on the web._

walkthroughs/premium-features/4-coming-soon.md

@@ -4,4 +4,4 @@
   <img src="../../images/docs/coming-soon-commit-graph.png" alt="Worktrees View in Side Bar"/>
 </p>
 
-You can expect more premium features like a visual commit graph for better repo visualization, and integrations with hosting services like GitHub Enterprise and GitLab Self-Managed.
+You can expect more premium features like a visual commit graph for better repo visualization, and additional integrations with hosting services like GitHub Enterprise and GitLab.