---
# System prepended metadata

title: Python 新手指南：00-C GitHub 版本控制入門
tags: [Fundamental]

---

# Python 新手指南：00-C GitHub 版本控制入門

**作者：** Tsung-Min Pai  
**單位：** NTUEE

---

## 大綱

### 1 Git 與 GitHub 基礎概念

- 什麼是版本控制？
- Git vs GitHub 的差異
- 為什麼需要版本控制？

### 2 GitHub 帳號設定

- 帳號註冊與設定
- SSH 金鑰設定
- 個人檔案優化

### 3 Git 基本操作

- 基本指令介紹
- 工作流程
- 常見使用情境

### 4 GitHub 協作功能

- Fork 與 Pull Request
- Issue 與 Project 管理
- GitHub Pages

---

## 什麼是版本控制？

**版本控制的重要性：**

想像你在寫一份重要的報告，你可能會這樣命名檔案：

```
報告_初稿.docx
報告_修改版.docx
報告_最終版.docx
報告_真正最終版.docx
報告_老師修改版.docx
報告_最最終版.docx
```

這樣的檔案管理方式有很多問題：

- 📁 檔案名稱混亂，不知道哪個是最新版
- 🔄 無法追蹤每次修改了什麼
- 👥 多人協作時容易產生衝突
- 💾 佔用大量儲存空間
- 🚫 無法回到之前的版本

**版本控制系統解決這些問題：**

- ✅ 自動追蹤檔案變更歷史
- ✅ 可以隨時回到任何歷史版本
- ✅ 支援多人同時開發
- ✅ 自動合併變更
- ✅ 分支開發，互不干擾

---

## Git vs GitHub

**Git：**

- 📊 分散式版本控制系統
- 💻 安裝在你的電腦上
- 🔧 命令列工具
- 📝 追蹤程式碼變更歷史

**GitHub：**

- ☁️ 基於 Git 的雲端平台
- 🌐 網頁介面
- 👥 支援團隊協作
- 📂 線上程式碼託管

**類比說明：**

```
Git = 照相機 📸
GitHub = Instagram 📱

Git 負責「拍照」(記錄版本)
GitHub 負責「分享」(託管與協作)
```

---

## 為什麼程式設計師需要 GitHub？

**個人開發者：**

- 📚 **作品集展示**：展示你的程式碼作品
- ☁️ **雲端備份**：程式碼安全儲存在雲端
- 📱 **跨裝置存取**：任何地方都能存取你的專案
- 📊 **進度追蹤**：看到自己的成長軌跡

**團隊協作：**

- 👥 **多人協作**：團隊成員同時開發不同功能
- 🔄 **程式碼合併**：自動整合每個人的貢獻
- 📝 **程式碼審查**：確保程式碼品質
- 🐛 **問題追蹤**：記錄和解決 Bug

**學習與成長：**

- 📖 **學習他人程式碼**：觀摩優秀專案的實作
- 🤝 **參與開源專案**：為世界做出貢獻
- 💼 **建立專業形象**：雇主可以看到你的實力
- 🌟 **社群互動**：認識志同道合的開發者

---

## GitHub 帳號註冊與設定

**註冊步驟：**

1. **前往 GitHub 官網**

   ```
   https://github.com
   ```

2. **點擊 "Sign up"**

   - 📧 輸入 Email 地址
   - 🔐 設定強密碼
   - 👤 選擇使用者名稱 (這很重要！)

3. **使用者名稱建議：**

   ```
   ✅ 好的範例：
   - johnsmith
   - jane-doe-dev
   - coding-alice
   - mike2024

   ❌ 避免：
   - 太長或太複雜的名稱
   - 包含個人隱私資訊
   - 特殊符號過多
   ```

4. **驗證帳號**
   - 📧 檢查 Email 收取驗證信
   - ✅ 點擊驗證連結完成註冊

---

## 個人檔案優化

**完善個人檔案：**

```markdown
# 你的 GitHub Profile README

## 👋 你好！我是 [你的名字]

### 🚀 關於我

- 🎓 [你的學校/科系]
- 💻 正在學習 Python 程式設計
- 🌱 目標是成為 [全端工程師/資料科學家/...]
- 📫 聯絡方式：[your.email@example.com]

### 🛠️ 技能

- **程式語言：** Python, JavaScript
- **工具：** VSCode, Git, GitHub
- **學習中：** 機器學習, 網頁開發

### 📊 GitHub 統計

![你的 GitHub stats](https://github-readme-stats.vercel.app/api?username=你的使用者名稱&show_icons=true&theme=radical)

### 🔗 社群連結

- [LinkedIn](你的LinkedIn連結)
- [個人網站](你的網站)
```

