Skip to content

feat: optimize UI behavior for large numbers of local branches #35

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ericanderson wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat: optimize UI behavior for large numbers of local branches #35

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 35 additions & 6 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,11 +54,14 @@ The project uses strict TypeScript configuration with:
- Deletes remote branches that have been merged (with --dry-run option)
- Shows progress bar during operation

4. **Local Command** (`src/commands/PruneLocalBranches.ts`): Local branch cleanup
4. **Local Command** (`src/commands/PruneLocalBranches.ts`): Local branch cleanup with enhanced UI
- Scans local branches for safe deletion candidates
- Verifies local branch SHA matches PR head SHA before deletion
- Protects current branch and branches with unpushed commits
- Includes comprehensive safety checks and dry-run mode
- **Enhanced UI for Large Datasets**: Automatically optimizes for repositories with 100+ branches
- **Interactive Features**: Paginated selection, search/filtering, bulk operations
- **Performance Optimization**: Memory-optimized processing, batch operations, limited PR fetching
- Shows detailed analysis and progress during operation

5. **All Command** (`src/commands/PruneAll.ts`): Combined branch cleanup
Expand All @@ -67,14 +70,39 @@ The project uses strict TypeScript configuration with:
- Provides combined summary of both operations
- Supports --dry-run and --force flags for both phases
- Ensures maximum cleanup efficiency in a single command
- Inherits enhanced UI capabilities for local cleanup phase

6. **Utilities** (`src/utils/`):
6. **Enhanced UI Utilities** (`src/utils/`):
- `enhancedPrompts.ts`: Paginated interactive prompts with search, filtering, and bulk actions
- `batchProcessor.ts`: Batch processing utilities for handling large datasets efficiently
- `performanceOptimizer.ts`: Performance optimization strategies and memory management
- `createOctokitPlus.ts`: Factory for creating authenticated Octokit instances
- `ownerAndRepoMatch.ts`: Validates PR head/base repository matching
- `localGitOperations.ts`: Local git operations (list branches, get status, delete branches)
- `branchSafetyChecks.ts`: Safety validation for branch deletion
- `getGitRemote.ts`: Git remote URL parsing and repository detection

### Enhanced UI Features

#### Large Dataset Handling
- **Automatic Detection**: Detects repositories with 100+ branches and enables enhanced mode
- **Paginated Selection**: Breaks large lists into manageable pages
- **Search and Filtering**: Allows users to quickly find specific branches using search patterns
- **Bulk Operations**: Select all, select none, or pattern-based selection using regex
- **Progress Reporting**: Shows detailed progress for long-running operations

#### Performance Optimization
- **Memory Management**: Uses batch processing for repositories with 500+ branches
- **Limited PR Fetching**: Fetches only the most recent 1000 PRs for very large repositories
- **Smart Processing Plans**: Dynamically adjusts batch sizes and processing strategies
- **Estimated Duration**: Provides time estimates for large operations

#### Repository Size Optimization
- **Small (1-50 branches)**: Standard processing, full interactive mode
- **Medium (51-200 branches)**: Enhanced UI with search and bulk actions
- **Large (201-500 branches)**: Memory optimization and progress reporting
- **Very Large (500+ branches)**: Full optimization suite with smart recommendations

### Authentication
Ghouls uses GitHub CLI authentication exclusively. Users must have the GitHub CLI (`gh`) installed and authenticated with `gh auth login`. The tool automatically uses the existing GitHub CLI authentication credentials.

Expand All @@ -83,11 +111,11 @@ Ghouls uses GitHub CLI authentication exclusively. Users must have the GitHub CL
# Remote branch cleanup
ghouls remote [--dry-run] [owner/repo]

# Local branch cleanup
ghouls local [--dry-run] [owner/repo]
# Local branch cleanup (with enhanced UI for large datasets)
ghouls local [--dry-run] [--force] [owner/repo]

# Combined cleanup (both remote and local)
ghouls all [--dry-run] [owner/repo]
ghouls all [--dry-run] [--force] [owner/repo]
```

All commands support repository auto-detection from git remotes when run within a git repository.
Expand All @@ -104,13 +132,14 @@ All commands support repository auto-detection from git remotes when run within
- Build System: TypeScript compiler with pnpm package manager
- Package Management: pnpm with semantic-release
- Test Framework: Vitest with comprehensive unit tests
- UI Framework: inquirer for enhanced interactive prompts

### AI Team Assignments

| Task | Agent | Notes |
|------|-------|-------|
| Code reviews and quality assurance | code-reviewer | Required for all PRs and feature changes |
| Performance optimization and profiling | performance-optimizer | Essential for CLI tool responsiveness |
| Performance optimization and profiling | performance-optimizer | Essential for CLI tool responsiveness and large dataset handling |
| Backend development and API integration | backend-developer | Handles GitHub API integration and CLI logic |
| API design and GitHub integration specs | api-architect | Designs interfaces for GitHub API wrapper |
| Documentation updates and maintenance | documentation-specialist | Maintains README, API docs, and user guides |
124 changes: 123 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -134,6 +134,89 @@ Or specify a repository explicitly:
ghouls local --dry-run myorg/myrepo
```

