What is Command Versioning?

Each command can be available in different versions like v1, v2, v3, and so on. This is to support downwards compatibility in pipeline scripts. This way a newer version of a command will not break old pipeline code since it can be specified in a pipeline which exact command version to use.

Which commands are available in which versions can be found in the commands reference docs.

Specify the version per command (locally)​

In order to use a specific version of a single command, you need to add it as suffix :<version> to the command name, whereas <version> needs to be replaced by the version to be used. For example :v1, :v2, :v3, and so on.

Here is an example to use the log command with exact version v3 in a pipeline:

Here, we use version v4 of thelogcommand:

Specify the version per pipeline (globally)​

Instead of defining the version for each command, you can also set it globally for all commands of a pipeline using the header version. For example:

In this case all commands defined in the pipeline will use version v4 without the need of local definition per command.

In case you combine the header version with the local version on a command, the local one wins:

In this example, the log command is used with version v5.

Version fallback (backwards compatibility)​

Defining a version means you specify the highest version number to be used. If this version is not available, the next lower available version is loaded instead.

In case you specify a version like v5, for example, it will attempt to load the command with this exact version. In case no such command with this version exists, the next lower version will be looked up, like v4 for example. If no command with this version exists, the next lower version v3 is tried, and so on until v1 is reached which is the most minimal version and must be available for any existing command.

Latest version (default)

If no version is specified, by default the latest available version is used, which is the highest available version number of an command. Lets assume you have a command log available in versions v1, v2 and v3. Using the keyword latest here would pick-up the version v3 and use it:

Is the same as:

Is the same as:

Is the same as: