docs: 添加Git操作指南与常见问题

2026-08-01 17:28:47 +08:00
parent 9bc23434ad
commit f7ff61fec2
1 changed files with 360 additions and 0 deletions
@@ -0,0 +1,360 @@
+# Git 操作指南与常见问题
+
+本指南面向本项目（spanish-diary）的开发人员，说明日常更新提交、Gitea 令牌、Windows 凭据管理以及常见 Git 问题的处理方法。
+
+## 1. 项目仓库信息
+
+```text
+主仓库：https://git.youzhilian.cn/guoqingshan/spanish-diary.git
+Wiki 仓库：https://git.youzhilian.cn/guoqingshan/spanish-diary.wiki.git
+主分支：main
+```
+
+项目目录：
+
+```text
+C:\Users\Administrator\Documents\Codex\2026-07-30\build-web-apps-plugin-build-web\spanish-diary
+```
+
+执行 Git 操作前，请先进入项目目录：
+
+```powershell
+cd C:\Users\Administrator\Documents\Codex\2026-07-30\build-web-apps-plugin-build-web\spanish-diary
+```
+
+## 2. 日常更新与提交
+
+### 2.1 查看状态
+
+```powershell
+git status
+```
+
+`M` 表示已修改，`??` 表示未跟踪的新文件。
+
+### 2.2 暂存文件
+
+提交全部修改：
+
+```powershell
+git add -A
+```
+
+只提交指定文件：
+
+```powershell
+git add app.js translate.js
+```
+
+### 2.3 提交
+
+```powershell
+git commit -m "feat: 增加新功能"
+```
+
+常用提交信息前缀：
+
+```text
+feat: 新功能
+fix: 修复问题
+docs: 文档更新
+style: 样式调整
+refactor: 代码重构
+test: 测试
+chore: 其他维护
+```
+
+### 2.4 推送到远程
+
+```powershell
+git push origin main
+```
+
+如果本地分支已经跟踪远程分支，可以直接：
+
+```powershell
+git push
+```
+
+### 2.5 拉取远程更新
+
+```powershell
+git pull origin main
+```
+
+### 2.6 查看提交历史
+
+```powershell
+git log --oneline
+```
+
+## 3. 撤销与修改提交
+
+### 3.1 撤销暂存
+
+```powershell
+git restore --staged 文件名
+```
+
+### 3.2 丢弃工作区修改
+
+```powershell
+git restore 文件名
+```
+
+> 注意：此操作不可恢复，请确认后再执行。
+
+### 3.3 修改上一次提交信息
+
+```powershell
+git commit --amend -m "新的提交信息"
+```
+
+### 3.4 撤销最近一次提交但保留修改
+
+```powershell
+git reset --soft HEAD~1
+```
+
+## 4. 配置提交者信息
+
+### 4.1 全局配置
+
+```powershell
+git config --global user.name "你的名字"
+git config --global user.email "你的邮箱"
+```
+
+### 4.2 当前仓库配置
+
+```powershell
+git config user.name "guoqingshan"
+git config user.email "704299375@qq.com"
+```
+
+### 4.3 查看当前配置
+
+```powershell
+git config --list
+```
+
+## 5. 创建 Gitea 访问令牌
+
+1. 登录 Gitea 网站。
+2. 进入右上角用户头像，打开 **用户设置**。
+3. 左侧选择 **应用**。
+4. 在“生成新的令牌”区域填写令牌名称，例如 `spanish-diary-push`。
+5. 根据需要选择权限，推送代码通常需要：
+
+   ```text
+   write:repository
+   ```
+
+6. 点击 **生成令牌**。
+7. **立即复制并保存令牌**，关闭页面后将无法再次查看。
+
+令牌格式示例：
+
+```text
+cfa2f2cb9a1a01283bae9586cd42fa0518e0a4dc
+```
+
+> 安全提醒：令牌等同于密码，不要提交到仓库、聊天记录或公开文档中。
+
+## 6. 将令牌存入 Windows 凭据管理器
+
+### 6.1 检查 Git 凭据管理器
+
+```powershell
+git config --global credential.helper
+```
+
+正常应显示：
+
+```text
+manager
+```
+
+### 6.2 写入令牌
+
+在 PowerShell 中执行：
+
+```powershell
+$cred = "protocol=https`nhost=git.youzhilian.cn`nusername=guoqingshan`npassword=你的令牌`n"
+$cred | git credential approve
+```
+
+执行后，Git Credential Manager 会把令牌加密保存到 Windows 凭据管理器。
+
+### 6.3 使用干净地址推送
+
+```powershell
+git remote set-url origin https://git.youzhilian.cn/guoqingshan/spanish-diary.git
+git push origin main
+```
+
+推送时会自动从凭据管理器读取令牌，不需要把令牌写进 URL。
+
+## 7. 查看和删除 Windows 凭据
+
+### 7.1 查看
+
+```powershell
+cmdkey /list | findstr git.youzhilian.cn
+```
+
+也可以查看所有凭据：
+
+```powershell
+cmdkey /list
+```
+
+### 7.2 删除
+
+```powershell
+cmdkey /delete:git:https://git.youzhilian.cn
+```
+
+删除后，下次推送会要求重新提供用户名和令牌。
+
+## 8. 常见问题与解决办法
+
+### 8.1 fatal: not a git repository
+
+原因：当前目录不是 Git 仓库。
+
+解决：
+
+```powershell
+cd C:\Users\Administrator\Documents\Codex\2026-07-30\build-web-apps-plugin-build-web\spanish-diary
+git status
+```
+
+### 8.2 Authentication failed
+
+原因：令牌失效、密码错误或凭据过期。
+
+解决：
+
+```powershell
+git credential approve
+```
+
+重新写入新令牌，或先在 Gitea 中撤销旧令牌并生成新令牌。
+
+### 8.3 fatal: remote origin already exists
+
+原因：远程地址已经存在。
+
+解决：不要重复添加，改用设置：
+
+```powershell
+git remote set-url origin https://git.youzhilian.cn/guoqingshan/spanish-diary.git
+```
+
+### 8.4 Everything up-to-date
+
+原因：本地没有新的提交。
+
+解决：先提交再推送：
+
+```powershell
+git add -A
+git commit -m "feat: 新提交"
+git push origin main
+```
+
+### 8.5 push rejected：非快速前进
+
+原因：远程分支有新提交，本地落后。
+
+解决：
+
+```powershell
+git pull origin main --rebase
+```
+
+如果出现冲突，解决冲突后继续：
+
+```powershell
+git add -A
+git rebase --continue
+git push origin main
+```
+
+### 8.6 LF will be replaced by CRLF
+
+原因：Windows 和 Linux 换行符不同。
+
+解决：可以接受该提示；也可以在仓库根目录添加 `.gitattributes`：
+
+```text
+* text=auto
+*.js text eol=lf
+*.html text eol=lf
+*.css text eol=lf
+```
+
+### 8.7 Author identity unknown
+
+原因：没有配置用户名和邮箱。
+
+解决：
+
+```powershell
+git config user.name "guoqingshan"
+git config user.email "704299375@qq.com"
+```
+
+### 8.8 合并冲突
+
+原因：两边修改了同一个文件的同一区域。
+
+解决：
+
+1. 查看冲突文件：
+
+   ```powershell
+   git status
+   ```
+
+2. 手动保留正确内容，删除冲突标记。
+3. 标记已解决：
+
+   ```powershell
+   git add -A
+   git commit -m "merge: 解决冲突"
+   ```
+
+### 8.9 提交到了 master，但远程是 main
+
+解决：
+
+```powershell
+git branch -M main
+git push -u origin main
+```
+
+### 8.10 想查看远程地址
+
+```powershell
+git remote -v
+```
+
+### 8.11 文件被其他程序占用
+
+Windows 下如果 Git 报文件被占用，先关闭正在编辑该文件的编辑器或开发工具，再重试。
+
+## 9. 推荐日常流程
+
+```powershell
+cd 项目目录
+git pull origin main
+git status
+# 修改代码
+git add -A
+git commit -m "feat: 描述本次修改"
+git push origin main
+```
+
+每次推送前先拉取，可以减少冲突。