跳转到主要内容
v0.2.0

团队 Git，有规可循

交互式 CLI + 策略护栏 + 全链路溯源。
让分支管理从靠人记变成工具管。

$ npm install -g rail-git
快速开始

一图胜千言

不需要记任何 Git 规范，跟着菜单选就行

初始化

Terminal — rail init
$ rail init
Rail — 团队分支管理助手
? 主干分支？ (master)
? 预发布分支？ (pre)
? 测试分支？ (dev)
✓ 配置已创建: master / pre / dev
✓ Git hooks 已安装
✓ CI: .github/workflows/rail.yml
✓ 已提交

日常工作流

Terminal — rail start / save / ship
$ rail start
? 你要做什么？
  ❯ 🚀 feature — 新功能开发
    🐛 hotfix — 线上问题修复
? 简单描述一下： user avatar upload
✓ feature/20260529-user-avatar-upload
$ rail save
? 改动类型？ ❯ feat — 新功能
? 提交说明： (add user avatar upload feature)
✓ feat(user): add user avatar upload feature (e0fc734)
$ rail ship
? 合入到哪？ ❯ 🧪 dev — 提交测试
变更预览: feature/user-avatar → dev
待合并提交 (3) e0fc734 feat(user): ...
⚠ 1 个文件在目标分支上也有改动
✓ 已合入 dev，切回 feature/user-avatar

全链路溯源

Terminal — rail trace
$ rail trace
? 按什么维度查询？
  ❯ 🔍 全字段搜索（分支/操作人/类型通搜）
───────────────────────────────────
筛选条件: 操作人: 张三
匹配记录: 3 条
操作时间线:
  🚀 2026-05-29 09:00 张三 创建分支 feature/user-avatar
  💾 2026-05-29 09:05 张三 提交 commit e0fc734
  📥 2026-05-29 09:15 张三 合入 feature/user-avatar → dev
  🚢 2026-05-29 10:00 李四 发布 pre → master (v1.2.0)
───────────────────────────────────

可视化看板

