snail-git-add

v2.0.0

Published

a month ago

Interactive git add, commit and push tool with conventional commits and remote checks

0High
0Medium
0Low

hu-snail01

git interactive add commit push conventional-commits remote branch cli snail-admin

snail-git-add

一个功能强大的交互式 Git 工作流工具，支持智能文件选择和约定式提交规范。

Interactive git add, commit and push tool with conventional commits and remote checks

✨ 特性

🎯 交互式文件选择 - 可视化选择要暂存的文件，支持文件状态高亮显示
📝 约定式提交 - 遵循标准提交规范，生成规范的提交信息
🎨 彩色终端输出 - 文件状态使用不同颜色区分（修改-黄色，新增-绿色，删除-红色，重命名-蓝色）
🔄 完整工作流 - 从文件选择、提交到推送的一站式解决方案
📋 交互式菜单 - 提供主菜单和高级工具菜单，方便管理 Git 仓库
🌿 分支管理 - 创建、切换、删除和合并分支
📜 提交历史 - 查看和管理提交历史
🗂️ Stash 管理 - 暂存和恢复工作区更改
🏷️ 标签管理 - 创建、删除和推送标签
🔗 远程管理 - 管理远程仓库和分支
⚙️ 灵活配置 - 支持多种使用场景和自定义选项
🛡️ 类型安全 - 使用 TypeScript 开发，提供完整的类型定义
📦 模块化设计 - 清晰的代码结构，易于扩展和维护

📦 安装

# 使用 npm
npm install -D snail-git-add

# 使用 yarn
yarn add -D snail-git-add

# 使用 pnpm
pnpm add -D snail-git-add

🚀 快速开始

基本使用

# 交互式选择文件并提交
npx snail-git-add

完整工作流示例

运行命令：
```
npx snail-git-add
```
选择要暂存的文件（使用空格选择，回车确认）
填写提交信息：
- 选择提交类型（feat、fix、docs 等）
- 输入作用域（可选）
- 编写提交主题
- 添加详细描述（可选）
确认并完成提交

📖 使用指南

主菜单功能

启动工具后，您将看到主菜单，提供以下选项：

| 选项 | 描述 | |------|------| | 查看状态 | 显示当前 Git 仓库的状态，包括修改的文件、已暂存的文件等 | | 提交更改 | 交互式选择要暂存的文件并提交 | | 管理分支 | 创建、切换、删除和合并分支 | | 查看历史记录 | 查看提交历史，支持查看详细信息和搜索 | | 管理 Stash | 暂存当前工作区的更改，或恢复之前的暂存 | | 管理标签 | 创建、删除和推送标签 | | 管理远程 | 添加、删除和查看远程仓库，推送和拉取代码 | | 配置设置 | 配置工具的默认行为和偏好设置 | | 高级工具 | 提供高级 Git 操作工具 | | 退出 | 退出工具 |

命令行选项

| 参数 | 简写 | 描述 | 示例 | |------|------|------|------| | --help | -h | 显示帮助信息 | npx snail-git-add --help | | --version | -V | 显示版本信息 | npx snail-git-add --version | | --auto-commit | - | 添加文件后自动进入提交流程 | npx snail-git-add --auto-commit | | --commit-only | - | 只提交已暂存的文件（不添加新文件） | npx snail-git-add --commit-only | | --push-only | - | 只执行推送（不添加或提交文件） | npx snail-git-add --push-only | | --all | -a | 默认选择所有修改的文件 | npx snail-git-add --all | | --cwd | -c | 指定工作目录 | npx snail-git-add --cwd ./project-path | | --status | -s | 只显示 Git 状态，不进行任何操作 | npx snail-git-add --status | | --no-status | - | 添加后不显示状态信息 | npx snail-git-add --no-status | | --auto-push | - | 提交后自动推送到远程仓库 | npx snail-git-add --auto-push | | --check-remote | - | 只检查远程分支状态 | npx snail-git-add --check-remote | | --branches | - | 分支管理 | npx snail-git-add --branches | | --log | - | 查看提交历史 | npx snail-git-add --log | | --undo | - | 撤销操作 | npx snail-git-add --undo | | 无参数 | - | 启动交互式主菜单（默认） | npx snail-git-add |

编程方式使用

import { interactiveGitAdd, createInteractiveGitAdd } from 'snail-git-add';

