Load files/items into stash

Collects a list of paths on the Clarive server and hands it back as a single value, so that a later op can test it or walk it. It looks in one of three places: a directory listing, a whole directory tree, or the item paths of the nature currently being processed.

It shares its form with FOREACH file/item. The loop op walks the paths one at a time with the nested ops inside it; this op gathers the same paths into one list and stops. Use this one when you want the list itself, and the loop op when you want to act on each entry.

Fields

Variable

This op does not read the name you type here.

The field belongs to the loop version of the form, where it names the loop variable. In this op the list reaches the stash only through Return Key, in the op's properties panel. Filling in Variable and leaving Return Key empty is the most common way to end up with a rule that scans the disk and quietly discards the result.

Set Return Key to the name you want, for example my_files, and read it back as ${my_files}.

Path

Base path to search, expanded from the stash, so ${job_dir}/${project}/dist works.

It is required for both file modes. Leave it blank and the op stops the job with a message about the root path not being configured.

A path with no * or ? in it must exist on disk, or the op stops the job. A path containing either of those characters skips that check and is treated as a pattern.

In Nature Items mode the field means something different: it is optional, and when filled it is stripped off the front of each returned path rather than searched. The existence check still applies there, so a prefix you type by hand has to be a real directory unless it carries a wildcard.

Path Mode

Choice	What it lists
Files, non Recursive	the direct contents of Path, one level deep
Recursive Files	everything under Path, at any depth
Nature Items	the item paths of the nature currently in scope

Default is Files, non Recursive.

In Files, non Recursive, a Path that points at a directory lists that directory's children. A Path that contains a wildcard is expanded as a shell pattern, so ${job_dir}/*/target/*.jar works and no other mode gives you that.

Recursive Files walks the tree and cannot take a wildcard; give it a plain directory. Pointing it at a single file stops the job with a directory error.

Nature Items only has anything to work with inside IF EXISTS nature THEN, which is the op that puts the current nature's item paths in scope, and only for the length of its block. Outside the block the list comes back empty and nothing warns you. APPLY NATURE is not a substitute: it sets a different list that this mode does not read, so this op finds nothing after it.

The paths it picks up have already been trimmed by that block's Cut Path. They are resolved under the job directory, and entries that no longer exist on disk are dropped, so items deleted by the changeset do not appear.

Dir Mode

Choice	Meaning
Files only	plain files, no directories
Files and Directories	both
Only Directories	directories, no files

Default is Files only.

Files and Directories behaves as written in Recursive Files and Nature Items modes. In Files, non Recursive it does not: anything other than Files only returns directories alone there, so a flat listing with Files and Directories gives you the subdirectories and none of the files. When you need both from one directory, run the op twice and join the two lists.

In Recursive Files, the Path directory itself counts as one of the results under Only Directories and Files and Directories. Exclude it with a filter row if that matters.

Return relative paths?

Off by default. When ticked, the leading Path is stripped from every entry, so /opt/jobs/DEV-1/myapp/bar/baz.war comes back as bar/baz.war. Stripping happens after the filters run, so the rows under Filters are still matched against the full path.

Ticking it with no Path filled in returns an empty list. That combination is reachable in Nature Items mode, where Path is optional, and it is a silent no-op: the op succeeds and hands back nothing.

In Nature Items mode with Path filled in the checkbox changes nothing, because those paths were made relative to Path before the checkbox was consulted.

Filters

A two-tab panel. Each tab is a one-column grid with Add and Delete buttons above it. Add inserts a row pre-filled with .*; click the row to edit it.

Include Paths

Regular expressions, one per row. A path survives when it matches at least one row. An empty grid means everything survives, which is the normal setting.

These are regular expressions and not shell globs. *.jar does not do what you expect; write \.jar$. A row matches anywhere in the path string and is not anchored for you, so /target/ filters by directory. In Nature Items mode with Path filled in, the paths reaching the filters are already relative, and a row that starts with a slash matches nothing.

Rows expand ${var} placeholders against the stash before they are compiled, so /${module}/ is a usable row.

For a case-insensitive row, or any other regex flag, wrap the pattern in double exclamation marks and put the flags after: !!\.JAR$!!i.

Exclude Paths

Same grid, applied after the includes. A path matching any row is dropped, whatever the include rows said. A row here beats a row there.

Only the drops reach the job log, as one debug entry listing the full include and exclude sets followed by a line per discarded path naming the rule responsible. A run where every path survived writes nothing, so silence means no filtering happened rather than no logging.

What you get back

A list of path strings, with no de-duplication.

Order depends on the mode. Files, non Recursive is a shell-style expansion, so it comes back alphabetically and never includes a name that begins with a dot. Recursive Files comes back in directory order, which is arbitrary, and it does pick up dot files and dot directories. Nature Items follows the order of the nature's own item list.

Files, non Recursive and Recursive Files return absolute paths unless Return relative paths? is ticked. Nature Items returns paths already made relative to Path when you filled it in, and absolute job-directory paths when you did not.

An empty result is not an error. The op reports success, and a later op that iterates the list runs zero times.

Combining with other ops

Set Return Key, then walk the result with FOREACH CI or test it with IF var condition THEN using IS EMPTY before you commit to a deployment step.

When all you want is to act on each file, skip this op entirely and use FOREACH file/item, which has the same form and loops directly.

For nature-driven lists, put Load Nature Items earlier in the rule and nest this op inside IF EXISTS nature THEN.

To send the files you found, follow with Ship File Remotely, which accepts include and exclude patterns of its own in the same regex style. To rewrite their contents first, use Replace Strings.

Examples

Every jar produced by a build, anywhere under the project checkout, put in the stash as my_files.

Return Key             my_files
Path                   ${job_dir}/${project}
Path Mode              Recursive Files
Dir Mode               Files only
Return relative paths? no
Include Paths          \.jar$
Exclude Paths          /test/

The immediate subdirectories of a deploy root, to loop over one deployment per module.

Return Key             module_dirs
Path                   ${job_dir}/myapp/modules
Path Mode              Files, non Recursive
Dir Mode               Only Directories
Return relative paths? yes

The files of the nature being processed, relative to the project checkout, ready to hand to a packaging step. Place it inside the IF EXISTS nature THEN block.

Return Key             nature_files
Path                   ${job_dir}/${project}
Path Mode              Nature Items
Dir Mode               Files only
Exclude Paths          \.bak$