在天文化有限公司
Git 開發指令速查手冊
VS Code 環境下的多裝置 (NAS/Mac) 協作標準作業程序
🟢 一、日常開發標準流程 (SOP)
1. 開工前的準備 (在開始寫 code 之前)
無論在 A 電腦還是 B 電腦，開工前務必執行，確保基礎是最新的。
# 1. 確認自己在哪個分支 (看到 * main 才是正確)
git branch
# 2. 回到主線
git checkout main
# 3. 下載最新進度
git pull
# 4. (選用) 更新雲端分支清單 (刪除本地殘影)
git fetch -p2. 開發新功能 (起手式)
絕對不要直接在 main 上修改程式碼，請開新分支。
# 建立並切換到新分支
git checkout -b 分支名稱
# 範例: git checkout -b feature-fuel-calc3. 存檔與上傳
做完一個小段落就可以存檔 (Commit)。您可以多次 Commit，等到一個大階段完成後再一次 Push。
# 1. 加入所有修改
git add .
# 2. 提交版本 (這是存在本機，可以做很多次)
git commit -m "完成平均油耗計算公式"
# --- 您可以重複上述步驟 1 & 2 多次，累積多個版本 ---
# 3. 上傳到雲端 (一次把所有累積的 commit 推上去)
# (第一次上傳該分支需加 -u，之後直接 git push 即可)
git push -u origin 分支名稱
💡 小技巧： 在本機可以盡量頻繁 Commit (存檔)，這樣可以隨時反悔回到上一步。不用擔心 Commit 太多，Git Push 會一次把所有累積的進度傳上去。
4. 合併回主線 (功能完成後)
當 feature-xxx 分支的功能寫好且測試沒問題了。
# 1. 切回主線
git checkout main
# 2. 再次確保主線是最新的 (以防別人在這期間有更新)
git pull
# 3. 合併分支
git merge 分支名稱
# 4. 推送主線到雲端
git push
# 5. 刪除舊分支 (打掃戰場)
git branch -d 分支名稱
🔄 二、多裝置協作 (A 電腦做完，換 B 電腦)
情境： A 電腦已經把功能寫好、合併回 main 並推送到 GitHub 了。現在打開 B 電腦，要把進度同步過來。
B 電腦操作步驟：
- 檢查狀態：確認目前沒有未存檔的修改。
-
切回主線：
git checkout main -
同步資料：
git pull(現在 B 電腦的 code 就跟 A 電腦一樣了)
-
清理舊分支：如果 A 電腦已經刪除了某個分支，B 電腦可以用此指令同步清單：
git fetch -p
Q: A 電腦推了新分支，B 電腦 Pull 會發生什麼事？
這是一個常見的誤區！B 電腦執行 git pull 後：
- B 電腦會知道有新分支 (Fetch 成功)。
- 但 B 電腦不會自動切換過去，畫面看起來沒變化 (還是在 main)。
B 電腦若要看到該分支，必須手動切換：
git checkout 新分支名稱
🔴 三、救命專區 (錯誤排除)
狀況 A：Pull 或 Checkout 時被拒絕
error: Your local changes … would be overwritten by merge
原因： 您有檔案 (index.php 或圖片) 修改了但沒存檔，Git 不敢覆蓋。
解法 1：我不要這些修改了 (直接覆蓋)
- VS Code 操作：在左側「原始碼控制」對該檔案按右鍵 -> Discard Changes (捨棄變更)。
- 指令操作：
git checkout .(還原所有檔案)
解法 2：我想保留修改 (暫存法)
git stash # 暫存
git pull # 更新
git stash pop # 取回暫存狀況 B：不小心進入 Detached HEAD
You are in ‘detached HEAD’ state
原因： 您使用了 git checkout origin/main (錯誤指令)，跑到了唯讀的雲端映像。
# 解法：回到地球表面
git checkout main狀況 C：本地端全亂了，想強制跟雲端一樣
⚠️ 警告： 這會刪除所有未上傳的修改，請謹慎使用。
情境： 放棄治療，我要讓電腦裡的程式碼跟 GitHub 上 一模一樣。
git fetch --all
git reset --hard origin/main
⚙️ 四、環境設定 (Mac / Docker)
1. Git 身分設定 (新電腦必做)
git config --global user.name "您的名字"
git config --global user.email "您的GitHub信箱"2. Mac 記住密碼設定
git config --global credential.helper osxkeychain3. Docker 常用指令 (測試環境)
在含有 docker-compose.yml 的資料夾下執行：
# 啟動環境 (背景執行)
docker-compose up -d
# 停止並移除環境
docker-compose down
# 修改了設定檔 (如加入 pdo_mysql) 後強制重建
docker-compose up -d --build
📝 五、VS Code 圖形介面 vs 指令對照表
| 動作 | 終端機指令 (CLI) | VS Code 介面操作 |
|---|---|---|
| 切換分支 | git checkout main | 點擊左下角分支名稱 -> 選擇清單 |
| 建立分支 | git checkout -b new-branch | 點擊左下角分支名稱 -> Create new branch |
| 同步 (Pull/Push) | git pull / git push | 點擊左下角「🔄」或是「☁️」圖示 |
| 提交 (Commit) | git commit -m “msg” | 左側「原始碼控制」 -> 輸入訊息 -> Commit |
| 放棄修改 | git checkout . | 對檔案清單按右鍵 -> Discard Changes |
| 看線圖 | git log –graph | 點擊下方狀態列的 Git Graph 按鈕 |
| 更新分支清單 | git fetch -p | (Git Graph 介面) 右上角重新整理按鈕 |
