Skip to content

Rename Environment Items and Files

Resolves environment markers after a checkout. Files whose names carry a {PROD}-style marker for the job's own environment get the marker cut out of the name, files marked for a different environment are deleted, and everything else is left alone. It does the same thing to the item list in the stash.

The op is how one repository ships per-environment variants of the same file. Commit app{DEV}.properties and app{PROD}.properties side by side, check both out, and this op leaves one app.properties behind on the environment that is being deployed to.

Run it after a checkout and before anything that reads the files. Load Job Items into Stash already resolves markers in the item list it builds, so in a modern pipeline the file pass is the half that does the work.

job directory, deploying to PROD app{PROD}.properties app{DEV}.properties setup{ALL}.sql readme.txt marker stripped deleted ALL and ANY also stripped, else kept app.properties setup.sql readme.txt if app.properties already existed, it is deleted first and the marked file takes its place. a marker in a folder name moves the file out of that folder, or stops the job

Fields

There is no form. Opening the op shows a configuration editor holding two keys, both set to 1:

rename_files: 1
rename_items: 1

rename_files

Controls the pass over the files on disk. Set it to 0, or delete the key, and no file in the job directory is renamed or deleted.

rename_items

Controls the pass over the item list in the stash. Set it to 0, or delete the key, and the list is left exactly as the loader built it.

The two passes are independent and run in that order, files first. Turning both off makes the op do nothing at all, with no log line to say so.

The file pass

The pass walks the whole job directory, every level down. For each file it computes a new name by removing three things from the full path: { plus the job's environment name plus }, then {ALL}, then {ANY}. Every occurrence goes, not only the first, and the match is on the path as a whole, so a marker in a directory component of the path counts too.

Then one of three things happens:

  • the name changed, so the file is renamed. If a file already sits at the new name, it is deleted first and the marked file takes its place. That is how a per-environment variant overrides a plain default committed next to it.
  • the name did not change but it does carry a marker for some other environment, so the file is deleted.
  • neither, so the file is left alone.

Directories are never renamed. Only the files inside them are, and the marker is cut out of the whole path, so a file sitting in conf{PROD}/ is moved to conf/. When conf/ does not already exist the move fails and the job stops. When it does exist the file lands there and the marked folder is left behind, now empty. Put environment markers on file names, not on folder names.

Paths containing system volume are skipped, which keeps the walk out of Windows system folders.

{ALL} and {ANY} come out whatever environment you are deploying to, and unlike the environment markers they never cause a delete.

A failed rename or a failed delete stops the job with a message naming the file and the reason.

A job whose environment is the wildcard * returns immediately, touching nothing and logging nothing. An empty job directory path stops the op with an error that carries no message of its own, which makes it a hard failure to place. If the job directory is named but is not there, the op fails saying it could not find the rename root directory, which normally means Init Job Home never ran.

The item pass

This pass rewrites items in the stash. Each entry is sorted into one of three outcomes:

  • path carries this environment's marker: the marker is stripped and the entry is kept, with its file name updated to match
  • path carries no environment marker at all: kept as is
  • path carries some other environment's marker: dropped from the list

Only the environment marker is handled here. {ALL} and {ANY} are stripped from files on disk but not from item paths, so an item can end up pointing at a name that no longer exists on disk. Where that matters, address the file by its final name rather than through the item list.

The list is replaced wholesale. Entries dropped here are gone for every op that follows.

What you see in the log

A debug line saying the file rename is running for the job's environment goes out before the walk starts, and only when rename_files is on.

The file pass writes Renamed N file(s) with the old and new names attached, and a separate line saying elements belonging to another environment were deleted, with that list attached. Each line appears only when that pass actually did something.

The item pass writes Renamed N item(s), removed M item(s) with the three lists attached, but only when at least one item was renamed. A run that renames nothing and removes ten items writes no line at all. Ten items vanish from the job in silence. When items go missing between this op and the next one, that is the first thing to check.

What comes back

Return Key on the op's Options tab captures the outcome in a stash variable of your choosing. It holds files, the renamed files as old and new pairs, and items, the same pairs for the item list. Deleted files and dropped items are not in it.

Set Return Key to = instead of a name and those two are merged into the stash as top-level variables, which replaces the job's item list with the short list of renamed pairs and breaks every op after it. Give it a name of your own.

Rollback

The op runs on a rollback pass like any other, and does the same thing: it strips markers and deletes other environments' files in the job directory as it finds it. It does not put back anything a forward run deleted. Where a rollback needs the original files, restore them from the backups Ship File Remotely keeps, or guard the op with IF ROLLBACK.

Combining with other ops

It goes after the checkout. Checkout Job Items, Checkout Job Environment and Checkout Job Environment (all repos) all write into the job directory, and this op cleans up what they wrote.

It goes before anything that reads file names. Replace Strings, Ship File Remotely, Zip local path and Run command or local script all see the final names only when they follow this op.

Load Job Items into Stash is where environment markers are first resolved, in the item list rather than on disk. Reading that page tells you which markers have already gone by the time this op runs.

Examples

The usual placement, with both passes on.

JOB STEP: RUN
  Init Job Home
  Load Job Items into Stash
  Checkout Job Items
  Rename Environment Items and Files
    rename_files: 1
    rename_items: 1

Clean the files on disk but leave the item list untouched, for a rule that reports on the items the job started with.

Rename Environment Items and Files
  rename_files: 1
  rename_items: 0