terradiff

README

terradiff

git diff for geospatial data. Compare GeoJSON, GeoPackage, and Shapefiles visually.

$ terradiff diff parcels_v1.geojson parcels_v2.geojson

Geospatial Diff Summary

  Source A: 5 features
  Source B: 5 features
  + 1 added
  - 1 removed
  ~ 2 modified
  = 1 unchanged

  Status     │ ID         │ Geometry       │ Attribute Changes
  + added    │ parcel-006 │                │
  - removed  │ parcel-003 │                │
  ~ modified │ parcel-002 │ moved 24.3m    │ owner, zoning
  ~ modified │ parcel-004 │                │ area_sqm

  Attribute Changes

  Feature parcel-002:
    owner: Ana Kovac → Ana Kovac-Brkic
    zoning: commercial → mixed-use

  Feature parcel-004:
    area_sqm: 750.8 → 820

Install

Go install:

go install github.com/MVidicek/terradiff/cmd/terradiff@latest

From binary:

Download the latest release from the releases page and drop it somewhere on your $PATH.

Docker:

docker run --rm -v $(pwd):/data ghcr.io/mvidicek/terradiff diff /data/a.geojson /data/b.geojson

Quick Start

# Compare two GeoJSON files
terradiff diff old.geojson new.geojson

# Output as JSON for scripting
terradiff diff old.geojson new.geojson --format json

# Match features by a custom property instead of "id"
terradiff diff old.gpkg new.gpkg --match-by id --match-field parcel_id

Features

• Three matching strategies: Match features by property ID, spatial proximity (nearest centroid within a threshold), or a hybrid of both.
• Geometry comparison: Detects moved, reshaped, or replaced geometries using bounding box overlap and Haversine centroid distance.
• Attribute diffing: Deep property comparison with type coercion — won't false-positive on 42 vs 42.0.
• Multiple output formats: Color-coded terminal tables, JSON reports, or self-contained HTML maps with MapLibre GL.
• Web viewer: terradiff serve launches a local web app to inspect diffs on an interactive map.
• CRS awareness: Warns when datasets use different coordinate reference systems.
• Caching: SQLite-backed cache so repeated diffs on the same file don't re-parse it.

Web Viewer

For visual inspection, run:

terradiff serve --file-a old.geojson --file-b new.geojson --open

This starts a local server and opens a browser with an interactive map. Features are color-coded:

• Green = added
• Red = removed
• Yellow = modified

Click any feature to inspect its properties and see exactly what changed.

Supported Formats

Format	Extension	Read	Notes
GeoJSON	.geojson	Yes	RFC 7946 FeatureCollections
GeoPackage	.gpkg	Yes	Reads first feature table via SQLite
Shapefile	.shp	Yes	Requires .shx and .dbf sidecar files

Matching Strategies

Strategy	Flag	How it works
ID	--match-by id	Matches features with the same value in --match-field
Spatial	--match-by spatial	Pairs each feature with the nearest centroid within --threshold meters
Hybrid	--match-by hybrid	Tries ID first, then spatial for unmatched features (default)

Alternatives

• geojson-diff — Ruby gem, GeoJSON only. Good if you just need GeoJSON and are already in a Ruby environment.
• geodiff — C++ library focused on GeoPackage diffing. Powerful but no CLI experience and harder to integrate.

terradiff sits between these — it handles multiple formats, has a real CLI with readable output, and includes a web viewer for when you want to actually see the diff on a map.

License

MIT. See LICENSE.