為啥要版本控制

軟體開發包含持續的修改，而每次修改都可能破壞既有行為。使用 AI 協助開發時，一次任務可能涉及多個檔案，更需要在修改前保存已確認可用的狀態。若只保留最新的檔案，修改失敗後便缺少可供回復的依據。版本控制的目的，就是有系統地保存這些變更紀錄。

版本控制帶來何種幫助

• 比較差異：確認一次修改涉及哪些檔案，以及新增、刪除或調整了哪些內容。例如，AI 完成功能後，可以透過差異檢查它是否修改了與任務無關的程式。
• 追蹤歷史：查閱各次提交的內容與說明，了解程式如何演變。若提交說明記錄了修改原因，也能幫助後續開發者理解當時的決定。
• 回復內容：修改不符合預期時，可以取回先前保存的內容，或撤銷特定變更。這項能力依賴事先保存的版本；尚未納入紀錄的內容，不一定能夠還原。

這些用途也適用於技術文件、設定檔與文章。例如，本系列的文章便可以透過版本控制比較各次修訂，並在需要時取回先前的文字。

what is Git

Git 是一套分散式版本控制系統，也是實作前述版本管理方式的工具之一。它以儲存庫（repository）管理專案的版本紀錄，讓開發者能夠保存檔案狀態、比較變更與查閱歷史。

在 Git 中，提交（commit）是保存版本的基本單位。每次提交會記錄當時納入版本的檔案狀態，以及作者、時間與提交說明。開發者可以選擇要納入的修改，再建立提交；編輯或儲存檔案本身，不會自動產生新的提交。

Git 的基本版本控制操作可以在本機完成，不需要網路連線或 GitHub 帳號。GitHub 則是託管 Git 儲存庫並提供協作功能的平台。單人開發時，可以先在本機使用 Git，待需要分享專案或與他人協作時，再使用遠端託管服務。

若尚未安裝 Git，可以依照 Git 官方安裝頁面中對應作業系統的說明完成安裝。

單人開發的 Git 基本流程

以下用一份待辦事項文件示範如何建立儲存庫、檢查修改並保存版本。範例假設已安裝 Git 與 VS Code，所有檔案編輯與 Git 指令都在同一個練習目錄中進行。操作以指令為主，檔案狀態與內容差異則搭配 VS Code 的畫面說明。

建立儲存庫：git init

先建立新的練習目錄，進入目錄後初始化儲存庫：

mkdir git-practice
cd git-practice
git init

git init 會在此目錄下建立 .git，用來保存 Git 的版本紀錄與設定。此時只是建立了儲存庫，還沒有任何提交；目錄中的檔案也不會因此自動被納入版本。Git 官方文件：git init

提交需要記錄作者姓名與電子郵件。以下設定只套用於目前的儲存庫，請將範例值替換成自己的資料；這些資料用於提交紀錄，不是登入帳號：

git config --local user.name "Your Name"
git config --local user.email "you@example.com"

Git 也支援用 --global 設定同一使用者的預設資料；此處使用儲存庫內的設定即可。Git 官方說明：初次設定

檢查修改：git status 與 VS Code

在 VS Code 中開啟 git-practice 資料夾，建立 todo.md，填入以下內容並存檔：

# 待辦事項

- [ ] 撰寫 Day5 草稿

執行以下指令查看目前狀態：

git status

預期會看到 todo.md 列在未追蹤檔案（untracked files）中，表示檔案已存在於目錄中，但尚未納入 Git 追蹤。建立並儲存檔案，不會自動將它加入版本紀錄。

VS Code 內建的原始檔控制（Source Control）面板也會顯示這些檔案狀態。開啟左側的 Source Control 面板，預期會在 Changes 清單中看到 todo.md，旁邊的 U 表示未追蹤。點選檔案即可檢查內容；目前是新檔案，尚無已提交的舊版本可供比較。VS Code 官方說明：查看變更

保存版本：git add / git commit

一次開發可能同時產生多項修改，但這些修改未必屬於同一個目的。提交之前，需要先選擇這次要保存的內容，避免將無關的修改混在一起。

Git 使用暫存區（staging area）準備下一次提交的內容。工作目錄是平常建立、編輯檔案的地方；暫存區則記錄選定的檔案狀態。git add 用來將指定檔案當下的內容記入暫存區，git commit 再將暫存區的狀態保存成版本。加入暫存區不會把檔案搬離工作目錄。Git 官方文件：git add

這裡需要區分三種情況：

• 未追蹤檔案（untracked）：尚未納入 Git 追蹤的新檔案，例如目前的 todo.md。
• 尚未暫存的修改（unstaged changes）：已追蹤檔案在工作目錄中的內容，與暫存區不同。例如，修改已提交的檔案後，尚未執行 git add。
• 已暫存的修改（staged changes）：已加入暫存區、相較於最近一次提交有所變動的內容，會納入下一次提交。若尚未建立任何提交，已暫存的新檔案便是第一個版本的內容。

先將 todo.md 加入暫存區：

git add todo.md

VScode上可用＋執行 git add

第一次對新檔案執行 git add，會開始追蹤並暫存它的內容。再次檢查狀態：

git status

