Plugin: updater-replace

Ersetzt reguläre Ausdrücke oder wörtlichen Text in beliebigen Projektdateien. Das Plugin hilft überall dort, wo eine Versionsangabe in einer Datei steht, für die es keinen eigenen Updater gibt – etwa ein README-Badge, ein Dockerfile-Argument oder eine Quelltextkonstante.

Installation

Binärdatei

semrel plugin install @semrel/updater-replace

semrel plugin install lädt die Binärdatei nach .semrel/plugins/ herunter und aktualisiert .semrel.lock. Committe .semrel.lock, um die Version für dein Team festzuschreiben.

Docker

Vorgefertigte, signierte Multi-Plattform-Images (linux/amd64, linux/arm64) werden bei jedem Release veröffentlicht:

docker pull ghcr.io/semrels/updater-replace:latest

Prüfe die Image-Signatur mit cosign:

cosign verify ghcr.io/semrels/updater-replace:latest \
  --certificate-identity-regexp 'https://github.com/SemRels/updater-replace/.github/workflows/release.yml.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

Konfiguration

version: 1
plugins:
  - uses: @semrel/updater-replace
    phase: pre-tag
    args:
      files: README.md,docs/**/*.md
      ignore: docs/archive/**
      from: 'version-\d+\.\d+\.\d+'
      to: 'version-${nextRelease.version}'
      countMatches: "true"

Die flache Form konfiguriert genau eine Regel. files und ignore akzeptieren durch Komma, Semikolon oder Zeilenumbruch getrennte Muster, einschließlich rekursiver **-Globs.

Umgebungsvariablen

Name	Erforderlich	Standard	Beschreibung
`SEMREL_PLUGIN_FILES`	ja	`—`	Dateimuster, die aktualisiert werden sollen.
`SEMREL_PLUGIN_IGNORE`	nein	`—`	Muster, die aus der Trefferliste ausgeschlossen werden.
`SEMREL_PLUGIN_FROM`	ja	`—`	Go-regulärer Ausdruck, nach dem gesucht wird.
`SEMREL_PLUGIN_TO`	nein	`—`	Ersetzungstext mit Template-Unterstützung.
`SEMREL_PLUGIN_LITERAL`	nein	`false`	`from` als wörtlichen Text statt als regulären Ausdruck behandeln.
`SEMREL_PLUGIN_FLAGS`	nein	`—`	Go-Regexp-Flags: `i`, `m`, `s` und `U`.
`SEMREL_PLUGIN_COUNT_MATCHES`	nein	`false`	Trefferanzahl in die Zusammenfassung je Datei aufnehmen.
`SEMREL_PLUGIN_REPLACEMENTS`	nein	`—`	YAML- oder JSON-Array mit mehreren Regeln.

Mehrere Regeln

SemRel bildet jeden args-Wert auf genau eine Umgebungsvariable ab. Strukturierte Regeln werden deshalb als YAML-Blockskalar übergeben:

version: 1
plugins:
  - uses: @semrel/updater-replace
    phase: pre-tag
    args:
      replacements: |
        - files: ["README.md", "docs/**/*.md"]
          ignore: ["docs/archive/**"]
          from: 'version-\d+\.\d+\.\d+'
          to: 'version-${nextRelease.version}'
          countMatches: true
          results:
            - file: README.md
              hasChanged: true
              numMatches: 1
              numReplacements: 1
        - files: Dockerfile
          from: '^ARG VERSION=.*$'
          flags: m
          to: 'ARG VERSION=${nextRelease.version}'

files, ignore und from akzeptieren entweder einen String oder eine Liste. Mehrere from-Muster werden der Reihe nach angewendet, und Ersetzungstexte nutzen die Go-Regexp-Expansion, sodass $1 und ${name} als Rückverweise funktionieren.

Templates

Template	Quelle
`${nextRelease.version}`	`SEMREL_VERSION` / `SEMREL_NEXT_VERSION`
`${lastRelease.version}`	`SEMREL_CURRENT_VERSION`
`${gitTag}` / `${tag}`	`SEMREL_TAG_NAME`
`${channel}` / `${branch}`	`SEMREL_BRANCH`
`${date}`	Aktuelles UTC-Datum (`YYYY-MM-DD`)

Versions-Templates liefern immer die nackte SemVer-Version, auch wenn SemRel einen Tag-Präfix wie v1.4.0 meldet.

Release-Kontextvariablen

SEMREL_VERSION
SEMREL_CURRENT_VERSION
SEMREL_TAG_NAME
SEMREL_TAG_PREFIX
SEMREL_BRANCH
SEMREL_DRY_RUN

Verhalten

Jede Regel wird zunächst vollständig im Speicher ausgewertet, und alle results-Zusicherungen müssen erfüllt sein, bevor eine einzige Datei geschrieben wird. So entstehen keine halbfertigen Änderungen, wenn ein regulärer Ausdruck nicht mehr passt. Geschrieben wird über eine temporäre Datei im Zielverzeichnis und ein anschließendes atomares Umbenennen; Dateirechte und vorhandene CRLF-Zeilenenden bleiben erhalten.

Im Dry-Run führt das Plugin Matching, Templating und Zusicherungsprüfung weiterhin aus, meldet die Dateien, die es ändern würde, und schreibt nichts. Geänderte Pfade werden zeilenweise auf stdout ausgegeben, Diagnosen auf stderr. Ein fehlender Dateitreffer, ein ungültiges Muster, eine verletzte Zusicherung oder ein Schreibfehler führen zu einem Exit-Code ungleich null.

Quelle

SemRels/updater-replace