How Graphify’s Git Hook Integration Automates Knowledge Graph Rebuilding on Commits

Graphify’s git hook integration installs post-commit and post-checkout hooks that trigger background Python processes to rebuild the knowledge graph automatically whenever you commit code or switch branches, without blocking your Git workflow.

The Graphify repository (Graphify-Labs/graphify) provides a robust git hook integration that eliminates the need for manual graph updates or background daemons. By installing custom Git hooks, the system detects repository changes and incrementally rebuilds the knowledge graph to reflect your codebase’s current state.

Hook Installation and Repository Detection

The graphify hook install command, implemented in graphify/hooks.py, handles the entire setup process through the install() function. The installer first locates the repository’s Git hooks directory, respecting the core.hooksPath configuration and various work-tree layouts to ensure compatibility with non-standard repository structures.

The installation process pins the current Python interpreter (sys.executable) into the hook scripts. This guarantees that the hooks execute correctly even when the Graphify launcher is not available on the system PATH, such as when using GUI Git clients or CI runners. The interpreter path is stored in .graphify_python within the output directory for later reference.

Hook Script Architecture and Safety Guards

Graphify writes self-contained shell scripts to .git/hooks/post-commit and .git/hooks/post-checkout, wrapping the logic between # graphify-hook-start and # graphify-hook-end markers. These scripts implement several safety mechanisms to prevent unnecessary or duplicate executions:

• Skip conditions: The hooks automatically exit during rebase, merge, or cherry-pick operations, or when the environment variable GRAPHIFY_SKIP_HOOK=1 is set.
• Worktree detection: The script detects linked worktrees and exits early to avoid duplicate rebuilds across multiple working directories.
• Change filtering: Using git diff --name-only HEAD~1 HEAD, the hook computes changed files. If modifications are limited to the graphify-out/ directory, the rebuild is skipped to prevent feedback loops.

Background Rebuild Process

When a commit triggers the post-commit hook, the script exports the GRAPHIFY_CHANGED environment variable containing the list of modified source files, then launches a detached Python process. This background execution ensures your git commit command returns immediately while the rebuild occurs asynchronously.

The detached payload uses the _REBUILD_BODY_COMMIT template, which imports graphify.watch._rebuild_code and applies resource limits via _apply_resource_limits(). The process respects the optional GRAPHIFY_REBUILD_TIMEOUT environment variable and writes operational logs to ~/.cache/graphify-rebuild.log. After a successful rebuild, the system refreshes any saved Q&A lessons to incorporate the updated code context.

Post-Checkout Full Rebuilds

The post-checkout hook follows a similar pattern but triggers a full rebuild rather than an incremental one. When you switch branches, the hook detects the branch change and calls _rebuild_code() without the changed_paths parameter, ensuring the knowledge graph completely reflects the newly checked-out codebase state rather than applying partial updates.

Automatic Merge Conflict Resolution

Beyond rebuild automation, the git hook integration registers a custom Git merge driver for graph.json files. The installer adds a merge.graphify driver configuration to your Git config and creates a corresponding entry in .gitattributes. This setup guarantees automatic union-merging of graph files during concurrent commits, eliminating manual conflict resolution for generated graph data.

Command Reference

Install the hooks and merge driver in your current repository:

$ graphify hook install
post-commit: installed at /path/to/repo/.git/hooks/post-commit
post-checkout: installed at /path/to/repo/.git/hooks/post-checkout
merge driver: registered (graphify-out/graph.json merge=graphify)

Check the current installation status:

$ graphify hook status
post-commit: installed
post-checkout: installed
merge driver: registered

Remove all Graphify hooks and the merge driver configuration:

$ graphify hook uninstall
post-commit: graphify removed from post-commit at /path/to/repo/.git/hooks/post-commit
post-checkout: graphify removed from post-checkout at /path/to/repo/.git/hooks/post-checkout
merge driver: removed (.gitattributes deleted - no other entries)

Summary

• Zero-daemon automation: Graphify uses standard Git hooks rather than background processes to trigger rebuilds, minimizing resource consumption.
• Non-blocking execution: Rebuilds run in detached Python processes, allowing Git commands to complete immediately while graph updates proceed asynchronously.
• Smart change detection: The integration filters out graph-output directory changes and detects rebase/merge states to avoid redundant builds.
• Cross-platform compatibility: Interpreter pinning ensures hooks work correctly in GUI Git clients and environments where Graphify isn’t on the PATH.
• Conflict-free collaboration: The custom merge driver for graph.json automatically handles concurrent graph modifications via union merging.

Frequently Asked Questions

How do I temporarily disable the Graphify git hooks?

Set the environment variable GRAPHIFY_SKIP_HOOK=1 before running your Git command. For example: GRAPHIFY_SKIP_HOOK=1 git commit -m "wip". This causes the hook to exit immediately without triggering a rebuild, which is useful when making experimental commits or during large rebases.

Where does the hook log its output if the rebuild fails?

The detached Python process writes all output and errors to ~/.cache/graphify-rebuild.log. Check this file if you suspect the background rebuild is failing silently or if you need to debug resource limit violations or timeout issues indicated by the GRAPHIFY_REBUILD_TIMEOUT setting.

Why does switching branches trigger a full rebuild instead of an incremental one?

The post-checkout hook performs a full rebuild (calling _rebuild_code without changed_paths) because branch switches can alter the entire codebase structure, including file renames and deletions that incremental diffs might miss. This ensures the knowledge graph accurately represents the complete state of the newly checked-out branch.

How does Graphify handle conflicts in the graph.json file during merges?

Graphify registers a custom merge driver named graphify that applies union-merge logic to graph.json files. When Git encounters a conflict in the graph file, the driver automatically merges the changes without producing conflict markers, as the graph is a generated artifact that should incorporate all concurrent modifications.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}