Annotations

Kart can calculate certain metadata about commits (and actually about arbitrary diffs) and store it for later use.

This feature is probably mostly useful for apps needing to present commit metadata to users in a timely fashion.

At present only one type of annotation is available: feature counts.

Finding feature counts for a commit

kart diff supports the --only-feature-count option, which can produce feature count estimates for an arbitrary diff with a range of different accuracies.

$ kart diff HEAD^..HEAD --only-feature-count=good
landonline_setup:
    151552 features changed

To get an exact feature count, use --only-feature-count=exact, which looks at all of the features.

Other values are veryfast, fast, medium, and good, all of which sample a proportion of the layer to determine an approximate feature count.

Annotation storage

All annotations are stored in a SQLite database, annotations.db, in the repo directory (.kart/annotations.db)

The first time a given annotation is requested, it will be calculated and stored in the database. If the database doesn’t exist, it will be created the first time it is used.

Subsequent requests for the same annotation will simply fetch it from the database, rather than re-calculate it.

If the database is unwritable for some reason, then annotations are not stored.

Bulk populating annotations

The kart build-annotations command populates annotations in bulk. It is useful as a post-commit, post-receive or post-merge hook for services handling Kart repos.

It takes a list of commit IDs from stdin, and builds exact feature counts for the diffs those commits represent.

Alternatively, provide --all-reachable to build annotations for all commits that are reachable from any local ref, rather than providing anything on stdin. Nothing is calculated for annotations that are already in the database.

If the database is unwritable for some reason, this command will error (exit code 20)