Git 使用指南：日常开发工作流与常见问题

1. 概述

Git 是现代软件开发中不可或缺的版本控制工具。本文总结了在日常 Rust 项目（如 Ashell、Blog-SSR）开发中常用的 Git 操作、工作流程以及踩坑记录，方便查阅。

2. 基础配置

2.1 用户身份

提交代码前必须先设置用户信息：

# 全局配置（影响所有仓库）
git config --global user.name "Your Name"
git config --global user.email "your@email.com"

# 局部配置（仅当前仓库）
git config user.name "Your Name"
git config user.email "your@email.com"

# 查看配置
git config --list
git config user.name

2.2 常用别名

git config --global alias.st status
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.lg "log --oneline --graph --all --decorate"

3. 日常开发工作流

3.1 标准流程

# 1. 查看当前状态
git status

# 2. 暂存变更
git add <file>          # 添加指定文件
git add .               # 添加所有变更
git add -p              # 交互式分块暂存

# 3. 提交
git commit -m "feat: 简洁清晰的提交信息"

# 4. 推送到远程
git push origin main

3.2 提交信息规范

推荐使用 Conventional Commits 规范：

<type>: <简短描述>

- <type>: feat, fix, docs, style, refactor, perf, test, chore
- 描述使用中文或英文均可，但建议保持一致

示例：

feat: add SSH session management panel
fix: resolve title bar drag issue on Linux
docs: update README with deployment instructions
refactor: extract SFTP file list into reusable component

4. 多远程仓库管理

当你有自己的 fork 并需要同时跟踪上游仓库时：

# 添加多个远程仓库
git remote add origin https://github.com/YOUR_USER/ashell.git
git remote add upstream https://github.com/ORIGINAL_OWNER/ashell.git

# 查看远程仓库
git remote -v

# 从上游拉取更新
git fetch upstream
git checkout main
git merge upstream/main

# 推送到自己的仓库
git push origin main

5. 分支操作

5.1 创建与切换

# 创建新分支并切换
git checkout -b feature/new-feature

# 或者两步
git branch feature/new-feature
git checkout feature/new-feature

5.2 合并与变基

# 合并（保留历史）
git checkout main
git merge feature/new-feature

# 变基（线性历史）
git checkout feature/new-feature
git rebase main
git checkout main
git merge feature/new-feature

5.3 删除分支

git branch -d feature/new-feature  # 本地
git push origin --delete feature/new-feature  # 远程

6. 撤销与回退

6.1 撤销工作区修改

git restore <file>              # 丢弃文件的未暂存修改
git restore .                   # 丢弃所有未暂存修改

6.2 撤销暂存

git restore --staged <file>     # 取消暂存但保留修改

6.3 修改最近提交

git commit --amend              # 修改提交信息或添加遗漏文件

6.4 回退到历史版本

# 软回退（保留修改在工作区）
git reset --soft HEAD~1

# 硬回退（丢弃所有修改，慎用！）
git reset --hard HEAD~1

# 回退到指定提交
git reset --hard <commit-hash>

7. 查看历史

git log                         # 完整日志
git log --oneline               # 简洁日志
git log --oneline --graph       # 图形化分支
git log -p                      # 带diff的详细日志
git log --since="2 weeks ago"   # 时间过滤
git log --author="RabitLogic"   # 作者过滤
git log --grep="ssh"            # 提交信息搜索
git blame <file>                # 查看每行代码的最后修改者

8. Git 配置存储位置

Git 配置分为三个层级：

| 层级 | 配置文件路径 | 作用范围 | |------|-------------|---------| | --system | /etc/gitconfig | 系统所有用户 | | --global | ~/.gitconfig | 当前用户所有仓库 | | --local | .git/config | 当前仓库（默认） |

# 查看各层级配置
git config --global --list
git config --local --list

9. 常见问题

*** Please tell me who you are.

git config user.email "your@email.com"
git config user.name "Your Name"
git commit --amend --reset-author

# 修改远程 URL
git remote set-url origin https://github.com/new-owner/repo.git

# 或添加新的远程并推送
git remote add myfork https://github.com/YOUR_USER/repo.git
git push myfork main

# 发生冲突时
git status  # 查看冲突文件
# 手动编辑解决冲突后
git add <resolved-file>
git commit

# 回退到目标版本
git reset --hard <target-commit>
# 强制推送（⚠️ 会覆盖远程历史，慎用！）
git push --force origin main

# 更安全的做法：使用 revert 保留历史
git revert <bad-commit>
git push origin main

# 1. 确保本地代码是最新的
git fetch upstream
git merge upstream/main

# 2. 检查修改
git status
git diff

# 3. 暂存所有改动
git add -A

# 4. 提交
git commit -m "fix: enable window title bar dragging on Linux"

# 5. 推送到自己的远程仓库
git push origin main

/target
**/*.rs.bk
.env
*.swp
*.swo
*~
.DS_Store