BranchFlow

CLI tool for modified Git-Flow with a linear history, GitHub integration, and AI-powered features.

Installation

npm install -g @div0ky/branchflow

Features

• Modified Git-Flow workflow
• Automatic PR creation with GitHub integration
• AI-powered commit messages and PR titles
• Branch protection
• Linear history maintenance
• Hotfix backfilling
• Staging management
• Branch cleanup and orphan detection
• Branch switching and management
• Incremental save points with automatic squashing
• Graceful error handling and recovery

Commands

Initialization (init)

bf init

• Initializes BranchFlow in your repository
• Sets up main and dev branches
• Configures GitHub integration (optional)
• Creates initial configuration

GitHub Integration

Configure GitHub (config)

bf config --github    # Configure GitHub token
bf config --show     # Show current token
bf config --test     # Test GitHub connectivity

• Manages GitHub integration settings
• Validates repository access
• Tests authentication

AI Integration

Configure OpenAI (config)

bf config --ai       # Configure OpenAI API key
bf config --show     # Show current configuration
bf config --test     # Test OpenAI connectivity

• Enables AI-powered commit messages and PR titles
• Validates API key and connectivity
• Tests integration status

AI Features

• Smart Commit Messages: Analyzes changes and generates descriptive commit messages
• Intelligent PR Titles: Generates PR titles based on commit history and changes
• Context-Aware: Considers both code changes and commit messages
• Conventional Format: Follows commit message conventions
• Interactive: Allows review and modification of generated content

Branch Management

Create Branch

bf feature new <n>
bf fix new <n>
bf hotfix new <n>

Finish Branch (finish)

bf finish

• Squashes all save point commits into one
• Prompts for final commit message
• Rebases current branch
• Creates PR automatically (if GitHub configured)
• For hotfixes:
  • Creates PR to main
  • Creates backfill PR to dev
• Updates branch tracking

Branch Cleanup (clean)

bf clean

• Identifies and removes orphaned local branches
• Interactive selection of branches to clean
• Protects essential branches (main, dev, current)

Save Changes (save)

bf save

• Creates a save point with a "." commit message
• Stages and commits all changes
• Multiple saves can be made before finishing
• All save points are squashed during finish
• Safe to use multiple times during development

Stage Changes (stage)

bf stage [type]

• Merges changes into staging branch
• Optional branch type specification (feature/fix/hotfix)

Switch Branches (checkout or co)

bf checkout
bf co

• Interactive branch switching
• Lists available branches for selection
• Safely stashes changes if needed
• Provides recovery instructions on errors

Branch Protection

bf protect <n>     # Protect a branch
bf unprotect <n>   # Remove protection

• Prevents accidental deletion or modification
• Manages branch protection status

Release Management

bf release

• Merges dev into main (production)
• Includes safety confirmations
• Handles production deployments

Abandon Branch

bf abandon

• Safely discards branch and changes
• Protects essential branches

List Branches

bf list

• Shows all branches
• Indicates branch status and type

Pull Request Management (pr)

bf pr retry

• Retry PR creation for finished branches
• Useful when GitHub token is added after branch completion
• Shows history of finished branches

Branch Synchronization (sync)

bf sync

• Rebases current branch from dev
• Not available for hotfix branches
• Updates local branch with latest dev changes
• Helps prevent conflicts during finish
• Handles remote synchronization

Configuration

BranchFlow stores its configuration in .branchflow.json:

{
  "initialized": true,
  "mainBranch": "main",
  "protectedBranches": ["main", "dev", "staging"],
  "githubToken": "your-token-here",
  "openaiApiKey": "your-openai-key-here",
  "initDate": "2024-01-01T00:00:00.000Z",
  "finished_branches": []
}

Configuration details:

• initialized: Indicates BranchFlow setup status
• mainBranch: Primary production branch name
• protectedBranches: List of protected branch names
• githubToken: GitHub personal access token (for PR creation)
• openaiApiKey: OpenAI API key for AI features
• initDate: Installation timestamp
• finished_branches: History of completed branches

GitHub Integration

Token Requirements

• Personal access token with repo scope
• Access to target repository
• Ability to create pull requests

Features

• Automatic PR creation
• PR retry capability
• Repository access verification
• Branch synchronization
• Detailed error reporting

Error Handling

BranchFlow provides robust error handling for:

Operation Failures

• Remote connectivity issues
• Permission problems
• Merge conflicts
• Stash conflicts
• Branch protection violations
• GitHub API errors
• OpenAI API errors
• Interrupted operations (CTRL+C)
• Save point failures

Recovery Mechanisms

• Stash recovery during errors
• Force delete fallbacks
• Remote operation retries
• Automatic conflict detection
• Clear error reporting without stack traces
• PR creation retry
• Graceful interrupt handling
• Helpful recovery instructions
• Safe state preservation

Safety Features

• Protected branch enforcement
• Production action confirmation
• Token security
• Branch type validation
• Remote sync verification
• Detailed change previews
• Graceful operation cancellation and interrupt handling
• Safe save point handling
• Secure API key storage