Git從入門到「入坑」：一個新手的環境配置與踩坑實錄

Git從入門到「入坑」一個新手的環境配置與踩坑實錄——AtomGit春季徵稿·開源入門實戰分享導語為什麼我要寫這篇文章三個月前我連git clone和git pull的區別都說不清楚。每次看到Git報錯我的第一反應不是讀錯誤信息而是複製粘貼到搜索引擎然後從Stack Overflow上找一條看起來「最像」的命令執行。運氣好的時候問題解決了運氣不好的時候——錯誤信息變得更長了。這篇文章不是大師的佈道而是一個剛從「Git小白」階段爬出來的人的踩坑筆記。我會用最樸實的語言還原我從安裝Git、配置SSH、理解分支、到第一次成功提交Pull Request的全過程以及那些讓我深夜抓狂的錯誤和最終的解決方案。如果你也是一個剛接觸開源、看到終端就頭皮發麻的新手這篇文章或許能幫你省下幾個失眠的夜晚。閱讀本文大約需要12分鐘建議邊看邊操作。第一章 環境配置三個操作系統下的「標準答案」1.1 macOS最「無感」的安裝我的主力機是MacBook這也是我最初接觸Git的環境。macOS的優勢在於系統自帶Git——至少我是這麼以為的。打開終端輸入git --version確實輸出了一串版本號。但當我試圖git push時遇到了第一個坑系統彈窗要求安裝Xcode Command Line Tools。這裡需要解釋一下macOS自帶的Git只是一個「占位符」實際執行Git命令時會觸發Xcode Command Line Tools的安裝。這個安裝包大約2GB下載時間取決於你的網速。正確做法不要和系統彈窗較勁。點擊「安裝」等待完成。如果彈窗沒有出現或者下載失敗可以手動執行xcode-select--install安裝完成後用git --version確認版本。我當時的版本是2.39.5足夠日常使用。如果需要最新版本可以通過Homebrew安裝brewinstallgit一個實用建議如果你打算長期參與開源建議用Homebrew管理Git版本。因為後續很多工具如gh、lazygit也依賴Homebrew統一管理會省去很多麻煩。1.2 WindowsWSL2是最優解沒有之一我的備用機是Windows台式機。最初我直接在Windows上安裝了Git for Windows雖然能用但體驗並不好——路徑分隔符\vs/、換行符CRLF vs LF、權限管理等問題層出不窮。踩坑1換行符之戰在Windows上提交代碼時Git會自動將LFLinux/Mac的換行符轉換為CRLFWindows的換行符。這看起來很貼心但當你的協作者使用Mac時每次合並都會出現大量「無關緊要」的差異。解決方案有兩種全局配置讓Git自動處理git config --global core.autocrlf true更徹底的方案使用WSL2推薦做法安裝WSL2 Ubuntu然後在WSL2的Linux環境中配置Git。這樣你的開發環境與服務器環境完全一致換行符、路徑、權限問題一次性解決。具體步驟以管理員身份打開PowerShell執行wsl --install重啟電腦首次啟動WSL2時設置用戶名和密碼進入WSL2終端執行sudo apt update sudo apt install git配置Git全局信息用戶名、郵箱等之後你可以用Windows Terminal同時管理PowerShell和WSL2兩個終端。開發時切換到WSL2環境體驗幾乎和Linux一模一樣。1.3 Linux最「原生」的體驗如果你使用的是Ubuntu/Debian系發行版安裝Git非常簡單sudoaptupdatesudoaptinstallgitCentOS/RHEL系sudoyuminstallgit# 或sudodnfinstallgitLinux下的Git通常是最新穩定版不需要額外配置。唯一需要注意的是部分企業內網環境可能需要配置代理才能訪問GitHub這個問題我們在第三章會詳細討論。第二章 SSH密鑰配置從「認證失敗」到「一鍵推送」2.1 為什麼要用SSH而不是HTTPS使用HTTPS方式克隆倉庫時每次git push都需要輸入用戶名和密碼或個人訪問令牌。而SSH方式配置好之後可以實現「免密推送」。踩坑2個人訪問令牌PAT的困惑GitHub從2021年8月13日起不再支持通過密碼進行Git操作。我第一次遇到Support for password authentication was removed這個錯誤時完全不知道發生了什麼。解決方案是生成一個Personal Access Token個人訪問令牌GitHub網頁右上角頭像 → Settings → Developer settings → Personal access tokens → Tokens (classic)點擊Generate new token勾選repo和workflow權限複製生成的令牌只出現一次丟失後需要重新生成然後用令牌代替密碼進行git push。但老實說每次push都輸入令牌也很煩。所以我的建議是一步到位配置SSH。2.2 生成SSH密鑰對全系統通用在終端中執行ssh-keygen-ted25519-C你的郵箱example.com這裡用ed25519算法而不是傳統的RSA因為它更安全、密鑰更短。一路回車即可不設置密碼短語也可以但建議設置一層簡單密碼。執行完成後在~/.ssh/目錄下會生成兩個文件id_ed25519私鑰絕不能洩露id_ed25519.pub公鑰需要上傳到GitHub2.3 將公鑰添加到GitHub顯示公鑰內容cat ~/.ssh/id_ed25519.pub複製輸出的全部內容GitHub網頁Settings → SSH and GPG keys → New SSH keyTitle隨便填如My MacBookKey粘貼剛才複製的公鑰點擊Add SSH key2.4 測試連接ssh-Tgitgithub.com如果看到Hi 你的用戶名! Youve successfully authenticated...恭喜SSH配置成功。踩坑3多個SSH密鑰的衝突如果你同時有GitHub和GitLab賬號或者有個人和工作兩個GitHub賬號需要配置~/.ssh/config文件# 個人GitHub Host github.com HostName github.com User git IdentityFile ~/.ssh/id_ed25519_personal # 工作GitHub Host github-work HostName github.com User git IdentityFile ~/.ssh/id_ed25519_work克隆倉庫時工作賬號用gitgithub-work:公司名/倉庫名.git而不是標準的gitgithub.com。第三章 Git核心操作新手最需要的「極簡命令集」很多教程會把Git的所有命令羅列一遍但新手真正需要的只有不到10個命令。以下是我整理的核心操作清單3.1 日常開發五步曲第一步克隆倉庫gitclone gitgithub.com:用戶名/倉庫名.gitcd倉庫名第二步創建分支# 查看當前分支gitbranch# 創建並切換到新分支gitcheckout-bfeat/你的功能描述分支命名建議feat/表示新功能fix/表示修復bugdocs/表示文檔更新。第三步修改代碼後提交# 查看修改狀態gitstatus# 添加文件到暫存區gitadd文件名# 添加單個文件gitadd.# 添加所有修改謹慎使用# 提交到本地倉庫gitcommit-m簡潔描述本次修改內容踩坑4commit message的規範我第一次提交時寫的是「update」第二次是「fix bug」第三次是「asdf」。這種message在回顧歷史時毫無意義。建議遵循約定式提交規範feat: 添加用戶登錄功能fix: 修復登錄超時導致的空指針異常docs: 更新README安裝說明refactor: 重構用戶認證模塊第四步拉取最新代碼gitpull origin main這一步在push之前執行可以避免合並衝突。第五步推送到遠程gitpush origin feat/你的功能描述3.2 遇到衝突怎麼辦衝突是Git新手最恐懼的問題但處理起來其實很簡單。場景你和同事同時修改了同一個文件的同一行代碼。當你git pull時Git會提示CONFLICT。解決步驟打開衝突文件你會看到類似這樣的標記 HEAD 你的代碼 同事的代碼 branch-name手動決定保留哪一段或兩者結合刪除、、這些標記保存文件git add 文件名git commitGit會自動生成合並提交信息git push3.3 救命級操作撤銷與回滾場景1提交完了才發現漏了一個文件gitadd漏掉的文件gitcommit--amend--no-edit這會把漏掉的文件合並到上一次提交中不改變commit message。場景2想撤銷工作區的修改還沒addgitcheckout -- 文件名場景3想撤銷暫存區的修改已經add但還沒commitgitreset HEAD 文件名場景4想撤銷最近一次提交但保留修改gitreset--softHEAD~1場景5想徹底刪除最近一次提交修改也不要了gitreset--hardHEAD~1⚠️ 這個操作不可恢復謹慎使用。第四章 開源項目入門如何找到第一個能上手的項目環境配置好了、基礎命令學會了下一步是「我該往哪裡貢獻代碼」4.1 新手友好型項目的三個特徵我在GitHub上搜索了很久總結出適合新手的項目通常具備以下特徵有明確的「good first issue」標籤GitHub官方鼓勵維護者給適合新手的問題打這個標籤貢獻指南CONTRIBUTING.md完整說明如何搭建開發環境、代碼風格要求、PR流程社區活躍但不過於龐大issue能在幾天內得到回復而不是石沉大海4.2 我推薦的三個新手項目項目一First Contributions這不是一個真正的「項目」而是一個教程性質的倉庫。它用自動化腳本引導你完成第一次PR的全流程——從fork倉庫、clone到本地、修改文件、提交、推送、創建PR。整個過程大約需要15分鐘。倉庫地址github.com/firstcontributions/first-contributions項目二Oh My Zsh如果你使用zsh作為終端這個項目是必備工具。它有大量「good first issue」且維護者對新手非常友好。倉庫地址github.com/ohmyzsh/ohmyzsh項目三freeCodeCamp這是一個非營利組織的開源項目有完整的文檔和活躍的社區。他們的issue按難度標記從「初級」到「高級」都有。倉庫地址github.com/freeCodeCamp/freeCodeCamp4.3 我的第一次PR經歷我選擇了First Contributions作為第一個目標。步驟如下Fork倉庫到自己的賬號下Clone到本地git clone gitgithub.com:我的用戶名/first-contributions.git創建分支git checkout -b add-我的用戶名在Contributors.md文件中添加自己的名字提交git commit -m feat: add 我的用戶名 to contributors list推送git push origin add-我的用戶名在GitHub網頁上點擊「Compare pull request」大約2小時後維護者合並了我的PR。雖然只修改了一行文本但那是我第一次感受到「我是開源社區的一員」。第五章 踩坑實錄那些讓我深夜抓狂的問題5.1 坑push時提示「failed to push some refs」錯誤信息! [rejected] main - main (fetch first)原因遠程倉庫有本地沒有的新提交。解決git pull --rebase origin main然後git push--rebase的作用是把你的本地提交「放在」遠程提交之後而不是創建一個無意義的合並提交。5.2 坑git clone巨慢甚至失敗原因GitHub在國內的CDN節點不穩定。解決方案1使用鏡像站點gitclone https://hub.fastgit.xyz/用戶名/倉庫名.git解決方案2配置代理如果你有gitconfig--globalhttp.proxy http://127.0.0.1:7890gitconfig--globalhttps.proxy http://127.0.0.1:7890解決方案3使用Gitee導入適合大型倉庫在Gitee上點擊「從GitHub導入」導入完成後從Gitee克隆速度會快很多。5.3 坑git push時提示「remote: Permission to … denied」原因SSH密鑰未正確關聯到GitHub賬號或者clone時用了HTTPS地址但嘗試用SSH推送。解決檢查遠程地址git remote -v如果是HTTPS地址改為SSHgit remote set-url origin gitgithub.com:用戶名/倉庫名.git5.4 坑合並時出現大量衝突但明明只改了不同文件原因換行符問題。Windows和Mac/Linux的換行符不同。解決統一配置換行符處理# 全局配置Windows用戶gitconfig--globalcore.autocrlftrue# Mac/Linux用戶gitconfig--globalcore.autocrlf input第六章 從工具到習慣給新手的幾條建議6.1 不要害怕終端很多人習慣用Git GUI工具如GitHub Desktop、Sourcetree這沒有錯。但如果你打算長期參與開源建議至少掌握終端下的基本操作。原因很簡單很多開源項目的文檔、issue評論、CI/CD日誌都是基於命令行的語境。不懂命令行相當於「只會用翻譯軟件讀外文」。6.2 學會讀錯誤信息Git的錯誤信息其實非常準確。比如fatal: not a git repository你不在一個Git倉庫目錄下rejected遠程有新提交需要先pulldetected dubious ownership文件所有者權限問題下次遇到錯誤先讀最後幾行嘗試理解它在說什麼而不是直接複製粘貼。6.3 用git log --oneline --graph替代git log這個命令會用圖形化的方式顯示提交歷史和分支關係對理解Git的內部邏輯非常有幫助。我曾經花了一個下午盯著這個輸出突然就理解了「分支只是指向某個提交的指針」這句話的含義。6.4 參與開源從文檔開始不要覺得修改代碼才是「真正的貢獻」。修復文檔中的錯別字、補充缺失的安裝步驟、翻譯英文文檔都是極其有價值的貢獻而且門檻遠低於修改代碼。很多開源項目的維護者會告訴你文檔貢獻是新手融入社區的最佳切入點。結語開源不是技術是協作寫到這裡我想起自己第一次成功提交PR時的心情——興奮、緊張、還有一點「原來我也能做到」的不真實感。開源社區之所以獨特不是因為它的代碼有多厲害而是因為它建立在一種「陌生人互相信任」的協作模式之上。你不需要有頂級學歷、不需要在大廠工作、甚至不需要寫出完美的代碼。你只需要願意嘗試、願意溝通、願意在遇到問題時先搜索再提問。這篇文章裡的所有內容都是我過去三個月裡真實踩過的坑、查過的資料、問過的問題。如果它能幫你少踩一個坑、少熬一個夜那就值了。最後如果你在配置環境或提交PR時遇到問題歡迎在AtomGit社區提問。開源的本質就是讓問題不再是「你的問題」而是「我們的問題」。本文為AtomGit春季徵稿原創作品作者保留所有權利。未經授權禁止轉載。工具版本信息Git 2.39.5 (macOS) / 2.40.1 (WSL2 Ubuntu)GitHub CLI 2.32.0測試環境macOS Sonoma 14.2 / Windows 11 WSL2 Ubuntu 22.04延伸閱讀Pro Git中文版https://git-scm.com/book/zh/v2GitHub官方文檔https://docs.github.com/zhFirst Contributions項目https://github.com/firstcontributions/first-contributions