Git指令大全：2025年版本控制完整教學指南 | 前端開發必學

Git 基礎設定

初次設定

# 設定使用者資訊
git config --global user.name "你的名字"
git config --global user.email "你的信箱"

# 初始化儲存庫
git init

# 查看設定
git config --list

實用設定

# 設定預設編輯器
git config --global core.editor "code --wait"

# 設定別名
git config --global alias.st status
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.ci commit

檔案管理

基本操作

# 查看狀態
git status
git status -s          # 簡潔顯示

# 添加檔案
git add filename.txt
git add .              # 添加所有檔案
git add *.js           # 添加所有 JS 檔案

# 移除暫存
git reset filename.txt
git reset              # 移除所有暫存

檔案操作

# 重新命名
git mv oldname.txt newname.txt

# 刪除檔案
git rm filename.txt
git rm --cached filename.txt    # 只從 Git 移除

# 查看差異
git diff                        # 工作區與暫存區
git diff --staged              # 暫存區與提交

提交管理

提交操作

# 提交
git commit -m "提交訊息"
git commit -am "快速提交"       # add + commit

# 修改最後提交
git commit --amend -m "新訊息"
git commit --amend --no-edit    # 不修改訊息

# 查看歷史
git log
git log --oneline              # 一行顯示
git log --graph                # 圖形化
git log --stat                 # 顯示統計

復原操作

# 復原檔案
git restore filename.txt       # 推薦使用
git checkout filename.txt       # 舊版本

# 復原提交
git reset --soft HEAD~1        # 保留在暫存區
git reset --mixed HEAD~1       # 保留在工作區
git reset --hard HEAD~1        # 完全刪除

# 反轉提交
git revert commit-hash

分支操作

分支管理

# 查看分支
git branch
git branch -a                  # 包含遠端分支
git branch -r                  # 只看遠端分支

# 建立分支
git branch branch-name
git switch -c branch-name      # 推薦使用
git checkout -b branch-name    # 舊版本

# 切換分支
git switch branch-name         # 推薦使用（Git 2.23+）
git checkout branch-name       # 舊版本但仍廣泛使用

# 刪除分支
git branch -d branch-name      # 安全刪除
git branch -D branch-name      # 強制刪除

合併操作

# 合併分支
git merge branch-name
git merge --no-ff branch-name  # 保留合併紀錄

# 重新整理
git rebase branch-name
git rebase -i HEAD~3           # 互動式重整

# 取消操作
git merge --abort
git rebase --abort

遠端操作

遠端管理

# 添加遠端
git remote add origin https://github.com/user/repo.git

# 查看遠端
git remote -v
git remote show origin

# 推送
git push origin main
git push -u origin main        # 設定上游追蹤
git push --all                 # 推送所有分支

# 拉取
git pull
git pull origin main
git fetch                      # 只下載不合併
git fetch --all                # 拉取所有遠端

協作操作

# 複製儲存庫
git clone https://github.com/user/repo.git
git clone --depth 1 url        # 淺複製

# 同步更新 - 重要：選擇正確的策略
git pull                       # 預設：fetch + merge（創建合併提交）
git pull --rebase              # fetch + rebase（線性歷史）
git fetch upstream
git merge upstream/main

# 修剪遠端分支
git remote prune origin
git fetch --prune

git pull vs git pull —rebase

git pull（預設行為）：

• 在歷史中創建合併提交
• 對於共享/已發布分支較安全
• 保留確切的協作時間線
• 可能創建「混亂」的非線性歷史

git pull —rebase：

• 創建乾淨的線性歷史
• 危險：絕對不要用於已發布的提交
• 適合個人功能分支
• 可能導致需要手動解決的衝突

最佳實踐： 只在未發布的本地分支使用 git pull --rebase。

git pull —rebase 安全使用指南

安全使用條件（同時滿足）：

• 功能分支：不是 main 或 develop 等公共分支
• 本地提交：你的提交尚未被其他人拉取或依賴
• 個人工作：沒有其他開發者在此分支上協作

