Bulk Rename Titles
Relevant source files
The following files were used as context for generating this wiki page:
Bulk Rename Titles is a feature within Refined GitHub Projects that allows users to perform mass updates to the titles of issues and pull requests directly from the GitHub Projects table view. It provides a guided interface for string manipulation—specifically finding and replacing text or appending prefixes and suffixes—and leverages a background sequential queue to execute these changes safely via the GitHub GraphQL API.
Sources: README.md:89, src/components/bulk/bulk-rename-modal.tsx:43-52
Architecture and Data Flow
The system follows a decoupled architecture where the UI (Content Script) communicates with a Background Service Worker to perform authenticated API mutations. This ensures that operations are rate-limit safe and do not block the main browser thread.
System Interaction Diagram
The following diagram illustrates the lifecycle of a bulk rename operation from user input to API execution.
UI Components and Logic
The rename interface is managed by the BulkRenameModal component, which transitions through several internal states to guide the user.
UI Stages
| Stage | Description |
|---|---|
LOADING | Fetches the current titles and types (Issue vs PR) for the selected IDs. |
CONFIGURE | Primary interface for defining transformation rules (Find/Replace or Prefix/Suffix). |
PREVIEW | A review table showing a side-by-side comparison of "Original Title" vs "New Title". |
ERROR | Displays failure messages if titles cannot be fetched or resolved. |
Sources: src/components/bulk/bulk-rename-modal.tsx:11-14, src/components/bulk/bulk-rename-modal.tsx:106-250
Transformation Rules
The applyRule function governs how titles are modified based on user configuration. It supports two primary modes:
- Find & Replace: Uses a regular expression with global and case-insensitive flags (optional) to swap text fragments.
- Prefix / Suffix: Simple string concatenation to prepend or append text to existing titles.
function applyRule(original: string, rule: RuleState): string {
if (rule.tab === 'FIND_REPLACE') {
if (!rule.findText) return original;
const flags = rule.caseSensitive ? 'g' : 'gi';
const escaped = rule.findText.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
return original.replace(new RegExp(escaped, flags), rule.replaceText);
}
return `${rule.prefix}${original}${rule.suffix}`;
}
Sources: src/components/bulk/bulk-rename-modal.tsx:43-52
Backend Processing
Once the user confirms the preview, the bulkRename message is sent to the background service worker. The background handler manages the resolution of node IDs and execution.
Item Resolution
Before renaming, the system must resolve DOM-based IDs to GitHub Node IDs. This is handled by resolveProjectItemIdsWithTitles, which paginates through project items to find matching database IDs.
Sources: src/entries/background/helpers.ts:1145-1175
Sequential Execution Queue
To prevent 403 Abuse rate-limits, the background handler uses a processQueue mechanism. It iterates through the rename tasks, pausing for 1000ms between each mutation.
GraphQL Mutations
The system distinguishes between Issues and Pull Requests to call the appropriate GraphQL mutation.
| Object Type | Mutation Used | Source |
|---|---|---|
| Issue | UPDATE_ISSUE_TITLE | src/lib/graphql/mutations.ts:145 |
| Pull Request | UPDATE_PR_TITLE | src/lib/graphql/mutations.ts:153 |
Implementation Details
Data Structures
The primary data interface for a rename operation is the TitleItem:
interface TitleItem {
domId: string;
issueNodeId: string;
title: string;
typename: 'Issue' | 'PullRequest';
}
Sources: src/components/bulk/bulk-rename-modal.tsx:16-21
Handling Constraints
- Case Sensitivity: Optional toggle for the Find/Replace mode.
- Preview Table: Items that will not be changed (e.g., "Find" text not found) are displayed with reduced opacity in the preview.
- Admin Access: While rename is generally available, some bulk operations in the same bar require admin permissions, though title renaming is standard for writers.
Sources: src/components/bulk/bulk-rename-modal.tsx:210-230, src/components/bulk/bulk-actions-bar.tsx:898-904
Summary
The Bulk Rename Titles module provides a safe, preview-driven way to manage large-scale title updates. By combining a React-based configuration UI with a background sequential task runner, it ensures that even hundreds of items can be renamed without triggering GitHub's anti-abuse mechanisms or losing project context.