分支作家

Git 分支名称 林入和交互式分支创建 - 树枝的约定/承诺

分支作家 帮助团队以精简、互动的工作流程保持吉特分支命名惯例的一致性:

• ✨ 无光滑分支创建 - 智能默认,最小提示
• 🔍 分支名称验证 - 违反你的规矩把现有的分行放下
• 🎯 广泛的规则制度 - 内建规则外加自定义规则插件
• ⚙️ 基于模板的命名 - 说吧 {{type}}/{{ticket}}-{{desc}} 或任何需要的格式
• 🚀 CLI 和 API 软件 - 单独使用或按方案整合
• 📦 类型脚本第一 - 包括全部类型定义

安装

# Global installation (recommended)
npm install -g @branchwright/cli

# Project-local installation
npm install --save-dev @branchwright/cli

# Or use without installing
npx @branchwright/cli create

快速启动

互动分支创建

# If installed globally or locally
brw create

# Without installing (using npx)
npx @branchwright/cli create

就这样! Branchwright将引导你通过:

1. 选择分支类型( feat, fix, chore等)
2. 可选输入出票证
3. 描述您的分支
4. 创建和切换到新分支

该工具使用 智能默认 尽量减少摩擦:

• 基地分行:现分行
• 自动退出:是
• 推向远程 : no( 可选)

验证分支名称

# Validate current branch
brw lint

# Validate specific branch
brw lint feature/user-auth

# Validate all branches
brw lint --all

配置

创建 branchwright.config.ts 在您的工程根中 :

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

export default defineConfig({
  // Define your branch types
  branchTypes: [
    { name: 'feat', label: 'Feature' },
    { name: 'fix', label: 'Bug Fix' },
    { name: 'chore', label: 'Chore' },
  ],
  
  // Customize branch name template
  template: '{{type}}/{{ticket}}-{{desc}}',
  
  // Configure rules
  rules: {
    ticketId: ['optional', { prefix: 'PROJ-' }],
  },
  
  // Control optional questions (all default to false)
  extraQuestions: {
    baseBranch: false,    // Ask which branch to base from
    checkout: false,      // Ask whether to switch to new branch
    pushToRemote: false,  // Ask whether to push to remote
  },
  
  // Customize prompts (optional)
  questions: {
    branchType: 'What type of branch?',
    description: 'Describe your change:',
    pushToRemote: 'Push to origin?',
  },
});

配置选项

模板系统

在分支名称模板中使用占位符 :

• {{type}} - 分支类型(feat、fix等)
• {{ticket}} - 车票号码(如果提供)
• {{desc}} - 说明

实例:

// Simple format
template: '{{type}}/{{desc}}'
// Output: feat/user-authentication

// With ticket
template: '{{type}}/{{ticket}}-{{desc}}'
// Output: feat/PROJ-123-user-authentication

// Custom format
template: '{{ticket}}/{{type}}-{{desc}}'
// Output: PROJ-123/feat-user-authentication

交互式问题

控制在其中显示的可选问题 brw create数字 :

extraQuestions: {
  baseBranch: true,    // Ask "Base branch?" (default: uses current branch)
  checkout: true,      // Ask "Switch to new branch?" (default: yes)
  pushToRemote: true,  // Ask "Push to remote?" (default: no)
}

默认情况下,所有 false 简洁的经验。 该工具:

• 使用您的当前分支作为基础
• 自动切换到新分支
• 不推向远程

只有在需要灵活性时才启用问题.

自定义提示

覆盖默认的提示文本 :

questions: {
  branchType: 'Select the type of work:',
  ticketId: 'Ticket/issue number (optional):',
  ticketIdRequired: 'Ticket/issue number:',
  description: 'Brief description:',
  descriptionWithTicket: 'Describe your changes:',
  baseBranch: 'Create from which branch?',
  checkout: 'Switch to this branch now?',
  proceed: 'Create this branch?',
  pushToRemote: 'Push to origin now?',
}

规则系统

Branchwright包括一个强大的,可扩展的规则引擎用于验证.

内部规则

ticketId - 验证车票识别格式和要求

rules: {
  // Off: No ticket ID validation
  ticketId: 'off',
  
  // Optional: Allow but don't require ticket IDs
  ticketId: 'optional',
  
  // Required: Ticket ID must be present
  ticketId: 'required',
  
  // With prefix validation
  ticketId: ['optional', { prefix: 'PROJ-' }],
  ticketId: ['required', { prefix: 'TEAM-' }],
}

规则配置

规则接受三个严重程度:

• 'off' - 规则被禁用
• 'optional' - 规则运行,但不阻断
• 'required' - 规则必须通过

配置格式 :

rules: {
  myRule: true,                           // Boolean (true = required, false = off)
  myRule: 'optional',                     // String severity
  myRule: ['required', { option: 'val' }], // Tuple with options
}

自定义规则

定义自己的验证规则 :

import { defineRule, coreRuleRegistry, createRegistry } from '@branchwright/cli';

const noWipRule = defineRule(
  {
    id: 'no-wip',
    meta: {
      title: 'Disallow WIP branches',
      description: 'Prevents work-in-progress markers from shipping.',
    },
    defaultSeverity: 'required',
  },
  (context) => {
    if (context.branchName.includes('wip')) {
      return { 
        message: 'Remove "wip" from the branch name.',
        suggestions: [context.branchName.replace('wip', '')],
      };
    }
    return null; // Valid
  },
);

// Use with evaluateRules
const registry = createRegistry(...coreRuleRegistry.entries(), noWipRule);

规则插件

从外部模块装入自定义规则 :

