Export and preload the set of files marked reviewed

[denysshnurenko]

What I'd like

Two halves of one round trip for the reviewed marks (Space):

1. --reviewed-output <file> — on exit, write the paths marked reviewed, one relative path per line.
2. --reviewed <file> — on start, mark those paths as reviewed up front.

revdiff already ships exactly this pair for the other half of a review's state: -o writes annotations, --annotations preloads them. Reviewed marks have no such pair, so they die with the process.

Why

A large review is not one sitting. I mark 27 of 85 files reviewed, quit, come back the next morning — everything is unreviewed again and F (unreviewed only) has nothing to filter on. Nothing else preserves it either: review history saves annotations plus diffs, and only when annotations exist, so a session that produced marks and no annotations leaves no trace at all.

With the pair above the second pass is what it should be: preload what I already finished, press F, and look only at what is left.

Why not --include / --only

I can already compute the remaining set outside revdiff and pass it in — but those flags drop every other file from the review. When the file I am reading refers to one I already checked, I cannot glance at it, and I cannot change my mind and un-finish a file mid-session.

A preloaded reviewed mark is different in exactly the way that matters: every file stays present and openable, the finished ones simply stop competing for attention, and Space still un-marks one when it turns out to deserve a second look. "Out of the way but reachable" is the state --only cannot express.

It also closes the loop with GitHub

GitHub tracks the same per-reviewer concept and it is scriptable: markFileAsViewed / unmarkFileAsViewed mutations, and PullRequestChangedFile.viewerViewedState reads back VIEWED / UNVIEWED / DISMISSED (the last meaning the file changed since it was viewed). So the export feeds the PR directly:

revdiff --reviewed-output reviewed.txt "$base"
xargs -I{} gh api graphql \
  -f query='mutation($pr:ID!,$p:String!){markFileAsViewed(input:{pullRequestId:$pr,path:$p}){clientMutationId}}' \
  -F pr="$PR_ID" -F p={} < reviewed.txt

and the query feeds the preload back on the next round. Today I read the files in revdiff and then re-click each one in the GitHub web UI by hand.

Shape

Probably not on the annotation stream: the record format is ## path[:line[-line]] (…), and the README already documents defending that parser against ## collisions in comment bodies, so a second record kind there would break existing consumers. A separate sink avoids the question — a plain path-per-line file, or a field in a structured (JSON) output mode if one is planned anyway.

Nothing new needs tracking: the model already holds the set, and R already owns the rule for when a mark survives a reload. This is persisting state that exists.

Environment

revdiff v1.12.0-ad8c796-20260804T171719 (homebrew, umputun/apps/revdiff), macOS 15.6.

[umputun]

the progress-loss problem is real and I want it solved. Reviewed marks were added for exactly this case (#54, "when reviewing large diffs with many files, it's easy to lose track"), and F came later for the same reason, so marks dying with the process makes F a single-session toy. Your read of the code is right: history.Save bails when there are no annotations (app/history/history.go:43), so a marks-only session leaves nothing behind.

the plain path-per-line file is the part I'm not taking. A mark is not a path, it's a path plus a fingerprint of that file's effective diff (app/ui/sidepane/filetree.go:25), and that fingerprint is what keeps a mark through a rebase that only shifts a hunk while dropping it the moment the content really changes. A bare list throws that away: preload one after someone force-pushed and F hides files you never read, which is the worst way for a review tool to be wrong. Whatever ships here will carry the fingerprint, so it ends up closer to your structured-output option than to the path list. That also caps the GitHub direction at advisory, since viewerViewedState gives back paths and nothing else.

[denysshnurenko]

Agreed on the fingerprint: a mark that survives a rebase but dies on a content change is exactly what I want, and a preload that degrades to "unreviewed" on mismatch is the safe failure. Two asks then. (1) Could the marks simply ride along in review history, so a marks-only session saves too and the next run on the same base/head restores them with no flags at all? That covers the "next morning" case by itself. (2) For the GitHub direction an export of path + fingerprint is enough: I can push markFileAsViewed from it outside revdiff, and I accept that the reverse (paths only) stays advisory.