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

本文记录如何把本地已有的项目文件夹推送到一个全新的 GitHub 仓库。整个流程是：本地初始化并提交，在 GitHub 创建一个空仓库，添加远程地址，首次推送。

前置条件

已安装 Git（Linux），可以用 git --version 确认；
有 GitHub 账号；
可选：安装 GitHub CLI（gh），用命令行创建仓库。

一、初始化本地仓库并完成首次提交

进入项目文件夹并初始化 Git 仓库：

1 2	cd /path/to/your-project 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，让远程仓库完全为空，第一次推送才不会冲突。

网页创建：打开 https://github.com/new，填写仓库名（例如 your-repo），选择 Public 或 Private，不勾选 README / .gitignore / License，点击 Create repository。创建成功后页面会显示 HTTPS 和 SSH 两种远程地址，任选其一。

命令行创建（需要 GitHub CLI）：在项目目录中执行：

1	gh repo create your-repo --public --source=. --remote=origin --push

不想立即推送的话，去掉 --push，稍后自己执行 git push。

三、配置远程地址

选项 1：HTTPS（开箱即用）

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

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

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

第一次使用需要配置 SSH Key。生成密钥（一路回车，默认保存在 ~/.ssh/id_ed25519 和 id_ed25519.pub）：

1	ssh-keygen -t ed25519 -C "你的邮箱"

启动 ssh-agent 并添加私钥：

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

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

1	cat ~/.ssh/id_ed25519.pub

测试连接，然后配置远程地址：

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

四、首次推送

先确认当前分支名，GitHub 默认使用 main：

1	git branch

如果还是 master，重命名为 main：

1	git branch -m master main

首次推送并建立追踪关系：

1	git push -u origin main

刷新 GitHub 仓库页面，就能看到代码了。

五、日常使用

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

# 拉取远程更新
git pull --rebase

# 查看远程地址
git remote -v

常见问题

现象	原因	处理方法
推送被拒绝：`rejected non-fast-forward`	远程不是空仓库，可能自动生成了 README 等文件	执行 `git pull --rebase origin main` 后再 `git push`
`Permission denied (publickey)`	SSH Key 没有配置好或没有添加到 GitHub	用 `ssh -T git@github.com` 自查，确认公钥已添加
每次都要输入账号和 Token	使用 HTTPS 推送时，GitHub 要求 Token 代替密码	改用 SSH
大文件推不动、仓库体积过大	提交了数据集、可执行文件或编译产物	不提交这类文件，必要时使用 Git LFS

忘记写 .gitignore、已经提交了不该提交的文件时，先修改 .gitignore，再清除索引重新提交：

1
2
3

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）；正文可以写改动的动机、做法和影响面，方便代码评审和后续排查；页脚写 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"