// branchwright.config.ts
export default defineConfig({
  plugins: [
    './config/rules/company-rules.ts',  // Local file
    '@acme/branchwright-rules',         // NPM package
  ],
  rules: {
    'no-wip': 'required',
    'acme/ticket-format': ['required', { pattern: /^[A-Z]+-\d+$/ }],
  },
});

插件格式 :

// company-rules.ts
import { defineRule } from '@branchwright/cli';

export default [
  defineRule(/* ... */),
  defineRule(/* ... */),
];

规则预设

组合多个规则配置 :

export default defineConfig({
  presets: [
    'recommended',              // Built-in preset
    '@acme/strict-preset',      // Package preset
  ],
  rules: {
    // Override preset defaults
    ticketId: 'required',
  },
});

预设按顺序合并,并明确 rules 拥有最后的优先权.

CLI 参考

brw create

以交互或预指定值创建新分支 .

旗帜 :

• -t, --type <type> - 预先指明分支类型(例如:成就、固定、弦乐)
• --ticket <id> - 预先注明票证(例如JIRA-123)
• -d, --desc <description> - 预先说明分支说明
• -y, --yes - 跳过确认提示
• --push - 创建后将分支推向远程
• --base <branch> - 指定基础分支(覆盖配置)
• --dry-run - 在不创建分支的情况下进行预览

实例:

# Standard interactive creation
brw create

# Fully non-interactive - provide all values
brw create -t feat --ticket PROJ-123 -d "add-user-auth" -y

# Partial - skip some prompts
brw create -t fix -d "resolve-login-bug"

# Quick feature branch
brw create -t feat -d "new-dashboard" --push

# Create from specific base
brw create --base main

# Preview what would be created
brw create --dry-run

非交互式使用

使用旗帜跳过交互式提示 - 完全适合脚本和CI/CD :

快速分支创建 :

# Minimal - just type and description
brw create -t feat -d "add-oauth"

# With ticket ID
brw create -t fix --ticket BUG-456 -d "memory-leak"

# Skip confirmation
brw create -t chore -d "update-deps" -y

自动化脚本( S) :

# CI/CD workflow
brw create -t release -d "v2.0.0" -y --push

# Batch creation script
for feature in auth payments dashboard; do
  brw create -t feat -d "$feature" -y
done

# Integration with ticket systems
TICKET=$(gh issue view 123 --json number -q .number)
brw create -t feat --ticket "GH-$TICKET" -d "implement-feature" --push

验证 :

旗帜像交互式输入一样被验证 :

• --type 必须匹配已配置的分支类型
• --ticket 必须匹配所配置的前缀(如果规则)。 票证已经设定)
• --desc 必须遵守描述Style和 maxDescriptionLength 规则

禁用提示 :

在全球隐藏 CLI 提示消息( 例如, 为有经验的用户) :

export default defineConfig({
  showCliTips: false,  // Disable "you can use flags" tip
  // ... rest of config
});

brw lint [branches...]

根据您的规则验证分支名称 .

旗帜 :

• --all - 检查所有地方分支

实例:

# Validate current branch
brw lint

# Validate specific branches
brw lint feature/auth fix/login-bug

# Check all branches
brw lint --all

brw init

生成默认值 branchwright.config.ts 文档.

brw config

显示您的当前配置 .

程序化 API

在您的节点代码中使用 Branchwright :

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

const branchwright = new Branchwright();

// Validate a branch name
const result = await branchwright.validate('feat/user-auth');
console.log(result.valid ? '✓ Valid' : `✗ ${result.message}`);

// Create a branch interactively
const branchName = await branchwright.create();

// Access underlying components
const validator = branchwright.getValidator();
const creator = branchwright.getCreator();

高级:规则评价

import { evaluateRules, coreRuleRegistry } from '@branchwright/cli';

const config = { /* your config */ };
const violations = await evaluateRules('feat/my-branch', config, coreRuleRegistry);

violations.forEach(v => console.error(v.message));

一体化

基特·胡克斯(胡斯基)

驱动前验证分支名称 :

npm install --save-dev husky
npx husky init

.husky/前推:

#!/bin/sh
npx brw lint || exit 1

CI/CD (GitHub 动作)

name: Branch Lint
on: [pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm install -g @branchwright/cli
      - run: brw lint ${{ github.head_ref }}

国家预防机制文稿

{
  "scripts": {
    "branch": "brw create",
    "branch:lint": "brw lint"
  }
}

常见模式

常规提交样式

export default defineConfig({
  branchTypes: [
    { name: 'feat', label: 'feat: New feature' },
    { name: 'fix', label: 'fix: Bug fix' },
    { name: 'docs', label: 'docs: Documentation' },
    { name: 'refactor', label: 'refactor: Code refactoring' },
    { name: 'test', label: 'test: Testing' },
    { name: 'chore', label: 'chore: Maintenance' },
  ],
  template: '{{type}}/{{desc}}',
});

车票所需工作流量

export default defineConfig({
  template: '{{type}}/{{ticket}}-{{desc}}',
  rules: {
    ticketId: ['required', { prefix: 'PROJ-' }],
  },
});

带可选外加的团队

export default defineConfig({
  template: '{{type}}/{{ticket}}-{{desc}}',
  rules: {
    ticketId: ['optional', { prefix: 'TEAM-' }],
  },
  extraQuestions: {
    pushToRemote: true,  // Ask about pushing
  },
});

解决问题

"不在一个git仓库"

确保您正在 Git 仓库内运行命令 :

git init  # If needed

分支名称验证失败

检查您的配置 :

brw config

验证您的分支名称符合模板和规则 .

自定义规则不加载

确保插件路径正确且导出符合预期格式 :

// my-rules.ts
export default [defineRule(/* ... */)];

许可证

麻省理工学院 分公司撰稿人

由诺尔达鲁开发和维护.