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

1. Navigate to your Git repository:

cd your-project

2. 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/ or feature/ (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
• Pushes changes to remote
• Provides direct PR creation URL
• Special hotfix handling (PR to main instead of dev)
• Does not delete branches (branches remain for PR workflow)

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 status
• mainBranch: Primary production branch name
• protectedBranches: List of protected branch names
• initDate: 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.

1. Fork the repository
2. Create your feature branch (bf feature new amazing-feature)
3. Commit your changes
4. Push to the branch
5. Open a Pull Request

Version update process:

1. Update version in package.json
2. CLI version auto-matches package.json
3. 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:

1. Check error messages
2. Verify Git repository state
3. Check branch protection settings
4. Review configuration file
5. File an issue on GitHub

Workflow Example

Here's a typical workflow using BranchFlow:

1. Create feature branch:

   bf feature new user-auth

2. Make and save changes:

   # Edit files
   bf save
   # More changes
   bf save

3. Switch branches if needed:

   bf checkout  # Changes auto-stashed
   # Do other work
   bf checkout  # Return to feature

4. Stage for testing:

   bf stage feature  # Select your branch

5. Finish feature and create PR:

   bf finish  # On feature branch
   # or
   bf feature finish  # From anywhere
   # Follow the provided URL to create PR

6. After PR is merged, clean up branch:

   bf abandon  # Deletes the branch after PR is merged

Built with ❤️ by developers, for developers who love clean Git workflows.