@div0ky/branchflow
v1.7.1
Published
CLI tool for modified Git-Flow with a linear history
Downloads
161
Maintainers
Readme
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 statusmainBranch
: Primary production branch nameprotectedBranches
: List of protected branch namesgithubToken
: GitHub personal access token (for PR creation)openaiApiKey
: OpenAI API key for AI featuresinitDate
: Installation timestampfinished_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