npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2025 – Pkg Stats / Ryan Hefner

@div0ky/branchflow

v1.7.1

Published

CLI tool for modified Git-Flow with a linear history

Downloads

161

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 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