// 基本使用 - 交互式添加文件并提交
await interactiveGitAdd.addSelectedFiles();

// 自动提交模式
await interactiveGitAdd.addSelectedFiles({
  autoCommit: true,
  selectAllByDefault: false,
  showStatusAfterAdd: true
});

// 只执行提交（针对已暂存的文件）
await interactiveGitAdd.interactiveCommit();

// 在指定目录中使用
const gitAdd = createInteractiveGitAdd('/path/to/your/project');
await gitAdd.addSelectedFiles();

// 获取修改的文件列表
const modifiedFiles = await interactiveGitAdd.getModifiedFiles();
console.log(`找到 ${modifiedFiles.length} 个修改的文件`);

// 显示当前 Git 状态
await interactiveGitAdd.showStatus();

提交类型规范

工具遵循约定式提交规范，支持以下提交类型：

| 类型 | 描述 | 示例 | |------|------|------| | feat | 新功能 | feat(auth): 添加用户登录功能 | | fix | 修复 bug | fix(api): 修复数据查询错误 | | docs | 文档更新 | docs(readme): 更新安装说明 | | style | 代码格式调整 | style: 格式化代码缩进 | | refactor | 代码重构 | refactor(utils): 优化工具函数 | | perf | 性能优化 | perf(db): 优化数据库查询 | | test | 测试相关 | test(auth): 添加登录测试用例 | | build | 构建系统变更 | build: 更新 webpack 配置 | | ci | CI 配置变更 | ci: 添加 GitHub Actions | | chore | 其他修改 | chore: 更新依赖版本 | | revert | 回滚提交 | revert: 回滚某次错误提交 |

提交信息格式

类型(作用域): 主题

详细描述（可选）

脚注信息（可选）

示例：

feat(auth): 添加 JWT 认证功能

- 实现用户登录接口
- 添加 token 验证中间件
- 更新用户认证文档

Closes #123

🚀 推送功能

工具提供了强大的交互式推送功能，帮助您安全地将本地提交推送到远程仓库：

推送流程

检查远程状态 - 自动检查本地分支与远程分支的差异
处理冲突 - 如果存在需要合并的分支，提供拉取合并或强制推送选项
预览提交 - 显示要推送的所有提交和修改的文件列表
确认推送 - 提示用户确认是否继续推送
执行推送 - 显示推送进度并完成操作

自动推送选项

# 提交后自动推送到远程仓库
npx snail-git-add --auto-push

# 编程方式使用自动推送
await interactiveGitAdd.addSelectedFiles({
  autoCommit: true,
  autoPush: true
});

推送前的提交预览

在推送前，工具会显示详细的提交信息和修改的文件列表，帮助您确认推送内容：

要推送的提交：

提交 1:
哈希：a1b2c3d4
作者：张三
日期：2023-10-15T10:30:00Z
信息：feat(auth): 添加用户登录功能
修改的文件：
  - src/auth/login.ts
  - src/auth/validate.ts
  - src/docs/auth.md

提交 2:
哈希：e5f6g7h8
作者：李四
日期：2023-10-15T11:45:00Z
信息：fix(api): 修复数据查询错误
修改的文件：
  - src/api/query.ts

🔧 配置选项

GitAddOptions

interface GitAddOptions {
  // 工作目录路径（默认：process.cwd()）
  cwd?: string;
  
  // 添加后是否显示状态信息（默认：true）
  showStatusAfterAdd?: boolean;
  
  // 是否默认选择所有文件（默认：false）
  selectAllByDefault?: boolean;
  
  // 是否自动进入提交流程（默认：false）
  autoCommit?: boolean;
  
  // 提交后是否自动推送到远程仓库（默认：false）
  autoPush?: boolean;
}

其他接口

// 文件状态接口
export interface FileStatus {
  path: string;           // 文件路径
  index: string;          // 文件状态代码（M/A/D/R）
  working_dir: string;    // 工作目录状态
  isStaged: boolean;      // 是否已暂存
}

// 提交信息接口
export interface CommitInfo {
  type: string;           // 提交类型
  scope?: string;         // 作用域（可选）
  subject: string;        // 提交主题
  body?: string;          // 详细描述（可选）
  footer?: string;        // 脚注信息（可选）
}

