GitHub 项目推送与拉取等操作使用随记

本小记适用于个人项目或组织项目，涵盖 GitHub 推送、拉取、分支管理、.gitignore 设置等常见需求。

---

1. 将已有本地工程推送至 GitHub 新仓库

1.1 前提条件

• 本地项目结构完整，已准备好；
• 本地已安装 Git，配置了用户名邮箱：

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

• 已在 GitHub 创建新仓库（可勾选 README）；

---

1.2 操作步骤

A. GitHub 网站端

1. 登录 GitHub；
2. 点击右上角 + → New repository；
3. 填写仓库信息；
4. 可选择勾选 “Add a README file”；
5. 点击【Create repository】；
6. 复制 HTTPS 地址（如：https://github.com/YourName/RepoName.git）；

B. 本地终端操作

# 在本地的工程目录下打开终端
cd /你的本地工程目录 
git init
# 若有.gitignore，可在其中添加工程中可忽略的文件
echo ".metadata/" >> .gitignore   # 忽略 .metadata
git remote add origin https://github.com/YourName/RepoName.git
git pull origin main --allow-unrelated-histories  # 若远程含 README
git add .
git commit -m "init: 初始化本地项目"
git push -u origin main

---

2. 远程仓库含 README，本地合并推送处理

2.1 前提条件

• GitHub 仓库已初始化 README；
• 本地项目也有初始代码。

2.2 操作步骤

git pull origin main --allow-unrelated-histories
# 解决冲突后
git add .
git commit -m "merge: 合并远程 README 与本地代码"
git push origin main

---

3. 修改本地分支名 master ➜ main 并同步远程

3.1 前提条件

• 本地分支仍是默认 master；
• GitHub 新仓库使用 main 分支。

3.2 操作步骤

git branch -m master main             # 重命名分支
git push -u origin main               # 推送新分支
git push origin --delete master      # 删除旧远程分支（可选）
# GitHub 设置：Settings → Branches → 修改默认分支为 main

---

4. 添加 .gitignore 忽略无关目录或文件

4.1 前提条件

• 项目含 .metadata/、.vscode/ 等非必要文件；

4.2 操作步骤

# 使用echo命令可将非必要文件写入.gitignore，也可直接打开文件进行写入
echo ".metadata/" >> .gitignore
echo ".vscode/" >> .gitignore
echo "__pycache__/" >> .gitignore
# 若之前已经添加这些文件，可使用下面命令删除
git rm -r --cached .metadata
git rm -r --cached .vscode
# 添加最新的.gitignore
git add .gitignore
git commit -m "chore: 更新 .gitignore"
git push

---

5. 推送失败：权限拒绝（组织仓库）

5.1 前提条件

• 仓库归属某个组织；
• 你不是组织成员或无写入权限；
• 报错信息示例：

  ERROR: Write access to repository not granted.
  

5.2 操作步骤

git remote -v                    # 检查当前远程地址
git remote set-url origin https://github.com/OrgName/RepoName.git# 若仍失败：
## 联系组织管理员添加你为协作者或团队成员
## 或 Fork 项目到你账号下再开发

---

6. 项目结构建议与 .gitignore 示例

6.1 推荐目录结构

# YourProject是github仓库名，即推送的最好是本地工程目录下的内容（而非用工程目录名包裹的内容），这样打开github仓库时映入眼帘的就是内部的重要文件夹，便于阅读YourProject/
├── README.md
├── .gitignore
├── requirements.txt
├── /src
├── /scripts
├── /config
├── /docs
└── ...

6.2 .gitignore 内容示例

.metadata/
.vscode/
__pycache__/
*.log
.DS_Store

---

7. 在 VS Code 中执行推送流程

7.1 前提条件

• 已在本地安装 Git；
• VS Code 安装了官方扩展：GitHub Pull Requests and Issues；
• 项目文件夹已通过 VS Code 打开；

7.2 操作步骤

A. 初始化 Git 仓库

1. 在 VS Code 左侧点击 Source Control（源代码管理图标）
2. 如果尚未初始化，会提示 “Initialize Repository” → 点击
3. 选择当前打开的文件夹作为 Git 根目录

B. 连接 GitHub 仓库

1. 打开命令面板（Ctrl+Shift+P 或 F1）
2. 输入并选择：Git: Add Remote
3. 输入远程名称（一般为 origin）
4. 粘贴 GitHub 仓库地址（如 https://github.com/YourName/Repo.git）

C. 拉取远程 README（若远程已存在）

1. 打开终端（Ctrl+` ）

2. 执行：

   git pull origin main --allow-unrelated-histories
   

D. 添加 .gitignore（忽略无关文件）

1. 在项目根目录新建 .gitignore 文件

2. 添加如下内容：（示例）

   .metadata/
   .vscode/
   __pycache__/
   

E. 提交代码

1. 左侧 Source Control 看到所有变更
2. 输入提交信息，如 init: 初始化项目
3. 点击 √ 图标（提交）

F. 推送至远程仓库

1. 点击...三点菜单 → Push

2. 若首次推送，自动提示选择远程和分支（选 origin/main）

3. 也可在终端执行：

   git push -u origin main
   

---

8. 附录：常用命令

# 初始化本地仓库
git init# 添加远程仓库
git remote add origin <仓库地址># 添加所有改动文件
git add .# 提交说明
git commit -m "备注信息"# 推送到远程分支
git push -u origin main# 拉取并允许无共同历史
git pull origin main --allow-unrelated-histories# 重命名分支
git branch -m master main

---

9. 总结

本笔记整理了将本地项目推送到 GitHub 的完整流程，主要包括：

1. 本地 Git 初始化与远程仓库建立连接；
2. 处理已有 README 的远程仓库合并问题；
3. 设置 .gitignore 忽略无关文件；
4. 重命名本地分支为 main 并同步推送；
5. 针对组织仓库的权限问题做出说明；
6. 补充了 VS Code 下的操作方法，适合图形化管理项目。

---

笔者能力有限，以上内容难免存在不足和纰漏，仅供参考，各位阅读时请带着批判性思维学习，遇到问题多查查，谢谢。