git-review-workflow 0.1.0

package/bin/git-review-verbs/save

@@ -0,0 +1,167 @@
+#!/usr/bin/env sh
+#
+# git review save — pause the review on the current branch and put it aside.
+#
+# A review in progress lives on a review/<branch> branch. Saving it converts that
+# branch into review-saved/<branch> and returns you to where you started, so you
+# can pick up something else and resume later with git review continue.
+#
+# The saved review carries everything needed to resume exactly where you left off:
+#   whole mode  the staged PR diff and your uncommitted edits, captured as a
+#               commit whose diff against the tip is just your edits.
+#   step mode   the step you are on, the edits on it, and every edit you have
+#               banked on other commits — the banked-edit refs are moved out of
+#               refs/review-edits/ (which git review clean prunes) into
+#               refs/review-saved-edits/ so a git review clean never touches them.
+#
+set -eu
+
+prog="git review save"
+
+usage() {
+	cat <<EOF
+usage: $prog
+
+Pause the review on the current review/* branch: stash it as review-saved/<branch>
+and return to the branch you started from. Resume it later with git review continue.
+EOF
+}
+
+die() {
+	echo "error: $1" >&2
+	exit 1
+}
+
+case "${1:-}" in
+-h | --h)
+	usage
+	exit 0
+	;;
+"") ;;
+*)
+	echo "error: unexpected argument $1" >&2
+	usage >&2
+	exit 1
+	;;
+esac
+
+cur="$(git symbolic-ref --quiet --short HEAD || true)"
+case "$cur" in
+review/*) ;;
+*)
+	echo "error: 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)"
+if [ -z "$src" ] || [ -z "$tip" ]; then
+	die "missing review metadata; was $cur created with git review start?"
+fi
+
+saved="review-saved/$src"
+git rev-parse --verify --quiet "refs/heads/$saved" >/dev/null &&
+	die "$saved already exists; resume it with git review continue or discard it with git review forget --saved $src"
+
+mode="$(git config "branch.$cur.reviewmode" || echo whole)"
+
+# Where to return to once the review is put aside — the branch you started from,
+# falling back to the base branch, exactly like git review abort.
+ret="$(git config "branch.$cur.reviewreturn" || true)"
+base="$(git config "branch.$cur.reviewbase" || true)"
+target=""
+if [ -n "$ret" ] && git rev-parse --verify --quiet "refs/heads/$ret" >/dev/null; then
+	target="$ret"
+elif [ -n "$base" ] && git rev-parse --verify --quiet "refs/heads/$base" >/dev/null; then
+	target="$base"
+fi
+[ -n "$target" ] || die "could not determine a branch to return to; switch away manually first"
+
+# copy_meta <key>: copy branch.<cur>.<key> to branch.<saved>.<key> when set.
+# The explicit if (rather than a && one-liner) keeps the function's exit status 0
+# when the key is absent, so it does not trip set -e for the optional keys.
+copy_meta() {
+	v="$(git config "branch.$cur.$1" || true)"
+	if [ -n "$v" ]; then
+		git config "branch.$saved.$1" "$v"
+	fi
+}
+
+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. Unlike status/preview there is no later numeric guard, so cover step too.
+	if [ -z "$start" ] || [ -z "$count" ] || [ -z "$step" ]; then
+		die "missing review metadata; was $cur created with git review start?"
+	fi
+	commits="$(git rev-list --reverse --first-parent --no-merges "$start..$tip")"
+
+	# Bank the edits on the commit we are sitting on, the same way review-next does
+	# before it moves, so the current step's work joins the other banked steps.
+	cstep="$(printf '%s\n' "$commits" | sed -n "${step}p")"
+	git add -A
+	tree="$(git write-tree)"
+	if [ "$tree" != "$(git rev-parse "$cstep^{tree}")" ]; then
+		edit="$(git commit-tree "$tree" -p "$cstep" -m "review edits step $step")"
+		git update-ref "refs/review-edits/$src/$step" "$edit"
+	else
+		# Reverting the step back to a clean tree must clear any edits we banked
+		# earlier, or they resurrect when the saved review is restored.
+		git update-ref -d "refs/review-edits/$src/$step" 2>/dev/null || true
+	fi
+
+	# Move the banked edits aside so git review clean (which prunes refs/review-edits/)
+	# leaves the saved review intact, and so they travel with it.
+	git for-each-ref --format='%(refname)' "refs/review-edits/$src/" | while read -r ref; do
+		n="${ref##*/}"
+		git update-ref "refs/review-saved-edits/$src/$n" "$(git rev-parse "$ref")"
+		git update-ref -d "$ref"
+	done
+
+	# The visible branch is just an anchor + metadata holder; point it at the tip.
+	git update-ref "refs/heads/$saved" "$tip"
+	git config "branch.$saved.reviewmode" step
+	copy_meta reviewstart
+	copy_meta reviewcount
+	copy_meta reviewstep
+	note="on step $step/$count"
+else
+	# whole mode: HEAD is the review's lower bound, the index holds the staged PR
+	# diff and the working tree holds that plus your edits. Capture the working tree
+	# as a commit parented on the tip, so its diff against the tip is exactly your
+	# edits — review-continue replays that to restore the editable state.
+	lower="$(git rev-parse HEAD)"
+	git add -A
+	tree="$(git write-tree)"
+	# Parent the saved commit on both the tip and the lower bound. The tip parent
+	# makes "git diff tip..saved" exactly your edits; the lower parent keeps the
+	# lower bound reachable even when it is a synthetic merge-tree commit (the
+	# folded-base case in git review start), so a gc between save and continue cannot
+	# prune it out from under "git reset --soft $lower".
+	commit="$(git commit-tree "$tree" -p "$tip" -p "$lower" -m "git review save: $src")"
+	git update-ref "refs/heads/$saved" "$commit"
+	git config "branch.$saved.reviewmode" whole
+	git config "branch.$saved.reviewsavedlower" "$lower"
+	note="whole-PR review"
+fi
+
+# Metadata common to both modes.
+copy_meta reviewsource
+copy_meta reviewbase
+copy_meta reviewtip
+copy_meta reviewprevreviewed
+copy_meta reviewlocal
+git config "branch.$saved.reviewreturn" "$target"
+
+# Leave the review branch: drop its working-tree changes (captured above), return
+# to the starting branch and delete review/<src>. Its config goes with it; the
+# saved copy already holds everything.
+git switch -q --discard-changes "$target"
+git branch -D "$cur" >/dev/null
+
+echo "saved review of $src ($note) as $saved; returned to $target"
+echo "resume it with git review continue"

