GitHub CLI 教學：高效的開發工作流程

--- lang: zh-tw tags: git, GitHub, CLI, 命令列介面, 版本控制 description: 這篇教學介紹如何使用GitHub CLI工具提高開發效率，包含從安裝到高級工作流程的詳細說明和視覺化流程圖。 --- # GitHub CLI 教學：高效的開發工作流程 [TOC] :::info 關於本教學本教學適合想要透過命令列提升GitHub工作效率的開發者，從基礎功能到進階工作流程都有涵蓋。 ::: ## 引言 **GitHub命令列工具（GitHub CLI）** 是提升開發工作流程效率的絕佳工具。透過命令列介面操作GitHub，您可以更快、更有條理地管理專案，無需頻繁切換至瀏覽器界面。本教學將帶您了解GitHub CLI的主要功能和實用工作流程。 ## 安裝與設置要開始使用GitHub CLI，首先需要安裝它： :::spoiler 各平台安裝命令 **macOS (使用Homebrew)**: ```bash brew install gh ``` **Windows (使用Scoop)**: ```bash scoop install gh ``` **Linux (Debian/Ubuntu)**: ```bash sudo apt install gh ``` 安裝後，您需要進行驗證： ```bash gh auth login ``` ::: 遵照螢幕上的指示，選擇通過瀏覽器或令牌（token）進行身份驗證。 ## 基本命令介紹 GitHub CLI使用`gh`作為主命令，後接不同的子命令執行各種操作： :::spoiler 常用指令類別 | 指令 | 功能 | | ---- | ---- | | `gh repo` | 倉庫管理 | | `gh issue` | 問題追蹤 | | `gh pr` | 拉取請求操作 | | `gh release` | 版本發布 | | `gh gist` | 代碼片段管理 | ::: 每個命令都有自己的子命令和選項，可以通過`gh help [command]`獲取幫助。 ## 實用使用案例讓我們看一些實際使用案例，幫助您更好地理解GitHub CLI在日常開發中的應用： :::info 以下案例展示了GitHub CLI如何在各種場景中幫助您提高工作效率。 ::: ### 案例1：快速複製並參與開源專案想要貢獻某個開源專案？GitHub CLI可以讓這個過程變得簡單： :::spoiler 快速參與開源專案的命令 ```bash # 複製倉庫並自動在您的帳號創建fork gh repo fork cli/cli # 自動為您設置遠端倉庫，無需手動配置 # 如果只想創建fork但不clone到本地 gh repo fork cli/cli --clone=false # 創建分支並開始工作 git checkout -b feature-branch # 完成工作後，直接從命令行提交PR gh pr create --title "實現新功能" --body "解決了#123問題" ``` ::: 這個流程讓您無需在瀏覽器和終端間切換，顯著提高效率。 ### 案例2：快速查看和管理專案狀態需要快速了解專案中的問題和拉取請求？ :::spoiler 專案狀態查詢命令 ```bash # 列出所有開放的PR gh pr list # 查看特定PR的詳細信息 gh pr view 21 # 列出分配給您的issue gh issue list --assignee @me # 查看特定issue的詳細信息和評論 gh issue view 13 --comments ``` ::: ### 案例3：團隊協作和代碼審查 :::success GitHub CLI提供強大的代碼審查功能，讓團隊協作更高效！ ::: :::spoiler 代碼審查相關命令 ```bash # 檢出同事的PR到本地，進行審查 gh pr checkout 15 # 在終端中查看PR的差異 gh pr diff # 直接在命令行中批准PR gh pr review 15 --approve # 或者提出評論和修改建議 gh pr review 15 --comment -b "請考慮優化這部分的性能" ``` ::: ### 案例4：自動化工作流程整合將GitHub CLI整合到您的自動化腳本中： :::spoiler 自動化工作流程命令 ```bash # 創建新版本發布 gh release create v1.0.0 --title "第一個穩定版本" --notes "修復了多個bug和性能優化" # 監控GitHub Actions工作流程 gh run list # 等待特定工作流程完成 gh run watch ``` ::: 這些使用案例展示了GitHub CLI如何在各種場景中幫助您提高工作效率。 ## 分支保護設置在使用GitHub CLI之前，建議先設定分支保護規則，確保工作流程的安全性： :::warning 沒有適當的分支保護設置，可能導致團隊成員意外直接推送至主分支。 ::: 1. 在GitHub網站上導航至您的倉庫 2. 點擊「Settings」→「Branches」 3. 點擊「Add rule」為主分支（通常是`main`）添加保護規則 4. 建議的設置： - 勾選「Require a pull request before merging」 - 勾選「Require approvals」（團隊協作時） - 勾選「Require status checks to pass before merging」 - 勾選「Do not allow bypassing the above settings」這些設置將防止直接推送到主分支，確保所有變更都經過PR流程審核。 ## 工作流程教學：從issue到PR到合併 GitHub CLI支持完整的開發工作流程，下面是一個典型範例： ### 步驟1：創建Issue 每個新功能或修復都從創建issue開始： :::spoiler Issue創建命令 ```bash gh issue create -t "添加新功能：使用者註冊" -b "實現使用者註冊功能，包括表單和驗證" ``` 或者使用交互模式： ```bash gh issue create ``` ::: 系統會提示您輸入標題、描述和其他詳細信息。 ### 步驟2：從Issue創建開發分支這是GitHub CLI的強大功能之一，您可以直接從issue創建並切換到新分支： :::spoiler 從Issue創建分支 ```bash gh issue develop [issue編號] -c ``` ::: 這個命令會： - 創建一個基於issue標題的新分支 - 將分支與issue關聯 - 自動切換到新分支現在您可以開始編寫代碼了！ ### 步驟3：提交更改並推送完成工作後，提交您的更改： :::spoiler 提交與推送命令 ```bash git add . git commit -m "添加使用者註冊功能" git push -u origin HEAD ``` ::: ### 步驟4：創建PR 使用GitHub CLI創建PR： :::spoiler PR創建命令 ```bash gh pr create ``` 系統會提示您輸入標題（默認使用提交信息）和描述。您也可以使用`-d`標記創建草稿PR： ```bash gh pr create -d ``` ::: 草稿PR表示工作仍在進行中，尚未準備好審核。 ### 步驟5：將草稿PR標記為準備就緒當您的工作完成並準備好審核時： :::spoiler 將PR標記為準備就緒 ```bash gh pr ready ``` ::: ### 步驟6：審核和合併PR 查看PR的狀態： :::spoiler PR審核與合併命令 ```bash gh pr view ``` 合併PR（如果您有權限）： ```bash gh pr merge ``` ::: 您可以選擇合併方式（標準合併、壓縮合併或變基合併）。 ## GitHub工作流程視覺化指南以下使用Mermaid圖表視覺化展示GitHub完整工作流程，從初次提交到分支開發、合併與發布： ### 初始化倉庫與首次提交 ```mermaid flowchart TB A[開始專案] --> B["初始化本地倉庫 git init"] B --> C["建立必要檔案 echo '# 專案名稱' > README.md echo '初始版本' > CHANGELOG.md"] C --> D["添加檔案 git add README.md CHANGELOG.md .gitignore"] D --> E["首次提交 git commit -m '初始提交: 建立專案結構'"] E --> F["創建遠端倉庫 gh repo create my-project --public --source=."] F --> G["推送至遠端 git push -u origin main"] style A fill:#f9f,stroke:#333,stroke-width:2px style G fill:#bbf,stroke:#333,stroke-width:2px ``` :::spoiler 查看詳細實現代碼 ```bash # 初始化本地倉庫 git init # 建立忽略檔案 (最佳實踐) cat > .gitignore << 'EOF' # 依語言自動生成適合的 .gitignore # 可訪問 https://gitignore.io/ 獲取適合您專案的內容 node_modules/ *.log .DS_Store .env EOF # 添加文件 echo "# 我的專案" > README.md echo "初始版本" > CHANGELOG.md git add README.md CHANGELOG.md .gitignore # 首次提交 git commit -m "初始提交: 建立專案結構" # 使用GitHub CLI創建遠端倉庫 (推薦選項) gh repo create my-project \ --public \ # 公開倉庫，使用 --private 創建私有倉庫 --description "我的新專案描述" \ # 添加描述 --homepage "https://myproject.com" \ # 可選的主頁 --source=. \ # 使用當前目錄作為源 --remote=origin \ # 設置遠端名稱 --gitignore Node # 自動添加語言特定的.gitignore (可選) # 如果需要添加授權文件 gh repo edit --add-license mit # 添加MIT授權 # 推送至遠端 git push -u origin main # 或 git push -u origin master 若使用舊版Git # 驗證倉庫創建成功 gh repo view --web # 在瀏覽器中打開倉庫 # 常見問題解決： # 如果遇到分支名稱問題 (master 與 main) git branch -M main # 將當前分支重命名為main ``` ::: **建議選項與最佳實踐：** :::info - 使用有意義的倉庫名稱和描述，方便他人理解專案目的 - 建立 `.gitignore` 文件排除不需要版本控制的檔案 - 添加 `LICENSE` 和詳細的 `README.md` 說明專案用途和使用方法 ::: 使用結構化格式獲取倉庫資訊： ```bash gh repo view --json name,description,visibility,defaultBranchRef ``` 創建私有倉庫時添加協作者： ```bash gh repo create --private my-project gh repo add-collaborator my-project username --permission admin ``` ### 開發分支與Bug修復流程 ```mermaid flowchart TB A["主分支 git checkout main git pull"] --> B["建立問題 gh issue create -t '修復登入問題'"] B --> C["創建分支 gh issue develop issue編號 -c"] C --> D["修改代碼 (編輯相關檔案)"] D --> E["提交修復 git add . git commit -m '修復登入問題'"] E --> F["推送分支 git push -u origin HEAD"] F --> G["創建PR gh pr create --title '修復登入問題'"] G --> H{"需要修改?"} H -- 是 --> I["審查反饋 gh pr view --comments"] I --> J["修改代碼 (根據反饋修改)"] J --> K["提交修改 git commit -am '根據審查調整' git push"] K --> H H -- 否 --> L["合併PR gh pr merge --squash"] L --> M["清理分支 git checkout main git pull git branch -d bugfix-branch"] style A fill:#bbf,stroke:#333,stroke-width:2px style M fill:#bbf,stroke:#333,stroke-width:2px ``` :::spoiler 使用GitHub CLI實現完整修復流程 ```bash # 確保main分支最新 git checkout main git pull # 創建並切換到bugfix分支 gh issue create -t "修復登入問題" -b "使用者無法在Safari瀏覽器登入" gh issue develop $(gh issue list --limit 1 --json number --jq '.[0].number') -c # 設置分支追踪 (可選，方便後續操作) git branch --set-upstream-to=origin/main # 修復問題並提交 # (進行必要的代碼修改) git add . git commit -m "修復Safari登入問題" -m "詳細描述問題原因和解決方案" # 遇到衝突時如何解決 # git fetch origin main # git rebase origin/main # (解決衝突後) # git rebase --continue # 推送分支到遠端 git push -u origin HEAD # 創建PR (完整選項) gh pr create \ --title "修復Safari登入問題" \ --body "解決issue #1中描述的Safari登入問題" \ --assignee @me \ # 分配給自己 --label "bug,urgent" \ # 添加標籤 --milestone "v1.0" \ # 指定里程碑 --reviewer teammate1,teammate2 # 請求審核 # 檢查PR狀態 gh pr status # 追蹤PR評論 gh pr view --comments # 修改PR以回應審查意見 # (進行修改後) git add . git commit -m "根據審查意見調整" git push # 等待審查後合併PR (多種選項) gh pr merge \ --squash \ # 壓縮合併，或使用 --merge/--rebase --delete-branch \ # 合併後刪除分支 --body "包含所有必要修復" # 自定義合併信息 # 同步本地環境 git checkout main git pull git branch -d bugfix-login-issue # 如果忘記刪除遠端分支 # gh pr list -s merged # 列出已合併的PR # gh pr view <number> # 查看特定PR # git push origin --delete <branch-name> # 手動刪除遠端分支 ``` ::: **重要提示與最佳實踐：** - 使用有意義的分支名稱，推薦格式: `<類型>/<描述>`，例如 `bugfix/safari-login` - 提交詳細的PR描述，使用模板： :::spoiler PR描述模板 ```markdown ## 問題描述簡要說明問題 ## 解決方案如何解決 ## 測試方法如何驗證修復 Fixes #1 ``` ::: - 定期從主分支同步變更，避免大型合併衝突 - 使用 `gh pr ready` 標記草稿PR為可審核狀態 - 利用GitHub CLI監控CI/CD狀態: `gh run list --workflow=ci.yml` ### 版本發布流程 ```mermaid flowchart TB A["同步最新代碼 git checkout main git pull"] --> B["確保測試通過 npm test"] B --> C["更新版本號 npm version patch 或手動更新package.json"] C --> D["更新變更日誌 更新CHANGELOG.md"] D --> E["提交版本更新 git add . git commit -m '版本提升至 v1.0.0' git push"] E --> F["創建標籤 git tag -a v1.0.0 -m '穩定版發布' git push origin v1.0.0"] F --> G["發布版本 gh release create v1.0.0 --title 'v1.0.0 穩定版發布' --notes-file CHANGELOG.md"] G --> H["添加發布資產 gh release upload v1.0.0 ./dist/app.zip"] style A fill:#f9f,stroke:#333,stroke-width:2px style H fill:#bbf,stroke:#333,stroke-width:2px ``` :::spoiler 使用GitHub CLI實現發布流程 ```bash # 確保在main分支上並同步最新變更 git checkout main git pull # 建立版本標籤的不同方式 # 方式1: 使用語義化版本標籤 VERSION="1.0.0" echo "當前版本: $VERSION" # 更新版本號（示例：在package.json中） # 方式1: 手動編輯 # 方式2: 使用npm工具 (Node.js項目) npm version patch --no-git-tag-version # 小版本更新 # 方式3: 使用jq工具 (通用方法) jq '.version = "1.0.0"' package.json > tmp && mv tmp package.json # 更新CHANGELOG.md (最佳實踐) cat > CHANGELOG.md << 'EOF' # 更新日誌 ## [1.0.0] - $(date +%Y-%m-%d) ### 新功能 - 實現使用者註冊 - 新增發布通知功能 ### 修復 - 修復Safari登入問題 - 解決移動裝置顯示錯誤 EOF # 提交版本更新 git add package.json CHANGELOG.md git commit -m "版本提升至 v1.0.0" git push # 創建發布標籤 git tag -a v1.0.0 -m "v1.0.0 穩定版發布" git push origin v1.0.0 # 使用GitHub CLI創建完整發布 (多樣選項) gh release create v1.0.0 \ --title "v1.0.0 穩定版發布" \ --notes-file CHANGELOG.md \ # 使用CHANGELOG作為發布說明 --discussion-category "公告" \ # 創建討論主題 --target main \ # 指定目標分支 --verify-tag # 驗證標籤存在 # 可選: 添加發布資產 gh release upload v1.0.0 ./dist/app.zip ./docs/user-guide.pdf # 可選: 發布後的維護操作 # 更新專案依賴 # npm update --save # git add package.json package-lock.json # git commit -m "更新專案依賴" # git push # 檢視並驗證發布 gh release view v1.0.0 gh release view v1.0.0 --web # 在瀏覽器中查看發布頁面 ``` ::: **版本發布最佳實踐建議：** :::success - 使用[語義化版本控制](https://semver.org/lang/zh-TW/)規範（MAJOR.MINOR.PATCH） - MAJOR: 不兼容的API變更 - MINOR: 向下兼容的功能新增 - PATCH: 向下兼容的問題修復 - 維護詳細的CHANGELOG文件，記錄每個版本的更改 - 發布前進行完整測試，確保所有CI流程通過 ::: 為發布添加詳細文檔和使用示例: - 使用預發布版本進行測試： ```bash gh release create v1.0.0-beta.1 --prerelease --title "v1.0.0 Beta 1" ``` - 設置自動化發布流程，利用GitHub Actions： :::spoiler GitHub Actions發布工作流程 ```yaml name: Release on: push: tags: ['v*'] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - run: npm ci - run: npm test - uses: softprops/action-gh-release@v1 ``` ::: 這個視覺化工作流程展示了使用GitHub CLI管理整個軟體開發生命週期的方式，從初始化專案到功能開發、bug修復，再到版本發布。通過遵循這些步驟和使用GitHub CLI，您可以顯著提高團隊協作效率和代碼質量。 ## 進階技巧：draft PR和PR驅動開發 ### 使用草稿PR進行迭代開發草稿PR非常適合用於長期持續開發的任務： :::info 草稿PR工作流程 1. 創建草稿PR以早期獲取反饋 2. 持續在分支上工作並推送更新 3. 團隊成員可以實時跟踪和評論您的工作 4. 當準備就緒時，將PR標記為可審核 ::: 這種方法的優點： - 保持工作透明度 - 提早發現潛在問題 - 避免大型PR帶來的審核困難 - 為長期工作保留開發記錄 ### 多分支平行開發當您同時處理多個功能時： :::info 平行開發策略 1. 為每個功能創建單獨的issue 2. 從每個issue創建開發分支 3. 使用草稿PR跟踪每個功能的開發進度 4. 在不同分支間切換：`gh pr checkout [PR編號]` ::: 當某個功能開發完成時，將其PR標記為可審核並合併，而不影響其他正在進行的工作。 ## 總結與建議 GitHub CLI是一個強大的工具，能夠顯著提升您的開發工作流程效率： :::success - 使用issue追踪任務和功能開發 - 遵循分支保護和PR流程，維護代碼質量 - 利用草稿PR進行透明的迭代開發 - 熟練使用GitHub CLI命令，減少上下文切換 ::: 最佳實踐： - 為每個任務創建issue - 保持PR規模小且集中 - 定期提交和推送更改 - 使用有意義的提交信息和PR描述 - 鼓勵團隊成員進行早期和持續的代碼審核通過熟練運用GitHub CLI和這些工作流程，您可以建立更有組織、更高效的開發過程，無論是個人專案還是團隊協作。 ## 常用命令參考 :::spoiler 常用命令速查表 ```bash # 倉庫操作 gh repo create # 創建新倉庫 gh repo clone [倉庫] # 克隆倉庫 gh repo view # 查看當前倉庫信息 # Issue操作 gh issue list # 列出issue gh issue create # 創建issue gh issue view [編號] # 查看issue詳情 gh issue develop [編號] # 從issue創建開發分支 # PR操作 gh pr create # 創建PR gh pr list # 列出PR gh pr view [編號] # 查看PR詳情 gh pr checkout [編號] # 檢出PR分支 gh pr ready # 將草稿PR標記為準備就緒 gh pr merge # 合併PR # 瀏覽器整合 gh browse # 在瀏覽器中打開當前倉庫 gh pr view --web # 在瀏覽器中查看PR # 其他實用命令 gh run list # 列出工作流程運行 gh release create # 創建發布 gh gist create # 創建代碼片段 ``` ::: ## 參考資料 1. [GitHub CLI官方文檔 - Examples](https://cli.github.com/manual/examples) 2. [GitHub CLI官方快速入門](https://docs.github.com/zh/github-cli/github-cli/quickstart) 3. [GitHub CLI - 將GitHub帶入命令行](https://developer.aliyun.com/article/1627855) 4. [GitHub CLI命令行工具(gh) - 知乎專欄](https://zhuanlan.zhihu.com/p/601200139) --- 希望本教學能幫助您提升GitHub工作流程效率！