Merge branch 'main' into unifying_the_style_checkers

Author: r-sharp

sbin/tagman

@@ -0,0 +1,340 @@
+#!/usr/bin/env bash
+# -----------------------------------------------------------------------------
+# (C) Crown copyright Met Office. All rights reserved.
+# The file LICENCE, distributed with this code, contains details of the terms
+# under which the code may be used.
+# -----------------------------------------------------------------------------
+#
+# Script to manage Git tags (add/delete/list).
+# Requires:
+#   GitHub CLI (gh): https://cli.github.com/
+#   Git command-line tool: https://git-scm.com/
+#   jq for JSON parsing: https://stedolan.github.io/jq/
+# Warnings:
+# - This script modifies Git tags. Use with caution.
+# - Always verify the current tags before making changes.
+# - Anyone with push/write access to the repository can create or delete tags.
+#   Ensure you have the necessary permissions and understand the implications
+#   of modifying tags in a shared repository.
+
+set -euo pipefail
+# Colour codes for output
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+YELLOW='\033[0;33m'
+NO_COLOR='\033[0m'
+
+# Default values
+DEFAULT_REPO="MetOffice/git_playground"
+REPO="${REPO:-$DEFAULT_REPO}"
+# Variables set by parse_args()
+REF=""
+TAG=""
+MESSAGE=""
+DRY_RUN=false
+
+usage() {
+  cat <<EOF
+Usage:
+  $(basename "$0") add <tag_name> <commit_ref> [options]
+  $(basename "$0") delete|del <tag_name> [options]
+  $(basename "$0") list|ls [options]
+
+Actions:
+  add       Create and push a new tag
+  delete    Delete a tag from the repository (alias: del)
+  list      List all tags in the repository (alias: ls)
+
+Arguments:
+  <tag_name>     Name of the tag to create or delete
+  <commit_ref>   Commit SHA, tag name, release name, or branch name
+
+Options:
+  --repo, -R REPO    Repository in format owner/repo (default: $DEFAULT_REPO)
+  --message MSG      Tag annotation message (for add action)
+  --dry-run, -n      Show what would be done without making changes
+
+Examples:
+  # Create tag from commit SHA or existing tag or release or branch
+  $(basename "$0") add Test abc123def|vn1.5|main --repo MetOffice/git_playground
+
+  # Delete tag
+  $(basename "$0") del 2025.12.0 --repo MetOffice/SimSys_Scripts
+
+Notes:
+  - REPO can be set via environment variable (default: $DEFAULT_REPO)
+  - All other parameters must be provided via command-line arguments
+  - Use --dry-run to preview changes before executing
+EOF
+  exit 1
+}
+
+cleanup() {
+  if [[ -n "${WORK_TMP:-}" ]]; then
+    rm -rf "$WORK_TMP"
+  fi
+}
+
+confirm() {
+  local message="$1"
+  local response
+  echo -en "${YELLOW}"
+  read -rp "$message (y/n): " response
+  echo -en "${NO_COLOR}"
+
+  case "${response^^}" in  # Note: requires bash 4+ for ^^ operator
+    YES | Y)
+      return 0 ;;
+    *)
+      echo "Aborted..."
+      return 1 ;;
+  esac
+}
+
+run() {
+  local msg="$1"
+  shift
+  local timestamp
+  timestamp=$(date "+%F %T")
+
+  if "$@"; then
+    echo -e "[$timestamp] ${GREEN}✓${NO_COLOR} $msg succeeded."
+    return 0
+  else
+    echo -e "[$timestamp] ${RED}✗${NO_COLOR} $msg failed."
+    return 1
+  fi
+}
+
+trap cleanup EXIT ERR SIGINT
+
+verify_tag() {
+  if gh api "repos/${REPO}/git/refs/tags/${TAG}" >/dev/null 2>&1; then
+    echo -e "${YELLOW}Tag '$TAG' exists in repository '$REPO'.${NO_COLOR}"
+    return 0
+  fi
+  return 1
+}
+
+verify_ref() {
+  local resolved_sha=""
+
+  # First, try to resolve as a commit SHA (handles both short and full)
+  if resolved_sha=$(gh api "repos/${REPO}/commits/${REF}" --jq '.sha' 2>/dev/null); then
+    REF="$resolved_sha"
+    echo -e "${GREEN}Using commit SHA: $REF${NO_COLOR}"
+    return 0
+  fi
+
+  # Try to resolve as a tag
+  if gh api "repos/${REPO}/git/refs/tags/${REF}" >/dev/null 2>&1; then
+    echo -e "${YELLOW}Resolving tag '$REF' to commit SHA...${NO_COLOR}"
+    local tag_sha
+    tag_sha=$(gh api "repos/${REPO}/git/refs/tags/${REF}" --jq '.object.sha')
+
+    # Try to get tag object to determine if it's annotated
+    local tag_info
+    if tag_info=$(gh api "repos/${REPO}/git/tags/${tag_sha}" 2>/dev/null); then
+      # It's an annotated tag - get the commit SHA it points to
+      local tag_type
+      tag_type=$(echo "$tag_info" | jq -r '.object.type')
+
+      if [[ "$tag_type" == "commit" ]]; then
+        resolved_sha=$(echo "$tag_info" | jq -r '.object.sha')
+      else
+        echo -e "${RED}** Tag points to object type: $tag_type, but a commit object type is expected${NO_COLOR}"
+        return 1
+      fi
+    else
+      # It's a lightweight tag - the SHA is the commit SHA
+      resolved_sha="$tag_sha"
+    fi
+
+    # Verify it's a full SHA and a valid commit
+    if resolved_sha=$(gh api "repos/${REPO}/commits/${resolved_sha}" --jq '.sha' 2>/dev/null); then
+      REF="$resolved_sha"
+      echo -e "${GREEN}Resolved to commit: $REF${NO_COLOR}"
+      return 0
+    else
+      echo -e "${RED}** Failed to verify commit SHA from tag${NO_COLOR}"
+      return 1
+    fi
+  fi
+
+  # Try to resolve as a release
+  if gh api "repos/${REPO}/releases/tags/${REF}" >/dev/null 2>&1; then
+    echo -e "${YELLOW}Resolving release '$REF' to commit SHA...${NO_COLOR}"
+    local target_ref
+    target_ref=$(gh api "repos/${REPO}/releases/tags/${REF}" --jq '.target_commitish')
+
+    # Resolve the target to full SHA
+    if resolved_sha=$(gh api "repos/${REPO}/commits/${target_ref}" --jq '.sha' 2>/dev/null); then
+      REF="$resolved_sha"
+      echo -e "${GREEN}Resolved to commit: $REF${NO_COLOR}"
+      return 0
+    else
+      echo -e "${RED}** Failed to resolve release target to commit SHA${NO_COLOR}"
+      return 1
+    fi
+  fi
+
+  # Try as a branch name
+  if gh api "repos/${REPO}/git/refs/heads/${REF}" >/dev/null 2>&1; then
+    echo -e "${YELLOW}Resolving branch '$REF' to commit SHA...${NO_COLOR}"
+    local branch_sha
+    branch_sha=$(gh api "repos/${REPO}/git/refs/heads/${REF}" --jq '.object.sha')
+
+    # Verify it's a full SHA
+    if resolved_sha=$(gh api "repos/${REPO}/commits/${branch_sha}" --jq '.sha' 2>/dev/null); then
+      REF="$resolved_sha"
+      echo -e "${GREEN}Resolved to commit: $REF${NO_COLOR}"
+      return 0
+    else
+      echo -e "${RED}** Failed to verify commit SHA from branch${NO_COLOR}"
+      return 1
+    fi
+  fi
+
+  echo -e "${RED}** Reference '$REF' not found in repository '$REPO'.${NO_COLOR}"
+  echo -e "${RED}** Tried: commit SHA, tag, release, and branch name.${NO_COLOR}"
+  return 1
+}
+
+add_tag() {
+  if [[ -z "$TAG" || -z "$REF" ]]; then
+    echo -e "${RED}** TAG and REF are required for add action.${NO_COLOR}"
+    usage
+  fi
+
+  if verify_tag ; then
+    exit 1  # Tag already exists, exit with error
+  fi
+  if ! verify_ref ; then
+    exit 1  # Reference resolution failed, exit with error
+  fi
+
+  local url="https://github.com/${REPO}.git"
+  local msg="${MESSAGE:-"Tagging $TAG @ $REF"}"
+
+  if [[ "$DRY_RUN" == true ]]; then
+    echo -e "${YELLOW}[DRY RUN] Would create tag with the following details:${NO_COLOR}"
+    echo -e "  Repository: $REPO"
+    echo -e "  Tag name:   $TAG"
+    echo -e "  Commit SHA: $REF"
+    echo -e "  Message:    $msg"
+    echo -e "${YELLOW}[DRY RUN] No changes made.${NO_COLOR}"
+    return 0
+  fi
+
+  WORK_TMP=$(mktemp -d -t tagman-XXXX)
+
+  pushd "$WORK_TMP" >/dev/null
+  run "Initialise temporary Git repository in $WORK_TMP" git init --bare --quiet
+  run "Add remote repository $url" git remote add origin "$url"
+  run "Fetch commit $REF" git fetch --quiet --depth 1 origin "$REF"
+  run "Create and sign tag '$TAG' at commit $REF" \
+    git tag --sign "$TAG" "$REF" --message "$msg"
+  run "Push '$TAG' to remote '$REPO'" git push --quiet origin "$TAG"
+  popd >/dev/null
+
+  echo -e "${GREEN}Successfully created and pushed tag '$TAG' to '$REPO'.${NO_COLOR}"
+}
+
+delete_tag() {
+  if [[ -z "$TAG" ]]; then
+    echo -e "${RED}** TAG is required for delete action.${NO_COLOR}"
+    usage
+  fi
+
+  if ! verify_tag; then
+    echo -e "${RED}** Tag '$TAG' does not exist in repository '$REPO'.${NO_COLOR}"
+    return 1
+  fi
+
+  if [[ "$DRY_RUN" == true ]]; then
+    echo -e "${YELLOW}[DRY RUN] Would delete tag with the following details:${NO_COLOR}"
+    echo -e "  Repository: $REPO"
+    echo -e "  Tag name:   $TAG"
+    echo -e "${YELLOW}[DRY RUN] No changes made.${NO_COLOR}"
+    return 0
+  fi
+
+  local url="https://github.com/${REPO}.git"
+
+  WORK_TMP=$(mktemp -d -t tagman-XXXX)
+
+  pushd "$WORK_TMP" >/dev/null
+  run "Initialise temporary Git repository in $WORK_TMP" git init --bare --quiet
+  run "Add remote repository $url" git remote add origin "$url"
+
+  if confirm "Are you sure you want to delete the tag '$TAG' from '$REPO'?"; then
+    run "Delete remote tag '$TAG' from '$REPO'" git push --quiet origin --delete "$TAG"
+    echo -e "${GREEN}Successfully deleted tag '$TAG' from '$REPO'.${NO_COLOR}"
+  fi
+  popd >/dev/null
+}
+
+list_tags() {
+  local url="https://github.com/${REPO}.git"
+  echo -e "${GREEN}Listing tags from '$REPO':${NO_COLOR}\n"
+  git ls-remote --tags --sort="-version:refname" "$url"
+}
+
+parse_args() {
+  if [[ $# -eq 0 ]]; then
+    usage
+  fi
+
+  ACTION="$1"
+  shift
+
+  case "$ACTION" in
+    add)
+      if [[ $# -lt 2 ]]; then
+        usage
+      fi
+      TAG="$1"
+      REF="$2"
+      shift 2
+      ;;
+    del|delete)
+      if [[ $# -lt 1 ]]; then
+        usage
+      fi
+      TAG="$1"
+      shift
+      ;;
+    ls|list)
+      # No arguments required
+      ;;
+    *)
+      echo -e "${RED}Unknown action: $ACTION${NO_COLOR}"
+      usage
+      ;;
+  esac
+
+  # Parse optional flags
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      -R|--repo) REPO="$2"; shift 2 ;;
+      --message) MESSAGE="$2"; shift 2 ;;
+      -n|--dry-run) DRY_RUN=true; shift ;;
+      *)
+        echo -e "${RED}Unknown option: $1${NO_COLOR}"
+        usage ;;
+    esac
+  done
+}
+
+main() {
+  parse_args "$@"
+
+  case "$ACTION" in
+    add) add_tag ;;
+    del|delete) delete_tag ;;
+    ls|list) list_tags ;;
+     *) echo -e "${RED}Invalid action: $ACTION${NO_COLOR}" ;;
+  esac
+}
+
+main "$@"