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 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:

    SHELL
    ?filePath=src/utils.js&filePath=src/components/App.js

  2. Focus on a single file:

    SHELL
    ?focus=true&filePath=src/components/Button.tsx

  3. Use compressed file list for many files:

    SHELL
    ?compressedFileList=H4sIAAAAAAAAA2NgYGBg...

This flexible filtering system allows you to create customized views of repository comparisons, making it easier to review changes in large projects.