簡介面向PyCharm初學(xué)者的Git配置圖文教程以PDF單文件方式整理幫助開發(fā)者解決在集成開發(fā)環(huán)境內(nèi)使用Git版本控制、克隆遠程倉庫與管理分支的常見困惑。包內(nèi)僅收1個PDF文檔大小僅257KB內(nèi)容緊湊適合放在手邊隨時對照練習。教程先從Git客戶端安裝與可執(zhí)行文件路徑配置入手再依次說明在PyCharm中指定git.exe、填入以.git結(jié)尾的倉庫地址完成克隆、借助藍紅黃顏色快速識別新增刪除與修改、創(chuàng)建新分支并實現(xiàn)多版本切換等關(guān)鍵操作全程配合界面截圖與演示結(jié)果步驟清晰直觀。目前已有6731人學(xué)習瀏覽特別適合剛接觸PyCharm的Python開發(fā)者和希望將代碼版本管理統(tǒng)一放進IDE的團隊新手。通過這份圖文講解讀者可以系統(tǒng)掌握從環(huán)境準備到日常提交、分支對比、推送合并的完整流程減少命令行與界面之間的頻繁切換有效提升協(xié)同開發(fā)與代碼維護效率。1. 先別急著玩界面pycharm配置git前要清楚的三件事很多人第一次做 pycharm配置git 這件事是在項目已經(jīng)寫到一半的時候裝好了PyCharm新建了項目然后在菜單欄里翻了半天找不到提交按鈕。不是PyCharm藏得深而是你得先告訴它兩件事系統(tǒng)里已經(jīng)裝了Git并且當前項目已經(jīng)納入了版本控制。這篇筆記要做的就是把這兩件事以及后續(xù)的提交、推送、分支操作全部講清楚適合剛接觸IDE和Git的開發(fā)者也適合換電腦后需要重新配置的人。全程不用記復(fù)雜命令但每個界面上你能看到的按鈕我都會告訴你它背后對應(yīng)哪條Git命令出了錯也知道去哪查。2. 配置前置裝好Git本體、填好全局身份卡住就別往下走2.1 安裝Git并驗證PATHWindows與macOS的各自細節(jié)PyCharm本身不攜帶Git它只是在界面上調(diào)用你系統(tǒng)里已經(jīng)裝好的Git可執(zhí)行文件。所以配置的第一步不是打開PyCharm而是確認系統(tǒng)里有一個能用的Git。Windows下常見的做法是用安裝包一路安裝但安裝過程中有一步下拉框非常關(guān)鍵它決定你之后在PyCharm和終端里能不能直接敲git命令。安裝到選擇組件的界面時注意看Adjusting your PATH environment這一項默認選的是Use Git from the command line and also from 3rd-party software這個選項會把Git的bin目錄寫進系統(tǒng)PATHPyCharm才能自動識別。如果你之前用的是Use Git from Git Bash only那打開PyCharm多半會報“Git not found”。安裝完成后按WinR輸入cmd在命令行里跑一句驗證git --version能看到git version 2.30.0之類輸出說明命令已經(jīng)進了PATHPyCharm識別不了就是設(shè)置面板的問題繼續(xù)看下一節(jié)。如果提示“不是內(nèi)部或外部命令”先不要懷疑安裝失敗把命令行窗口關(guān)掉重新開一次PATH才會重新加載還不行就檢查系統(tǒng)環(huán)境變量里是否有Git的bin路徑手動補一條例如C:\Program Files\Git\bin。macOS這邊簡單一些裝完Git后打開終端執(zhí)行同樣的驗證命令。macOS在第一次執(zhí)行g(shù)it時會彈系統(tǒng)對話框讓你安裝“Command Line Tools”允許后會自動裝好。屏幕提示不再是“command not found”就說明這一步過了。這里有個小習慣不論哪個系統(tǒng)裝完Git后順手分配一個提交身份避免等會兒在PyCharm里第一次提交就被卡住git config --global user.name 你的名字 git config --global user.email 你的郵箱這兩條命令分別設(shè)置了提交者的姓名和郵箱。--global表示該配置對你機器上的所有倉庫生效命令執(zhí)行后不輸出任何東西是正常的可以用git config --list查看確認。很多新手跳過這一步結(jié)果在PyCharm里點提交左下角飄紅Please tell me who you are這就是身份沒設(shè)置的表現(xiàn)。2.2 PyCharm設(shè)置面板里的兩個必經(jīng)入口Version Control與Git確認系統(tǒng)Git可用后打開PyCharm按快捷鍵CtrlAltS進設(shè)置界面在左側(cè)搜Git。這里有第一個必經(jīng)入口Settings → Version Control → Git右側(cè)頂部是Path to Git executable一般情況下PyCharm會自動填上你只需要點一下旁邊的Test按鈕彈出Git executed successfully就說明識別正常。如果這里空白手工點文件夾圖標選擇剛才安裝的git.exeWindows路徑通常在C:\Program Files\Git\cmd\git.exe。第二個入口藏在Settings → Version Control的根頁面它決定當前打開的項目是否啟用版本控制集成。很多人配置完Git路徑后回到主界面發(fā)現(xiàn)還是沒有Commit按鈕原因就是這一步項目本身沒有成功關(guān)聯(lián)到Git。正常狀態(tài)下這里會列出當前打開的項目名稱右側(cè)有一個下拉框選擇版本控制系統(tǒng)選Git確認后主界面頂部才會出現(xiàn)一排Git操作圖標。補充一個容易被忽略的入口Settings → Tools → Terminal。如果想讓PyCharm內(nèi)置終端也使用命令行Git把這里的Shell path改成Git Bash的可執(zhí)行文件路徑。Windows下早期版本需要手填C:\Program Files\Git\bin\bash.exe新版直接下拉選Git Bash即可。這個設(shè)置不影響界面操作但會影響你之后看Git輸出的原始日志建議順手配掉。到這里PyCharm和Git本體之間的通路已經(jīng)建立。下一步讓項目本身成為Git倉庫。3. 讓項目進版本庫本地倉庫初始化與遠程倉庫對接3.1 在PyCharm用VCS菜單初始化倉庫兩個入口的差異讓項目成為Git倉庫PyCharm里有兩種常見路徑。第一種適合已經(jīng)寫了一半的項目主菜單VCS → Enable Version Control Integration彈出的對話框里選擇Git點確定后項目根目錄會被標記為倉庫根目錄。第二種適合剛新建項目的場景在New Project的窗口里Version Control下拉框直接選Git項目創(chuàng)建的同時倉庫就初始化好了。兩種方式的本質(zhì)都是執(zhí)行g(shù)it init區(qū)別在于第二種會在項目模板生成階段就把.git目錄放進去后續(xù)不用再手動啟用。初始化完成后最直觀的變化在文件顏色上未被Git跟蹤的新文件顯示為紅色已跟蹤但修改過的文件變成綠色提交后恢復(fù)為白色。這是PyCharm的VCS文件狀態(tài)著色新手經(jīng)常誤以為是編碼錯誤。緊接著做一件事在項目根目錄新建.gitignore文件把不需要納入版本控制的內(nèi)容排除掉。一個Python項目最基礎(chǔ)的內(nèi)容如下__pycache__/ *.pyc .idea/ .vscode/ .env三行簡單說明PyCharm的.idea目錄存放當前機器的項目配置不同操作系統(tǒng)和不同人的PyCharm版本會生成不同內(nèi)容放進版本庫會導(dǎo)致無意義的沖突.env文件通常存數(shù)據(jù)庫密碼和密鑰進去遠程倉庫等于公開敏感信息__pycache__是運行時的字節(jié)碼緩存沒有任何版本價值。.gitignore的生效規(guī)則是在文件里寫了之后尚未被跟蹤的路徑才會被忽略如果某個文件已經(jīng)被提交過要先用git rm --cached把它從索引里挪出來這個坑會在后面避坑章詳細展開。此時回到PyCharm主界面右上角會出現(xiàn)一排圖標向下的箭頭表示拉取兩個半圓箭頭表示更新項目藍色向上箭頭表示推送。Git工具窗口從View → Tool Windows → Git打開左下角三列分別是本地變更、日志和控制臺輸出。變更列表里能看到所有未提交的文件文件右鍵有Git → Add子菜單對應(yīng)命令git add這一步是暫存別和提交搞混。3.2 添加遠程地址并完成首次推送SSH與HTTPS本地倉庫建好后還需要接上遠程倉庫否則代碼永遠只存在本機。遠程地址有兩種協(xié)議HTTPS和SSH。兩者的核心差異在鑒權(quán)方式新手常用HTTPS因為是賬號加密碼就能推但GitHub、Gitee等平臺已經(jīng)陸續(xù)改了規(guī)則密碼登錄被取消HTTPS方式必須使用Personal Access Token也就是個人訪問令牌密碼欄填的不是賬號密碼而是令牌字符串。SSH方式則走密鑰對提前生成一次密鑰之后每次推送都不用輸任何口令。在遠程平臺上新建一個空倉庫拿到地址后回到PyCharmGit → Manage Remotes打開管理窗口點加號Name填originURL粘貼倉庫地址。這對應(yīng)命令行執(zhí)行g(shù)it remote add origin gitgithub.com:你的用戶名/你的倉庫名.gitorigin只是一個約定俗成的名字表示“這是原始遠程倉庫”你可以改成別的名字但所有教程和默認操作都假定它叫origin不建議換。添加成功后首次推送在主界面點那個藍色向上箭頭PyCharm會彈一個窗口讓你選擇推送的分支默認是當前分支。強制推薦在命令行執(zhí)行一次帶參數(shù)的推送git push -u origin main-u參數(shù)的作用是把本地分支和遠程分支建立追蹤關(guān)系相當于告訴Git以后在main分支上敲git push或git pull默認對origin的main分支操作。如果不加這個參數(shù)之后每次推送都要重復(fù)寫完整分支名。執(zhí)行完這條命令本地倉庫和遠程倉庫就算是正式打通了。如果選擇SSH方式需要先生成密鑰對ssh-keygen -t ed25519 -C 你的郵箱默認會在~/.ssh下生成id_ed25519私鑰和id_ed25519.pub公鑰把公鑰內(nèi)容復(fù)制到遠程平臺的SSH Keys管理頁面。-t ed25519指定非對稱加密算法類型比傳統(tǒng)的RSA密鑰更短且更安全-C只是加一個注釋方便辨認不影響使用。生成過程會提示輸入密碼短語直接回車表示不設(shè)密碼方便日常推送。4. 日常編碼時真正高頻的四個操作提交、推送、拉取與分支4.1 Commit與Push拆開理解先落本地再上遠程遠程倉庫連接成功后每天的開發(fā)循環(huán)就是四個動作提交、推送、拉取、切分支。先講最容易混淆的一對Commit和Push。很多人以為點了提交按鈕代碼就上了遠程倉庫實際沒有。Commit的全稱是git commit它只把當前變更記錄到本地倉庫生成一個版本號Push才負責把本地版本上傳到遠程。這兩步中間隔著網(wǎng)絡(luò)完全可以只Commit不Push等代碼邏輯確認沒問題后再推送。在PyCharm里Commit的入口是右上角的Commit按鈕或者Git → Commit快捷鍵CtrlK。彈出的Commit窗口上半部分是變更文件列表每個文件右側(cè)有勾選框?qū)?yīng)git add被勾選的文件才會進入本次提交下半部分是提交信息輸入框?qū)懲晷畔⒑蟾鶕?jù)你的需要從兩個按鈕里選Commit只提交到本地Commit and Push在本地提交后緊接著彈推送對話框。我的建議是剛開始用的時候只點Commit推送單獨點這樣能看清每個動作的邊界不會因為一次誤操作把半成品代碼推上去。拉取操作對應(yīng)git pull快捷鍵CtrlT。這里有一個選項容易被忽略在PyCharm的Update Project對話框里有兩個單選Update直接合并遠程變更Update (Rebase)先把本地未推送的提交暫存起來再合并遠程變更最后把暫存的提交補上去。日常開發(fā)選Rebase能讓提交記錄是一條直線可讀性好很多。但要注意Rebase會改寫提交歷史如果這條分支已經(jīng)推送到遠程并且其他同事在用別用Rebase否則會讓人家倉庫里的歷史和你對不上最后只能做強制推送收場。每次提交前記得在Commit窗口里看一下變更列表確認沒有.idea/workspace.xml這類本地偏好文件和密鑰文件混進來。這種誤提交在避坑章里會作為重點踩坑記錄講。4.2 分支的創(chuàng)建、切換與合并在主面板完成不等于不用命令行分支是多人協(xié)作里繞不開的操作。PyCharm底部狀態(tài)欄右側(cè)有一個顯示當前分支名的區(qū)域比如main點它會彈出所有本地分支列表這就是分支操作的主入口。創(chuàng)建新分支在彈出菜單里選New Branch輸入分支名PyCharm會自動切換過去這對應(yīng)兩條命令git branch 分支名和git checkout 分支名實際上新版Git更推薦用git switch但PyCharm界面里看不到區(qū)別你只需要知道它同時完成了創(chuàng)建和切換兩個動作。日常開發(fā)的規(guī)范分支名通常帶類型前綴比如feature/login-page、fix/bug-1023。分支名里用斜杠分組是Git官方推薦的約定不是必須但團隊協(xié)作時能一眼看出分支用途。切換分支在PyCharm里同樣是點擊底部狀態(tài)欄分支名選擇目標分支快捷鍵CtrlShiftBackspace可以快速回跳上一次所在分支這在我臨時切去修線上bug時非常好用。分支合并的入口在Git → Branches → 選擇要被合并的分支 → Merge into Current。比如當前在main分支上要合并feature/login-page就選這個feature分支然后點Merge into Current。這里有一個關(guān)鍵心理預(yù)設(shè)合并不是把分支里的文件復(fù)制過來而是把兩個分支的提交歷史做一次合并所以會產(chǎn)生一個新的合并提交。如果當前分支和待合并分支同時改了同一個文件的同一行PyCharm會彈沖突對話框左側(cè)是當前版本右側(cè)是分支版本中間是合并結(jié)果預(yù)覽。逐處處理沖突后點Apply提交信息會默認寫成Merge branch feature/login-page保留默認即可不要為了好看刪掉。分支操作里最容易翻車的是在主分支上直接改代碼。記住一條原則——main或master分支永遠保持可發(fā)布狀態(tài)新功能代碼一律在feature分支里寫測好了再合并回來。如果團隊只有你一個開發(fā)者這條原則同樣適用因為它是Git工作流的根基不是有沒有人協(xié)作的問題。5. 避坑指南PyCharm配Git繞不開的5個坑5.1 “Git is not a valid command”不是Git裝錯了是PATH沒對上現(xiàn)象PyCharm設(shè)置面板里Test按鈕變紅提示Git is not a valid command但系統(tǒng)終端里git --version正常運行。原因PyCharm進程在啟動時繼承了當時的環(huán)境變量。如果你在PyCharm打開之后才安裝Git或修改PATHIDE里的環(huán)境變量不會自動刷新所以它找不到git可執(zhí)行文件。另一個常見原因是PyCharm是綠色版或免安裝版沒有經(jīng)過安裝器的環(huán)境變量廣播。解決首先是重啟PyCharm讓它重新讀取系統(tǒng)環(huán)境變量無效就在Settings → Version Control → Git里手動指定可執(zhí)行文件路徑不用靠自動檢測。Windows下填C:\Program Files\Git\cmd\git.exemacOS下可以用終端查出路徑which git的輸出結(jié)果原樣填進去。注意不要填成了bash路徑要的是git主程序。5.2 Push被拒遠Failed to push some refs現(xiàn)象點擊Push后Git工具窗口控制臺里報錯第一行寫著Failed to push some refs to緊跟著一句Updates were rejected because the remote contains work that you do not have locally。原因遠程倉庫的提交歷史領(lǐng)先于本地也就是說在你上次Pull之后別人往遠程倉庫推送了新提交Git出于安全考慮拒絕用一個“過時”的本地歷史覆蓋遠程歷史。新手最常見的誤操作是在這個提示出來后直接勾選Force Push這會讓遠程倉庫丟棄那些遠程獨有的提交如果那些提交是同事的代碼后果就是協(xié)作歷史被抹掉。解決先CtrlT拉取遠程變更PyCharm會彈Update Project對話框選擇Update (Rebase)等它把遠程提交和本地未推送提交整合成一條干凈的歷史再重新Push。如果拉取過程中出現(xiàn)沖突用合并對話框逐處解決。這里面有個值得記住的原則非緊急情況永遠不使用Force Push它一旦執(zhí)行遠程歷史被覆蓋有能力找回的人只有平臺管理員。5.3 提示輸入Password或Token填了賬號密碼就是登不進現(xiàn)象用HTTPS方式Clone或Push時彈出一個憑據(jù)窗口要求輸入Password或Token輸入平臺賬號密碼之后反復(fù)提示認證失敗。原因主流的代碼托管平臺已經(jīng)全面取消賬號密碼的HTTPS認證改用Personal Access Token也就是個人訪問令牌。這個Token不是拿來登錄網(wǎng)頁的是作為密碼填進Git憑據(jù)窗口里的。很多人在這個窗口填了平臺登錄密碼Git拿它去認證服務(wù)端只認Token雙方對不上自然失敗。解決到托管平臺里生成一個新的訪問令牌生成時勾選repo權(quán)限把生成的字符串復(fù)制粘貼到憑據(jù)窗口的Password欄用戶名照填。另一種一勞永逸的解法是切換SSH協(xié)議只要在倉庫管理窗口把URL從https://開頭換成git開頭即自動切換成密鑰認證之后再也見不到這個憑據(jù)窗口。如果是已有倉庫用Git → Manage Remotes直接把URL改掉就行注意改動后要重新git fetch一次確認連通。5.4 切換分支后代碼“消失”不是丟了是藏在沒提交的變更里現(xiàn)象當前分支上有幾個改過的文件右下角分支名點了一下切到另一個分支切回來后發(fā)現(xiàn)改動的代碼不見了文件內(nèi)容恢復(fù)成了改動前版本嚇出一身冷汗。原因Git切換分支時會清空工作區(qū)里已跟蹤文件的未提交改動因為那些改動本質(zhì)上是基于原分支的不能帶到新分支。PyCharm在切換前會彈一個Uncommitted Changes窗口提示你有未提交變更很多人在彈窗里選了Force Checkout這個選項會丟棄這些未提交的改動代碼就從工作區(qū)消失了。解決不是完全沒有后悔藥。如果只是丟棄了一兩個文件可以右鍵文件目錄Git → Local History → Show HistoryPyCharm的本地歷史里還保存著最近幾小時內(nèi)的文件快照能找回大部分內(nèi)容。但真正的習慣是防止這個場景發(fā)生在切換分支前要么先Commit把臨時提交留在原分支要么右鍵變更列表Git → Stash Changes把改動暫存到一個叫stash的坑位里切回來后再Git → Unstash Changes取回。Stash對應(yīng)命令行里的git stash和git stash pop是保護未提交代碼最標準的方式。從這次翻車之后我的習慣是切分支前先瞄一眼Git工具窗口里有沒有紅色的未提交變更有就先處理絕不給Force Checkout出場機會。5.5 大文件推不上去LFS不是插件是遠程倉庫的協(xié)議配合現(xiàn)象項目里加了一個數(shù)據(jù)集或設(shè)計資源壓縮包幾百MBPush時卡在傳輸階段或者直接報錯說遠程倉庫超出文件大小限制。原因托管平臺的普通Git倉庫一般不歡迎大文件Git本身的傳輸協(xié)議對大文件也不友好因為它要把每個文件的所有歷史版本完整存下來一個1GB的文件改十次倉庫體積就接近10GB服務(wù)端和本地都會爆炸。這是Git的設(shè)計邊界不是PyCharm的故障。解決常見做法是引入Git LFS即Large File Storage大文件存儲方案。它的原理是用指針對大文件做輕量引用真實文件存放在獨立的存儲區(qū)。在項目倉庫里先把需要托管的大文件類型寫進.gitattributes*.zip filterlfs difflfs mergelfs -text *.ipk filterlfs difflfs mergelfs -text然后執(zhí)行一次git lfs install初始化鉤子。執(zhí)行完后后續(xù)Commit這個大文件時Git會自動走LFS通道。推不上去時要留意遠程倉庫的LFS配額這是平臺側(cè)的限制和本機配置無關(guān)。還有一條經(jīng)驗除非這個文件必須讓每個協(xié)作者都完整下載否則優(yōu)先考慮不放倉庫用網(wǎng)盤或內(nèi)部文件服務(wù)分發(fā)LFS只用來存儲真正繞不開的構(gòu)建產(chǎn)物。5.6 換電腦后SSH密鑰失效拷的不是文件是配套關(guān)系現(xiàn)象新電腦上打開PyCharm拉取或推送時提示Permission denied (publickey)明明在舊電腦上推送一直正常。原因公鑰和私鑰是成對的。換電腦后只復(fù)制了項目代碼沒有復(fù)制~/.ssh目錄下的私鑰文件或者把公鑰粘貼到了遠程平臺但本地沒有對應(yīng)的私鑰服務(wù)端校驗永遠過不了。另一個隱蔽原因是新電腦的全局身份沒配置提交記錄里的作者信息變成了未知用戶遠程平臺拒絕關(guān)聯(lián)。解決最快的解法是把舊電腦~/.ssh下的id_ed25519和id_ed25519.pub兩個文件一起拷到新電腦同樣的目錄下同時確認遠程平臺里存的是同一個公鑰如果公鑰在平臺上有變動用新的公鑰重新注冊。然后在新電腦上執(zhí)行ssh-agent -s ssh-add ~/.ssh/id_ed25519ssh-add的作用是把私鑰加載到ssh-agent進程里有些發(fā)行版開機不會自動加載導(dǎo)致Git調(diào)用SSH協(xié)議時找不到私鑰。做完后可以用ssh -T gitgitee.com或?qū)?yīng)平臺域名測試鏈路顯示歡迎語即代表通了。換電腦后建議順手復(fù)查git config --global user.email確保和平臺賬號一致很多提交被處理成Anonymous Author的案例查到最后都是這里漏了。6. 配置完成后自己做一次全鏈路驗證從改一行代碼到回滾到上一個版本到這里環(huán)境已經(jīng)全部打通但配置是否真的可靠我建議用一個完整的鏈路自測一遍全程十分鐘。這一步驗證的是IDE下的Git集成也順帶建立你對整個流程的肌肉記憶。實踐路徑在PyCharm中打開項目到項目根目錄新建一個文件命名為check_git.py輸入一行代碼并保存。打開Git → Commit勾選這個新文件填寫提交信息test: check git config點Commit。隨后右鍵項目根目錄選擇Git → Repository → Push把提交推到遠程倉庫。接著模擬一次還原操作把該文件的內(nèi)容改成另一行代碼再次提交并推送然后在Git → Log里選中上一次提交記錄右鍵選擇Reset Current Branch to Here在彈出對話框里選Soft模式PyCharm會把這個倉庫回滾到上一個提交的快照狀態(tài)你新增的那次提交不會丟失它還在Log歷史里只是當前分支指針指了回來?；貪L操作里三個模式的區(qū)別值得記住Soft保留所有改動在工作區(qū)相當于撤銷了提交但代碼改動還在Mixed保留改動但移出暫存區(qū)Hard直接丟棄改動文件恢復(fù)到當時的狀態(tài)。日常操作里我?guī)缀醪挥肏ard它沒有后悔藥真用的時候只在確認代碼無用并已備份的情況下用。最后在PyCharm底部狀態(tài)欄的分支名上右鍵選擇Show History或者打開Git工具窗口切到Log標簽頁你剛才的操作以圖形化時間線方式展開在列表里每一行對應(yīng)真實提交哈希值。對照一下提交說明和時間能看到整個鏈路是通的說明從Git安裝、身份配置、倉庫初始化到遠程對接的每一步都正確落位了。我自己的習慣是每次換電腦或換IDE后都先跑一遍這套驗證跑完才敢把舊環(huán)境的任務(wù)遷移過來。這套驗證同樣適合作為新同事接手代碼前的熱身操作因為一次成功的全流程跑通比任何配置文檔都有說服力。希望幫到你。本文還有配套的精品資源點擊獲取