Browser — http://localhost:3456
🚂 Rail Dashboard
master / pre / dev
feature/* → dev → pre → master
⛔ dev → feature/hotfix/refactor/pre/master (禁止)
所有分支
feature/user-avatar feature
hotfix/login-crash hotfix
feature/payment-flow feature
dev integration
pre prerelease
master production ←
操作记录
🚀 09:00 zhangsan 创建 feature/user-avatar
💾 09:05 zhangsan 提交 commit e0fc734
📥 09:15 zhangsan 合入 feature → dev

5 分钟上手

从安装到上线，四步走完完整流程。

1

安装

一行命令全局安装：npm install -g rail-git

2

初始化项目

在项目根目录执行 rail init，自动配置分支模型 + 安装 hooks + 生成 CI 工作流

3

日常开发

rail start 建分支 → rail save 提交 → rail push 推送 → rail ship 合入

4

发布上线

rail release 发布 → rail sync-dev 同步。全程不需要碰 git 原生命令。

初始化
$ rail init
? 主干分支？ (master)
? 预发布分支？ (pre)
? 测试分支？ (dev)
✓ 配置已创建: master / pre / dev
✓ Git hooks 已安装
✓ CI: .github/workflows/rail.yml
日常工作流
$ rail start
? 你要做什么？
❯ 新功能开发 · feature
线上问题修复 · hotfix
? 简单描述一下： user avatar upload
✓ feature/20260529-user-avatar-upload

$ rail save
? 改动类型： ❯ feat — 新功能
? 提交说明： (add user avatar upload feature)
✓ feat(user): add user avatar upload feature (e0fc734)

$ rail ship
? 合入到哪？ ❯ dev — 提交测试
变更预览: feature/user-avatar-upload → dev
待合并提交 (3) e0fc734 feat(user): ...
✓ 已合入 dev，切回 feature/user-avatar-upload

为什么选 Rail

不是又一个 Git GUI，而是一套完整的团队分支治理体系。

交互式引导

每步操作都有菜单选择、默认值和确认步骤。新人不需要记任何 Git 规范。

三重防线

Git hooks + CI 检查 + 平台分支保护。dev 永远无法往上游合入。

全链路溯源

每个操作记录时间和操作人。按分支、操作人、操作类型多维度搜索。

变更预览

合并前展示待合入提交和文件。热点文件高亮警告，防止代码被误覆盖。

冲突引导

遇到冲突不慌，工具一步步引导解决。解决不了可一键取消。

可视化看板

一键启动 Web 看板，浏览器查看所有分支状态和操作记录。

分支模型

一切操作围绕三个固定分支，方向固定，不可逆。

feature/* → dev → pre → master | hotfix/* → dev | refactor/* → dev

核心铁律：dev 永远不能合入 feature、hotfix、refactor、pre 或 master。违反此规则的操作在客户端、CI、平台三层被拦截。

命令参考

18 个命令，覆盖日常 Git 工作流。用 rail help 随时查看。

日常工作流

命令说明示例
rail start创建新分支rail start → 选类型 → 输入描述
rail save提交代码rail save → 选 type → 回车确认
rail push推送分支rail push
rail ship合入到 dev/pre/masterrail ship → 选目标 → 预览
rail switch切换分支rail switch → 搜索过滤
rail update拉取最新代码rail update

查看与追溯

命令说明
rail status分支状态、工作树、远程同步、合并进度
rail log最近 20 条提交，按 type 着色
rail diff未暂存改动摘要
rail trace按分支/操作人/操作类型搜索历史

高级操作

命令说明
rail cleanup勾选删除已合并的分支（本地 + 远程）
rail undo安全撤销提交（soft / mixed / hard）
rail abort取消进行中的合并
rail releasepre → master 合并 + 打版本 tag
rail sync-dev发布后 master 强同步到 dev
rail doctor环境诊断
rail dashboard启动 Web 看板
rail ciCI 策略检查

通用选项

选项说明
--dry-run预览操作，不实际执行
--yes / -y跳过交互确认
--no-interactive禁用交互模式，用于 CI/脚本

Type 体系

标准化 commit 类型和分支命名。每个类型都有推荐文案。

Commit Type

Type标签默认文案
feat新功能add [scope] feature
fix修复fix [scope] issue
docs文档update [scope] docs
style样式adjust [scope] styles
refactor重构refactor [scope]
perf性能optimize [scope]
test测试add [scope] tests
chore杂项update [scope]

分支 Type

Type标签命名规则
feature新功能feature/YYYYMMDD-desc
hotfix紧急修复hotfix/YYYYMMDD-desc
refactor重构refactor/YYYYMMDD-desc

CI 集成

rail init 自动生成 CI 配置。PR 时自动检查策略和格式。

.github/workflows/rail.yml（自动生成）
name: Rail Policy Check
on:
  pull_request:
    branches: [dev, pre, master]
jobs:
  rail-check:
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm install -g rail-git
      - run: rail ci --source ${{ github.head_ref }} --target ${{ github.base_ref }}

完整防线：本地 hooks 拦截 + CI 自动检查 + GitHub 分支保护规则。即使有人直接在网页上操作，不合规的合并也会被 CI 拒绝。

常见问题

你可能想知道的一些事情。

为什么 dev 不能合入其他分支？+
dev 是测试集成分支，可能包含未测试代码。Rail 在客户端、CI、平台三层彻底禁止 dev 往上游合入。
merge 冲突怎么办？+
rail ship 合并前展示变更预览并标记热点文件。如果冲突：rail status 查看 → 解决冲突 → rail save 完成，或 rail abort 取消。
团队成员需要每个人都 init 吗？+
一人 rail init 后提交配置文件。其他人 clone 后只需 rail init --no-interactive 安装本地 hooks。
CI / 脚本中使用？+
可以。--no-interactive 禁用交互，--yes 跳过确认。rail ci 专为 CI 设计。
支持哪些操作系统？+
macOS、Linux 完全支持。Windows 需要 Git for Windows。Node.js ≥ 18。

让团队的 Git 有规可循

一行命令，5 分钟，全团队用起来。

$ npm install -g rail-git