简介：这是一份面向初学者的Git与GitHub上手指南，帮助开发者理解版本控制的基本流程，解决本地代码如何安全、规范地推送到远程仓库的问题。内容整理为1份docx文档，压缩包仅52KB，轻量易读，适合随时查阅。文档从注册GitHub账号、创建仓库讲起，逐步介绍msysgit客户端的安装与右键菜单的使用，再到本地生成SSH key、配置用户名和邮箱，完成本地与远程仓库的连接；也提及了TortoiseGit图形界面扩展，方便不习惯命令行的用户选择。围绕git add、git commit、git push这套核心提交流程，文档结合具体命令给出了可照做的操作步骤，并解释了git status、git pull的常见用法。同时用专门篇幅讲解.gitignore文件的写法与作用，帮助用户排除编译生成的中间文件；还介绍了tag标签的查看、创建、删除与共享，方便标记版本迭代的关键节点，其中带注释tag和GPG签名tag的差异也有说明。整体结构清晰，从环境准备到日常提交流程，再到进阶的忽略规则与标签管理，形成了完整的Git使用链路。已有1062人浏览学习，适合刚接触版本控制、希望尽快上手Git与GitHub的开发者参考。
1. 用Git上传代码到GitHub：从注册到首次push的一次走通
把代码用Git推到GitHub，听起来就是几条命令的事，但真到自己动手时，很多人在SSH Key、remote地址、commit信息这些环节上翻车。这份资源讲的是一整套从注册GitHub账号开始，到安装客户端、配置SSH认证、最终把本地仓库推送上去的完整路径，也覆盖了.gitignore和tag标签这两个容易被忽略的实用点。适合刚接触版本控制的开发者，也适合那些本地已经在写代码、但还没理清“仓库怎么建、密钥怎么配、哪些文件不该提交”的从业者。后面每一章的命令我都按实际操作的顺序来写，照着敲基本能一把过。
2. 仓库与客户端选型：公共仓库的边界和msysgit能做什么
2.1 从注册到建仓：免费账号的操作边界
注册GitHub账号这一步没什么好说的，注册完成后最要紧的是创建仓库。登录后进入Repositories页面，点New按钮，填仓库名、写几句描述，然后选择可见性。这里有一个实际约束：免费账号默认只能建公共仓库，仓库里的代码默认对所有人可见。如果是公司内部项目或还没打算开源的代码，要么等私有仓库配额，要么先放在本地，等想清楚了再推上去。我一般会在建仓时顺手勾选README.md，这样远程端会有一个初始提交，后面本地和远程合并时会更直观，也方便刚克隆仓库的人一眼看到项目说明。
创建成功后，页面会给出几组命令行提示，包括HTTPS地址和SSH地址。很多第一次接触的人在这里直接复制HTTPS地址就去用，结果每次push都要输密码，输错几次还会被锁一段时间。想省事的做法是直接用SSH地址，也就是git@github.com:yourName/yourRepo.git这种形式，后面配置好密钥之后，push和pull都不需要再输入账号密码。仓库名称建议全小写、用短横线连接多个单词，比如my-project，这样在命令行里不用频繁切换大小写，URL也更好记。
2.2 客户端选型：命令行为主、图形界面为辅
服务端仓库解决的是“代码放在哪”，本地还需要一个Git客户端来执行提交推送。资源里用的是msysgit，这个客户端提供了最核心的命令行功能，装完之后在文件夹里右键就能看到“Git Init Here”和“Git Bash”。Git Init Here会在当前目录生成一个.git文件夹，这个文件夹就是本地仓库的元数据区，里面记录着版本历史、分支、远端地址等信息。初始化成功后会多出这个隐藏目录，说明本地git仓库已经建立。Windows系统如果看不到.git文件夹，需要在文件管理器里开启“隐藏项目”显示，不然会以为初始化失败。
如果觉得命令行不直观，可以在msysgit的基础上安装TortoiseGit，装完之后右键菜单里会多出Git Commit、Git Pull、Git Push这些图形化操作。我一般建议新手先不要依赖图形界面，把add、commit、push这三条命令用熟，因为图形界面封装了细节，出错时反而不容易定位问题。Git的大部分“翻车”都发生在原理不清的情况下，把底层命令跑通了，再去用图形工具会顺手得多。
这里还要多说一句：msysgit本质上是Windows下的Git实现，如果你用的是macOS，官方安装包里自带Git，直接装官方命令行工具就行；Linux发行版一般有自己的包管理器，apt、yum装一下git就是同样的效果。资源的操作路径以Windows为准，但原理完全通用。本地仓库初始化时，命令行的当前路径一定要定位到项目根目录，不要建在磁盘根目录或者系统目录下，否则.git会被放在不合适的位置，后续操作容易出各种权限问题，这一点我后面在第5章的排查部分还会再提。
3. SSH认证与身份配置：让GitHub认你是自己人
3.1 生成SSH Key并添加到GitHub后台
要让本地git与GitHub建立信任关系，最常用的方式就是SSH Key。原理上它是非对称加密：本地保留私钥，把公钥交给GitHub，push时GitHub用公钥来验证你的身份。整个过程比每次输密码要安全，也省去了输密码的麻烦。很多人不理解为什么要多这一步，其实很简单：GitHub服务器不认识你本人，它只认你手上的密钥。
生成密钥的命令是在git bash里运行：
ssh-keygen -t rsa -C "your_email@youremail.com"把邮箱换成自己的注册邮箱。这里说明一下参数含义：-t是指定密钥类型，rsa是最通用的类型；-C是注释，一般写邮箱，方便在GitHub后台识别是哪台机器生成的密钥。后面会提示确认保存路径和输入密码，直接一路回车即可。那个密码可以留空，也可以设置一个短语，留空的话私钥存放在本机就完全依赖文件权限保护；设置短语的话每次push都要输入一次，很多人嫌麻烦所以留空。安全敏感的项目建议设置，个人练习项目一路回车问题不大。
生成成功后，在用户主目录下会多出.ssh文件夹，里面有两个关键文件：id_rsa是私钥，无论如何不能泄露；id_rsa.pub是公钥，可以放心交给GitHub。打开id_rsa.pub，复制里面的完整内容，回到GitHub的Account Settings，在SSH Keys页面点击Add SSH Key，标题随便填，把公钥粘贴进去保存。验证是否连通，在git bash里执行：
ssh -T git@github.com第一次连接时，命令行会提示确认服务器指纹信息，输入yes回车，看到类似“You’ve successfully authenticated”的提示，就说明认证已经打通。一个常见的坑是复制公钥时漏掉了末尾的邮箱后缀，或者误复制了id_rsa私钥，这两种情况都会导致认证失败，检查时优先看这两处。
3.2 设置身份信息与添加远端仓库地址
SSH只解决“机器是否可信”，GitHub的每次commit记录还需要知道“是谁”提交的。所以接下来要配置用户名和邮箱，这两项会写入到每一次的提交记录里：
git config --global user.name "your name" git config --global user.email "your_email@youremail.com"两个值建议与GitHub账号保持一致，这样提交记录才能在GitHub页面正确关联到个人账号。这里补充一个技巧：如果电脑上有多个Git账号，比如一个公司账号一个个人账号，就不要加--global，而是在每个仓库目录下单独设置，这样不同项目的提交记录就会自动区分开。判断当前仓库用的是哪套身份，执行git config user.name和git config user.email就能看到。
接下来进入本地仓库目录，右键打开Git Bash，添加远端地址：
git remote add origin git@github.com:yourName/yourRepo.gityourName是你的GitHub用户名，yourRepo是你刚创建的仓库名。执行完这条命令后，.git/config文件里会多出一段remote "origin"信息，里面记录了远端地址。你也可以直接打开这个config文件手动修改地址，效果一样。这里要注意的是，如果建仓时勾选了创建README，远端已经有一个初始提交，本地仓库如果完全是空的，直接push会提示远端有本地没有的提交，需要先git pull把远端的README拉下来合并。这一步是新手最常见的首个卡点。
4. 提交推送的完整闭环：从首次push到日常修改流程
4.1 首次提交：add、commit、push三步走
本地仓库有了，身份也配置好了，接下来就是把文件提交上去。在项目目录下先放一个README或者其他源码文件，然后执行：
git add README git commit -m "first commit" git push origin mastergit add的作用是把文件从工作区加入暂存区，告诉Git“这次要提交哪些内容”；git commit则是把暂存区的内容固化成一次提交记录，并附上说明信息；git push把本地的提交推送到远端地址。三者的关系可以粗浅理解为：add是挑选货物，commit是打包成包裹，push是交到快递手里。很多初学的人上来直接commit，发现提示nothing to commit，就是因为漏掉了add这一步。
如果这个仓库不是新建的，远端可能已经有了别的分支，直接用master分支名不一定匹配。GitHub现在的默认分支名一般叫main，如果你建仓后没有手动改过，本地又没有对应名称的分支，push时建议用git push origin HEAD:main，或者先执行git branch -M main把本地分支改名。这一步看着小，却是新手最容易卡住的地方。如果你在执行git push时想省掉每次指定远端和分支的麻烦，可以加上-u参数，也就是git push -u origin master，这次推送会把上游关联信息写入config，之后直接git push就行。
4.2 日常修改闭环与.gitignore的前置认识
代码提交上线之后，日常改动的流程是：git status查看当前工作区有哪些文件变化，git diff可以逐行查看改动细节，确认无误后git add添加，git commit提交，最后git push推到远端。与之相对的git pull则是把远端最新的改动拉回到本地，方向与push相反。初次接触版本控制的人容易混淆push和pull的方向，记住一条经验：自己写完代码往外推是push，别人改动或远端初始化内容拿回来是pull。
git status的输出里会区分三类状态：位于“Changes not staged for commit”表示文件有改动但还没add；位于“Changes to be committed”表示已经add进暂存区，等待commit；位于“Untracked files”表示是新文件，Git还不知道要不要管它。看到这三种提示时，对应的处理方式分别是git add、git commit、以及决定是否要把它纳入版本管理。
如果你是第一次接触.gitignore，这里先说一个最简单的场景：项目里如果有编译生成的中间文件、日志文件、本地配置文件，这些内容不应该进Git仓库。.gitignore规则文件放在项目根目录，执行git add时，匹配到的文件会被自动排除。比如C#项目的典型写法：
bin/ obj/ *.suobin和obj是编译目录，里面全是生成产物；*.suo是Visual Studio的配置文件，属于个人环境信息，这些都不该提交。配置好之后，git status的输出会干净很多，提交时用git add -A也不会再误带入一堆垃圾文件。关于.gitignore的具体规则和“不生效”的处理，我放到后面的排查章节细说，这里先掌握基础用法就够了。
5. 常见问题与排查：SSH权限、push被拒、gitignore不生效的四项典型坑
5.1 Permission denied (publickey)：密钥对不上
现象：执行ssh -T git@github.com返回Permission denied，连接被拒绝。
原因：多数是公钥没有正确配置到GitHub后台，或者本地使用的不是对应私钥，还有可能是公钥内容复制时少了字符。
解决：先重新打开id_rsa.pub，确认复制的是.pub结尾的文本内容，不是id_rsa私钥。再去GitHub后台检查SSH Keys列表，删除旧key重新添加一次。如果还不行，执行ssh-add -l看看本地有没有加载密钥，没有就先ssh-add ~/.ssh/id_rsa，再验证一遍。这里有一个容易被忽视的细节：公钥内容开头是ssh-rsa，结尾是邮箱或注释，复制的时候要把首尾都包含进去，粘贴时不要手动换行，否则GitHub会认定格式非法。
5.2 push被拒：non-fast-forward提示与远端领先本地
现象：git push时提示“failed to push some refs”，英文下面还有non-fast-forward字样。
原因：远端仓库有本地没有的提交，比如建仓时勾选了README，或者同事在你的仓里推了新代码，直接覆盖会造成冲突，所以Git拒绝推送。
解决：先git pull origin master，把远端提交拉下来合并或rebase，解决可能的冲突后再git push。如果你确定远端的内容不重要，可以git push -f强制覆盖，但这条命令要格外慎重，强制推送之后远端的历史不可恢复，我一般只在个人分支上使用，只要涉及多人共用的分支，绝不轻易加-f。
5.3 提交的作者名字不对，GitHub上显示灰色
现象：push成功后，GitHub页面上的commit记录没有显示你的头像，只显示一串“Unrecognized author”之类的内容。
原因：本地git config里设置的邮箱和GitHub账号邮箱不一致，GitHub无法把提交关联到你的账号。
解决：检查git config user.name和git config user.email，把邮箱改成注册GitHub用的邮箱。已经提交的错误记录，可以用git commit --amend --reset-author修复上一条提交，需要改更多历史时再用git filter-branch或专门的工具，但如果是个人项目，改历史前一定先确认没有别人在用这个分支。我建议在配置完身份后先跑一次git config --list，把所有全局配置都过一遍，确认身份项准确再继续操作。
5.4 .gitignore不生效，文件还是被提交上去了
现象：明明在.gitignore里写了规则，git status里还是能看到相关文件，git add -A也一样全部加进去。
原因：文件在规则添加之前就已被Git跟踪，gitignore只影响未被跟踪的文件，已经进入暂存区或历史记录的文件不受影响。
解决：先把这类文件从暂存区移除但保留在本地磁盘，执行git rm -r --cached .再重新add和commit。如果你不确定具体是哪条规则没有匹配上，用git check-ignore -v 文件名，Git会告诉你是哪一行规则匹配到了，或者根本没匹配到，这个命令在排查规则时非常实用。下表整理了常见错误提示与对应含义，遇到类似输出时可以直接对照排查：
| 提示信息 | 含义 | 优先处理方向 |
|---|---|---|
| Permission denied (publickey) | SSH公钥未匹配 | 检查密钥内容与GitHub后台配置 |
| non-fast-forward | 远端有本地缺失的提交 | git pull后再push |
| nothing to commit | 暂存区为空 | 先git add再commit |
| remote origin already exists | 远端地址已重复添加 | 用git remote rm origin清理后重加 |
5.5 tag没有跟着push走
现象：打完tag后执行git push，GitHub仓库页面上看不到任何标签。
原因：git push默认只推送分支和commit，不会自动推送tag。
解决：显式执行git push origin --tags推送全部标签，或者git push origin v1.0只推送某一个标签。这是新手最容易忽略的细节，我在下一章里会专门展开讲，顺便把tag的完整操作串一遍。
6. tag标签的进阶用法：版本回溯与批量推送的收尾习惯
6.1 常用tag操作速览
tag的核心价值是给某个commit打一个可以随时回溯的标记，通常用在版本号更新的节点上。查看已有标签：
git tag git tag -l v1.*第一条列出所有tag，按字母排序，和创建时间没关系；第二条加-l和通配符，只看v1系列。创建标签有三种方式：轻量标签git tag v1.0直接打上，不带说明；带注释的标签git tag -a v1.0 -m "first version"记录更多上下文；有GPG私钥时还可以git tag -s v1.0做签名，安全性更高。除了给当前commit打tag，也可以给历史commit补打，先用git log --oneline找到目标commit的哈希值，再执行git tag -a v1.1 8a5cbc2。删除本地标签用git tag -d v1.0，验证签名用git tag -v v1.0。
6.2 把tag推送与版本管理做成固定习惯
推送tag的命令是git push origin --tags，它会一次性把所有本地标签推到远端，GitHub页面上的Releases/Tags位置就会显示出这些标记。如果只想推某一个，git push origin v1.0。这里有一个容易被忽视的细节：tag是绑定在具体commit上的，而不是绑定在分支上的，所以即使分支后来被删除或重命名，tag依然可以用于找回那个历史版本的代码。发布版本时配合tag，还可以在GitHub的Releases页面写版本说明，把每个版本的新特性、修复项和已知问题都列出来，比单纯看commit记录要直观得多。
从那以后我每次发布版本都会固定走一遍这个流程：先git tag -a确认当前版本号，再git push origin --tags同步到远端，同时在commit信息里标明版本变更点。这样无论是自己回溯还是别人接手项目，都能沿着tag这条线快速定位到每一个关键版本，而不是靠翻commit历史来猜版本边界。希望这些操作细节能帮到你。
本文还有配套的精品资源，点击获取
