新手指南：从 GitHub 拉取项目（以VScode为例）¶

适用人群：第一次使用 Git / GitHub / VS Code 的同学
本页面由 ThirteenAsh 编写，欢迎指正与补充！
目标：能完成 安装 Git → 配置 Git → 从 GitHub 拉取项目 → 在 VS Code 开发 → 提交并推送

目录¶

1. 你需要的东西
1. 安装 Git（Windows）
1. 配置 Git（用户名与邮箱）
1. 准备 GitHub 账号与登录方式（HTTPS / SSH）
1. 从 GitHub 拉取项目（Clone）
1. 用 VS Code 打开项目
1. 开发后提交与推送（Commit / Push）
1. 更新到最新代码（Pull）
1. 忽略输出目录（output/log 等）
1. 常见问题（FAQ）

1. 你需要的东西¶

一个 GitHub 账号
已安装 VS Code
网络可以访问 GitHub（如公司/学校网络有限制，可能需要代理或镜像）
注册好的GitHub账户

2. 安装 Git（Windows）¶

打开 Git 官方下载页：
Git - Install for Windows

2. 下载并安装 Git（一般默认选项即可） 3. 安装完成后验证： - 打开 PowerShell 或 CMD，输入：

git --version

- 如果能看到版本号，例如 git version 2.xx.x，说明安装成功。

VS Code 通常会自动识别 Git。如果没有识别到，重启 VS Code 或电脑。

3. 配置 Git（用户名与邮箱）¶

这一步是为了让 Git 知道「提交代码的人是谁」。

打开终端（PowerShell / CMD / VS Code Terminal）执行：

git config --global user.name "你的名字"
git config --global user.email "你的邮箱"

检查是否配置成功：

git config --global --list

4. 准备 GitHub 登录方式（HTTPS / SSH）¶

方式 A：HTTPS（新手推荐）¶

Clone 地址形如：https://github.com/xxx/yyy.git (算法项目ThirteenAsh/eeg_modular: EEG+AI+VR算法仓库)
第一次推送时可能会要求登录 GitHub（通常是浏览器授权）

注意：GitHub 现在一般不再支持“账号密码”直接推送，需要用 浏览器授权 或 Personal Access Token (PAT)。VS Code 通常会引导你完成登录。

5. 从 GitHub 拉取项目（Clone）¶

方法 1：用 VS Code 一键 Clone（推荐）¶

打开 VS Code
按 Ctrl + Shift + P 打开命令面板
输入并选择：Git: Clone
粘贴你的 GitHub 仓库地址
选择本地保存路径
Clone 完成后，VS Code 会问你是否打开该项目 → 选择 Open

方法 2：用命令行 Clone¶

找到仓库地址（GitHub 页面上点绿色 Code 按钮复制）
在终端执行：

git clone 仓库地址

cd 项目文件夹名

6. 用 VS Code 打开项目¶

如果你是通过 VS Code Clone 的，通常会自动打开
如果是命令行 Clone 的：
打开 VS Code
File -> Open Folder... 选择项目目录

建议安装/启用这些常用扩展：

GitHub Pull Requests and Issues（可选）
Python / C++ / Java 等语言支持（按项目需要）

7. 开发后提交与推送（Commit / Push）¶

Git 的基本流程通常是：

改代码 → 暂存（Stage）→ 提交（Commit）→ 推送（Push）

7.1 查看改动¶

VS Code 左侧点 源代码管理（小分叉图标）
能看到哪些文件被修改（M）、新增（U）、删除（D）

7.2 暂存（Stage）¶

两种方式：

VS Code：在改动文件旁点 +（Stage Changes）
命令行：

git add .

7.3 提交（Commit）¶

VS Code：在消息框写提交说明 → 点 Commit
命令行：

git commit -m "你的提交说明"

提交说明建议写清楚做了什么，例如：

fix: 修复数据加载路径
feat: 新增训练脚本
chore: 更新依赖与说明文档

7.4 推送到远程（Push）¶

VS Code：点 Push（或者同步 Sync）
命令行：

git push

第一次 push 可能需要登录 GitHub（VS Code 会弹窗引导）。

7.5使用源代码管理提交¶

在源代码管理页面可以提交已做的更改

在资源管理器页面可以看到通过不同颜色标记的内容

🔵 蓝色
已修改（Modified）
文件被修改过
但还没有加入暂存区（git add）
🟢 绿色
新文件（Untracked / Added）
新建的文件
还没被 Git 跟踪（未 git add）
或已经 git add，但还没提交（视具体版本和主题）
🟡 / 🟠 黄色 / 橙色
有警告 / 合并冲突 / 部分修改
可能存在 合并冲突
或文件同时存在暂存和未暂存的修改
通常伴随：
文件中出现 <<<<<< HEAD 之类的冲突标记
🔴 红色
删除（Deleted）或严重冲突
文件被删除
或存在无法自动解决的冲突
⚪ 灰色
被忽略（Ignored）
在 .gitignore 中被忽略的文件
Git 不会跟踪它们

8. 更新到最新代码（Pull）¶

当队友更新了仓库，你本地需要同步：

VS Code：点击底部状态栏的同步按钮（或 Source Control 的 Pull）
命令行：

git pull

9. 忽略输出目录（output/log 等）¶

很多项目会产生 output/、logs/ 之类的文件，不应该提交到仓库，否则会一直出现在 VS Code 源码管理里。

9.1 新文件/未追踪文件：直接写 `.gitignore`¶

在项目根目录创建/编辑 .gitignore，加入：

# 训练输出/日志
output/
outputs/
log/
logs/
runs/
results/
checkpoints/
wandb/

# Python 常见缓存
__pycache__/
*.pyc

保存后，新的输出文件不会再被识别为改动。

9.2 如果 output/log 之前已经被提交过：需要取消追踪¶

.gitignore 对“已被追踪”的文件不生效，需要执行：

git rm -r --cached output logs
git add .gitignore
git commit -m "chore: ignore output and logs"
git push

这样仓库里不再追踪它们，本地文件仍然保留。

9.3 只保留空目录结构（可选）¶

Git 不会提交空目录。若希望仓库里保留目录但不提交内容：

.gitignore：

output/*
!output/.gitkeep
logs/*
!logs/.gitkeep

创建占位文件：

touch output/.gitkeep logs/.gitkeep
git add output/.gitkeep logs/.gitkeep
git commit -m "chore: keep output/log dirs but ignore contents"
git push

10. 常见问题¶

Q1：VS Code 看不到 Git（源代码管理是空的/提示找不到 Git）¶

确认 git --version 有输出
重启 VS Code
仍不行：在 VS Code 设置里搜索 git path，确认 Git 路径正确

Q2：推送时提示权限不足 / Authentication failed¶

HTTPS 方式：通常需要通过浏览器登录授权 GitHub
确认你对该仓库有写权限（是否是协作者/成员）
如果是组织仓库，可能需要管理员授予权限

Q3：我不小心把大文件（模型权重/数据）提交了怎么办？¶

立刻停止继续提交
与项目负责人沟通，通常需要：
删除历史记录中的大文件（可能要用 git filter-repo / BFG）
或转用 Git LFS（存大文件）

这是团队层面操作，建议不要自己硬改历史，先沟通。

Q4：Pull 时冲突（conflict）怎么办？¶

冲突表示同一段代码你和别人都改过
VS Code 会标注冲突区块，手动选择保留哪部分
解决后：

git add .
git commit -m "fix: resolve merge conflict"