Git 本地项目推送到 GitHub 实战：init、commit、push 详解

Git 本地项目推送到 GitHub 实战：init、commit、push 详解

刚开始学 Git 的时候，很多人都会卡在这几个问题上：

• 我已经在本地写好了项目，接下来怎么上传到 GitHub？
• git init、git add、git commit、git push 到底分别在干什么？
• 本地仓库和远程仓库有什么区别？
• 为什么我一推送就报错？

本文将不只讲解命令，还会尽量把背后的逻辑讲清楚。

如果你现在的状态是：

• 本地已经有一个项目目录
• 想把它上传到 GitHub
• 但不太理解 Git 的整体流程

那这篇文章会比较适合你。

本文会一步一步带你走完下面这条主线：

1. 创建本地项目目录
2. 初始化 Git 仓库
3. 添加文件并创建第一次提交
4. 在 GitHub 上创建远程仓库
5. 绑定远程地址
6. 把本地代码推送到 GitHub
7. 解决常见报错

本文使用的示例项目名是 RepoCopilot，你也可以把它替换成自己的项目名来操作。

1. 先理解：本地仓库和远程仓库分别是什么

如果只记一句话，可以记这个：

• 本地仓库：你电脑上的版本管理记录
• 远程仓库：GitHub 上的在线备份和协作中心

也就是说，Git 主要负责本地版本管理，GitHub 主要负责远程托管和协作。

一个项目从本地推到 GitHub，通常会经历下面这条主线：

1. 创建项目目录
2. 初始化本地 Git 仓库
3. 添加文件
4. 创建第一次提交
5. 在 GitHub 上创建远程仓库
6. 绑定远程仓库
7. 推送到 GitHub

2. 创建本地项目目录

先在本地新建一个文件夹作为项目根目录：

mkdir RepoCopilot
cd RepoCopilot

这时它还只是一个普通文件夹，不是 Git 仓库。

你可以先放一些基础文件进去，比如：

• README.md
• .gitignore
• LICENSE
• 源代码目录

例如：

touch README.md .gitignore
mkdir apps

3. 初始化本地 Git 仓库

在项目目录执行：

git init -b main

这一步做了两件事：

• 创建一个隐藏的 .git 目录
• 把当前文件夹变成 Git 仓库

参数 -b main 的作用是把默认分支直接设为 main。

执行后，你可以用下面命令检查当前状态：

git status

如果成功，通常会看到类似信息：

On branch main
No commits yet
Untracked files: (use "git add <file>..." to include in what will be committed)

这表示仓库已经初始化成功，但还没有任何提交记录。

4. 为什么要先写 .gitignore

很多新手会直接 git add .，结果把不该上传的内容也一起传上去了。

所以初始化之后，最好先写一个 .gitignore。

例如 Python 或全栈项目常见写法：

__pycache__/
*.py[cod]
.venv/
node_modules/
.env
dist/
build/

.gitignore 的作用是告诉 Git：

• 哪些文件不需要纳入版本控制
• 哪些内容只属于本地开发环境

典型不应该提交的内容包括：

• 虚拟环境目录
• 依赖安装目录
• 构建产物
• 本地配置和密钥文件

5. git add 在做什么

Git 里有一个很重要的概念叫'暂存区'。

可以把它理解成三层：

• 工作区：你正在修改的文件
• 暂存区：准备放进下一次提交的文件
• 仓库历史：已经正式提交保存的版本

如果你想把当前修改准备提交，需要先执行：

git add .

这里的 . 表示把当前目录下的所有变更加入暂存区。

然后执行：

git status

你通常会看到类似：

Changes to be committed:
new file: README.md
new file: .gitignore

说明这些文件已经准备好进入下一次提交。

6. git commit 在做什么

git add 只是把文件放进暂存区，还没有真正写进版本历史。

真正生成一个'历史快照'的命令是：

git commit -m "chore: bootstrap RepoCopilot project"

这里：

• commit 表示创建一次提交
• -m 表示直接写提交说明

一次 commit 可以理解为项目在某个时刻的一个快照。

提交后，可以查看历史：

git log --oneline

例如：

423c79d chore: bootstrap RepoCopilot project

这表示你已经有了第一条版本记录。

7. 提交前先配置 Git 身份

在提交之前，建议先配置用户名和邮箱。

全局配置方式：

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

如果你只想给当前项目配置：

git config user.name "Your Name"
git config user.email "[email protected]"

建议邮箱尽量和 GitHub 账号关联邮箱保持一致，这样提交记录更容易在 GitHub 上正确归属到你的账号。

8. 在 GitHub 上创建远程仓库

本地仓库准备好后，下一步是在 GitHub 上创建远程仓库。

创建时通常需要填写：

• Repository name
• Description
• Public 或 Private

如果你的本地已经有 README.md、.gitignore、LICENSE，建议创建远程仓库时不要再勾选初始化这些文件。

