iru-swift-bump-version
/iru-swift-bump-version <new-version> - sets a Swift package, command-line tool or Apple app version to the exact value given: the CLI version literal, a SwiftPM library's tag-mirroring files, or an a
SKILL.md.claude/skills/iru-swift-bump-version/SKILL.md
GitHubSwift Bump Version
Set a Swift (SwiftPM library) or Apple app (Xcode-generated) project's version to an exact value across every file
that needs to agree with it. Unlike the Java/npm/Android ecosystems, a SwiftPM library carries no in-tree
version field the package manager itself reads — a consumer's .package(url:, from:/exact:) resolves against the
package's git tag, full stop, so this skill only rewrites the files that exist purely by this catalog's own
convention to mirror that tag (version.txt, CHANGELOG.md, README snippets), never a value SwiftPM itself
consults. An Apple app, by contrast, does carry an in-tree version: MARKETING_VERSION/CURRENT_PROJECT_VERSION
in whichever project format (XcodeGen, Tuist, raw .xcconfig, or .xcodeproj) is in play. A Swift command-line
tool carries one too: the string literal its --version prints (Version.swift's toolVersion, or a
CommandConfiguration(version:) literal), which follows the x.y.z-dev convention on the integration branch. This
skill never computes
a version itself — it applies exactly the version string it's given, validated for shape. The "which version to
compute next" logic belongs to the caller and is defined in Step 5, mirroring iru-typescript-bump-version's Step 5
and iru-android-bump-version's Step 5.
Step 0 — Resolve inputs
Parse the invocation:
- The positional argument is
<new-version>— the exact target version string (e.g.1.4.0,1.4.0-rc.1). If it's missing, ask the user for it before doing anything else; don't guess or compute one here. args(key: valuelines), if present:sync-files: yes|no— whether to also updatedocs/antora.yml/Antora page version mentions and, for an app, a README version mention (Step 8). If omitted, ask once withAskUserQuestionafter Step 2 confirms whether such mentions actually exist; skip asking if none do.next-version: <upcoming-version>— the upcoming pre-release version (e.g.1.5.0-rc.1, or the next planned tag) that README/Antora "Latest snapshot"/"Current development version"-style markers should show after a release, while "Latest release" markers and the dependency snippet show<new-version>. Only meaningful withsync-files: yes;iru-releasepasses it so a release never regresses a development marker to the release value (see Step 8).dry-run: yes|no— defaultno. Whenyes, run every step through composing the new file contents and showing the diff (Step 7), then stop — do not write anything, and say so plainly in the report.kind: library|app|cli— overrides Step 2's auto-detected project kind. Use this when a repository legitimately carries both a rootPackage.swift(e.g. a localPackages/Corepackage used by an app target) and a generator manifest/.xcodeproj— auto-detection alone can't disambiguate which one the user means to bump.
Reject, before touching anything, a <new-version> that is obviously not attempting a version at all (empty
string, or contains whitespace) with a short message asking for a valid value — Step 1 validates the actual shape.
Step 1 — Validate the version string
Neither SwiftPM nor Xcode's build settings parse or validate MARKETING_VERSION/a git tag as strict semver (both
are free-form strings), so — the same situation iru-android-bump-version is in — there's no build-tool command to
lean on the way npm version <v> --no-git-tag-version validates for the npm ecosystem. Validate with a regex
instead, using this catalog's convention: plain semver, X.Y.Z optionally followed by a hyphen pre-release
identifier and/or a + build-metadata identifier (X.Y.Z-rc.1, X.Y.Z+build.5) — the general form, since a Swift
package release tag and an app's MARKETING_VERSION/TestFlight build both commonly use pre-release suffixes
(-rc.1, -beta.2) that the stricter Java -SNAPSHOT-only shape doesn't need to allow for:
python3 -c 'import re,sys; v=sys.argv[1]; sys.exit(0 if re.fullmatch(r"\d+\.\d+\.\d+(-[0-9A-Za-z][0-9A-Za-z.]*)?(\+[0-9A-Za-z][0-9A-Za-z.]*)?", v) else 1)' "<new-version>"
Verified locally: 1.2.0 and 1.2.0-rc.1 match; 1.2 (missing patch), 1.2.0 (trailing whitespace), an empty
string, and abc all correctly fail to match.
If it doesn't match, warn the user the value doesn't follow this catalog's X.Y.Z/X.Y.Z-<pre-release> convention
and ask whether to proceed anyway (some projects intentionally use a different scheme) — don't hard-stop on a
non-matching but plausible string, only flag it, mirroring iru-android-bump-version's Step 1.
Step 2 — Survey which project kind/files exist
Determine the project kind (honor args: kind if given, otherwise auto-detect):
- Command-line tool (checked first): a root
Package.swiftdeclaring an.executableTargetthat depends onArgumentParser(grep -n 'executableTarget\|ArgumentParser' Package.swift), no generator manifest/.xcodeprojat the root, and Step 3b's helper finds a version literal underSources/→kind: cli, Step 3b applies. An ArgumentParser package with no literal (its--versionisn't wired, or it reads the version from elsewhere) falls through to Library — the git tag is then its only version; say so. - Library: a root
Package.swiftexists and no generator manifest/.xcodeprojis present at the root →kind: library, Step 3 applies. - App: any of
project.yml(XcodeGen),Project.swift(Tuist), or a*.xcodeprojdirectory exists at the root →kind: app, Step 4 applies. When more than one of these exists (e.g. both a generator manifest and a checked-in.xcodeprojthe generator produced), prefer the generator manifest — it's the source of truth the.xcodeprojis regenerated from, so editing the.xcodeprojdirectly would be overwritten on the nextxcodegen generate/tuist generate. - Both present (e.g. an app repository with a local
Packages/CoreSwiftPM package alongside its own rootPackage.swift): this is exactly the caseargs: kindexists to disambiguate — if it isn't given, ask viaAskUserQuestionwhich one the user means, rather than guessing; note that a nested package underPackages/is not scanned as a second target on its own, only the repository root. - Neither found: hard stop — tell the user no
Package.swift,project.yml,Project.swift, or.xcodeprojwas found at the repository root, and ask for the correct path or whether the project uses a different layout than this catalog'siru-setup-swift-library/iru-setup-apple-appscaffold produces — don't silently do nothing.
Also note, for Step 3/8, whether version.txt and CHANGELOG.md already exist at the root (both are optional —
version.txt is only meaningful when this repository's iru-setup-swift-github-workflows-generated sync.yml
bumps MARKETING_VERSION/version.txt on the gitflow sync — and CHANGELOG.md is
created by iru-setup-changelog), and for Step 4, which of project.yml/Project.swift/*.xcconfig/.xcodeproj
actually carry MARKETING_VERSION/CURRENT_PROJECT_VERSION (a project can spread these across more than one —
e.g. a Version.xcconfig included from project.yml's configFiles: — survey with grep -rn "MARKETING_VERSION\|CURRENT_PROJECT_VERSION" across project.yml, Project.swift, and every *.xcconfig before
picking which file(s) actually own the value, so Step 4 doesn't silently miss one or double-bump another).
Step 3 — Read and rewrite library files (version.txt, CHANGELOG.md, README snippets)
These three files are this skill's primary output for a library — unlike the optional Step 8 sync, they are
rewritten unconditionally (when the file exists, or, for version.txt, created per the note below), because the
task description for this skill states them as the library path's core deliverable, not an opt-in extra.
version.txt — a plain one-line file holding the current released version, read by this catalog's
sync.yml template (iru-setup-swift-github-workflows) to know what the "current" version is between
tags. Read the old value first, then overwrite:
cat version.txt 2>/dev/null || echo "(no version.txt yet)"
printf '%s\n' "<new-version>" > version.txt
If version.txt doesn't exist yet, create it — but only after confirming with the user (or via args) that this
repository's sync.yml/README actually reference it (grep -rn "version.txt" .github/workflows/ README.md 2>/dev/null);
if nothing references it, note in the report that a version.txt file was not created because nothing in this
repository reads one, and the only real "version" for this package remains its git tag.
CHANGELOG.md — rename the top ## [Unreleased] heading to ## [<new-version>] - <today's date> and reopen a
fresh, empty ## [Unreleased] above it, the same Keep a Changelog convention iru-release's Step 7 uses for the
Java/Maven path:
python3 - "CHANGELOG.md" "<new-version>" "$(date +%F)" <<'PY'
import re, sys
path, new_version, today = sys.argv[1], sys.argv[2], sys.argv[3]
text = open(path).read()
new_text, n = re.subn(
r'^## \[Unreleased\]\s*\n(?:[ \t]*\n)*',
f'## [Unreleased]\n\n## [{new_version}] - {today}\n\n',
text,
count=1,
flags=re.MULTILINE,
)
if n == 0:
sys.exit("## [Unreleased] heading not found in CHANGELOG.md")
open(path, "w").write(new_text)
PY
Skip this file entirely (note it in the report) if CHANGELOG.md doesn't exist — don't create one here, that's
iru-setup-changelog's job.
README .package(url:, from:/exact:) snippets — rewrite the version literal following either keyword,
covering both the version-range form (from: "1.0.0", which SwiftPM resolves as .upToNextMajor(from:)) and the
pinned form (exact: "1.0.0"):
python3 - "README.md" "<new-version>" <<'PY'
import re, sys
path, new_version = sys.argv[1], sys.argv[2]
text = open(path).read()
new_text, n = re.subn(
r'((?:from|exact)\s*:\s*)"[^"]*"',
lambda m: f'{m.group(1)}"{new_version}"',
text,
)
open(path, "w").write(new_text)
print(f"README replacements: {n}")
PY
If n is 0, README has no .package(...) snippet to update — note that, don't fail. If n is greater than the
number of snippets you expected (e.g. the README also shows an unrelated from:/exact: argument in a different
context), show the diff and confirm before trusting it silently — this regex is intentionally broad because it
must match both the from:/exact: keyword forms and doesn't anchor on .package(url: (a snippet can wrap across
lines), so a false-positive match elsewhere in the README is possible in principle, though not observed in this
skill's own verification.
Step 3b — Read and rewrite a command-line tool's version literal (kind: cli)
A Swift command-line tool keeps its version in source, because --version must print it: in the
iru-setup-swift-cli layout that is Sources/<Bin>Kit/Version.swift (public let toolVersion = "0.1.0-dev",
which the root command's CommandConfiguration(version: toolVersion) reads), and in other ArgumentParser tools often a
literal version: "1.2.3" inside CommandConfiguration(...). The helper below finds both — a *version*-named
let/var string literal in any Version.swift, a toolVersion/version literal elsewhere under Sources/, and a
semver-looking version: "…" in a file that builds a CommandConfiguration — and rewrites every one of them, never
.build/, Tests/ or a differently-named literal such as apiVersion = "2.0.0". Write it to a scratch file outside
the repository and run it from the repository root:
import difflib, os, re, sys
# Usage: python3 -I cli_version.py <package-root> [--list | --dry-run <new> | <new>]
LITERAL = re.compile(
r'^(?P<head>[ \t]*(?:(?:public|package|internal|fileprivate|private|static|nonisolated)[ \t]+)*(?:let|var)[ \t]+'
r'(?P<name>\w*[Vv]ersion\w*)(?:[ \t]*:[ \t]*String)?[ \t]*=[ \t]*")(?P<value>\d+\.\d+\.\d+[^"\\\n]*)(?P<tail>")',
re.MULTILINE,
)
CONFIG = re.compile(r'(?P<head>\bversion:[ \t]*")(?P<value>\d+\.\d+\.\d+[^"\\\n]*)(?P<tail>")')
def sources(root):
base = os.path.join(root, "Sources")
for directory, dirs, files in os.walk(base):
dirs[:] = sorted(d for d in dirs if not d.startswith(".") and not d.endswith(".docc"))
for name in sorted(files):
if name.endswith(".swift"):
yield os.path.join(directory, name)
def find(root):
hits = []
for path in sources(root):
text = open(path, encoding="utf-8").read()
in_version_file = os.path.basename(path) == "Version.swift"
for match in LITERAL.finditer(text):
# Outside Version.swift only `toolVersion`/`version` count, so an `apiVersion = "2.0.0"` is left alone.
if in_version_file or match.group("name") in ("toolVersion", "version"):
hits.append((path, "literal", match))
if "CommandConfiguration" in text:
for match in CONFIG.finditer(text):
hits.append((path, "CommandConfiguration", match))
return hits
def main():
root, args = sys.argv[1], sys.argv[2:]
hits = find(root)
if not hits:
sys.exit("no version literal found under Sources/ (Version.swift or CommandConfiguration(version:))")
values = sorted({match.group("value") for _, _, match in hits})
for path, kind, match in hits:
print(f"{os.path.relpath(path, root)}: {kind} {match.group('value')!r}")
if len(values) > 1:
print(f"WARNING: the literals disagree: {values}")
if not args or args[0] == "--list":
return
dry = args[0] == "--dry-run"
new = args[1] if dry else args[0]
for path in sorted({path for path, _, _ in hits}):
old = open(path, encoding="utf-8").read()
spans = {match.span() for hit_path, kind, match in hits if hit_path == path and kind == "literal"}
text = LITERAL.sub(lambda m: m.group("head") + new + m.group("tail") if m.span() in spans else m.group(0), old)
if "CommandConfiguration" in text:
text = CONFIG.sub(lambda m: m.group("head") + new + m.group("tail"), text)
if text == old:
continue
if dry:
rel = os.path.relpath(path, root)
sys.stdout.writelines(difflib.unified_diff(old.splitlines(True), text.splitlines(True), rel, rel))
else:
open(path, "w", encoding="utf-8").write(text)
print(f"updated {os.path.relpath(path, root)}")
main()
python3 -I <scratch>/cli_version.py . --list— prints every literal (path: literal|CommandConfiguration 'value'); the old version is that value. If the literals disagree (WARNING: the literals disagree), show them and ask which is authoritative before writing. No literal → exit 1 ("no version literal found"): report that--versionisn't wired and stop (or fall back to the library path if the user confirms).python3 -I <scratch>/cli_version.py . --dry-run <new-version>prints a unified diff (Step 7's preview);python3 -I <scratch>/cli_version.py . <new-version>writes and printsupdated <path>per file.
A tool's README .package(from:) snippets don't apply (a CLI isn't consumed as a dependency) and CHANGELOG.md is
left to the caller (iru-release's own Step 7 writes the release section) — only Step 8's optional sync (README /
docs/antora.yml / Antora version mentions, e.g. a Homebrew or download snippet) touches other files.
Step 4 — Read and rewrite app files (MARKETING_VERSION/CURRENT_PROJECT_VERSION)
Apply to whichever file(s) Step 2 identified as owning the value. MARKETING_VERSION always gets set to
<new-version> verbatim; CURRENT_PROJECT_VERSION is a monotonically increasing build-number integer — the same
role Android's versionCode plays for Google Play, and Apple's own guidance requires it strictly increase for
every build uploaded to App Store Connect/TestFlight, so always increment it by exactly 1 on every call of this
skill (unlike iru-android-bump-version's conditional -SNAPSHOT-gated rule, there is no in-tree pre-release
marker for an app's MARKETING_VERSION to gate on here — see Step 5).
XcodeGen project.yml (settings: base:):
grep -n "MARKETING_VERSION\|CURRENT_PROJECT_VERSION" project.yml
python3 - "project.yml" "<new-version>" <<'PY'
import re, sys
path, new_version = sys.argv[1], sys.argv[2]
text = open(path).read()
# Quote-tolerant: matches both `MARKETING_VERSION: 1.0.0` and `MARKETING_VERSION: "1.0.0"`, and keeps
# whichever form the file already uses.
text, n_mv = re.subn(
r'(MARKETING_VERSION:\s*)("?)[^"\s]+\2',
lambda m: f'{m.group(1)}{m.group(2)}{new_version}{m.group(2)}',
text, count=1,
)
if n_mv == 0:
sys.exit("MARKETING_VERSION not found in project.yml")
def bump(m):
return f"{m.group(1)}{m.group(2)}{int(m.group(3)) + 1}{m.group(2)}"
text, n_cpv = re.subn(
r'(CURRENT_PROJECT_VERSION:\s*)("?)(\d+)\2',
bump,
text, count=1,
)
if n_cpv == 0:
sys.exit("CURRENT_PROJECT_VERSION not found in project.yml")
open(path, "w").write(text)
print(f"MARKETING_VERSION replacements: {n_mv}, CURRENT_PROJECT_VERSION replacements: {n_cpv}")
PY
Both regexes only touch the first occurrence in the file, and both tolerate an optional pair of double
quotes around the value (1.0.0 and "1.0.0"; 1 and "1"), preserving whichever form the file uses —
iru-setup-apple-app writes them unquoted, but a hand-edited or older manifest may quote them. This catalog's
iru-setup-apple-app scaffold writes these keys once, under the top-level settings: base: block; a project that also overrides either key
per-target (a nested targets: <Target>: settings: base: block) needs those reviewed by hand afterward (Step 9
warns about this explicitly) — this skill does not attempt to find and rewrite every per-target override, only the
project-wide default.
Tuist Project.swift (settings: .settings(base: [...])) — same idea, Swift dictionary-literal syntax
instead of YAML:
grep -n "MARKETING_VERSION\|CURRENT_PROJECT_VERSION" Project.swift
python3 - "Project.swift" "<new-version>" <<'PY'
import re, sys
path, new_version = sys.argv[1], sys.argv[2]
text = open(path).read()
text, n_mv = re.subn(
r'("MARKETING_VERSION":\s*)"[^"]*"',
lambda m: f'{m.group(1)}"{new_version}"',
text, count=1,
)
if n_mv == 0:
sys.exit('MARKETING_VERSION not found in Project.swift')
def bump(m):
return f'{m.group(1)}"{int(m.group(2)) + 1}"'
text, n_cpv = re.subn(
r'("CURRENT_PROJECT_VERSION":\s*)"(\d+)"',
bump,
text, count=1,
)
if n_cpv == 0:
sys.exit('CURRENT_PROJECT_VERSION not found in Project.swift')
open(path, "w").write(text)
print(f"MARKETING_VERSION replacements: {n_mv}, CURRENT_PROJECT_VERSION replacements: {n_cpv}")
PY
*.xcconfig (e.g. a shared Version.xcconfig included via project.yml's configFiles:, or hand-maintained
in a .xcodeproj-only project) — same substitution shape, KEY = value syntax:
grep -n "MARKETING_VERSION\|CURRENT_PROJECT_VERSION" <path>.xcconfig
python3 - "<path>.xcconfig" "<new-version>" <<'PY'
import re, sys
path, new_version = sys.argv[1], sys.argv[2]
text = open(path).read()
text, n_mv = re.subn(
r'(MARKETING_VERSION\s*=\s*)\S+',
lambda m: f'{m.group(1)}{new_version}',
text, count=1,
)
if n_mv == 0:
sys.exit("MARKETING_VERSION not found in xcconfig")
def bump(m):
return f"{m.group(1)}{int(m.group(2)) + 1}"
text, n_cpv = re.subn(
r'(CURRENT_PROJECT_VERSION\s*=\s*)(\d+)',
bump,
text, count=1,
)
if n_cpv == 0:
sys.exit("CURRENT_PROJECT_VERSION not found in xcconfig")
open(path, "w").write(text)
print(f"MARKETING_VERSION replacements: {n_mv}, CURRENT_PROJECT_VERSION replacements: {n_cpv}")
PY
Hand-maintained .xcodeproj with no generator manifest at all (no project.yml/Project.swift found in
Step 2, only a checked-in .xcodeproj) — do not hand-edit project.pbxproj's version fields with a regex as the
first choice; Apple ships a purpose-built tool for exactly this:
xcrun agvtool new-marketing-version "<new-version>"
xcrun agvtool new-version -all "<current-build-number> + 1" # compute the new integer yourself, agvtool takes the literal target value, not a delta
agvtool new-marketing-version <v> sets MARKETING_VERSION (all matching build configurations); agvtool new-version -all <n> sets CURRENT_PROJECT_VERSION to the literal integer <n> (not a delta — read the current
value first with agvtool what-version and pass current + 1). Both commands must be run from the directory
containing the .xcodeproj (or its parent). agvtool requires the project's "Current Project Version" build
setting to already be using agvtool-managed versioning (VERSIONING_SYSTEM = "apple-generic") — if it isn't
(agvtool what-version errors with a message to that effect), fall back to the documented sed on
project.pbxproj instead, which needs a -g since MARKETING_VERSION/CURRENT_PROJECT_VERSION appear once per
build configuration (Debug/Release, and once more per target):
sed -i.bak -E \
-e 's/(MARKETING_VERSION = )[^;]+;/\1<new-version>;/g' \
-e 's/(CURRENT_PROJECT_VERSION = )[0-9]+;/echo "\1$((\2 + 1));"/ge' \
<name>.xcodeproj/project.pbxproj && rm <name>.xcodeproj/project.pbxproj.bak
(The CURRENT_PROJECT_VERSION line above uses GNU sed's e flag to evaluate a shell expression per match so
each occurrence increments independently rather than being set to one literal value — this needs GNU sed; on
macOS's BSD sed this e-flag trick does not work identically, so on macOS prefer the agvtool path, or fall
back to the python3 regex form shown above adapted to project.pbxproj's KEY = value; syntax with a trailing
semicolon, matching every occurrence with re.subn(..., text) with no count=1 limit.) Confirmed locally:
xcrun agvtool help exists and lists new-marketing-version/new-version [-all] as documented above; the actual
rewrite (either path) was not exercised against a real hand-maintained .xcodeproj in this skill's own
verification — see "Known quirks / verification notes".
Step 5 — The Swift-catalog pre-release convention (for iru-release and other callers)
This is the Swift-ecosystem equivalent of the Java catalog's Maven -SNAPSHOT convention (iru-release), the npm
catalog's -dev.N convention (iru-typescript-bump-version's Step 5), and the Android catalog's -SNAPSHOT
convention (iru-android-bump-version's Step 5) — except that, unlike those three ecosystems, there is no
in-tree pre-release marker for a library at all:
- Library: no development-version file or field exists in-tree between releases — SwiftPM has nothing to read
until a tag exists, so there is nothing to set to a "next dev" value the way
1.4.0-dev.0/1.4.0-SNAPSHOTare. The release is the git tag:iru-releasedetermines the release version as the next semver component bump from the last tag —
(verified locally: tagging a throwaway repo's initial commitgit describe --tags --abbrev=01.1.0, then committing again, correctly returns1.1.0— the last reachable tag, not a guess) — asks the user which component to bump (patch/minor/major) from that value the same way the Java/npm/Android paths do, then calls this skill once with the resultingnew-versionto updateversion.txt/CHANGELOG.md/README (Step 3), and separately creates the actual git tag itself (this skill never tags — tagging is a release-orchestration action, not a file-rewrite one, and belongs to the caller, exactly as this skill never commits). - Command-line tool (
kind: cli): the in-tree literal carries a-devpre-release suffix on the integration branch (0.1.0-dev), exactly like this catalog's PHP/.NET/Rust/Go command-line conventions.iru-releasestrips it for the release (0.1.0-dev→0.1.0, calling this skill with0.1.0), and the next development value is the minor bump plus-dev(0.2.0-dev) — written by the repository'ssync.ymlafter the release, or by a second call of this skill againstdevelop. The release tag is the version without avprefix and must equal the literal (the release workflow checks it). - App:
MARKETING_VERSIONis the release version in-tree (there's no separate pre-release file to bump either, but for a different reason than the library case — an app's "current development version" is simply whateverMARKETING_VERSIONalready says, since TestFlight/App Store builds are distinguished from each other byCURRENT_PROJECT_VERSION, not by a-SNAPSHOT/-dev.N-style suffix onMARKETING_VERSION). The convention:CURRENT_PROJECT_VERSIONincreases by exactly 1 on every call (Step 4) — monotonically, forever, never reset — whileMARKETING_VERSIONis set to whatever release/beta version string the caller decides on (a plainx.y.zfor a store release, orx.y.z-beta.Nfor an internal/TestFlight-only build, at the caller's discretion — this skill validates the shape in Step 1 but does not itself decide which one a given call should use).
Step 6 — Sanity check
- Library: confirm
Package.swiftis still syntactically valid after Step 3 touched files near it (Step 3 never editsPackage.swiftitself, but this is still the cheapest signal that nothing in the package broke):
A non-zero exit means something is wrong with the package manifest (unrelated to this skill's own edits, since it never touchesswift package dump-packagePackage.swift, but worth surfacing) — show the actual error and don't report success blindly. Verified locally: run against a throwawayDemoLibpackage (Swift 6.4 toolchain,swift-tools-version:5.10), exits0and prints the expected JSON manifest (name, platforms, products, targets). - Command-line tool: build and ask the binary —
swift build --product <bin>then"$(swift build --show-bin-path)/<bin>" --versionmust print exactly<new-version>(the<bin>is the.executableproduct name inPackage.swift). A compile error here means the helper matched something it shouldn't have — show it and restore the file from the diff. - App: regenerate the Xcode project from its manifest and confirm the new value round-trips through
xcodebuild -showBuildSettings:
Unverified locally — this environment has noxcodegen generate # or: tuist generate xcodebuild -showBuildSettings -project <Name>.xcodeproj -scheme <Scheme> | grep MARKETING_VERSIONbrew, soxcodegen/tuistare not installable here (per this group's environment notes) and this check was not exercised against a real generated project. Theproject.yml/Project.swift/*.xcconfigregex rewrites themselves (Step 4) were verified directly against sample files (see "Known quirks / verification notes") — only this specific generate-and-inspect round-trip is unverified. For a hand-maintained.xcodeproj(agvtoolpath), the equivalent check isagvtool what-marketing-version/agvtool what-versionimmediately after Step 4'sagvtoolcalls, which read back exactly what was just written — cheaper than a fullxcodebuild -showBuildSettingsand doesn't need a scheme name.
Step 7 — Preview (dry-run: yes) or write
- Compose the new file contents for every file touched (Step 3/4, and Step 8 if accepted) without writing them to
disk first — every
python3snippet above naturally supports this since it builds the substituted string in memory before the finalopen(path, "w").write(...)call; for a dry run, print that string (or a diff) instead of writing it. - Quirk discovered during this skill's own verification: computing the diff via a shell
diff -u <(cat original) <(printf '%s' "$new_text")one-liner (the formiru-android-bump-version's Step 7 uses) loses the file's trailing newline oncenew_texthas passed through a bash$(...)command substitution — bash strips trailing newlines from command substitution, so the diff shows a spurious "\ No newline at end of file" even though the real write (viapython3's ownopen().write(), not through a shell variable) would have preserved it correctly. Prefer computing and printing the dry-run diff inside the samepython3process that builtnew_text(e.g.difflib.unified_diff(open(path).read().splitlines(keepends=True), new_text.splitlines(keepends=True))) rather than round-tripping the string through a shell variable first. - If
dry-run: yes: show the diff for every file that would change, do not write anything, do not run Step 6, and say plainly in the report that this was a preview only — no file was modified. - Otherwise: write each file, then run Step 6.
Step 8 — Optionally sync other files that mirror the version
Ask (or honor args: sync-files) whether to also update other places that name the current version, the same way
iru-typescript-bump-version's Step 6 and iru-android-bump-version's Step 8 do for their ecosystems. Unlike
those two skills, a library's README dependency snippet is already handled unconditionally in Step 3 — Step 8 here
only covers the files that may legitimately be intentionally out of step with the in-tree/tag version:
Marker mapping when next-version was given (the iru-release case — same rule as
iru-java-bump-version's Step 7): rewrite each mention by what it names rather than to one value —
"Latest release"-style markers and a Project Status Latest release row → <new-version> when it is a release
(no pre-release pre-release suffix), left untouched when <new-version> is itself a pre-release; "Latest snapshot"/
"Current development version"-style markers → next-version when given, otherwise <new-version> only if it is
a pre-release value, and untouched (with a warning in the Report step that the caller should pass next-version)
when <new-version> is a release — never regress a development marker to a release value. A snippet with no
such marker → <new-version>.
docs/antora.yml— itsversion:field, if this repository has an Antora site and that field is meant to track the released version (skip for a pre-release value, e.g.x.y.z-rc.N— this catalog's convention, matchingiru-release's Java path and the npm/Android bump-version skills, is to only write a released version there).- Any Antora page under
docs/modules/ROOT/pages/showing an install/dependency snippet with a literal version string:
Update each match with the samegrep -rl '"[^"]*":\s*"\?[0-9]\+\.[0-9]\+\.[0-9]\+' docs/modules/ROOT/pages/*.adoc 2>/dev/nullfrom:/exact:substitution shown in Step 3 (or aMARKETING_VERSION-style substitution for an app-flavored doc page, if any). - App only — a README "Current version"/App Store badge mention, if any (
grep -n "MARKETING_VERSION\|Current version" README.md): apps more commonly show a static App Store/TestFlight badge that pulls live rather than hardcoding a version string, so ask before touching README at all here, unlike the library path where the.package(...)snippet in Step 3 is always meant to track the exact current version.
This is offered, not automatic — these files may be intentionally out of step with the tag/MARKETING_VERSION
(e.g. a badge pulling live from the Swift Package Index or the App Store rather than a hardcoded string), so don't
rewrite anything the user didn't confirm.
Step 9 — Report
Summarize:
- The project kind detected (
library/app, and how — auto-detected orargs: kindoverride), the old version and the new version. - Library: every file actually changed (
version.txt— or "not created, nothing references it";CHANGELOG.md— or "skipped, file doesn't exist"; README.package(...)snippet replacement count), and the explicit reminder that the git tag itself is the actual release artifact — this skill does not create it, the caller must rungit tag <new-version>(typically un-prefixed, matching this catalog'sgit tag --sort=-v:refnameconvention used elsewhere) and push it once the changes here are committed. - Command-line tool: every literal rewritten (path + kind), the
--versionread-back, and thatCHANGELOG.mdwas left to the caller. - App: which file(s)
MARKETING_VERSION/CURRENT_PROJECT_VERSIONwere rewritten in (project.yml,Project.swift, one or more*.xcconfigfiles, or viaagvtool/project.pbxprojsed), the old/newCURRENT_PROJECT_VERSIONbuild number, and any per-target override left untouched that needs manual review (Step 4's note). - Whether this was a
dry-run(no file written) or an actual write. - The Step 6 sanity-check result —
swift package dump-packagepassed/failed for a library (this was actually run during this skill's own verification), or "not run —xcodegen/tuistunavailable, unverified locally" for an app (or theagvtool what-version/what-marketing-versionread-back result for the.xcodeproj-only path). - Warn explicitly: review the diff before committing (this skill doesn't commit or tag anything); for a
library, the version-bearing artifact is the git tag, not any file this skill touched — nothing here
substitutes for actually creating and pushing that tag; for an app,
CURRENT_PROJECT_VERSIONmust never be reused once a build carrying it has been uploaded to App Store Connect, so re-running this skill against a value already shipped is not recoverable by re-running it again with a lower number; aproject.yml/Project.swiftvalue that's also overridden per-target was not touched and needs manual review; a README/Antora mention that pulls the version live from the Swift Package Index/App Store rather than hardcoding it should not have Step 8 applied to it.
Known quirks / verification notes
Verified in $TMPDIR/iru-verify/swift/bump-version/, using the local toolchain (Xcode 27.0, Swift 6.4, no brew
— xcodegen/tuist not installable in this environment, per this group's environment notes):
- Step 1 regex:
1.2.0and1.2.0-rc.1match;1.2,1.2.0(trailing space), an empty string, andabcall correctly fail — exercised withpython3 -cdirectly, all six cases behaved as documented above. - Step 3,
version.txt: a throwaway1.0.0file correctly became1.2.0afterprintf '%s\n' "1.2.0" > version.txt. - Step 3, README
.package(...)snippets: a sample README with both afrom: "1.0.0"range-form and anexact: "1.0.0"pinned-form snippet — both replaced correctly to"1.2.0"in one run (README replacements: 2reported), confirming the single regex handles both keyword forms. - Step 3,
CHANGELOG.mdheading: the first draft of the regex (^## \[Unreleased\]\s*$, matching only the heading's own line) left a missing blank line between the newly inserted## [<version>] - <date>heading and the following### Addedsubsection, because the blank line that originally followed## [Unreleased]stayed exactly where it was in the source text rather than moving with the heading. Fixed by widening the match to also consume any blank lines immediately following the heading (^## \[Unreleased\]\s*\n(?:[ \t]*\n)*) and re-inserting exactly the right blank lines in the replacement template — reverified against the same sample file, output now has the expected blank line before### Added, matching this catalog'sCHANGELOG.md's own Keep a Changelog formatting exactly (checked by diffing against the format used in this repository's real rootCHANGELOG.md). - Step 4,
project.yml: a sample XcodeGen manifest withsettings: base: MARKETING_VERSION: 1.0.0/CURRENT_PROJECT_VERSION: 1correctly became1.2.0/2after one run; a target-levelsettings: base:block with an unrelated key (PRODUCT_BUNDLE_IDENTIFIER) was correctly left untouched (the regex only matched the top-level occurrence, as intended — see Step 4's caveat about per-target overrides). - Step 4,
Project.swift: a sample Tuist manifest with"MARKETING_VERSION": "1.0.0"/"CURRENT_PROJECT_VERSION": "1"insidesettings: .settings(base: [...])correctly became"1.2.0"/"2". - Step 4,
*.xcconfig: a sampleVersion.xcconfigwithMARKETING_VERSION = 1.0.0/CURRENT_PROJECT_VERSION = 1correctly becameMARKETING_VERSION = 1.2.0/CURRENT_PROJECT_VERSION = 2. - Step 4,
agvtool:xcrun agvtool helpconfirmed present and documents exactly the subcommands this skill relies on (new-marketing-version,new-version [-all],what-version,what-marketing-version). The actualnew-marketing-version/new-version -allinvocations and theproject.pbxprojsedfallback were not exercised against a real.xcodeprojin this verification (building one from scratch outside Xcode's own project-creation flow was out of scope here) — the commands are documented fromagvtool help's own usage text and Apple's documented behavior, not independently confirmed end-to-end. - Step 5, pre-release convention:
git describe --tags --abbrev=0confirmed against a throwaway git repo — tag1.1.0on the first commit, a second commit on top,git describe --tags --abbrev=0correctly returns1.1.0(the last reachable tag, ignoring the untagged commit on top of it). - Step 6, library:
swift package dump-packageagainst the throwawayDemoLibpackage (a minimal library product/target with a Swift Testing test) exits0and prints the expected JSON (name, platforms, products, targets) — confirmed working end-to-end. - Step 6, app: unverified locally — no
xcodegen/tuistbinary available in this environment (nobrew); theproject.yml/Project.swift/*.xcconfigrewrites themselves were verified directly (see above), but the generate-and-inspect round-trip (xcodegen generate→xcodebuild -showBuildSettings | grep MARKETING_VERSION) was not exercised. - Step 7, dry-run diff mechanism: discovered and documented inline in Step 7 above — a shell
diff -u <(cat original) <(printf '%s' "$var")one-liner silently drops the file's trailing newline once the new content has passed through a bash command substitution, producing a spurious "no newline at end of file" diff line; computing the diff inside the samepython3process that built the replacement text avoids this. - Step 3b, command-line tool (verified 2026-10-16 in
$TMPDIR/iru-verify/cli/swift/iru-swift-bump-version/, Swift 6.4): on a copy of aniru-setup-swift-cliscaffold,--listfound onlySources/MyToolKit/Version.swift('0.1.0-dev');--dry-run 0.1.0printed a one-line diff and wrote nothing;0.1.0rewrote it,swift buildsucceeded andmy-tool --versionprinted0.1.0;0.2.0-devthen rewrote it again. On a second package with noVersion.swiftandCommandConfiguration(abstract: "Does things (fast).", version: "1.2.3-dev", …)plus astatic let apiVersion = "2.0.0", only theCommandConfigurationliteral changed (parentheses in the abstract didn't confuse it;apiVersionuntouched). A package with no literal exits 1 with "no version literal found".