危險使用情境（絕對禁止）：

• 在 main、develop 等公共分支上使用
• 提交已被團隊成員拉取或合併
• 多人協作的功能分支
• 已經推送並被 CI/CD 或其他系統依賴的提交

關鍵 Rebase 安全規則

git pull —rebase 的安全場景：

# 個人功能分支，從未推送
git checkout -b feature/my-work
# 只在本地工作
git pull --rebase origin main

# 功能分支已推送但沒有其他人依賴
git push -u origin feature/my-work
# 如果沒有協作者仍可安全 rebase
git pull --rebase origin main

危險場景（絕對不要 rebase）：

# 主分支/共享分支
git checkout main
git pull --rebase  # 絕對不要這樣做

# 已被隊友拉取的提交
git checkout feature/shared-work
git pull --rebase  # 會破壞隊友的歷史

# 已在 PR/MR 中的提交
# 一旦提交進入 Pull Request，就不要 rebase

真實後果： 如果您 rebase 已發布的提交，隊友會看到：

• Git 歷史衝突
• “您的分支與 origin/main 已分歧” 錯誤
• 需要強制推送自己的工作（也會破壞其他人）

隊友在共享分支被錯誤 rebase 後的恢復：

# 如果主分支被錯誤 rebase
git fetch origin
git reset --hard origin/main
# 可能會失去本地工作 - 務必先備份！

暫存管理

Stash 操作

# 暫存變更
git stash
git stash push -m "暫存訊息"
git stash -u                   # 包含未追蹤檔案

# 管理暫存
git stash list
git stash show stash@{0}

# 恢復暫存
git stash pop                  # 恢復並刪除
git stash apply stash@{0}      # 只恢復不刪除

# 清理暫存
git stash drop stash@{0}
git stash clear                # 清除所有

標籤管理

標籤操作

# 建立標籤
git tag v1.0.0
git tag -a v1.0.0 -m "版本 1.0.0"

# 查看標籤
git tag
git tag -l "v1.*"
git show v1.0.0

# 推送標籤
git push origin v1.0.0
git push --tags

# 刪除標籤
git tag -d v1.0.0
git push origin :refs/tags/v1.0.0

專業標籤與發布管理

專業標籤策略

語意化版本控制（推薦）：

# 版本格式：主版本.次版本.修補版本
git tag v1.0.0          # 初始發布
git tag v1.0.1          # 錯誤修復
git tag v1.1.0          # 新功能
git tag v2.0.0          # 破壞性變更

# 帶發布說明的註解標籤
git tag -a v1.2.0 -m "發布 v1.2.0

功能：
- 新增使用者驗證
- 性能提升 30%

錯誤修復：
- 修復資料處理記憶體洩漏
- 解決 CSS 佈局問題"

與 CI/CD 整合：

# 觸發自動部署
git tag v1.0.0
git push origin v1.0.0

# 按版本排序列出標籤
git tag -l --sort=-version:refname

生產發布工作流程

完整發布流程：

# 1. 準備發布分支
git checkout main
git pull origin main
git checkout -b release/v1.2.0

# 2. 更新版本檔案
echo "1.2.0" > VERSION
git add VERSION package.json  # 更新相關檔案中的版本
git commit -m "Bump version to 1.2.0"

# 3. 建立並推送標籤
git tag -a v1.2.0 -m "發布 v1.2.0

新功能：
- 使用者驗證系統
- 儀表板分析
- 行動響應式設計

錯誤修復：
- 修復資料處理記憶體洩漏
- 解決 Safari 上的 CSS 佈局問題

破壞性變更：
- API 端點 /old-api 已廢棄
- 需要 Node.js 18+"

# 4. 推送所有內容
git push origin release/v1.2.0
git push origin v1.2.0

# 5. 合併回主分支
git checkout main
git merge release/v1.2.0
git push origin main

