Synchronize tags

[pytooling-claude]

Rebased onto dev after #1 was merged; the base was retargeted automatically. Sibling of #2; the two are
independent.

New Features

• Tags are synchronized. gh repo sync knows branches only, so a fork drifts behind its upstream in releases
  even while its branches are current. Measured on the repositories this action will run against: ghdl/ghdl has
  46 tags, Paebbels/ghdl has 19 — among the 27 missing are v1.0.0rc1, v0.36-rc1 and v0.35rc2.

• An optional fourth field carries the tag patterns:

  ghdl/ghdl=ghdl:master:v\d+\.\d+.*
  OSVVM/OSVVM=OSVVM:main,dev:nightly,v\d+\.\d+\.\d+
  antonblanchard/microwatt=microwatt::v\d+\.\d+
  

  <upstream>=<fork>:<branches>[:<tagPatterns>]. A line without it behaves exactly as before, so every existing
  configuration file keeps working untouched. As the third line shows, the branch list may be empty when tag
  patterns are given — a fork followed for its releases only.

• A pattern is a fixed name or a regular expression, matched against the whole tag name. Both forms in one
  list, comma separated.

• What happens per matching tag of the upstream:

  Situation	Result
  The fork doesn't have it	Created at the same object — 🏷️ v2.1.0 — created from OSVVM/OSVVM@a1b2c3d
  The fork has it, same object	Counted, reported as one line per repository (🟰 12 tag(s) already up to date)
  The fork has it, different object	Error, tag left alone, run continues

  The moved case reads:
  ☢️ v1.0.0 — moved in 'OSVVM/OSVVM' (fork 90e6af7, upstream d3d07ba)
  and the annotation carries both SHAs. It is deliberately not rewritten: git push --force on a tag discards
  whatever the fork's tag points at, and that is not a decision an unattended nightly job should make. Deleting the
  tag in the fork lets the next run recreate it.

• created-tags is a new output parameter and a new line in the summary. Tags are never deleted from a fork, and
  a tag existing only in the fork is left untouched.

Changes

• The patterns of one line are joined into a single alternation — (p1)|(p2) — rather than passed as several
  -e arguments. Not cosmetic: GNU grep refuses the latter.

  $ grep -xP -e 'v\d+' -e 'nightly'
  grep: the -P option only supports a single pattern    (exit 2)
  

  This container's grep is ugrep, which accepts multiple -e happily — so the naive form passes here and fails
  on every GitHub runner. Checked against /usr/bin/grep (GNU grep 3.11) before committing.

• grep -P is probed once, and only reported when a line actually configures tags — a repository that
  synchronizes branches only needs nothing beyond gh.

• The parser reads the fourth field, and rejects a line with neither branches nor tags. Splitting is on the first
  colon after the fork name, so a colon inside a pattern survives.

• Each kind of message has its own symbol (from review): 🏷️ marks a created tag only, 🟰 the tags already pointing
  at the same object, ℹ️ the two nothing-to-do cases, and ☢️ a tag that moved upstream — in the log and in the
  Not synchronized: list, which needed each entry of that list to carry its own symbol instead of a hard-coded ❌.
  The README gains a table of the whole vocabulary.

Documentation

• README.md gains a Tag Synchronization section: why gh can't do it, the pattern syntax with the PCRE note
  (and the trap that a "fixed name" is still a regex — v1.0 matches v1x0), the three per-tag outcomes, and what
  the action never does. The line-format table gains the fourth element, the worked PLC2 example now carries a tag
  pattern, the sample log shows both new lines, and Dependencies names the grep -P requirement.

Unit Tests

• check-outputs verifies created-tags, and both verification jobs assert it. The Valid fixture now contains two
  lines with tag patterns — one of them without any branch — which proves in CI that the new field parses and that
  a three-field line is unaffected: the branch counts are unchanged at 4 synchronized, 2 skipped.
• The workflow can't reach the tag path: dry-run touches no repository. Seven cases in the local harness cover it
  against a stub gh serving git/matching-refs/tags:
  • matching tags created, the non-matching nightly left alone, and the POST carrying ref=refs/tags/v1.0.0 with
    the upstream SHA,
  • a moved tag → one counted error with both SHAs, the other tag still created, the run continuing,
  • tags already up to date → counted, no POST at all,
  • a pattern matching nothing → reported, not an error,
  • an upstream repository without tags,
  • a fixed name beside a regular expression on a line with no branches → three tags created, gh repo sync never
    called,
  • dry-run printing the patterns and issuing no API call.
• All 17 cases in the harness pass (10 from Add the 'SynchronizeForks' composite action #1, 7 new).

Others

• Verified read-only against the real repositories while designing this: GET /repos/<owner>/<repo>/git/matching-refs/tags
  returns the ref and the object SHA per tag, and the SHAs of tags present in both ghdl/ghdl and Paebbels/ghdl all
  agree — so the "moved" case is genuinely rare, and comparing the ref's object is the right test. Note that the object
  compared is the annotated tag object where there is one, not the commit it points at.

---

Related Issues and Pull-Requests

• Follows Add the 'SynchronizeForks' composite action #1 (merged).
• Sibling: Create a branch that is missing in the fork #2 creates a branch missing from the fork. Both touch the per-repository loop in action.yml; whichever
  merges second rebases.
• Possible follow-up, deliberately not here: letting force update a moved tag. It would need care — it's the one
  operation in this action that can lose something.

🤖 Generated with Claude Code