第五章：遠端倉庫與團隊協作 - 連接世界的橋樑

到目前為止，我們所有的 Git 操作都在本地進行。但 Git 真正的威力在於它的分散式特性 – 能夠與世界各地的開發者協作。今天我們要學習如何與遠端倉庫互動，這是從個人開發者轉變為團隊協作者的關鍵一步。

什麼是遠端倉庫？

遠端倉庫就像是程式碼的「雲端備份」，但功能遠不止於此。它是團隊協作的中央樞紐，讓多個開發者能夠分享和整合彼此的工作成果。

想像遠端倉庫是一個共同的圖書館，每個開發者都可以：

借閱最新的「書籍」（拉取程式碼）
貢獻新的「章節」（推送變更）
查看其他人的「筆記」（查看提交歷史）
討論內容（透過 Pull Request）

常見的遠端倉庫托管平台包括：

GitHub：最大的程式碼託管平台
GitLab：提供完整的 DevOps 解決方案
Bitbucket：Atlassian 生態系的一部分
Azure DevOps：微軟的企業解決方案

遠端倉庫的核心概念

Origin 和 Upstream

# origin：你 fork 或 clone 的來源
# upstream：原始專案的倉庫（如果你是從別人的專案 fork 的）

git remote -v

典型的輸出：

origin    https://github.com/yourusername/project.git (fetch)
origin    https://github.com/yourusername/project.git (push)
upstream  https://github.com/originalowner/project.git (fetch)
upstream  https://github.com/originalowner/project.git (push)

追蹤分支

追蹤分支是本地分支與遠端分支之間的連結：

# 查看追蹤關係
git branch -vv

輸出範例：

* main                    a1b2c3d [origin/main] 最新的提交訊息
  feature/user-login      e4f5g6h [origin/feature/user-login: ahead 2] 功能開發中
  hotfix/critical-bug     h7i8j9k 緊急修復分支

說明：

[origin/main]：與遠端同步
[origin/feature/user-login: ahead 2]：本地領先遠端 2 個提交
hotfix/critical-bug：沒有設定追蹤分支

複製遠端倉庫

基本複製操作

# HTTP 方式（推薦給初學者）
git clone https://github.com/username/repository.git

# SSH 方式（推薦給日常使用）
git clone git@github.com:username/repository.git

# 指定本地資料夾名稱
git clone https://github.com/username/repository.git my-project

# 只複製特定分支
git clone -b develop https://github.com/username/repository.git

# 淺層複製（不包含完整歷史，適合大型專案）
git clone --depth 1 https://github.com/username/repository.git

複製後的自動設定

當你複製倉庫時，Git 自動：

# 1. 設定 origin 遠端
git remote add origin https://github.com/username/repository.git

# 2. 設定本地 main 分支追蹤 origin/main
git branch --set-upstream-to=origin/main main

# 3. 切換到預設分支
git switch main

SSH 金鑰設定 – 無密碼操作的關鍵

SSH 金鑰讓你可以安全地與遠端倉庫互動，無需每次輸入密碼。這是專業開發者的必備設定。

檢查現有的 SSH 金鑰

# 查看是否已有 SSH 金鑰
ls -la ~/.ssh

# 常見的金鑰檔案名稱
# id_rsa, id_rsa.pub (RSA)
# id_ed25519, id_ed25519.pub (Ed25519, 推薦)
# id_ecdsa, id_ecdsa.pub (ECDSA)

生成新的 SSH 金鑰

# 使用 Ed25519 算法（推薦）
ssh-keygen -t ed25519 -C "your.email@example.com"

# 如果系統不支援 Ed25519，使用 RSA
ssh-keygen -t rsa -b 4096 -C "your.email@example.com"

執行後會看到：

Generating public/private ed25519 key pair.
Enter a file in which to save the key (/Users/username/.ssh/id_ed25519): 
Enter passphrase (empty for no passphrase): 
Enter same passphrase again:

建議：

檔案位置：使用預設位置
密碼短語：可以設定，增加安全性（雖然會需要輸入密碼）

將 SSH 金鑰加入到 SSH Agent

# 啟動 SSH Agent（macOS/Linux）
eval "$(ssh-agent -s)"

# 加入私鑰到 SSH Agent
ssh-add ~/.ssh/id_ed25519