**設定頭像：**

- 📸 上傳清晰的個人照片或設計圖
- 🎨 保持專業形象
- 📏 建議尺寸：400x400 像素

---

## Git 安裝與設定

**Windows 安裝：**

```bash
# 1. 下載 Git for Windows
# 前往 https://git-scm.com/download/win

# 2. 執行安裝程式，建議設定：
# - Use Git from Git Bash only
# - Checkout Windows-style, commit Unix-style line endings
# - Use MinTTY

# 3. 驗證安裝
git --version
```

**macOS 安裝：**

```bash
# 方法 1：使用 Homebrew
brew install git

# 方法 2：下載官方安裝檔
# 前往 https://git-scm.com/download/mac

# 驗證安裝
git --version
```

**初始設定：**

```bash
# 設定使用者資訊 (必須)
git config --global user.name "你的姓名"
git config --global user.email "你的Email"

# 設定預設編輯器 (可選)
git config --global core.editor "code --wait"  # VSCode
git config --global core.editor "nano"         # Nano

# 設定預設分支名稱
git config --global init.defaultBranch main

# 檢查設定
git config --list
```

---

## SSH 金鑰設定

**為什麼需要 SSH 金鑰？**

- 🔐 安全的身分驗證
- 🚫 不需要每次輸入密碼
- ⚡ 更快的連線速度

**產生 SSH 金鑰：**

```bash
# 1. 產生新的 SSH 金鑰
ssh-keygen -t ed25519 -C "你的email@example.com"

# 如果系統不支援 ed25519，使用：
ssh-keygen -t rsa -b 4096 -C "你的email@example.com"

# 2. 按 Enter 使用預設檔案位置
# 3. 設定密碼 (可選，建議設定)
```

**將 SSH 金鑰加入 SSH Agent：**

```bash
# 啟動 SSH Agent
eval "$(ssh-agent -s)"

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

**將公鑰加入 GitHub：**

```bash
# 1. 複製公鑰內容
cat ~/.ssh/id_ed25519.pub
# 或在 Windows 上
type %USERPROFILE%\.ssh\id_ed25519.pub

# 2. 在 GitHub 上：
# - 前往 Settings > SSH and GPG keys
# - 點擊 "New SSH key"
# - 貼上公鑰內容
# - 點擊 "Add SSH key"

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

---

## Git 基本概念

**工作區域：**

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Working Dir   │───▶│  Staging Area   │───▶│   Repository    │
│   (工作目錄)      │ add │    (暫存區)     │commit│    (儲存庫)     │
└─────────────────┘    └─────────────────┘    └─────────────────┘
```

**基本工作流程：**

1. **修改檔案** → 在工作目錄中編輯程式碼
2. **暫存變更** → `git add` 將變更加入暫存區
3. **提交變更** → `git commit` 將變更儲存到儲存庫
4. **推送到遠端** → `git push` 上傳到 GitHub

---

## Git 基本指令

**初始化專案：**

```bash
# 方法 1：從零開始
mkdir my-project
cd my-project
git init
echo "# My Project" >> README.md
git add README.md
git commit -m "Initial commit"

# 方法 2：複製現有專案
git clone https://github.com/username/repository.git
cd repository
```

**檢查狀態：**

```bash
# 檢查目前狀態
git status

# 檢查變更內容
git diff

# 檢查提交歷史
git log
git log --oneline  # 簡潔版本
```

**暫存與提交：**

```bash
# 暫存特定檔案
git add filename.py

# 暫存所有變更
git add .

# 提交變更
git commit -m "Add new feature"

# 修改最後一次提交訊息
git commit --amend -m "Updated commit message"
```

**分支操作：**

```bash
# 列出所有分支
git branch

# 建立新分支
git branch feature-login

# 切換分支
git checkout feature-login
# 或使用新語法
git switch feature-login

# 建立並切換到新分支
git checkout -b feature-signup
# 或
git switch -c feature-signup

# 合併分支
git checkout main
git merge feature-login

# 刪除分支
git branch -d feature-login
```

---

## 與 GitHub 互動

**連接遠端儲存庫：**

```bash
# 查看遠端儲存庫
git remote -v

# 新增遠端儲存庫
git remote add origin git@github.com:username/repository.git

# 推送到遠端
git push -u origin main  # 第一次推送
git push                 # 後續推送

