Closes #4723 adds ref & range to commit search

 - Adds a `ref:` search operator to filter commits by specific references (branches, tags, SHAs) or commit ranges (e.g., `main..feature`, `HEAD~5..HEAD`)
 - Enhances the Git search command with a dedicated quick pick and button for selecting references or inputting ranges
 - Adds natural language search understanding by documenting the `ref:` operator in AI prompts

Author: eamodio

CHANGELOG.md

@@ -9,6 +9,8 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/) and this p
 ### Added
 
 - Adds a new _Safe Hard Reset_ (`--keep`) option to Git _reset_ command
+- Adds support for reference or range commit searches on the _Commit Graph_, _Search & Compare_ view, and in the _Search Commits_ command ([#4723](https://github.com/gitkraken/vscode-gitlens/issues/4723))
+  - Adds natural language support to allow for more powerful queries
 
 ### Changed
 

src/commands/git/search.ts

@@ -12,6 +12,7 @@ import { showContributorsPicker } from '../../quickpicks/contributorsPicker';
 import type { QuickPickItemOfT } from '../../quickpicks/items/common';
 import { ActionQuickPickItem, createQuickPickSeparator } from '../../quickpicks/items/common';
 import { isDirectiveQuickPickItem } from '../../quickpicks/items/directive';
+import { ReferencesQuickPickIncludes, showReferencePicker2 } from '../../quickpicks/referencePicker';
 import { configuration } from '../../system/-webview/configuration';
 import { getContext } from '../../system/-webview/context';
 import { first, join, map } from '../../system/iterable';
@@ -53,6 +54,11 @@ const UseFolderPickerQuickInputButton: QuickInputButton = {
 	tooltip: 'Pick Folder',
 };
 
+const UseRefPickerQuickInputButton: QuickInputButton = {
+	iconPath: new ThemeIcon('git-branch'),
+	tooltip: 'Pick Reference',
+};
+
 interface Context {
 	container: Container;
 	repos: Repository[];
@@ -94,6 +100,8 @@ const searchOperatorToTitleMap = new Map<SearchOperators, string>([
 	['since:', 'Search After Date'],
 	['before:', 'Search Before Date'],
 	['until:', 'Search Before Date'],
+	['^:', 'Search by Reference or Range'],
+	['ref:', 'Search by Reference or Range'],
 ]);
 
 type SearchStepState<T extends State = State> = ExcludeSome<StepState<T>, 'repo', string>;
@@ -299,23 +307,30 @@ export class SearchGitCommand extends QuickCommand<State> {
 		const items: QuickPickItemOfT<Items>[] = [
 			{
 				label: searchOperatorToTitleMap.get('')!,
-				description: `pattern or message: pattern or =: pattern ${GlyphChars.Dash} use quotes to search for phrases`,
+				description: `<message> or message:<message> or =:<message> ${GlyphChars.Dash} use quotes to search for phrases`,
 				alwaysShow: true,
 				item: { type: 'add', operator: 'message:' },
 			},
 			{
 				label: searchOperatorToTitleMap.get('author:')!,
-				description: 'author: pattern or @: pattern',
+				description: 'author:<author> or @:<author>',
 				buttons: [UseAuthorPickerQuickInputButton],
 				alwaysShow: true,
 				item: { type: 'add', operator: 'author:' },
 			},
 			{
 				label: searchOperatorToTitleMap.get('commit:')!,
-				description: 'commit: sha or #: sha',
+				description: '<sha> or commit:<sha> or #:<sha>',
 				alwaysShow: true,
 				item: { type: 'add', operator: 'commit:' },
 			},
+			{
+				label: searchOperatorToTitleMap.get('ref:')!,
+				description: 'ref:<ref> or ^:<ref> (supports ranges like main..feature)',
+				buttons: [UseRefPickerQuickInputButton],
+				alwaysShow: true,
+				item: { type: 'add', operator: 'ref:' },
+			},
 		];
 
 		if (!context.hasVirtualFolders) {
@@ -428,6 +443,8 @@ export class SearchGitCommand extends QuickCommand<State> {
 						state,
 						context,
 					);
+				} else if (button === UseRefPickerQuickInputButton) {
+					await updateSearchQuery(item.item.operator, { ref: true }, quickpick, step, state, context);
 				}
 
 				return false;
@@ -516,7 +533,7 @@ export class SearchGitCommand extends QuickCommand<State> {
 
 async function updateSearchQuery(
 	operator: SearchOperatorsLongForm,
-	usePickers: { author?: boolean; file?: { type: 'file' | 'folder' } },
+	usePickers: { author?: boolean; file?: { type: 'file' | 'folder' }; ref?: boolean },
 	quickpick: QuickPick<any>,
 	step: QuickPickStep,
 	state: SearchStepState,
@@ -594,9 +611,30 @@ async function updateSearchQuery(
 			append = true;
 		}
 
-		if (files == null || files.size === 0) {
+		if (!files?.size) {
 			ops.delete('file:');
 		}
+	} else if (usePickers?.ref && operator === 'ref:') {
+		using _frozen = step.freeze?.();
+
+		const refs = ops.get('ref:');
+
+		const pick = await showReferencePicker2(
+			state.repo.path,
+			'Search by Reference or Range',
+			'Choose a reference to search',
+			{
+				allowedAdditionalInput: { range: true, rev: false },
+				include: ReferencesQuickPickIncludes.All,
+				picked: refs && first(refs),
+			},
+		);
+
+		if (pick.value != null) {
+			ops.set('ref:', new Set([pick.value.ref]));
+		} else {
+			append = true;
+		}
 	} else {
 		const values = ops.get(operator);
 		append = !values?.has('');

src/commands/quickCommand.steps.ts

@@ -525,9 +525,7 @@ export function getValidateGitReferenceFn(
 
 				if (!getSettledValue(leftResult, false) || !getSettledValue(rightResult, false)) {
 					quickpick.items = [
-						createDirectiveQuickPickItem(Directive.Noop, true, {
-							label: `Invalid Range: ${value}`,
-						}),
+						createDirectiveQuickPickItem(Directive.Noop, true, { label: `Invalid Range: ${value}` }),
 					];
 					return true;
 				}

src/constants.search.ts

@@ -1,4 +1,4 @@
-type SearchOperatorsShortForm = '' | '=:' | '@:' | '#:' | '?:' | '~:' | 'is:' | '>:' | '<:';
+type SearchOperatorsShortForm = '' | '=:' | '@:' | '#:' | '?:' | '~:' | 'is:' | '>:' | '<:' | '^:';
 export type SearchOperatorsLongForm =
 	| 'message:'
 	| 'author:'
@@ -9,7 +9,8 @@ export type SearchOperatorsLongForm =
 	| 'after:'
 	| 'since:'
 	| 'before:'
-	| 'until:';
+	| 'until:'
+	| 'ref:';
 export type SearchOperators = SearchOperatorsShortForm | SearchOperatorsLongForm;
 
 export const searchOperators = new Set<string>([
@@ -32,6 +33,8 @@ export const searchOperators = new Set<string>([
 	'<:',
 	'before:',
 	'until:',
+	'^:',
+	'ref:',
 ]);
 
 export const searchOperatorsToLongFormMap = new Map<SearchOperators, SearchOperatorsLongForm>([
@@ -54,10 +57,12 @@ export const searchOperatorsToLongFormMap = new Map<SearchOperators, SearchOpera
 	['<:', 'before:'],
 	['before:', 'before:'],
 	['until:', 'before:'],
+	['^:', 'ref:'],
+	['ref:', 'ref:'],
 ]);
 
 export const searchOperationHelpRegex =
-	/(?:^|(\b|\s)*)((=:|message:|@:|author:|#:|commit:|\?:|file:|~:|change:|is:|type:|>:|after:|since:|<:|before:|until:)(?:"[^"]*"?|\w*))(?:$|(\b|\s))/g;
+	/(?:^|(\b|\s)*)((=:|message:|@:|author:|#:|commit:|\?:|file:|~:|change:|is:|type:|>:|after:|since:|<:|before:|until:|\^:|ref:)(?:"[^"]*"?|[^\s]*))(?:$|(\b|\s))/g;
 
 export interface SearchQuery {
 	query: string;

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

@@ -1041,7 +1041,6 @@ export class CommitsGitSubProvider implements GitCommitsSubProvider {
 			const similarityThreshold = configuration.get('advanced.similarityThreshold');
 			const args = [
 				'log',
-
 				...parser.arguments,
 				`-M${similarityThreshold == null ? '' : `${similarityThreshold}%`}`,
 				'--use-mailmap',
@@ -1055,7 +1054,8 @@ export class CommitsGitSubProvider implements GitCommitsSubProvider {
 			if (shas?.size) {
 				stdin = join(shas, '\n');
 				args.push('--no-walk');
-			} else {
+			} else if (!filters.refs) {
+				// Don't include stashes when using ref: filter, as they would add unrelated commits
 				// TODO@eamodio this is insanity -- there *HAS* to be a better way to get git log to return stashes
 				({ stdin, stashes } = convertStashesToStdin(
 					await this.provider.stash?.getStash(repoPath, undefined, cancellation),

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

@@ -663,11 +663,14 @@ export class GraphGitSubProvider implements GitGraphSubProvider {
 				args.push('--no-walk');
 
 				remappedIds = new Map();
-			} else {
+			} else if (!filters.refs) {
+				// Don't include stashes when using ref: filter, as they would add unrelated commits
 				// TODO@eamodio this is insanity -- there *HAS* to be a better way to get git log to return stashes
 				({ stdin, stashes, remappedIds } = convertStashesToStdin(
 					await this.provider.stash?.getStash(repoPath, undefined, cancellation),
 				));
+			} else {
+				remappedIds = new Map();
 			}
 
 			if (stdin) {

src/git/search.ts

@@ -5,6 +5,7 @@ import type { Source } from '../constants.telemetry';
 import type { Container } from '../container';
 import type { NaturalLanguageSearchOptions } from '../plus/search/naturalLanguageSearchProcessor';
 import { NaturalLanguageSearchProcessor } from '../plus/search/naturalLanguageSearchProcessor';
+import { some } from '../system/iterable';
 import type { GitRevisionReference } from './models/reference';
 import type { GitUser } from './models/user';
 import { isSha, shortenRevision } from './utils/revision.utils';
@@ -185,6 +186,8 @@ export interface SearchQueryFilters {
 	files: boolean;
 	/** Specifies whether the search results will be filtered to a specific type, only `stash` is supported */
 	type?: 'stash';
+	/** Specifies whether the search results will be filtered to a specific ref or ref range */
+	refs: boolean;
 }
 
 export interface SearchQueryCommand {
@@ -207,6 +210,7 @@ export function parseSearchQueryCommand(search: SearchQuery, currentUser: GitUse
 	const filters: SearchQueryFilters = {
 		files: false,
 		type: undefined,
+		refs: false,
 	};
 
 	let op;
@@ -225,10 +229,6 @@ export function parseSearchQueryCommand(search: SearchQuery, currentUser: GitUse
 		shas = searchArgs;
 	} else {
 		searchArgs.add('--all');
-		searchArgs.add(search.matchRegex ? '--extended-regexp' : '--fixed-strings');
-		if (search.matchRegex && !search.matchCase) {
-			searchArgs.add('--regexp-ignore-case');
-		}
 
 		for ([op, values] of operations.entries()) {
 			switch (op) {
@@ -355,6 +355,31 @@ export function parseSearchQueryCommand(search: SearchQuery, currentUser: GitUse
 
 					break;
 				}
+
+				case 'ref:':
+					for (let value of values) {
+						if (!value) continue;
+
+						if (value.startsWith('"') && value.endsWith('"')) {
+							value = value.slice(1, -1);
+							if (!value) continue;
+						}
+
+						filters.refs = true;
+						// Replace --all with the specific ref or ref range
+						searchArgs.delete('--all');
+						searchArgs.add(value);
+					}
+
+					break;
+			}
+		}
+
+		// Add regex/string matching flags if we have (--grep, --author) patterns
+		if (some(searchArgs.values(), arg => arg.startsWith('--grep=') || arg.startsWith('--author='))) {
+			searchArgs.add(search.matchRegex ? '--extended-regexp' : '--fixed-strings');
+			if (search.matchRegex && !search.matchCase) {
+				searchArgs.add('--regexp-ignore-case');
 			}
 		}
 	}

src/plus/ai/prompts.ts

@@ -351,14 +351,18 @@ Available search operators:
 - 'file:' - Search by file path (e.g. 'file:"package.json"', 'file:"*.ts"'); maps to \`git log -- <value>\`
 - 'change:' - Search by specific code changes using regular expressions (e.g. 'change:"function.*auth"', 'change:"import.*react"'); maps to \`git log -G<value>\`
 - 'type:' - Search by type -- only stash is currently supported (e.g. 'type:stash')
+- 'ref:' - Search for commits reachable by a reference (branch, tag, commit) or reference range. Supports single refs (e.g. 'ref:main', 'ref:v1.0'), two-dot ranges (e.g. 'ref:main..feature' for commits in feature but not in main), three-dot ranges (e.g. 'ref:main...feature' for symmetric difference), and relative refs (e.g. 'ref:HEAD~5..HEAD'); maps to \`git log <ref>\`
 - 'after:' - Search for commits after a certain date or range (e.g. 'after:2023-01-01', 'after:"6 months ago"', 'after:"last Tuesday"', 'after:"noon"', 'after:"1 month 2 days ago"'); maps to \`git log --since=<value>\`
 - 'before:' - Search for commits before a certain date or range (e.g. 'before:2023-01-01', 'before:"6 months ago"', 'before:"yesterday"', 'before:"3PM GMT"'); maps to \`git log --until=<value>\`
 
-File and change values should be double-quoted. You can use multiple message, author, file, and change operators at the same time if needed.
+File and change values should be double-quoted. You can use multiple message, author, file, change, and ref operators at the same time if needed.
+
+Use 'ref:' when the query involves exploring commit history within or between specific references. Use temporal operators ('after:', 'before:') for date-based filtering. These operators can be combined when appropriate.
+
+IMPORTANT: When "after" or "since" is used with a reference (branch, tag, commit SHA), it refers to commit ancestry, not time. Use ref ranges (e.g., 'ref:v1.0..HEAD' for "commits after tag v1.0"). Only use 'after:' for actual dates or time expressions.
+
+Temporal queries leverage Git's 'approxidate' parser, which understands relative date expressions like "yesterday", "5 minutes ago", "1 month 2 days ago", "last Tuesday", "noon", and explicit timezones like "3PM GMT".
 
-Temporal queries should be converted to appropriate after and/or before operators, leveraging Git's powerful 'approxidate' parser, which understands a wide array of human-centric relative date expressions, including simple terms ("yesterday", "5 minutes ago"), combinations of time units ("1 month 2 days ago"), days of the week ("last Tuesday"), named times ("noon"), and explicit timezones ("3PM GMT").
-For specific temporal ranges, e.g. commits made last week, or commits in the last month, use the 'after:' and 'before:' operators with appropriate relative values or calculate absolute dates, using the current date provided below.
-For ambiguous time periods like "this week" or "this month", prefer simple relative expressions like "1 week ago" or absolute dates using the current date provided below.
 
 The current date is \${date}
 \${context}

src/plus/integrations/providers/github/utils/-webview/search.utils.ts

@@ -64,6 +64,7 @@ export async function getQueryArgsFromSearchQuery(
 			case 'type:':
 			case 'file:':
 			case 'change:':
+			case 'ref:':
 				// Not supported in GitHub search
 				break;
 

src/webviews/apps/shared/components/search/search-input.ts

@@ -640,6 +640,11 @@ export class GlSearchInput extends GlElement {
 				return html`<span>Author: use a user's account, e.g. <code>author:eamodio</code></span>`;
 			case 'commit:':
 				return html`<span>Commit: use a full or short Commit SHA, e.g. <code>commit:4ce3a</code></span>`;
+			case 'ref:':
+				return html`<span
+					>Ref: use a reference (branch, tag, etc) or reference range, e.g. <code>ref:main</code> or
+					<code>ref:main..feature</code></span
+				>`;
 			case 'type:':
 				return html`<span
 					>Type: use <code>stash</code> to search only stashes, e.g. <code>type:stash</code></span
@@ -710,6 +715,11 @@ export class GlSearchInput extends GlElement {
 						Commit SHA <small>commit: or #:</small>
 					</button>
 				</menu-item>
+				<menu-item role="none">
+					<button class="menu-button" type="button" @click="${() => this.handleInsertToken('ref:')}">
+						Ref <small>ref: or ^:</small>
+					</button>
+				</menu-item>
 				<menu-item role="none">
 					<button class="menu-button" type="button" @click="${() => this.handleInsertToken('type:stash')}">
 						Type <small>type:stash or is:stash</small>