Git 使用说明

> 以下覆盖日常开发中最常用的 Git 操作，按场景分类。

---

## 一、基础配置

```bash
# 首次使用
git config --global user.name "你的名字"
git config --global user.email "你的邮箱"

# 常用别名
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.st status
git config --global alias.lg "log --oneline --graph --all --decorate"
```

---

## 二、日常开发流程

### 1. 克隆仓库
```bash
git clone <仓库地址>
git clone -b <分支名> <仓库地址>   # 克隆指定分支
```

### 2. 分支操作
```bash
git branch                    # 查看本地分支
git branch -r                 # 查看远程分支
git branch -a                 # 查看所有分支

git checkout -b feature/xxx   # 创建并切换到新分支
git switch -c feature/xxx     # 同上（新版语法）

git branch -d feature/xxx     # 删除本地分支（已合并）
git branch -D feature/xxx     # 强制删除（未合并）

git push origin --delete feature/xxx   # 删除远程分支
```

### 3. 三板斧：add → commit → push
```bash
git status                    # 查看变更
git diff                      # 查看具体改动
git add .                     # 暂存所有变更
git add 文件名                 # 暂存单个文件

git commit -m "feat: 添加用户注册功能"
git push origin HEAD          # 推送到当前分支的远程

# 如果远程分支不存在
git push -u origin feature/xxx   # -u 建立追踪关系，后续只需 git push
```

#### 实例：

    您需要手动在终端中执行以下命令：
   
    ```bash
    cd /Users/liquancun/file-transfer
    git add -A
    git commit -m "refactor: 将项目文件从 file-transfer-app 目录移到根目录"
    git push origin master
    ```
   
    或者，如果您已经移动了文件，可能需要重新设置 git 仓库：
   
    ```bash
    cd /Users/liquancun/file-transfer
    git init
    git add -A
    git commit -m "init: 重新初始化仓库，项目文件在根目录"
    git remote add origin https://github.com/isaveall/file-transfer.git
    git push -f origin master
    ```

### 4. 拉取最新代码
```bash
git pull                      # 拉取并合并（推荐）
git pull --rebase             # 拉取并变基（保持线性历史）
git fetch                     # 只拉取，不合并
```

---

### 新建的Claude code 项目git流程

```

# 查看当前目录下的git状态
Bash(git status)                                                                                                                                   
  ⎿  Error: Exit code 128                                                                                                                            
     fatal: not a git repository (or any of the parent directories): .git                                                                            
                                 
⏺ Bash(git remote -v)                                                                                                                                
  ⎿  Error: Exit code 128                                                                                                                            
     fatal: not a git repository (or any of the parent directories): .git
                                                                                                                                                     
⏺ Bash(git log --oneline -5)                                                                                                                         
  ⎿  Error: Exit code 128                                                
     fatal: not a git repository (or any of the parent directories): .git                                                                            
                                                                                                                                                     
⏺ 当前目录还不是 git 仓库，也没有配置远程仓库。请告诉我 GitHub 仓库的 URL（如 git@github.com:username/repo.git 或
  https://github.com/username/repo.git），我来完成初始化和推送。 

【告诉我在github上新建的仓库URL】
https://github.com/isaveall/world-knowledge.git

# 执行git 初始化验证授权
⏺ Bash(git init && git add -A && git commit -m "$(cat <<'EOF'
      Initial commit: API documentation management system…)
  ⎿  Error: Exit code 128
     Initialized empty Git repository in /Users/liquancun/world-knowledge/.git/
     Author identity unknown

     *** Please tell me who you are.

     Run

       git config --global user.email "you@example.com"
       git config --global user.name "Your Name"
     … +5 lines (ctrl+o to see all)

⏺ Bash(git config user.email "isaveall@github.com" && git config user.name "iSaveall")
  ⎿  (No output)

# 验证通过后，首次上传全部源码，提交备注
⏺ Bash(git add -A && git commit -m "$(cat <<'EOF'
      Initial commit: API documentation management system…)
  ⎿  [main (root-commit) 1a8c4f3] Initial commit: API documentation management system
      69 files changed, 13907 insertions(+)
      create mode 100644 .gitignore
     … +31 lines (ctrl+o to expand)

⏺ Bash(git remote add origin https://github.com/isaveall/world-knowledge.git && git push -u origin main)

如果验证失败，根据提示协助Claude进行Git验证，如果验证成功，
推送很快进展。

已成功推送到 GitHub。

```