# 從遠端拉取更新
git pull origin main
```

**在 GitHub 上建立新儲存庫：**

1. **點擊 "New repository"**
2. **填寫儲存庫資訊：**
   - 📝 Repository name
   - 📋 Description (可選)
   - 🔓 Public 或 🔒 Private
   - ✅ Add a README file
3. **點擊 "Create repository"**

---

## GitHub 常用功能

**Issues (問題追蹤)：**

```markdown
# Bug 回報範例

## 🐛 Bug 描述

程式在輸入特殊字元時會當機

## 🔄 重現步驟

1. 開啟應用程式
2. 在輸入框中輸入 "特殊字元@#$"
3. 按下確認鍵

## 🎯 預期行為

程式應該正常處理特殊字元

## 📸 截圖

[附上錯誤截圖]

## 🖥️ 環境資訊

- OS: Windows 10
- Python: 3.9.0
- 瀏覽器: Chrome 95.0
```

**Pull Request (拉取請求)：**

```markdown
# Pull Request 範例

## 📝 變更說明

新增使用者登入功能

## 🔄 變更內容

- 新增 login.py 模組
- 更新 main.py 新增登入流程
- 新增單元測試

## 📋 測試清單

- [x] 功能測試通過
- [x] 單元測試通過
- [ ] 整合測試 (待完成)

## 📸 截圖

[附上功能截圖]
```

---

## GitHub Desktop 圖形化介面

**什麼是 GitHub Desktop？**

- 🖱️ Git 的圖形化介面
- 👆 點擊操作，無需記憶指令
- 👀 視覺化的變更檢視
- 🔄 簡化的合併流程

**下載與安裝：**

```bash
# 前往官網下載
https://desktop.github.com/

# 安裝後登入 GitHub 帳號
# 選擇要複製的儲存庫
```

**GitHub Desktop 基本操作：**

1. **複製儲存庫：**

   - File → Clone repository
   - 選擇 GitHub.com 上的儲存庫

2. **提交變更：**

   - 在左側看到變更的檔案
   - 輸入提交訊息
   - 點擊 "Commit to main"

3. **推送變更：**

   - 點擊 "Push origin"

4. **建立分支：**
   - Branch → New branch
   - 輸入分支名稱

---

## VSCode 與 GitHub 整合

**VSCode Git 功能：**

```bash
# VSCode 內建 Git 支援
- 左側活動列的 Git 圖示
- 檔案變更狀態顯示
- 內建終端機執行 Git 指令
```

**實用擴充套件：**

```bash
# 安裝 GitHub 相關擴充套件：
1. GitLens — Git supercharged
2. GitHub Pull Requests and Issues
3. Git Graph
4. Git History
```

**VSCode Git 操作：**

```bash
# 快捷鍵
Ctrl+Shift+G    # 開啟 Git 面板
Ctrl+Shift+`    # 開啟終端機
Ctrl+K Ctrl+O   # 開啟專案資料夾

# Git 面板操作
- 點擊 + 暫存變更
- 輸入提交訊息
- 點擊 ✓ 提交
- 點擊 ... 更多操作
```

---

## 開源專案貢獻

**如何參與開源專案：**

1. **尋找專案：**

   - 🔍 使用 GitHub 搜尋
   - 🏷️ 查看 "good first issue" 標籤
   - 📚 閱讀專案文件

2. **Fork 專案：**

   ```bash
   # 在 GitHub 上點擊 Fork 按鈕
   # 複製專案到你的帳號下
   ```

3. **本地開發：**

   ```bash
   # 複製你的 Fork
   git clone git@github.com:你的使用者名稱/專案名稱.git
   cd 專案名稱

   # 新增原作者的 remote
   git remote add upstream git@github.com:原作者/專案名稱.git

   # 建立功能分支
   git checkout -b my-feature

   # 開發你的功能
   # ... 修改程式碼 ...

   # 提交變更
   git add .
   git commit -m "Add my awesome feature"
   git push origin my-feature
   ```

4. **建立 Pull Request：**
   - 前往你的 Fork 頁面
   - 點擊 "Compare & pull request"
   - 填寫 PR 說明
   - 點擊 "Create pull request"

---

## GitHub Pages 免費網站託管

**什麼是 GitHub Pages？**

- 🌐 免費的靜態網站託管服務
- 📝 支援 HTML, CSS, JavaScript
- 🚀 自動部署
- 🔗 提供 .github.io 網域

**建立個人網站：**

