@div0ky/branchflow
v1.3.0
Published
CLI tool for modified Git-Flow with a linear history
Downloads
883
Maintainers
Readme
BranchFlow CLI
A powerful command-line interface for streamlined Git workflow management. BranchFlow enforces consistent branching strategies and automates common Git operations while maintaining a clean repository state.
Features
- 🌿 Standardized branch management (feature, fix, hotfix)
- 🔄 Automated branch creation and merging workflows
- 💾 Single-commit workflow with automatic save functionality
- 🔄 Intelligent stashing of changes during branch operations
- 🛡️ Branch protection system with safe deletion mechanisms
- 🚀 Streamlined release process with safety checks
- 🎭 Flexible staging environment for pre-production testing
- 📋 Branch status overview with protection indicators
- 🎯 Git-flow inspired workflow enforcement
- 🎨 Beautiful CLI with colorful interface and interactive prompts
- 🔀 Interactive branch switching with automatic stash handling
- 🌍 Sophisticated remote branch synchronization
Prerequisites
- Node.js 14 or higher
- Git installed and configured
- Active Git repository (or BranchFlow can initialize one for you)
Installation
npm install -g @div0ky/branchflow
Quick Start
- Navigate to your Git repository:
cd your-project
- Initialize BranchFlow:
bf init
During initialization, BranchFlow will:
- Verify or create a Git repository if needed
- Detect or prompt for your main branch
- Create a development (dev) branch if it doesn't exist
- Set up the necessary configuration
- Attempt to set up remote tracking (if a remote exists)
Branch Types and Naming Convention
BranchFlow enforces consistent branch naming with the following prefixes:
- Features:
feat/
orfeature/
(both supported) - Bug fixes:
fix/
- Hot fixes:
hotfix/
Core Concepts
Single-Commit Workflow
BranchFlow implements a clean single-commit workflow:
- Each branch starts with an empty initial commit (message: ".")
- All changes are saved by amending this single commit
- The final commit message is set when finishing the branch
- Force pushing is handled automatically when needed
- This approach keeps branch history clean and focused
Auto-stashing
BranchFlow automatically handles uncommitted changes during branch operations:
- Changes are stashed when switching branches
- Stashes are automatically reapplied after the operation
- Stash conflicts are detected and reported
- Recovery mechanisms for failed stash operations
- Stashed changes are committed automatically when creating new branches
Remote Synchronization
BranchFlow handles remote operations intelligently:
- Detects existence of remote branches
- Uses appropriate push strategies (normal vs force)
- Creates tracking relationships for new branches
- Handles remote branch cleanup during finish/abandon
- Provides fallbacks for remote operation failures
Command Reference
Basic Commands
# Branch Creation
bf feature new my-feature # Creates feat/my-feature
bf fix new bug-123 # Creates fix/bug-123
bf hotfix new critical # Creates hotfix/critical
# Save Changes
bf save # Stages, amends, and pushes changes
# Switch Branches
bf checkout # Interactive branch switching
bf co # Shorthand for checkout
# Finish Branches
bf feature finish # Select and finish a feature branch
bf fix finish # Select and finish a fix branch
bf hotfix finish # Select and finish a hotfix branch
bf finish # Finish current branch
# Stage Changes
bf stage # Stage everything from dev
bf stage feature # Select a feature branch to stage
bf stage fix # Select a fix branch to stage
bf stage hotfix # Select a hotfix branch to stage
# Release to Main
bf release # Merge dev into main
# Branch Management
bf list # List all branches with status
bf abandon # Safely abandon current branch
bf protect <name> # Protect a branch
bf unprotect <name> # Remove branch protection
# Branch Synchronization
bf sync # Rebase current branch from dev
Command Details
Branch Creation (new
)
bf <type> new <name>
- Creates branch from latest dev
- Generates initial empty commit
- Stashes and reapplies any current changes
- Sets up remote tracking
- Handles existing branch scenarios
Save Changes (save
)
bf save
- Stages all current changes
- Amends the branch's single commit
- Force pushes to remote if needed
- Creates remote branch if it doesn't exist
- Blocked on protected branches
- Notifies if branch is behind dev (except for hotfix branches)
Branch Switching (checkout
/co
)
bf checkout # or bf co
- Shows interactive branch list
- Excludes current branch from options
- Automatically stashes changes
- Reapplies changes after switch
- Handles stash conflicts
Finishing Branches (finish
)
bf <type> finish # or just bf finish
- Interactive branch selection (if type specified)
- Uses current branch (if no type specified)
- Prompts for final commit message
- Stages and commits any changes
- Updates target branch
- Handles remote cleanup
- Special hotfix handling (merges to both dev and main)
Staging (stage
)
bf stage [type]
- Creates staging branch if needed
- Interactive branch selection
- Updates and rebases staging
- Proper merge sequence
- Returns to original branch
- Options:
- No type: Stages dev
- With type: Select specific branch
Release Command (release
)
bf release
- Updates both branches
- Performs safety checks
- Requires confirmation
- Maintains clean history
- Handles remote synchronization
Protection Commands
bf protect <branch-name> # Add protection
bf unprotect <branch-name> # Remove protection
- Prevents deletion
- Blocks automated merges
- Prevents abandonment
- Stores status in config
Branch Listing (list
)
bf list
- Shows all branches
- Indicates current branch
- Shows protection status
- Shows remote status
- Color-coded output
Branch Abandonment (abandon
)
bf abandon
- Discards all changes
- Deletes local and remote
- Blocked for protected branches
- Requires confirmation
- Includes cleanup operations
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"],
"initDate": "2024-01-01T00:00:00.000Z"
}
Configuration details:
initialized
: Indicates BranchFlow setup statusmainBranch
: Primary production branch nameprotectedBranches
: List of protected branch namesinitDate
: Installation timestamp
Error Handling
BranchFlow provides robust error handling for:
Operation Failures
- Remote connectivity issues
- Permission problems
- Merge conflicts
- Stash conflicts
- Branch protection violations
Recovery Mechanisms
- Stash recovery during errors
- Force delete fallbacks
- Remote operation retries
- Automatic conflict detection
- Clear error reporting
Safety Features
- Confirmation prompts for destructive actions
- Branch protection system
- Safe branch deletion with checks
- Automatic update checks
- Force push protection
- Stash management
- Remote operation safeguards
Updating BranchFlow
Automatic Update Detection
- Checks for updates on command execution
- Shows available version information
- Provides update instructions
Update Command
bf update
- Checks for latest version
- Downloads and installs updates
- Provides feedback
- Shows manual steps if needed
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
bf feature new amazing-feature
) - Commit your changes
- Push to the branch
- Open a Pull Request
Version update process:
- Update version in
package.json
- CLI version auto-matches package.json
- README badge auto-updates with npm version
License
This project is licensed under the MIT License - see the LICENSE file for details.
Support
If you encounter issues:
- Check error messages
- Verify Git repository state
- Check branch protection settings
- Review configuration file
- File an issue on GitHub
Workflow Example
Here's a typical workflow using BranchFlow:
Create feature branch:
bf feature new user-auth
Make and save changes:
# Edit files bf save # More changes bf save
Switch branches if needed:
bf checkout # Changes auto-stashed # Do other work bf checkout # Return to feature
Stage for testing:
bf stage feature # Select your branch
Finish feature:
bf finish # On feature branch # or bf feature finish # From anywhere
Built with ❤️ by developers, for developers who love clean Git workflows.