# 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 統計
### 🔗 社群連結
- [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
# 專案名稱
簡短的專案描述
## 🚀 功能特色
- 功能 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 討論！
Sign in with Wallet
Connect another wallet