# git-aid

**Repository Path**: prettyboyazu/git-aid

## Basic Information

- **Project Name**: git-aid
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-27
- **Last Updated**: 2026-04-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# git-aid 项目交接文档

> Git 新手助手 - 可视化命令图解、交互式引导、智能错误诊断

---

## 一、项目简介

git-aid 是一个命令行工具，帮助编程新手理解和使用 Git。

**它能做什么：**
- 用通俗的中文解释每个 Git 命令，附带 ASCII 图解和生动比喻
- 自动诊断你当前仓库的问题，给出解决方案
- 可视化显示仓库状态（分支、提交历史）
- 手把手引导你完成冲突解决、撤销提交等操作
- 提供 Git 工作流教学（分支策略、团队协作）

---

## 二、环境要求

在开始之前，确保你的电脑已经安装了以下软件：

| 软件 | 最低版本 | 检查命令 | 如何安装 |
|------|---------|---------|---------|
| **Node.js** | >= 18.0.0 | `node -v` | https://nodejs.org 下载 LTS 版本 |
| **npm** | >= 9.0（随 Node.js 自带） | `npm -v` | 随 Node.js 一起安装 |
| **Git** | 任意版本 | `git --version` | https://git-scm.com/downloads |

> **提示：** Windows 用户建议使用 Git Bash 或 Windows Terminal 运行命令。

验证环境：
```bash
node -v        # 应输出 v18.x.x 或更高
npm -v         # 应输出 9.x.x 或更高
git --version  # 应输出 git version x.x.x
```

---

## 三、从零开始安装（5 步）

### 第 1 步：获取源代码

将源代码复制到你的工作目录。假设你放在 `D:\workspace\git-aid`：

```bash
# 如果通过 Git 克隆
git clone <仓库地址> D:\workspace\git-aid

# 或者直接复制整个文件夹到 D:\workspace\git-aid
```

### 第 2 步：进入项目目录

```bash
cd D:\workspace\git-aid
```

### 第 3 步：安装依赖

```bash
npm install
```

> 这会安装所有必需的依赖包（commander, chalk, boxen, simple-git 等）。需要联网，大约 1-2 分钟。

### 第 4 步：构建项目

```bash
npm run build
```

> 这会把 TypeScript 源码编译为可执行的 JavaScript，输出到 `dist/` 目录。

### 第 5 步：全局安装（可选但推荐）

```bash
npm link
```

> 安装后你就可以在任何目录直接使用 `git-aid` 命令了。

---

## 四、验证安装

运行以下命令确认一切正常：

```bash
# 查看欢迎界面
git-aid

# 查看命令图解
git-aid explain commit

# 列出所有可用内容
git-aid list
```

如果看到彩色卡片输出，说明安装成功。

---

## 五、如何使用

### 5.1 了解 Git 命令

当你不确定某个 Git 命令的作用时：

```bash
git-aid explain commit     # 了解 commit
git-aid explain push       # 了解 push
git-aid explain pull       # 了解 pull
git-aid explain merge      # 了解 merge
git-aid explain branch     # 了解 branch
git-aid explain checkout   # 了解 checkout
git-aid explain stash      # 了解 stash
git-aid explain rebase     # 了解 rebase
```

每个命令会显示：
- 通俗的中文解释
- 生动的比喻（帮助理解）
- ASCII 流程图
- 常用命令示例
- 常见错误和解决办法
- 相关命令链接

### 5.2 遇到 Git 问题时自动诊断

在你的 Git 项目目录下运行：

```bash
git-aid troubleshoot
```

它会自动检测：
- 合并冲突
- 分离的 HEAD 状态
- 未提交的更改
- 推送被拒绝
- 缺少上游分支
- 过多未跟踪文件

然后给出针对性的解决方案。

### 5.3 可视化查看仓库状态

```bash
git-aid visualize
```

显示当前分支、提交历史图、工作区状态。

### 5.4 跟着步骤一步步操作

```bash
git-aid workflow resolve-conflict   # 解决合并冲突（手把手）
git-aid workflow undo-commit        # 撤销上一次提交（手把手）
```

每一步都有详细解释，按回车进入下一步。

### 5.5 系统学习 Git 概念

```bash
git-aid guide branching-strategies  # 学习分支管理策略
```

### 5.6 切换语言

```bash
git-aid config --lang en      # 切换英文
git-aid config --lang zh-CN   # 切换中文（默认）
```

### 5.7 查看所有可用内容

```bash
git-aid list
```

---

## 六、项目结构

```
git-aid/
├── package.json                 # 项目配置和依赖声明
├── tsconfig.json                # TypeScript 编译配置
├── tsup.config.ts               # 构建工具配置
├── .gitignore                   # Git 忽略规则
│
├── src/                         # 源代码
│   ├── cli/                     # CLI 入口和命令定义
│   │   ├── index.ts             # 主入口，注册所有命令
│   │   └── commands/            # 每个子命令一个文件
│   │       ├── explain.ts       # git-aid explain
│   │       ├── troubleshoot.ts  # git-aid troubleshoot
│   │       ├── visualize.ts     # git-aid visualize
│   │       ├── workflow.ts      # git-aid workflow
│   │       ├── guide.ts         # git-aid guide
│   │       ├── config.ts        # git-aid config
│   │       └── list.ts          # git-aid list
│   │
│   ├── core/                    # 核心业务逻辑（与 UI 无关）
│   │   ├── engine/
│   │   │   └── ascii-renderer.ts    # ASCII 图形渲染引擎
│   │   ├── models/
│   │   │   └── types.ts             # 类型定义
│   │   └── services/
│   │       ├── git.service.ts           # Git 操作封装
│   │       ├── diagram.service.ts       # 终端卡片渲染
│   │       └── error-diagnostic.service.ts  # 错误诊断
│   │
│   ├── data/                    # 内容数据（YAML 文件）
│   │   ├── commands/            # 8 个命令详解
│   │   ├── errors/              # 3 个错误模式
│   │   ├── guides/              # 1 个学习指南
│   │   └── workflows/           # 2 个交互式工作流
│   │
│   ├── i18n/                    # 国际化
│   │   ├── index.ts             # i18n 逻辑
│   │   └── locales/             # zh-CN.json, en.json
│   │
│   └── shared/                  # 共享工具
│       ├── config.ts            # 用户配置管理
│       └── data-loader.ts       # YAML 数据加载器
│
└── dist/                        # 构建输出（npm run build 后生成）
```

