Adds git notes support via ${notes} format token - closes #2432

- Adds ${notes} token to CommitFormatter for inline blame, hovers, and status bar

- Adds %N to log parser commits mapping for notes from git log

- Adds getCommitNotes() sub-provider method using git notes show

- Adds ensureNotes() on GitCommit with @gate() and cancellation support

- Adds notes to settings preview and settings HTML token documentation

- Updates logParser tests for new notes field

Author: Mattwmaster58

CHANGELOG.md

@@ -8,6 +8,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/) and this p
 
 ### Added
 
+- Adds support for displaying git notes in blame annotations, hovers, and status bar via the `${notes}` format token ([#2432](https://github.com/gitkraken/vscode-gitlens/issues/2432)) thanks to [PR #5085](5085) by Matt M ([@Mattwmaster58](https://github.com/Mattwmaster58))
 - Adds a conflict files panel to the _Interactive Rebase_ editor — shows conflicting files with per-file conflict counts, conflict status indicators, and actions to view current or incoming changes ([#5040](https://github.com/gitkraken/vscode-gitlens/issues/5040))
 - Adds branch activity dates to the _Home_ view recents — sorts by most recent activity and displays the most relevant activity label ([#5034](https://github.com/gitkraken/vscode-gitlens/issues/5034))
 

README.md

@@ -448,6 +448,7 @@ A big thanks to the people that have contributed to this project 🙏❤️:
 - JounQin ([@JounQin](https://github.com/JounQin)) — [contributions](https://github.com/gitkraken/vscode-gitlens/commits?author=JounQin)
 - Noritaka Kobayashi ([@noritaka1166](https://github.com/noritaka1166)) — [contributions](https://github.com/gitkraken/vscode-gitlens/commits?author=noritaka1166)
 - Daniel Asher ([@danielasher115](https://github.com/danielasher115)) — [contributions](https://github.com/gitkraken/vscode-gitlens/commits?author=danielasher115)
+- Matt M ([@Mattwmaster58](https://github.com/Mattwmaster58)) — [contributions](https://github.com/gitkraken/vscode-gitlens/commits?author=Mattwmaster58)
 
 Also special thanks to the people that have provided support, testing, brainstorming, etc:
 

src/annotations/lineAnnotationController.ts

@@ -287,6 +287,19 @@ export class LineAnnotationController implements Disposable {
 				? this.container.git.getRepositoryService(repoPath).getBranchesAndTagsTipsLookup()
 				: undefined;
 
+		const getNotesForLines = !uncommittedOnly && repoPath != null && CommitFormatter.has(cfg.format, 'notes');
+		if (getNotesForLines) {
+			const seen = new Set<string>();
+			await Promise.allSettled(
+				Array.from(lines.values(), state => {
+					if (state.commit.isUncommitted || seen.has(state.commit.ref)) return Promise.resolve();
+					seen.add(state.commit.ref);
+					return state.commit.ensureNotes(cancellation);
+				}),
+			);
+		}
+		if (cancellation.isCancellationRequested) return;
+
 		async function updateDecorations(
 			container: Container,
 			editor: TextEditor,

src/env/node/git/sub-providers/commits.ts

@@ -114,6 +114,20 @@ export class CommitsGitSubProvider implements GitCommitsSubProvider {
 		return log.commits.get(rev) ?? first(log.commits.values());
 	}
 
+	@debug({ exit: true })
+	async getCommitNotes(repoPath: string, rev: string, cancellation?: CancellationToken): Promise<string | undefined> {
+		const result = await this.git.exec(
+			{ cwd: repoPath, cancellation: cancellation, errors: 'ignore' },
+			'notes',
+			'show',
+			rev,
+		);
+		if (result.cancelled || cancellation?.isCancellationRequested) throw new CancellationError();
+
+		const data = result.stdout.trim();
+		return data || undefined;
+	}
+
 	@debug({ exit: true })
 	async getCommitCount(repoPath: string, rev: string, cancellation?: CancellationToken): Promise<number | undefined> {
 		const result = await this.git.exec(
@@ -1394,6 +1408,7 @@ function createCommit(
 ) {
 	const message = c.message.trim();
 	const index = message.indexOf('\n');
+	const notes = c.notes?.trim() || null;
 
 	return new GitCommit(
 		container,
@@ -1416,6 +1431,10 @@ function createCommit(
 		c.stats,
 		undefined,
 		c.tips?.split(' '),
+		undefined,
+		undefined,
+		undefined,
+		notes,
 	);
 }
 

src/git/formatters/commitFormatter.ts

@@ -119,6 +119,7 @@ export interface CommitFormatOptions extends FormatOptions {
 		id?: TokenOptions;
 		link?: TokenOptions;
 		message?: TokenOptions;
+		notes?: TokenOptions;
 		pullRequest?: TokenOptions;
 		pullRequestAgo?: TokenOptions;
 		pullRequestAgoOrDate?: TokenOptions;
@@ -715,6 +716,10 @@ export class CommitFormatter extends Formatter<GitCommit, CommitFormatOptions> {
 		);
 	}
 
+	get notes(): string {
+		return this._padOrTruncate(this._item.notes ?? '', this._options.tokenOptions.notes);
+	}
+
 	get id(): string {
 		const sha = this._padOrTruncate(this._item.shortSha ?? '', this._options.tokenOptions.id);
 		if (this._options.outputFormat !== 'plaintext' && this._options.unpublished) {

src/git/gitProvider.ts

@@ -339,6 +339,7 @@ export interface GitCommitsSubProvider {
 		options?: { firstIfNotFound?: boolean | undefined },
 		cancellation?: CancellationToken,
 	): Promise<GitCommit | undefined>;
+	getCommitNotes?(repoPath: string, rev: string, cancellation?: CancellationToken): Promise<string | undefined>;
 	getIncomingActivity?(
 		repoPath: string,
 		options?: IncomingActivityOptions,

src/git/models/commit.ts

@@ -1,4 +1,5 @@
 /* eslint-disable @typescript-eslint/no-restricted-imports -- TODO need to deal with sharing rich class shapes to webviews */
+import type { CancellationToken } from 'vscode';
 import { Uri } from 'vscode';
 import type { EnrichedAutolink } from '../../autolinks/models/autolinks.js';
 import { getAvatarUri, getCachedAvatarUri } from '../../avatars.js';
@@ -88,11 +89,13 @@ export class GitCommit implements GitRevisionReference {
 		stashName?: string | undefined,
 		stashOnRef?: string | undefined,
 		parentTimestamps?: GitStashParentInfo[] | undefined,
+		notes?: string | null | undefined,
 	) {
 		this.ref = sha;
 		this.shortSha = sha.substring(0, this.container.CommitShaFormatting.length);
 		this.tips = tips;
 		this.parentTimestamps = parentTimestamps;
+		this._notes = notes;
 
 		if (stashName) {
 			this.refType = 'stash';
@@ -132,6 +135,11 @@ export class GitCommit implements GitRevisionReference {
 		this.lines = ensureArray(lines) ?? [];
 	}
 
+	private _notes: string | undefined | null;
+	get notes(): string | undefined {
+		return this._notes ?? undefined;
+	}
+
 	get date(): Date {
 		return this.container.CommitDateFormatting.dateSource === 'committed' ? this.committer.date : this.author.date;
 	}
@@ -588,6 +596,14 @@ export class GitCommit implements GitRevisionReference {
 		return this.author.getCachedAvatarUri(options);
 	}
 
+	@gate()
+	async ensureNotes(cancellation?: CancellationToken): Promise<void> {
+		if (this.isUncommitted || this._notes !== undefined) return;
+
+		const svc = this.container.git.getRepositoryService(this.repoPath);
+		this._notes = (await svc.commits.getCommitNotes?.(this.sha, cancellation)) ?? null;
+	}
+
 	async getSignature(): Promise<CommitSignature | undefined> {
 		if (this.isUncommitted) return undefined;
 		if (this._signature === null) return undefined;
@@ -745,6 +761,7 @@ export class GitCommit implements GitRevisionReference {
 			this.stashName,
 			this.stashOnRef,
 			this.getChangedValue(changes.parentTimestamps, this.parentTimestamps),
+			this._notes,
 		) as T;
 	}
 
@@ -771,6 +788,7 @@ export class GitCommit implements GitRevisionReference {
 					this.stashName,
 					this.stashOnRef,
 					this.parentTimestamps,
+					this._notes,
 				) as T);
 	}
 

src/git/parsers/__tests__/logParser.test.ts

@@ -23,7 +23,7 @@ suite('Log Parser - File Parsing Test Suite', () => {
 	}
 
 	// Helper to create a mock commit record with files
-	// Format from commitsMapping: sha, author, authorEmail, authorDate, committer, committerEmail, committerDate, parents, tips, message
+	// Format from commitsMapping: sha, author, authorEmail, authorDate, committer, committerEmail, committerDate, parents, tips, notes, message
 	// The file content comes as a separate field AFTER the message field
 	function createCommitRecord(
 		sha: string,
@@ -35,8 +35,8 @@ suite('Log Parser - File Parsing Test Suite', () => {
 		// File content: --raw lines first, then --numstat lines, separated by newlines
 		const fileContent = [...rawLines, ...numstatLines].join('\n');
 
-		// Format: recordSep + 10 mapped fields + 1 file content field, all separated by fieldSep
-		// When fieldCount === keys.length (10), the parser reads the file content field
+		// Format: recordSep + 11 mapped fields + 1 file content field, all separated by fieldSep
+		// When fieldCount === keys.length (11), the parser reads the file content field
 		const fields = [
 			sha, // sha (field 0)
 			'Test Author', // author (field 1)
@@ -47,8 +47,9 @@ suite('Log Parser - File Parsing Test Suite', () => {
 			'1234567890', // committerDate (field 6)
 			'', // parents (field 7)
 			'', // tips (field 8)
-			'Test commit message', // message (field 9)
-			fileContent, // file content (field 10, parsed when fieldCount === 10)
+			'', // notes (field 9)
+			'Test commit message', // message (field 10)
+			fileContent, // file content (field 11, parsed when fieldCount === 11)
 		];
 		return recordSep + fields.join(fieldSep);
 	}

src/git/parsers/logParser.ts

@@ -14,6 +14,7 @@ const commitsMapping = {
 	committerDate: '%ct',
 	parents: '%P',
 	tips: '%D',
+	notes: '%N',
 	message: '%B',
 };
 

src/hovers/hovers.ts

@@ -245,13 +245,17 @@ export async function detailsMessage(
 		!commit.isUncommitted &&
 		CommitFormatter.has(options.format, 'signature');
 
+	const showNotes =
+		!commit.isUncommitted && commit.notes === undefined && CommitFormatter.has(options.format, 'notes');
+
 	const [
 		enrichedAutolinksResult,
 		prResult,
 		presenceResult,
 		previousLineComparisonUrisResult,
 		_fullDetailsResult,
 		signedResult,
+		_notesResult,
 	] = await Promise.allSettled([
 		enhancedAutolinks
 			? pauseOnCancelOrTimeoutMapTuplePromise(
@@ -279,6 +283,7 @@ export async function detailsMessage(
 			: undefined,
 		commit.message == null ? commit.ensureFullDetails() : undefined,
 		showSignature ? commit.isSigned() : undefined,
+		showNotes ? commit.ensureNotes(options?.cancellation) : undefined,
 	]);
 
 	if (options?.cancellation?.isCancellationRequested) return undefined;