OSWatcher Procedures

Custom Neo4j stored procedures for OSWatcher — recursive tree diffing over the merkle graph.

These procedures are deployed as a JAR plugin into Neo4j and power the diff engine used by neogit and oswatcher-plugins.

Procedures

oswatcher.diffTreesRecursive

Recursively diffs two nodes in the OSWatcher merkle graph, yielding per-node change records.

CALL oswatcher.diffTreesRecursive(
    parent_label,       // String:       node label to traverse (e.g. 'Tree', 'Blob')
    base,               // String|null:  hash of the base node
    diffee,             // String|null:  hash of the diffee node
    base_path,          // String:       starting path prefix (e.g. '/')
    filter,             // List<String>: child labels to include (empty = all)
    max_depth,          // Long:         depth limit (-1 = unlimited)
    with_intermediates, // Boolean:      include intermediate nodes
    status_filter       // List<String>: filter by status (empty = all except UNCHANGED)
)
YIELD status, type, path, old_props, new_props

max_depth

Value	Behaviour
0	Compare nodes themselves only (no children)
1	Immediate children only
n	n levels deep
-1	Unlimited recursion (default)

status_filter

Value	Meaning
NEW	Node exists only in diffee
MOD	Node exists in both with different hash
DEL	Node exists only in base
UNCHANGED	Node exists in both with same hash (opt-in only)

Empty list returns all statuses except UNCHANGED.

Examples

// Diff symbols between two Blobs (immediate children only)
CALL oswatcher.diffTreesRecursive('Blob', 'hash1', 'hash2', '/', ['Symbol'], 1, false, [])
YIELD status, path, old_props, new_props

// Full recursive filesystem tree diff
CALL oswatcher.diffTreesRecursive('Tree', 'hash1', 'hash2', '/', [], -1, false, [])
YIELD status, path

// Compare two nodes directly (git-log style, no recursion)
CALL oswatcher.diffTreesRecursive('Tree', 'hash1', 'hash2', '/', [], 0, false, [])
YIELD status, path

// Only show modified and new nodes
CALL oswatcher.diffTreesRecursive('Tree', 'hash1', 'hash2', '/', [], -1, false, ['MOD', 'NEW'])
YIELD status, path

Building

Requires Java 17 and Maven 3.9+.

./mvnw clean package

This produces target/oswatcher-procedures-1.0.0.jar. Deploy it to the plugins/ directory of your Neo4j instance and restart.

Deployment

Download the latest JAR from Releases and place it in your Neo4j plugins/ directory. No configuration beyond Neo4j’s standard plugin loading is required.

License

Apache License 2.0 — see LICENSE.