Getting Started

Get up and running with Branchwright in minutes.

Installation

Branchwright can be installed globally, locally in your project, or used without installation via npx.

Global Installation (Recommended)

npm install -g @branchwright/cli

With global installation, you can use brw or branchwright commands anywhere.

Local Installation

npm install --save-dev @branchwright/cli

Local installation is great for team projects where everyone should use the same version.

No Installation (npx)

npx @branchwright/cli create

Try Branchwright without installing it first.

Quick Start

Create Your First Branch

# Run the interactive branch creator
brw create

# Or with npx
npx @branchwright/cli create

You'll be guided through a simple workflow:

Select branch type: Choose from feat, fix, chore, or custom types
Enter ticket ID (optional): Link to your issue tracker
Describe your branch: Short, meaningful description
Confirm: Review and create

Branchwright will:

Create the branch with a properly formatted name
Automatically switch to the new branch (by default)
Base it off your current branch (by default)

Validate Branch Names

# Validate current branch
brw lint

# Validate specific branch
brw lint feature/user-auth

# Validate all branches
brw lint --all

Basic Configuration

Create a branchwright.config.ts file in your project root to customize behavior:

import { defineConfig } from '@branchwright/cli';

export default defineConfig({
  branchTypes: [
    { name: 'feat', label: 'Feature' },
    { name: 'fix', label: 'Bug Fix' },
    { name: 'chore', label: 'Chore' },
    { name: 'docs', label: 'Documentation' },
  ],
  
  template: '{{type}}/{{ticket}}-{{desc}}',
  
  rules: {
    ticketId: ['optional', { prefix: 'PROJ-' }],
  },
});

Common Workflows

Feature Development

# Create feature branch
brw create
# Select: feat
# Ticket: PROJ-123
# Description: user authentication
# Creates: feat/PROJ-123-user-authentication

# Work on your feature
git add .
git commit -m "feat: implement user auth"

# Push when ready
git push origin feat/PROJ-123-user-authentication

Bug Fixes

# Create bugfix branch
brw create
# Select: fix
# Ticket: PROJ-456
# Description: login redirect
# Creates: fix/PROJ-456-login-redirect

# Fix the bug
git add .
git commit -m "fix: correct login redirect"

# Push the fix
git push origin fix/PROJ-456-login-redirect

Validate Before Push

# Check your branch name is valid
brw lint

# If valid, push
git push origin $(git branch --show-current)

CLI Commands

`brw create`

Launch the interactive branch creation wizard.

brw create [options]

Options:
  --no-checkout   Don't switch to new branch
  --push          Push to remote after creation
  --help          Show help

`brw lint`

Validate branch names against your configured rules.

brw lint [branch-name] [options]

Arguments:
  branch-name     Branch to validate (default: current)

Options:
  --all           Validate all branches
  --json          Output JSON format
  --help          Show help

`brw config`

Display current configuration.

brw config [options]

Options:
  --json          Output JSON format
  --help          Show help

Next Steps

← Home Configuration →