Shell

kind: shell

sourceconditiontarget

Description

source

The Shell "source" retrieves the source value from the standard output of a shell command.

condition

The Shell "condition" validates the condition by checking the exit code of a shell command with a source as argument.

target

The Shell "targets" delegates the update of your files to a shell command with a source as argument.

Parameters

NameRequiredDefaultDescription

command

Command to execute (Linux or Windows)

Shell Source

The command provided by your spec section is executed by updatecli to retrieve the source:

  • If the commands runs successfully (e.g. with an exit code of zero), the source takes the value of the inlined (e.g. removing the line returns) standard output.

  • An error is raised if the exit code of the command is different than zero. The error prints the content from both standard error (stderr) and output (stdout) of the command.

Source Examples

  • The following example should result in a source value of 1.2.3:

    # source-shell-OK.yaml
    sources:
      example:
        kind: shell
        spec:
          command: echo 1.2.3
    $ updatecli --config=./source-shell-OK.yaml apply
    # ...
    
    SOURCE:
    =======
    
    ✔ The shell 🐚 command "echo 1.2.3" ran successfully and retrieved the following source value: "1.2.3"
    
    # ...
  • The following example should result in a failing source:

    # source-shell-FAIL.yaml
    sources:
      example:
        kind: shell
        spec:
          command: ls /foobar
    $ updatecli --config=./source-shell-FAIL.yaml apply
    # ...
    
    SOURCE:
    =======
    
    ERROR: ✗ The shell 🐚 command "ls /foobar" failed with an exit code of 1 and the following messages:
    stderr=
    ls: /foobar: No such file or directory
    stdout=

Shell Condition

The command provided by your spec section is executed by updatecli to validate the condition:

  • If the commands runs successfully (e.g. with an exit code of zero), then the condition is validated.

  • Otherwise (an exit code different than zero) the condition is marked as not valid, and both the standard error and outputs are logged.

The source associated to this condition (the default source or through the key sourceID) is appended as the last argument to the command line.

Condition Examples

The following example shows how to test if the value from the source named newVersion equals to 1.2.3:

conditions:
  default:
    kind: shell
    sourceID: newVersion
    spec:
      # The value of the source "newVersion" is appended by updatecli
      command: test 1.2.3 ==
  • If the value of the source is 1.2.3, then you get:

    CONDITIONS:
    ===========
    
    ✔ The shell 🐚 command "test 1.2.3 == 1.2.3" successfully validated the condition.
  • If the value of the source is 2.0.0, than you get:

    CONDITIONS:
    ===========
    
    The shell 🐚 command "test 1.2.3 == 2.0.0" failed with an exit code of 1 and the following messages:
    stderr=
    
    stdout=
    
    ✗ condition not met, skipping pipeline

Shell Target

The command provided by your spec section is executed by updatecli to change your files:

  • When the commands runs successfully (e.g. with an exit code of zero), the behavior depends on the content of the standard output:

    • If it is empty, then updatecli report a success with no changes applied.

    • Otherwise updatecli report a success with the content of the standard output as the resulting value of the change.

  • Otherwise (an exit code different than zero) the condition is marked as not valid, and both the standard error and outputs are logged.

Please note that:

  • ℹ️ The source associated to this target (the default source or through the key sourceID) is appended as the last argument to the command line.

  • ℹ️ The environment variable DRY_RUN is set to the value true when using updatecli diff to report that any change should only be reported and not applied.

Target Examples

Consider the following shell script target.sh:

#!/bin/bash
# Script "target.sh"
# The script check the content of the file "version.txt"
# - if different than $1 and DRY_RUN is set to:
#   - "false" then it updates it with the value of $1
#   - "true" then it only reports the value of $1
# - otherwise it exists without any value reported
version_file=version.txt

if test "$1" == "$(cat "${version_file}")"
then
  ## No change
  # early return with no output
  exit 0
else
  if test "$DRY_RUN" == "false"
  then
    ## Value changed to $1" - NO dry run
    # do something such as writing a file here
    echo "$1" > "${version_file}"
  fi
  # Report on stdout
  echo "$1"
  exit 0
fi

With this updatecli configuration shell-target.yaml:

# shell-target.yaml
sources:
  default:
    kind: shell
    spec:
      command: echo 1.2.4
targets:
  default:
    name: setGrepVersion
    sourceID: default
    kind: shell
    spec:
      command: bash ./examples/updateCli.generic/shell/target.sh

You would have the following behaviors:

  • Running with dry run enabled:

    $ cat version.txt
    1.0.0
    
    $ updatecli --config=./shell-target.yaml diff
    #...
    
    TARGETS:
    ========
    
    **Dry Run enabled**
    
    ⚠ The shell 🐚 command "bash ./examples/updateCli.generic/shell/target.sh 1.2.4" ran successfully and reported the following change: "1.2.4".
    
    $ cat version.txt
    1.0.0 # No change
  • Applying the changes:

    $ updatecli --config=./shell-target.yaml apply
    #...
    
    TARGETS:
    ========
    
    ⚠ The shell 🐚 command "bash ./examples/updateCli.generic/shell/target.sh 1.2.4" ran successfully and reported the following change: "1.2.4".
    
    $ cat version.txt
    1.2.4 # Version changed

Reference

sources:
  newVersion:
    kind: shell
    name: Get new version
    spec:
      command: bash ./get-new-version.sh"
  failing:
    kind: shell
    name: Failing command
    spec:
      command: ls /foobar
conditions:
  checkIfVersionEquals123:
    kind: shell
    sourceId: newVersion
    spec:
      command: test 1.2.3 ==
targets:
  default:
    name: setGrepVersion
    sourceID: default
    kind: shell
    spec:
      command: bash apply.sh

Edit this page on GitHub