Compare two version numbers with each other. See VersionNumber.java for how version strings are handled.

The return value is an Integer;

• -1 if v1 < v2
• 0 if v1 == v2
• 1 if v1 > v2

Find files in the current working directory. The step returns an array of file info objects who's properties you can see in the below example.
Ex: def files = findFiles(glob: '**/TEST-*.xml') echo """${files[0].name} ${files[0].path} ${files[0].directory} ${files[0].length} ${files[0].lastModified}"""

Creates a file if it does not already exist, and prepends given content to it.

Reads a file in the current working directory or a String as a plain text. A List of CSVRecord instances is returned

Example:

def records = readCSV file: 'dir/input.csv'
assert records[0][0] == 'key'
assert records[1][1] == 'b'

def records = readCSV text: 'key,value\na,b'
assert records[0][0] == 'key'
assert records[1][1] == 'b'
	

Advanced Example:

def excelFormat = CSVFormat.EXCEL
def records = readCSV file: 'dir/input.csv', format: excelFormat
assert records[0][0] == 'key'
assert records[1][1] == 'b'

def records = readCSV text: 'key,value\na,b', format: CSVFormat.DEFAULT.withHeader()
assert records[0].get('key') == 'a'
assert records[0].get('value') == 'b'
	

Reads a file in the current working directory or a String as a plain text JSON file. The returned object is a normal Map with String keys or a List of primitives or Map.

Example:

def props = readJSON file: 'dir/input.json'
assert props['attr1'] == 'One'
assert props.attr1 == 'One'

def props = readJSON text: '{ "key": "value" }'
assert props['key'] == 'value'
assert props.key == 'value'

def props = readJSON text: '[ "a", "b"]'
assert props[0] == 'a'
assert props[1] == 'b'

def props = readJSON text: '{ "key": null, "a": "b" }', returnPojo: true
assert props['key'] == null
props.each { key, value ->
    echo "Walked through key $key and value $value"
}
	

Reads a Jar Manifest file or text and parses it into a set of Maps. The returned data structure has two properties: main for the main attributes, and entries containing each individual section (except for main).

Example:

            def man = readManifest file: 'target/my.jar'
            assert man.main['Version'] == '6.15.8'
            assert man.main['Application-Name'] == 'My App'
            assert man.entries['Section1']['Key1'] == 'value1-1'
            assert man.entries['Section2']['Key2'] == 'value2-2'
        

Reads a Maven project file. The returned object is a Model .

Avoid using this step and writeMavenPom. It is better to use the sh step to run mvn goals. For example:

def version = sh script: 'mvn help:evaluate -Dexpression=project.version -q -DforceStdout', returnStdout: true

Reads a file in the current working directory or a String as a plain text Java Properties file. The returned object is a normal Map with String keys. The map can also be pre loaded with default values before reading/parsing the data.

• file: Optional path to a file in the workspace to read the properties from. These are added to the resulting map after the defaults and so will overwrite any key/value pairs already present.
• text: An Optional String containing properties formatted data. These are added to the resulting map after file and so will overwrite any key/value pairs already present.
• defaults: An Optional Map containing default key/values. These are added to the resulting map first.
• interpolate: Flag to indicate if the properties should be interpolated or not.
  Prefix interpolations allowed by default are: urlDecoder, urlEncoder, date, base64Decoder, base64Encoder. Default prefix interpolations can be overridden by setting the system property:
  org.jenkinsci.plugins.pipeline.utility.steps.conf.ReadPropertiesStepExecution.CUSTOM_PREFIX_INTERPOLATOR_LOOKUPS
  Note that overriding default prefix interpolations can be insecure depending on which ones you enable. In case of error or cyclic dependencies, the original properties will be returned.
• charset: What charset to use when read properties file. Default is empty, then will use jvm ISO 8859-1.

Example:

        def d = [test: 'Default', something: 'Default', other: 'Default']
        def props = readProperties defaults: d, file: 'dir/my.properties', text: 'other=Override'
        assert props['test'] == 'One'
        assert props['something'] == 'Default'
        assert props.something == 'Default'
        assert props.other == 'Override'
        

        def props = readProperties interpolate: true, file: 'test.properties'
        assert props.url = 'http://localhost'
        assert props.resource = 'README.txt'
        // if fullUrl is defined to ${url}/${resource} then it should evaluate to http://localhost/README.txt
        assert props.fullUrl = 'http://localhost/README.txt'
        

        def props = readProperties charset: 'UTF-8', file: 'test.properties'
        

Reads a file in the current working directory or a String as a plain text TOML file. The returned object is a normal Map with String keys or a List of primitives or Map.

Example:

def props = readTOML file: 'dir/input.toml'
assert props['attr1'] == 'One'
assert props.attr1 == 'One'

def props = readTOML text: 'key = "value"'
assert props['key'] == 'value'
assert props.key == 'value'

def props = readTOML text: 'a = [ "a", "b" ]'
assert props.a[0] == 'a'
assert props.a[1] == 'b'

def props = readTOML text: 'a.b.c = 1\n[key]\nvalue = ""'
assert props['key'].value == ""
assert props.a.b.c == 1
props.each { key, value ->
    echo "Walked through key $key and value $value"
}
	

