git-review-workflow 0.1.0

package/bin/git-review-verbs/forget

@@ -0,0 +1,289 @@
+#!/usr/bin/env sh
+#
+# git review forget — discard the persistent state a review leaves behind:
+# the --delta markers (--delta) or a review paused with git review save (--saved).
+# Exactly one mode is required.
+#
+# Both kinds of state outlive the review/<branch> and review-fixes/<branch>
+# branches on purpose — a later --delta keeps working, a paused review waits to
+# be resumed — so git review clean deliberately leaves them alone. This command
+# is how you throw them away. To delete the review branches themselves, use
+# git review clean.
+#
+set -eu
+
+prog="git review forget"
+
+usage() {
+	cat <<EOF
+usage: $prog --delta (<branch> | --all | --stale [--dry-run])
+       $prog --saved (<branch> | --all) [--dry-run]
+
+Discard the persistent state a review leaves behind. Choose one mode:
+
+  --delta   forget the recorded last-reviewed tip used by git review start --delta
+  --saved   discard a review paused with git review save: delete
+            review-saved/<branch>, its banked edits and metadata, and roll back
+            the --delta marker it left
+
+--delta targets:
+  <branch>     forget the marker(s) for one source branch (remote and --local)
+  --all        forget every recorded marker
+  --stale      forget only markers whose branch no longer exists: remote markers
+               when <remote>/<branch> is gone (fetches and prunes first), local
+               markers when the local <branch> is gone
+  --dry-run    with --stale, list what would be forgotten without forgetting it
+
+--saved targets:
+  <branch>     discard the saved review for one source branch
+  --all        discard every saved review
+  --dry-run    list what would be discarded without discarding it
+EOF
+}
+
+die() {
+	echo "error: $1" >&2
+	exit 1
+}
+
+mode=""
+arg=""
+all=0
+stale=0
+dryrun=0
+while [ $# -gt 0 ]; do
+	case "$1" in
+	-h | --h)
+		usage
+		exit 0
+		;;
+	--delta)
+		[ -z "$mode" ] || [ "$mode" = delta ] || die "use only one of --delta and --saved"
+		mode="delta"
+		;;
+	--saved)
+		[ -z "$mode" ] || [ "$mode" = saved ] || die "use only one of --delta and --saved"
+		mode="saved"
+		;;
+	--all) all=1 ;;
+	--stale) stale=1 ;;
+	--dry-run) dryrun=1 ;;
+	-*)
+		echo "error: unknown option $1" >&2
+		usage >&2
+		exit 1
+		;;
+	*)
+		if [ -z "$arg" ]; then
+			arg="$1"
+		else
+			echo "error: unexpected argument $1" >&2
+			usage >&2
+			exit 1
+		fi
+		;;
+	esac
+	shift
+done
+
+# The mode selects which kind of state to discard; without it the request is
+# ambiguous (markers? a saved review?), so there is no safe default.
+if [ -z "$mode" ]; then
+	usage >&2
+	exit 1
+fi
+
+# ── --saved ─────────────────────────────────────────────────────────────────────
+if [ "$mode" = saved ]; then
+	[ "$stale" -eq 0 ] || die "--stale only applies to --delta"
+
+	if [ -n "$arg" ] && [ "$all" -eq 1 ]; then
+		die "use either <branch> or --all, not both"
+	fi
+	if [ -z "$arg" ] && [ "$all" -eq 0 ]; then
+		usage >&2
+		exit 1
+	fi
+
+	git rev-parse --git-dir >/dev/null 2>&1 || die "not a git repository"
+
+	cur="$(git symbolic-ref --quiet --short HEAD || true)"
+
+	# forget_saved_one <src>: discard the saved review for one source branch.
+	forget_saved_one() {
+		src="$1"
+		saved="review-saved/$src"
+		if ! git rev-parse --verify --quiet "refs/heads/$saved" >/dev/null; then
+			echo "no saved review for $src" >&2
+			return
+		fi
+		if [ "$dryrun" -eq 1 ]; then
+			echo "would discard saved review of $src"
+			return
+		fi
+		if [ "$saved" = "$cur" ]; then
+			echo "skipping $src (its branch is currently checked out)" >&2
+			return
+		fi
+
+		# Roll the --delta marker back to the last actual review before the metadata
+		# disappears with the branch. Local reviews track their marker in a separate
+		# config section, matching git review start / git review abort.
+		if [ "$(git config "branch.$saved.reviewlocal" || true)" = "1" ]; then
+			markerkey="reviewworkflowlocal.$src.reviewed"
+		else
+			markerkey="reviewworkflow.$src.reviewed"
+		fi
+		prevreviewed="$(git config "branch.$saved.reviewprevreviewed" || true)"
+		if [ -n "$prevreviewed" ]; then
+			git config "$markerkey" "$prevreviewed"
+		else
+			git config --unset "$markerkey" 2>/dev/null || true
+		fi
+
+		git for-each-ref --format='%(refname)' "refs/review-saved-edits/$src/" | while read -r ref; do
+			git update-ref -d "$ref"
+		done
+		git branch -D "$saved" >/dev/null
+
+		echo "discarded saved review of $src"
+	}
+
+	if [ "$all" -eq 1 ]; then
+		branches="$(git for-each-ref --format='%(refname:short)' refs/heads/review-saved/)"
+		[ -n "$branches" ] || {
+			echo "no saved reviews"
+			exit 0
+		}
+		printf '%s\n' "$branches" | while read -r b; do
+			forget_saved_one "${b#review-saved/}"
+		done
+	else
+		forget_saved_one "$arg"
+	fi
+	exit 0
+fi
+
+# ── --delta ─────────────────────────────────────────────────────────────────────
+# parse_marker <key>: split a marker key into the source branch ($msrc), a human
+# label ($mlabel) and whether it is a local marker ($mislocal). Local markers (git
+# review start --local) live in their own config section, reviewworkflowlocal.<src>
+# .reviewed, while remote ones are reviewworkflow.<src>.reviewed. Disjoint sections
+# (rather than a .local segment inside one section) keep the two apart even for a
+# branch literally named "<src>.local".
+parse_marker() {
+	case "$1" in
+	reviewworkflowlocal.*)
+		msrc="${1#reviewworkflowlocal.}"
+		msrc="${msrc%.reviewed}"
+		mlabel=" (local)"
+		mislocal=1
+		;;
+	*)
+		msrc="${1#reviewworkflow.}"
+		msrc="${msrc%.reviewed}"
+		mlabel=""
+		mislocal=0
+		;;
+	esac
+}
+
+# forget_delta <key> <src> <verb>: unset a marker (or, in dry-run, say it would be).
+forget_delta() {
+	if [ "$dryrun" -eq 1 ]; then
+		echo "would forget delta marker for $2$3"
+	else
+		git config --unset "$1" || true
+		echo "forgot delta marker for $2$3"
+	fi
+}
+
+# Exactly one target selector: a branch, --all or --stale.
+selectors=0
+[ -n "$arg" ] && selectors=$((selectors + 1))
+[ "$all" -eq 1 ] && selectors=$((selectors + 1))
+[ "$stale" -eq 1 ] && selectors=$((selectors + 1))
+if [ "$selectors" -eq 0 ]; then
+	usage >&2
+	exit 1
+fi
+[ "$selectors" -eq 1 ] || die "use only one of <branch>, --all and --stale"
+
+# --dry-run is a preview of the inferred --stale set; it means nothing for the
+# explicit targets, where you already named exactly what to forget.
+if [ "$dryrun" -eq 1 ] && [ "$stale" -ne 1 ]; then
+	die "--dry-run only applies to --stale"
+fi
+
+git rev-parse --git-dir >/dev/null 2>&1 || die "not a git repository"
+
+# Remote whose branches back the markers; defaults to origin, override with
+# reviewworkflow.remote.
+remote="$(git config reviewworkflow.remote || echo origin)"
+
+# ── one branch ────────────────────────────────────────────────────────────────
+if [ -n "$arg" ]; then
+	any=0
+	if [ -n "$(git config "reviewworkflow.$arg.reviewed" || true)" ]; then
+		forget_delta "reviewworkflow.$arg.reviewed" "$arg" ""
+		any=1
+	fi
+	if [ -n "$(git config "reviewworkflowlocal.$arg.reviewed" || true)" ]; then
+		forget_delta "reviewworkflowlocal.$arg.reviewed" "$arg" " (local)"
+		any=1
+	fi
+	[ "$any" -eq 1 ] || echo "no delta marker recorded for $arg"
+	exit 0
+fi
+
+# Collect every marker into a temp file so the loop runs in the current shell
+# (a pipe into `while` would forget unsets in a subshell). Both sections are
+# gathered: remote markers (reviewworkflow.*) and local ones (reviewworkflowlocal.*).
+tmp="$(mktemp)"
+trap 'rm -f "$tmp"' EXIT
+{
+	git config --get-regexp '^reviewworkflow\..*\.reviewed$' 2>/dev/null || true
+	git config --get-regexp '^reviewworkflowlocal\..*\.reviewed$' 2>/dev/null || true
+} >"$tmp"
+
+if [ ! -s "$tmp" ]; then
+	echo "no delta markers recorded"
+	exit 0
+fi
+
+# ── --stale ───────────────────────────────────────────────────────────────────
+if [ "$stale" -eq 1 ]; then
+	# A local marker's staleness is decided entirely by whether its local branch
+	# still exists — no remote state involved. Only fetch (to prune deleted
+	# remote-tracking refs) when at least one remote marker is present; a set of
+	# purely --local markers needs no network at all. The anchored pattern matches
+	# reviewworkflow.<src>.reviewed but not reviewworkflowlocal.<src>.reviewed.
+	if grep -q '^reviewworkflow\.' "$tmp"; then
+		git fetch --prune --quiet "$remote" || die "could not fetch from $remote"
+	fi
+
+	any=0
+	while read -r key _; do
+		[ -n "$key" ] || continue
+		parse_marker "$key"
+		if [ "$mislocal" -eq 1 ]; then
+			# A local marker is stale when its local branch is gone.
+			git rev-parse --verify --quiet "refs/heads/$msrc" >/dev/null && continue
+			forget_delta "$key" "$msrc" " (local; $msrc no longer exists)"
+		else
+			git rev-parse --verify --quiet "refs/remotes/$remote/$msrc" >/dev/null && continue
+			forget_delta "$key" "$msrc" " ($remote/$msrc no longer exists)"
+		fi
+		any=1
+	done <"$tmp"
+
+	[ "$any" -eq 1 ] || echo "no stale delta markers (every branch still exists)"
+	exit 0
+fi
+
+# ── --all ─────────────────────────────────────────────────────────────────────
+while read -r key _; do
+	[ -n "$key" ] || continue
+	parse_marker "$key"
+	forget_delta "$key" "$msrc" "$mlabel"
+done <"$tmp"

