graphify watch / update / hook 指令詳解 · Graphify

指令用途

建一次圖譜很慢（特別是大 monorepo）。graphify 的「增量同步三兄弟」可讓圖譜與程式碼持續同步，避免每次都 full rebuild：

指令	觸發時機	用途
`graphify update`	手動觸發增量重建	只重抓變動過的檔、最小化成本
`graphify watch`	檔案系統事件觸發	即時 AST 增量同步
`graphify hook install`	git post-commit / post-checkout 觸發	自動重建 + `graph.json` merge driver

update：手動增量重建

基本用法

# 對當前 corpus 增量重建（依檔案 mtime / hash 判斷變動）
graphify update ./src

# 等同
graphify extract . --update

v0.9.42 起增量偵測涵蓋「同長度重寫」：若檔案在同一 mtime tick 內被改寫成相同長度，仍會重新排入佇列，不再因 hash 未變而漏掉（#2466）。配合既有的 file-hash guard，正常編輯不會重複萃取。

強制某些情境

# 跳過 Leiden 分群，只更新 AST 邊
graphify update ./src --no-cluster

# 強制覆寫（節點較少也願意寫，例如清理幽靈 / refactor 後）
graphify update ./src --force

# 強制以另一 corpus root 計算相對路徑
graphify update ./src --graph ../shared/graph.json

`--check-update` 純檢查不重建

# 只回報哪些檔案變動了，不寫 graph.json
graphify check-update ./src

watch：檔案變動即時同步

graphify watch ./src

watch 啟動檔案系統監聽；檔案一變就觸發 AST-only 增量重建，graph.json 持續保持最新。適合：

開發中想讓助理讀到的圖譜永遠反映當前編輯狀態
跑 IDE 同時開 watch，devloop 變很短

注意：watch 預設只更新 AST 邊（不重算 LLM 語意層，避免每次存檔就花 token）。

Windows 上的 timeout 修正（v0.9.32）

graphify v0.9.32 延續了 Windows 上 GRAPHIFY_REBUILD_TIMEOUT 的 threading.Timer fallback；這讓 hook rebuild 不依賴 Unix-only 的 signal.SIGALRM。¹

hook install：git commit / checkout 自動重建

graphify hook install

寫入：

post-commit hook — 每次 git commit 後自動執行 AST-only 重建（零 API 成本）
post-checkout hook — 切 branch 時重建圖譜，確保助理看到的是當前 branch 的 code
git merge driver — graphify-out/graph.json 使用 merge=graphify driver，使兩人平行 commit graphify-out/ 時 union-merged，永不出現 conflict marker

反安裝 hook

graphify hook uninstall
graphify hook status

團隊工作流：commit `graphify-out/`

graphify 設計上鼓勵把 graphify-out/ commit 進 repo，讓團隊每個人 clone 後立刻拿到地圖：

一人建圖 — 跑 /graphify .，commit graphify-out/
其他人 pull — 助理立即可讀
每人都 graphify hook install — 任何 commit 自動重建
docs 變動才需 LLM — /graphify --update 刷新 semantic node

建議的 .gitignore 排除：

graphify-out/cost.json        # local only
# graphify-out/cache/         # 可選：commit 提速 / 不 commit 節省 repo 大小

manifest.json 自 v0.9.18 起以 root-relative path 鍵值儲存，可安全 commit。²

範例：團隊 monorepo 上持續同步

# 進 repo
cd ~/my-monorepo

# 一次性設定
graphify claude install --project      # 寫助理 skill
graphify hook install                  # 寫 post-commit hook + merge driver

# 開發時搭配 watch 即時更新
graphify watch ./services/auth

開發完 commit：

git add services/auth/login.py
git commit -m "feat(auth): add rate limit"
# → post-commit hook 自動重建 AST 圖譜，graph.json 更新成最新狀態

內部連結與外部參考

官方 README「Team setup」
官方 README「Common commands」: --watch / hook install
上一章：graphify install 指令詳解

下一步

v0.9.55～v0.9.56：增量同步與 hook 的可靠性修正

近期 patch 對長時間開著 watch / hook 的專案有幾個重要修正：

code-only watch rebuild 不會再把 pending semantic update flag 清掉，docs / paper 等待語意重萃取的工作不會被一次 AST rebuild 吃掉。
no-cluster mode 也會正確 disambiguate 相同 basename 的檔案。
git hook 判定「本次要 skip」時改在 subshell 執行，不會把同一個 hook 檔後面串接的其他工具一起終止。
rebuild watchdog timeout 會先結束 spawned extraction workers，避免留下 orphan process。

升到 v0.9.56 後，若你的 graph 長期由 watch / hook 維護，建議做一次完整 graphify update，確認 manifest 與 graph 都由新版 resolver 接手。

v0.9.32 changelog：保留 Windows hook rebuild timeout 的相容性修正。 ↩
v0.9.18 changelog：manifest.json portable（relative paths + re-anchor on load）。 ↩