当前位置：首页 > news >正文

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

news 2025/8/1 21:23:38

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

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

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

1.1 前提条件

本地项目结构完整，已准备好；

本地已安装 Git，配置了用户名邮箱：

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

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

1.2 操作步骤

A. GitHub 网站端

登录 GitHub；
点击右上角 + → New repository；
填写仓库信息；
可选择勾选 “Add a README file”；
点击【Create repository】；
复制 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 仓库

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

B. 连接 GitHub 仓库

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

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

打开终端（Ctrl+` ）

执行：

git pull origin main --allow-unrelated-histories

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

在项目根目录新建 .gitignore 文件
添加如下内容：（示例）
```
.metadata/
.vscode/
__pycache__/
```

E. 提交代码

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

F. 推送至远程仓库

点击...三点菜单 → Push
若首次推送，自动提示选择远程和分支（选 origin/main）
也可在终端执行：
```
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