从本地文件夹到 GitHub 新仓库：一步步推送指南

这篇文章记录如何把“本地已有代码文件夹”推送到一个全新的 GitHub 仓库。默认假设：你本地已经有一个项目文件夹，但 GitHub 上还没有对应的远程仓库。

前置条件

已安装 Git（Linux）
拥有 GitHub 账号
可选：安装 GitHub CLI（gh）以命令行创建仓库

1 2	# 查看 Git 版本（确认已安装） git --version

一、初始化本地仓库并做首个提交

进入项目文件夹

1	cd /path/to/your-project

初始化 Git 仓库

git init

设置用户名和邮箱（一次性全局设置）

1 2	git config --global user.name "你的名字" git config --global user.email "你的邮箱"

创建/完善 .gitignore（避免把无关文件提交上去）

示例（按需取用）：

# 编译/缓存
node_modules/
*.log
.DS_Store
__pycache__/
*.py[cod]
.env
.idea/
.vscode/
dist/
build/
public/

暂存并提交

1 2	git add . git commit -m "chore: initial commit"

注意：首次提交前建议检查 git status，确认不会把隐私文件、超大文件误传。

二、在 GitHub 创建一个“空”仓库

创建仓库时，务必保持“不要勾选”自动生成 README / .gitignore / License，这样远程是完全空的，推送更顺畅。

方式 A：网页创建（GUI）

打开 https://github.com/new
填写仓库名（例如：your-repo）
可选：选择 Public / Private
不勾选 README / .gitignore / License
Create repository

创建成功后页面会显示两种远程地址：HTTPS 和 SSH，任选其一。

方式 B：命令行创建（GitHub CLI，可选）

1 2	# 进入你的项目目录后执行（交互式创建） gh repo create your-repo --public --source=. --remote=origin --push

如果不想立即 push，可以去掉 --push，稍后自己执行 git push。
若无 gh，可跳过本节，用网页方式创建。

三、配置远程地址（HTTPS 或 SSH）

你可以二选一：

选项 1：使用 HTTPS（简单、开箱即用）

1	git remote add origin https://github.com/<your-username>/<your-repo>.git

推送时可能需要输入 GitHub 账号与 Token（个人访问令牌）。Token 可在 GitHub → Settings → Developer settings → Personal access tokens 中创建。

选项 2：使用 SSH（推荐长期使用）

首次使用需配置 SSH Key：

生成密钥（若不存在）

1 2	ssh-keygen -t ed25519 -C "你的邮箱" # 一路回车，默认保存在 ~/.ssh/id_ed25519 和 id_ed25519.pub

启动 ssh-agent 并添加私钥

1 2	eval "$(ssh-agent -s)" ssh-add ~/.ssh/id_ed25519

复制公钥内容，添加到 GitHub → Settings → SSH and GPG keys

1 2	cat ~/.ssh/id_ed25519.pub # 复制输出到 GitHub

测试连接

1	ssh -T git@github.com

配置远程地址（SSH）

1	git remote add origin git@github.com:<your-username>/<your-repo>.git

四、推送到远程（默认分支 main）

确认当前分支名（建议使用 main）

1	git branch

若仍是 master，可重命名：

1	git branch -m master main

首次推送并建立追踪关系

1	git push -u origin main

成功后，刷新 GitHub 仓库页面即可看到代码。

五、后续协作的常用命令

提交新改动：

1
2
3

git add .
git commit -m "feat: 描述本次改动"
git push

拉取远程更新：

1	git pull --rebase

查看远程：

1	git remote -v

常见问题排查（FAQ）

推送被拒绝：rejected non-fast-forward

原因：远程不是空仓库，可能自动生成了 README 等
解决：
- 方法 A：删除远程的自动文件，保持远程为空；
- 方法 B：git pull --rebase origin main 后再 git push

Permission denied (publickey)

原因：SSH Key 未正确配置或未添加到 GitHub
自查：

1	ssh -T git@github.com

检查 ~/.ssh/id_ed25519.pub 是否已添加到 GitHub → SSH keys

需要输入账号密码/Token

使用 HTTPS 推送时，GitHub 需要 Token 替代密码
建议改用 SSH 方式，长期更省心

大文件推不动或仓库体积过大

避免把数据集、可执行文件、编译产物提交
必要时使用 Git LFS（Large File Storage）

忘记 .gitignore，提交了不该上的文件

# 先修改 .gitignore
# 然后清除索引并重新提交

git rm -r --cached .
git add .
git commit -m "chore: apply .gitignore"

六、提交信息规范（推荐）

为了让提交历史更清晰、可搜索，推荐遵循 Conventional Commits 规范：

基本格式：

<type>(<scope>): <简要说明>

<可选正文，多行>

<可选页脚，例如 Closes #123 或 BREAKING CHANGE>

常用类型一览：

类型	用途	示例
feat	新功能（feature）	feat(bt): add new takeoff behavior
fix	修复 bug	fix(mavros): correct FCU URL parsing
chore	非功能改动（构建脚本、依赖、初次提交）	chore: initial commit
docs	文档修改	docs: update README with usage example
style	代码格式（不影响功能）	style: reformat indentation in ListenCommand.cpp
refactor	重构（非修复非新增）	refactor(bt): simplify tick logic
test	测试相关改动	test: add unit test for JSON parser
perf	性能优化	perf(nav): improve GPS update rate
build	构建系统或依赖更改	build: switch to CMake 3.22
ci	CI 配置更改	ci: add GitHub Actions workflow

小贴士：

scope 可选，用于指明影响范围（例如模块名：bt、mavros、nav、planner 等）。
提示性提交可以在正文描述动机、做法与影响面，便于 Code Review 与后续排查。
关联问题单：在页脚使用 Closes #123 / Refs #123，平台会自动联动。
破坏性变更：页脚使用 BREAKING CHANGE: 说明迁移指南。

示例：

git commit -m "feat(bt): add new takeoff behavior"
git commit -m "fix(mavros): correct FCU URL parsing"
git commit -m "refactor(nav): simplify tick logic"
git commit -m "docs: update README with usage example"
git commit -m "chore: initial commit"

结合上文流程，建议首次提交使用：