# macOS 用戶可以加入到鑰匙圈
ssh-add --apple-use-keychain ~/.ssh/id_ed25519

複製公鑰到剪貼簿

# macOS
pbcopy < ~/.ssh/id_ed25519.pub

# Linux
xclip -selection clipboard < ~/.ssh/id_ed25519.pub

# Windows (Git Bash)
clip < ~/.ssh/id_ed25519.pub

# 或直接查看內容
cat ~/.ssh/id_ed25519.pub

將公鑰加入到 GitHub

登入 GitHub
點選右上角頭像 → Settings
左側選單選擇 “SSH and GPG keys”
點選 “New SSH key”
輸入標題（例如：工作筆電）
貼上公鑰內容
點選 “Add SSH key”

測試 SSH 連線

# 測試 GitHub 連線
ssh -T git@github.com

# 成功的輸出
Hi username! You've successfully authenticated, but GitHub does not provide shell access.

# 測試 GitLab 連線
ssh -T git@gitlab.com

# 測試自定義的 Git 伺服器
ssh -T git@your-git-server.com

遠端倉庫管理

查看遠端倉庫

# 簡單列表
git remote

# 詳細資訊（包含 URL）
git remote -v

# 查看特定遠端的詳細資訊
git remote show origin

新增遠端倉庫

# 新增遠端倉庫
git remote add origin https://github.com/username/repo.git

# 新增上游倉庫（用於 Fork 的專案）
git remote add upstream https://github.com/originalowner/repo.git

# 新增其他協作者的倉庫
git remote add colleague https://github.com/colleague/repo.git

修改遠端倉庫 URL

# 從 HTTPS 改為 SSH
git remote set-url origin git@github.com:username/repo.git

# 從 SSH 改為 HTTPS
git remote set-url origin https://github.com/username/repo.git

# 查看修改結果
git remote -v

重新命名和刪除遠端倉庫

# 重新命名遠端倉庫
git remote rename origin main-repo

# 移除遠端倉庫
git remote remove colleague

# 或使用 rm（相同功能）
git remote rm colleague

推送到遠端倉庫

基本推送操作

# 推送當前分支到對應的遠端分支
git push

# 首次推送並設定上游分支
git push -u origin main
git push -u origin feature/new-feature

# 推送到指定遠端和分支
git push origin main

# 推送所有分支
git push --all origin

# 推送標籤
git push --tags origin

強制推送（使用需謹慎）

# 強制推送（危險）
git push --force origin main

# 較安全的強制推送
git push --force-with-lease origin main

什麼時候需要強制推送？

使用 git rebase 重寫了歷史
修改了最後的提交訊息
需要覆蓋遠端的錯誤提交

注意事項：

# --force-with-lease 會檢查遠端是否有其他人的新提交
# 如果有，會拒絕推送，避免覆蓋他人的工作
git push --force-with-lease origin feature/my-branch

推送新分支

# 建立本地分支
git switch -c feature/payment-system

# 首次推送新分支
git push -u origin feature/payment-system

# 後續推送只需要
git push

從遠端倉庫拉取

Pull vs Fetch 的差異

Fetch：只下載資料，不合併

git fetch origin

Pull：下載並合併到當前分支

git pull origin main

實際上 git pull 等同於：

git fetch origin
git merge origin/main

拉取操作範例

# 拉取所有遠端的更新
git fetch --all

# 拉取特定遠端
git fetch origin
git fetch upstream

# 拉取並合併
git pull origin main

# 拉取並使用 rebase 而非 merge
git pull --rebase origin main

# 設定預設使用 rebase
git config --global pull.rebase true

檢視遠端分支

# 查看所有分支（包含遠端）
git branch -a

# 只查看遠端分支
git branch -r

# 查看遠端分支的詳細資訊
git ls-remote origin

追蹤遠端分支

設定追蹤關係

# 設定當前分支追蹤遠端分支
git branch --set-upstream-to=origin/main

# 或者在推送時設定
git push -u origin feature/new-feature

# 從遠端分支建立本地分支並設定追蹤
git switch -c feature/payment origin/feature/payment

同步遠端分支

# 查看本地和遠端的差異
git status

# 可能看到的訊息：
# Your branch is ahead of 'origin/main' by 2 commits.
# Your branch is behind 'origin/main' by 1 commit.
# Your branch and 'origin/main' have diverged.

# 推送本地變更到遠端
git push

