Add file and directory filtering on compare page

docs/code-search/compare-file-filtering.mdx

@@ -0,0 +1,118 @@
+# File Filtering in the Repository Comparison Page
+
+The repository comparison page provides powerful file filtering capabilities that allow you to focus on specific files in a comparison. The system supports multiple ways to specify which files you want to view when comparing branches, tags, or commits.
+
+## Query parameter-based file filtering
+
+The comparison page supports three different query parameters to specify which files to include in the comparison:
+
+### 1. Individual file paths
+
+You can specify individual files using either of these parameters:
+
+- `filePath=path/to/file.js` - Primary parameter for specifying files
+- `f=path/to/file.js` - Shorthand alternative
+
+Multiple files can be included by repeating the parameter:
+
+```shell
+?filePath=src/index.ts&filePath=src/components/Button.tsx
+```
+
+### 2. Compressed file lists
+
+For comparisons with a large number of files, the system supports compressed file lists (newline-separated):
+
+- `compressedFileList=base64EncodedCompressedData` - Efficiently packs many file paths
+
+This parameter efficiently transmits large file paths using base64-encoded, gzip-compressed data. The compression allows hundreds or thousands of files to be included in a URL without exceeding length limits, which vary depending on the browser, HTTP server, and other services involved, like Cloudflare.
+
+```typescript
+// Behind the scenes, the code decompresses file lists using:
+const decodedData = atoburl(compressedFileList)
+const compressedData = Uint8Array.from([...decodedData].map(char => char.charCodeAt(0)))
+const decompressedData = pako.inflate(compressedData, { to: 'string' })
+```
+
+One way to create a list of files for the `compressedFileList` parameter is to use Python's built-in libraries to compress and encode using url-safe base64 encoding (smaller than base64-encoding, then url-encoding).
+
+```shell
+python3 -c "import sys, zlib, base64; sys.stdout.write(base64.urlsafe_b64encode(zlib.compress(sys.stdin.buffer.read())).decode().rstrip('='))" < list.of.files > list.of.files.deflated.b64url
+```
+
+### 3. Special focus mode
+
+You can focus on a single file using:
+
+- `focus=true&filePath=path/to/specific/file.js` - Show only this file in detail view
+
+## File filtering UI components
+
+The comparison view provides several UI components to help you filter and navigate files:
+
+### FileDiffPicker
+
+The FileDiffPicker component allows you to:
+
+- Search for files by name or path
+- Filter files by type/extension
+- Toggle between showing all files or only modified files
+- Sort files by different criteria (path, size of change, etc.)
+
+This component uses a dedicated file metadata query optimized for quick filtering. Results are displayed as you type. Through client-side filtering, the component can efficiently handle repositories with thousands of files.
+
+### File navigation
+
+When viewing diffs, you can:
+
+- Click on any file in the sidebar to switch to that file
+- Use keyboard shortcuts to navigate between files
+- Toggle between expanded and collapsed views of files
+- Show or hide specific changes (additions, deletions, etc.)
+
+### URL-based filtering
+
+Any filters you apply through the UI will update the URL with the appropriate query parameters. This means you can:
+
+1. Share specific filtered views with others
+2. Bookmark comparisons with specific file filters
+3. Navigate back and forth between different filter states using browser history
+
+## Implementation details
+
+The system makes strategic performance trade-offs to provide a smooth user experience:
+
+```typescript
+/*
+ * For customers with extremely large PRs with thousands of files,
+ * we fetch all file paths in a single API call to enable client-side filtering.
+ *
+ * This eliminates numerous smaller API calls for server-side filtering
+ * when users search in the FileDiffPicker. While requiring one large
+ * initial API call, it significantly improves subsequent search performance.
+ */
+```
+
+The file filtering system uses a specialized file metadata query that is faster and lighter than the comprehensive file diffs query used to display actual code changes.
+
+## Usage examples
+
+1. View only JavaScript files:
+
+```bash
+ ?filePath=src/utils.js&filePath=src/components/App.js
+```
+
+2. Focus on a single file:
+
+```bash
+ ?focus=true&filePath=src/components/Button.tsx
+ ```
+
+3. Use a compressed file list for many files:
+
+```bash
+ ?compressedFileList=H4sIAAAAAAAAA2NgYGBg...
+```
+
+This flexible filtering system allows you to create customized views of repository comparisons, making reviewing changes in large projects easier.

docs/code-search/features.mdx

@@ -120,6 +120,15 @@ Here is an example of search results with personalized search ranking enabled:
 
 As you can see, the results are now ranked based on their relevance to the query, and the results from repositories you've recently contributed to are boosted.
 
+## Compare changes across revisions
+
+When you run a search, you can compare the results from two different revisions of the codebase. From your search query results page, click the three-dot **...** icon next to the **Contributors** tab. Then select the **Compare** option.
+
+From here, you can execute file and directory filtering and compare large diffs, making it easier to navigate and manage.
+
+This file picker is useful when comparing branches with thousands of changed files and allows you to select specific files or directories to focus on. You can [filter files directly](/code-search/compare-file-filtering) by constructing a URL with multiple file paths or use a compressed file list for even larger selections.
+
+![file-and-directory-filtering](https://storage.googleapis.com/sourcegraph-assets/Docs/filter-by-file-dir-on-compare.png)
 
 ## Other search tips