Inspecting History

runic provides several commands for inspecting the revision DAG without modifying the database.

runic history

Print all revisions, newest first:

$ runic history
7b3d9e2f         (head)                add email fulltext index
3f9a12c1                               add person email index

Show verbose metadata for each revision with --verbose:

$ runic history --verbose
7b3d9e2f         (head)                add email fulltext index
    create_date:   2026-05-30 10:00:00+00:00
    down_revision: 3f9a12c1ab4e

3f9a12c1                               add person email index
    create_date:   2026-05-30 09:00:00+00:00
    down_revision: None

Mark the currently applied revision in the output with --indicate-current (requires a database connection):

$ runic history --indicate-current
7b3d9e2f         (head, current)       add email fulltext index
3f9a12c1                               add person email index

Show only a subset of the chain with --range start:end:

$ runic history --range 3f9a12c1:7b3d9e2f
7b3d9e2f         (head)                add email fulltext index
3f9a12c1                               add person email index

Either side of the range may be omitted: --range :7b3d9e2f means “from the base up to that revision”, and --range 3f9a12c1: means “from that revision to head”.

runic show

Print full metadata for a single revision by ID or unique prefix:

$ runic show 3f9a12c1
Revision ID:   3f9a12c1ab4e
Revises:       <base>
Message:       add person email index
Create Date:   2026-05-30 09:00:00+00:00
Irreversible:  False
Snapshot:      False
Branch Labels: []
Depends On:    []
Path:          runic/versions/3f9a12c1ab4e_add_person_email_index.py

runic current

Print the currently applied revision (requires a database connection):

$ runic current
7b3d9e2f — add email fulltext index

# When no revision has been applied:
$ runic current
<none>

runic heads

Print all head revisions — revisions that no other revision points back to:

# Single head (normal state):
$ runic heads
7b3d9e2f  add email fulltext index  (single head)

# Multiple heads (after a branch is created):
$ runic heads
c1d2e3f4  add vector index          (MULTIPLE HEADS — use merge to resolve)
7b3d9e2f  add email fulltext index  (MULTIPLE HEADS — use merge to resolve)

When there are multiple heads, runic upgrade head and runic upgrade (without a target) will refuse to run. Use runic merge to create a merge revision, or specify an explicit revision ID.

runic branches

Print every revision that is a branch point — a revision that two or more other revisions build upon:

$ runic branches
3f9a12c1  add person email index  ['7b3d9e2f', 'c1d2e3f4']

The last column lists the direct child revision IDs.

See also