git-pr-merge

#!/bin/bash
#
# Merge and update branches for GitHub Pull Requests (PRs).
#
# Usage: git <pr-merge|pr-update>
#
# git pr-merge
# ------------
# Merge the current "feature" branch into the base "master" branch and push
# to GitHub, closing the PR.
#
# Alternatively, merge a PR by number with `-p NN` into the base "master"
# branch and push to GitHub.
#
# GitHub allows you to push a merge commit on a branch even when that branch is
# protected, if that commit is the result of merging a PR and that PR is
# suitable to be merged (all required checks have been satisfied, the required
# number of approvals are present, the branch is up-to-date WRT the target
# branch, etc). This feature allows you to operate from the command line
# instead of needing to use the GitHub web-ui to merge and close a PR.
#
# git pr-update
# -------------
# Update the current "feature" branch by merging the base "master" branch
# into it, ready for merging with "git pr-merge".
#
# If you have "Require branches to be up-to-date" on branch protection, you
# cannot merge a PR if the base "master" branch has moved on from where the
# feature branch was branched from master. The GitHub UI has an "Update Branch"
# button that merges master into the branch, which gets it up-to-date from the
# base branch, but the merge commit added to the branch is a "back merge". If
# that is fast-forward merged into master, you end up with a "foxtrot" merge
# where the first parent is the feature branch, not the master branch, breaking
# `git log --first-parent`. If you do a merge commit back into master, you end
# up with merges going back and forth between master and feature branches,
# making a mess of your history. Neither is ideal.
#
# When run as "git pr-update", this script will create a merge commit from
# master on the head of the feature branch, but that commit will have the
# correct order of parents and a complete merge commit message such that it
# can be fast-forward merged into master. This will allow CI to run on the
# result of merging master as the branch will be up-to-date, but no foxtrot
# or criss-cross merges will occur. If the head commit is already a merge
# commit from this script, it will be removed before re-merging so as to
# not have a bunch of unnecessary merges.
#
# Requirements
# ------------
# This scripts relies on the github `gh` tool to retrieve information about
# the merge branch PR. It will fail if not installed. Install it from
# https://github.com/cli/cli.

main() {
	set -e
	set -u
	set -o pipefail
	shopt -s extglob

	case "${0##*/}" in
	git-pr-merge)
		prmerge "$@"
		;;
	git-pr-update)
		prupdate "$@"
		;;
	*)
		printf 'Unknown command name: %s\n' "$0" >&2
		exit 1
		;;
	esac
}

prmerge::usage() {
	cat <<EOF
Usage: ${0##*/} {<options>...}
  -m    Merge PR with a merge commit (overrides git-config)
  -p NN Merge PR <NN> instead of the current branch
  -s    Merge PR with a squash merge (overrides git-config)

${0##*/} merges the current branch's GitHub pull request (PR) to the
base branch of the PR, or the PR specified with "-p NN", using the PR
description as the merge commit message along with a diff stat and a
one-line log of the commits in the PR. The markdown in the PR
description is cleaned up a little to be more suitable for a git commit
message.

By default a merge commit is created, but the PR can be squash-merged
by running with "-s" or by setting the git comfig setting:

  git config pr.merge.squash true

You can have single commit PRs squash merged and multi-commit PRs merged
with a merge commit by setting the git config setting:

  git config pr.merge.squash-singles true

The title of the merge commit can have a prefix prepended to the title,
which by default is "✨ ". It can be overridden by a git config setting:

  git config pr.merge.title-prefix ''

After merging, the PR branch is automatically deleted both locally and on the
remote. This can be changed with the git config setting:

  git config pr.merge.delete-remote-branch false

EOF
}

prmerge() {
	args=()
	common::read_config
	prmerge::parse_args "$@"
	common::setup ${args[@]+"${args[@]}"}
	prmerge::prepare
	prmerge::merge
	prmerge::clean
}

prupdate() {
	common::read_config
	common::setup "$@"
	prupdate::prepare
	prupdate::update
}

# Read the config variables used by this script. For example, set them with:
# git config pr.merge.title-prefix ''
# git config pr.merge.delete-remote-branch false
# git config --global pr.merge.sleep-time-before-delete 10
# git config pr.merge.squash true
# git config pr.merge.squash-singles true

title_prefix='✨ '
cli_pr_num=''
delete_remote_branch='true'
sleep_time_before_delete='15'
squash_merge='false'
squash_singles='false'

common::read_config() {
	common::get_config title_prefix title-prefix
	common::get_config delete_remote_branch delete-remote-branch
	common::get_config sleep_time_before_delete sleep-time-before-delete
	common::get_config squash_merge squash
	common::get_config squash_singles squash-singles
}

prmerge::parse_args() {
	OPTSTRING=':hmp:s'
	while getopts "${OPTSTRING}" opt; do
		case "${opt}" in
		h)
			prmerge::usage
			exit 0
			;;
		m)
			squash_merge='false'
			;;
		p)
			cli_pr_num="${OPTARG}"
			;;
		s)
			squash_merge='true'
			;;
		\?)
			printf 'Invalid option: -%s\n\n' "${OPTARG}" >&2
			usage >&2
			exit 1
			;;
		:)
			printf 'Option -%s requires an argument\n\n' "${OPTARG}" >&2
			usage >&2
			exit 1
			;;
		esac
	done
	shift $((OPTIND - 1))

	args=("$@")
}

