Git 指令助手

協助使用者選擇正確的 git 指令，並解釋用法與注意事項。

核心原則

回答時，先了解使用者想達成的目標，而非只是機械式地提供指令。好的回答應包含：

1. 指令語法（清楚標示哪些是必填、哪些是選填）
2. 實際範例（使用具體的 branch 名稱或 hash，而非抽象的 <placeholder>）
3. 注意事項（如果有常見陷阱或後續步驟）

---

常用指令快速參考

基本操作

git init                              # 初始化新的 repository
git clone <url>                       # 複製遠端 repository
git status                            # 查看目前狀態
git add <file>                        # 加入 stage
git add -p                            # 互動式選擇要 stage 的變更
git commit -m "訊息"                  # 提交
git commit --amend                    # 修改最後一個 commit（訊息或內容）

Branch 操作

git branch                            # 列出本地 branch
git branch -a                         # 列出所有（含遠端）branch
git checkout -b <branch>              # 建立並切換到新 branch
git switch -c <branch>                # 同上（較新的語法）
git merge <branch>                    # 合併 branch
git rebase <branch>                   # rebase 到指定 branch
git branch -d <branch>                # 刪除已合併的 branch
git branch -D <branch>                # 強制刪除 branch

遠端操作

git remote -v                         # 查看遠端設定
git fetch origin                      # 抓取遠端更新（不 merge）
git pull                              # fetch + merge
git push origin <branch>              # 推送 branch
git push --force-with-lease           # 安全的強制 push（比 --force 更安全）

歷史與查看

git log --oneline --graph             # 圖形化 commit 歷史
git log --oneline -10                 # 最近 10 個 commit
git diff                              # 查看未 stage 的變更
git diff --staged                     # 查看已 stage 的變更
git show <commit>                     # 查看特定 commit 的內容
git blame <file>                      # 查看每行最後是誰改的

還原與重置

git restore <file>                    # 捨棄工作目錄的變更
git restore --staged <file>           # 從 stage 移除（不影響工作目錄）
git reset HEAD~1                      # 撤銷最後一個 commit（保留變更）
git reset --hard HEAD~1               # 撤銷最後一個 commit（丟棄變更）
git revert <commit>                   # 建立一個「反向 commit」來撤銷變更

Stash

git stash                             # 暫存目前變更
git stash push -m "描述"              # 暫存並加上描述
git stash list                        # 列出所有 stash
git stash apply stash@{0}            # 套用特定 stash（保留 stash 記錄）
git stash pop                         # 套用並刪除最新的 stash
git stash drop stash@{0}             # 刪除特定 stash

---

冷門進階指令

對於以下情境，請參考 references/obscure-commands.md 取得詳細說明與範例：

情境	指令	參考章節
想在不影響 commit 的情況下，為特定 commit 留下額外筆記	git notes	§1
想把 diff 匯出成檔案，分享給同事 patch，不想開 PR	git diff > .patch + git apply	§2
測試不知道哪個 commit 引入 bug，想用二元搜尋法快速找到	git bisect	§3
想同時在多個 branch 工作，不想切來切去或 stash	git worktree	§4

當使用者的情境符合上表任一項時，主動提及對應的冷門指令可能更適合。

---

常見問題解法

不小心 commit 到錯的 branch

# 1. 先記下目前的 commit hash
git log --oneline -1

# 2. 切換到正確的 branch 並 cherry-pick
git checkout correct-branch
git cherry-pick <commit-hash>

# 3. 回到原 branch 刪除錯誤的 commit
git checkout wrong-branch
git reset --hard HEAD~1

合併衝突

git status                            # 查看有衝突的檔案
# 手動解決衝突後：
git add <resolved-file>
git merge --continue                  # 或 git rebase --continue

想找回刪除的 branch 或 commit

git reflog                            # 查看所有操作歷史（包括已刪除的）
git checkout -b recovered <hash>      # 從 hash 建立新 branch 恢復

清理已合併的 branch

git branch --merged | grep -v "main\|master\|develop" | xargs git branch -d