# 拉取遠端變更到本地
git pull

# 如果分支分歧了，需要合併或 rebase
git pull --rebase

Fork 工作流程

Fork 是 GitHub 等平台特有的功能，讓你可以複製他人的專案到自己的帳號下。

Fork 專案的標準流程

# 1. 在 GitHub 上 Fork 專案

# 2. 複製你 Fork 的版本
git clone git@github.com:yourusername/project.git
cd project

# 3. 新增原始專案為 upstream
git remote add upstream git@github.com:originalowner/project.git

# 4. 確認遠端設定
git remote -v
# origin    git@github.com:yourusername/project.git (fetch)
# origin    git@github.com:yourusername/project.git (push)
# upstream  git@github.com:originalowner/project.git (fetch)
# upstream  git@github.com:originalowner/project.git (push)

保持 Fork 同步

# 1. 拉取上游變更
git fetch upstream

# 2. 切換到主分支
git switch main

# 3. 合併上游變更
git merge upstream/main

# 4. 推送到你的 Fork
git push origin main

貢獻流程

# 1. 建立功能分支
git switch -c feature/improve-documentation

# 2. 進行修改並提交
git add .
git commit -m "改善安裝說明文件"

# 3. 推送功能分支
git push -u origin feature/improve-documentation

# 4. 在 GitHub 上建立 Pull Request

多人協作的實際案例

場景 1：小型團隊協作

# 團隊成員 A
git switch main
git pull origin main
git switch -c feature/user-authentication
# ... 開發工作 ...
git push -u origin feature/user-authentication

# 團隊成員 B
git fetch origin
git switch -c review/user-authentication origin/feature/user-authentication
# ... 檢視和測試 ...
git push origin review/user-authentication

場景 2：處理同事的分支

# 查看同事的分支
git fetch origin
git branch -r

# 檢出同事的分支
git switch -c colleague-feature origin/colleague-feature

# 在同事的分支上繼續工作
git add .
git commit -m "協助完成功能"
git push origin colleague-feature

場景 3：解決推送衝突

# 嘗試推送時遇到拒絕
git push origin main
# ! [rejected]        main -> main (fetch first)
# error: failed to push some refs to 'origin'

# 解決方案：先拉取再推送
git pull origin main
# 如果有衝突，解決衝突
git push origin main

遠端分支管理

刪除遠端分支

# 刪除遠端分支
git push origin --delete feature/completed-feature

# 或使用舊語法
git push origin :feature/completed-feature

# 清理本地的遠端追蹤分支
git remote prune origin

重新命名遠端分支

# Git 沒有直接重新命名遠端分支的指令
# 需要透過刪除和建立新分支

# 1. 重新命名本地分支
git branch -m old-name new-name

# 2. 推送新分支
git push -u origin new-name

# 3. 刪除舊的遠端分支
git push origin --delete old-name

進階遠端操作

部分克隆（Partial Clone）

# 只克隆最近的提交（適合大型專案）
git clone --depth 1 https://github.com/large-project/repo.git

# 後續可以獲取更多歷史
git fetch --unshallow

# 只克隆特定分支
git clone -b develop --single-branch https://github.com/project/repo.git

稀疏檢出（Sparse Checkout）

# 只檢出專案的部分檔案
git clone --no-checkout https://github.com/large-project/repo.git
cd repo
git sparse-checkout init --cone
git sparse-checkout set src tests

# 檢出指定的檔案
git checkout main

子模組（Submodules）

# 新增子模組
git submodule add https://github.com/library/awesome-lib.git lib/awesome-lib

# 複製包含子模組的專案
git clone --recursive https://github.com/project/main-project.git

# 初始化和更新子模組
git submodule init
git submodule update

# 或一次性完成
git submodule update --init --recursive

常見問題解決

問題 1：推送被拒絕

# 錯誤訊息：
# ! [rejected] main -> main (fetch first)

# 解決方案：
git pull origin main  # 先拉取遠端變更
git push origin main   # 再推送

問題 2：遠端分支不存在

# 錯誤訊息：
# fatal: couldn't find remote ref feature/my-branch

# 解決方案：確認分支名稱和遠端設定
git branch -a  # 查看所有分支
git remote -v  # 確認遠端設定

問題 3：SSH 連線失敗

# 錯誤訊息：
# Permission denied (publickey)

