@div0ky/branchmate v0.7.1

BranchMate CLI

A powerful command-line interface for streamlined Git workflow management. BranchMate 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
• 🔄 Auto-stashing of changes when switching branches
• 🛡️ Branch protection system with safe deletion mechanisms
• 🚀 Streamlined release process with safety checks
• 📋 Branch status overview with protection indicators
• 🎯 Git-flow inspired workflow enforcement
• 🎨 Beautiful CLI with colorful interface and interactive prompts

Prerequisites

• Node.js 14 or higher
• Git installed and configured
• Active Git repository (or BranchMate can initialize one for you)

Installation

npm install -g @div0ky/branchmate

Quick Start

1. Navigate to your Git repository:

cd your-project

2. Initialize BranchMate:

bmate init

During initialization, BranchMate 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

Auto-stashing

BranchMate automatically handles uncommitted changes when switching between branches:

• When creating a new branch or finishing a branch, if there are uncommitted changes in your working directory, BranchMate will automatically stash these changes.
• After the operation is complete, BranchMate will attempt to reapply the stashed changes.
• If there are conflicts when reapplying the stash, BranchMate will notify you and provide instructions on how to resolve the conflicts manually.

This feature ensures that your work-in-progress is preserved when performing branch operations, reducing the risk of losing uncommitted work.

Branch Types and Naming Convention

BranchMate enforces consistent branch naming with the following prefixes:

• Features: feat/
• Bug fixes: fix/
• Hot fixes: hotfix/

Usage

Branch Management

# Create branches
bmate feature new my-feature
bmate fix new bug-123
bmate hotfix new critical-issue

# Finish branches (merges to appropriate branch and deletes the source branch)
bmate feature finish my-feature
bmate fix finish bug-123
bmate hotfix finish critical-issue

Release Management

# Merge dev branch into main
bmate release

Branch Protection

# Protect important branches
bmate protect branch-name

# Remove protection
bmate unprotect branch-name

Utility Commands

# View all branches with protection status
bmate list

# Safely abandon current branch
bmate abandon

Command Details

bmate init

• Initializes BranchMate in your repository
• Creates necessary branch structure
• Interactive setup with configuration options
• Stores configuration in .branchmate.json

Branch Commands

Creation (new)

bmate <type> new <name>

• Automatically creates branch from dev
• Enforces naming conventions
• Pulls latest changes before branching
• Handles existing branch scenarios

Finishing (finish)

bmate <type> finish

• Updates target branch with latest changes
• Merges using --ff-only for clean history
• Deletes branch after successful merge
• Special handling for hotfixes (merges to both dev and main)

Release Command

bmate release

• Updates both dev and main branches
• Performs safety checks before merging
• Requires explicit confirmation
• Maintains clean merge history

Protection Commands

Protect

bmate protect <branch-name>

• Prevents branch deletion
• Prevents automated merges
• Prevents branch abandonment
• Stores protection status in config

Unprotect

bmate unprotect <branch-name>

• Removes protection status
• Allows normal branch operations

Utility Commands

List

bmate list

• Shows all local and remote branches
• Indicates current branch
• Shows protection status
• Color-coded output

Abandon

bmate abandon

• Safely discards all changes
• Deletes local and remote branch
• Prevents abandoning protected branches
• Requires explicit confirmation

Configuration

BranchMate stores its configuration in .branchmate.json within your Git directory:

{
  "initialized": true,
  "mainBranch": "main",
  "protectedBranches": [],
  "initDate": "2024-01-01T00:00:00.000Z"
}

Safety Features

• Confirmation prompts for destructive actions
• Protection for critical branches (main, dev)
• Safe branch deletion with merge checks
• Automatic update checks before operations
• Force push protection
• Automatic stashing of uncommitted changes when switching branches

Error Handling

BranchMate provides clear error messages for common scenarios:

• Uninitialized repository
• Protected branch operations
• Merge conflicts
• Remote connectivity issues
• Permission problems

Updating BranchMate

BranchMate includes an automatic update checker and an update command to ensure you're always using the latest version.

Automatic Update Checks

BranchMate automatically checks for updates when you run commands. If a new version is available, you'll see a notification:

New version available: X.X.X (current: X.X.X) Run 'bmate update' to update to the latest version.

Manual Update Command

To manually check for updates and update BranchMate, use the following command:

bmate update

This command will:

1. Check for the latest version of BranchMate
2. If an update is available, it will automatically download and install it
3. Provide feedback on the update process

If you're already on the latest version, you'll see:

You're already using the latest version!

Update Process

When updating:

• BranchMate will use npm to install the latest version globally
• You'll see a spinner indicating the update progress
• Upon successful update, you'll be prompted to run your command again to use the new version

If the update fails for any reason, BranchMate will provide an error message and instructions for manual updating.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

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

When updating versions: 1. Update the version in package.json 2. The CLI version will automatically match package.json 3. The README badge will automatically reflect the npm version

Note: The CLI's version must always match the package version to ensure proper update detection.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

If you encounter any issues or have questions: 1. Check the error messages for specific guidance 2. Ensure your Git repository is in a clean state 3. Verify your branch protection settings 4. File an issue on the GitHub repository

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