---

## 七、开发命令

```bash
# 开发模式运行（不需要构建）
npm run dev                      # 等同于 npx tsx src/cli/index.ts

# 构建项目
npm run build                    # 编译到 dist/

# 类型检查
npm run lint                     # tsc --noEmit

# 运行测试
npm test                         # vitest run

# 全局安装（开发时用）
npm link                         # 注册全局 git-aid 命令

# 取消全局安装
npm unlink -g git-aid
```

---

## 八、如何扩展内容

### 8.1 添加新的命令解释

在 `src/data/commands/` 下新建 YAML 文件，例如 `src/data/commands/reset.yaml`：

```yaml
id: reset
name: git reset
category: basics
difficulty: intermediate
tags: [reset, undo, rollback]
explanations:
  zh-CN:
    short: "回退到指定的提交状态"
    long: |
      git reset 用于将当前分支的 HEAD 指针移动到指定位置。
      可以选择保留或丢弃更改。
    analogy: "就像撤销操作——回到之前的某个状态。"
  en:
    short: "Reset current HEAD to a specified state"
    long: |
      git reset moves the HEAD pointer to a specified position.
      You can choose to keep or discard changes.
    analogy: "Like an undo operation - go back to a previous state."
diagram: |
  当前: A --- B --- C (HEAD)
  reset --soft HEAD~1:
  结果: A --- B (HEAD)  [C 的更改在暂存区]
examples:
  - title:
      zh-CN: "软重置（保留更改在暂存区）"
      en: "Soft reset (keep changes staged)"
    command: "git reset --soft HEAD~1"
    description:
      zh-CN: "回退一个提交，更改保留在暂存区"
      en: "Go back one commit, changes stay staged"
commonErrors:
  - error: "fatal: ambiguous argument"
    solution:
      zh-CN: "指定的提交不存在。用 git log 查看有效的提交记录。"
      en: "Specified commit doesn't exist. Use git log to check."
related: [commit, checkout, revert]
```

然后用 `git-aid explain reset` 就能看到了。

### 8.2 添加新的交互式工作流

在 `src/data/workflows/` 下新建 YAML 文件。

### 8.3 添加新的学习指南

在 `src/data/guides/` 下新建 YAML 文件。

### 8.4 添加新的错误模式

在 `src/data/errors/` 下新建 YAML 文件。

---

## 九、技术栈说明

| 技术 | 用途 |
|------|------|
| TypeScript 5.x | 主要开发语言 |
| Commander.js | CLI 命令解析和路由 |
| chalk 5 | 终端彩色输出 |
| boxen 7 | 终端边框卡片 |
| simple-git | Git 操作封装（调用系统 Git） |
| yaml | 解析 YAML 内容文件 |
| @clack/prompts | 交互式提示（工作流中使用） |
| ora | 加载动画 |
| string-width | 处理中文字符宽度 |
| wrap-ansi | 中文自动换行 |
| tsup | TypeScript 构建工具 |

---

## 十、常见问题

### Q: 运行 `git-aid` 提示 "command not found"

**A:** 需要先运行 `npm link` 全局注册命令。或者用 `npx tsx src/cli/index.ts` 直接运行。

### Q: 运行 `npm run build` 后 `git-aid explain xxx` 找不到数据

**A:** 确保 `dist/data/` 目录存在且包含 YAML 文件。重新运行 `npm run build`。

### Q: 中文显示乱码或对齐不正常

**A:** 建议使用 Windows Terminal、Git Bash 或 iTerm2 等现代终端。CMD 可能不支持 Unicode 字符。

### Q: `git-aid troubleshoot` 提示不是 Git 仓库

**A:** 需要在 Git 仓库目录下运行。先 `cd` 到你的项目目录。

### Q: 如何卸载

**A:** 运行 `npm unlink -g git-aid`，然后删除项目文件夹即可。

---

## 十一、npm 脚本速查

| 命令 | 说明 |
|------|------|
| `npm install` | 安装依赖 |
| `npm run build` | 构建项目 |
| `npm run dev` | 开发模式运行 |
| `npm run lint` | 类型检查 |
| `npm test` | 运行测试 |
| `npm link` | 全局安装 |
| `npm unlink -g git-aid` | 取消全局安装 |

---

## 十二、文件清单

交接时应包含以下文件（不包含 `node_modules/` 和 `dist/`）：

```
package.json
package-lock.json
tsconfig.json
tsup.config.ts
.gitignore
src/  (整个目录)
```

接收方只需运行 `npm install && npm run build && npm link` 即可开始使用。