简介这是一份面向Git初学者的操作指南文档系统讲解如何从零开始使用Git将本地代码上传至GitHub资源以docx格式提供共1个文件压缩包大小约52KB。正文按完整流程分步编排从注册GitHub账号、创建仓库到安装msysgit客户端从生成SSH key并配置公钥到设置Git全局用户名与邮箱再详细演示git add、git commit、git push、git pull、git status等常用命令并说明通过git remote add origin关联远程仓库的方法。文档还专门介绍了.gitignore文件的编写思路教读者忽略bin、obj、*.suo等编译中间文件从而放心使用git add -A批量添加同时讲解了标签tag的查看、创建、删除、验证与共享操作帮助开发者标记软件开发中的关键版本节点。内容覆盖代码托管与版本管理的主要环节适合刚接触Git或希望规范提交流程的开发者按步骤对照操作快速搭建本地与远程仓库协作基础。目前已有1062人学习下载是一份实用的Git入门参考资料。1. 用 git 上传代码到 GitHub先想清楚这一行的价值第一次接触 git 上传代码到 GitHub 的人十有八九是在本地建了个文件夹、写了几十个文件然后想把它放到 GitHub 上保存一份。很多人第一反应是打开 GitHub 网页点 Upload files把文件拖进去。这个方式对单个小文件确实能行但一旦你的项目有几十个文件、要持续迭代、还要在不同电脑之间同步纯网页拖拽很快就会失控。git 的意义不是“上传”这个动作本身而是给每次上传建立一条完整的版本时间线。你提交的每个版本都能回滚、能对比、能追溯是谁在哪一次提交里改了什么。这篇笔记要解决的就是这条时间线怎么搭建、怎么走通、以及第一次走通时常见的坑。2. 动手之前本地仓库和远程仓库的映射关系2.1 三个基础概念工作区、暂存区、本地仓库很多新手第一次上传失败不是因为命令敲错而是脑子里没有建立起“本地”和“远程”是两套独立系统这个模型。在本地git 把项目分成三个区域工作区是你电脑上实际看到的文件和文件夹暂存区是一个中间缓冲地带你执行 git add 后文件会先到这里本地仓库则是 git 真正记录版本的地方执行 git commit 后暂存区的内容被打成一个提交存进本地仓库。这三个区域的关系决定了你每天要敲的那几条命令分别在对谁说话。git add 是把工作区的改动挪到暂存区git commit 是把暂存区的改动固化成本地仓库的一个版本git push 才是把本地仓库的版本同步到 GitHub 上的远程仓库。很多人以为 git commit 就等于“上传了”其实 commit 只发生在本地哪怕断网也能执行。只有 push 是真正和 GitHub 打交道的那一步这一步需要网络、需要身份验证、需要保证本地和远程的历史没有分叉。git status这条命令在任何时候都值得先敲一遍。它会告诉你当前在哪个分支、工作区有哪些文件被修改、哪些改动已经进入暂存区、哪些还没有被 git 跟踪。你在上传之前先看一眼 git status能避免很多“以为自己传了、其实没传”的尴尬。我自己的习惯是每次 push 之前必敲先确认要传的东西确实在列表里。2.2 origin 和 main两个新手最容易懵的词origin 是 git 默认给远程仓库起的名字它不是 GitHub 的官方术语而是 git 自己的约定。你在本地执行 git remote add origin 某个地址就是把“origin”这个名字绑定到某个远程 URL 上。以后所有跟远程相关的操作git push origin main、git pull origin main都是用 origin 指代那个远程仓库。main 是分支名。2020 年之后GitHub 新建仓库默认分支叫 main之前叫 master。很多本地的 git 版本git init 之后创建的默认分支仍然是 master这就埋下了一个隐患你本地在 master 上提交远程仓库默认是 main直接 git push origin master 会把代码推到 master 分支而 GitHub 默认展示的分支却是 main于是你打开仓库页面发现空空如也代码“丢了”。git branch -a git remote -v这两条命令一个是列出所有本地和远程跟踪的分支一个是显示你当前绑定的远程仓库地址。建议第一次配置完就敲一次确认你本地的分支名和远程要推的分支名能对上。如果本地是 master 而远程是 main直接改名就好后续会讲到。2.3 为什么第一次推送到 GitHub 一定要加 -ugit push -u origin main 里的 -u全称是 --set-upstream意思是把本地分支和远程分支绑定成上下游关系。绑定之后后续在这个分支上只需要敲 git push 或 git pullgit 会自动知道该往哪个远程的哪个分支推不用每次把 origin main 写全。这个绑定的价值在日常使用中才显现。第一次推送如果不加 -ugit 只会执行这一次推送不会记录关联关系。你第二次想偷懒只敲 git pushgit 会提示你缺少上游分支信息还得再补一次完整命令。所以第一次推送时加 -u 是一劳永逸的习惯不是可选项。需要注意的是-u 只对你当前所在的分支起作用。如果项目有好几个分支每个分支第一次推送时都需要单独加一次 -u 绑定。这是很多人在多分支项目里推完 main 之后推新分支时又收到一通提示的原因。提示绑定关系是存在本地 .git/config 文件里的换一台电脑 clone 下来的仓库不会有这些绑定需要在每个分支上重新设置或直接敲完整命令。3. 完成第一次上传从零到 GitHub 出现你的代码3.1 初始化仓库与在 GitHub 新建远程仓库在动手写命令之前建议先决定你的项目目录结构。这里有一个值得养成的习惯先创建 .gitignore 再提交代码。.gitignore 用来声明哪些文件不要被 git 跟踪比如 Python 项目里的pycache文件夹、node_modules 目录、IDE 的 .idea 或 .vscode 配置、还有 .env 这类包含密钥的配置文件。不要小看这个文件少了它你迟早会把不该传的东西传到 GitHub 上。mkdir my-project cd my-project git init进入项目目录后执行 git initgit 会在这个目录下创建隐藏的 .git 文件夹所有版本历史都存在这里面。这个文件夹不建议手动去改也不建议把它传给任何人。之后在 GitHub 网页上新建一个空仓库名字和本地项目同名就行其他选项全部留空。很多人会被“初始化 README、添加 .gitignore、添加 license”这三个选项诱惑但对第一次上传来说建议都不要勾。勾了 README远程就有了一个本地没有的提交第一次 push 就会被拒。3.2 走一遍完整的首次推送命令远程仓库建好后GitHub 页面会给你一段建议命令。下面是一条完整的首次推送流程我把每步拆开写方便你对照理解git config --global user.name your-name git config --global user.email your-email第一次在电脑上使用 git 时会先用这几行设置提交者的名字和邮箱。这些信息会记录在每一个 commit 里GitHub 的提交记录页显示的作者头像和名字就来自这里。邮箱建议和 GitHub 账号绑定的邮箱一致否则提交虽然能推上去但不会关联到你的账号头像。user.name 和 user.email 是 --global 级别的配置一次设置后面所有仓库都生效不用每个项目重复配。git add . git commit -m first commit git branch -M main git remote add origin https://github.com/your-name/my-project.git git push -u origin maingit add . 里的点代表当前目录所有改动。这里有个隐藏陷阱git add . 只会添加那些没有被 .gitignore 忽略的文件而且是按当前目录递归添加所以如果你在仓库根目录执行会把你项目里所有文件加进暂存区。如果只想提交某个文件写成 git add 文件名。git commit -m 后面跟的是提交信息第一次提交写 “first commit” 就行后面越写越讲究。git branch -M main 是强制把当前分支重命名为 main。这里的 M 是大写和 git branch -m 的小写不一样。小写 m 在目标分支名已存在时会报错大写 M 则是“不管怎样都要改成这个名字”。这一步能彻底避免 master/main 分支名不一致的问题。git remote add origin 后面的 URL 有两种常见格式https 开头的是 HTTPS 方式git 开头的是 SSH 方式。两种方式对应不同的认证机制。HTTPS 方式在 push 时会要求输入 GitHub 的用户名和密码实际是个人访问令牌SSH 方式需要你先在本机生成一对密钥再把公钥配置到 GitHub。对新手来说HTTPS 方式配置起来最简单后面推多了再换 SSH。git push -u origin main 是命令的临门一脚。输入后会提示输入用户名和密码看到类似 “master - main” 或 “main - main” 的输出再去刷新 GitHub 页面代码就已经在仓库里了。3.3 日常更新改代码、提交、推送的三步循环首次推送成功之后后续的工作流就是固定的三步循环。它的稳定性值得信赖因为每一步都在做一件很纯粹的事git add . git commit -m update xxx module git push为什么每次都要三步走直接说原因git add 是让你决定“这一批改动里哪些要进版本历史”git commit 是把这个决定固化成本地的一个版本点git push 才是把版本点同步到远程。很多人想省掉 add 直接 commitgit 其实提供了 git commit -a 这条捷径它会自动把所有已跟踪文件的改动加入暂存区再提交。但 -a 不会把新文件加进来只对已跟踪文件生效所以新手不建议用这个捷径老老实实 add 再 commit能少踩很多“新文件没被提交”的坑。日常更新时commit 信息写得清楚一点对三天后的自己很有帮助。比如 git commit -m fix: 修复登录页密码框在手机端被键盘遮挡的问题比 git commit -m fix bug 要实用得多。为什么建议 commit 信息里带一条简短描述下面第 5 章会专门展开。3.4 换电脑继续开发clone 下来再推回去换了新电脑或者团队成员要接手这个仓库不需要重新把文件拷来拷去。git 提供了 clone 命令会把远程仓库的全部代码和完整历史下载到本地git clone https://github.com/your-name/my-project.git cd my-project git pushclone 下来的仓库会自动把远程地址绑定为 originmain 分支也会自动建立跟踪关系所以你第一次 push 不用再敲 git push -u origin main直接 git push 就行。这里有个值得注意的边界clone 之后你在新电脑上提交的代码如果和你原来电脑上的提交不在同一个版本线上比如旧电脑上又有新的提交两边的历史就分叉了。下一次 push 就可能遇到 non-fast-forward 的拒绝第 4 章第一个坑就是它。4. 上传避坑5 个开发者常见的翻车现场4.1 坑一push 被拒绝提示 non-fast-forward现象执行 git push 后git 提示 “! [rejected] main - main (non-fast-forward)” 或者 “failed to push some refs to ...”并且建议你先 pull。很多人第一次看到这个报错会慌以为代码丢了其实代码一条没丢只是 git 在保护远程仓库的历史不被覆盖。原因本地仓库和远程仓库的历史分叉了。最常见的场景是你在 GitHub 网页上勾选了“初始化 README”远程因此多了一个本地没有的提交或者你换电脑 clone 代码后改了又推而旧电脑上也有未推送的提交。git 发现两边的历史没有共同的“最新点”就不允许直接推。解决先把远程的提交拉下来合并到本地再推上去。常见做法是执行 git pull --rebase origin main。--rebase 和普通 pull 的区别在于它会把本地的提交“挪”到远程最新提交的后面而不是生成一个合并提交历史看起来是线性的更干净。执行完再 git push 就通了。git pull --rebase origin main git push注意如果在 pull 过程中出现冲突比如本地和远程都改了同一个文件git 会停下来并告诉你哪个文件冲突了。你需要打开文件、手动保留正确的部分、然后 git add 那个文件再 git rebase --continue。不要在这里乱敲 git commitrebase 中途手动 commit 会把 rebase 状态搞乱。4.2 坑二文件明明在远程仓库里却没有现象push 成功GitHub 页面上也显示提交了但某些文件就是找不到。常见的是 node_modules 目录不存在了或者 .env 文件没上去。有人以为是 git 抽风重新 add 再 push还是一样。原因文件被 .gitignore 忽略了。.gitignore 里的规则不止能忽略你写进去的目录也可能误伤你想提交的文件。比如规则写的是 *.log你某个资源文件恰好叫 error.log它就被静默跳过了。git add . 不会给你任何报错只会假装这个文件不存在。解决先用 git check-ignore -v 文件名 看看是哪条规则把这个文件拦下来的再决定是改 .gitignore 还是强制添加。git check-ignore -v error.log这条命令会输出类似 “.gitignore:3:*.log error.log” 的信息冒号前是规则文件的路径中间是行号后面是具体规则。如果确实需要这个文件入库有两种处理方式要么删掉或改掉 .gitignore 里那条规则要么用 git add -f error.log 强制添加。强制添加的文件不受忽略规则限制会正常入库。但要小心使用 -f它会让 .gitignore 形同虚设用多了就失去了保护意义。4.3 坑三push 时提示密码错误或身份验证失败现象push 时提示 “Username for GitHub” 或 “Password for GitHub”输入 GitHub 密码后却报 “remote: Support for password authentication was removed”。如果去 GitHub 网页重新设置密码再回来输入还是不对然后就开始怀疑人生。原因GitHub 从 2021 年 8 月起不再接受账号密码直接 push。HTTPS 方式要求使用 Personal Access Token个人访问令牌作为密码或者在 GitHub 个人设置里把原有密码方式升级为 token。这是很多刚接触 git 的新手第一次踩到的墙因为界面提示根本不提 token 这回事。解决在 GitHub 的 Settings 里找到 Developer settings生成一个 Personal Access Token生成时把 repo 相关的权限勾上把生成的 token 复制下来。push 提示输入密码时粘贴这个 token 而不是账号密码。注意 token 只显示一次刷新页面后就看不到了建议复制到临时文件里等 push 完成。如果觉得每次输 token 太麻烦可以配置 SSH key 方式但 SSH 的配置涉及密钥对的生成和公钥部署属于另一个话题新手先走 token 路线最快。4.4 坑四把不该传的文件传上去了比如密钥现象push 成功后第二天发现仓库里有一个 .env 文件里面写着数据库密码或 API 密钥。虽然没被陌生人发现但自己心里总觉得不安。想删掉再 commit 一次但 git 提示这个文件已经不在工作区了删干净了然而打开 GitHub 仓库的历史记录那个文件还在。原因git 的历史是只追加的。你提交过的每一个版本只要它还存在于提交历史中就不会因为后续的删除而消失。把密钥文件删掉再提交只是让它在最新版本里消失历史里仍然能看到。只要仓库是公开的就等于密钥还是公开的。解决分两步走。第一步立刻去对应的服务后台把密钥作废重新生成这是唯一的根治方式。第二步再处理仓库历史。如果仓库只有你一个人在开发可以用 git filter-repo 这类工具重写历史把那个文件从所有提交中抹掉然后强制推送。但要注意重写历史后所有本地 clone 过的仓库都会和远程失去一致需要重新 clone。如果仓库是多人协作的重写历史会让其他人的本地仓库全部作废必须和团队充分沟通。我的建议是处理完之后把所有老 clone 删掉重新 clone 一遍。git log --oneline -- .env这条命令可以快速查看 .env 文件在哪些提交里出现过先确认影响范围再决定处理方案。4.5 坑五分支名不一致代码找不到在哪现象推送时报成功GitHub 页面却没有显示你的分支或者在 pull request 里怎么都找不到自己刚才推的代码。明明显示上传成功了却不知道代码跑哪去了。原因本地和远程的分支名不一致。比如说本地分支叫 master直接 git push origin master代码推到了远程的 master 分支而 GitHub 默认展示的是 main 分支你打开仓库主页当然看不到。还有另一种情况执行 git push 时没有指定目标分支git 把本地分支推到了同名远程分支但远程那边其实没有这个名字的分支于是 git 自动创建了一个新分支代码在分支列表里。解决先看当前分支名和远程分支列表再决定怎么推。git branch -a输出里本地分支前面没有前缀远程跟踪分支显示为 remotes/origin/某名字。如果远程已经有 main本地叫 master建议直接把本地分支改名为 main 再推git branch -M main git push -u origin main。如果远程没有 main推送时显式指定本地和远程的分支对应关系git push origin 本地分支名:远程分支名。比如 git push origin develop:main把本地的 develop 推到远程的 main。这样写能保证推错分支这种问题从源头消失。5. 从“能上传”到“传得漂亮”提交规范、标签与回退习惯5.1 提交信息怎么写回滚时才能看懂commit 信息是给未来的自己和其他协作者看的。一个值得推广的格式是type(scope): subjecttype 表示这次提交的类型比如 feat 是新功能、fix 是修 bug、docs 是文档、refactor 是重构冒号后面用一句简短的话说清楚做了什么。比如 fix(login): 修复手机端密码框被键盘遮挡。这个格式的好处是git log --oneline 浏览历史时一眼就能看出每一条提交的意图回滚时也能快速定位到具体哪一次提交引入了问题。git log --oneline回滚的思路也要提前想清楚。如果需要撤销某次提交优先用 git revert它会生成一次新的提交来抵消旧提交历史不会被改写适合多人协作的分支。只有确定这个提交只有你自己知道、还没推到远程时才用 git reset 硬重置。reset 会改写历史push 时会被拒绝必须加 -f 强制推送这是危险系数最高的操作用了就要有承担后果的准备。5.2 用标签给版本打点回退不再靠翻日志如果你的项目已经到了需要发版本的阶段建议给关键的提交打标签。git tag 的功能是在某个提交上固定一个名字比如 v1.0.0之后随时可以一键切换到那个版本不用靠时间戳和提交哈希去翻历史。打标签的操作很简单git tag -a v1.0.0 -m release v1.0.0 git push origin v1.0.0-a 是创建一个带注释的附注标签-m 后面是标签说明。推送时指定标签名标签才会跟着提交一起到远程。之后在 GitHub 的 Releases 页面能看到这个标签可以直接从这里发版本说明。回退时git checkout v1.0.0 就能切到那个历史状态。不过要注意checkout 标签会进入 detached HEAD 状态在这个状态下做的提交不会属于任何分支想改东西先建一个新分支再改。5.3 一段关于提交习惯的个人教训最后说一个让我印象深刻的教训。早年在某公司做内部项目时赶进度每次提交信息都写 “update” 或 “fix”过了一个月产品要发版我对着几百条 commit 完全找不到某个需求的代码在哪一次提交里加的只能一个个 checkout 试。那次之后我就给自己定了一条规矩提交信息不许裸写至少说明改了哪个模块。后来转做需要多人评审的项目这条习惯直接从“可选”变成“强制”评审的人不会愿意点开一条信息是空白的提交记录。现在我自己维护小项目也会遵守这个习惯因为总有一天你会回来看这份历史。上传代码到 GitHub 从来不是终点你的提交记录质量才是这个技术方向真正值不值得投入的地方。希望这些经验能帮到你少走一段弯路。本文还有配套的精品资源点击获取