04 GitHub 協作平台

GitHub 是什麼？

GitHub 是全球最大的程式碼託管平台，基於 Git 版本控制系統。它不只是存放程式碼的地方，更提供了完整的協作工具。

📦 程式碼託管

將你的 Git Repository 存放在雲端，任何裝置都能存取。

🤝 團隊協作

透過 Pull Request、Issue、Code Review 等功能進行團隊開發。

🌐 開源社群

數百萬個開源專案在 GitHub 上開發，你可以學習、使用、甚至貢獻程式碼。

Git ≠ GitHub：Git 是版本控制工具，可以完全在本地使用。GitHub 是基於 Git 的雲端平台。其他類似平台還有 GitLab、Bitbucket 等。

GitHub 帳號註冊與設定

註冊流程

前往 github.com 點擊「Sign up」。
輸入 Email、密碼與使用者名稱（username）。
完成 Email 驗證。
選擇免費方案（Free plan 已包含無限公開/私有 Repo）。

SSH Key 設定（推薦）

使用 SSH Key 可以免去每次 push/pull 都要輸入密碼的麻煩。

產生並設定 SSH Key

# 產生 SSH Key（使用你的 GitHub email）
$ ssh-keygen -t ed25519 -C "your@email.com"

# 連按 Enter 使用預設路徑與空密碼（或設定密碼）
Generating public/private ed25519 key pair.
Enter file in which to save the key: [按 Enter]
Enter passphrase: [按 Enter 或設定密碼]

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

# Linux
$ cat ~/.ssh/id_ed25519.pub
# 手動複製輸出的內容

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

登入 GitHub → 右上角頭像 → Settings
左側選單 → SSH and GPG keys
點擊 New SSH key
Title 輸入描述（如 "My Laptop"），Key 貼上公鑰
點擊 Add SSH key

$ ssh -T git@github.com
Hi username! You've successfully authenticated,
but GitHub does not provide shell access.

看到這個訊息就表示 SSH Key 設定成功。

Remote（遠端版本庫）操作

Remote 是指存放在網路上（如 GitHub）的版本庫。你的本地 Repo 可以連結一個或多個 remote。

核心指令

指令	用途	說明
`git clone <url>`	複製遠端 Repo	下載完整的版本庫到本地，自動設定 remote 為 `origin`。
`git remote add origin <url>`	新增遠端連結	將本地已有的 Repo 連結到 GitHub 上的遠端 Repo。
`git push origin main`	推送到遠端	把本地的 commit 上傳到 GitHub 的 main 分支。
`git pull origin main`	拉取遠端更新	下載遠端的最新 commit 並合併到本地分支。
`git fetch origin`	下載但不合併	只下載遠端的更新資訊，不自動合併。
`git remote -v`	查看遠端設定	列出所有已設定的 remote 名稱與 URL。

兩種常見的起手流程

流程 A：本地先建，再推上 GitHub

# 1. 本地建立 Repo
$ mkdir my-project && cd my-project
$ git init
$ echo "# My Project" > README.md
$ git add . && git commit -m "初始提交"

# 2. 在 GitHub 建立空 Repo（不勾選 README）

# 3. 連結並推送
$ git remote add origin git@github.com:user/my-project.git
$ git push -u origin main

流程 B：GitHub 先建，再 clone 到本地

# 1. 在 GitHub 建立 Repo（可勾選 README）

# 2. Clone 到本地
$ git clone git@github.com:user/my-project.git
$ cd my-project

# 3. 開始工作
$ echo "Hello" > index.html
$ git add . && git commit -m "新增首頁"
$ git push

建議初學者使用流程 B，因為 git clone 會自動設定好 remote，減少設定步驟出錯的機會。

Push / Pull 的運作流程

sequenceDiagram participant L as 本地 Repo participant R as GitHub (Remote) Note over L: 編輯 → git add → git commit L->>R: git push origin main Note over R: 遠端更新到最新 commit Note over R: 其他人推送了新 commit R->>L: git pull origin main Note over L: 本地合併遠端的變更

push 被拒絕怎麼辦？

如果遠端有你本地沒有的 commit，git push 會被拒絕：

$ git push origin main
! [rejected]        main -> main (non-fast-forward)
error: failed to push some refs to 'github.com:user/my-project.git'
hint: Updates were rejected because the remote contains work that you do not have locally.

解決方式：

# 先拉取遠端更新，再推送
$ git pull origin main
$ git push origin main

GitHub 上的 Repo 管理

Public vs Private

Public：任何人都能看到程式碼（適合開源專案）。
Private：只有你和被邀請的協作者能存取。

README.md

專案的首頁文件。GitHub 會自動渲染 Markdown 格式，通常包含專案介紹、安裝方式與使用說明。

License

授權條款，告訴別人可以怎麼使用你的程式碼。常見選項：MIT、Apache 2.0、GPL。

.gitignore

告訴 Git 哪些檔案不需要追蹤。GitHub 提供各語言的範本。

GitHub 的協作功能總覽

GitHub 不只是存放程式碼，它提供了完整的專案管理與協作工具：

功能	說明	適用場景
Pull Request (PR)	提出程式碼變更的請求，讓其他人審查後合併。	多人協作、程式碼審查。
Issue	追蹤 bug、功能需求或待辦事項。	專案管理、問題回報。
Branch Protection	保護特定分支，強制要求 PR 審查才能合併。	保護 main 分支的穩定性。
Actions (CI/CD)	自動化工作流程，如自動測試、自動部署。	持續整合與部署。
Projects	看板式的專案管理工具（類似 Trello）。	任務追蹤與進度管理。
Wiki	專案的 Wiki 文件空間。	撰寫詳細的技術文件。

下一章預告：Pull Request、Issue 與 Branch 是最常用的三個協作功能，我們會在第五章深入介紹。

GitHub 協作平台