pith —— Git 常用组合命令脚手架

一个命令搞定高频 Git 工作流：add + commit + push、pull --rebase + push、分支创建/切换、交互式挑选提交、暂存同步、分支清理等。支持通过配置文件自定义组合命令，零依赖，兼容 Node.js 14+。

pith commit "feat: 添加登录"    # git add -A + git commit
pith push "fix: 修复 bug"       # git add . + git commit + git push
pith sync                       # git pull --rebase + git push
pith switch feature/login        # 存在即切换，不存在则基于当前分支新建

特性

• 🚀 组合命令：把 2~4 条 git 命令合并为一条，自动处理常见边界（无上游自动 -u、无变更跳过提交等）
• 🧩 可扩展：.pithrc.json 配置文件自定义组合命令（支持当前目录 / 用户目录）
• 💬 智能交互：缺提交信息时交互输入；危险操作二次确认；支持管道输入（echo y | pith clean）
• 🎨 友好输出：彩色分步日志、仓库概览、提交历史回显（支持 --no-color / NO_COLOR）
• 🔒 安全设计：clean 保护 master/main/develop/release/*；amend 推送使用 --force-with-lease
• 📦 零依赖：仅用 Node.js 内置模块，无任何第三方依赖，兼容 Node 14+

安装

# 从 npm 全局安装（发布后）
npm install -g pith-cli
pith --version

要求：Node.js ≥ 14，git 已安装且在 PATH 中。

本地开发 / 未发布时试用

npm link                # 全局链接到本地开发目录（等价于安装本包）
pith --version

# 或直接运行，无需任何安装
node bin/pith.js --help

发布到 npm

npm 上的 pith 已被他人占用，因此本包发布名为 pith-cli（安装后命令仍是 pith，见 package.json 的 bin 字段）。发布前请确认 package.json 的 version / bin / files 已配置好（files 仅打包 bin/、lib/、README.md、LICENSE）：

npm test                 # 1. 跑通集成测试（发布前也会由 prepublishOnly 自动执行）
npm pack --dry-run       # 2. 预览将要发布的文件清单
npm login --registry=https://registry.npmjs.org   # 3. 登录 npm 官方源账号（首次发布时）
npm publish --registry=https://registry.npmjs.org # 4. 发布到官方源

# 发新版本：升级版本号后再次发布（自动更新 version 并打 git tag，需工作区干净）
npm version patch        # 或 minor / major
npm publish --registry=https://registry.npmjs.org

注意：若本地 npm config get registry 显示的是镜像源（如 npmmirror.com）， 发布时务必加 --registry=https://registry.npmjs.org，否则会尝试发布到镜像源而失败。 镜像源通常只用于加速下载，不支持普通用户发布。

要求：Node.js ≥ 14，git 已安装且在 PATH 中。

命令一览

| 命令 | 别名 | 组合内容 | 说明 | | --- | --- | --- | --- | | pith init [--branch <name>] | — | git init -b main . | 初始化仓库，默认初始分支 main，可 --branch/-b 指定；已是仓库时安全重新初始化 | | pith commit [message] | ci / quick | add -A + commit | 一键提交全部更改，缺省 message 时交互输入 | | pith push [message] [<remote-url>] | pu | add . + commit + push | 提交当前目录变更并推送，无上游时自动 -u（原 ship，仓库根目录下与 add -A 等价）；目录不是仓库或无远程时自动 init / link（地址交互输入，或第二个参数传入） | | pith sync [--stash] [--no-push] | pull-push | pull --rebase + push | 同步远端；--stash 自动暂存本地更改 | | pith switch <branch> | sw | checkout / checkout -b | 分支已存在直接切换；不存在则基于当前分支新建并切换 | | pith newbranch <branch> [--base <branch>] | br / branch | 校验 + push + checkout -b | 有未保存变更时拒绝；基于远端 main/master 新建分支并检出 | | pith pick [message] | — | 选文件 + add + commit | 交互式挑选文件提交（支持 1,3-5 / all） | | pith stash-pull | sp | stash + pull --rebase + stash pop | 暂存本地更改后同步远端再恢复 | | pith amend [--push] | — | add -A + commit --amend | 追加到上次提交；--push 时 --force-with-lease | | pith uncommit [--hard] | undo | reset --soft/--hard HEAD~1 | 撤销上次提交，默认保留更改 | | pith clean [--dry-run] [-f] | prune | fetch --prune + 删已合并分支 | 清理本地冗余分支，保护常用分支 | | pith ignore <pattern...> [--commit] | gi | 写 .gitignore + 提示 | 忽略规则一键写入，提示已跟踪文件 | | pith config [user] [<user> <email>] | cfg | git config --global | 无参数时交互输入用户名/邮箱；或以 --global 设置（支持 pith config user <user> <email>） | | pith link [<name>] <url> | remote | remote add / remote set-url | 关联远程仓库（默认名 origin）；远程已存在时确认后更新地址，无参数时交互输入 | | pith info | st / status | status -sb + log | 仓库概览：分支、状态、最近提交 |

全局参数：-y/--yes（跳过确认）、--no-color、-h/--help、-v/--version。

使用示例

# 初始化仓库（默认分支 main；--branch/-b 可指定初始分支）
pith init
pith init --branch develop

# 快速提交（交互输入提交信息）
pith commit

# git add . + git commit -m + git push 合体（原 ship；根目录下与 add -A 等价）
pith push "feat: 用户登录"

# 目录还不是 git 仓库 / 没有关联远程时，自动 init 和 link：
# 地址交互输入，或作为第二个参数传入（非交互环境必须传参）
pith push "feat: 初始化" [email protected]:user/repo.git

# 同步：先 rebase 拉取再推送；工作区脏时自动 stash
pith sync --stash

# 切换分支：已存在直接切换，不存在则基于当前分支新建
pith switch feature/order

# 有未保存的变更时拒绝创建；先提交（pith commit）或暂存（git stash）再运行
# 工作区干净时，基于远端 main/master 新建分支并检出
pith newbranch feature/pay
pith newbranch hotfix/urgent --base master

# 切换分支；本地不存在则自动 git checkout -b <b> origin/<b>
pith switch develop

# 交互式挑选文件提交
pith pick "fix: 部分文件"
#   1. M  src/a.js
#   2. ?? src/b.js
# 选择序号（如 1 / 1,3-5 / all，0 取消）: 1

# 暂存本地修改 → 拉取 → 恢复修改
pith stash-pull

# 把当前修改追加到上一次提交，并强制推送
pith amend --push

# 撤销上次提交（更改留在暂存区）
pith uncommit

# 清理已合并分支（交互确认；--dry-run 预览）
pith clean --dry-run
pith clean -f

# 忽略规则
pith ignore "*.log" node_modules/ --commit

# 设置全局 Git 身份（--global）：无参数时交互输入用户名、邮箱
pith config
# 输入用户名: 张三
# 输入邮箱: [email protected]
# 等价于 git config --global user.name / user.email

# 或直接传参（两种写法等价）
pith config "张三" "[email protected]"
pith config user "张三" "[email protected]"

# 关联远程仓库：默认名 origin；远程已存在时确认后更新地址
pith link [email protected]:user/repo.git
pith link upstream https://github.com/user/repo.git
pith link（交互输入远程地址，回车默认 origin）

# 查看仓库概览
pith info

自定义组合命令

在当前目录或用户目录创建 .pithrc.json（旧名 .gitxrc.json 仍兼容，新名优先），通过 custom 字段注册组合命令，每个 step 是传给 git 的参数数组，按顺序执行、失败即中止：

{
  "custom": {
    "deploy": [
      ["fetch", "origin"],
      ["pull", "--rebase"],
      ["push", "origin", "main"]
    ],
    "wip": [
      ["add", "-A"],
      ["commit", "-m", "wip"]
    ]
  }
}

pith deploy    # 依次执行 fetch / pull --rebase / push
pith help      # 自定义命令会出现在命令列表中

自定义命令与内置命令重名时会报错；配置文件解析失败会给出明确提示。

设计说明

• 执行模型：child_process.spawnSync 调用系统 git，捕获输出用于判断（git()），交互命令透传 stdio（gitLive()，如 push 进度条）
• 交互输入：全程单例 readline，管道输入（echo "y" | pith clean）下多次提问不丢数据，EOF 时安全返回默认值；命令执行完毕后自动关闭，进程立即退出（不会挂起等待输入）
• 退出码：0 成功；1 git/运行时错误；2 用法错误
• 环境变量：NO_COLOR 关闭颜色；PITH_DEBUG=1 输出错误堆栈
• 兼容性：仅使用 ES2018 及以下语法与 Node 14 内置 API（无 replaceAll、Array.at、fs.rmSync 依赖等），engines.node >= 14

目录结构

├── bin/pith.js            # CLI 入口（shebang + Node 版本检查）
├── lib/
│   ├── cli.js             # 参数解析、命令分发、帮助/版本
│   ├── git.js             # git 执行器（捕获输出 / 透传 stdio）
│   ├── ui.js              # 彩色输出、交互输入（单例 readline）
│   ├── helpers.js         # 共享逻辑：推送、提交、分支校验等
│   ├── custom.js          # .pithrc.json 自定义命令加载
│   ├── errors.js          # GitError(1) / UsageError(2)
│   └── commands/          # 15 个内置组合命令
└── test/run-tests.js      # 集成测试（真实 git 仓库，58 个用例）

开发与测试

npm test                    # 在临时目录创建真实 git 仓库跑集成测试
node bin/pith.js --help     # 本地预览

License

MIT