GitHub使用小记——本地推送、外部拉取和分支重命名

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 下的操作方法，适合图形化管理项目。

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