# Git 使用说明

## 1. Windows 下的符号链接配置

本项目包含 Linux 符号链接文件（`AppAlgo/`、`SDK/` 目录下的 `.so` 软链接）。
Windows 下需要正确配置才能管理这些文件。

### 前提条件

- **开发者模式已开启**（设置 → 开发者选项 → 开发人员模式）
- **Git 安装时选择了 Enable symbolic links**

### 配置环境变量

在 PowerShell 中执行（设置一次即可，永久生效）：

```powershell
[System.Environment]::SetEnvironmentVariable('MSYS', 'winsymlinks:nativestrict', 'User')
```

设置后**重启终端**。验证：

```bash
echo $MSYS
# 输出: winsymlinks:nativestrict
```

### 确认 git 配置

```bash
git config core.symlinks
# 输出: true（如果为 false 需要重新 clone）
```

### 修复已有仓库的符号链接

如果 `git status` 显示大量 `T`（type change），说明符号链接未正确创建。
设置好环境变量后执行：

```bash
git status --short | grep "^ T" | awk '{print $2}' | xargs git checkout --
```

### 新 clone 仓库

环境变量设好后直接 clone 即可，符号链接会自动正确创建：

```bash
git clone <url>
```

> **注意：** 如果未配置 `MSYS=winsymlinks:nativestrict`，Git Bash 会将 symlink 创建为
> JUNCTION 或占位文件，导致 `git status` 出现大量 T 状态且 `git diff` 报错。

---

## 2. WSL / Linux 下的 Git 管理

Linux 原生支持符号链接，无需额外配置。适用于 WSL 和 ARM 开发板等环境。

### 安装 Git

```bash
sudo apt update && sudo apt install git
```

### 配置用户信息

```bash
git config --global user.name "你的用户名"
git config --global user.email "你的邮箱@example.com"
```

### 凭证存储（避免重复输入密码）

```bash
# 方式一：缓存（默认 15 分钟，可自定义）
git config --global credential.helper 'cache --timeout=3600'

# 方式二：永久存储到文件（明文，仅限个人开发机）
git config --global credential.helper store
```

### WSL 访问 Windows 仓库

WSL 中可以直接访问 Windows 磁盘上的仓库：

```bash
cd /mnt/c/project/QT/GrabBag
git status
```

> **注意：** 跨文件系统操作性能较低。如果频繁在 WSL 中操作，建议将仓库 clone 到
> WSL 本地文件系统（`~/projects/`），性能会快很多。

### WSL 与 Windows 双环境协作

| 操作 | 建议环境 |
|------|---------|
| 代码编辑、Qt 编译 | Windows |
| ARM 交叉编译、打包、发布 | WSL / Linux |
| Git 日常操作（add/commit/push） | 两边都可以 |
| 涉及 .so 符号链接的提交 | WSL（更可靠） |

---

## 2. 项目构建与发布脚本

所有脚本位于 `GrabBagPrj/` 目录下，在 Linux / WSL 环境中运行。

### 常用命令

```bash
# 发布（编译 + 打包 + 更新版本号）— 最常用
./project_release.sh GrabBag

# 单独打包
./project_pkg_desktop.sh GrabBag        # 桌面应用
./project_pkg_service.sh BeltTearing    # 服务

# 单独操作
./buildArmPrj.sh GrabBag               # 仅编译
./project_updateversion.sh GrabBag      # 仅更新版本号

# 查看所有可用项目
./project_release.sh --list
```

### 新增项目

编辑 `GrabBagPrj/project_registry.sh`，在数组中加一行：

```bash
# 桌面项目 — 标准格式一行搞定
"NewApp;newAlgoDir"

# 服务项目
"NewService;newAlgoDir"
```

详见 `project_registry.sh` 顶部注释。

---

## 3. Git 常用命令速查

### 状态查看

| 命令 | 说明 |
|------|------|
| `git status` | 查看工作区状态 |
| `git log --oneline` | 简洁提交历史 |
| `git log --graph --oneline` | 图形化提交历史 |
| `git diff` | 查看未暂存的修改 |
| `git diff --staged` | 查看已暂存的修改 |

### 文件与提交

| 命令 | 说明 |
|------|------|
| `git add <file>` | 添加文件到暂存区 |
| `git add .` | 添加所有修改 |
| `git commit -m "信息"` | 提交 |
| `git commit -am "信息"` | 添加并提交（仅已跟踪文件） |
| `git checkout -- <file>` | 撤销工作区修改 |
| `git reset HEAD <file>` | 取消暂存 |

### 分支

| 命令 | 说明 |
|------|------|
| `git branch` | 查看本地分支 |
| `git branch -a` | 查看所有分支 |
| `git checkout -b <name>` | 创建并切换分支 |
| `git merge <branch>` | 合并分支 |
| `git branch -d <name>` | 删除分支 |

### 远程同步

| 命令 | 说明 |
|------|------|
| `git fetch` | 获取远程更新 |
| `git pull` | 拉取并合并 |
| `git push` | 推送 |
| `git push -u origin <branch>` | 推送并设置上游 |

### 撤销与暂存

| 命令 | 说明 |
|------|------|
| `git reset --soft HEAD~1` | 撤销提交（保留暂存） |
| `git reset --mixed HEAD~1` | 撤销提交（保留工作区） |
| `git revert <commit>` | 创建反向提交 |
| `git stash` | 暂存工作区 |
| `git stash pop` | 恢复暂存 |

### 标签

| 命令 | 说明 |
|------|------|
| `git tag` | 查看标签 |
| `git tag -a <name> -m "说明"` | 创建标签 |
| `git push origin --tags` | 推送所有标签 |