common::setup() {
	if ! command -v gh >/dev/null; then
		printf 'You need to install gh (https://github.com/cli/cli)\n' >&2
		return 1
	fi

	# If called with a PR number, check out that PR using `gh`. This is used
	# when merging someone elses PR (either from a fork or you just dont have
	# the local branch).
	if [[ -n "${cli_pr_num}" ]]; then
		if ! gh pr checkout "${cli_pr_num}"; then
			printf 'Could not checkout PR#%s\n' "${cli_pr_num}"
			return 1
		fi
	fi

	if ! feature=$(git symbolic-ref --short --quiet HEAD); then
		printf 'Not on a branch. Ignoring.\n' >&2
		return 1
	fi

	if [[ -n "${cli_pr_num}" ]]; then
		pr_ref="${cli_pr_num}"
	else
		pr_ref="${feature}"
	fi

	if ! master=$(gh pr view --json baseRefName --jq .baseRefName "${pr_ref}"); then
		printf 'Cannot get base branch for pull request. Is there a PR?\n' >&2
		return 1
	fi

	pr_num="$(gh pr view --json number --jq .number "${pr_ref}")"

	if [[ "${squash_singles}" == 'true' && "${squash_merge}" == 'false' ]]; then
		if [[ "$(git rev-list --count "${feature}" "^${master}" --)" == 1 ]]; then
			squash_merge=true
		fi
	fi
}

common::prepare() {
	# cd to root of repo as master may not contain CWD, but switch back
	# when we're done.
	# shellcheck disable=SC2064
	# We want to evaluate $(pwd) now and not later.
	trap "cd \"$(pwd)\"" EXIT
	cd "$(git rev-parse --show-toplevel)"

	# Fetch from all remotes so we can check if local branch is up-to-date
	git remote update >/dev/null
}

prmerge::prepare() {
	common::prepare

	local do_pull=false
	if [[ "$(git rev-parse "${master}")" != "$(git rev-parse "${master}@{upstream}")" ]]; then
		printf '\n%s is not up-to-date. To update, press enter (^C to abort):' "${master}"
		read -r
		do_pull=true
	fi

	git switch --quiet "${master}"

	if "${do_pull}"; then
		git pull
		if ! git merge-base --is-ancestor "${master}" "${feature}"; then
			# If we are merging via PR number and not a local branch, delete the branch we
			# created with `gh pr checkout` earlier. This will leave us on master.
			if [[ -n "${cli_pr_num}" ]]; then
				git branch --delete "${feature}"
			else
				git switch "${feature}"
			fi
			printf 'Local %s is not up-to-date. Update %s before merging\n' "${master}" "${feature}"
			exit 1
		fi
	fi
}