package/bin/git-review-verbs/start

@@ -0,0 +1,333 @@
+#!/usr/bin/env sh
+#
+# git review start — stage a pull request diff on a review/<branch> branch.
+#
+# Two independent axes:
+#   range  — where the review starts: the merge-base with the base branch
+#            (default), your last review (--delta), or an explicit commit
+#            (--from <commit>).
+#   layout — how you see it: the whole range as one staged diff (default), or
+#            one commit at a time (--step, advance with git review next).
+#
+set -eu
+
+prog="git review start"
+
+usage() {
+	cat <<EOF
+usage: $prog [<branch>] [<base> | --base <base> | --delta | --from <commit>] [--step] [--local]
+
+Stage a pull request diff on a review/<branch> branch for inline review.
+With no <branch>, review the branch you currently have checked out.
+
+  <branch>          branch to review; omit it to review the current branch
+  <base>            commit-ish to diff against — a branch, tag or commit
+                    (required for a full review; set a default with:
+                    git config reviewworkflow.base <branch>)
+  --base <base>     the base to diff against; use it to pass a base while
+                    letting <branch> default to the current branch
+  --delta           review only the commits added since your last review
+  --from <commit>   review only the commits after <commit>
+  --step            review one commit at a time; advance with git review next
+  --local           review your local branches directly, without fetching
+EOF
+}
+
+die() {
+	echo "error: $1" >&2
+	exit 1
+}
+
+src=""
+base=""
+base_explicit=0
+from=""
+delta=0
+step=0
+local_mode=0
+while [ $# -gt 0 ]; do
+	case "$1" in
+	-h | --h)
+		usage
+		exit 0
+		;;
+	-d | --delta) delta=1 ;;
+	--step) step=1 ;;
+	--local) local_mode=1 ;;
+	--base)
+		shift
+		[ $# -gt 0 ] || die "--base requires a base"
+		[ -n "$1" ] || die "--base requires a base"
+		[ "$base_explicit" -eq 0 ] || die "base given more than once"
+		base="$1"
+		base_explicit=1
+		;;
+	--base=*)
+		[ "$base_explicit" -eq 0 ] || die "base given more than once"
+		base="${1#--base=}"
+		[ -n "$base" ] || die "--base requires a base"
+		base_explicit=1
+		;;
+	--from)
+		shift
+		[ $# -gt 0 ] || die "--from requires a commit"
+		from="$1"
+		[ -n "$from" ] || die "--from requires a commit"
+		;;
+	--from=*)
+		from="${1#--from=}"
+		[ -n "$from" ] || die "--from requires a commit"
+		;;
+	--)
+		# End-of-options, the git convention: everything after is positional,
+		# so a branch whose name starts with "-" (or collides with a flag) can
+		# still be reviewed, e.g. git review start -- --weird develop.
+		shift
+		while [ $# -gt 0 ]; do
+			if [ -z "$src" ]; then
+				src="$1"
+			elif [ -z "$base" ]; then
+				base="$1"
+				base_explicit=1
+			else
+				die "unexpected argument $1"
+			fi
+			shift
+		done
+		break
+		;;
+	-*)
+		echo "error: unknown option $1" >&2
+		usage >&2
+		exit 1
+		;;
+	*)
+		if [ -z "$src" ]; then
+			src="$1"
+		elif [ -z "$base" ]; then
+			base="$1"
+			base_explicit=1
+		else
+			die "unexpected argument $1"
+		fi
+		;;
+	esac
+	shift
+done
+
+if [ "$delta" -eq 1 ] && [ -n "$from" ]; then
+	die "use only one of --delta and --from"
+fi
+
+if [ "$base_explicit" -eq 1 ] && { [ "$delta" -eq 1 ] || [ -n "$from" ]; }; then
+	die "base is ignored with --delta/--from; pass only one"
+fi
+
+git rev-parse --git-dir >/dev/null 2>&1 || die "not a git repository"
+
+# 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"
+
+# With no <branch>, review the branch you currently have checked out. This is
+# git's own default — push, status, log and rebase all act on the current branch
+# when you name nothing. It only resolves the name; the mode (remote vs --local)
+# is still chosen by flags. The check against the review/*, review-saved/* and
+# review-fixes/* namespaces avoids the nonsense of reviewing a review branch.
+if [ -z "$src" ]; then
+	cur="$(git symbolic-ref --quiet --short HEAD || true)"
+	[ -n "$cur" ] || die "no branch given and HEAD is detached; name a branch to review"
+	case "$cur" in
+	review/* | review-saved/* | review-fixes/*) die "refusing to review a review branch (HEAD is $cur); name a branch to review" ;;
+	esac
+	src="$cur"
+fi
+
+# Remote to review from; defaults to origin, override with reviewworkflow.remote.
+remote="$(git config reviewworkflow.remote || echo origin)"
+
+# Remember where to return to when the review is aborted.
+returnbranch="$(git symbolic-ref --quiet --short HEAD || true)"
+
+if [ -z "$base" ]; then
+	base="$(git config reviewworkflow.base || true)"
+fi
+
+if ! git diff --quiet || ! git diff --cached --quiet; then
+	die "you have local changes; commit or stash them first"
+fi
+
+# --local reviews your local branches directly; the default reviews the remote's.
+# The two are kept apart everywhere: which ref the tip comes from, how it is named
+# in messages, and the delta marker — local markers live in their own config
+# section (reviewworkflowlocal.*) so a local and a remote review of the same branch
+# name never overwrite each other's progress. A separate section, rather than a
+# reviewworkflow.<src>.local.reviewed key, is deliberate: the latter would be
+# ambiguous for a branch literally named "<src>.local".
+if [ "$local_mode" -eq 1 ]; then
+	srcref="refs/heads/$src"
+	srclabel="$src"
+	markerkey="reviewworkflowlocal.$src.reviewed"
+else
+	git fetch --quiet "$remote" || die "could not update from $remote"
+	srcref="refs/remotes/$remote/$src"
+	srclabel="$remote/$src"
+	markerkey="reviewworkflow.$src.reviewed"
+fi
+
+# Resolve the base into a ref and a human label. A base is normally a branch, so
+# try the branch namespace first — the remote's copy, or the local branch with
+# --local — to keep the familiar origin/<base> labels and the merged-base folding
+# below. Anything that is not a branch there still works as a read-only lower
+# bound via any commit-ish: a tag, a SHA, or an origin/<x> spelled out in full.
+# baseref stays empty when the base does not resolve at all; the full-review path
+# treats that as fatal ("not found"), while the delta/from folding treats an
+# unresolvable base as a no-op, exactly as before.
+baseref=""
+baselabel="$base"
+if [ -n "$base" ]; then
+	if [ "$local_mode" -eq 1 ]; then
+		if git rev-parse --verify --quiet "refs/heads/$base^{commit}" >/dev/null; then
+			baseref="refs/heads/$base"
+		fi
+	else
+		if git rev-parse --verify --quiet "refs/remotes/$remote/$base^{commit}" >/dev/null; then
+			baseref="refs/remotes/$remote/$base"
+			baselabel="$remote/$base"
+		fi
+	fi
+	if [ -z "$baseref" ]; then
+		bcommit="$(git rev-parse --verify --quiet "$base^{commit}" || true)"
+		if [ -n "$bcommit" ]; then
+			baseref="$bcommit"
+		fi
+	fi
+fi
+
+git rev-parse --verify --quiet "$srcref" >/dev/null ||
+	die "$srclabel not found"
+
+rb="review/$src"
+git rev-parse --verify --quiet "refs/heads/$rb" >/dev/null &&
+	die "$rb already exists; run git review clean $src first"
+git rev-parse --verify --quiet "refs/heads/review-saved/$src" >/dev/null &&
+	die "you have a saved review of $src; resume it with git review continue $src or discard it with git review forget --saved $src"
+
+tip="$(git rev-parse "$srcref")"
+prev="$(git config "$markerkey" || true)"
+
+# A remote review targets the remote's copy of the branch, never your local one,
+# which git review start never updates. If a local branch of the same name exists
+# and points elsewhere, you are reviewing a different snapshot than the one you
+# have checked out — and a later git review finish --onto-source, which writes to
+# the local branch, will refuse unless it sits at the reviewed tip. Warn rather than
+# silently review the wrong thing; --local reviews what you have checked out.
+if [ "$local_mode" -eq 0 ]; then
+	localtip="$(git rev-parse --verify --quiet "refs/heads/$src" || true)"
+	if [ -n "$localtip" ] && [ "$localtip" != "$tip" ]; then
+		echo "note: reviewing $srclabel ($(git rev-parse --short "$tip")), which differs from your local $src ($(git rev-parse --short "$localtip")); use --local to review what you have checked out" >&2
+	fi
+fi
+
+# Resolve the lower bound of the review range (exclusive).
+if [ "$delta" -eq 1 ]; then
+	[ -n "$prev" ] || die "no previous review of $src recorded; run a full review first"
+	[ "$prev" != "$tip" ] || die "no new commits since your last review of $src"
+	git merge-base --is-ancestor "$prev" "$tip" ||
+		die "$src was force-pushed since your last review; run a full review instead"
+	start="$prev"
+	range="since last review ($(git rev-parse --short "$prev"))"
+elif [ -n "$from" ]; then
+	start="$(git rev-parse --verify --quiet "$from^{commit}")" || die "unknown commit: $from"
+	git merge-base --is-ancestor "$start" "$tip" ||
+		die "$from is not an ancestor of $srclabel"
+	[ "$start" != "$tip" ] || die "no commits to review after $from"
+	range="since $(git rev-parse --short "$start")"
+else
+	[ -n "$base" ] ||
+		die "no base branch set; pass one as an argument or with --base, or run: git config reviewworkflow.base <branch>"
+	[ -n "$baseref" ] ||
+		die "$baselabel not found"
+	start="$(git merge-base "$baseref" "$srcref")" ||
+		die "could not compute merge-base with $baselabel"
+	# Nothing to review when the source is already at the base (e.g. running on the
+	# base branch itself, or a branch fully merged into it). Mirror the explicit
+	# guards on --delta/--from instead of creating an empty review/ branch.
+	[ "$start" != "$tip" ] ||
+		die "no commits to review; $srclabel is already at $baselabel"
+	range="vs $baselabel"
+	if [ -n "$prev" ] && [ "$prev" != "$tip" ] && git merge-base --is-ancestor "$prev" "$tip"; then
+		n="$(git rev-list --count "$prev..$tip")"
+		echo "note: previously reviewed at $(git rev-parse --short "$prev"); $n new commit(s) since (use --delta to review only those)" >&2
+	fi
+fi
+
+if [ "$step" -eq 1 ]; then
+	# --first-parent --no-merges: walk only the branch's own commits, skipping
+	# merge commits (e.g. merges of the base branch) so changes that came from
+	# the base are never shown as a step.
+	commits="$(git rev-list --reverse --first-parent --no-merges "$start..$tip")"
+	[ -n "$commits" ] || die "no commits to review in range"
+	count="$(printf '%s\n' "$commits" | wc -l | tr -d ' ')"
+	first="$(printf '%s\n' "$commits" | sed -n '1p')"
+
+	git switch -q -c "$rb" "$first" || die "could not create $rb"
+	git reset --soft HEAD^
+	git config "branch.$rb.reviewsource" "$src"
+	git config "branch.$rb.reviewbase" "$base"
+	git config "branch.$rb.reviewtip" "$tip"
+	git config "branch.$rb.reviewstart" "$start"
+	git config "branch.$rb.reviewmode" "step"
+	git config "branch.$rb.reviewcount" "$count"
+	git config "branch.$rb.reviewstep" "1"
+	if [ -n "$prev" ]; then
+		git config "branch.$rb.reviewprevreviewed" "$prev"
+	fi
+	if [ "$local_mode" -eq 1 ]; then
+		git config "branch.$rb.reviewlocal" "1"
+	fi
+	git config "$markerkey" "$tip"
+	if [ -n "$returnbranch" ]; then
+		git config "branch.$rb.reviewreturn" "$returnbranch"
+	fi
+
+	echo "$rb ready ($range) — walking $count commit(s) one at a time"
+	show_commit "$first" 1 "$count"
+	exit 0
+fi
+
+# Lower bound for the staged diff. Normally it is the range start, but if the
+# base branch has been merged into the PR, fold that already-merged base content
+# into the lower bound so changes that came from the base do not appear as part
+# of the review. This is a no-op when the base was not merged in (it never
+# invents deletions), and degrades gracefully on git without merge-tree.
+lower="$start"
+if [ -n "$baseref" ]; then
+	mb="$(git merge-base "$baseref" "$tip" 2>/dev/null || true)"
+	if [ -n "$mb" ] && ! git merge-base --is-ancestor "$mb" "$start"; then
+		if ltree="$(git merge-tree --write-tree "$start" "$mb" 2>/dev/null)"; then
+			lower="$(git commit-tree "$ltree" -p "$start" -m 'review lower bound')"
+		else
+			echo "note: could not exclude merged base content from the review diff" >&2
+		fi
+	fi
+fi
+
+git switch -q -c "$rb" "$tip" || die "could not create $rb"
+git reset -q --soft "$lower"
+
+git config "branch.$rb.reviewsource" "$src"
+git config "branch.$rb.reviewbase" "$base"
+git config "branch.$rb.reviewtip" "$tip"
+if [ -n "$prev" ]; then
+	git config "branch.$rb.reviewprevreviewed" "$prev"
+fi
+if [ "$local_mode" -eq 1 ]; then
+	git config "branch.$rb.reviewlocal" "1"
+fi
+git config "$markerkey" "$tip"
+if [ -n "$returnbranch" ]; then
+	git config "branch.$rb.reviewreturn" "$returnbranch"
+fi
+
+echo "$rb ready ($range) — the staged diff is the PR; edit, then run git review finish"

package/bin/git-review-verbs/status

@@ -0,0 +1,99 @@
+#!/usr/bin/env sh
+#
+# git review status — show the state of the review on the current branch.
+#
+set -eu
+
+prog="git review status"
+
+usage() {
+	cat <<EOF
+usage: $prog
+
+Show the state of the review on the current review/* branch: source PR, mode,
+and (in commit-by-commit mode) which commit you are on and which steps have
+banked edits.
+EOF
+}
+
+case "${1:-}" in
+-h | --h)
+	usage
+	exit 0
+	;;
+"") ;;
+*)
+	echo "error: unexpected argument $1" >&2
+	usage >&2
+	exit 1
+	;;
+esac
+
+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
+	echo "error: missing review metadata; was $cur created with git review start?" >&2
+	exit 1
+fi
+
+printf 'review of %s (tip %s)\n' "$src" "$(git rev-parse --short "$tip")"
+printf '  branch  %s\n' "$cur"
+
+if [ "$mode" = "step" ]; then
+	count="$(git config "branch.$cur.reviewcount" || true)"
+	step="$(git config "branch.$cur.reviewstep" || true)"
+	start="$(git config "branch.$cur.reviewstart" || 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 "$count" ] || [ -z "$start" ]; then
+		echo "error: missing review metadata; was $cur created with git review start?" >&2
+		exit 1
+	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 cnow ends up empty and git rev-parse '' crashes while
+	# the printf around it still "succeeds", printing a corrupt status line.
+	total="$(printf '%s\n' "$commits" | grep -c .)"
+	case "$step" in
+	'' | *[!0-9]*)
+		echo "error: corrupt review metadata: reviewstep is '$step', not a positive integer" >&2
+		exit 1
+		;;
+	esac
+	if [ "$step" -lt 1 ] || [ "$step" -gt "$total" ]; then
+		echo "error: review step $step out of range (1..$total) — corrupt metadata?" >&2
+		exit 1
+	fi
+	cnow="$(printf '%s\n' "$commits" | sed -n "${step}p")"
+	printf '  mode    step  [%s/%s] on %s %s\n' "$step" "$count" \
+		"$(git rev-parse --short "$cnow")" "$(git log -1 --format='%s' "$cnow")"
+
+	banked=""
+	i=1
+	while [ "$i" -le "$count" ]; do
+		if git rev-parse --verify --quiet "refs/review-edits/$src/$i" >/dev/null; then
+			banked="$banked $i"
+		fi
+		i=$((i + 1))
+	done
+	printf '  banked  %s\n' "${banked:- none}"
+
+	hint="git review next"
+	[ "$step" -gt 1 ] && hint="$hint / git review prev"
+	printf '  next    edit, then %s  (git review finish when done)\n' "$hint"
+else
+	base="$(git config "branch.$cur.reviewbase" || true)"
+	printf '  mode    whole%s\n' "${base:+  (base $base)}"
+	printf '  next    edit, then git review finish\n'
+fi