Skip to content

hardis:project:version:list

Description

Command Behavior

Lists the release versions of the project: the version deployed on each versioned major branch, the version each promotion would create, and the history of the version tags.

With release versioning, each successful deployment on a major branch whose branch config declares releaseVersioning: true creates a semver tag: release candidates (v1.5.0-rc.3) on every versioned branch but the highest one, plain versions (v1.5.0) on the highest one (usually main).

The command:

  • fetches the tags of the remote repository (skip it with --no-fetch);
  • gives, for each versioned branch, its role in the chain (first, middle, final) and the version last deployed in its org;
  • computes, for each major branch merged into a versioned branch, the version the next promotion would create, with the same rules as a deployment job;
  • lists the version tags, newest first, with the branch, the org, the deployment date, the Pull Request and the job that created them, in a report file;
  • with --with-links, adds the web URL of each tag and Release. It is off by default, since building the git provider client can call its API.

Nothing is written: no tag is created, no org is called. Without --with-links, only git is called: one fetch of the tags, then local reads. On a shallow clone, the history is not downloaded: a warning says that the release candidates older than the clone depth may be missing.

The DevOps Pipeline of the VS Code extension reads it with --json to show the versions on the branch and org nodes, the version each promotion will create, and the Releases tab.

Technical explanations
  • The tags are read with git for-each-ref refs/tags: a version tag created by a deployment is an annotated tag whose message starts with sfdx-hardis release version and holds the branch, the version, the release candidate number, the variables of the tag format, the org, the date, the Pull Request and the job URL. The version comes from that message, whatever the tag name (releaseVersioningTagFormat).
  • Other tags count only when their name is a plain semver version (v1.3.0, v1.3.0-rc.2), with no branch. The others (v2.0, release-x, v1.3.0-pi2-rc1 made by hand) are ignored.
  • The version a promotion would create is computed from the tags reachable from origin/<source branch>, as the deployment job computes it from the deployed commit.
  • With --json, the result holds enabled, initialVersion, minimumVersion, branches (branchName, role, current, nextOnPromotion) and history. Each version entry has tag, version (semver form, 1.5.0-rc.3: with tag formats, two release candidates of two branches can share it), variables (values of the custom variables of the tag format), prerelease, branchName, commit, deployedAt, org, pullRequest, jobUrl, tagUrl and releaseUrl.

Agent Mode

Supports non-interactive execution with --agent:

sf hardis:project:version:list --agent --json

In agent mode:

  • No flag is required: the command never prompts.
  • Use --json and read branches to know which version is in which org, and nextOnPromotion to know the version a promotion will create.

Reports

The command writes these reports in the hardis-report folder of the project: a CSV file, and its Excel copy (XLSX) in the xls sub-folder.

Release versions

One row per version tag of the repository, newest first: version, branch, deployment date, Pull Request and org.

Files: release-versions-*.csv, xls/release-versions-*.xlsx

Parameters

Name Type Description Default Required Options
agent boolean Run in non-interactive mode for agents and automation
debug
-d
boolean Activate debug mode (more logs)
fetch boolean Fetch the tags of the remote repository first (use --no-fetch to read the local tags only)
flags-dir option Import flag values from a directory.
history-limit option Number of version tags returned in the history, newest first 50
json boolean Format output as json.
skipauth boolean Skip authentication check when a default username is required
websocket option Websocket host:port for VsCode SFDX Hardis UI integration
with-links boolean Also return the web URL of each tag and Release (builds the git provider client, which can call its API)

Examples

$ sf hardis:project:version:list
$ sf hardis:project:version:list --json
$ sf hardis:project:version:list --no-fetch --history-limit 200
$ sf hardis:project:version:list --with-links --json
$ sf hardis:project:version:list --agent --json

Comments