# 6. 部署（由 CI/CD 中的標籤觸發）
# GitHub Actions、GitLab CI、Jenkins 等會看到標籤

CI/CD 整合範例（GitHub Actions）：

# .github/workflows/release.yml
name: Release
on:
  push:
    tags:
      - 'v*'
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Extract version
        run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> $GITHUB_ENV
      - name: Build and deploy
        run: |
          npm ci
          npm run build
          npm run deploy

緊急修復發布流程：

# 生產環境緊急修復
git checkout tags/v1.2.0
git checkout -b hotfix/v1.2.1

# 修復關鍵問題
git add .
git commit -m "修復關鍵安全漏洞"

# 標記緊急修復
git tag -a v1.2.1 -m "緊急修復 v1.2.1 - 安全補丁"
git push origin v1.2.1

# 合併回 main 和 develop
git checkout main
git merge hotfix/v1.2.1
git push origin main

搜尋與查找

內容搜尋

# 搜尋內容
git grep "搜尋字串"
git grep -n "搜尋字串"         # 顯示行號

# 搜尋歷史
git log --grep="關鍵字"
git log --author="作者"
git log -S "程式碼字串"         # 搜尋程式碼變更

# 查看檔案歷史
git log filename.txt
git log -p filename.txt        # 顯示變更內容
git blame filename.txt         # 逐行顯示作者

除錯工具

# 二分搜尋
git bisect start
git bisect good commit-hash
git bisect bad commit-hash

# 查看引用歷史
git reflog
git reflog expire --expire=now --all

維護清理

清理操作

# 清理未追蹤檔案
git clean -n                   # 預覽
git clean -f                   # 清理檔案
git clean -fd                  # 清理檔案和資料夾

# 垃圾回收
git gc
git gc --aggressive            # 積極清理

# 檢查完整性
git fsck
git fsck --full

設定管理

# 忽略檔案變更
git update-index --skip-worktree filename.txt
git update-index --no-skip-worktree filename.txt

# 變更遠端 URL
git remote set-url origin new-url

# 重寫歷史（危險）
git filter-branch --env-filter 'export GIT_AUTHOR_EMAIL="[email protected]"'

工作流程

標準流程

# 功能開發流程
git switch main
git pull origin main
git switch -c feature/new-feature

# 開發完成
git add .
git commit -m "完成新功能"
git push -u origin feature/new-feature

# 合併清理
git switch main
git pull origin main
git merge feature/new-feature
git branch -d feature/new-feature
git push origin main

衝突處理

# 查看衝突
git status
git diff
git diff --ours              # 你的變更
git diff --theirs            # 他們的變更

# 解決衝突後
git add 已解決檔案
git commit

# 或放棄合併
git merge --abort

進階衝突管理

進階衝突處理

預防策略：

# 頻繁同步以避免大型衝突
git fetch origin
git diff origin/main         # 合併前檢查差異
git merge --no-commit origin/main  # 預覽合併而不提交

團隊工作流程中的衝突預防

1. 小而頻繁的分支：

# 好的：小而專注的變更
git checkout -b feature/fix-login-button
# 進行 1-3 個相關變更
git push origin feature/fix-login-button

# 壞的：大型長期分支
git checkout -b feature/complete-redesign
# 工作數週而不同步

2. 定期主分支同步：

# 功能分支的日常例行程序
git checkout feature/my-work
git fetch origin
git merge origin/main         # 或在安全時 rebase
git push origin feature/my-work

# 這讓您的分支與 main 保持接近，減少衝突

3. Pull Request 最佳實踐：

# 建立 PR 前，確保是最新的
git checkout feature/my-work
git fetch origin
git merge origin/main
git push origin feature/my-work
# 現在建立 PR - 發生衝突的可能性大大降低

4. 團隊溝通協議：

• 宣布重大重構 - 警告團隊可能的衝突
• 協調共享檔案變更 - 討論何時誰變更什麼
• 使用功能開關 - 避免發布中的大型合併衝突
• 將大型功能拆分 為較小的獨立 PR

