From bee8357f88e8bccb5943c3e6b33c451ebada9fd9 Mon Sep 17 00:00:00 2001 From: Maedah Batool Date: Wed, 30 Apr 2025 14:03:23 -0700 Subject: [PATCH 1/4] Add file and directory filtering on compare page --- docs/code-search/features.mdx | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/code-search/features.mdx b/docs/code-search/features.mdx index 345d284b6..95d31999c 100644 --- a/docs/code-search/features.mdx +++ b/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 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 From 956e95f5b1ed55d033ded7b952bb3b877bc425c3 Mon Sep 17 00:00:00 2001 From: Peter Guy Date: Wed, 30 Apr 2025 16:11:14 -0700 Subject: [PATCH 2/4] Add page for compare file filtering --- docs/code-search/compare-file-filtering.mdx | 116 ++++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 docs/code-search/compare-file-filtering.mdx diff --git a/docs/code-search/compare-file-filtering.mdx b/docs/code-search/compare-file-filtering.mdx new file mode 100644 index 000000000..f066cc4d6 --- /dev/null +++ b/docs/code-search/compare-file-filtering.mdx @@ -0,0 +1,116 @@ +# 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: + +``` +?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 uses base64-encoded, gzip-compressed data to efficiently transmit large sets of file paths. The compression makes it possible to include hundreds or thousands of files in a URL without exceeding length limits. The length limits 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 (which is 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, with results displayed instantly as you type. The component can efficiently handle repositories with thousands of files through client-side filtering. + +### 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 certain types of 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 more lightweight than the comprehensive file diffs query used for displaying actual code changes. + +## Usage Examples + +1. View only JavaScript files: + + ``` + ?filePath=src/utils.js&filePath=src/components/App.js + ``` + +2. Focus on a single file: + + ``` + ?focus=true&filePath=src/components/Button.tsx + ``` + +3. Use compressed file list for many files: + ``` + ?compressedFileList=H4sIAAAAAAAAA2NgYGBg... + ``` + +This flexible filtering system allows you to create customized views of repository comparisons, making it easier to review changes in large projects. From 40ce3ebf07fa0712bf55d445c444811083849740 Mon Sep 17 00:00:00 2001 From: Peter Guy Date: Wed, 30 Apr 2025 16:30:36 -0700 Subject: [PATCH 3/4] Add link to the new page --- docs/code-search/features.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/code-search/features.mdx b/docs/code-search/features.mdx index 95d31999c..0c8ac9a7d 100644 --- a/docs/code-search/features.mdx +++ b/docs/code-search/features.mdx @@ -126,7 +126,7 @@ When you run a search, you can compare the results from two different revisions 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 by constructing a URL with multiple file paths or use a compressed file list for even larger selections. +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) From 03f6f9bde4280861b985c51939d9bcf431557c2d Mon Sep 17 00:00:00 2001 From: Maedah Batool Date: Wed, 30 Apr 2025 17:13:38 -0700 Subject: [PATCH 4/4] add small tweaks --- docs/code-search/compare-file-filtering.mdx | 54 +++++++++++---------- 1 file changed, 28 insertions(+), 26 deletions(-) diff --git a/docs/code-search/compare-file-filtering.mdx b/docs/code-search/compare-file-filtering.mdx index f066cc4d6..b2bd3776f 100644 --- a/docs/code-search/compare-file-filtering.mdx +++ b/docs/code-search/compare-file-filtering.mdx @@ -2,11 +2,11 @@ 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 +## 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 +### 1. Individual file paths You can specify individual files using either of these parameters: @@ -15,17 +15,17 @@ You can specify individual files using either of these parameters: Multiple files can be included by repeating the parameter: -``` +```shell ?filePath=src/index.ts&filePath=src/components/Button.tsx ``` -### 2. Compressed File Lists +### 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 uses base64-encoded, gzip-compressed data to efficiently transmit large sets of file paths. The compression makes it possible to include hundreds or thousands of files in a URL without exceeding length limits. The length limits vary depending on the browser, HTTP server, and other services involved like Cloudflare. +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: @@ -34,18 +34,19 @@ const compressedData = Uint8Array.from([...decodedData].map(char => char.charCod 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 (which is smaller than base64-encoding, then url-encoding). +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 +### 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 +## File filtering UI components The comparison view provides several UI components to help you filter and navigate files: @@ -58,18 +59,18 @@ The FileDiffPicker component allows you to: - 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, with results displayed instantly as you type. The component can efficiently handle repositories with thousands of files through client-side filtering. +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 +### 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 certain types of changes (additions, deletions, etc.) +- Show or hide specific changes (additions, deletions, etc.) -### URL-Based Filtering +### URL-based filtering Any filters you apply through the UI will update the URL with the appropriate query parameters. This means you can: @@ -77,7 +78,7 @@ Any filters you apply through the UI will update the URL with the appropriate qu 2. Bookmark comparisons with specific file filters 3. Navigate back and forth between different filter states using browser history -## Implementation Details +## Implementation details The system makes strategic performance trade-offs to provide a smooth user experience: @@ -92,25 +93,26 @@ The system makes strategic performance trade-offs to provide a smooth user exper */ ``` -The file filtering system uses a specialized file metadata query that is faster and more lightweight than the comprehensive file diffs query used for displaying actual code changes. +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 +## Usage examples 1. View only JavaScript files: - ``` - ?filePath=src/utils.js&filePath=src/components/App.js - ``` +```bash + ?filePath=src/utils.js&filePath=src/components/App.js +``` 2. Focus on a single file: - ``` - ?focus=true&filePath=src/components/Button.tsx - ``` +```bash + ?focus=true&filePath=src/components/Button.tsx + ``` + +3. Use a compressed file list for many files: -3. Use compressed file list for many files: - ``` - ?compressedFileList=H4sIAAAAAAAAA2NgYGBg... - ``` +```bash + ?compressedFileList=H4sIAAAAAAAAA2NgYGBg... +``` -This flexible filtering system allows you to create customized views of repository comparisons, making it easier to review changes in large projects. +This flexible filtering system allows you to create customized views of repository comparisons, making reviewing changes in large projects easier.