ws:* Goal Reference

ws:scaffold-init — bootstrap a workspace

Bootstrap a workspace. Idempotent — safe to re-run any time a new subproject is declared in workspace.yaml. Two responsibilities:

1. Manifest bootstrap — if no workspace.yaml exists, generate a minimal manifest in the current directory (one entry per subdirectory with a .git/pom.xml shape, plus the workspace root POM scaffolding).
2. Subproject hydration — for every subproject in workspace.yaml, ensure the on-disk directory exists with git initialized. Three modes per subproject:
   1. Already cloned — directory has .git/; skip.
   2. Syncthing working tree — directory exists but has no .git/. Initializes git in-place: git init, adds the remote, fetches, and resets to match the remote branch. This preserves file content synced from another machine, avoiding a re-clone overwrite.
   3. Fresh clone — no directory; runs git clone.

Subprojects are processed in topological order so dependencies are present before dependents.

Folds the retired ws:create and ws:init goals (ike-issues#393): the same goal handles first-run bootstrap and ongoing hydration of declared-but-missing subprojects.

mvn ws:scaffold-init

ws:add — add a subproject

Add a single repository to an existing workspace. Given a git URL, the goal:

1. Clones the repository into the workspace.
2. Derives the subproject name from the URL (or accepts -Dsubproject=<name>).
3. Scans the POM to derive groupId and inter-subproject dependencies.
4. Appends an entry to workspace.yaml.

mvn ws:add -Drepo=git@github.com:IKE-Network/new-component.git
mvn ws:add -Drepo=... -Dsubproject=custom-name

ws:remove — remove a subproject

Remove a subproject from workspace.yaml. Fails with a clear error if any other workspace subproject still depends on the target, unless -Dforce=true is passed. The on-disk directory is left in place — the developer chooses whether to delete it.

mvn ws:remove -Dsubproject=old-component
mvn ws:remove -Dsubproject=old-component -Dforce=true

ws:stignore — generate Syncthing ignore files

Generate Syncthing .stignore files for the workspace. Syncthing should sync source files across a developer’s own machines but must not sync build artifacts or git metadata (those are machine-specific and trying to sync them produces packfile corruption).

The goal generates two files: a workspace-level .stignore and a template that includes a shared stignore-shared block. Re-run any time the workspace shape changes.

mvn ws:stignore

ws:overview — consolidated dashboard

Consolidated workspace overview, replacing the former ws:dashboard, ws:status, and ws:graph. Loads the manifest once and presents four sections:

1. Manifest — subproject count, consistency check.
2. Graph — dependency order with direct dependencies.
3. Status — branch, SHA, clean/uncommitted per subproject.
4. Cascade — downstream rebuild impact of components with uncommitted changes.

Use -Dformat=dot to output Graphviz DOT format instead of the text overview (delegates to graph rendering).

mvn ws:overview
mvn ws:overview -Dformat=dot

This is the right starting point for almost any workspace operation — run it first to see what’s there before mutating anything.

ws:graph — dependency graph

Print the workspace dependency graph. Displays subprojects in topological order with their direct dependencies. Optional DOT output for Graphviz rendering.

mvn ws:graph
mvn ws:graph -Dformat=dot | dot -Tsvg > workspace-graph.svg

ws:verify-convergence — transitive dependency convergence

Check transitive dependency convergence across workspace subprojects. Runs mvn dependency:tree for each subproject in topological order, then compares resolved versions of shared dependencies. Divergences (the same artifact resolving to different versions in different components) are reported in the terminal and written to a markdown report. Useful before a release to confirm the workspace is internally consistent.

mvn ws:verify-convergence

ws:lint — preflight hygiene gate

Surface workspace-hygiene preflight conditions as a standalone gate (ike-issues#217). Runs every preflight condition in report-only mode against the current workspace and emits a markdown summary. Always exits 0 — the goal is visibility, not gating.

Catches problems like typo’d .mvn/jvm.config comments, uncommitted state, and leaking SNAPSHOT properties before they propagate to git or Syncthing.

mvn ws:lint

ws:report — open per-goal reports

List and open the ws꞉.md goal reports at the workspace root. Each ws: goal writes its latest output to a per-goal file (e.g., ws꞉overview.md, ws꞉release-draft.md). This goal lists those reports newest-first and opens the workspace root in the default file manager so you can browse them.

mvn ws:report

ws:release-status — diagnose in-flight releases

Read-only diagnostic for any in-flight or partial workspace release. Walks every checked-out subproject in workspace.yaml, collects git artifacts that indicate an interrupted release (release/ branches and unpushed v tags), and prints a punch list with one line per subproject. The footer recommends a next action — typically pointing at IKE-RELEASE-RECOVERY.md for the matching state.

Performs no mutations. Run this any time you suspect a release went sideways.

mvn ws:release-status

ws:check-branch — defensive git hook

Defensive git hook — warns when a branch is created or switched outside the workspace tooling. Intended to be called from a post-checkout git hook:

#!/bin/sh
mvn -q ws:check-branch -- "$@"

In workspace mode, compares the current branch to the expected branch in workspace.yaml and warns on mismatch. Provides copy-pasteable undo commands. In bare mode (no workspace.yaml), silently exits — nothing to check. Never blocks; always exits 0.

ws:sync — pull + refresh-main + push

Pull then push across the workspace — the everyday "sync" operation: bring down what teammates have committed, then push up what I have committed. Replaces the daily two-step of ws:pull followed by ws:push.

Between the pull and the push, this goal also refreshes local main from origin/main across the workspace via the same mechanism ws:refresh-main uses. This keeps local main coherent with the remote even on machines where Syncthing carries an out-of-band checkout.

mvn ws:sync

ws:pull — git pull across the workspace

Pull latest changes across the workspace. When the workspace root is itself a git repository (i.e. has a .git directory), it is pulled first so any changes to the root POM or workspace.yaml land before subproject operations run. Runs git pull --rebase in each cloned subproject directory in topological order. Uninitialized components are skipped with a warning.

mvn ws:pull

ws:push — git push across the workspace

Push with a VCS-bridge catch-up preamble. When run from a workspace root, iterates all subproject repositories in topological order and pushes each. When run from a single repository, operates on the current directory only.

mvn ws:push
mvn ws:push -DskipUpToDate=false   # show "already up to date" lines

ws:commit — stage + commit workspace-wide

Commit with a VCS-bridge catch-up preamble. By default stages all tracked-modified and untracked-not-ignored files before committing — workspace-wide goals routinely create new files (scaffold writes, IDE settings cleanup, generated configs) and a staged-only default silently dropped them. Pass -DstagedOnly to commit only what is already in the index.

Each subproject’s commit line includes a count of modified vs. new files, with the new file paths listed inline so the developer can see what was pulled in without running git status after the fact:

  ✓ komet-ws — 7 modified, 1 new (.idea/kotlinc.xml)

mvn ws:commit -Dmessage="fix: deploy-path bug"
mvn ws:commit -Dmessage="..." -DstagedOnly

ws:refresh-main — refresh local main from origin

Refresh local main from origin/main across the workspace. For each subproject, fetches origin and reconciles local main with origin/main:

• Fast-forward when behind.
• Leave alone when purely ahead (unpushed work).
• Auto-resolve via merge when diverged. The merge stays local until pushed via ws:push or ws:sync.

Used internally by ws:sync, ws:feature-start, and ws:feature-finish-*. Available standalone for the case where you want to refresh main without pulling subproject branches.

mvn ws:refresh-main

ws:feature-start — coordinated feature branch

Create a feature branch with a consistent name across all workspace subprojects, optionally setting branch-qualified SNAPSHOT versions in each POM.

Before branching, the goal refreshes local main from origin/main so the new feature branch starts from current main rather than whatever stale state happens to be on the local machine. If the refresh would produce file conflicts, the goal hard-errors before any branch is created (ike-issues#284).

In workspace mode (workspace.yaml found):

1. Refreshes local main from origin/main.
2. Validates the working tree is clean.
3. Creates branch feature/<name> from the current HEAD.
4. If the subproject has a Maven version, sets a branch-qualified version (e.g., 1.2.0-my-feature-SNAPSHOT).

The publish variant additionally runs ws:align-publish so the new feature branch starts from a consistent inter-subproject state.

mvn ws:feature-start-draft -Dfeature=my-feature       # preview
mvn ws:feature-start-publish -Dfeature=my-feature     # execute

ws:update-feature — incorporate main into feature

Update the current feature branch by incorporating changes from main. For long-lived feature branches, main may advance significantly. This goal brings the feature branch up to date, surfacing merge conflicts incrementally rather than at feature-finish time.

Uses merge (not rebase) by default to incorporate main — this preserves all commit hashes and is safe for branches shared via Syncthing or pushed to origin. Pass -Dstrategy=rebase for a linear history when no one else has pulled the branch.

mvn ws:update-feature-draft                       # preview
mvn ws:update-feature-publish                     # merge (default)
mvn ws:update-feature-publish -Dstrategy=rebase   # rebase

ws:feature-finish-squash — squash-merge back to main

Squash-merge a feature branch back to the target branch. The default and recommended strategy for finishing features. The feature branch’s full commit history is compressed into a single commit on the target branch. The feature branch is deleted after merge because squash creates divergent history — continuing on the branch would cause conflicts.

Pass -DkeepBranch=true only if you understand that the branch can no longer be cleanly merged again.

Before squash-merging, refreshes local main from origin/main so the feature is not landed on top of stale main (ike-issues#284). If the refresh would conflict, the goal hard-errors before touching any feature branch.

When to use

Most features. Feature branch history is disposable. Target branch gets one clean commit.

mvn ws:feature-finish-squash-draft -Dfeature=done
mvn ws:feature-finish-squash-publish -Dfeature=done -Dmessage="Ship it"

ws:feature-finish-merge — no-fast-forward merge

No-fast-forward merge of a feature branch, preserving full history. Creates a merge commit on the target branch containing the complete feature branch history. The feature branch is kept alive by default because histories stay connected — the branch can continue to receive work and be merged again later.

Same origin/main refresh preamble as feature-finish-squash (ike-issues#284).

When to use

Long-lived feature branches that periodically merge intermediate work to the target branch. Use when you need traceability of individual feature commits on the target branch.

mvn ws:feature-finish-merge-draft -Dfeature=long-running
mvn ws:feature-finish-merge-publish -Dfeature=long-running

ws:feature-abandon — discard a feature branch

Abandon a feature branch across all workspace subprojects. The draft variant previews what would be abandoned — which components, how many unmerged commits, what would be lost. The publish variant prompts for confirmation then executes the deletion.

Components are processed in reverse topological order (downstream first) to avoid transient dependency issues.

mvn ws:feature-abandon-draft                       # preview
mvn ws:feature-abandon-publish                     # with confirmation
mvn ws:feature-abandon-publish -Dforce=true        # skip confirmation
mvn ws:feature-abandon-publish -DdeleteRemote=true # also delete remote branches

ws:switch — coordinated branch checkout

Switch all workspace subprojects to a different branch with optional auto-stash. Discovers all local feature branches across subprojects and presents an interactive menu. The selected branch is checked out in every subproject that has it locally; subprojects without the branch are skipped with a warning.

Pass -Dbranch=<name> to skip the interactive menu.

mvn ws:switch-draft                              # preview
mvn ws:switch-publish                            # interactive
mvn ws:switch-publish -Dbranch=feature/foo       # non-interactive

ws:align — sync inter-subproject dependency versions

Align inter-subproject dependency versions in POM files. For each subproject on disk, scans POM dependency declarations. When a dependency’s groupId:artifactId matches another workspace subproject, updates the version to match that subproject’s current POM version.

Daily-use, safe, idempotent. The draft variant writes the would-be changes to a report; the publish variant applies them.

The alignment logic lives in AlignmentReconciler and is shared with ws:scaffold-publish (when -DupdateAlignment is left at its default true), ws:feature-start-publish, ws:checkpoint-publish, and the per-subproject catch-up step inside ws:release-publish. ws:align stays as the standalone shortcut for the alignment-only case.

mvn ws:align-draft                              # preview
mvn ws:align-publish                            # apply

ws:reconcile-branches — recover yaml/git mismatch

Reconcile workspace.yaml branch fields against on-disk git state. Recovery / rare-use, separated from ws:align per ike-issues#200’s two-axis split. Each goal name describes its audience: ws:align is the safe daily POM convergence; ws:reconcile-branches is the recovery operation when the YAML’s recorded branch and the actual git checkout have drifted apart.

mvn ws:reconcile-branches-draft                # preview
mvn ws:reconcile-branches-publish              # apply

ws:release-draft — preview a coordinated release

Workspace-level release — releases all release-pending checked-out components (those with unreleased commits since their last tag, or cascaded as transitive downstream of one) in topological order. Scans for commits since each subproject’s last release tag. The release set is the union of:

• source-changed — subprojects with unreleased commits.
• cascade-pulled — subprojects whose upstream got released, even if they themselves had no commits.

The draft variant writes the planned actions to ws꞉release-draft.md and exits without changes.

mvn ws:release-draft

ws:release-publish — execute the coordinated release

Execute a workspace release with per-subproject catch-up alignment. The release loop performs per-subproject catch-up alignment immediately before each subproject’s release: every workspace-internal upstream version reference (parent and version properties) is bumped to the upstream’s current target version. This means a downstream component released second sees the actual just-released upstream version, not the snapshot it had when the release started.

Each subproject’s release runs the single-repo ike:release-publish under the hood, so site deploy, Nexus deploy, GitHub Release, and the workspace VCS state file all update in lockstep.

mvn ws:release-publish

ws:post-release — bump to next development version

Post-release version bump across workspace subprojects. After a release, this goal bumps every checked-out subproject’s POM version to the specified nextVersion, commits the change, pushes if a remote exists, then updates workspace.yaml to reflect the new development versions.

Components are processed in topological order so that upstream components bump before their downstreams.

mvn ws:post-release -DnextVersion=22-SNAPSHOT

ws:release-notes — milestone-derived release notes

Generate release notes from a GitHub milestone’s closed issues. Queries the GitHub REST API to find the named milestone, lists its closed issues, and categorizes them by label into Fixes, Enhancements, and Internal sections. Delegates to the same support class used by ike:release to auto-populate GitHub Release notes.

mvn ws:release-notes -Dmilestone="my-component v17"

ws:checkpoint — tag without releasing

Create a workspace checkpoint — tag every subproject at its current HEAD and record the snapshot in a YAML manifest. A checkpoint records the current state of the workspace for reproduction. It is not a build or a release — no POM version changes, no compilation, no deployment. TeamCity watches for checkpoint tags on the workspace repo and handles CI verification.

The publish variant runs ws:align-publish first so the checkpoint captures a consistent inter-subproject state.

mvn ws:checkpoint-draft -Dlabel=before-major-refactor
mvn ws:checkpoint-publish -Dlabel=before-major-refactor

ws:scaffold-draft — drift report

Read-only convergence drift report. Walks the ReconcilerRegistry in declared order and asks each reconciler to surface drift between the workspace’s current state and its declared convention:

• FieldNormalizationReconciler — workspace.yaml denormalized fields (groupIds, version, parent name) match each subproject POM’s authoritative truth (folds the retired ws:fix). Also collapses pre-existing duplicate subproject field keys to last-wins — the #387 safety net (#399).
• WorkspaceVerifier — manifest consistency, dependency reference resolution, cycle detection, valid subproject types, subproject git state, Syncthing health, environment presence (folds the retired ws:verify).
• ParentCascadeReconciler — aggregator parent version matches the scaffold manifest’s foundation: pin across the root POM and every cloned subproject (folds the retired ws:set-parent).
• ScaffoldConventionReconciler — gitignore blocks, git hooks, .mvn/maven.config, IDE settings against the scaffold manifest’s template files (folds the retired ws:scaffold-upgrade).
• AlignmentReconciler — inter-subproject dependency versions point at the workspace’s actual subproject versions (shares logic with ws:align, which stays as a standalone shortcut for the alignment-only case).

Writes the drift to ws꞉scaffold-draft.md; makes no on-disk changes. Pair with ws:scaffold-publish to apply.

mvn ws:scaffold-draft

ws:scaffold-publish — apply convergence drift

Apply the drift reported by ws:scaffold-draft. Drives the same ReconcilerRegistry, but each reconciler is asked to apply rather than report. This is the routine workspace-state reconciler — the one to run after any state-changing operation to converge the workspace back to its declared convention.

By default ws:scaffold-publish engages every reconciler. Each can be individually opted out via -D…​=false flags when you need to narrow the scope (e.g., apply field normalization without bumping the parent version):

The AlignmentReconciler is also invoked from ws:align-publish (standalone alignment-only shortcut), ws:feature-start-publish, ws:checkpoint-publish, and the per-subproject catch-up step inside ws:release-publish. Logic is shared; entry points differ.

mvn ws:scaffold-publish
mvn ws:scaffold-publish -DparentVersion=21
mvn ws:scaffold-publish -DupdateScaffold=false
mvn ws:scaffold-publish -DupdateFields=false -DupdateParent=false  # alignment-only

ws:cleanup-draft — list merged feature branches

Scan all workspace subprojects for merged feature branches and report them. Lists feature branches across all subprojects, classifies each as merged (into the target branch) or active, and displays last-commit timestamps. Read-only; the publish variant does the deletion.

mvn ws:cleanup-draft                           # list (default target=main)
mvn ws:cleanup-draft -DtargetBranch=develop    # check against develop

ws:cleanup-publish — interactive cleanup

Execute workspace cleanup — delete merged feature branches. Prompts interactively for each candidate.

mvn ws:cleanup-publish
mvn ws:cleanup-publish -Dforce=true            # delete without prompting