衝突解決工具：

# 設定合併工具（一次性設定）
git config --global merge.tool vimdiff
git config --global merge.tool code

# 使用合併工具處理衝突
git mergetool

# 查看檔案歷史以了解背景
git log --oneline -- filename.txt
git blame filename.txt

Rebase 過程中的衝突：

# 修復衝突後繼續
git add 已解決檔案
git rebase --continue

# 跳過有問題的提交
git rebase --skip

# 中止整個 rebase
git rebase --abort

緊急救援

常見問題

# 撤銷 git add
git reset HEAD filename.txt

# 找回刪除的提交
git reflog
git cherry-pick commit-hash

# 完全重置
git fetch origin
git reset --hard origin/main

# 強制推送（小心使用）
git push --force-with-lease

強制推送：核彈選項

理解強制推送：

git push --force              # 核彈：完全覆蓋遠端
git push --force-with-lease   # 較安全：先檢查衝突
git push --force-if-includes  # 最安全：更多保護檢查

真實強制推送場景：

# 您的功能分支有提交 A-B-C
# 您進行 rebase 清理歷史
git rebase -i HEAD~3
# 現在您有 A'-B'-C'（不同的提交雜湊）
# 正常推送會失敗
git push  # 錯誤：更新被拒絕

# 解決方案：強制推送（小心！）
git push --force-with-lease origin feature/my-branch

Force Push 的真實災難場景

如果您在共享分支使用 --force，隊友會遇到什麼：

步驟 1：災難發生

# 您在共享的 feature/login 分支強制推送
git push --force origin feature/login

步驟 2：隊友 Alice 的體驗

# Alice 嘗試推送她的工作
git push origin feature/login
# 錯誤：! [rejected] feature/login -> feature/login (non-fast-forward)

# Alice 嘗試拉取
git pull origin feature/login
# 錯誤：Your branch and 'origin/feature/login' have diverged,
# and have 2 and 3 different commits each, respectively.

步驟 3：Alice 看到的混亂

git log --oneline --graph
# * abc123 (HEAD -> feature/login) Alice's work
# * def456 Alice's previous work
# | * 789xyz (origin/feature/login) Your new history after force push
# | * 456abc Your rewritten commits
# |/
# * 123def Common ancestor

步驟 4：隊友的痛苦恢復過程

# Alice 的正確恢復方式（複雜且容易出錯）：
git fetch origin
git branch backup-alice-work    # 先備份自己的工作！

# 選項 1：重新應用工作（推薦）
git reset --hard origin/feature/login
git cherry-pick backup-alice-work~1..backup-alice-work

# 選項 2：合併衝突（可能很複雜）
git merge origin/feature/login  # 會有很多衝突

# Alice 現在也必須強制推送（連鎖反應）
git push --force-with-lease origin feature/login

真實後果統計：

• 團隊 3 人協作的分支被強制推送
• 每人平均花費 30-60 分鐘恢復工作
• 可能丟失 2-4 小時的開發進度
• 需要團隊緊急會議討論歷史重建
• CI/CD 管道可能中斷或產生錯誤建置

安全強制推送協議：

1. 先溝通 - 強制推送前告知團隊
2. 使用 —force-with-lease - 防止覆蓋他人工作
3. 只在功能分支 - 絕不在 main/共享分支
4. 確認沒有協作者 - 檢查分支是否有其他人的提交
5. 備份重要工作 - 危險操作前建立分支

危險操作 - 使用前請閱讀

歷史重寫指令（絕對不要用於共享分支）：

# 這些指令會重寫歷史 - 在團隊環境中極其危險
git rebase -i HEAD~3          # 互動式重整
git reset --hard HEAD~1       # 永久刪除
git push --force              # 危險：覆蓋遠端
git push --force-with-lease   # 較安全：先檢查衝突

關鍵警告：