## 三、代码提交规范（Conventional Commits）

```
<type>(<scope>): <subject>

格式：
feat:    新功能
fix:     修复 bug
docs:    文档
style:   格式调整（不影响代码逻辑）
refactor: 重构
test:    测试
chore:   构建/工具
```

**示例：**
```
feat: 添加用户登录接口
fix(cart): 修复购物车数量溢出问题
docs: 更新 API 使用说明
```

---

## 四、撤销与回退

```bash
# 工作区撤销（还没 git add）
git restore 文件名
git checkout -- 文件名        # 旧版写法

# 暂存区撤销（已经 git add，还没 commit）
git restore --staged 文件名

# 撤销最近一次 commit（保留改动）
git reset --soft HEAD~1

# 撤销最近一次 commit（丢弃改动）
git reset --hard HEAD~1       # ⚠️ 危险，会丢失代码

# 回退到指定版本（保留历史记录）
git revert HEAD               # 生成一个反向提交
git revert <commit-id>        # 回退到某次提交

# 把某次提交的改动搬到当前分支
git cherry-pick <commit-id>
```

---

## 五、合并与冲突解决

```bash
# 将 feature 分支合并到 main
git checkout main
git merge feature/xxx

# 变基（使历史更干净）
git checkout feature/xxx
git rebase main

# 交互式变基（合并多个 commit）
git rebase -i HEAD~3
```

**冲突解决：**

```
<<<<<<< HEAD
当前分支的代码
=======
合并进来的代码
>>>>>>> feature/xxx
```

1. 手动编辑冲突文件，保留需要的代码
2. `git add <冲突文件>`
3. `git commit`（merge）或 `git rebase --continue`（rebase）

---

## 六、储藏（Stash）

```bash
# 临时保存工作区改动
git stash                    # 等价于 git stash push
git stash save "描述信息"

# 查看储藏列表
git stash list

# 恢复并删除
git stash pop                # 恢复最近一个并删除
git stash pop stash@{2}      # 恢复指定储藏

# 恢复但不删除
git stash apply

# 删除
git stash drop stash@{1}
git stash clear              # 删除所有储藏
```

**典型场景：**正在开发 A，突然需要修紧急 bug，先把 A 的改动 stash 起来。

---

## 七、查看历史

```bash
git log                      # 完整日志
git log --oneline            # 一行显示
git log --oneline --graph    # 图形化
git log -p                   # 显示每个 commit 的具体改动
git log --author="xxx"       # 按作者筛选
git log --since="2026-01-01" # 按时间筛选

git blame 文件名              # 每行代码是谁改的
git show <commit-id>         # 查看某次提交详情
```

---

## 八、常用工作流示例

### 完整开发流程
```bash
# 1. 拉取最新代码
git checkout main
git pull

# 2. 创建功能分支
git checkout -b feat-login

# 3. 开发、提交
git add .
git commit -m "feat: 登录功能"
git push -u origin feat-login

# 4. 拉起 PR/MR → 代码审查 → 合并

# 5. 合并后删除本地分支
git checkout main
git pull
git branch -d feat-login
```

### 紧急修复流程
```bash
git stash                    # 保存当前工作
git checkout -b hotfix/crash # 从主分支开修复分支
# 修复...
git commit -am "fix: 修复崩溃"
git push
# 合并到 main 后
git checkout main
git pull
git stash pop                # 恢复之前的工作
```

---

## 九、Git 工作流对比

| 工作流 | 适用场景 | 特点 |
|--------|---------|------|
| **GitHub Flow** | 小型团队 | 1 个 main 分支 + 功能分支 + PR |
| **Git Flow** | 大项目、发版 | main + develop + feature + release + hotfix |
| **GitLab Flow** | 持续部署 | main + environment 分支（staging/production） |

---

## 十、避坑指南

⚠️ **不要** `git push --force` 到共享分支（除非你知道后果），用 `--force-with-lease` 更安全。

⚠️ **不要** 在 main/master 上直接提交，永远用分支 + PR。

⚠️ **不要** commit 大文件（>100MB），用 `.gitignore` 排除或 `git lfs` 管理。

⚠️ **及时** 写有意义的 commit message，不要 `"fix"` 或 `"update"`。

⚠️ **定期** `git fetch` + `git remote prune origin` 清理过期的远程分支。