# 解決步驟：
# 1. 檢查 SSH Agent
ssh-add -l

# 2. 重新加入金鑰
ssh-add ~/.ssh/id_ed25519

# 3. 測試連線
ssh -T git@github.com

# 4. 檢查遠端 URL 是否正確
git remote -v

問題 4：HTTPS 憑證問題

# 每次都要輸入密碼
# 解決：使用憑證管理器或改用 SSH

# macOS
git config --global credential.helper osxkeychain

# Windows
git config --global credential.helper manager-core

# Linux
git config --global credential.helper store

團隊協作最佳實踐

1. 建立清楚的工作流程

# 標準功能開發流程
git switch main
git pull origin main
git switch -c feature/feature-name
# ... 開發 ...
git push -u origin feature/feature-name
# ... 建立 Pull Request ...

2. 定期同步

# 每天開始工作前
git switch main
git pull origin main

# 定期將主分支合併到功能分支
git switch feature/my-feature
git merge main

3. 使用有意義的分支名稱

# 好的分支名稱
feature/user-authentication
bugfix/login-error
hotfix/security-patch
docs/api-documentation

# 避免的分支名稱
my-branch
fix
temp
test

4. 保持提交訊息清楚

# 好的提交訊息
git commit -m "新增使用者登入 API 端點"
git commit -m "修復購物車計算稅金錯誤"
git commit -m "更新 README 安裝說明"

# 避免的提交訊息
git commit -m "修改"
git commit -m "WIP"
git commit -m "asdf"

企業環境的特殊考慮

防火牆和代理設定

# 設定 HTTP 代理
git config --global http.proxy http://proxy.company.com:8080
git config --global https.proxy http://proxy.company.com:8080

# 設定 SSH 代理（在 ~/.ssh/config）
Host github.com
  Hostname ssh.github.com
  Port 443
  ProxyCommand connect -H proxy.company.com:8080 %h %p

自簽憑證處理

# 暫時跳過 SSL 驗證（不建議用於正式環境）
git config --global http.sslVerify false

# 指定憑證檔案位置
git config --global http.sslCAInfo /path/to/certificate.pem

企業 Git 伺服器

# 連接企業內部 Git 伺服器
git remote add origin https://git.company.com/team/project.git

# 使用企業 SSH 金鑰
ssh-keygen -t ed25519 -C "employee@company.com"
# 將公鑰提供給系統管理員

監控和維護遠端倉庫

查看遠端倉庫狀態

# 查看遠端倉庫的詳細資訊
git ls-remote origin

# 比較本地和遠端的差異
git log origin/main..main  # 本地有但遠端沒有的提交
git log main..origin/main  # 遠端有但本地沒有的提交

# 查看遠端分支的最後更新時間
git for-each-ref --format='%(refname:short) %(committerdate)' refs/remotes

清理和維護

# 清理已刪除的遠端分支引用
git remote prune origin

# 垃圾回收（清理不必要的物件）
git gc

# 檢查倉庫完整性
git fsck

# 壓縮倉庫（減少空間佔用）
git repack -ad

小結

遠端倉庫是現代軟體開發不可或缺的一部分，掌握遠端操作讓你能夠：

核心技能回顧：

SSH 金鑰設定：安全無密碼的認證方式
遠端倉庫管理：新增、修改、刪除遠端倉庫
推送和拉取：與遠端同步程式碼
分支追蹤：建立本地與遠端分支的關聯
Fork 工作流程：參與開源專案的標準方式

重要指令：

git clone <url>                    # 複製遠端倉庫
git remote -v                      # 查看遠端倉庫
git push -u origin branch-name     # 推送並設定追蹤
git pull origin main               # 拉取遠端變更
git fetch --all                    # 獲取所有遠端更新
ssh-keygen -t ed25519              # 生成 SSH 金鑰

最佳實踐：

使用 SSH 金鑰進行認證
定期同步遠端變更
建立清楚的分支命名規範
保持提交訊息的清楚和一致
遵循團隊的工作流程

在下一篇文章中，我們將深入探討 Pull Request 工作流程，學習如何進行 Code Review，以及如何建立高效的團隊協作機制。

記住，掌握遠端操作需要實際的練習。建議你建立一個測試倉庫，嘗試今天學到的所有操作。遠端協作是團隊開發的基石，值得投入時間深入學習和實踐。