From bf73ed092379aa3dec2da32513d145900469e7f0 Mon Sep 17 00:00:00 2001 From: yami Date: Thu, 17 Sep 2026 14:31:23 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=89=8B=E5=86=8C=E6=94=B9=E4=B8=BA?= =?UTF-8?q?=E7=BD=91=E9=A1=B5=E4=BC=98=E5=85=88=E7=89=88=EF=BC=88=E4=B8=8A?= =?UTF-8?q?=E4=BC=A0/=E4=B8=8B=E8=BD=BD=E7=BD=AE=E9=A1=B6=EF=BC=8C?= =?UTF-8?q?=E5=91=BD=E4=BB=A4=E8=A1=8C=E9=99=8D=E4=B8=BA=E8=BF=9B=E9=98=B6?= =?UTF-8?q?=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 250 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 168 insertions(+), 82 deletions(-) diff --git a/README.md b/README.md index b930c8c..f83110a 100644 --- a/README.md +++ b/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）。 +> 页面顶部蓝色横幅、右上角「新手手册」入口，都能一键跳到这里。