官方文檔：[Github 官方入門document](https://docs.github.com/zh/get-started)

## 🔹 🅖 Git常用指令

git init 在檔案目錄下建立 .git隱藏資料夾
touch .gitignore 建立 .gitignore檔案 用editor打開編輯不想被git追蹤的檔案
git add file_name 使git追蹤此檔案的變更
git add . 當前資料夾所有檔案

git commit -m “commit message” 建立一個版本

git remote add origin <repo網址> 將遠端 GitHub repo 命名為 origin
git push -u origin main 把 main branch 第一次推到 GitHub 並建立追蹤關係
git push 推送最新 commit 到 GitHub
git pull 從 GitHub 把更新拉下來（自動合併）
git pull origin main --allow-unrelated-histories 解決本地與遠端沒有共同歷史的情況（如雙方都各自 init 過）
git clone <repo網址> 從 GitHub 複製整個專案到本地

git diff 看哪些地方有修改（但還沒 add）
git diff --cached 看 staging 區（已 add 但尚未 commit）的差異

git status 顯示哪些檔案被修改

git log —oneline 顯示所有commit紀錄
-> output:<commit_id> <commit_message>

git checkout <commit_id> 回到檔案當時版本
git checkout — file_name 回到上次commit狀態（取消當前的修改）

git rm [file]: Deletes the file from the working directory and stages the deletion

git rm —cached [file]: 只從 staging 區移除，不刪檔案

git mv [file-original] [file-renamed]: Changes the file name and prepares it for commit

git restore --staged [file] 將檔案從 staging 區拿出來（Git 2.23+）

git reset 移除所有 staging 區的變更
git reset --hard 還原整個 repo 到上次 commit（會丟掉未儲存更改）

git config --global user.name "你的名字" 設定 Git 使用者名稱（全域）
git config --global user.email "你的 Email" 設定 Git email（跟 GitHub 綁定）
git config --global core.editor "code --wait" 設定 VSCode 為預設編輯器
git config --list 檢視目前的 Git 設定

## 🔹Git 運作方式

**Git 就是一個本地端的版本控制系統**，它的主要功能就是在你的電腦上**記錄每次的變更**，就像一個「時間機器」，讓你隨時可以回溯到過去的版本

---

Git 主要有三個區域：
1. **工作區（Working Directory）💻**
- 你實際編輯的檔案所在的地方。
- 這裡的檔案**還沒進入 Git 的版本控制**。

2. **暫存區（Staging Area）🛒**
- 你用 `git add` 後，檔案會被放到**暫存區**，表示「準備好要提交了」。
- 這就像是**確認無誤後放進購物車，但還沒結帳**。

3. **Git 倉庫（Repository）📦**
- 你用 `git commit` 之後，檔案就會被存到**本地 Git 倉庫**，變成永久的歷史版本。

🎞️ **流程圖**

💻[工作區]  →  git add  →  🛒[暫存區]  →  git commit  →  📦[Git 倉庫]

這樣你的檔案變更就被安全地記錄下來了！

---

### Git 和 GitHub 的差別
| **Git** | **GitHub** |
|---------|------------|
| **本地端**版本控制 | **雲端** Git 倉庫 |
| 變更儲存在**你自己的電腦** | 變更儲存在 **GitHub 伺服器** |
| 即使**沒網路**也可以使用 | 需要網路才能 push/pull |
| `git commit` 把變更儲存到本機 | `git push` 把變更上傳到 GitHub |

**你可以只用 Git 而不需要 GitHub**，這樣你的變更都存放在 **本地端**。
**如果你想讓別人也能看到你的專案**，或是在不同電腦同步，才需要把專案 push 到 **GitHub**。

### **總結**
- **Git = 本地端的版本控制工具**
- **`git add` = 把檔案放進暫存區**
- **`git commit` = 把暫存區的變更存入 Git 倉庫**
- **GitHub = 遠端備份 & 團隊協作工具**
- **沒網路也能用 Git，GitHub 只是額外的雲端存放點**

## 🔹 流程：

### 📌 新增

初始化 git
這會在該資料夾內建立 .git 隱藏資料夾，代表這個資料夾已經受到 Git 版本控制。

將要追蹤的檔案加入 Git，這表示 Git 會**追蹤這個檔案的變更**。

這會建立(提交)一個版本，提交訊息可說明版本描述。


### 📌 修改

假設你對 algorithm.md 進行修改了，想保存這次的變更：

1. 查看變更

git status

它會顯示哪些檔案被修改了。

2. 加入變更並提交

git add algorithm.md
git commit -m "Updated algorithm with new approach"

這樣 Git 會記住你這次的變更。



### 📌 遠端備份
如果你想要把你的 Git 紀錄同步到 GitHub，這樣不管換電腦還是意外刪除檔案，都能找回：

1. 到 GitHub 建立一個 Repository（倉庫）。
2. 連結你的本地 Git 專案到 GitHub：

git remote add origin https://github.com/你的帳號/你的專案.git
git branch -M main
git push -u origin main

3. 之後如果有新修改，只要：

git add .
git commit -m "New changes"
git push origin main

就能更新到 GitHub 了。


### 📌 如何查看歷史紀錄？

git log --oneline

這樣可以看到你所有的 commit 記錄，類似這樣：

f3a2b1c Updated algorithm with new approach
a1d4f6e Initial commit: Added algorithm description

你可以隨時回到舊版本，不怕改壞。

### 📌 如何回到某個版本？
1. 如果你覺得新版本有問題，想回到上一個版本：

git checkout <commit_id>

例如：

git checkout a1d4f6e

這樣你的檔案會變回當時的版本。

2. 如果你只是想「取消當前的修改」：

git checkout -- algorithm.md

這會讓檔案回到上次 commit 的狀態。



### ⚠️ 記得加 .gitignore 避免提交虛擬環境！
虛擬環境裡的 venv 目錄通常不需要被 Git 追蹤（因為它可以用 requirements.txt 或 pyproject.toml 重新建立環境），所以你應該加一個 .gitignore 檔案來忽略它。

1. 新增 .gitignore（建議內容）
在專案資料夾內建立 .gitignore 檔案，內容如下：

# 忽略虛擬環境資料夾
venv/
.myenv/
.env/

# Python 產生的暫存檔
__pycache__/
*.pyc
*.pyo

# Jupyter Notebook 檔案暫存
.ipynb_checkpoints/

# VSCode 設定檔（選擇性）
.vscode/

2. 然後執行：

git add .gitignore
git commit -m "Added .gitignore to exclude virtual environment"

####  這樣做的好處
Git 不會追蹤你的虛擬環境，減少不必要的 commit。
別人 clone 你的專案後，只要執行 ```pip install -r requirements.txt``` 就能重建環境。
這樣，你的 Git 和虛擬環境就能完美共存了！



如果你之後打算上傳到 GitHub，也可以用 GitHub 提供的 .gitignore 模板：

curl -o .gitignore https://raw.githubusercontent.com/github/gitignore/main/Python.gitignore

這會下載一份 官方的 Python .gitignore，裡面有完整的排除規則。



**註：在 .gitignore 檔案裡，# 開頭的行是註解，不會影響 Git 的行為。你可以用註解來標記忽略的檔案類型，方便未來自己或其他開發者理解。**


## 🔹 分支 (branch)：

Git 分支（branch）是用來**同時開發不同版本的程式碼**，讓你可以在不影響主分支的情況下**測試新想法、修 bug、或開發新功能**。方便管理不同版本

---

### **1. 檢查目前的分支**

git branch

這會列出目前專案內的所有分支，`*` 星號標示的是當前所在的分支。

如果你剛初始化 Git，預設的分支通常叫做 `main`：

* main

---

### **2. 建立新分支**
假設你想測試新的演算法，不想影響 `main` 分支：

git branch new-idea

這樣就建立了一個名為 `new-idea` 的新分支。
但目前你**還在 main 分支**，你需要切換過去 👇

---

### **3. 切換到新分支**

git checkout new-idea

或是（Git 2.23+ 版本推薦使用）：

git switch new-idea

現在你就在 `new-idea` 分支，可以自由修改檔案。

確認一下：

git branch

你會看到：

main
* new-idea # 你現在在這個分支

---

### **4. 在新分支進行修改**
假設你改了 `algorithm.md`，然後想要提交：

git add algorithm.md
git commit -m "Tried a new approach for the algorithm"

這樣你的修改只會存到 `new-idea`，不會影響 `main`！

---

### **5. 切回 main 分支**
如果你想回到原本的 `main` 分支：

git checkout main

或

git switch main

切回 `main` 之後，你會發現 `algorithm.md` 還是原本的版本，因為 `new-idea` 分支的改動**還沒合併進來**。

---

### **6. 合併新分支**
如果你覺得 `new-idea` 的改動很好，想合併回 `main`：

git merge new-idea

這樣 `main` 就會包含 `new-idea` 的改動。

確認合併成功後，你可以刪掉這個測試分支：

git branch -d new-idea

這樣你的 Git 就乾淨了！

---

### **7. 如果合併後發現有問題？**
如果你發現合併後有錯誤，想要回到合併前的狀態：

git reset --hard HEAD~1

這會撤銷上一次合併，但**請確保你不會丟失重要的變更**！

---

### **8. 用 `git log` 來查看歷史**

git log --oneline --graph --all

這會顯示你的分支歷史，像這樣：

* 3f5b2a1 (HEAD -> main) Merged new-idea
| * 8c2f9d3 (new-idea) Tried a new approach
|/
* a1d4f6e Initial commit

這樣你就能直覺地看到不同分支的發展路徑。

---

### **📌 這樣使用分支**
| **操作**       | **指令**                           | **說明** |
|--------------|--------------------------------|------|
| 查看目前的分支  | `git branch`                  | 顯示所有分支 |
| 建立新分支    | `git branch new-idea`         | 建立新分支 |
| 切換分支     | `git switch new-idea`        | 切到 `new-idea` |
| 提交變更     | `git add . && git commit -m "描述"` | 提交當前變更 |
| 切回 main    | `git switch main`            | 回到 `main` |
| 合併分支     | `git merge new-idea`         | 把 `new-idea` 合併到 `main` |
| 刪除分支     | `git branch -d new-idea`     | 刪除不需要的分支 |
| 查看歷史     | `git log --oneline --graph --all` | 查看所有分支變更記錄 |

這樣你就可以**乾淨又有條理地管理你的演算法版本**，不用再手動存 `v1.0, v2.0` 了！也可以 push 分支到 GitHub


### **📌 終端機 Git 狀態**
這些符號不是 Git 原生輸出的訊息，而是終端機（特別是像 zsh, oh-my-zsh）自動做的提示。

[main] 在 main branch，工作目錄乾淨，沒有任何變動。
[main+] 在 main branch，有東西加入 staging 區（git add），但還沒 commit。
[main+*] 在 main branch，有 staging 區變動（+），也有尚未加入 staging 區的變動（*）。
[main*] 只有未加入 staging 的變動（也就是你改了東西但沒 git add）。
[main?] 有未追蹤（untracked）檔案。
[main!] 有 conflict 或 merge 中的狀態。