简介本资源是一份面向初学者的 Git 与 GitHub 入门实践指南适用于刚接触版本控制的开发者、学生及自学编程者系统解决「如何将本地代码规范上传至 GitHub 远程仓库」这一核心问题。文档以清晰步骤串联注册建仓、Git 客户端安装msysgit TortoiseGit、SSH 密钥配置、全局用户信息设置、add/commit/push 提交流程、.gitignore 文件编写规范以及 tag 创建与共享等关键操作并附有常见命令说明与排错提示如 SSH 认证验证、远程地址配置、多版本标签管理。资源为单个 Word 文档.docx共 1 个文件大小仅 52KB内容精炼、图文结合度高便于快速查阅与实操对照。目前已有 1061 人学习下载适合作为 Git 入门第一手参考资料帮助读者建立从本地开发到云端协作的完整工作流认知。1. 为什么“用 git 上传代码到 GitHub”不是一句命令能解决的事——新手卡在第 1 步老手栽在第 3 次 push你刚写完一个 Python 脚本想把它存到 GitHub 上备份、协作或当作品集展示。你搜到“git 上传代码到 github”点开教程照着敲了git init、git add .、git commit -m first然后复制仓库地址敲下git remote add origin https://github.com/xxx/yyy.git再git push -u origin main……结果终端突然卡住、报错fatal: unable to access https://github.com/xxx/yyy.git/: Could not resolve host: github.com或者更玄学的Authentication failed for https://github.com/xxx/yyy.git/。你刷新 GitHub 页面仓库还是空的。这不是你手速慢也不是网不好——这是本地 Git 环境、远程仓库状态、认证机制、分支命名规范四者没对齐造成的系统性阻塞。它不挑人Windows 新手会困在 SSH 密钥生成失败Mac 用户常被默认分支名mainvsmaster绊倒Linux 老手也可能因.gitignore里漏写__pycache__/导致上传了千个临时文件。本文不讲“Git 是什么”只聚焦一件事从git init到 GitHub 仓库真实显示你的代码文件每一步为什么必须这么走、不这么走会翻车在哪、怎么一眼看出卡在哪一层。适合所有已安装 Git 但还没成功 push 过一次的人——哪怕你已经重装过三次 Git。2. 本地 Git 初始化与首次提交别跳过这三步检查否则后面全是玄学Git 不是“上传工具”它是本地版本控制系统。上传push只是把本地已存在的提交commit同步到远程。所以第一步永远不是连 GitHub而是让 Git 认出你的项目目录是“受管仓库”。很多人直接git add .就跑结果发现.git目录没生成、git status报错“not a git repository”根源就在这一步没立住。2.1 创建本地仓库git init的隐藏前提与验证方式执行git init前请确认当前终端路径是你代码所在的最外层文件夹比如你的项目叫my-web-app那路径必须是/path/to/my-web-app而不是/path/to/或/path/to/my-web-app/src。运行命令git init逻辑说明该命令会在当前目录创建一个隐藏的.git文件夹里面存着 Git 的元数据对象库、分支指针、配置等。它不联网不依赖 GitHub纯本地操作。参数说明无参数时初始化为默认仓库加--bare会创建裸仓库无工作区仅用于服务器端接收 push普通用户不用加--initial-branchmain可指定默认分支名推荐避免后续因master/main差异报错。验证是否成功执行ls -lamacOS/Linux或dir /a .gitWindows能看到.git文件夹执行git status应返回On branch main或master和No commits yet若返回fatal: not a git repository (or any of the parent directories)说明路径错了用cd切到正确目录再试。2.2 添加文件到暂存区git add不是“选中文件”而是“声明要纳入版本控制”很多新手以为git add .是“把当前所有文件打包上传”其实它只是把文件快照放进暂存区staging area为下一步commit做准备。Git 不跟踪空文件夹、不自动忽略编译产物所以这一步必须主动干预。先看当前有哪些未跟踪文件git status你会看到类似Untracked files: (use git add file... to include in what will be committed) app.py requirements.txt __pycache__/注意__pycache__/被列为未跟踪文件——但你绝不想把它传到 GitHub它是 Python 运行时生成的缓存体积大且无意义。此时必须先配置.gitignore。创建并编辑.gitignore文件用 VS Code、Notepad 或nano .gitignore# Python __pycache__/ *.pyc *.pyo *.pyd .Python env/ venv/ .venv/ pip-log.txt # OS .DS_Store Thumbs.db # IDE .vscode/ .idea/逻辑说明.gitignore是 Git 的“过滤白名单”它告诉 Git “这些路径下的文件永远不要加入暂存区”。它只对尚未被 Git 跟踪的文件生效。如果__pycache__/已被git add过.gitignore就失效了——必须先git rm -r --cached __pycache__/清除缓存。参数说明--cached表示只从 Git 索引中移除不删除本地文件-r递归处理文件夹。保存后再次运行git status你会发现__pycache__/消失了只剩真正需要版本控制的文件如app.py,requirements.txt。现在执行添加git add app.py requirements.txt # 或一次性添加所有未忽略的文件 git add .逻辑说明git add .会递归扫描当前目录把所有未被.gitignore排除、且未被 Git 跟踪的文件加入暂存区。它不会添加空文件夹也不会添加已忽略的路径。关键提示如果你只想加部分文件比如先传核心代码文档稍后用git add file1.py file2.js显式指定避免误加调试日志或密钥文件。2.3 提交到本地仓库git commit是“打时间戳”不是“上传”暂存区准备好后才能生成永久快照git commit -m init: add core app files and requirements逻辑说明git commit把暂存区的文件快照写入本地.git对象库并创建一个唯一的 commit ID如a1b2c3d。这个操作完全离线不接触网络。-m后的字符串是提交信息必须写有意义的内容不能是update或fix因为它是你未来回溯代码变更的唯一线索。参数说明-m是 message 的缩写若不加-mGit 会打开默认编辑器通常是 vim让你输入多行信息--amend可修改上一次提交仅限未 push 前-a会自动add所有已跟踪文件的修改但不会 add 新文件慎用。验证提交是否成功git log --oneline应输出类似a1b2c3d init: add core app files and requirements至此你的代码已在本地 Git 仓库中“落盘”具备了可上传的基础。但注意GitHub 上还没有任何东西甚至还没有仓库。下一步才是连接远程。3. 创建 GitHub 仓库与建立远程连接HTTPS 和 SSH 不是二选一是场景选择很多人卡在git push报错本质是没搞清GitHub 仓库必须手动创建Git 不会替你建远程连接方式HTTPS/SSH决定了认证流程选错等于自断后路。别急着复制粘贴 URL先看清 GitHub 页面上的两个关键按钮。3.1 在 GitHub 上创建空仓库必须“空”且“同名”否则 push 会拒绝打开 github.com 登录后点击右上角→New repository。填写Repository name: 必须和你本地项目文件夹名完全一致比如本地是my-web-app这里就填my-web-app。虽然不强制但名字不一致会导致后续git clone时路径混乱新手极易混淆。Description: 随意写不影响功能。Public/Private: 新手建议选Public免费且可见Private 需付费或用学生认证。Initialize this repository with a README?:务必取消勾选原因如果勾选GitHub 会自动生成一个含README.md的 commit。而你的本地仓库是空的只有你自己的app.pygit push时 Git 会发现“远程有 commit本地没有”拒绝推送报错non-fast-forward。你得先git pull合并但新手根本不会处理冲突。所以——永远先建空仓库再 push 本地内容。点击Create repository。页面会跳转显示一个空仓库URL 类似https://github.com/yourname/my-web-app.git。3.2 配置远程仓库地址git remote add的 URL 格式决定认证方式回到本地终端确保你在项目根目录my-web-app文件夹内执行git remote add origin https://github.com/yourname/my-web-app.git逻辑说明git remote add是给远程仓库起一个本地别名这里是origin并绑定其 URL。origin是约定俗成的默认别名几乎所有教程都用它。URL 中的https://表示使用 HTTPS 协议通信。参数说明origin是别名可改成upstream或backup但git push时需对应如git push upstream mainURL 必须和 GitHub 页面上显示的Clone with HTTPS地址完全一致注意末尾的.git。提示如果你看到 GitHub 页面显示Clone with SSH以gitgithub.com:开头那是 SSH 方式。它需要你提前生成 SSH 密钥并添加到 GitHub 账户见 4.2 节。新手强烈建议先用 HTTPS因为它的错误信息更直白排错成本低。验证远程是否添加成功git remote -v应输出origin https://github.com/yourname/my-web-app.git (fetch) origin https://github.com/yourname/my-web-app.git (push)3.3 推送代码到远程git push的分支映射是成败关键现在执行推送git push -u origin main逻辑说明git push把本地分支的 commit 发送到远程仓库。-u--set-upstream是关键参数——它把本地main分支和远程origin/main分支永久关联。这样下次只需git pushGit 就知道推到哪。参数说明origin是远程别名main是本地分支名。如果你的 Git 版本较老2.28默认分支可能是master则命令为git push -u origin master。如何确认执行git branch带*的就是当前分支。如果一切顺利你会看到类似输出Enumerating objects: 4, done. Counting objects: 100% (4/4), done. Writing objects: 100% (4/4), 352 bytes | 352.00 KiB/s, done. Total 4 (delta 0), reused 0 (delta 0) To https://github.com/yourname/my-web-app.git * [new branch] main - main Branch main set up to track remote branch main from origin.刷新 GitHub 页面你的app.py和requirements.txt就真实出现了。注意如果执行git push -u origin main报错error: src refspec main does not match any说明你本地根本没有main分支可能git init时没指定或旧版 Git 默认master。此时先查git branch再用git checkout -b main创建并切换到main分支再 push。4. 认证失败排查HTTPS 密码过期、SSH 密钥失效、Token 权限不足——三类高频翻车现场90% 的git push失败不是网络问题而是认证环节崩了。GitHub 已于 2021 年 8 月起全面禁用密码认证即不能再输 GitHub 账号密码必须用 Personal Access TokenPAT或 SSH 密钥。下面按现象直击根因。4.1 HTTPS 方式报Authentication failed你还在输密码现象执行git push后终端弹出用户名/密码输入框你输入 GitHub 账号和密码报错Authentication failed for https://github.com/xxx/yyy.git/。原因GitHub 已彻底废弃密码认证。你输入的密码无论对错都会被拒绝。解决生成 Personal Access TokenPAT登录 GitHub → 右上角头像 →Settings→Developer settings→Personal access tokens→Tokens (classic)→Generate new token→Generate new token (classic)。勾选权限至少选repo读写私有/公开仓库、delete_repo删仓库可选、workflow触发 Actions可选。点Generate token立即复制生成的 token 字符串形如ghp_abc123def456...关闭页面——token 只显示一次用 Token 替代密码下次git push时用户名输你的 GitHub 账号如yourname密码栏粘贴整个 token 字符串不是密码。为免每次输入配置 Git 缓存凭证# macOS git config --global credential.helper osxkeychain # Windows git config --global credential.helper manager # Linux git config --global credential.helper cache首次输入 token 后Git 会缓存它后续 push 不再提示。血泪经验Token 权限别乱开。admin:org或delete_repo一旦泄露攻击者能删你所有仓库。生产环境建议用 Fine-grained tokens新式 Token权限粒度更细。4.2 SSH 方式报Permission denied (publickey)密钥没配对或没加载现象用gitgithub.com:xxx/yyy.gitURL执行git push报错Permission denied (publickey)。原因SSH 连接需公钥存于 GitHub和私钥存于本地严格匹配。常见原因私钥文件权限过大、SSH agent 未启动、公钥未添加到 GitHub。解决检查私钥权限Linux/macOSchmod 600 ~/.ssh/id_rsa如果权限是644或755SSH 会拒绝读取报错Bad permissions。启动 SSH agent 并添加私钥eval $(ssh-agent -s) ssh-add ~/.ssh/id_rsa若提示Could not open a connection to your authentication agent说明 agent 没启动。验证 SSH 连接ssh -T gitgithub.com成功时返回Hi username! Youve successfully authenticated...。失败则检查公钥是否已添加到 GitHubSettings→SSH and GPG keys→New SSH key粘贴cat ~/.ssh/id_rsa.pub的输出。避坑Windows 用户若用 Git Bash确保ssh-agent已启用任务栏右键 Git Bash 图标 →Options→Enable SSH Agent若用 PowerShell需单独启动Start-Service ssh-agent。4.3 其他认证相关报错速查表现象原因解决remote: Repository not found.远程 URL 错如少写了.git、用户名拼错、仓库名大小写不符、仓库是 Private 但 Token 无repo权限用git remote set-url origin https://github.com/correct-user/correct-repo.git修正 URL检查 GitHub 仓库设置fatal: origin does not appear to be a git repositorygit remote add未执行或执行时不在项目根目录运行git remote -v确认cd到正确路径再git remote adderror: failed to push some refs to https://... 提示non-fast-forward远程有你本地没有的 commit如别人 push 了或你勾选了 README 初始化先git pull origin main --rebase拉取并变基解决冲突后再 push5. 分支管理与持续上传从main到dev一次 push 不是终点上传成功只是起点。真实开发中你不会总在main分支改代码——那会污染主干。Git 的分支模型Branching Model是协作基石。本节教你用最小成本建立安全、可追溯的日常上传流。5.1 创建开发分支隔离新功能保护main主干假设你要开发一个新功能比如增加用户登录不要直接在main上改# 切换到 main确保最新 git checkout main git pull origin main # 创建并切换到新分支 git checkout -b feature/login逻辑说明git checkout -b branch-name是git branch branch-namegit checkout branch-name的快捷组合。新分支feature/login会从当前main分支的 HEAD最新 commit开始分叉独立演进。命名规范推荐type/description格式如feature/xxx、fix/yyy、docs/zzz便于团队识别意图避免空格和特殊字符。现在所有代码修改、git add、git commit都在feature/login分支进行。main分支保持干净随时可发布。5.2 同步远程分支让队友看到你的进展本地分支创建后GitHub 上还不存在feature/login。需显式推送git push -u origin feature/login逻辑说明-u同样设置上游分支之后在此分支上只需git push。GitHub 会自动创建同名远程分支。关键区别git push origin main是推送到已存在的远程maingit push -u origin feature/login是创建并推送新远程分支。刷新 GitHub 页面点击Branch: main下拉框就能看到feature/login分支以及你刚 push 的 commit。5.3 合并到主干Pull RequestPR是协作的正式入口功能开发完成测试通过后不能直接git merge到main。标准流程是发起 Pull RequestPR在 GitHub 仓库页面点击Compare pull request通常在feature/login分支页顶部填写 PR 标题如feat: add user login form和描述说明改动、影响、测试方法点Create pull request。此时 PR 进入代码审查Code Review流程。团队成员可在 PR 中评论、要求修改、批准合并。只有批准后才能点击Merge pull request将feature/login的 commit 合并到main。为什么不用git merge本地合并因为 PR 提供了审查、测试可集成 CI、讨论、审计日志的完整闭环。绕过 PR 直接 merge等于放弃协作保障是团队大忌。合并后本地需同步更新git checkout main git pull origin main # 拉取已合并的 commit git branch -d feature/login # 删除已合并的本地分支注意git branch -d只能删除已合并的分支若要强制删除如未合并用git branch -D但需谨慎。6. 进阶技巧用.gitconfig自动化重复操作用git alias把长命令变短当你重复执行git status、git add . git commit -m wip、git push origin main时说明该优化了。Git 的配置系统.gitconfig和别名alias能帮你省下每天 10 分钟——而且它们是跨项目的一次配置终身受益。6.1 配置全局用户信息与默认行为避免每次 commit 都被问“你是谁”Git 要求每个 commit 记录作者信息。若未配置git commit会报错please tell me who you are。在任意目录执行git config --global user.name Your Name git config --global user.email your.emailexample.com逻辑说明--global表示写入全局配置文件~/.gitconfig对所有仓库生效不加--global则只对当前仓库生效写入.git/config。参数说明user.name是显示名非 GitHub 用户名user.email必须和 GitHub 账户绑定的邮箱一致否则 commit 不会关联到你的 GitHub 账户头像。进阶配置写入~/.gitconfig[core] editor code --wait # 设置 VS Code 为默认编辑器需安装 shell 命令 autocrlf input # Windows 用户提交时转 LF检出时不转换防换行符污染 [init] defaultBranch main # 强制所有新仓库默认分支为 main推荐 [pull] rebase false # pull 时默认 merge更直观设 true 则变基6.2 创建常用 Git 别名把 5 个单词缩成 2 个字母别名是提升效率的核武器。编辑~/.gitconfig在[alias]段下添加[alias] # 状态简写 st status -s # 日志美化一行显示 commit id、作者、日期、信息 lg log --color --graph --prettyformat:%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)%an%Creset --abbrev-commit # 一键添加提交慎用确保你知道自己在提交什么 cm !f() { git add . git commit -m \$1\; }; f # 推送到当前分支无需写 origin main p !f() { git push origin $(git branch --show-current); }; f # 拉取当前分支并 rebase保持线性历史 up !f() { git pull --rebase origin $(git branch --show-current); }; f逻辑说明cm是函数式别名$1代表第一个参数如git cm add login uip和up用$(git branch --show-current)动态获取当前分支名避免手误。安全提示cm别名虽快但会git add .所有未忽略文件。我习惯用git add -p交互式添加逐块确认再git commit -m宁可慢一秒不传错一行。6.3 实用小技巧三招快速定位上传问题当git push卡住或失败别盲目重试按顺序查这三项查网络连通性ping github.com # 看是否能解析域名 curl -I https://github.com # 看 HTTPS 是否可达返回 HTTP 200 或 302 即可查 Git 状态与差异git status -sb # -s 简洁模式-b 显示分支 git diff --stat origin/main # 查看本地比远程多哪些修改未 push 的 commit git log origin/main..HEAD --oneline # 查看哪些 commit 还没 push 到远程 main查远程 URL 与凭证git remote get-url origin # 确认 URL 是 https 还是 ssh git config --global credential.helper # 查看凭证助手是否启用 # macOS钥匙串里搜 github.com删掉旧凭据重试 # Windows凭据管理器 → Windows 凭据 → 找 github.com 条目删除最后说个我踩过的坑某次在公司内网git push总是超时。查了半天发现是代理设置残留——执行git config --global --unset http.proxy和git config --global --unset https.proxy清除后立刻恢复。Git 的配置层级系统/全局/本地像洋葱一层层剥总有一层藏着问题。希望帮到你。本文还有配套的精品资源点击获取