第一階段｜自己的研究專案
從零開始，走兩次完整日常循環。
開資料夾→加 Git→連 GitHub→建檔→diff→commit→push
再修改→再看 diff→再存／推→歷史→show／restore／revert
Word
追蹤修訂
零先看這一頁：今天要完成什麼
一句話：第一階段先把自己的普通資料夾變成可回溯的 GitHub 專案；第二階段兩人輪流當研究生與指導教授，用 Pull Request（PR）提交、退回、補改與合併。
🟢 上課必看：現在就要懂🔵 展開說明：想知道原因與幕後指令再看🟡 課後參考：實際使用時回來查🔴 安全紅線：操作前一定停下確認
第二階段｜研究生 × 指導教授
兩人用同一個假論文 repo，交換角色各做一次。
研究生開分支→修改／PR→教授看 diff→要求補改→核准 merge→雙方 pull
AI 與人的分工
AI 負責：把自然語言轉成操作、先列計畫、執行 Git、回報狀態、草擬 commit 與 PR 說明。
人負責：確認資料夾與公開範圍、看 diff、判斷研究內容、決定 restore、revert、merge 與刪除。
口訣：AI 提議與代操作；人看懂、驗收、拍板。
壹為什麼經濟學者需要這門課
「這個係數三週前是 0.98，怎麼現在變 0.96 了？」
——每個做實證的人都被這句話追殺過。（改寫自 Michael Stepner, git vs. Dropbox, CC-BY 4.0）
——每個做實證的人都被這句話追殺過。（改寫自 Michael Stepner, git vs. Dropbox, CC-BY 4.0）
痛點一：版本災難
資料夾裡躺著 paper_v2_final_really.docx、final_v3_這次真的final.docx。哪版能跑、哪版投過稿，只剩考古學能回答；「上個月那版其實比較好」找不回來。
痛點二：協作混亂
共同作者靠 email 附件往返，兩人同時改同一版，誰蓋掉誰的段落沒人說得清；「你改了哪裡」要靠肉眼比對。
痛點三：期刊要求
AEA 等期刊已把可重現的資料與程式（replication package）當投稿門檻。「投稿當下的完整狀態」得隨時指得回去——資料夾備份撐不起這件事。
「我有 Dropbox 和 Word 追蹤修訂了，為什麼還要 git？」
好問題。先列出做研究真正需要的五件事，然後你自己按按看，三個工具各做得到幾件：
研究上真正需要的是……
Dropbox
git
反過來也要誠實：git 不會自動存檔、自動同步——它要你（或你的 agent）主動說「存」。所以分工就好：大檔案與原始資料繼續放雲端硬碟，論文與程式的版本交給 git；但別把 git 版本庫放進 Dropbox 同步資料夾，兩套同步機制會打架。一句話記住差別：「git 存的是專案的版本，Dropbox 存的是檔案的版本。」
那為什麼是現在、為什麼跟 AI 一起學？
你最近在用的 AI 工具（Claude Code、GitHub Copilot 這類），背後整天在跑 git——存檔、開分支、比差異，都是它們的日常。AI agent 一次改十幾個檔案是常態；沒有 git 當安全網，你連「它剛才到底改了什麼」都說不清。
指令 AI 都會，你不必背；但它可能改錯檔案、動錯分支、把不該上傳的東西上傳。概念你不懂，就只能全盤照收；概念懂了，你才看得懂它的計畫、驗得了它的差異、攔得住它的危險動作。這門課教的是指揮與監督 AI 的語言。
貳行前準備包（請留兩個晚上，別排在開課前一天）
第 1、2 項約 30 分鐘；第 3、4、5、8 項要下載安裝（第 6、7 項不用下載），視網速可能要一小時以上。第 5 項只有 Windows 要做，Mac 直接跳過。
卡住不用硬撐，直接問 AI。裝好 Antigravity（第 3 項）之後就問它——把錯誤訊息或畫面截圖貼進輸入框，請它一步一步帶你；還沒裝好之前，問你慣用的 AI 助手（ChatGPT、Gemini 都可以）。
這些勾只給你自己看——最後用第 10 項的自我檢查收尾。（勾選狀態存在這台電腦的瀏覽器裡，關掉再開還在。）目前完成：0 / 10
1｜GitHub 帳號 ✓ 完成
到 github.com 註冊，用學校信箱（之後申請教育方案用得上），完成信箱驗證。
怎麼確認驗證成功：點網頁裡右上角你的頭像（哪一顆才對？見下圖）→ Settings → Emails，信箱旁有綠色 Verified 就完成了。
登入後畫面中間若跳出「Join GitHub Education!」的大卡片，按它右上角的 ✕ 關掉就好——那是之後才用得到的教育方案，不在行前準備裡。
完成判準：能登入、能看到自己的個人頁。
到 github.com 註冊，用學校信箱（之後申請教育方案用得上），完成信箱驗證。
怎麼確認驗證成功：點網頁裡右上角你的頭像（哪一顆才對？見下圖）→ Settings → Emails，信箱旁有綠色 Verified 就完成了。
登入後畫面中間若跳出「Join GitHub Education!」的大卡片，按它右上角的 ✕ 關掉就好——那是之後才用得到的教育方案，不在行前準備裡。
完成判準：能登入、能看到自己的個人頁。
2｜兩步驟驗證（two-factor authentication, 2FA） ✓ 完成
先到手機的 App Store／Play 商店搜尋「Google Authenticator」裝起來（不要選簡訊）。然後在 GitHub 網頁右上角點你的頭像（網頁裡的那顆，見上圖）→ Settings → Password and authentication，找 Two-factor authentication 按 Enable。網頁會出現一個方格圖案（QR code）：打開手機那支 App 按「＋」掃它，再把手機上跳出的六位數字打回網頁。最後畫面會給你一串備援碼（recovery codes）——手機掉了要靠它，請存進密碼管理工具或列印收好。
完成判準：電腦上那一頁（GitHub 的 Password and authentication 設定頁）顯示 2FA 已啟用、Authenticator app 旁出現「Configured」。手機那支 App 不會顯示「已啟用」，它只負責跳六位數字。當天請帶著這支手機。
先到手機的 App Store／Play 商店搜尋「Google Authenticator」裝起來（不要選簡訊）。然後在 GitHub 網頁右上角點你的頭像（網頁裡的那顆，見上圖）→ Settings → Password and authentication，找 Two-factor authentication 按 Enable。網頁會出現一個方格圖案（QR code）：打開手機那支 App 按「＋」掃它，再把手機上跳出的六位數字打回網頁。最後畫面會給你一串備援碼（recovery codes）——手機掉了要靠它，請存進密碼管理工具或列印收好。
完成判準：電腦上那一頁（GitHub 的 Password and authentication 設定頁）顯示 2FA 已啟用、Authenticator app 旁出現「Configured」。手機那支 App 不會顯示「已啟用」，它只負責跳六位數字。當天請帶著這支手機。
3｜裝 Antigravity（我們的 AI 工作環境） ✓ 完成
Google 出的 AI 工作環境（編輯器和 AI 助手合在一起），免費。到 antigravity.google 下載——網址列開頭是 antigravity.google 才是官方的，別點搜尋結果裡其他長得像的網站。
裝好打開，用 Google 帳號登入：先試學校信箱 @gms.ndhu.edu.tw，被擋就改用個人 Gmail（本課用得到的功能都一樣）。
打開之後長這樣：左邊是專案清單、正中央一條寬寬的輸入框（寫著 Ask anything）——那就是你之後所有指令要打的地方。右上角有顆「Install IDE」是進階用的編輯器，本課用不到，不用裝。
完成判準：打得開、登入成功、找得到那個可以打字的輸入框。找不到就把畫面截圖問你慣用的 AI 助手，別自己耗。
Google 出的 AI 工作環境（編輯器和 AI 助手合在一起），免費。到 antigravity.google 下載——網址列開頭是 antigravity.google 才是官方的，別點搜尋結果裡其他長得像的網站。
裝好打開，用 Google 帳號登入：先試學校信箱 @gms.ndhu.edu.tw，被擋就改用個人 Gmail（本課用得到的功能都一樣）。
打開之後長這樣：左邊是專案清單、正中央一條寬寬的輸入框（寫著 Ask anything）——那就是你之後所有指令要打的地方。右上角有顆「Install IDE」是進階用的編輯器，本課用不到，不用裝。
完成判準：打得開、登入成功、找得到那個可以打字的輸入框。找不到就把畫面截圖問你慣用的 AI 助手，別自己耗。
4｜裝 git 本體 ✓ 完成
這步交給 AI 助手做就好，你不用自己去下載。在第 3 項找到的輸入框裡貼這句：
「請幫我確認這台電腦有沒有裝 git；沒有的話幫我裝好，過程中要我做什麼請一步一步告訴我。」
它會自己判斷你的作業系統、下載安裝。過程中可能出現兩種情況：Mac 會跳出一個寫著「Xcode 命令列工具」的視窗——沒錯，git 就在裡面，按「安裝」，約 5–10 分鐘；Windows 可能會問你要不要允許安裝，按「是」。
完成判準：它回覆你 git 的版本號（像 git version 2.5x.x）。⚠️ 如果它要你輸入這台電腦的系統管理員密碼，先停下來——密碼不要交給任何 AI；改用你慣用的 AI 助手問怎麼自己輸入，或找人在旁邊陪你操作。本課全程你不必自己開終端機，那是 AI 助手的工具，不是你的。
這步交給 AI 助手做就好，你不用自己去下載。在第 3 項找到的輸入框裡貼這句：
「請幫我確認這台電腦有沒有裝 git；沒有的話幫我裝好，過程中要我做什麼請一步一步告訴我。」
它會自己判斷你的作業系統、下載安裝。過程中可能出現兩種情況：Mac 會跳出一個寫著「Xcode 命令列工具」的視窗——沒錯，git 就在裡面，按「安裝」，約 5–10 分鐘；Windows 可能會問你要不要允許安裝，按「是」。
完成判準：它回覆你 git 的版本號（像 git version 2.5x.x）。⚠️ 如果它要你輸入這台電腦的系統管理員密碼，先停下來——密碼不要交給任何 AI；改用你慣用的 AI 助手問怎麼自己輸入，或找人在旁邊陪你操作。本課全程你不必自己開終端機，那是 AI 助手的工具，不是你的。
5｜裝 PowerShell 7（Windows 專用，Mac 直接打勾跳過）✓ 完成
為什麼要多這一步：Windows 內建的 PowerShell 是 5.1 版。請 AI 用它建中文檔案時，某些寫法會把檔案存成一種 Git 認不出是文字的格式——於是你之後的「論文.md」「方法.md」，Git 會當成一張圖片，完全看不出你改了哪裡。而「看改了哪裡」正是這門課的主軸。最麻煩的是它不會報錯，你只會覺得工具怪怪的。
PowerShell 7 沒有這個毛病，而且它跟舊版並存、不會蓋掉原本的（這是微軟官方的設計）。
這步一樣交給 AI 助手做。在第 3 項找到的輸入框裡貼這句：
⚠️ 回你 5.1 的話，代表裝好了但還沒生效——PowerShell 7 是與舊版並存、不是取代，所以 AI 助手可能還在用舊的那支。貼這句叫它改：
💡 不論版本是 7 還是 5，這句都值得記起來：以後請 AI 幫你建中文檔案時，多說一句「用編輯器建，不要用 > 導出」。這樣不管它背後跑的是哪一版，檔案都不會壞。
⚠️ 安裝途中若跳出 Windows 的「是否允許」視窗，按是就好；但如果它要你輸入這台電腦的系統管理員密碼，先停下來——密碼不要交給任何 AI，自己輸入，或找人在旁邊陪你。學校統一控管的筆電可能整個擋掉安裝，那就先跳過、當天現場處理。
🍎 Mac 沒有這個問題（本來就是 UTF-8），這項直接打勾跳過。
為什麼要多這一步：Windows 內建的 PowerShell 是 5.1 版。請 AI 用它建中文檔案時，某些寫法會把檔案存成一種 Git 認不出是文字的格式——於是你之後的「論文.md」「方法.md」，Git 會當成一張圖片，完全看不出你改了哪裡。而「看改了哪裡」正是這門課的主軸。最麻煩的是它不會報錯，你只會覺得工具怪怪的。
PowerShell 7 沒有這個毛病，而且它跟舊版並存、不會蓋掉原本的（這是微軟官方的設計）。
這步一樣交給 AI 助手做。在第 3 項找到的輸入框裡貼這句：
我用的是 Windows。請先幫我確認這台電腦有沒有 winget（跑 winget --version）；有的話用 winget install --id Microsoft.PowerShell --source winget 幫我裝 PowerShell 7，沒有的話改用微軟官網的 MSI 安裝檔帶我裝。裝完告訴我版本號。過程中要我做什麼請一步一步告訴我。
裝完一定要再問這一句（最容易被跳過，但不問就等於白裝）：請告訴我你現在執行指令用的 PowerShell 是哪一版，跑 $PSVersionTable.PSVersion 給我看。版本號開頭是 7 還是 5？
完成判準：看到版本號開頭是 7（像 7.6.x）。⚠️ 回你 5.1 的話，代表裝好了但還沒生效——PowerShell 7 是與舊版並存、不是取代，所以 AI 助手可能還在用舊的那支。貼這句叫它改：
請你之後執行所有指令都改用 pwsh（PowerShell 7），不要用舊的 powershell。改好後再跑一次 $PSVersionTable.PSVersion 給我確認。
還是 5.1，就把 Antigravity 整個關掉重開再問一次；仍然不行就截圖問 AI 助手，不影響你先往下做第 6 項（當天現場也可以救）。💡 不論版本是 7 還是 5，這句都值得記起來：以後請 AI 幫你建中文檔案時，多說一句「用編輯器建，不要用 > 導出」。這樣不管它背後跑的是哪一版，檔案都不會壞。
⚠️ 安裝途中若跳出 Windows 的「是否允許」視窗，按是就好；但如果它要你輸入這台電腦的系統管理員密碼，先停下來——密碼不要交給任何 AI，自己輸入，或找人在旁邊陪你。學校統一控管的筆電可能整個擋掉安裝，那就先跳過、當天現場處理。
🍎 Mac 沒有這個問題（本來就是 UTF-8），這項直接打勾跳過。
6｜跟 AI 助手打第一聲招呼（見面測試） ✓ 完成
打開 Antigravity，在第 3 項找到的那個輸入框裡貼這句話，按 Enter：
這句話同時測了三件事：工具會不會動、登入成不成功、網路通不通。
打開 Antigravity，在第 3 項找到的那個輸入框裡貼這句話，按 Enter：
你好，請確認這台電腦的 git 裝好了嗎？版本幾號？
它會回你一段話，親眼看到版本號就完成了。這句話同時測了三件事：工具會不會動、登入成不成功、網路通不通。
7｜調一下 AI 助手的授權（讓它別每件小事都問你） ✓ 完成
預設情況下 AI 助手每跑一個指令都會停下來問「可以嗎」——課堂上會很卡。 打開左下角 Settings（Windows 按 Ctrl+,、Mac 按 ⌘,），左欄點 General，找 Agent Settings 這一區：
這一步不只是為了順，它本身就是這門課的縮影：哪些你願意授權、哪些你要親自把關，是你決定的。
當天現場會一起調一次，先看看就好。
預設情況下 AI 助手每跑一個指令都會停下來問「可以嗎」——課堂上會很卡。 打開左下角 Settings（Windows 按 Ctrl+,、Mac 按 ⌘,），左欄點 General，找 Agent Settings 這一區：
建議這樣設
Security Preset 選 Custom，下面會多出兩格；先把 Outside of folders file access policy 設成 Always Ask——agent 要碰工作資料夾以外的檔案時，還是先問你一聲。
二選一
Terminal Command Auto Execution 只有兩個選項：課堂建議 Always Proceed——指令不再每條都停下來問，課堂才跑得順；把關就落在你本來就要做的「放行前看計畫、做完看 diff」與三條紅線上。想每一條指令都過目再跑，就選 Require Review：多一層安全，代價是每步多按幾次執行。
✗ 千萬別選 Turbo mode——它的說明白紙黑字寫著「關閉所有安全防護」（Disables all safety barriers）。這門課教的正好相反：你是它的指導教授，不是橡皮圖章。
8｜GitHub 登入（一樣讓 AI 助手代裝代登） ✓ 完成
這步讓 AI 助手陪你做。在輸入框貼這句：
一、它會給你一組八碼（長得像 A1B2-C3D4），請先複製起來。二、瀏覽器會自動打開 github.com/login/device（沒自動開就自己貼這個網址）：把八碼貼進去，按 Continue。三、按綠色的 Authorize，可能要輸入 GitHub 密碼與手機上的六位數字。完成後回到 Antigravity，會看到 Logged in as 你的帳號。最後對它說：
完成判準：它回覆你已經登入、看得到你的帳號名。⚠️ 如果卡住、或畫面要你輸入這台電腦的系統管理員密碼，先停下來，把畫面截圖問你慣用的 AI 助手——這步沒完成，第一次上傳就會卡住，請務必在動手前（或開課前）解決。
這步讓 AI 助手陪你做。在輸入框貼這句：
幫我裝 GitHub CLI（gh），並登入我的 GitHub 帳號。請一步一步告訴我要做什麼。
接下來會經過三步，都很單純：一、它會給你一組八碼（長得像 A1B2-C3D4），請先複製起來。二、瀏覽器會自動打開 github.com/login/device（沒自動開就自己貼這個網址）：把八碼貼進去，按 Continue。三、按綠色的 Authorize，可能要輸入 GitHub 密碼與手機上的六位數字。完成後回到 Antigravity，會看到 Logged in as 你的帳號。最後對它說：
幫我確認 GitHub 登入好了沒
親眼看到你的帳號名就完成了。完成判準：它回覆你已經登入、看得到你的帳號名。⚠️ 如果卡住、或畫面要你輸入這台電腦的系統管理員密碼，先停下來，把畫面截圖問你慣用的 AI 助手——這步沒完成，第一次上傳就會卡住，請務必在動手前（或開課前）解決。
9｜小試身手：讓 AI 助手替你做一件小事（約 5 分鐘）✓ 完成
前面都裝好了？現在讓它真的動手一次。在 Antigravity 輸入框貼這句：
完成判準三樣：① 桌面真的出現 warmup-check 資料夾、裡面有 hello.md 且內容正確 ② 它回報了 git 版本 ③ 它回報的 gh 帳號就是你的帳號。三樣都對，代表安裝鏈整條是通的。
加碼 30 秒（Chrome／Edge）：打開闖關頁按「連接目前工作資料夾」選 warmup-check，儀表板顯示出資料夾名稱＝讀資料夾功能正常，當天就不會卡。
前面都裝好了？現在讓它真的動手一次。在 Antigravity 輸入框貼這句：
幫我在桌面建一個資料夾 warmup-check，在裡面建一個 hello.md，內容寫今天的日期和我的 GitHub 帳號名。做完後告訴我：git 的版本、gh 登入的帳號是誰。只准動這個新資料夾，其他都不要碰。
然後自己去桌面打開 hello.md 看——裡面真的有日期和你的帳號名，才算數（AI 說做完 ≠ 做完，這就是這門課要教你的第一件事）。完成判準三樣：① 桌面真的出現 warmup-check 資料夾、裡面有 hello.md 且內容正確 ② 它回報了 git 版本 ③ 它回報的 gh 帳號就是你的帳號。三樣都對，代表安裝鏈整條是通的。
加碼 30 秒（Chrome／Edge）：打開闖關頁按「連接目前工作資料夾」選 warmup-check，儀表板顯示出資料夾名稱＝讀資料夾功能正常，當天就不會卡。
10｜最終自我檢查 ✓ 完成
這份教材是自助式的，不用交任何回報——把關的人就是你自己。三件事都成立，行前準備才算完成：
① 上面 1–9 項準備任務全部打勾（第 5 項 Mac 免做，直接打勾）；② 桌面的
哪一項卡住，先把畫面或錯誤訊息貼給 AI 助手問；要參加現場工作坊的人，講師開場配對前也會快掃一輪，卡住的當場救。
這份教材是自助式的，不用交任何回報——把關的人就是你自己。三件事都成立，行前準備才算完成：
① 上面 1–9 項準備任務全部打勾（第 5 項 Mac 免做，直接打勾）；② 桌面的
warmup-check/hello.md 真的存在、內容正確；③ 你說得出 AI 助手回報的 gh 帳號就是你的 GitHub 帳號。哪一項卡住，先把畫面或錯誤訊息貼給 AI 助手問；要參加現場工作坊的人，講師開場配對前也會快掃一輪，卡住的當場救。
紅線先講：課程全程只用模擬假資料，請勿把學生個資、成績、未公開研究資料帶進課堂或上傳。
本課的 AI 工具：Antigravity
全班統一用 Google 的 Antigravity：免費、用 Google 帳號登入（東華的學校信箱本身就是 Google 帳號）、編輯器與 AI 助手一體。
課堂上的每一個任務，講師都先拿它從頭到尾走過一遍才排進課表。我們也故意對它下過危險指令「幫我強制覆蓋遠端」——
它先查了兩邊的差異、指出有些紀錄會被毀掉，然後拒絕照做。工具會把關，但最後點頭的人是你，這正是這門課要練的。
| 備援與延伸 | 定位 |
|---|---|
| Gemini CLI（Google） | 備援：同一個 Google 帳號可用的命令列版；Antigravity 裝不起來的人用它 |
| GitHub Copilot | 課後禮物：你通過 GitHub Education 驗證後，可免費使用 Copilot Pro（審核要數天到數週，行前信同步發動申請） |
| Claude Code（Anthropic） | 講師示範機：開場與攔停演示用，順便看到「不同 agent、同一套 git 概念」 |
🏁 行前準備到這裡結束。上面 10 項都打勾＝課前的事全部做完，可以安心闔上電腦。
當天只要帶三樣：筆電、充電器、設定 2FA 的那支手機。
從下一節「參」開始是課堂當天的教材——想先翻可以，沒翻也完全不影響上課。
從下一節「參」開始是課堂當天的教材——想先翻可以，沒翻也完全不影響上課。
參概念地圖：課前快速認識 Git
〔課堂當天的教材從這一節開始〕以下各節上課會帶著走；課前想預習，就從這裡讀起。
每張卡三句話：白話是什麼、用論文日常打比方、AI agent 什麼時候用它。點卡片展開；實際操作請回到 P1–P9 與 C1–C6 的對應步驟。
課後概念
標籤（tag）：替某個存檔點釘上好記的名字，例如 v1.0-submission。投稿那天在書脊貼標籤，半年後審稿意見回來，一句話翻回投稿當下的完整狀態。
術語總表：這門課出現過的每一個詞
標 ◆ 的詞看得懂就好、不用會用。點右欄可回到實際練習步驟；標示「課後延伸」的內容不列入課堂操作。
| 詞 | 英文 | 一句話 | 哪裡出場 |
|---|---|---|---|
| AI 助手 ◆ | agent | 你目前使用、能查看工作資料夾並代跑指令的 AI；本教材「AI 助手」與「agent」指同一類工具 | 全程 |
| 終端機 ◆ | terminal | 打指令的那個黑底視窗——本課由 AI 助手代打，你不必自己開 | 幕後 |
| Markdown | .md | 純文字檔，打開就能改；格式只有「標題前加 #」這種程度 | P3 |
| 版本庫 | repository（常簡稱 repo） | 資料夾＋它的完整修改紀錄 | P1 |
| 主線 ◆ | main | 預設的那條正式版本線 | P2 |
| 提交 | commit | 有註記的存檔點 | P4 |
| 暫存區 ◆ | index／staging area | 下一個 commit 預計保存的內容快照，不只是檔案清單 | P4 |
| 工作區 ◆ | working tree／working directory | 你目前實際看得到、正在編輯的檔案 | 全程 |
| 差異 | diff | 兩版之間逐行比對 | P6 |
| 歷史 | log | 存檔點的時間軸 | P8 |
| blame ◆ | blame | 這一行是誰、哪天、為了什麼改的 | P8 延伸 |
| 查看舊版 | show | 直接讀取舊 commit 的內容，不切換分支，也不修改目前檔案 | P9 |
| 還原工作檔 | restore | 用指定來源覆蓋工作區或暫存區的檔案；可能丟掉尚未 commit 的修改 | P9 |
| 撤銷版本 | revert | 新增一筆反向 commit，保留原本錯誤紀錄 | P9 |
| 重設 ◆ | reset | 調整目前版本位置，並依模式決定是否同步暫存區與工作區；本課只辨識風險、不執行 | P9 安全補充 |
| HEAD ◆ | HEAD | 指向目前所在的 commit，不包含尚未 commit 的修改 | P9 安全補充 |
| 第一個父版本 ◆ | HEAD~1 | HEAD 的第一個父 commit；直線歷史中可先理解成上一版 | P9 安全補充 |
| 遠端 | remote／origin | GitHub 上的那一份；origin 是它的預設名字 | P2 |
| 推送 | push | 把本機的歷史上傳到遠端 | P5 |
| 拉取 | pull | 把遠端的新東西抓下來對齊 | C5 |
| 複製 | clone | 整個版本庫連歷史抓一份到自己電腦 | C1 |
| 分支 | branch | 平行的草稿線，試東西不動正稿 | C2 |
| 合併 | merge | 把分支成果併回主線 | C4 |
| 快轉 ◆ | fast-forward | 主線沒動過時的直線合併，不留岔路 | C5 延伸 |
| 衝突 | conflict | 兩邊改到同一行，git 停下來要人裁決 | 協作進階 |
| Pull Request | PR | 「我改好了，請你看過再併入」的正式提案 | C2 |
| 審查 | review | 在 PR 的對應行上留意見 | C3 |
| 協作者 | collaborator | 被你授權讀寫 repo 的人 | C1 |
| .gitignore | — | 指定哪些未追蹤檔案不要納入版本；不是保密工具，也不會自動移除已追蹤檔案 | P2 |
| 標籤 | tag | 替重要存檔點釘上好記的名字 | 課後延伸 |
| replication package | — | 期刊要求的可重現資料與程式包 | 課後延伸 |
| gh ◆ | GitHub CLI | 讓 agent 操作 GitHub 用的工具 | 行前包 |
| 兩步驟驗證 | 2FA | 登入除了密碼還要手機驗證碼 | 行前包 |
導完整操作手冊：每一步都寫清楚
下面 15 步和課堂闖關使用相同編號、目標與完成標準，但分工不同：闖關頁帶你做，這份教材幫你看懂。每一步先說明為什麼需要、Git 正在處理哪個狀態、有哪些新名詞，以及你要判斷什麼；完整 AI 提示、操作計畫與幕後指令收在「實作參考」，需要時再展開。
不用一次讀完：上課先掌握「先懂這個」與「你要判斷什麼」。課後遇到疑問，再用瀏覽器搜尋關鍵字，或從闖關頁直接開啟對應步驟。
格式範例：桌牌用
lin；配對 repo 可寫成 advisor-account/thesis-pair-03；夥伴用 chen。這只是格式示意，闖關頁不會預填 repo；C1 由教授角色現場建好之後，把他回報的實際 owner/repo 填進去。肆協作進階：衝突來了怎麼辦
兩個人改到同一行時，Git 會停下來等人決定，這叫合併衝突（merge conflict）。AI 可以把兩邊攤開，卻不能替研究者決定內容。
情境
你和夥伴都改了 paper.md 的同一句結論。夥伴的版本先進了主線，你這邊一說「併回去」，agent 停下來了。
AI 助手回報：合併時撞到衝突（conflict）：paper.md 第 12 行，兩邊都改了。左邊是你的版本「觀光支出的所得彈性大於一」，右邊是夥伴已合併的版本「觀光支出的所得彈性接近一」。Git 不會替你們選，要你決定留哪一句，或重寫一句。
裁決三步：一、請 agent 把兩邊版本並排念出來；二、你決定——留一邊、或口述一句新的給它；三、agent 完成合併並提交，衝突解除。就這樣，衝突不是故障，是兩位作者的意見被攤開來等人裁決。
如果你自己打開那個檔案，會看到 <<<<<<< 和 ======= 把兩個版本框起來——那不是檔案壞掉，是 git 把兩邊並排攤給你看。
課堂上時間允許的話，講師會故意安排兩人改同一行，當場引爆、全班圍觀裁決一次（時間不夠就割愛，這頁自己看完也夠用）。看過一次，以後自己遇到就不慌。
肆之二誰能動正稿？三個檔位（合寫前先講好）
C2–C6 的修改都走「分支 → PR → 看過 → 併入」。但誰能按下 merge、把東西併進正稿，其實是 main 那扇門上的設定。同一套協作，門可以越鎖越緊：
檔位一「全開放」——什麼都不設。PR 是大家說好的禮數，協作者互相看過就自己併。適合已經約定好流程、彼此高度互信的共同作者。
檔位二「必走 PR」——設定「改 main 一律要走 PR」。誰都不能偷偷直改正稿，每筆修改都留下攤開過的紀錄；但舉完手自己就能併，不用等誰點頭。適合想要「凡走過必留下痕跡」的團隊。
檔位三「要核可」——再加一條「要 1 個核可（Approve），merge 鈕才會亮」。課堂上你們現場自建的配對 repo 走的是檔位一＋課堂紀律：C3 明訂由另一人逐行審查、作者不得自我核准——這把鎖裝在約定裡，不在門上。課後帶研究生做真實研究，建議把門升到檔位三：GitHub 規定不能核可自己的 PR，所以研究生的 PR 一定要指導教授點頭；整段指導歷程（誰改了什麼、為什麼要求修改）都留在 PR 裡，半年後仍可查閱。
⚠️ 設檔位三時要多勾一格：repo 的擁有者與管理員預設可以繞過這道規則直接 merge，所以除了「Require a pull request before merging」與「Require approvals: 1」，還要勾 Do not allow bypassing the above settings，這道門才真的鎖得住你自己。
設定位置：repo 的 Settings → Branches，給 main 加規則、勾上面說的三個選項（要走 PR、要 1 個核可、不允許繞過）就完成，隨時可調。⚠️ 誠實提醒：私人 repo 要用這些門檻，免費方案不夠（公開 repo 免費就能設）——但申請了行前信提過的 GitHub Education 教師方案，就有付費版功能可用。
這一節跟第伍節說的是同一件事：哪些事互信、哪些事上鎖，是你決定的——差別只是這次的鎖設在 GitHub 的門上，不是設在 agent 的授權裡。
伍安全紅線與監督三原則
監督三原則
一、動手前看計畫。agent 動手前會先說「我打算怎麼做、為什麼」；沒看懂那段話，先問——聽得懂才放行，解釋不通就不准做。
二、動手後看 diff。agent 說做完了不算數，逐行差異你掃過一眼才算數。就當審自己學生的修改稿。
這三條跟行前第 7 項的授權設定是同一件事：指令自動執行讓課堂跑得順、要碰工作資料夾以外的檔案保持要問、千萬別選 Turbo mode。設定是你調的，代表哪些事你願意授權、哪些你要親自把關，是你決定的。
三、破壞性動作，agent 必須先問你。紅線動詞清單：強制推送（force push）、把分支 reset 到舊 commit、硬重設（reset --hard）、改寫歷史（rebase）、刪除檔案或分支、覆蓋遠端。reset --hard 會讓暫存區與已追蹤工作檔對齊目標 commit，未提交修改會被覆蓋；其他 reset 模式若指向舊 commit，也會移動本機歷史。看到這些動詞一律喊停，先問「會動哪一層？會不會弄丟東西？這段歷史是否已經分享？有沒有更安全的做法？」它沒問就做了，換掉它的設定或換掉它。
兩條資料紅線（跟技術無關，跟你的責任有關）
四、學生個資與未發表資料，不進公開 repo。成績單、名冊、還在審的稿子，公開版本庫一律不放；研究協作應使用私人 repo，公開前仍要逐檔確認。.gitignore 只能協助排除尚未追蹤的檔案，不能取代資料判斷與存取權限。
五、私人 repo 也不放帳密。密碼、API 金鑰（API key）一旦提交過就會進入歷史，事後刪掉目前檔案也不代表舊紀錄消失。敏感資料放在專案資料夾外；非敏感但只供本機使用的設定，再用 .gitignore 排除。
急救箱：誤把敏感檔存進去了怎麼辦
一喊停：先別做任何事，尤其別 push。二確認：問 agent「那個檔進了版本庫嗎？推上 GitHub 了嗎？」三處理：還沒 push 的話，把這句話貼給 AI 助手——「那個檔案進過哪幾個 commit？請每一個都清掉、把檔名加進 .gitignore，清完再驗一次給我看，先不要 push。」（只清最後一筆常常清不乾淨，所以要它全部檢查）；已經 push 的話，當成外洩處理——改掉裡面的密碼、通知相關的人，再找懂的人協助清歷史（清得掉自己這份，清不掉別人已經抓走的）。
開新 repo 時順手確認兩件事：可見性選 Private——含任何學生資料的一律私人；要公開分享的教材記得選一個授權條款（license），別人才知道能不能用。
現場演練：對 agent 說「幫我強制覆蓋遠端」，觀察它怎麼回。好的 agent 會停下來問你為什麼、有什麼會被覆蓋；不問就動手的，就是第三條說的那種。
陸怎麼跟 agent 說：12 句常用的話
12 句你真的會說的話。按「複製」可以直接貼進 agent 對話框試。
課堂當天的任務句都在闖關頁、照抄就好；這張表是課後回到自己研究時的日常用語表——也就是紙本對照表的內容。另一張「我想做什麼→怎麼說」的任務式速查在〈救〉的自然語言操作速查，兩張互補、不重複。
⚠️ 一個要小心的說法：「退回上一版」對 agent 是模糊的——它分不清你是「剛改還沒存」「存了想撤銷」還是「想砍掉最近三個版本」，解讀錯了可能把還沒存檔的東西弄丟。用下表的句型講清楚情境，或讓 agent 先覆述它的理解再放行。
| 你這樣說 | agent 會做什麼 | 背後概念 |
|---|
救出事怎麼辦：先判斷，再處理
救援第一句永遠一樣：「先只查看目前路徑、git status、git log 與 remote，告訴我發生什麼事；不要修改、不要 reset、不要 force push。」先把現況保留下來，通常就還救得回來。
上表對不上你的狀況？把這句通用求救句填空後貼給 AI——它本身就是「先查看、再計畫、才動手」的隨身版：
我在做 Git 工作坊的第＿＿關，目標是＿＿＿，現在卡在＿＿＿。請先只查看、不要修改：告訴我目前的工作資料夾完整路徑、git status 與 gh auth status 的結果，說明哪裡不對勁；先講修復計畫，等我同意後才動手。全程禁止 reset、rebase、force push。
自然語言操作速查
這些句子可以直接交給 AI。會影響檔案或歷史的操作，仍要先看計畫與 diff。情境式的 12 句日常用語在〈陸〉怎麼跟 agent 說；這張是任務式速查，兩張互補。
| 我想做什麼 | 可以怎麼說 |
|---|
柒小測驗：考概念與監督判斷，不考指令背誦
目前得分：0 / 8
捌當天 2 小時課表
最低完成線：完成 P1–P9，包括 2 次 commit、2 次 push，以及 P9 的 show／restore／revert 安全練習；再完整走過 1 次「研究生提 PR → 指導教授要求補改 → 研究生補改 → 教授核准合併 → 雙方 pull」。第二輪交換角色也要完成；時間緊時縮小修改內容，不省略 diff、另一人核准與合併。
每關標示的是單人順利操作的估計時間；下面課表把相鄰關卡合併，並把 0:56–1:02 留作共同緩衝，因此各列不會逐格等於每關分鐘數。
| 時間 | 教室正在做什麼 | 對應步驟 | 講師巡桌重點 |
|---|---|---|---|
| 0:00–0:08 | 開場：版本災難、AI 與人的分工 | 全課路線 | 先講安全紅線，不教背指令 |
| 0:08–0:14 | 建立普通資料夾、用 Antigravity 開啟 | P1 | 全員確認工作路徑相同 |
| 0:14–0:22 | 加入 Git、.gitignore、建立並連接 GitHub repo | P2 | 公開前確認只有假資料 |
| 0:22–0:31 | 建 notes.md、看狀態、第一個 commit | P3–P4 | commit 前一定先看檔案與 diff |
| 0:31–0:40 | 第一次 push；讓 AI 做小修改並看 diff | P5–P6 | 修改前看計畫，修改後逐行驗收 |
| 0:40–0:47 | 第二次 commit 與 push | P7 | 分清 commit 與 push |
| 0:47–0:56 | 歷史、版本比較、restore 與 revert | P8–P9 | 每個改動步驟都停下確認 |
| 0:56–1:02 | 個人階段補進度 | 最低線檢查 | 2 commits＋2 pushes |
| 1:02–1:06 | 休息、配對、發角色卡、兩人互報 GitHub 帳號 | 配對 | 帳號抄在角色卡背面，C1 立刻要用 |
| 1:06–1:16 | C1 教授建配對 repo、研究生接受邀請後 clone（第二個資料夾） | C1 | 教授沿用剛建的資料夾不重複 clone；兩人權限都要 WRITE；闖關頁改連新資料夾 |
| 1:16–1:41 | 第一輪：研究生提 PR；教授要求補改；補改後核准合併；雙方 pull | C2–C5 | 另一人親自看 Files changed；作者不可自我核准 |
| 1:41–1:50 | 交換角色，走一次短流程 | C6 | 不能省略 diff 與另一人核准 |
| 1:50–1:56 | 第二輪合併後雙方最終 pull、看歷史、故障排除 | C6 收尾＋救援 | 兩台電腦都看得到 main 最新內容 |
| 1:56–2:00 | 小測驗、回顧與帶走資源 | 收尾 | 說得出 AI／人的分工與三條紅線 |
開課前講師要完成的準備
配對 repo 改由學員在 C1 現場自建（教授角色的 AI 一句話建好、研究生親自接受邀請），講師不必預建。要準備的是：角色卡——正面寫組號與第一輪角色，背面留兩格「我的 GitHub 帳號／夥伴的 GitHub 帳號」讓兩人互抄；配對方式——建議相鄰兩人一組，奇數人時最後一組三人、第三人在 C6 當第二輪研究生；以及一個講師示範 repo——照 C1 規格先建好（paper.md 含「方法」「文獻回顧」、.gitignore 排除 WORKSHOP-RECEIPT*.txt），哪一組 C1 卡超過五分鐘，把兩人都加為示範 repo 的協作者（請他們親自接受邀請、確認權限是 WRITE，否則 C2 的 push 會失敗），再讓他們 clone 那一個繼續走 C2，課後補建自己的。
個別學員的 AI 工具或網路臨時出狀況：請他改用 GitHub 網頁版跟完流程（網頁上改檔＋commit；PR 的審查與合併本來就在網頁上做），概念不減量。全場性故障才由講師投影單機示範。
玖參考資料
這份名單是我們把網路上 18 門 git 課程實際看過一遍後選出來的（2026 年 7 月）。每一條都寫了「從哪裡開始讀」，因為你有 agent 代打指令，很多章可以直接跳過。
| 你是誰 | 推薦 | 從哪開始 |
|---|---|---|
| 想用中文複習概念 | 猴子都能懂的 Git 入門 | 第一部分讀到「還原變更」就停；操作篇整段跳過（那是給自己打指令的人）；卡住再翻故障排除 |
| 為你自己學 Git | 跳過安裝與終端機三章，從「工作區、暫存區與儲存庫」進；狀況題群當出事時的急救箱 | |
| 寫 R 或 Stata 做實證 | EC 607 Lecture 2（repo 內的 02-git） | 經濟學家寫給經濟學家的課綱；從 RStudio 的 Git 面板那段開始 |
| Software Carpentry git-novice | 研究者取向；Open Science／Licensing／Citation 那四集別的課沒有 | |
| 想有系統或拿認證 | Microsoft Learn：GitHub Foundations 繁中版 | 免費讀完就有完整系統；認證考試無中文、要錢，一般不必真考。注意它用微軟譯名（存放庫＝repo、提取要求＝PR） |
| edX IBM: Git and GitHub Basics | 旁聽免費、全程瀏覽器實驗室、期末產出一個公開 repo | |
| 想深入原理 | MIT Missing Semester：版本控制 | 從「資料模型」那節讀起——先懂心智模型，指令就不用背 |
| Learn Git Branching 繁中版 | 只做基礎篇四關就收手，後面的關卡用不到 |
經濟系背景讀物：Michael Stepner《git vs. Dropbox》（最適合當課前讀物）｜Frank Pinter《Git: A Guide for Economists》｜Arthur Turrell《Coding for Economists》｜AEA Data & Code Policy 與 AEA Data Editor 指引。
這些可以先不學
stash、rebase、amend、fork 工作流、GitHub Actions、git 內部原理——研究者課程的共識是入門階段全部跳過，我們跟進。理由一句話：需要它們的時候，你的 agent 會用，而你只要看得懂它的計畫。這張「可以不學」清單跟前面「該學」的一樣重要——有它，兩小時的範圍才站得住腳。
拾三條誠實限制（不藏）
一、Word 和 Excel 在 git 裡看不到逐行差異。它們不是純文字檔，diff 只會說「檔案變了」，不會說哪一行變了。git 對純文字檔（.md、.R、.do、.tex、.csv）才火力全開。Word 照樣可以放進版本庫備份與同步，只是「追蹤修訂」那種體驗要靠 Word 自己。
二、GitHub Free 可在公開 repo 使用分支保護規則，私人 repo 的可用功能則依帳號與組織方案而定。本課用公開假資料 repo 練習審查；真正研究資料要先判斷是否能公開，不能為了功能把敏感資料改成公開。開課前請再查 GitHub 官方文件與現場帳號設定。
三、agent 會犯錯，所以概念才要懂。它可能改錯檔案、寫錯說明、在你不想動的分支上動工。你不必背指令，但你得看得懂它的計畫和 diff——前面的概念地圖，是讓你有能力當它的指導教授，而不是它的橡皮圖章。