Shixunzhou/handbook
6
0
派生 0
代码 工单 合并请求 版本发布 百科 动态

docs: 手册改为网页优先版（上传/下载置顶，命令行降为进阶）

浏览代码
这个提交包含在：
yami
2026-09-17 14:31:23 +08:00
父节点 d648f3b6a1
当前提交 bf73ed0923
共有 1 个文件被更改，包括 168 次插入 和 82 次删除
下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件

250
README.md
查看文件

@@ -1,134 +1,220 @@
# 团队 Git 使用手册（git.yami.ink 新手版）
# 团队手册：在 git.yami.ink 上传、下载、改代码（零基础版）
> 适用对象：第一次用 Git 的同学。**不用先去学 Git**，照着本文操作就行。
> 遇到任何报错：**整屏复制报错，发给 AI（Trae / Claude / ChatGPT），照它说的做**。
> 网址：**https://git.yami.ink** ｜ 账号由管理员统一创建（平台已关闭自助注册，看到「注册已禁用」是正常的）
> 适用对象：会写代码、但**完全没用过 Git** 的同学。
> 一句话：这份手册里九成的操作，**在网页上点几下就完成，电脑上不用装任何东西**。
---
## 〇、先记住三句话
1. 每天开工先 `git pull`
2. 改完代码 `git add .` → `git commit -m "说明"` → `git push`
3. 报错不可怕，复制给 AI 兜底
1. **要传文件**：进仓库（仓库 = 一个项目的文件夹，能存文件、看历史、多人一起改）→ 点绿色「上传文件」→ 把文件拖进去 → 底部写一句说明 → 提交。
2. **要拿文件**：进仓库 → 点绿色「代码」按钮 →「下载 ZIP」，解压就是完整项目。
3. **要改代码**：在 Trae（或 Cursor）里跟 AI 说一句「帮我把改动提交并推送到 git」，让它去敲命令。
下面是详细步骤，第一次照着做一遍，之后就是肌肉记忆。
**不用装任何东西也能用**：上面第 1、2 件事，还有「改一个小文件」，都不需要装 Git、不需要命令行、不需要背任何命令，有浏览器就行。
只有「全组一起开发同一个项目（要跑本地、要拉别人的改动）」才需要装 Git，见第 4 节；装和配也可以让 AI 代劳。
### 先看这张表：你想干的事 ↔ 该用哪种做法
| 你想干的事 | 用哪种做法 | 要装 Git 吗 | 看第几节 |
| -------------------------------- | ------------------------- | ----------- | -------- |
| 传几张图 / 一个文档 / 一个压缩包 | 网页「上传文件」，拖进去 | 不用 | 1 |
| 把整个项目下载到电脑 | 网页「代码」→「下载 ZIP」 | 不用 | 2 |
| 只下载某**一个**文件 | 文件页面的下载按钮 | 不用 | 2 |
| 改 README、改笔记、改配置 | 网页「编辑」→「提交变更」 | 不用 | 3-B |
| 改了代码，要让队友看到 | 让 AI 帮你提交推送 | 不用你操心 | 3-A |
| 全组一起做同一个项目 | clone / pull / push | 要 | 4 |
> 顶部那条蓝色横幅就是入口：横幅上的《3 分钟上手指南》指向本手册，「团队仓库」直接跳到全组的仓库列表。
---
## 一、账号设置（登录后先做这两件事）
## 一、【我要传文件】网页拖拽上传（不用 Git）
- 平台地址：**https://git.yami.ink** （账号由管理员统一创建，无需注册）
适合：传单个或少量文件（图片、文档、压缩包、一份 .py 文件）。全程在浏览器里完成。
用管理员给你的用户名和初始密码登录后，点**右上角头像 → 「设置」**：
1. 打开 **https://git.yami.ink**，用管理员给你的用户名和密码登录。
2. 点进要放文件的**仓库**（例如 `Shixunzhou/handbook`）。
3. 在仓库的文件列表页，点右上方绿色的 **「上传文件」** 按钮。
- 没看到的话：先点旁边的 **「添加文件」**，下拉菜单里就有「上传文件」（不同版本按钮摆放略有差异，功能一样）。
4. 进入上传页后，把文件从电脑文件夹**直接拖进中间的虚线框**；不想拖就点虚线框，在弹出的窗口里选文件。
- 可以一次拖多个文件。
- 单个文件别超过 **100MB**（服务器限制），太大的先压缩或分卷再传。
5. 往下拉到页面最底，在提交说明里写一句人话，例如：`添加迎新活动照片（10 张）`。
6. 点绿色的 **「提交变更」** 按钮。出现文件列表且能看到你刚传的文件，就是成功了。
### 1. 改密码
传完想确认：刷新仓库页，文件列表里有它，且右侧能看到「x 分钟前 · 你的名字」。
在左侧 **「账号」** 页最上方「修改密码」：填旧密码 → 设一个你记得住的新密码。
**几个常见疑问**
### 2. 改邮箱（自助，立即生效）
同一页往下找 **「管理邮箱地址」**：
1. 底部输入框填你的常用邮箱 → 点「添加」
2. 不需要收验证邮件，**加完立即生效**
3. 把初始化的旧邮箱删掉（点邮箱旁的删除按钮）
> 注意两点：
> - 这个邮箱要和你后面 `git config` 里填的邮箱**保持一致**（见第二节），这样你的提交在网页上才会显示你的头像和名字
> - 这页最底下有「删除账号」红色按钮，**别乱点**
### 3. 界面是英文？切中文
头像 → 设置 → **「外观」（Appearance）** → Language 选 **简体中文** → 保存。
### 4. 忘记密码怎么办
平台没配邮件服务，网页上「忘记密码」点不出结果，**直接找管理员重置**。
| 疑问 | 回答 |
| -------------------- | ---------------------------------------------------------------------------------------- |
| 传错文件了怎么办？ | 进那个文件页面，点右侧的删除按钮（垃圾桶图标），提交一次删除即可。历史记录还在，不用怕。 |
| 想传整个文件夹？ | 网页上传建议一次少量文件；整个项目文件夹请用第 3 节 A（让 AI 推）或第 4 节。 |
| 传上去别人能看到吗？ | 看仓库设置：公开仓库谁都能看，私有仓库只有被授权的人能看。不确定就问管理员。 |
| 传完还要不要点别的？ | 不用，不需要 push、不需要命令行，网页上这一步就是最终提交。 |
---
## 二、本地准备（每台电脑只做一次）
## 二、【我要下载】两种下载方式
### 1. 安装 Git
### A. 下载整个项目（最常用）
下载：https://git-scm.com/download/win —— 安装时一路「Next」到底即可。
1. 打开仓库首页。
2. 点绿色的 **「代码」** 按钮。
3. 在弹层里选 **「下载 ZIP」**。
4. 浏览器会下载一个 `.zip`，解压就是完整的项目文件夹（不需要 Git，也不能用来提交，纯查看/备份用）。
### 2. 告诉 Git 你是谁
### B. 只下载一个文件
打开 Trae / VSCode 的终端（或开始菜单里的「Git Bash」），粘贴运行（引号里换成自己的）：
1. 点开那个文件，进入文件内容页面。
2. 页面右上角有一个**向下的箭头图标**（鼠标悬停显示「下载文件」），点它就把这个文件原样存到电脑。
3. 想直接看纯文本内容（方便复制）：点旁边的 **「原始文件」**，打开后可以右键另存。
---
## 三、【我要改代码】两条路，先看走哪条
| 你的情况 | 走哪条 | 要装 Git 吗 |
| ------------------------------------ | ----------------------------- | ------------------------- |
| 改的是项目里的代码、要让全组拿到 | **A. 让 AI 帮你提交**（推荐） | 不用你操心，AI 会执行命令 |
| 只改一个文档 / 笔记 / 配置这类小文件 | **B. 网页上直接改** | 不用 |
### A. 推荐：让 AI 帮你提交（Trae / Cursor）
1. 在 Trae 里打开这个项目的文件夹（如果是第一次，先找 AI 要「clone 命令」，见第 4 节第 1 步）。
2. 正常让 AI 帮你改代码。
3. 改完，直接对 AI 说一句（照抄即可）：
> **先 pull 一下，然后把我这次的改动提交并推送到 git，提交说明写：修复登录按钮不响应**
为什么要先说「先 pull」：队友可能在你干活的时候推了新代码，先把最新的拿下来，才不会打架。
4. 如果弹出登录框：用户名填 git.yami.ink 的**用户名**（不是邮箱），密码填你的登录密码。Windows 会记住，以后不用再输。
5. 完成标准：刷新 git.yami.ink 的仓库页面，能看到你这次的提交记录，作者是你的名字。
> 已经被 AI 一路带到这一步的同学，可以顺手把这三句话存进备忘录，下次直接复制给 AI：
>
> 1. 先 pull 2) 提交并推送 3) 提交说明写「……」。
### B. 小文件直接改（README、笔记、配置）
1. 打开仓库 → 点开要改的文件（例如 `README.md`）。
2. 点右上角的**铅笔图标「编辑」**。
3. 直接改内容（支持 Markdown，也能即时预览）。
4. 拉到页面最底部，填一句改动说明，例如：`补充周三例会记录`。
5. 点 **「提交变更」**。完成，队友刷新就能看到。
> 适合改文本类小文件（`.md` / `.txt` / `.json` / `.py` 单文件的小改）。
> 要传图片、压缩包、二进制文件，走第 1 节；要改多个文件、要跑本地项目，走 A。
---
## 四、【进阶：手动 Git 四步】（全组一起开发时才需要）
每台电脑**只做一次**准备：
1. 装 Git：https://git-scm.com/download/win ，安装时一路「Next」。
2. 告诉 Git 你是谁（在 Trae 的终端里粘贴运行，引号里换成你自己的）：
```bash
git config --global user.name "你的名字（拼音或网名）"
git config --global user.email "你在第一节点设置的邮箱"
git config --global user.email "你在第 5 节设置的邮箱"
```
检验：运行 `git config --global --list`，能看到这两行就 OK。
---
## 三、第一次拿代码（clone）
1. 在网页打开要协作的仓库，点绿色 **「代码」** 按钮，复制 HTTPS 地址，形如：
`https://git.yami.ink/组织名/仓库名.git`
2. 在电脑上选一个放代码的文件夹，在该文件夹打开终端，执行：
3. 把项目拿下来（clone）：在网页仓库页点绿色「代码」，复制里面的 **HTTPS 地址**，形如 `https://git.yami.ink/组织名/仓库名.git`；然后在电脑上选一个放代码的文件夹，在该文件夹打开终端执行：
```bash
git clone 刚才复制的地址
```
3. 第一次会弹出登录框：输入 git.yami.ink 的**用户名和密码**，Windows 会记住，以后免输。
完成后文件夹里多出一个和仓库同名的目录，代码就在里面。
---
## 四、日常上传（每天就是这一套）
> 节奏口诀：**开工先 pull，改完 add + commit，收工 push**。
4. 日常四步（每天都一样，背下来就不会出错）：
```bash
cd 仓库文件夹 # 进入 clone 下来的代码目录
git pull # ① 拉取别人的最新改动（每天开工第一步！）
cd 项目文件夹 # 进入 clone 下来的那个目录
git pull # ① 开工第一步：把队友的最新改动拿下来
# ......正常写你的代码......
git add . # ② 把改动放入暂存区（. 表示全部文件）
git commit -m "一句话说明改了什么，例如：修复登录按钮不响应" # ③ 打包成一次提交
git push # ④ 上传到 git.yami.ink
git add . # ② 把改动挑出来（add = "这些都要提交"）
git commit -m "一句话说明改了什么，例如：修复登录按钮不响应" # ③ 存成一个带说明的快照
git push # ④ 传上去，队友就能看到
```
push 成功后，刷新网页仓库页面就能看到你的提交和名字。
口诀：**开工先 pull，改完 add + commit，收工 push。**
**为什么开工要先 pull？** 别人可能在你没干活的时候推了新代码，先 pull 拿到最新版，再改才不会打架。
> 术语速查：**提交（commit）**= 给这次改动拍一张带说明的快照；**pull**= 把服务器上别人的最新内容拿下来；**push**= 把自己电脑上的提交传上去；**分支（branch）**= 同一份代码的平行版本线，你们暂时只需要用默认的 `main` 这条主线，不用管分支。
---
## 五、不装 Git 也能干的活（网页端）
## 五、【账号设置】（登录后花两分钟做完）
- **看代码**：仓库页直接点文件浏览
- **只想下载看，不参与协作**：绿色「代码」按钮 → 「下载 ZIP」
- **看谁改了什么**：仓库页「提交」标签页 = 全部历史记录
- **改个小文件（文档类）**：进入文件 → 「编辑」→ 改完在底部填提交说明 → 「提交变更」
- **报 bug / 提需求**：仓库页「议题（Issues）」→ 「创建议题」，标题写清现象，正文贴截图和复现步骤
点**右上角头像 → 「设置」**，都在左侧「账号」这一页：
| 我要做的事 | 点哪里 | 注意 |
| ------------ | --------------------------------------------------------------- | ------------------------------------------------------------ |
| 改密码 | 设置 → 账号 → 最上方「修改密码」 | 填旧密码 + 新密码；改完记得同步更新 Windows 记住的密码 |
| 改邮箱 | 设置 → 账号 → 往下找「管理邮箱地址」→ 底部填新邮箱 → 点「添加」 | **不需要收验证邮件，加完立即生效**；加完把旧的删掉 |
| 界面切成中文 | 设置 → 「外观」→ Language 选「简体中文」→ 保存 | 平台已把中文设为默认，一般不用改 |
| 忘记密码 | 找管理员重置 | 平台没配邮件服务，网页上的「忘记密码」点不出结果，这是正常的 |
> 邮箱最好和第 4 节 `git config` 里填的一致，这样你的提交在网页上才会正确显示成你的名字。
---
## 六、常见报错对照表
## 六、【常见报错对照表】
| 报错关键词 | 意思 | 怎么办 |
|---|---|---|
| `Please tell me who you are` | 没做第二节的身份配置 | 回去做 `git config` 那两条命令 |
| `Authentication failed` | 用户名或密码错 | 确认输的是用户名（不是邮箱）；密码改过就用新密码 |
| `! [rejected] ... fetch first` | 服务器上有你本地没有的提交 | 先 `git pull`，然后重新 push |
| `CONFLICT (content)` | 你和别人改了同一个地方 | 别慌，把整屏报错发给 AI，按它说的做 |
| `not a git repository` | 当前文件夹不是代码仓库目录 | `cd` 到 clone 下来的那个文件夹里 |
| `nothing to commit` | 没有改动可提交 | 检查文件是否保存、是否在正确目录 |
看到报错别慌，先在表里找关键词；找不到就把整屏复制给 AI（第 7 节）。
### 网页上（不用 Git 的那部分）
| 你看到的 | 什么意思 | 怎么办 |
| ------------------------------- | ------------------------------ | -------------------------------------------------- |
| 打不开注册页 / 提示注册已禁用 | 平台是邀请制，账号由管理员建 | 直接找管理员要账号 |
| 登录提示用户名或密码错误 | 账号不对 | 用户名填**用户名**（不是邮箱）；改过密码就用新密码 |
| 上传时提示文件过大 / 转圈后失败 | 超过服务器 100MB 上限 | 先压缩，或分几次传 |
| 看不到某个仓库 / 打开是 404 | 没登录，或这个仓库没给你权限 | 先确认登录了；仍不行找管理员把你加进组织 |
| 点了「提交变更」没反应 | 多半是没填提交说明，或网络中断 | 填一句说明再提交；刷新页面重试 |
| 编辑页改完不知道点哪 | 按钮在页面最底部 | 拉到最底，点「提交变更」 |
### 命令行 / AI 帮你跑 git 时
| 报错关键词 | 什么意思（人话） | 怎么办 |
| -------------------------------------------------------- | ------------------------------------------ | --------------------------------------------- |
| `Please tell me who you are` | 电脑上的 Git 还不知道你是谁 | 做第 4 节的 `git config` 那两条命令 |
| `Authentication failed` / 一直弹登录框 | 用户名或密码不对 | 用户名填 git.yami.ink 的用户名；密码用新密码 |
| `! [rejected] ... fetch first` / `Updates were rejected` | 服务器上有你电脑里没有的内容（队友先推了） | 先 `git pull`，再 `git push` |
| `CONFLICT (content)` / 提示冲突 | 你和队友改了同一个文件的同一处 | 别硬来，整屏复制给 AI，让它帮你选保留哪一版 |
| `not a git repository` | 当前文件夹不是项目目录 | `cd` 到 clone 下来的那个文件夹再执行 |
| `nothing to commit` | 没有检测到改动 | 确认文件已保存、且改的是项目目录里的文件 |
| `fatal: unable to access ...` / 一直转圈超时 | 网络问题 | 换手机热点试试；或先用网页上传（第 1 节）应急 |
| `error: failed to push some refs` | 推不上去，多半是落后于服务器 | 先 pull，再 push；还不行复制给 AI |
---
## 七、三条纪律 + 万能兜底
## 七、【三条纪律 + 万能兜底】
1. **每天开工先 `git pull`**
2. **尽量各改各的文件**，避免多人同时改同一个文件
3. **push 前先 `git pull`**；push 被拒就先 pull 再试
4. 万能兜底：**整屏复制报错 + 说一句你刚才在干什么 → 发给 AI → 照做**。还搞不定，找管理员。
1. **开工先 pull**（第 4 节第 4 步），再动手改。
2. **尽量各改各的文件**；非改同一个文件不可时，先在群里喊一声。
3. **push 被拒就先 pull 再 push**；两边改了同一处，找 AI 合并，别手工硬删。
4. **万能兜底**：把**整屏报错**复制下来，加上一句「我刚才在做：……」发给 AI（Trae / Claude / ChatGPT），照着它说的做。还搞不定，找管理员。
### 给 AI 的一句话模板（复制粘贴即用）
```text
我在 git.yami.ink 的【项目名】里改了代码。请先 pull，然后把这次的改动提交并推送。
提交说明写：……
```
```text
我执行 git push（或：在网页上传文件）时报了下面的错。我刚才在做：……
请告诉我具体该点哪里 / 输什么命令，一步一步来。
【把整屏报错原样粘在这里】
```
---
> 本手册的网页版在 https://git.yami.ink/Shixunzhou/handbook （团队手册仓库的 README）。
> 页面顶部蓝色横幅、右上角「新手手册」入口，都能一键跳到这里。