prupdate::prepare() {
	common::prepare

	if git merge-base --is-ancestor "${master}@{upstream}" "${feature}"; then
		printf 'Already up to date\n'
		exit 0
	fi

	# If we create an update-merge and push that to the feature branch, GitHub
	# shows the commits from master as well as the feature branch on the PR.
	# It also removes any approval which may have been grated. This defeats the
	# purpose of pushing an update merge - the point is to retain approval.
	#
	# Through experimentation, we have determined that if you push a foxtrot
	# update merge, GitHub updates the PRs base.sha field, which is what is
	# necessary to not have GitHub show the commits on master on the PR. You
	# can then remove that merge commit and force push it, which leaves the
	# base.sha updated, and it does not remove approval. The PR/branch is
	# then read to receive a proper update merge commit successfully.
	#
	# If the head commit on the branch is an update merge we have previously
	# put there, prepare the branch by removing it, so there is only ever one
	# merge commit on the branch. Otherwise, perform the steps described above
	# (push and remove a foxtrot update merge), so we can push a proper
	# update merge without dropping approval on the PR.
	read -ra parents < <(git show --no-patch --format='%P' "${feature}" --)
	if ((${#parents[@]} == 2)) && git merge-base --is-ancestor "${master}" "${parents[0]}"; then
		printf '\nHEAD looks to be a previous git-pr-update merge commit.\n'
		read -r -p 'Will first undo this (reset, force-push). Press enter (^C to abort):'
		printf '\nRemoving previous update merge\n'
		git reset --hard @^2
	else
		printf '\nCreating bogus foxtrot merge\n'
		git merge --no-edit --no-ff "${master}@{upstream}"
		printf '\nPushing bogus foxtrot merge\n'
		git push
		printf '\nRemoving bogus foxtrot merge\n'
		git reset --hard @^1
	fi

	printf '\nForce pushing merge removal\n'
	git push --force
}

prmerge::merge() {
	if "${squash_merge}"; then
		prmerge::squash_merge
	else
		prmerge::local_merge
	fi
}

prmerge::local_merge() {
	echo merging "${feature}" to "${master}"

	#open 'https://gist.github.com/rxaviers/7360908'
	#open 'https://gitmoji.carloscuesta.me'

	# If the feature branch has been updated with git-pr-update, then the head
	# of the feature branch will be a merge commit that has the master branch
	# as the first parent. In that case, just fast-forward merge instead of
	# creating a merge commit.
	read -ra parents < <(git show --no-patch --format='%P' "${feature}" --)
	master_hash=$(git rev-parse "${master}")
	if ((${#parents[@]} == 2)) && [[ "${parents[0]}" == "${master_hash}" ]]; then
		git merge --ff --no-edit "${feature}"
	else
		merge_message="$(common::merge_message "${feature}" "${master}" "${pr_ref}")"
		if ! git merge --edit --no-ff -m "${merge_message}" "${feature}"; then
			printf 'merge aborted\n' >&2
			git merge --abort
			git switch --quiet "${feature}"
			return 1
		fi
	fi

	# Pushing the merge commit will merge the PR with a merge commit, both
	# for local changes and PRs of forked repos when merged by PR num
	# (-p flag).
	git push
}

prmerge::squash_merge() {
	echo squash merging "${feature}" to "${master}"
	commit_msg_file=$(mktemp "git-prmerge.${pr_num}.XXXXXXXXX")
	# shellcheck disable=SC2064
	trap "rm ${commit_msg_file}" EXIT

	common::merge_message "${feature}" "${master}" "${pr_ref}" >"${commit_msg_file}"
	common::editor "${commit_msg_file}"
	if ! grep -E -q -v -e '^[[:space:]]*(#|$)' "${commit_msg_file}"; then
		printf 'no commit message. merge aborted\n'
		git switch --quiet "${feature}"
		return 1
	fi
	local commit_title commit_message
	commit_title=$(grep -v '^[[:space:]]*#' "${commit_msg_file}" | head -n 1)
	commit_message=$(grep -v '^[[:space:]]*#' "${commit_msg_file}" | tail -n +3)

	local result
	if ! result=$(
		gh api "repos/{owner}/{repo}/pulls/${pr_num}/merge" \
			--method PUT \
			--header 'Accept: application/vnd.github.v3+json' \
			--raw-field "commit_title=${commit_title}" \
			--raw-field "commit_message=${commit_message}"$'\n' \
			--raw-field "sha=$(git rev-parse "${feature}")" \
			--raw-field "merge_method=squash"
	); then
		jq --raw-output .message <<<"${result}"
		git switch --quiet "${feature}"
		return 1
	fi

	# Fetch the new merge commit
	git pull
}

prupdate::update() {
	echo updating "${feature}" from "${master}"

	# Create a temporary branch from ${master} so we can merge the
	# feature branch into it.
	local tmpmaster="prupdate/${feature}"
	git branch --force "${tmpmaster}" "${master}@{upstream}"
	git switch --quiet "${tmpmaster}"

	merge_message="$(common::merge_message "${feature}" "${tmpmaster}" "${pr_ref}")"
	if ! git merge --edit --no-ff -m "${merge_message}" "${feature}"; then
		printf 'merge aborted\n' >&2
		git merge --abort
		git switch --quiet "${feature}"
		git branch --delete --force "${tmpmaster}"
		return 1
	fi

	# reset feature branch to updated feature branch
	git switch --quiet "${feature}"
	git reset --hard "${tmpmaster}"
	git branch --delete --force "${tmpmaster}"
	git push
}

prmerge::clean() {
	# Feature branches need to be force-deleted after a squash merge as they
	# appear unmerged locally. So just always force delete.
	git branch --delete --force "${feature}"

	if remote=$(git rev-parse --abbrev-ref --symbolic-full-name '@{u}' 2>/dev/null); then
		remote=${remote%%/*} # strip off branch name
	else
		remote='origin' # default if tracking not set
	fi

	# Allow a delay before deleting the remote branch as some syncing programs
	# try to sync the merge commit and the branch deletion in parallel, leaving
	# one to fail, mucking up the github status. This delay is also used to wait
	# before pruning remote branches as automatic delete on merge does not
	# usually happen immediately.
	if ((sleep_time_before_delete > 0)); then
		printf 'Waiting before deleting/pruning remote branch (%s)...\n' "${sleep_time_before_delete}"
		sleep "${sleep_time_before_delete}"
	fi

	local autodelete
	autodelete=$(gh repo view --json deleteBranchOnMerge --jq .deleteBranchOnMerge)
	if [[ "${delete_remote_branch}" == 'true' ]] && [[ "${autodelete}" == 'false' ]]; then
		if ! git push "${remote}" --delete "${feature}"; then
			echo 'Perhaps GitHub already deleted the branch? Disable deletion with:'
			echo 'git config pr.merge.delete-remote-branch false'
		fi
	else
		# Assume the remote branch is automatically deleted. Prune remote refs.
		git remote prune "${remote}"
	fi
}

common::get_config() {
	local var="$1" name="$2"
	local val
	if val=$(git config --get pr.merge."${name}"); then
		eval "${var}='${val}'"
	fi
}

common::editor() {
	local e
	if ! e=$(git config --get core.editor); then
		e=${VISUAL:-${EDITOR:-vi}}
	fi

	$e "$@"
}

common::merge_message() {
	local from_branch="$1"
	local to_branch="$2"
	local pr_ref="$3"
	# Create default merge log message by making a title prefix (from config),
	# title from the PR title and the PR number, then adding a short log of
	# what is being merged and add a diff stat of the files changed by the merge.

	# Get the PR body to be the commit message. Remove any trailers so we
	# can re-add them after the log and diff-stat along with our own
	# Pull-request: trailer.
	local body trailers title pr_url
	title="$(gh pr view --json title --jq .title "${pr_ref}")"
	body=$(gh pr view --json body --jq .body "${pr_ref}" | tr -d '\015')
	body=$(awk "${markdown_for_commit_awk}" <<<"${body}") # clean up markdown for readability
	body="${body%%*($'\n')}"                              # strip trailing newlines.
	trailers=$(git interpret-trailers --parse <<<"${body}")
	body="${body%%*($'\n')"${trailers}"}" # strip trailers and preceding newlines

	pr_url="$(gh pr view --json url --jq .url "${pr_ref}")"

	cat <<EOF
${title_prefix}${title} (#${pr_num})

${body}
EOF

	# Don't include the commit titles or diff stat if squash merging - it doesn't
	# make sense, because usually there are fixup commits with irrelevant titles
	# and the diff stat can be easily shown with `git log --stat=72 ...`.
	if ! "${squash_merge}"; then
		cat <<EOF

This merges the following commits:
$(git log --reverse --pretty=tformat:"* %s" "${to_branch}..${from_branch}")

$(git diff --no-color --stat=72 "${to_branch}...${from_branch}" | sed 's/^/    /')
EOF
	fi

	# Put a newline ahead of $trailers only if it is non-empty, otherwise we end
	# up with two newlines in the empty trailers case.
	trailers="${trailers:+$'\n'${trailers}}"
	cat <<EOF
${trailers}
Pull-request: ${pr_url}

# Gitmoji: https://gitmoji.carloscuesta.me
# rxaviers list: https://gist.github.com/rxaviers/7360908
#
EOF
}

# shellcheck disable=SC2016
# We don't want to expand shell expressions (it's awk!), so single quotes.
markdown_for_commit_awk='
# print_heading converts a heading starting with a hash to one with an
# underline, as a line starting with a hash in a git commit message is
# ignored.
function print_heading(line)
{
  level1heading = match(line, /^# /) != 0
  sub(/^##* /, "", line)
  marker = level1heading ? "=" : "-"
  printf("%s\n", line)
  for (i = 0; i < length(line); i++)
    printf marker
  printf "\n"
}

# If there is a triple dash line --- preceded by a blank line, throw
# it out and everything after it. These are reviewer notes and do not
# go into the commit message.
/^---$/ && last_blank { exit }

# If we want a blank and the current line is not blank, inject a blank line.
/\S/ && want_blank { print "" }
{ want_blank = 0 }

# Lines starting with one or more hashes, followed by a space and one more
# char at least are headings. Convert to underline headings.
/^##* .+/ { print_heading($0); next }

# Convert triple-backtick code blocks to indented code blocks. Ensure there
# is a blank line before and after the block, but dont add extra unnecessary
# blank lines.
/^\s*```/ {
  in_code_block = !in_code_block
  want_blank = !last_blank
  next
}

# Print other lines, indenting code blocks
{
  last_blank = (gsub(/^\s*$/, "") > 0)
  printf("%s%s\n", in_code_block ? "    " : "", $0)
}'

# Only run main if executed as a script and not sourced.
if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then main "$@"; fi