1. **建立特殊儲存庫：**

   ```
   儲存庫名稱：你的使用者名稱.github.io
   例如：johnsmith.github.io
   ```

2. **新增 index.html：**

   ```html
   <!DOCTYPE html>
   <html>
     <head>
       <title>我的個人網站</title>
     </head>
     <body>
       <h1>歡迎來到我的網站！</h1>
       <p>這是我的第一個 GitHub Pages 網站。</p>
     </body>
   </html>
   ```

3. **推送到 GitHub：**

   ```bash
   git add .
   git commit -m "Add personal website"
   git push origin main
   ```

4. **存取網站：**
   ```
   https://你的使用者名稱.github.io
   ```

---

## 專案展示最佳實務

**優秀的 README.md 結構：**

````markdown
# 專案名稱

簡短的專案描述

![專案截圖](screenshot.png)

## 🚀 功能特色

- 功能 1
- 功能 2
- 功能 3

## 🛠️ 技術棧

- Python 3.9+
- Flask
- SQLite

## 📦 安裝說明

```bash
# 複製專案
git clone https://github.com/username/project.git

# 安裝相依套件
pip install -r requirements.txt

# 執行程式
python app.py
```
````

## 🎯 使用方法

詳細的使用說明...

## 🤝 貢獻

歡迎提交 Issue 和 Pull Request！

## 📄 授權

MIT License

```

**專案結構組織：**

```

my-awesome-project/
├── README.md # 專案說明
├── requirements.txt # Python 相依套件
├── .gitignore # Git 忽略檔案
├── LICENSE # 授權條款
├── src/ # 原始碼
│ ├── **init**.py
│ ├── main.py
│ └── utils.py
├── tests/ # 測試檔案
│ ├── test_main.py
│ └── test_utils.py
├── docs/ # 文件
│ └── api.md
└── examples/ # 範例程式碼
└── basic_usage.py

````

---

## Git 常見問題與解決方案

**問題 1：忘記提交訊息**

```bash
# 修改最後一次提交訊息
git commit --amend -m "正確的提交訊息"
````

**問題 2：想要撤銷變更**

```bash
# 撤銷工作目錄的變更
git checkout -- filename.py

# 撤銷暫存區的變更
git reset HEAD filename.py

# 撤銷最後一次提交 (保留變更)
git reset HEAD~1

# 撤銷最後一次提交 (刪除變更)
git reset --hard HEAD~1
```

**問題 3：合併衝突**

```bash
# 當出現衝突時
git status  # 查看衝突檔案

# 手動編輯衝突檔案，解決衝突後
git add 解決的檔案
git commit -m "Resolve merge conflict"
```

**問題 4：不小心推送了敏感資訊**

```bash
# 從歷史中完全移除檔案
git filter-branch --force --index-filter \
'git rm --cached --ignore-unmatch 敏感檔案' \
--prune-empty --tag-name-filter cat -- --all

# 強制推送
git push origin --force --all
```

---

## .gitignore 最佳實務

**Python 專案 .gitignore：**

```gitignore
# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
*.egg-info/
.installed.cfg
*.egg

# 虛擬環境
venv/
env/
ENV/

# IDE
.vscode/
.idea/
*.swp
*.swo

# 作業系統
.DS_Store
Thumbs.db

# 環境變數
.env
.env.local

# 日誌檔案
*.log

# 資料庫
*.db
*.sqlite3

# 暫時檔案
*.tmp
*.temp
```

**Visual Studio Code 設定：**

```json
// .vscode/settings.json
{
  "python.defaultInterpreterPath": "./venv/bin/python",
  "git.ignoreLimitWarning": true,
  "files.exclude": {
    "**/__pycache__": true,
    "**/*.pyc": true
  }
}
```

---

## GitHub 協作工作流程

**GitHub Flow 工作流程：**

```mermaid
graph LR
    A[main 分支] --> B[建立功能分支]
    B --> C[開發功能]
    C --> D[提交變更]
    D --> E[推送分支]
    E --> F[建立 Pull Request]
    F --> G[程式碼審查]
    G --> H[合併到 main]
    H --> A
