本地项目关联远程Git仓库完整步骤

lovecspplon

423人浏览 · 2026-04-10 14:46:25

lovecspplon · 2026-04-10 14:46:25 发布

本文章包含“从零创建本地Git仓库→关联远程仓库→将本地master分支改为main分支→同步至远程”的完整操作，所有命令可直接复制到终端/Git Bash执行，适配Windows、Mac系统，适用于GitHub/Gitee/GitLab等所有Git远程仓库。

一、前提条件

操作前请确认以下3个条件已满足，避免后续操作报错：

1. 远程仓库已创建（需记录远程仓库地址，格式如：https://gitee.com/xxx/xxx.git 或 git@github.com:xxx/xxx.git）；

2. 本地已安装Git（可通过终端输入 git --version 验证，出现版本号即安装成功）；

3. 找到本地项目根目录（如：D:/WorkCode/FastAPICrawler），并在该目录下打开终端/Git Bash（Windows可按住Shift+右键，选择“在此处打开PowerShell窗口”）。

二、完整操作步骤（按顺序执行）

提示：所有命令均需在本地项目根目录的终端中执行，建议直接复制文档中的命令，避免手动输入出错。

第一步：初始化本地Git仓库

作用：在本地项目目录中创建Git仓库，让Git开始管理本地文件。

终端命令（直接复制执行）：

bash
git init

成功提示：Initialized empty Git repository in 你的项目路径/.git/（如：D:/WorkCode/FastAPICrawler/.git/），说明本地Git仓库创建成功。

第二步：将本地文件加入Git暂存区

作用：将本地项目所有文件提交到Git暂存区，准备进行版本提交。

终端命令（直接复制执行）：

bash
git add .

说明：命令中“.”表示当前目录下所有文件，执行后无明显提示（无报错即成功）。

第三步：提交本地文件到版本库

作用：将暂存区的文件正式提交到本地Git仓库，生成第一个版本记录。

终端命令（可修改引号内的提交说明，直接复制执行）：

bash
git commit -m "首次提交项目，初始化本地仓库"

成功提示：出现类似 “10 files changed, 123 insertions(+)” 的提示，说明提交成功。

第四步：关联远程Git仓库

作用：将本地Git仓库与已创建的远程仓库建立连接，后续可实现本地与远程的同步。

终端命令（需替换“你的远程仓库地址”，直接复制修改后执行）：

bash
git remote add origin 你的远程仓库地址

示例（替换为自己的仓库地址）：

bash
git remote add origin https://gitee.com/xxx/FastAPICrawler.git

验证关联是否成功：执行以下命令，若出现origin及对应的远程仓库地址，说明关联成功。

bash
git remote -v

第五步：将本地master分支改名为main分支（核心步骤）

说明：默认情况下，本地初始化后的分支名为master，需将其重命名为main，与远程分支保持一致。

终端命令（按顺序复制执行，3条命令即可完成改名+同步）：

1. 本地master分支重命名为main（不影响本地文件）：
git branch -m master main

2. 将本地main分支推送到远程，创建远程main分支：
git push -u origin main

3. 删除远程旧的master分支（可选但推荐，彻底统一为main分支）：
git push origin --delete master

成功提示：执行第2条命令后，出现“Branch 'main' set up to track remote branch 'main' from 'origin'”；执行第3条命令后，出现“To 你的远程仓库地址 + 0000000...1111111 master -> [deleted]”，说明改名及同步成功。

第六步：验证最终效果（可选）

作用：确认本地和远程分支均已改为main，操作无遗漏。

执行以下命令，查看本地分支和远程分支，确认均为main：

查看本地分支（当前分支前会有“*”）：
git branch

查看远程分支：
git branch -r

正常结果：本地只有main分支，远程只有origin/main分支，说明操作全部完成。

三、常见报错及解决方案（必看）

遇到以下报错时，直接对应解决方案操作，快速解决问题：

报错1：fatal: remote origin already exists

原因：本地已关联过其他远程仓库，需先删除旧关联，再重新关联。

解决方案（按顺序执行）：

bash
git remote remove origin
git remote add origin 你的远程仓库地址

报错2：推送失败（fatal: refusing to merge unrelated histories）

原因：远程仓库有文件（如README.md、LICENSE等），与本地仓库无关联历史，无法直接推送。

解决方案：先拉取远程文件并合并，再推送（执行以下命令）：

bash
git pull origin main --allow-unrelated-histories
git push origin main

报错3：删除远程master分支失败（error: unable to delete 'master': remote ref is protected）

原因：远程仓库设置了master分支保护，禁止直接删除。

解决方案：登录远程仓库（GitHub/Gitee/GitLab），进入仓库设置，取消master分支保护，删除后可重新开启保护（具体路径：仓库设置→分支管理→找到master分支，取消“保护分支”勾选）。

四、后续常用命令（方便后续开发）

开发过程中常用以下命令，直接复制执行即可：

1. 提交本地修改（后续修改文件后，推送前执行）：
git add .
git commit -m "修改说明（如：修复xxxbug、新增xxx功能）"
git push

2. 从远程拉取最新代码（多人协作时，避免冲突）：
git pull origin main

3. 查看当前分支状态（是否有未提交文件、冲突等）：
git status

五、注意事项

1. 所有命令需在本地项目根目录的终端中执行，否则会报错；

2. 远程仓库地址需复制正确，避免多输/少输字符（可从远程仓库页面直接复制“克隆地址”）；

提示：文档中示例地址（https://gitee.com/xxx/FastAPICrawler.git）及通用地址（https://gitee.com/xxx/xxx.git）均无法正常访问（提示网页解析失败或链接失效），请务必替换为自己实际的、可正常访问的远程仓库地址。