預期 todo.md 會從未追蹤檔案移到待提交的變更（changes to be committed）中。在 VS Code 中，同一個檔案則會從 Changes 移到 Staged Changes，表示內容已暫存、準備提交。終端機與 VS Code 顯示的是同一個儲存庫的狀態。VS Code 官方說明：原始檔控制

若執行 git add 後又繼續編輯，同一個檔案就可能同時有已暫存與未暫存的修改：暫存區仍保留執行 git add 當下的內容，後續編輯則留在工作目錄中。需要再次執行 git add，才會將後續修改也納入下一次提交。這與檔案尚未被追蹤的情況不同。Git 官方文件：git status

提交之前，在 VS Code 的 Staged Changes 清單中點選 todo.md，檢查本次準備提交的內容。由於儲存庫還沒有任何提交，預期整份文件都會被標示為新增。

查看差異時，應確認自己點選的是哪個清單：Changes 中的已追蹤檔案用來查看尚未暫存的修改；Staged Changes 則用來查看已暫存、將納入下一次提交的修改。提交前應檢查後者，避免把尚未暫存的內容誤認為已經準備提交。

確認內容後，建立第一個提交：

git commit -m "新增文章待辦清單"

-m 用來指定提交說明。這次提交會保存已暫存的內容；未暫存的修改不會被一起保存。提交完成後執行 git status，預期會顯示工作目錄乾淨（working tree clean），代表在這個範例中已沒有待提交的變更。Git 官方文件：git commit

接著在 todo.md 末尾新增一行並存檔：

- [ ] 校對 Git 指令範例

再次檢查檔案狀態：

git status

這次檔案已被追蹤，預期 git status 會列出尚未暫存的修改。VS Code 的 Changes 清單中，todo.md 旁會顯示 M，表示已修改。點選檔案開啟差異檢視器，即可比較修改前後的內容；預期會看到新增的「校對 Git 指令範例」這一行。VS Code 官方說明：檢查差異

確認修改後，將內容加入暫存區：

git add todo.md

再從 Staged Changes 開啟檔案，確認準備提交的內容符合預期，然後建立第二個提交：

git commit -m "新增 Git 指令校對事項"

查看歷史：git log

完成兩次提交後，可以查看提交紀錄：

git log --oneline

--oneline 將每個提交顯示為一行，包含縮短的提交識別碼與提交說明。在本例中，預期會依序看到「新增 Git 指令校對事項」與「新增文章待辦清單」，較新的提交排在前面。識別碼由 Git 產生，實際值會隨提交內容與時間等資料而不同。Git 官方文件：git log

若需要查看作者、日期與完整提交說明，可以直接執行 git log。若終端機進入分頁檢視畫面，可按 q 離開。

撤銷最近一次提交：git revert

已經提交的修改，可以使用 git revert 撤銷。Git 會新增一筆提交，反向套用指定提交的變更，原本的提交紀錄仍會保留。Git 官方文件：git revert

沿用前面的範例，假設現在決定移除剛加入的「校對 Git 指令範例」事項。先確認目前狀態與最近的提交：

git status
git log --oneline

確認工作目錄乾淨，且最新一筆提交是「新增 Git 指令校對事項」後，執行以下指令。這會撤銷該次提交新增的待辦事項，並自動建立撤銷紀錄：

git revert --no-edit HEAD

HEAD 在此代表目前所在的最新提交；--no-edit 表示使用 Git 產生的提交說明，不另外開啟編輯器。執行後，todo.md 預期只剩下「撰寫 Day5 草稿」這一項，原本的兩筆提交仍然存在。

再次執行 git log --oneline，預期最上方會多出一筆 Revert "新增 Git 指令校對事項"。這筆紀錄說明了哪次變更被撤銷，也保留了完整的修改過程。

讓 AI 協助版本管理

理解版本控制的基本流程後，可以讓具備檔案讀取與指令執行能力的 AI Agent 協助操作。指示中應說明要處理的修改範圍、目標版本與預期結果。以下是幾種常見的使用方式，檔案名稱與提交識別碼需依實際專案調整。

• 整理修改內容：「檢查目前尚未提交的修改，包含已暫存、未暫存與未追蹤的檔案。整理各個檔案改了什麼，並且回報。」AI 可以先協助整理變更，再由我們搭配 VS Code 的差異畫面確認內容。

• 建立提交：「將這次新增校對事項的修改建立成一筆提交，提交說明要描述修改目的。完成後回報提交識別碼與納入的檔案。」明確指定範圍，能讓 AI 有依據選擇提交內容，避免將無關修改混在一起。

• 比較兩個版本：「幫我比較這一版跟上一版差在哪裡。」AI 可以協助整理兩個版本之間的內容變化；若對話中還無法確定比較的版本，再補上提交識別碼即可。修改原因則需要搭配提交說明與其他紀錄理解。

• 撤銷指定提交：「檢查目前是否有尚未提交的修改；若有，先回報狀態。若工作目錄乾淨，撤銷提交 A，完成後回報檔案變化與新增的提交紀錄。」以提交識別碼指定目標，可以避免「改回去」所指的版本不明確。

實際開發時，可以在完成一項修改後，讓 AI 整理差異並協助建立提交；需要追查問題時，再請它比較指定版本或執行撤銷。Git 提供可查閱的版本紀錄，AI 則協助整理資訊與執行操作。哪些修改應該保存、哪些變更需要撤銷，仍需要我們根據需求決定，並確認操作結果符合預期。