# Git 工作流程说明

## 🎯 仓库信息

- **Gitea 地址**: https://gitea.nosuchip.de
- **仓库 URL**: https://gitea.nosuchip.de/zack/ai-shell
- **用户名**: zack
- **仓库名**: ai-shell

## 📋 当前状态

✅ **已完成**:
- 初始化 Git 仓库
- 配置 .gitignore 文件
- 创建远程仓库 (通过 API)
- 推送初始代码到 main 分支
- 设置上游分支跟踪

## 🔧 基本 Git 操作

### 1. 查看状态
```bash
git status                    # 查看工作区状态
git log --oneline            # 查看提交历史
git remote -v                # 查看远程仓库
```

### 2. 日常开发流程
```bash
# 1. 修改代码
vim ai_shell/main.py

# 2. 查看更改
git diff

# 3. 添加更改
git add .                    # 添加所有更改
git add ai_shell/main.py     # 添加特定文件

# 4. 提交更改
git commit -m "feat: add new feature"

# 5. 推送到远程
git push                     # 推送到当前分支
git push origin main         # 明确推送到 main 分支
```

### 3. 版本发布流程
```bash
# 1. 更新版本号
python scripts/bump_version.py patch    # 0.1.0 -> 0.1.1
python scripts/bump_version.py minor    # 0.1.0 -> 0.2.0
python scripts/bump_version.py major    # 0.1.0 -> 1.0.0

# 2. 提交版本更新
git add ai_shell/__init__.py pyproject.toml
git commit -m "bump: version to v0.1.1"

# 3. 创建标签
git tag -a v0.1.1 -m "Release version 0.1.1"

# 4. 推送代码和标签
git push
git push --tags
```

## 🌿 分支管理

### 创建功能分支
```bash
# 创建并切换到新分支
git checkout -b feature/new-command-parser

# 开发完成后合并
git checkout main
git merge feature/new-command-parser

# 删除功能分支
git branch -d feature/new-command-parser
```

### 创建发布分支
```bash
# 创建发布分支
git checkout -b release/v0.2.0

# 在发布分支上进行最后的调整
# 完成后合并到 main
git checkout main
git merge release/v0.2.0
git tag -a v0.2.0 -m "Release version 0.2.0"
```

## 🔄 同步和更新

### 从远程拉取更新
```bash
git pull                     # 拉取并合并
git fetch                    # 仅拉取，不合并
git pull --rebase           # 使用 rebase 方式拉取
```

### 解决冲突
```bash
# 如果出现冲突
git status                   # 查看冲突文件
# 手动编辑冲突文件
git add .                    # 标记冲突已解决
git commit                   # 完成合并
```

## 📝 提交信息规范

使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范：

```bash
# 功能添加
git commit -m "feat: add configuration validation"

# Bug 修复
git commit -m "fix: resolve cache directory issue"

# 文档更新
git commit -m "docs: update installation guide"

# 代码重构
git commit -m "refactor: improve config loading logic"

# 性能优化
git commit -m "perf: optimize command generation speed"

# 测试相关
git commit -m "test: add unit tests for config module"

# 构建相关
git commit -m "build: update dependencies"

# CI/CD 相关
git commit -m "ci: add automated testing workflow"
```

## 🛡️ 安全配置

### 1. 凭据管理
```bash
# 查看当前远程 URL（包含凭据）
git remote get-url origin

# 如果需要更改凭据
git remote set-url origin https://new_username:new_password@gitea.nosuchip.de/zack/ai-shell.git
```

### 2. 敏感文件保护
- ✅ `.env` 文件已在 `.gitignore` 中排除
- ✅ 构建产物 (`dist/`, `build/`) 已排除
- ✅ 缓存文件已排除

### 3. 检查敏感信息
```bash
# 检查是否意外提交了敏感文件
git log --name-only | grep -E "\.(env|key|pem)$"

# 如果意外提交了敏感文件，需要从历史中移除
git filter-branch --force --index-filter \
  'git rm --cached --ignore-unmatch .env' \
  --prune-empty --tag-name-filter cat -- --all
```

## 🚀 自动化工作流

### 1. 快速升级和推送
创建脚本 `scripts/release.sh`:
```bash
#!/bin/bash
# 快速发布脚本

VERSION_TYPE=${1:-patch}

echo "🔄 升级版本 ($VERSION_TYPE)..."
python scripts/bump_version.py $VERSION_TYPE

echo "📦 重新构建..."
uv build

echo "🔧 重新安装..."
uv tool install . --force

echo "📝 提交更改..."
git add .
git commit -m "bump: version to $(grep '__version__' ai_shell/__init__.py | cut -d'"' -f2)"

echo "🚀 推送到远程..."
git push

echo "✅ 发布完成！"
```

### 2. 使用方法
```bash
chmod +x scripts/release.sh

# 发布补丁版本
./scripts/release.sh patch

# 发布次版本
./scripts/release.sh minor

# 发布主版本
./scripts/release.sh major
```

## 🔍 常用命令速查

```bash
# 状态查看
git status                   # 工作区状态
git log --oneline -10        # 最近10次提交
git diff                     # 查看未暂存的更改
git diff --cached            # 查看已暂存的更改

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

# 远程操作
git remote -v                # 查看远程仓库
git fetch --all              # 拉取所有远程分支
git push --all               # 推送所有分支

# 标签操作
git tag                      # 查看所有标签
git tag -l "v*"              # 查看版本标签
git push --tags              # 推送所有标签

# 撤销操作
git checkout -- file.txt    # 撤销文件更改
git reset HEAD file.txt     # 取消暂存
git reset --hard HEAD~1     # 撤销最后一次提交
```

---

🎉 **仓库地址**: https://gitea.nosuchip.de/zack/ai-shell

现在您可以在浏览器中访问仓库，查看代码和文档！