原因很简单：

• 如果远程仓库先有内容
• 本地仓库也有内容
• 两边初始历史不一致

第一次推送时就更容易出现冲突。

创建完成后，GitHub 会给你一个仓库地址。

HTTPS 形式通常是：

https://github.com/你的用户名/RepoCopilot.git

SSH 形式通常是：

git@github.com:你的用户名/RepoCopilot.git

如果你刚开始使用，HTTPS 会更直观一些。

9. 绑定远程仓库

现在本地仓库还不知道 GitHub 上对应的是哪个远程仓库，所以需要先绑定：

git remote add origin https://github.com/你的用户名/RepoCopilot.git

这里：

• remote 表示远程仓库
• add 表示新增一个远程
• origin 是远程仓库的默认名字

你可以用下面命令检查绑定结果：

git remote -v

通常会看到：

origin https://github.com/你的用户名/RepoCopilot.git (fetch)
origin https://github.com/你的用户名/RepoCopilot.git (push)

这说明本地已经成功关联远程仓库。

10. 第一次推送到 GitHub

执行下面这条命令：

git push -u origin main

这条命令可以拆成几个部分理解：

• push：把本地提交上传到远程
• origin：远程仓库名
• main：要推送的分支
• -u：建立本地 main 和远程 origin/main 的跟踪关系

第一次推送成功后，后面如果你一直在 main 分支开发，通常只需要：

git push

刷新 GitHub 页面后，你就能看到本地项目已经同步到了远程仓库。

11. 后续开发的日常流程

第一次推送完成后，后面的开发大多会进入一个固定循环：

1. 修改文件
2. 查看状态
3. 添加到暂存区
4. 创建提交
5. 推送到 GitHub

常见命令流程如下：

git status
git add .
git commit -m "feat: add repository health endpoint"
git push

这就是最典型的 Git 日常开发流程。

12. 常见报错与解决方法

12.1 fatal: not a git repository

原因通常有两个：

• 当前目录不是项目根目录
• 还没有执行 git init

解决方式：

git init -b main

或者先进入正确目录再执行 Git 命令。

12.2 remote origin already exists

说明你已经添加过一个名为 origin 的远程仓库。

解决方法一，先删再加：

git remote remove origin
git remote add origin https://github.com/你的用户名/RepoCopilot.git

解决方法二，直接修改远程地址：

git remote set-url origin https://github.com/你的用户名/RepoCopilot.git

12.3 src refspec main does not match any

这个错误通常出现在：

• 你还没有 commit
• 就直接执行了 git push

解决方式是先创建至少一次提交：

git add .
git commit -m "init"
git push -u origin main

12.4 推送时需要认证

如果你使用 HTTPS 地址，GitHub 往往不会再接受账号密码直接推送，而是需要：

• Personal Access Token
• Git Credential Manager
• 浏览器登录后的本机凭据

如果你已经在本机配置过 GitHub Desktop、VS Code GitHub 登录或凭据管理器，很多时候可以直接推送成功。

12.5 本地和远程都有初始文件，导致冲突

比如：

• 你本地有 README.md
• GitHub 创建仓库时也勾选了初始化 README

这时两边初始历史不同，第一次推送可能失败。

通常可以先拉取再处理：

git pull --rebase origin main
git push origin main

更简单的做法是：远程仓库初建时不要额外勾选初始化文件。

12.6 dubious ownership 或 safe.directory

这是 Git 的安全检查机制，常见于：

• 仓库由管理员权限创建
• 当前登录用户和仓库所有者不一致

解决方式：

git config --global --add safe.directory D:/Program/RepoCopilot

这表示你把该目录加入 Git 的安全目录列表。

13. 一组最常用的命令清单

如果你想快速回顾，可以只看下面这些命令：

mkdir RepoCopilot
cd RepoCopilot
git init -b main
git config user.name "Your Name"
git config user.email "[email protected]"
git add .
git commit -m "chore: bootstrap RepoCopilot project"
git remote add origin https://github.com/yourname/RepoCopilot.git
git push -u origin main

后续更新：

git add .
git commit -m "feat: add new API endpoint"
git push

14. 结语

把一个本地项目推到 GitHub，看起来命令不多，但背后其实涉及了几个非常核心的概念：

• Git 管理的是本地版本历史
• GitHub 提供的是远程托管和协作能力
• git add 管理的是暂存区
• git commit 生成的是版本快照
• git remote add 建立的是本地和远程的连接
• git push 完成的是远程同步

如果把这条主线理解清楚，后面学习分支、协作、Pull Request、Rebase 就会容易很多。

一句话总结这篇文章的核心：

本地仓库负责记录开发历史，远程仓库负责同步、备份和协作，而 git init -> git add -> git commit -> git remote add -> git push 就是把一个本地项目发布到 GitHub 的完整主线。