### Enhanced UI for Large Repositories

The `local` command now includes enhanced UI capabilities that automatically optimize for repositories with many branches:

#### Automatic Performance Optimization
- **Large Dataset Detection**: Automatically detects when you have 100+ branches and enables optimized processing
- **Memory Management**: Uses batch processing and memory optimization for repositories with 500+ branches
- **Progress Reporting**: Shows detailed progress and estimated completion times for long-running operations
- **Smart Recommendations**: Provides context-aware tips for better performance in large repositories

#### Interactive Features for 100+ Branches
When working with large numbers of branches, Ghouls provides enhanced interactive features:

- **Search and Filtering**: Quickly find specific branches using search patterns
- **Bulk Operations**: Select all, select none, or select branches matching regex patterns
- **Paginated Selection**: Navigate through large lists without overwhelming your terminal
- **Smart Defaults**: Pre-selects safe branches while showing detailed information

### Example with Large Dataset

```bash
$ ghouls local --dry-run

Scanning for local branches that can be safely deleted...
Found 347 local branches
📊 Large dataset detected - using optimized processing
🔍 Consider using search/filtering to narrow down results
⚡ Use --force flag to skip interactive mode for faster processing

🔧 Using memory-optimized processing (estimated duration: 2 minutes)
Fetching merged pull requests from GitHub...
Found 89 merged pull requests

Branch Analysis:
Safe to delete: 67
Unsafe to delete: 280

Skipping unsafe branches:
- main (protected branch)
- develop (protected branch)
- feature/active-work (2 unpushed commits)
- hotfix/critical-fix (current branch)
... and 276 more

Found 67 items. Using enhanced selection mode for large datasets.

Current selection: 67/67 items

What would you like to do?
> 🔍 Search/filter items
📦 Bulk actions
✏️ Individual selection
📋 Review selected items (67)
✅ Continue with current selection
```

#### Search and Filter Example

```bash
# Using search to filter branches
? Enter search term (branch name pattern): feature/old
Found 23 matches for "feature/old"

Current selection: 23/23 items
Search filter: "feature/old" (23 matches)
```

#### Bulk Actions Example

```bash
# Using regex patterns for bulk selection
? Choose bulk action: Select by pattern - Select items matching a regex pattern
? Enter regex pattern (e.g., "^feature/", ".*-old$"): ^hotfix/.*-2023$
Selected 8 items matching pattern "^hotfix/.*-2023$"
```

### Performance Characteristics

- **Small repositories (1-50 branches)**: Standard processing, interactive mode
- **Medium repositories (51-200 branches)**: Batched processing, enhanced UI
- **Large repositories (201-500 branches)**: Memory optimization, limited PR fetching
- **Very large repositories (500+ branches)**: Full optimization suite with performance recommendations

### Safety Features

The `local` command includes several safety checks to prevent accidental deletion of important branches:
Expand All @@ -145,6 +228,20 @@ The `local` command includes several safety checks to prevent accidental deletio
- **Unpushed commits protection**: Skips branches that have unpushed commits
- **Dry-run mode**: Use `--dry-run` to see what would be deleted without making changes

### Force Mode for Automation

For automated workflows or when you trust the safety checks completely:

```bash
# Skip interactive mode and delete all safe branches automatically
ghouls local --force
```

This is particularly useful for:
- CI/CD cleanup jobs
- Automated maintenance scripts
- Large repositories where manual selection isn't practical

### Example Output

```
Expand Down Expand Up @@ -193,7 +290,7 @@ ghouls all --dry-run myorg/myrepo

The command executes in two phases:
1. **Remote cleanup**: Deletes merged remote branches first
2. **Local cleanup**: Then deletes corresponding local branches
2. **Local cleanup**: Then deletes corresponding local branches (with enhanced UI for large datasets)

Even if one phase encounters errors, the command will continue with the next phase to ensure maximum cleanup.

Expand Down Expand Up @@ -228,6 +325,31 @@ Local cleanup: ✅ Success
✅ All cleanup operations completed successfully!
```

# Performance Tips for Large Repositories

When working with repositories that have hundreds or thousands of branches:

## Memory and Performance Optimization
- Ghouls automatically detects large datasets and enables optimized processing
- Batch processing reduces memory usage and improves performance
- Limited PR fetching (most recent 1000 PRs) prevents API rate limiting

## Interactive Mode Efficiency
- Use search/filtering to narrow down results before making selections
- Leverage bulk actions for pattern-based selections (e.g., all branches from 2023)
- Consider using `--force` flag for automated cleanup of safe branches

## Best Practices
- Run cleanup during off-peak hours for very large repositories (1000+ branches)
- Use `--dry-run` first to understand the scope of changes
- Consider running `git remote prune origin` before using Ghouls to clean up stale remote references

## Repository Size Guidelines
- **Small (1-50 branches)**: Standard processing, full interactive mode
- **Medium (51-200 branches)**: Enhanced UI with search and bulk actions
- **Large (201-500 branches)**: Memory optimization and progress reporting
- **Very Large (500+ branches)**: Full optimization suite with smart recommendations

# Development

## Testing
Expand Down
Loading