1. 先把这件事想明白Linux 里推代码到底推的是什么很多人第一次在 Linux 终端里敲下推送命令的时候心里其实是虚的命令行黑漆漆一片没有图形界面里那种上传成功的绿色提示只有一个光标在那儿闪。我当年也是这样对着终端反复敲git status看了七八遍就怕哪天一个手抖把本地改了一半的代码给覆盖没了。后来带过几个刚入行的同学发现大家在 Linux 上做这件事卡住的地方高度重合不是不会写那几行命令而是脑子里没有一张本地仓库、远程仓库、工作区、暂存区之间的空间关系图所以每一步都像在盲操作。这篇内容就围绕Linux 系统下用 Git 把代码上传到 GitHub 仓库这条主线展开。它解决的核心问题很具体你有一台只有命令行的 Linux 机器可能是云主机、可能是实验室的服务器、也可能是一台退役笔记本装的发行版你想把上面写的代码同步到 GitHub 上做备份、做协作、做版本管理。适合三类人看刚接触 Linux 和 Git 的入门者、平时只在图形化工具里点按钮、想搞懂底层命令的中级使用者以及需要在不带界面的服务器上完成代码提交的从业者。整篇会按仓库怎么设计—关键细节怎么处理—完整实操怎么走—出问题怎么查的顺序推进。先铺一个底层认知不然后面全是死记硬背。Git 的模型是分布式的你本地有一个完整的仓库里面存着全部历史GitHub 上那个叫远程仓库它也是完整的。所谓上传本质是把本地新增的提交对象commit 对象及其指向的目录树、文件内容打包传过去然后让远程仓库某个分支的指针移动到新的位置。这解释了后面很多现象为什么第一次推送慢、为什么推送不是复制文件夹、为什么有时候推上去只传了几 KB。理解成同步提交历史而不是上传文件你在遇到冲突和拒绝时就不会慌因为你知道它拒绝的是历史线对不上不是文件坏了。我也得说清楚一点这篇里涉及的系统配置、路径、命令都是基于常见发行版主流的 Debian 系和 Red Hat 系的通用实践不同发行版的小工具名字会有点差异我会把差异点标出来。至于版本号、具体包名请以你机器上的包管理器实际输出为准不要照抄我写的数字。2. 整体设计从一台裸机到能推代码要打通哪几层2.1 分层拆解这件事其实是四层不是一条命令我习惯把Linux 上推代码到 GitHub拆成四层一层不通后面全堵。第一层系统层。Git 程序本身装没装、版本够不够、有没有基础的编译和网络工具。这一层最容易被忽略很多命令找不到的报错根子在这里。第二层身份层。Git 每次提交都要记录谁提交的需要配置用户名和邮箱。这一层配错了不会立刻报错但你的提交记录会变成一堆奇怪的署名事后改起来很麻烦。第三层认证层。GitHub 不接受账号密码做命令行推送必须用凭证个人访问令牌或者密钥对。这一层是新手卡死率最高的地方。第四层仓库层。本地初始化为仓库、关联远程地址、分支对应、推送。这一层反而是最简单的最顺的路径就三四条命令。分层的好处是排错有方向。终端说command not found去看第一层说Permission denied或者Authentication failed去看第三层说rejected或者non-fast-forward去看第四层。不要一上来就怀疑网络绝大多数情况跟网络没关系。2.2 为什么用命令行而不是图形工具有人会问既然有图形化客户端为什么非要在 Linux 终端里折腾我的理由有三条都是踩出来的。第一服务器上没有图形界面。你连上去的就是一个 shell图形工具根本起不来这是硬约束。第二命令行是唯一在所有环境都一致的接口。你在本地机器上学熟的这套命令换到容器里、换到 CI 流水线里、换到别人的机器上一字不改照样能用图形工具换个版本菜单就变了。第三排错时命令行给出的信息更完整。图形工具往往把底层报错吞掉只给你一句操作失败而终端会把完整的拒绝原因打出来那几行英文就是你排查的钥匙。代价当然也有没有可视化 diff、不能点选文件、冲突解决要靠编辑器。所以我的实际做法是混合使用日常提交走命令行涉及复杂合并冲突的时候把仓库同步到有图形界面的机器上用可视化工具处理处理完再推。工具是为人服务的不必搞成信仰之争。2.3 分支策略个人项目也别全堆在主分支上标题里说的是上传代码但只要你开始推第二次、第三次就不可避免要面对分支问题。我给的建议很朴素哪怕是一个人写的小项目也别所有改动都直接怼到主分支。原因很实际。主分支代表当前可用的状态你在上面做半成品的实验一旦推上去远程就处于一个半坏不坏的状态。正确的做法是拉一个特性分支干活做完了确认能跑再合回主分支。这个过程在命令行里就是两条命令的事git switch -c feature-xxx建分支干活干完git switch main切回来再合。多花的这十秒换来的是任何时候远程仓库都是可用的。对于纯学习练手的仓库可以放宽一点但也建议养成一个功能一个分支的肌肉记忆。习惯这东西等你哪天真要跟别人协作的时候再补成本会高得多。2.4 传输方式的选择HTTPS 还是 SSH这是个必须提前决策的点因为它决定了第三层认证怎么配。两种方式的差别我用一张表说清楚。对比项HTTPS 方式SSH 方式认证凭证个人访问令牌PAT密钥对私钥留本地公钥传平台首次配置难度低网页上生成令牌即可中要生成密钥、传公钥、可能还要配 config日常使用体验每次推送要么输令牌要么靠凭证缓存配好之后免交互直接推适合场景临时机器、容器、一次性环境长期使用的开发机、服务器出问题时的排查令牌过期、权限范围不够密钥权限、agent 未加载、端口被封凭证泄露风险令牌等同于密码泄露需立刻吊销私钥泄露风险更大但私钥不出机器我的选择逻辑是长期用的机器一律配 SSH临时环境用 HTTPS。原因很简单SSH 配一次管很久日常推送零摩擦而在一台只用来跑一次任务的容器里配密钥纯属浪费时间用 HTTPS 加一个短期令牌更省事。有人担心 SSH 在某些网络环境下连不上这确实存在。我的应对办法是给 SSH 配一个备用端口和连接保活参数写进~/.ssh/config这样即使默认端口不通也能走备用路径。这部分配置我在第 3 章会给出具体写法。至于具体哪些端口可用取决于你所在网络的实际策略我不做推荐你自己测。3. 关键细节那些不写出来一定会踩的坑3.1 身份配置一次配错历史全是错的user.name和user.email是每次提交都会写进 commit 对象的元数据。这两个值配错了后果不是报错而是悄无声息地错你的提交记录署名是个奇怪的东西等到你想在平台上看到自己的贡献图时发现一片空白。配置分两级这点很多人不清楚# 全局配置对当前用户的所有仓库生效 git config --global user.name 你的显示名 git config --global user.email 你的邮箱 # 仓库级配置只对当前仓库生效优先级高于全局 git config user.name 另一个显示名 git config user.email 另一个邮箱什么场景需要仓库级覆盖比如你在公司机器上用全局配的是个人邮箱但公司仓库要求用工作邮箱这时候在仓库里单独覆盖一下就行不用来回改全局。一个特别容易踩的点邮箱要和平台上账号绑定的邮箱一致或者至少是平台能识别的形式否则平台无法把提交归属到你名下。有些平台还提供一个专用的匿名转发邮箱用那个也能正确归属同时不暴露真实邮箱具体地址在账号设置里能找到。注意不要在配置里随手写一个不存在的邮箱很多平台的提交归属是靠邮箱匹配的写错了你的提交会变成未归属状态事后要批量改写历史才能修非常痛苦。配置完立刻验证别等提交了才发现git config --global --list这条命令会把当前生效的所有全局配置打出来你重点确认user.name和user.email两行。3.2 认证命令行推送为什么总被拒这是新手最常撞的墙。现象是地址没问题、仓库存在、命令也对但一推送就提示认证失败。原因在于主流代码托管平台早就关闭了用账号密码直接做命令行认证的通道必须改用令牌或密钥。走 HTTPS 的话需要在平台网页上生成一个个人访问令牌并给它勾选合适的权限范围。这里有个细节权限给多了不安全给少了推不上去。最小可用的范围通常是仓库内容读写这一项够你拉取和推送代码。生成后令牌只显示一次务必当场复制保存到密码管理器里。令牌的使用方式是把用户名填账号名、密码位置填令牌# 推送时会提示输入用户名和密码 git push origin main # Username: 你的账号名 # Password: 粘贴令牌输入时不显示字符这是正常的很多人在这里翻车是因为粘贴令牌时终端不回显以为没输进去反复敲回车结果认证失败。记住不回显是设计如此粘完直接回车。如果不想每次都输可以启用凭证缓存# 缓存凭证一段时间单位秒这里是一小时 git config --global credential.helper cache --timeout3600 # 或者用 store 明文存到磁盘安全性差仅限个人受控机器 git config --global credential.helper storestore会把凭证明文写在~/.git-credentials里我只建议在完全个人控制、不共享的机器上用共享服务器上绝对不要这么干。走 SSH 的话流程是本地生成密钥对、把公钥内容贴到平台的 SSH 密钥设置里、验证连通性。生成命令ssh-keygen -t ed25519 -C 你的邮箱或备注这里我强烈建议用ed25519而不是老的rsa前者密钥短、速度快、安全性好。生成过程中会问保存路径直接回车用默认和口令passphrase。口令这一项我的建议是设一个它不是登录密码而是给私钥加的一层加密即使私钥文件被拷走没有口令也用不了。当然如果你追求免交互比如脚本里自动推送可以不设但要靠文件权限保护私钥。生成后查看并复制公钥cat ~/.ssh/id_ed25519.pub输出的整行内容以算法名开头、以备注结尾原样贴到平台即可注意别漏了开头或结尾。然后验证ssh -T gitgithub.com第一次连接会提示确认主机指纹输入yes。成功的标志是返回一句包含你账号名的欢迎语。注意它可能会显示不提供 shell 访问之类的提示那是正常的能连上就够了。3.3 私钥权限这个报错 90% 的人遇到过SSH 密钥机制有个硬性要求私钥文件必须只有你自己可读。如果你的私钥权限是 644其他用户可读SSH 客户端会直接拒绝使用它报一句类似权限过于开放的错误。# 修权限目录 700私钥 600公钥 644 chmod 700 ~/.ssh chmod 600 ~/.ssh/id_ed25519 chmod 644 ~/.ssh/id_ed25519.pub我第一次遇到这个报错的时候盯着权限两个字看了半天心想我明明是这台机器的所有者啊。后来才明白SSH 不管你是谁它只检查文件模式位。这个设计是对的——它在保护你。注意不要把整个家目录用chmod -R一把梭改权限那会把很多系统预期的权限搞乱。只改~/.ssh下的这几个文件。3.4 换行符跨平台的隐形炸弹这个问题极其隐蔽。Windows 上的换行是 CRLF两个字符Linux 上是 LF一个字符。当仓库里同时有不同平台上改过的文件时Git 可能把整个文件标记为全部修改diff 里一片红实际上你什么都没改。在 Linux 单机环境下最稳妥的做法是明确告诉 Git 怎么处理# 提交时把 CRLF 转成 LF检出时不转换适合纯 Linux 环境 git config --global core.autocrlf input # 或者干脆关闭自动转换用 .gitattributes 精确控制 git config --global core.autocrlf false我更推荐后者加一个.gitattributes文件在仓库根目录写明各类型的处理规则这样规则跟着仓库走换哪台机器都一致不依赖每个人的本地配置。这是我吃过亏之后改过来的习惯——依赖本地全局配置的方案在多人协作时必然出问题因为总有人没配。4. 完整实操从零到推送成功的每一步4.1 第一步确认系统里的 Git 能用先别急着敲命令确认工具在位git --version有版本号输出就说明装了。如果提示找不到命令按发行版装# Debian / Ubuntu 系 sudo apt update sudo apt install -y git # Red Hat / CentOS / Fedora 系 sudo dnf install -y git # 老版本用 yum # Arch 系 sudo pacman -S git装完再看一眼版本。如果版本特别老比如低于 2.23某些现代命令如git switch不支持那就用等价的旧命令git checkout -b。判断标准很简单报未知命令就换旧写法。顺便配好身份这一步别跳过git config --global user.name 你的显示名 git config --global user.email 你的邮箱 git config --global init.defaultBranch main最后一行是把默认分支名设成main。现在主流平台新建仓库默认都是main本地如果还叫master推送时分支名对不上会多一步手工对应。提前设好省事。4.2 第二步在平台上先把仓库建出来这一步在网页上完成。要点有几个不要勾选自动生成 README 或 .gitignore。为什么如果你勾了远程仓库就不是空的它会有一个初始提交而你本地是空仓库两边历史毫无关系第一次推送会直接被拒报历史不相关。新手最容易在这里卡住。要么建一个完全空的仓库要么在本地先拉取再往里加东西。仓库建好后页面会给出仓库地址形如githost:账号/仓库名.gitSSH或https://host/账号/仓库名.gitHTTPS。用哪种取决于你第 3 章选的认证方式要对应上。混用是常见错误配了 SSH 密钥却用 HTTPS 地址然后疑惑为什么还要输密码。4.3 第三步本地初始化并关联远程进入你的代码目录初始化cd /path/to/your/project git init这一步会在当前目录建一个.git隐藏目录所有版本信息都在里面。不要手动去改这个目录里的任何东西它是 Git 的工作区不是给人编辑的。关联远程地址git remote add origin githost:账号/仓库名.gitorigin是远程仓库的默认别名你可以叫别的名字但没必要生态里所有人都用origin。关联完检查一下git remote -v会打出两行fetch 和 push确认地址没打错。地址错了后面所有操作都会失败而且报错信息未必直观所以这一步值得多看一眼。如果写错了用git remote set-url origin 新地址改不用删了重加。4.4 第四步暂存与提交理解两段式设计Git 的提交是两段式的先add到暂存区再commit到仓库。很多人觉得这一步多余直接提交不就行了这个设计其实很有价值它让你能精确挑选这次提交包含哪些改动。你改了三个文件但只有一个跟当前这个功能相关另外两个是顺手改的实验性代码——有了暂存区你就能只把相关的那一个提上去保持提交的语义干净。# 看当前状态哪些改了、哪些已暂存 git status # 暂存单个文件 git add path/to/file # 暂存所有改动包括新增文件不包括删除 git add . # 暂存所有改动包括删除和重命名 git add -A # 交互式挑选按块hunk暂存这是我最常用的 git add -pgit add -p值得单独说。它会把每个改动块逐个展示给你让你选择暂存还是跳过y/n甚至拆分更细的块s。我用它来把一次大改动拆成几个语义清晰的提交回头查历史的时候非常舒服。前期会觉得麻烦用顺手之后回不去。提交时写清楚信息git commit -m 修复配置解析在空值时的异常提交信息的写法我的经验是第一行说清做了什么不要写修改了一些东西这种废话。半年后你回来看历史只有具体的信息能帮你定位。如果改动稍复杂用多行git commit -m 重构配置加载逻辑 -m 把散落在各处的读取收敛到单一入口便于后续加缓存两个-m会自动用空行分隔第一行当标题后面当正文。4.5 第五步推送以及第一次推送的特殊写法推送命令git push -u origin main-u等同于--set-upstream的作用是把本地main和远程origin/main建立跟踪关系。建立之后以后在这个分支上直接git push就行不用再写后面那一串。第一次推送加-u之后可以省这是我建议的习惯。推送过程中你会看到类似这样的输出Enumerating objects: 12, done. Counting objects: 100% (12/12), done. Writing objects: 100% (12/12), 2.31 KiB | 2.31 MiB/s, done. To host:账号/仓库名.git * [new branch] main - main几个字段值得看懂Enumerating是清点要传的对象数Writing是实际传输的字节数最后一行是分支映射。如果对象数很少但字节数很大说明你提交了一个大文件比如误提交了编译产物或数据集这时候要停下来处理别硬推。关于大文件Git 对大文件不友好一个几十兆的二进制文件进了历史之后每次克隆都要拖着它。我的做法是在项目一开始就写好.gitignore把编译输出、依赖目录、日志、本地配置、数据集统统排除。写到一半发现已经提交了大文件处理起来要走历史重写很麻烦。预防成本远低于治疗成本这条我吃过两次亏。.gitignore的写法示例针对常见项目结构# 依赖目录 node_modules/ venv/ __pycache__/ # 编译产物 build/ dist/ *.o *.so # 日志与临时文件 *.log *.tmp .DS_Store # 本地配置含敏感信息绝不能提交 .env config.local.*如果某个文件已经被跟踪了加进.gitignore是不起作用的要先取消跟踪git rm --cached path/to/file注意是--cached只从索引里移除本地文件保留。不加这个参数会把本地文件一起删掉这是很多人手抖的地方。4.6 第六步验证别只看命令没报错就以为成了推送完做三件事确认本地看远程跟踪状态git status应该显示你的分支与 origin/main 一致。看提交历史git log --oneline -5确认最近几条提交都在署名正确。去平台网页上刷新肉眼确认文件在、提交信息对、署名归属到你。第三步不能省。我遇到过一种情况命令返回成功但推到的是一个同名的旧仓库地址远程地址配错网页上看什么都没有。肉眼看一眼比什么都可靠。5. 常见问题与排查实录5.1 报错速查表下面这张表是我这些年攒下来的高频问题按报错关键词排列遇到问题先在这里找。报错关键词典型原因处理办法command not foundGit 未安装或不在 PATH用包管理器安装确认git --versionAuthentication failed用了账号密码而非令牌或令牌过期/权限不足重新生成令牌并勾选仓库读写权限Permission denied (publickey)公钥未上传、密钥未加载、私钥权限过宽检查公钥是否贴对、ssh -T验证、chmod 600Host key verification failed主机指纹未确认或被变更首次连接输yes变更时先确认再更新 known_hostsrejected ... non-fast-forward远程有你本地没有的提交先git pull --rebase再推别用强制推refusing to merge unrelated histories本地和远程是两条独立历史建空仓库或确认后加--allow-unrelated-historiesremote: Support for password authentication was removed平台已关闭密码认证改用令牌或 SSHFile exists/ 已跟踪文件忽略无效文件已在索引中git rm --cached后重新提交error: insufficient permission for adding an object.git目录属主或权限不对修正目录属主别用 sudo 混跑 git推送卡住无响应网络到目标端口不通检查连通性SSH 可配备用端口5.2 三个我亲身踩过的坑坑一用 sudo 跑 git把仓库权限搞乱。有次在一台新机器上装完 Git顺手用sudo git init结果整个.git目录属主变成了 root。之后用普通用户提交一路报权限错误。更麻烦的是有些操作部分成功部分失败状态变得很乱。教训很明确Git 命令永远用普通用户跑不要加 sudo。需要系统级操作的时候单独用 sudo别和 git 混在一起。已经搞乱了就用sudo chown -R 用户名:组名 /path/to/repo修回来。坑二强制推送覆盖了远程的改动。早期我习惯遇到推送被拒就git push -f觉得省事。有一次在另一台机器上改了点东西推上去了本机不知道一个强制推直接把那边的提交抹掉了。虽然纯个人项目损失不大但这个习惯极其危险在协作场景里是事故级的。后来我给自己定了死规矩除非确认这个分支只有我一个人在用并且明确知道要丢弃什么否则绝不加-f。被拒了老老实实拉取合并。坑三把含密钥的配置文件提交上去了。有次赶时间把一份带数据库连接串的本地配置一起提交推了上去。虽然及时发现并删了文件但历史里还留着要彻底清除得重写历史。平台的密钥扫描会在几分钟内发告警邮件那一刻真的后背发凉。从此我的项目模板里第一个文件永远是.gitignore.env类和*.local.*一律排除。如果真发生了处理顺序是立刻吊销那个凭证这是第一优先改历史是第二步、清理历史、强制推、通知可能的协作方重新克隆。5.3 排查的基本方法论遇到问题别乱试命令按这个顺序走能省大量时间。第一步看完整报错。终端里的报错往往有好几行重点在最后两三行但前面几行常有关键上下文。别只盯着第一行的error字样。第二步确认当前状态。git status和git remote -v这两条命令几乎能定位一半的问题你在哪个分支、有哪些未提交改动、远程地址对不对。第三步分层定位。按第 2 章的四层模型判断问题出在哪系统层命令能不能跑、身份层配置对不对、认证层能不能连上远程、仓库层分支和历史对不对。ssh -T能单独验证认证层非常有用。第四步最小化复现。如果问题复杂在一个空目录里重新走一遍最小流程看是否还复现。这一步能排除掉大量本地环境特殊状态造成的干扰。第五步查历史操作。git reflog记录了你所有 HEAD 移动误操作后想找回之前的提交这里是救命稻草。git reset --hard搞丢了东西先用 reflog 找到那个提交的哈希再恢复。提示git reflog的记录默认保留一段时间不是永久的。重要节点该打标签就打标签git tag别指望 reflog 兜底一切。5.4 几个容易被忽略的实用技巧用别名减少打字。把常用命令配成短别名效率提升明显git config --global alias.st status git config --global alias.co checkout git config --global alias.br branch git config --global alias.last log -1 HEAD --stat git config --global alias.unstage reset HEAD --配完git st就是git status。别配太多配到肌肉记忆里常用的那几个就行配多了换台机器反而不会用了。提交前先看 diff。git diff看未暂存的改动git diff --staged看已暂存的。养成提交前扫一眼的习惯能拦住大量误提交比如调试用的打印语句、临时改的端口号。用git log的图形模式看分支结构git log --oneline --graph --all --decorate这一条能把整个分支拓扑画出来合并关系一目了然。排查为什么我的提交不见了这类问题时先看这个图比瞎猜快得多。换行符和文件模式的噪音。如果git status显示一堆你没动过的文件被修改了先怀疑换行符第 3.4 节或文件权限位变化。后者可以用git config core.fileMode false关掉对权限位的跟踪在跨文件系统比如挂载的共享目录里工作时这个设置很有用。推送前先拉一下。哪怕确定只有你一个人在改git pull --rebase一下也就几秒钟能避免大部分被拒的情况。--rebase和默认的 merge 的区别在于前者把你的本地提交接到远程最新提交之后历史是一条直线看起来干净后者会生成一个合并提交。个人项目我倾向 rebase协作项目按团队约定来。6. 一套可复用的日常流程把上面所有东西收拢成一个每次开新项目都能照着走的流程我自己是这么干的写在这里供参考。新项目初始化平台上建空仓库不勾任何自动生成项→ 本地git init→ 配好身份 →git remote add origin→ 写.gitignore→git add→ 首次提交 →git push -u origin main。这套走完项目就活了。日常改动git status看状态 →git diff扫一眼改动 →git add -p挑选 →git commit -m 具体描述→git pull --rebase→git push。六七条命令熟练之后一分钟内完成。分支干活git switch -c feature-xxx→ 改代码、提交若干次 →git switch main→git pull --rebase→git merge feature-xxx或先在平台上发起合并请求→ 推送 → 删掉特性分支。分支别留太多做完就删不然一段时间后你自己都分不清哪个是哪个。定期维护隔一段时间跑一次git remote prune origin清理远程已删除分支的本地引用跑一次git gc整理对象库。这些不是必须的但能让本地仓库保持健康。最后分享一个我自己定的小规矩它帮我避免了很多麻烦每次推送前问自己一句这条提交信息三个月后的我看得懂吗。看不懂就重写提交信息。代码是写给未来的自己看的提交历史也是。这个习惯看起来小题大做但当你需要回溯某个 bug 是什么时候引入的时候一份清晰的提交历史能省下你半天的时间。
