Search & Retrieve

How it works

Every saved context is searchable using hybrid full-text search across titles, reasoning, code snippets, file paths, and commit SHAs. Search results are ranked by relevance with field-weighted scoring — title matches rank highest, followed by domain/topic, then body content. Search works across both local contexts (in .git/gitwhy/contexts/) and cloud workspace contexts (synced via git why push), including team-shared contexts. GitWhy also searches visible WhySpec change folders in gitwhy/changes/, with legacy .gitwhy/changes/ still supported during migration. Results are deduplicated and merged.

Search

CLI
TUI
Web Dashboard
MCP

git why search "JWT tokens"

Output:

  ctx_a1b2c3d4  0.87  JWT implementation setup  [authentication/jwt-implementation]
    We chose JWT because the mobile app needs stateless auth...
    files: api/auth/jwt.go, api/auth/middleware.go
1 result(s) found

Flags:

Flag	Description	Default
`--repo`	Filter to a specific repository (owner/name)	current repo
`--domain`	Filter to a specific domain	all
`--limit`	Max results to return	10 (max 20)
`--local-only`	Skip cloud search	false

Examples:

git why search "authentication"
git why search --domain architecture "billing"
git why search --local-only "middleware"

In a terminal, git why search opens an interactive search view with real-time results as you type.

Search results show context IDs, titles, domains, agents, and dates — navigate and preview inline.

You: "What did we decide about JWT tokens?"

Agent: [calls gitwhy_search(query="JWT tokens")]
GitWhy: [returns ranked results with title, snippet, score, files, and commit SHAs]

The agent can filter by repo or domain:

Agent: [calls gitwhy_search(query="billing", domain="architecture", limit=5)]

Results include context_id, title, snippet, score, repo, domain, files, commit_shas, author, and source (local or cloud).

Cloud search

When authenticated, search automatically queries both your local contexts and your cloud workspace. This means:

Your synced contexts are searchable from any machine
Team-shared contexts (published via gitwhy_publish) are discoverable
Results are deduplicated by context ID — if the same context exists locally and in the cloud, the cloud version (with richer metadata) is preferred

Cloud search uses PostgreSQL full-text search with field-weighted ranking on the server side.

Retrieve

git why get ctx_a1b2c3d4

Prints the full structured markdown to stdout.

You: "Get context ctx_a1b2c3d4"

Agent: [calls gitwhy_get(id="ctx_a1b2c3d4")]
GitWhy: [returns full structured markdown]

Browse

CLI
TUI
Web Dashboard
MCP

git why log

Shows all saved contexts with summary info: context ID, date, title, agent, domain, and topic.

In a terminal, git why log opens an interactive log browser.

TUI log view with context list navigation

Browse all saved contexts with their linked commits, agents, and domains.

You: "List all contexts in the authentication domain."

Agent: [calls gitwhy_list(domain="authentication")]
GitWhy: [returns domain/topic tree with context summaries]

Getting Started

Core Features

Sharing & Collaboration

Interfaces

Integration Guide

CLI Reference

Context Format

Plans & Pricing

Search & Retrieve

How it works

Search

Cloud search

Retrieve

Browse

​How it works

​Search

​Cloud search

​Retrieve

​Browse

How it works

Search

Cloud search

Retrieve

Browse