Computes the SHA1 of a given file.

Computes the SHA256 of a given file.

Create a tar/tar.gz file of content in the workspace.

Creates a file if it does not already exist, and updates the timestamp.

Extract a tar/tar.gz file in the workspace.

Extract a zip file in the workspace.

Verifies the SHA1 of a given file.

Verifies the SHA256 of a given file.

Write a CSV file in the current working directory. That for example was previously read by readCSV. See CSVPrinter for details.

• records: The list of CSVRecord instances to write.
• file: Path to a file in the workspace to write to.
• format: See CSVFormat for details.

Example:

def records = [['key', 'value'], ['a', 'b']]
writeCSV file: 'output.csv', records: records, format: CSVFormat.EXCEL
    

Write JSON to a file in the current working directory, or to a String.

• json: The object to write. Can either be a JSON instance or another Map/List implementation. Both are supported.
• file (optional): Optional path to a file in the workspace to write to. If provided, then returnText must be false or omitted. It is required that either file is provided, or returnText is true.
• pretty (optional): Prettify the output with this number of spaces added to each level of indentation.
• returnText (optional): Return the JSON as a string instead of writing it to a file. Defaults to false. If true, then file must not be provided. It is required that either file is provided, or returnText is true.

Example:
Writing to a file:

        def amap = ['something': 'my datas',
                    'size': 3,
                    'isEmpty': false]

        writeJSON file: 'data.json', json: amap
        def read = readJSON file: 'data.json'

        assert read.something == 'my datas'
        assert read.size == 3
        assert read.isEmpty == false
        

        def amap = ['something': 'my datas',
                    'size': 3,
                    'isEmpty': false]

        String json = writeJSON returnText: true, json: amap
        def read = readJSON text: json

        assert read.something == 'my datas'
        assert read.size == 3
        assert read.isEmpty == false
        

Writes a Maven project file. That for example was previously read by readMavenPom.

• model: The Model object to write.
• file: Optional path to a file in the workspace to write to. If left empty the step will write to pom.xml in the current working directory.

Example:

        def pom = readMavenPom file: 'pom.xml'
        //Do some manipulation
        writeMavenPom model: pom
        

Avoid using this step and readMavenPom. It is better to use the sh step to run mvn goals: For example:

sh 'mvn versions:set-property -Dproperty=some-key -DnewVersion=some-value -DgenerateBackupPoms=false'

Write TOML to a file in the current working directory, or to a String.

• toml: The object to write. Can be Map implementation.
• file (optional): Optional path to a file in the workspace to write to. If provided, then returnText must be false or omitted. It is required that either file is provided, or returnText is true.
• returnText (optional): Return the TOML as a string instead of writing it to a file. Defaults to false. If true, then file must not be provided. It is required that either file is provided, or returnText is true.

Example:
Writing to a file:

        def amap = ['something': 'my datas',
                    'size': 3,
                    'isEmpty': false]

        writeTOML file: 'data.toml', toml: amap
        def read = readTOML file: 'data.toml'

        assert read.something == 'my datas'
        assert read.size == 3
        assert read.isEmpty == false
        

        def amap = ['something': 'my datas',
                    'size': 3,
                    'isEmpty': false]

        String toml = writeTOML returnText: true, toml: amap
        def read = readTOML text: toml

        assert read.something == 'my datas'
        assert read.size == 3
        assert read.isEmpty == false
        

Writes yaml to a file in the current working directory or a String from an Object or a String. It uses SnakeYAML as YAML processor. The call will fail if the file already exists.

• file (optional): Optional path to a file in the workspace to write the YAML datas to. If provided, then returnText must be false or omitted. It is required that either file is provided, or returnText is true.
• data (optional): An Optional Object containing the data to be serialized. You must specify data or datas, but not both in the same invocation.
• datas (optional): An Optional Collection containing the datas to be serialized as several YAML documents. You must specify data or datas, but not both in the same invocation.
• charset (optional): Optionally specify the charset to use when writing the file. Defaults to UTF-8 if nothing else is specified. What charsets that are available depends on your Jenkins master system. The java specification tells us though that at least the following should be available:
  • US-ASCII
  • ISO-8859-1
  • UTF-8
  • UTF-16BE
  • UTF-16LE
  • UTF-16
• overwrite (optional): Allow existing files to be overwritten. Defaults to false.
• returnText (optional): Return the YAML as a string instead of writing it to a file. Defaults to false. If true, then file, charset, and overwrite must not be provided. It is required that either file is provided, or returnText is true.

Examples:
Writing to a file:

        def amap = ['something': 'my datas',
                    'size': 3,
                    'isEmpty': false]

        writeYaml file: 'datas.yaml', data: amap
        def read = readYaml file: 'datas.yaml'

        assert read.something == 'my datas'
        assert read.size == 3
        assert read.isEmpty == false
        

        def amap = ['something': 'my datas',
                    'size': 3,
                    'isEmpty': false]

        String yml = writeYaml returnText: true, data: amap
        def read = readYaml text: yml

        assert read.something == 'my datas'
        assert read.size == 3
        assert read.isEmpty == false
        

Create a zip file of content in the workspace.