• 絕對不要重整已發布/共享的提交 - 會破壞他人的工作
• 絕對不要使用 —force 而不用 —with-lease - 可能摧毀他人的工作
• 危險操作前務必備份重要工作
• 任何歷史變更操作前都要與團隊溝通

安全替代方案：

# 在共享分支使用合併而非重整
git merge feature-branch

# 使用 revert 而非硬重置以保留歷史
git revert commit-hash

# 使用 --force 時，創建新分支
git checkout -b fix-branch

修復問題

# 修復分離的 HEAD
git switch main

# 修復損壞的索引
git reset --mixed HEAD

# 重建索引
rm .git/index
git reset

Git 指令速查

基礎操作

git status                      # 查看當前狀態
git add .                       # 添加所有變更
git commit -m "message"         # 提交變更
git push origin main            # 推送到遠端
git pull                        # 拉取更新

分支管理

git branch                      # 查看分支
git switch -c branch-name       # 建立並切換分支
git merge branch-name           # 合併分支
git branch -d branch-name       # 刪除分支

復原操作

git reset HEAD filename.txt     # 撤銷暫存
git restore filename.txt        # 復原檔案
git reset --hard HEAD~1         # 強制回退
git stash                       # 暫存變更

查看資訊

git log --oneline               # 簡潔歷史
git diff                        # 查看差異
git blame filename.txt          # 逐行作者
git remote -v                   # 查看遠端

Git 版本兼容性與舊版指令

指令版本需求

現代指令（Git 2.23+）：

git switch branch-name         # Git 2.23（2019）引入
git restore filename.txt       # Git 2.23（2019）引入

舊版指令（仍然有效）：

git checkout branch-name       # 適用於所有 Git 版本
git checkout filename.txt      # 適用於所有 Git 版本

何時需要使用舊版指令：

• Git 版本 < 2.23：某些預設環境還沒更新到支援 switch/restore 的版本
• CI/CD 系統：許多自動化腳本仍依賴 checkout 指令
• IDE 和工具：某些開發工具內部仍使用 checkout
• 團隊規範：專案可能要求使用舊版指令保持一致性

何時使用舊版指令

git checkout 並未廢棄，仍適用於：

# 檢出特定提交（分離的 HEAD）- switch 無法做到
git checkout commit-hash
git checkout HEAD~2
git checkout tags/v1.0.0

# 從特定提交檢出檔案 - restore 在此有限制
git checkout commit-hash -- filename.txt
git checkout HEAD~3 -- src/config.js

# 從特定提交建立分支
git checkout -b new-branch commit-hash
git checkout -b hotfix tags/v1.0.0

# 稀疏檢出（進階功能）
git checkout --sparse-checkout

# 舊的 CI/CD 系統和腳本
# 某些 IDE 和 Git 工具內部仍使用 checkout

指令能力對照表

何時您必須使用 checkout：

• Git 版本 < 2.23（沒有 switch/restore 可用）
• 檢出特定提交以供探索
• 從任意提交進行複雜檔案復原
• 尚未更新的舊腳本
• 尚未遷移到新指令的 IDE/工具

最佳實踐策略

新專案（Git 2.23+）：

• 分支操作使用 git switch
• 檔案操作使用 git restore
• 進階情境學習 git checkout

舊版系統：

• Git 版本 < 2.23 時堅持使用 git checkout
• 檢查 Git 版本：git --version

團隊環境：

• 建立團隊慣例
• 記錄要使用哪些指令
• 考慮最低公分母方法

檢查您的 Git 版本

# 檢查目前 Git 版本
git --version

# 更新 Git（依系統而定）
# macOS 使用 Homebrew: brew update && brew upgrade git
# Ubuntu/Debian: sudo apt update && sudo apt upgrade git
# Windows: 從 git-scm.com 下載

最低建議版本：

• Git 2.23+（用於 switch/restore 指令）
• Git 2.17+（用於大多數現代功能）
• Git 2.0+（用於基本專業使用）