```

**團隊協作最佳實務：**

1. **分支命名慣例：**

   ```bash
   feature/user-login      # 新功能
   bugfix/login-error      # Bug 修復
   hotfix/security-patch   # 緊急修復
   docs/update-readme      # 文件更新
   ```

2. **提交訊息格式：**

   ```bash
   type(scope): description

   # 範例：
   feat(auth): add user login functionality
   fix(ui): resolve button alignment issue
   docs(readme): update installation instructions
   refactor(utils): simplify data validation logic
   ```

3. **Pull Request 檢查清單：**
   ```markdown
   ## PR 自我檢查清單

   - [ ] 程式碼已經過測試
   - [ ] 遵循專案的編碼規範
   - [ ] 更新了相關文件
   - [ ] 沒有破壞現有功能
   - [ ] 提交訊息清楚明確
   ```

---

## GitHub 進階功能

**GitHub Actions (CI/CD)：**

```yaml
# .github/workflows/python-app.yml
name: Python application

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2

      - name: Set up Python
        uses: actions/setup-python@v2
        with:
          python-version: 3.9

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt

      - name: Run tests
        run: |
          python -m pytest tests/
```

**專案範本 (Template Repository)：**

```bash
# 建立專案範本
1. 前往儲存庫設定
2. 勾選 "Template repository"
3. 其他使用者可以 "Use this template" 建立新專案
```

**Dependabot 自動更新：**

```yaml
# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "pip"
    directory: "/"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 10
```

---

## 學習資源與社群

**官方資源：**

- 📚 [GitHub 官方文件](https://docs.github.com/)
- 🎓 [GitHub Learning Lab](https://lab.github.com/)
- 📺 [GitHub YouTube 頻道](https://www.youtube.com/github)

**實用工具：**

- 🔧 [GitHub CLI](https://cli.github.com/) - 命令列工具
- 📊 [GitHub Desktop](https://desktop.github.com/) - 桌面應用程式
- 📱 [GitHub Mobile](https://github.com/mobile) - 手機應用程式

**學習專案建議：**

1. **個人作品集網站** - 使用 GitHub Pages
2. **小型 Python 專案** - 練習基本 Git 操作
3. **參與開源專案** - 學習協作流程
4. **建立專案範本** - 分享給其他開發者

---

## 總結與下一步

**你已經學會了：**

✅ **GitHub 基本概念** - 版本控制的重要性  
✅ **帳號設定** - 個人檔案和 SSH 金鑰  
✅ **Git 基本操作** - add, commit, push, pull  
✅ **分支管理** - 建立、切換、合併分支  
✅ **協作功能** - Fork, Pull Request, Issues  
✅ **專案展示** - README, GitHub Pages  
✅ **最佳實務** - .gitignore, 提交訊息, 工作流程

**下一步建議：**

1. **建立第一個專案** 🚀

   - 選擇一個簡單的 Python 專案
   - 建立 GitHub 儲存庫
   - 實際操作 Git 指令

2. **完善個人檔案** 📝

   - 新增個人 README
   - 上傳一些練習專案
   - 建立作品集網站

3. **參與社群** 👥

   - 關注有趣的專案
   - 提交第一個 Pull Request
   - 回報 Issues 或提供建議

4. **持續學習** 📚
   - 探索 GitHub Actions
   - 學習進階 Git 指令
   - 研究開源專案的結構

**記住：**

- 🎯 **實作勝過理論** - 動手做比只看文件更有效
- 🤝 **不怕犯錯** - Git 可以讓你隨時回到之前的狀態
- 🌱 **循序漸進** - 從簡單專案開始，逐步挑戰複雜功能
- 💪 **堅持練習** - 每天使用 Git，很快就會變成習慣

**歡迎來到 GitHub 的世界！開始你的程式設計之旅吧！** 🚀

---

## 常見問題 Q&A

**Q: 我應該把所有檔案都放到 GitHub 上嗎？**  
A: 不建議。避免上傳：

- 包含密碼或 API 金鑰的檔案
- 大型檔案 (>100MB)
- 自動產生的檔案 (如 `__pycache__`)
- 個人隱私資訊

**Q: Public 和 Private 儲存庫有什麼差別？**  
A:

- **Public**: 任何人都能看到你的程式碼，適合開源專案
- **Private**: 只有你和授權的人能存取，適合私人或公司專案

**Q: 如果我不小心刪除了重要檔案怎麼辦？**  
A: Git 的好處就是可以復原！使用 `git log` 找到之前的版本，然後用 `git checkout` 恢復檔案。

**Q: 為什麼我的 push 被拒絕了？**  
A: 通常是因為遠端有新的提交。先執行 `git pull` 獲取最新變更，解決可能的衝突後再 push。

**Q: 什麼時候應該建立新分支？**  
A:

- 開發新功能時
- 修復 Bug 時
- 實驗性變更時
- 不確定變更是否正確時

有任何問題嗎？歡迎在 GitHub 上建立 Issue 討論！
