Git 基本操作与 GitHub 仓库初始化笔记
2026/5/25
Project Learning GitGitHubProject LearningVersion Control
Git 基本操作与 GitHub 仓库初始化笔记
1. Git 是什么？
Git 是一个代码版本管理工具，可以帮我们记录项目的每一次修改。
简单理解：
Git = 项目的代码存档系统
它可以做到：
- 保存代码历史版本
- 查看代码改了什么
- 回退到之前的版本
- 管理分支
- 把本地项目上传到 GitHub
- 多人协作开发
2. 本地项目第一次使用 Git
假设项目路径是：
D:\workspace\code\project\edu_ai_project\正确仓库名称
进入项目目录：
cd D:\workspace\code\project\edu_ai_project\正确仓库名称
初始化 Git：
git init
成功后会看到类似：
Initialized empty Git repository in D:/workspace/code/project/edu_ai_project/正确仓库名称/.git/
这说明当前目录已经变成一个 Git 仓库。
Git 会在项目根目录创建一个隐藏文件夹：
.git/
这个 .git/ 文件夹用来保存 Git 的版本记录，不要手动删除。
3. 创建 .gitignore 文件
.gitignore 用来告诉 Git：哪些文件或文件夹不要提交。
Python 项目里，最重要的是：
.venv/ 不要提交
.env 不要提交
__pycache__/ 不要提交
数据库文件不要提交
日志文件不要提交
3.1 Windows PowerShell 创建 .gitignore
在项目根目录执行：
$content = @'
.venv/
__pycache__/
*.pyc
*.pyo
*.pyd
.pytest_cache/
.mypy_cache/
.ruff_cache/
.env
*.db
wit_edu_agent.db
uploads/
logs/
.vscode/
.idea/
.DS_Store
Thumbs.db
'@
$Utf8NoBom = New-Object System.Text.UTF8Encoding $false
[System.IO.File]::WriteAllText((Join-Path (Get-Location) ".gitignore"), $content, $Utf8NoBom)
然后查看内容：
Get-Content .gitignore
注意：
如果用 Windows PowerShell 5.1，下面这个命令可能会报错：
Set-Content .gitignore -Encoding utf8NoBOM
因为旧版 PowerShell 不支持 utf8NoBOM 这个参数。
4. 查看 Git 当前状态
git status
这个命令非常常用。
它会告诉你：
- 哪些文件还没有被 Git 管理
- 哪些文件被修改了
- 哪些文件已经加入暂存区
- 当前在哪个分支
5. 把文件加入暂存区
添加所有文件：
git add .
只添加某个文件：
git add requirements.txt
只添加某个目录：
git add app
解释：
git add . 表示把当前目录下所有没有被 .gitignore 忽略的改动加入暂存区
6. 第一次提交代码
git commit -m "初始化教育智能体项目结构"
-m 后面是提交说明。
提交说明建议写清楚这次做了什么，例如：
git commit -m "初始化项目结构"
git commit -m "添加 FastAPI 基础配置"
git commit -m "添加用户模型和数据库连接"
git commit -m "修复依赖安装问题"
7. Git 的三个区域
Git 里可以粗略理解成三个区域：
工作区 你正在修改代码的地方
暂存区 git add 之后进入的地方
版本库 git commit 之后真正保存的地方
流程是：
修改代码 → git add . → git commit -m "说明"
8. 日常开发最常用流程
每次写完一小块功能后：
git status
git add .
git commit -m "本次修改说明"
如果已经绑定远程 GitHub 仓库，还可以继续：
git push
完整日常流程：
git status
git add .
git commit -m "完成某某功能"
git push
9. 在 GitHub 上创建新仓库
9.1 打开 GitHub
浏览器打开：
https://github.com
登录自己的账号。
9.2 创建仓库
点击右上角：
+ 号 → New repository
9.3 GitHub 创建仓库时各个名字怎么填
假设本地项目叫：
正确仓库名称
那么 GitHub 页面可以这样填写：
Repository name
仓库名。
建议和本地项目文件夹保持一致：
正确仓库名称
命名建议：
全部小写
单词之间用 -
不要用中文
不要用空格
不要用特殊符号
推荐：
正确仓库名称
edu-ai-agent
stock-system
ironpillar-quant
fastapi-backend
不推荐：
我的教育智能体
wit edu agent
WIT_EDU_AGENT
project!!!
Description
仓库描述。
可以写一句简短说明，例如：
A FastAPI-based educational AI agent project.
或者中文也可以：
基于 FastAPI 的教育智能体项目
这个不是必填项。
Public / Private
选择仓库可见性。
如果是个人学习项目，可以选：
Public
如果暂时不想让别人看到，选：
Private
建议课程项目、实验项目、含 API Key 风险的项目先选：
Private
注意：
.env 文件不要上传，即使是 Private 仓库也不要上传密钥。
Add a README file
如果本地项目已经有文件，并且准备从本地推送，建议：
不要勾选 Add a README file
原因：
如果 GitHub 远程仓库先生成了 README，而本地也有自己的提交，第一次 push 时容易出现远程和本地历史不一致。
新手建议：
本地已有项目 → GitHub 创建空仓库 → 不勾选 README
Add .gitignore
如果本地已经手动创建 .gitignore，建议：
不要选择
保持 GitHub 仓库是空的。
Choose a license
学习项目可以先不选：
None
以后需要开源时再补。
9.4 推荐的 GitHub 新仓库填写方式
以 正确仓库名称 为例：
Repository name: 正确仓库名称
Description: 基于 FastAPI 的教育智能体项目
Visibility: Private 或 Public
Add a README file: 不勾选
Add .gitignore: 不选
Choose a license: None
然后点击：
Create repository
10. 本地仓库绑定 GitHub 远程地址
GitHub 仓库创建完成后，会给你一个远程地址。
HTTPS 格式一般是：
https://github.com/你的用户名/仓库名.git
例如：
https://github.com/你的用户名/正确仓库名称.git
在本地项目终端执行：
git remote add origin https://github.com/你的用户名/正确仓库名称.git
解释：
origin 是远程仓库的默认名字
https://github.com/你的用户名/正确仓库名称.git 是 GitHub 仓库地址
查看是否绑定成功：
git remote -v
正常会看到：
origin https://github.com/你的用户名/正确仓库名称.git (fetch)
origin https://github.com/你的用户名/正确仓库名称.git (push)
11. 第一次推送到 GitHub
先把当前分支改名为 main：
git branch -M main
然后第一次推送：
git push -u origin main
解释：
git push 把本地提交推送到远程仓库
-u 建立本地 main 和远程 main 的追踪关系
origin 远程仓库名字
main 分支名
第一次用了 -u 之后，以后再推送只需要：
git push
12. 新项目从零到上传 GitHub 的完整流程
假设当前已经在项目根目录：
cd D:\workspace\code\project\edu_ai_project\正确仓库名称
完整流程：
git init
# 创建 .gitignore
$content = @'
.venv/
__pycache__/
*.pyc
*.pyo
*.pyd
.pytest_cache/
.mypy_cache/
.ruff_cache/
.env
*.db
wit_edu_agent.db
uploads/
logs/
.vscode/
.idea/
.DS_Store
Thumbs.db
'@
$Utf8NoBom = New-Object System.Text.UTF8Encoding $false
[System.IO.File]::WriteAllText((Join-Path (Get-Location) ".gitignore"), $content, $Utf8NoBom)
git status
git add .
git commit -m "初始化教育智能体项目结构"
git branch -M main
git remote add origin https://github.com/你的用户名/正确仓库名称.git
git push -u origin main
注意：
上面的远程地址要换成你自己的 GitHub 仓库地址。
13. 如果远程地址填错了怎么办？
先查看当前远程地址：
git remote -v
如果地址错了，修改：
git remote set-url origin https://github.com/你的用户名/正确仓库名.git
例如：
git remote set-url origin https://github.com/你的用户名/正确仓库名称.git
再次查看：
git remote -v
14. 如果重复添加 origin 报错怎么办？
如果执行：
git remote add origin 地址
报错类似：
remote origin already exists
说明已经有一个叫 origin 的远程仓库了。
解决方法一：修改已有 origin：
git remote set-url origin 新地址
解决方法二：删除后重新添加：
git remote remove origin
git remote add origin 新地址
推荐使用方法一。
15. 如果 push 时连不上 GitHub
如果执行：
git push
报错类似：
Failed to connect to github.com port 443
Couldn't connect to server
这不是代码问题，也不是 venv 问题，而是网络连接 GitHub 失败。
常见原因：
浏览器能走代理，但 Git 命令行没走代理
网络无法直连 GitHub
Git 配置了错误代理
15.1 查看远程地址
git remote -v
15.2 测试能否访问 GitHub
PowerShell / Git Bash / macOS 终端：
curl -I https://github.com
15.3 查看 Git 是否配置代理
git config --global --get http.proxy
git config --global --get https.proxy
15.4 如果你开了代理，例如 Clash 端口是 7890
git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890
然后重新：
git push
15.5 如果你没开代理，但 Git 配过代理
取消代理：
git config --global --unset http.proxy
git config --global --unset https.proxy
然后重新：
git push
16. HTTPS 和 SSH 两种远程地址
GitHub 远程地址常见两种。
16.1 HTTPS 地址
格式：
https://github.com/用户名/仓库名.git
例如：
https://github.com/你的用户名/正确仓库名称.git
优点：
简单直观
适合新手
缺点：
可能需要 GitHub Token
网络代理问题比较常见
16.2 SSH 地址
格式：
git@github.com:用户名/仓库名.git
例如：
git@github.com:你的用户名/正确仓库名称.git
优点：
配置好 SSH Key 后推送方便
不用每次处理 HTTPS 登录
缺点：
第一次配置 SSH Key 稍微麻烦
修改为 SSH：
git remote set-url origin git@github.com:你的用户名/正确仓库名称.git
测试 SSH：
ssh -T git@github.com
推送：
git push
17. 查看提交历史
完整查看：
git log
简洁查看：
git log --oneline
输出类似：
a1b2c3d 初始化教育智能体项目结构
18. 查看代码改动
查看工作区改了什么：
git diff
查看暂存区改了什么：
git diff --cached
19. 分支基本操作
查看分支：
git branch
创建分支：
git branch dev
切换分支：
git switch dev
创建并切换分支：
git switch -c dev
切回 main：
git switch main
合并 dev 到 main：
git switch main
git merge dev
20. 克隆已有 GitHub 项目
如果远程仓库已经存在，本地还没有项目，可以用：
git clone https://github.com/用户名/仓库名.git
例如：
git clone https://github.com/你的用户名/正确仓库名称.git
克隆后进入目录：
cd 正确仓库名称
21. 拉取远程最新代码
git pull
常见场景：
别人在 GitHub 上更新了代码
你在另一台电脑提交了代码
你想把远程最新内容同步到本地
22. Windows PowerShell 和 Linux 命令区别
在网上经常看到：
mkdir -p app/core app/db app/models
这是 Linux / macOS / Git Bash 写法。
在 Windows PowerShell 里应该写：
New-Item -ItemType Directory -Force -Path app/core, app/db, app/models
例如创建项目目录：
New-Item -ItemType Directory -Force -Path app/core, app/db, app/models, app/schemas, app/services, app/agents, app/tools, app/utils, app/prompts/zh, tests
查看目录树：
tree app /F
23. Python 项目里 Git 提交注意事项
不要提交：
.venv/
.env
__pycache__/
*.pyc
*.db
logs/
uploads/
应该提交：
app/
tests/
requirements.txt
.gitignore
README.md
pyproject.toml
特别重要：
.venv 不提交
requirements.txt 要提交
.env 不提交
.env.example 可以提交
24. requirements.txt 和 Git 的关系
requirements.txt 要提交到 Git。
生成依赖文件：
python -m pip freeze > requirements.txt
别人拿到项目后安装依赖：
python -m pip install -r requirements.txt
25. 推荐的新项目 Git 初始化模板
25.1 本地已有项目，准备上传 GitHub
cd 项目路径
git init
# 写 .gitignore
# 确保 .venv、.env、缓存、数据库、日志都被忽略
git status
git add .
git commit -m "初始化项目"
git branch -M main
git remote add origin https://github.com/你的用户名/仓库名.git
git push -u origin main
25.2 已经有远程仓库，准备下载到本地
cd 你想放项目的目录
git clone https://github.com/你的用户名/仓库名.git
cd 仓库名
26. 教育智能体项目参考流程
项目名：
正确仓库名称
本地路径：
D:\workspace\code\project\edu_ai_project\正确仓库名称
GitHub 仓库名：
正确仓库名称
GitHub 描述：
基于 FastAPI 的教育智能体项目
本地命令：
cd D:\workspace\code\project\edu_ai_project\正确仓库名称
git init
git status
git add .
git commit -m "初始化教育智能体项目结构"
git branch -M main
git remote add origin https://github.com/你的用户名/正确仓库名称.git
git push -u origin main
之后每次开发：
git status
git add .
git commit -m "说明这次修改了什么"
git push
27. 常见错误速查
27.1 git init 后看到 Initialized empty Git repository
说明初始化成功。
27.2 git remote add origin 报 remote origin already exists
说明已经绑定过远程仓库。
解决：
git remote set-url origin 新仓库地址
27.3 git push 失败，提示 Failed to connect to github.com port 443
说明网络连不上 GitHub。
可能要配置代理：
git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890
或者取消错误代理：
git config --global --unset http.proxy
git config --global --unset https.proxy
27.4 .venv 出现在 git status 里
说明 .gitignore 没生效，或者 .venv 已经被加入暂存区。
先确认 .gitignore 有：
.venv/
如果已经被 add 过，执行：
git rm -r --cached .venv
然后：
git add .
git status
28. 最终记忆版
最常用的 Git 命令只需要先记住这几个：
git init
git status
git add .
git commit -m "提交说明"
git branch -M main
git remote add origin GitHub仓库地址
git push -u origin main
git push
git pull
git log --oneline
日常开发三连：
git add .
git commit -m "说明"
git push
新项目上传 GitHub 五连：
git init
git add .
git commit -m "初始化项目"
git remote add origin https://github.com/用户名/仓库名.git
git push -u origin main