package/bin/git-review-verbs/list

@@ -0,0 +1,99 @@
+#!/usr/bin/env sh
+#
+# git review list — list every review/* branch in progress.
+#
+# git review status reports only the review on the current branch; this shows all
+# of them at once, so you can see what you have open across branches. The current
+# branch is marked with a "*".
+#
+set -eu
+
+prog="git review list"
+
+usage() {
+	cat <<EOF
+usage: $prog
+
+List every review/* branch in progress, with its source PR, mode and — in
+commit-by-commit mode — which commit you are on ([k/N]). The branch you are on
+is marked with a "*". Reviews paused with git review save are listed too, under
+"saved".
+EOF
+}
+
+case "${1:-}" in
+-h | --h)
+	usage
+	exit 0
+	;;
+"") ;;
+*)
+	echo "error: unexpected argument $1" >&2
+	usage >&2
+	exit 1
+	;;
+esac
+
+git rev-parse --git-dir >/dev/null 2>&1 || {
+	echo "error: not a git repository" >&2
+	exit 1
+}
+
+cur="$(git symbolic-ref --quiet --short HEAD || true)"
+branches="$(git for-each-ref --format='%(refname:short)' refs/heads/review/)"
+saved="$(git for-each-ref --format='%(refname:short)' refs/heads/review-saved/)"
+
+if [ -z "$branches" ] && [ -z "$saved" ]; then
+	echo "no reviews in progress"
+	exit 0
+fi
+
+# describe <branch> <marker>: print one line for a review branch, reading its
+# mode and position from the branch config. Used for both active and saved reviews.
+describe() {
+	b="$1"
+	label="$2"
+	src="$(git config "branch.$b.reviewsource" || true)"
+	# A branch with no reviewsource is an orphan: either hand-made, or left by a
+	# git review save / git review start that died after creating the branch but before
+	# writing its metadata. Surface it instead of skipping silently — otherwise an
+	# orphan-only state prints nothing at all — so it can be cleaned up (e.g. with
+	# git review forget --saved).
+	if [ -z "$src" ]; then
+		printf '%s %s  %s(no metadata)\n' "$label" "$b" "$prefix"
+		return
+	fi
+	tip="$(git config "branch.$b.reviewtip" || true)"
+	mode="$(git config "branch.$b.reviewmode" || echo whole)"
+
+	shorttip="$tip"
+	[ -n "$tip" ] && shorttip="$(git rev-parse --short "$tip" 2>/dev/null || echo "$tip")"
+
+	if [ "$mode" = "step" ]; then
+		count="$(git config "branch.$b.reviewcount" || echo '?')"
+		step="$(git config "branch.$b.reviewstep" || echo '?')"
+		printf '%s %s  %sstep [%s/%s]  tip %s\n' "$label" "$b" "$prefix" "$step" "$count" "$shorttip"
+	else
+		printf '%s %s  %swhole  tip %s\n' "$label" "$b" "$prefix" "$shorttip"
+	fi
+}
+
+prefix=""
+printf '%s\n' "$branches" | while read -r b; do
+	[ -n "$b" ] || continue
+	marker=" "
+	[ "$b" = "$cur" ] && marker="*"
+	describe "$b" "$marker"
+done
+
+# Reviews put aside with git review save, tagged so they are not mistaken for
+# active ones. The branch you are on is still marked with "*".
+if [ -n "$saved" ]; then
+	prefix="saved  "
+	printf '%s\n' "$saved" | while read -r b; do
+		[ -n "$b" ] || continue
+		marker=" "
+		[ "$b" = "$cur" ] && marker="*"
+		describe "$b" "$marker"
+	done
+fi

package/bin/git-review-verbs/next

@@ -0,0 +1,46 @@
+#!/usr/bin/env sh
+#
+# git review next — advance a commit-by-commit review (started with review start --step).
+#
+# Moving banks the edits you made on the current commit into a ref of its own and
+# restores any edits you had previously banked on the commit you move to, so you
+# can walk back and forth without losing work. git review finish replays every
+# banked edit onto the PR tip.
+#
+set -eu
+
+prog="git review next"
+
+usage() {
+	cat <<EOF
+usage: $prog
+
+Advance a commit-by-commit review to the next commit. Your edits are remembered;
+run git review prev to go back, or git review finish when you are done.
+EOF
+}
+
+case "${1:-}" in
+-h | --h)
+	usage
+	exit 0
+	;;
+"") ;;
+*)
+	echo "error: unexpected argument $1" >&2
+	usage >&2
+	exit 1
+	;;
+esac
+
+# Shared helpers, sourced from the libexec directory the dispatcher points us at.
+# shellcheck source=../git-review-lib.sh
+. "${GIT_REVIEW_LIBEXEC:?}/git-review-lib.sh"
+
+load_step_review_meta
+
+if [ "$step" -lt "$count" ]; then
+	goto_step "$((step + 1))"
+else
+	echo "no more commits — run git review finish"
+fi

package/bin/git-review-verbs/prev

@@ -0,0 +1,45 @@
+#!/usr/bin/env sh
+#
+# git review prev — step a commit-by-commit review back to the previous commit.
+#
+# Like git review next but backwards: it banks the current commit's edits and
+# restores any edits you had banked on the previous commit, so you can revisit
+# and keep editing them.
+#
+set -eu
+
+prog="git review prev"
+
+usage() {
+	cat <<EOF
+usage: $prog
+
+Go back to the previous commit of a commit-by-commit review. Your edits are
+remembered in both directions.
+EOF
+}
+
+case "${1:-}" in
+-h | --h)
+	usage
+	exit 0
+	;;
+"") ;;
+*)
+	echo "error: unexpected argument $1" >&2
+	usage >&2
+	exit 1
+	;;
+esac
+
+# Shared helpers, sourced from the libexec directory the dispatcher points us at.
+# shellcheck source=../git-review-lib.sh
+. "${GIT_REVIEW_LIBEXEC:?}/git-review-lib.sh"
+
+load_step_review_meta
+
+if [ "$step" -gt 1 ]; then
+	goto_step "$((step - 1))"
+else
+	echo "already at the first commit"
+fi

package/bin/git-review-verbs/preview

@@ -0,0 +1,195 @@
+#!/usr/bin/env sh
+#
+# git review preview — show the edits you have made so far, without disturbing them.
+#
+# It prints the same diff that git review finish would extract — your review edits
+# on top of the PR tip — but it never commits, never switches branch and never
+# touches your working tree or index, so you go straight back to editing where you
+# left off. Think of it as "what would git review finish give me right now?".
+#
+# Everything is computed in a throwaway index (GIT_INDEX_FILE), the same plumbing
+# style git review save/git review finish use, so running it is a no-op on your state:
+#   whole mode  capture the working tree (edits + any new files) as a tree and diff
+#               it against the tip.
+#   step mode   reproduce git review finish's replay in the throwaway index — the
+#               current step's edits plus every banked edit, applied onto the tip
+#               with the same --3way merge — and diff the result against the tip.
+#               An edit that genuinely conflicts with the tip is the one case that
+#               differs from git review finish: git review finish leaves you conflict
+#               markers to resolve, whereas a read-only preview cannot, so it omits
+#               that edit and prints a note pointing you at git review finish.
+#
+set -eu
+
+prog="git review preview"
+
+usage() {
+	cat <<EOF
+usage: $prog [--stat]
+
+Show the review edits you have made so far on the current review/* branch — the
+same diff git review finish would extract — without committing, switching branch
+or changing your working tree, so you can keep editing where you left off.
+
+  --stat   show a diffstat summary instead of the full diff
+EOF
+}
+
+die() {
+	echo "error: $1" >&2
+	exit 1
+}
+
+stat=0
+while [ $# -gt 0 ]; do
+	case "$1" in
+	-h | --h)
+		usage
+		exit 0
+		;;
+	--stat) stat=1 ;;
+	*)
+		echo "error: unexpected argument $1" >&2
+		usage >&2
+		exit 1
+		;;
+	esac
+	shift
+done
+
+cur="$(git symbolic-ref --quiet --short HEAD || true)"
+case "$cur" in
+review/*) ;;
+*)
+	echo "not on a review/* branch (HEAD is ${cur:-detached})" >&2
+	exit 1
+	;;
+esac
+
+src="$(git config "branch.$cur.reviewsource" || true)"
+tip="$(git config "branch.$cur.reviewtip" || true)"
+mode="$(git config "branch.$cur.reviewmode" || echo whole)"
+if [ -z "$src" ] || [ -z "$tip" ]; then
+	die "missing review metadata; was $cur created with git review start?"
+fi
+
+# A git review finish left mid-conflict has conflict markers in the working tree; a
+# preview built from it would show the markers as content, not your edits. Refuse
+# until they are resolved, mirroring the state git review finish --resume expects.
+if [ "$(git config "branch.$cur.reviewresume" || true)" = "conflict" ]; then
+	die "git review finish is mid-conflict; resolve the markers and run git review finish --resume first"
+fi
+if [ -n "$(git ls-files --unmerged)" ]; then
+	die "you have unresolved merge conflicts; resolve them first"
+fi
+
+# Throwaway indexes live inside the git dir and are removed on exit, so the real
+# index is never touched and a preview leaves no residue.
+gitdir="$(git rev-parse --git-dir)"
+idx="$gitdir/review-preview-index.$$"
+idx2="$gitdir/review-preview-replay.$$"
+# Patches go through files, never shell variables: command substitution corrupts
+# a binary hunk (dropped NUL bytes and trailing newline). curpatch holds the
+# current step's edits, ppatch each banked edit in turn.
+curpatch="$gitdir/review-preview-curpatch.$$"
+ppatch="$gitdir/review-preview-patch.$$"
+trap 'rm -f "$idx" "$idx2" "$curpatch" "$ppatch"' EXIT
+
+# worktree_tree: capture the current working tree — staged, unstaged and any new
+# files — as a tree object, the same content git review finish folds in with git add -A.
+worktree_tree() {
+	cp "$(git rev-parse --git-path index)" "$idx"
+	GIT_INDEX_FILE="$idx" git add -A
+	GIT_INDEX_FILE="$idx" git write-tree
+}
+
+if [ "$mode" = "step" ]; then
+	start="$(git config "branch.$cur.reviewstart" || true)"
+	count="$(git config "branch.$cur.reviewcount" || true)"
+	step="$(git config "branch.$cur.reviewstep" || true)"
+	# A key deleted by a hand-edit (while reviewmode stays "step") would otherwise
+	# let set -e kill the bare read silently mid-script; read with || true and report
+	# it. reviewstep falls through to the numeric guard below for a precise message.
+	if [ -z "$start" ] || [ -z "$count" ]; then
+		die "missing review metadata; was $cur created with git review start?"
+	fi
+	commits="$(git rev-list --reverse --first-parent --no-merges "$start..$tip")"
+	# Guard against a step that maps to no commit (corrupt config, hand-edited
+	# metadata): otherwise cstep is empty and git diff '' aborts the preview with
+	# an opaque exit 128 instead of a clear message.
+	total="$(printf '%s\n' "$commits" | grep -c .)"
+	case "$step" in
+	'' | *[!0-9]*) die "corrupt review metadata: reviewstep is '$step', not a positive integer" ;;
+	esac
+	if [ "$step" -lt 1 ] || [ "$step" -gt "$total" ]; then
+		die "review step $step out of range (1..$total) — corrupt metadata?"
+	fi
+	cstep="$(printf '%s\n' "$commits" | sed -n "${step}p")"
+
+	# The current step's edits are not banked yet (they live in the working tree),
+	# so derive them from the working tree against the commit being reviewed.
+	git diff --binary "$cstep" "$(worktree_tree)" >"$curpatch"
+
+	# Replay onto the tip exactly like git review finish: walk the steps in order,
+	# applying the current step's edits in its slot and each other step's banked
+	# edits, into a fresh index seeded with the tip — with the same --3way merge
+	# git review finish uses, so an edit whose context the PR later shifted still lands.
+	GIT_INDEX_FILE="$idx2" git read-tree "$tip"
+	good="$(GIT_INDEX_FILE="$idx2" git write-tree)"
+	conflict=0
+	i=1
+	while [ "$i" -le "$count" ]; do
+		if [ "$i" -eq "$step" ]; then
+			pf="$curpatch"
+		else
+			ref="refs/review-edits/$src/$i"
+			if git rev-parse --verify --quiet "$ref" >/dev/null; then
+				git diff --binary "${ref}^" "$ref" >"$ppatch"
+				pf="$ppatch"
+			else
+				pf=""
+			fi
+		fi
+		if [ -n "$pf" ] && [ -s "$pf" ]; then
+			# A --3way apply that conflicts leaves unmerged entries, which write-tree
+			# refuses; so apply, then try to capture the tree. On success keep it as
+			# the new baseline; on a genuine conflict roll the index back to the last
+			# clean tree and note the edit as omitted (git review finish would leave you
+			# conflict markers to resolve — a preview cannot, so it skips it).
+			if GIT_INDEX_FILE="$idx2" git apply --cached --3way --binary - <"$pf" 2>/dev/null &&
+				t="$(GIT_INDEX_FILE="$idx2" git write-tree 2>/dev/null)"; then
+				good="$t"
+			else
+				conflict=1
+				GIT_INDEX_FILE="$idx2" git read-tree "$good"
+			fi
+		fi
+		i=$((i + 1))
+	done
+	tree="$good"
+else
+	tree="$(worktree_tree)"
+	conflict=0
+fi
+
+# A conflict note is about edits, not the diff, so it must be reported whether or
+# not anything could be applied — otherwise an all-overlapping case would wrongly
+# look like "no edits".
+if [ "$conflict" -eq 1 ]; then
+	echo "note: some edits overlap the PR tip; git review finish will need a 3-way merge to apply them (they are omitted below)" >&2
+fi
+
+if git diff --quiet "$tip" "$tree"; then
+	if [ "$conflict" -eq 1 ]; then
+		echo "all your edits overlap the PR tip; nothing previews cleanly — run git review finish to resolve them with a 3-way merge" >&2
+	else
+		echo "no review changes yet — edit some files, then run $prog again"
+	fi
+	exit 0
+fi
+
+if [ "$stat" -eq 1 ]; then
+	git diff --stat "$tip" "$tree"
+else
+	git diff "$tip" "$tree"
+fi