Pick a method
Git hooks
Refresh on every git event. Runs in the background after commits, branch switches, merges, pulls and rebases.
graphify watch
Refresh as you save. Rebuilds a few seconds after code files change.
Git hooks
Run this once in each repository, after you’ve built a graph:graph.json:
You don’t need to run
graphify update . after git pull. The post-merge or post-rewrite hook does it for you.
What hook install changes in your repo
graphify hook install writes four hook files, one .gitattributes line, and two keys in the repository’s git config. Nothing is written to the global git config.
By default the files are .git/hooks/post-commit, .git/hooks/post-checkout, .git/hooks/post-merge, and .git/hooks/post-rewrite. Each graphify block sits between its own start and end markers:
If the hook file already exists, the block is added after the lines that are already there. Those lines stay. A new hook file starts with
#!/bin/sh and is made executable.
If core.hooksPath is .husky/_, the four hook files are written to .husky/. A missing .husky/_ directory is created as well. A core.hooksPath outside the repository is refused, and the files are written to .git/hooks.
It adds graphify-out/graph.json merge=graphify to .gitattributes. Every other line in that file stays.
In .git/config it sets:
merge.graphify.nametographify graph.json union mergemerge.graphify.driverto the quoted path of the Python interpreter that rangraphify hook install, followed by-m graphify merge-driver %O %A %B
graphify hook install again.
Turn off or remove the hooks
SetGRAPHIFY_SKIP_HOOK=1 for a single git command, for example GRAPHIFY_SKIP_HOOK=1 git pull. The rebuild is skipped for that command. The hooks stay installed.
graphify hook uninstall removes only the graphify marker block from each of the four hook files. Lines you added stay. The file is deleted when nothing is left, or when the only line left is #!/bin/sh or #!/bin/bash. It removes the merge=graphify line from .gitattributes, and deletes .gitattributes when that line was the only one. It unsets merge.graphify.name and merge.graphify.driver in the local git config.
graphify uninstall without --project removes those same hooks and the merge driver. graphify-out/ stays. graphify uninstall --purge is what deletes it. The rebuild log at ~/.cache/graphify-rebuild.log stays after either command, including graphify uninstall --purge.
Check that it’s working
graphify hook status should print:
out of date, run graphify hook install again. To see what a rebuild did, read ~/.cache/graphify-rebuild.log.
A few things to know:
- It runs in the background. Git returns straight away, so a query right after a commit or pull can still see the old graph for a moment. Output goes to
~/.cache/graphify-rebuild.log. - It needs a graph to exist. Build one first with
/graphify .orgraphify extract .. The branch, merge and rebase hooks do nothing untilgraphify-out/exists. - It skips some moments on purpose. No rebuild runs mid-rebase, in a linked
git worktree, or whenGRAPHIFY_SKIP_HOOK=1is set. - It keeps your own hooks. Graphify adds its block between markers and leaves the rest of the file alone. See What hook install changes in your repo.
- Re-run it after moving Python. The hooks and the merge driver keep the interpreter path from
hook install. See What hook install changes in your repo.
graphify watch
The watcher needs thewatch extra:
- Code changed: rebuilds the code graph right away. No model is called.
- A doc, PDF or image changed: writes a
graphify-out/needs_updateflag and tells you to run/graphify --updatein your assistant. It does not call a model by itself. - A file was deleted: rebuilds, so the deleted file’s nodes drop out.
What stays manual
Hooks and the watcher refresh code. They never call a model, so changes to docs, PDFs and images wait for you:graphify check-update . to see whether a doc refresh is pending.
Known limits
These are open issues in the Graphify CLI repository. We’ll update this page when they’re fixed.Hooks rebuild a --code-only graph as a full graph
Hooks rebuild a --code-only graph as a full graph
If you built with
graphify extract . --code-only, the next branch switch, merge or rebase rebuilds it with docs included, so it grows. The rebuild doesn’t remember the scope you chose. Until this is fixed, add docs you want kept out to .graphifyignore. Tracked in #4923.Deleting a doc can re-queue every other doc
Deleting a doc can re-queue every other doc
After you delete a document and run
/graphify --update, the next update can treat all your other docs as changed and run them through the semantic pass again. Cached results still save the model calls, but the run takes longer. Tracked in #4914.An interrupted doc extraction can look finished
An interrupted doc extraction can look finished
If you stop a semantic extraction partway through a long document, the cache can mark that document as done, and later updates skip the part that never ran. If you interrupted a run, rebuild that file with
graphify extract . --force. Tracked in #4943.FAQ
How do I keep a code graph up to date automatically?
How do I keep a code graph up to date automatically?
Run
graphify hook install once in the repository. From then on, git rebuilds the code graph after each commit, branch switch, merge, pull and rebase. With hosted Graphify, the graph rebuilds on every push and there’s nothing to install.Do I still need graphify update after git pull?
Do I still need graphify update after git pull?
Not if you’ve run
graphify hook install. A pull that merges fires post-merge, and git pull --rebase fires post-rewrite. Both rebuild the code graph in the background. Without hooks, run graphify update . yourself.Should I use hooks and watch together?
Should I use hooks and watch together?
You can. Rebuilds take a per-repository lock and queue behind each other, so they don’t pile up. Most people only need hooks.
How do I turn the hooks off for one command?
How do I turn the hooks off for one command?
Set
GRAPHIFY_SKIP_HOOK=1, for example GRAPHIFY_SKIP_HOOK=1 git pull. To remove the hooks, see Turn off or remove the hooks.Do the hooks call a model or use tokens?
Do the hooks call a model or use tokens?
No. Hooks and the watcher only re-read code, locally. Docs, PDFs and images refresh when you run
/graphify . --update.Next steps
Keep the graph current
Manual refreshes, ignore files and the
--force flag.Troubleshooting
Fixes for stale answers, missing nodes and hook problems.
Try it in Graphify
We build and host the graph for you, and review your pull requests with it. The Free plan (up to 3 repositories) needs no card. Pro and Teams start with a 14-day trial, card required.