// 分支信息接口
export interface BranchInfo {
  name: string;           // 分支名称
  isCurrent: boolean;     // 是否为当前分支
  isRemote: boolean;      // 是否为远程分支
  commit: string;         // 最新提交哈希
  message: string;        // 最新提交信息
}

// 远程分支状态接口
export interface RemoteBranchInfo {
  name: string;           // 分支名称
  ahead: number;          // 领先远程的提交数
  behind: number;         // 落后远程的提交数
  needsMerge: boolean;    // 是否需要合并
}

在项目中的集成示例

// scripts/git-commit.ts
import { interactiveGitAdd } from 'snail-git-add';

// 自定义提交脚本
async function main() {
  try {
    await interactiveGitAdd.addSelectedFiles({
      autoCommit: true,
      selectAllByDefault: process.argv.includes('--all')
    });
  } catch (error) {
    console.error('提交过程出错：', error);
    process.exit(1);
  }
}

main();

在 package.json 中添加脚本：

{
  "scripts": {
    "commit": "ts-node scripts/git-commit.ts",
    "commit:all": "ts-node scripts/git-commit.ts --all"
  }
}

🎯 使用场景

日常开发工作流

# 启动主菜单，进行完整的 Git 操作
npx snail-git-add

# 开发完成后，快速提交当前改动
npx snail-git-add --auto-commit

# 或者使用快捷方式（如果配置了 package.json 脚本）
npm run commit

代码审查前整理提交

# 选择性提交部分文件，保持提交的原子性
npx snail-git-add

# 只提交已暂存的文件（用于拆分大提交）
npx snail-git-add --commit-only

# 查看提交历史，确保提交记录清晰
npx snail-git-add --history

团队协作规范

# 确保所有提交都符合团队规范
npx snail-git-add --auto-commit

# 提交后自动推送到远程仓库
npx snail-git-add --auto-commit --auto-push

# 统一分支管理
npx snail-git-add --branches

分支管理

# 创建新分支
npx snail-git-add --branches

# 切换到其他分支
npx snail-git-add --branches

# 合并分支
npx snail-git-add --branches

Stash 管理

# 暂存当前工作区的更改
npx snail-git-add --stash

# 恢复之前的暂存
npx snail-git-add --stash

# 查看所有暂存记录
npx snail-git-add --stash

标签管理

# 创建新标签
npx snail-git-add --tags

# 推送标签到远程仓库
npx snail-git-add --tags

# 查看所有标签
npx snail-git-add --tags

🔍 故障排除

常见问题

Q: 运行命令时提示 "当前目录不是 git 仓库" A: 确保在 Git 仓库的根目录中运行命令，或使用 --cwd 参数指定正确的目录。

Q: 提交时遇到 "没有已暂存的文件可以提交" A: 先使用 npx snail-git-add 选择并暂存文件，或直接使用 git add 命令添加文件。

Q: 编辑器打开后不知道如何保存退出 A: 在 Vim 中按 ESC 后输入 :wq 回车；在 Nano 中按 Ctrl+X 然后按 Y 确认。

环境要求

Node.js >= 14.0.0
Git >= 2.0.0

调试模式

# 显示详细错误信息
DEBUG=* npx snail-git-add

# 或使用 Node.js 调试模式
node --inspect-brk bin/cli.js

🤝 贡献

欢迎提交 Issue 和 Pull Request！

Fork 本仓库
创建特性分支：git checkout -b feature/amazing-feature
提交更改：git commit -m 'feat: add some amazing feature'
推送到分支：git push origin feature/amazing-feature
开启 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🏗️ 开发

# 克隆项目
git clone https://github.com/snail-admin/git-add.git

# 安装依赖
npm install

# 构建项目
npm run build

# 开发模式（监听文件变化）
npm run dev

# 运行测试
npm test

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

snail-git-add

✨ 特性

📦 安装

🚀 快速开始

基本使用

完整工作流示例

📖 使用指南

主菜单功能

命令行选项

编程方式使用

提交类型规范

提交信息格式

🚀 推送功能

推送流程

自动推送选项

推送前的提交预览

🔧 配置选项

GitAddOptions

其他接口

在项目中的集成示例

🎯 使用场景

日常开发工作流

代码审查前整理提交

团队协作规范

分支管理

Stash 管理

标签管理

🔍 故障排除

常见问题

环境要求

调试模式

🤝 贡献

📄 许可证

🏗️ 开发