Stashing environment

Stash the module environment changes compared to Initial environment in current shell session away. Inspired from git stash mechanisms and made as close as possible to them to enable people knowing these mechanisms to use them on module.

Stash mechanism on Modules rely on collection and initial environment mechanisms. When stashing, current environment is saved in a collection and initial environment is restored.

stash sub-command

stash sub-command saves current environment in a collection then restore initial environment.

General properties:

• Shortcut name: none

• Accepted option: --force, --auto, --no-auto

• Expected number of argument: 0

• Accept boolean variant specification: no

• Parse module version specification: no

• Fully read modulefile when checking validity: yes

• Sub-command only called from top level: yes

• Lead to modulefile evaluation: yes (unload and load modes)

stash is equivalent to save stash-<current_unixtime> then reset. Thus reset_target_state configuration value is taken into account to determine what is the initial environment state.

As it evaluates modules, --force, --auto and --no-auto options can be set for stash sub-command. But, as for reset sub-command these options should have no impact.

Nothing happens and a warning message is emitted when current environment state equals initial environment state.

• When comparing current environment and initial one, only the extra tags set and state-specific tags (auto-loaded, keep-loaded) are compared by default.

• If collection_pin_tag is enabled, all tags set (extra and regular) are compared

• A corner case exists if initial environment is recorded with collection_pin_tag disabled, then enabled afterward: in this situation stash cannot detect current environment is the same than recorded initial environment, so a stash collection will be created but nothing is changed after that when restoring initial environment

Error is obtained:

• and processing stops if stash collection cannot be saved.

• if a super-sticky module has to be unloaded.

• and processing stops if collection to restore does not exist, cannot be read or is not valid.

• and processing stops if current environment is empty or if the module constraints described are not satisfied.

When saved, stash collection is named stash-<milliseconds>. milliseconds is the current number of milliseconds since Unix Epoch. This 13-digit number makes latest generated stash collection the highest stash collection name. If collection_target configuration is set, target value is appended to the stash collection name, like for any other collection. For example, if collection target equals foo, stash collection file name is stash-1662295591123.foo.

Milliseconds is preferred over seconds as multiple stash operations may occur during the same second. This is for instance the case when running the non-regression testsuite.

By using current number of milliseconds we get a unique file name without the need to check existing stash file names.

stashpop sub-command

stashpop sub-command restore a stashed collection then delete this collection file.

General properties:

• Shortcut name: none

• Accepted option: --force, --auto, --no-auto

• Expected number of argument: 0 or 1

• Accept boolean variant specification: no

• Parse module version specification: no

• Fully read modulefile when checking validity: yes

• Sub-command only called from top level: yes

• Lead to modulefile evaluation: yes (unload and load modes)

stashpop is equivalent to restore stash-<xxx> then saverm stash-<xxx>.

As it evaluates modules, --force, --auto and --no-auto options can be set for stashpop sub-command. But, as for reset and stash sub-commands these options should have no impact.

The stash collection to restore can be specified as argument to stashpop sub-command. Either as:

• a stash index: 0 for the most recent stash, 1 for the one before it

• a stash collection name (e.g., stash-<milliseconds>)

Error is obtained and processing stops if:

• stash index does not correspond to an existing stash collection (for currently set collection target)

• stash collection name does not correspond to an existing collection (for currently set collection target)

• stash collection exists but cannot be accessed

• stash collection cannot be removed

If stash collection to pop is not different than current environment, collection restore will not change a thing and stash collection will be removed.

stashrm sub-command

stashrm sub-command delete a stash collection file.

General properties:

• Shortcut name: none

• Accepted option: none

• Expected number of argument: 0 or 1

• Accept boolean variant specification: no

• Parse module version specification: no

• Fully read modulefile when checking validity: yes

• Sub-command only called from top level: yes

• Lead to modulefile evaluation: no

stashrm is equivalent to saverm stash-<xxx>.

The stash collection to delete can be specified as argument to stashrm sub-command. Either as:

• a stash index: 0 for the most recent stash, 1 for the one before it

• a stash collection name (e.g., stash-<milliseconds>)

Error is obtained and processing stops if:

• stash index does not correspond to an existing stash collection (for currently set collection target)

• stash collection name does not correspond to an existing collection (for currently set collection target)

• stash collection exists but cannot be accessed

• stash collection cannot be removed

stashshow sub-command

stashshow sub-command displays the content of a stash collection file.

General properties:

• Shortcut name: none

• Accepted option: none

• Expected number of argument: 0 or 1

• Accept boolean variant specification: no

• Parse module version specification: no

• Fully read modulefile when checking validity: yes

• Sub-command only called from top level: yes

• Lead to modulefile evaluation: no

stashshow is equivalent to saveshow stash-<xxx>.

The stash collection to display can be specified as argument to stashshow sub-command. Either as:

• a stash index: 0 for the most recent stash, 1 for the one before it

• a stash collection name (e.g., stash-<milliseconds>)

Error is obtained and processing stops if:

• stash index does not correspond to an existing stash collection (for currently set collection target)

• stash collection name does not correspond to an existing collection (for currently set collection target)

• stash collection exists but cannot be accessed

• stash collection cannot be removed

stashclear sub-command

stashclear sub-command delete all stash collection files.

General properties:

• Shortcut name: none

• Accepted option: none

• Expected number of argument: 0

• Accept boolean variant specification: no

• Parse module version specification: no

• Fully read modulefile when checking validity: yes

• Sub-command only called from top level: yes

• Lead to modulefile evaluation: no

stashclear removes stash collection of currently defined collection_target.

stashclear proceeds without a confirmation message and does not output the list of stash collection removed, even in verbose mode.

Error is obtained and processing stops if:

• a stash collection cannot be removed

stashlist sub-command

stashlist sub-command lists all stash collection files.

General properties:

• Shortcut name: none

• Accepted option: --terse, --long, --json

• Expected number of argument: 0

• Accept boolean variant specification: no

• Parse module version specification: no

• Fully read modulefile when checking validity: yes

• Sub-command only called from top level: yes

• Lead to modulefile evaluation: no

stashlist is equivalent to savelist stash-*.

stashlist lists stash collection of currently defined collection_target.

Returned stash collections are listed in the reverse order (most recent collection first) and list index starts at 0. Index is this way consistent with stash index argument value that could be provided to stashpop, stashshow or stashrm sub-commands.

stashlist relies on savelist sub-command. A difference exists however: when no collection target is set, only the stash collections without a target defined are returned.

Error is obtained and processing stops if:

• stash collection exists but cannot be accessed

savelist sub-command

savelist sub-command is adapted to filter out stash collections by default. Stash collections are reported if --all option is set.