| 1 |
.. _stashing-environment: |
| 2 |
|
| 3 |
Stashing environment |
| 4 |
==================== |
| 5 |
|
| 6 |
Stash the module environment changes compared to :ref:`initial-environment` |
| 7 |
in current shell session away. Inspired from ``git stash`` mechanisms and made |
| 8 |
as close as possible to them to enable people knowing these mechanisms to use |
| 9 |
them on ``module``. |
| 10 |
|
| 11 |
Stash mechanism on Modules rely on collection and initial environment |
| 12 |
mechanisms. When stashing, current environment is saved in a collection and |
| 13 |
initial environment is restored. |
| 14 |
|
| 15 |
stash sub-command |
| 16 |
----------------- |
| 17 |
|
| 18 |
:subcmd:`stash` sub-command saves current environment in a collection then |
| 19 |
restore initial environment. |
| 20 |
|
| 21 |
General properties: |
| 22 |
|
| 23 |
* Shortcut name: none |
| 24 |
* Accepted option: :option:`--force`, :option:`--auto`, :option:`--no-auto` |
| 25 |
* Expected number of argument: 0 |
| 26 |
* Accept boolean variant specification: no |
| 27 |
* Parse module version specification: no |
| 28 |
* Fully read modulefile when checking validity: yes |
| 29 |
* Sub-command only called from top level: yes |
| 30 |
* Lead to modulefile evaluation: yes (``unload`` and ``load`` modes) |
| 31 |
|
| 32 |
``stash`` is equivalent to :subcmd:`save stash-\<current_unixtime\><save>` |
| 33 |
then :subcmd:`reset`. Thus :mconfig:`reset_target_state` configuration value |
| 34 |
is taken into account to determine what is the initial environment state. |
| 35 |
|
| 36 |
As it evaluates modules, ``--force``, ``--auto`` and ``--no-auto`` options can |
| 37 |
be set for ``stash`` sub-command. But, as for ``reset`` sub-command these |
| 38 |
options should have no impact. |
| 39 |
|
| 40 |
Nothing happens and a warning message is emitted when current environment |
| 41 |
state equals initial environment state. |
| 42 |
|
| 43 |
* When comparing current environment and initial one, only the extra tags set |
| 44 |
and state-specific tags (*auto-loaded*, *keep-loaded*) are compared by |
| 45 |
default. |
| 46 |
* If :mconfig:`collection_pin_tag` is enabled, all tags set (extra and |
| 47 |
regular) are compared |
| 48 |
* A corner case exists if initial environment is recorded with |
| 49 |
``collection_pin_tag`` disabled, then enabled afterward: in this situation |
| 50 |
``stash`` cannot detect current environment is the same than recorded |
| 51 |
initial environment, so a stash collection will be created but nothing is |
| 52 |
changed after that when restoring initial environment |
| 53 |
|
| 54 |
Error is obtained: |
| 55 |
|
| 56 |
* and processing stops if stash collection cannot be saved. |
| 57 |
* if a *super-sticky* module has to be unloaded. |
| 58 |
* and processing stops if collection to restore does not exist, cannot be read |
| 59 |
or is not valid. |
| 60 |
* and processing stops if current environment is empty or if the module |
| 61 |
constraints described are not satisfied. |
| 62 |
|
| 63 |
When saved, stash collection is named *stash-<milliseconds>*. *milliseconds* |
| 64 |
is the current number of milliseconds since Unix Epoch. This 13-digit number |
| 65 |
makes latest generated stash collection the highest stash collection name. If |
| 66 |
:mconfig:`collection_target` configuration is set, target value is appended |
| 67 |
to the stash collection name, like for any other collection. For example, if |
| 68 |
collection target equals ``foo``, stash collection file name is |
| 69 |
``stash-1662295591123.foo``. |
| 70 |
|
| 71 |
Milliseconds is preferred over seconds as multiple stash operations may occur |
| 72 |
during the same second. This is for instance the case when running the |
| 73 |
non-regression testsuite. |
| 74 |
|
| 75 |
By using current number of milliseconds we get a unique file name without the |
| 76 |
need to check existing stash file names. |
| 77 |
|
| 78 |
stashpop sub-command |
| 79 |
-------------------- |
| 80 |
|
| 81 |
:subcmd:`stashpop` sub-command restore a stashed collection then delete this |
| 82 |
collection file. |
| 83 |
|
| 84 |
General properties: |
| 85 |
|
| 86 |
* Shortcut name: none |
| 87 |
* Accepted option: :option:`--force`, :option:`--auto`, :option:`--no-auto` |
| 88 |
* Expected number of argument: 0 or 1 |
| 89 |
* Accept boolean variant specification: no |
| 90 |
* Parse module version specification: no |
| 91 |
* Fully read modulefile when checking validity: yes |
| 92 |
* Sub-command only called from top level: yes |
| 93 |
* Lead to modulefile evaluation: yes (``unload`` and ``load`` modes) |
| 94 |
|
| 95 |
``stashpop`` is equivalent to :subcmd:`restore stash-\<xxx\><restore>` then |
| 96 |
:subcmd:`saverm stash-\<xxx\><saverm>`. |
| 97 |
|
| 98 |
As it evaluates modules, ``--force``, ``--auto`` and ``--no-auto`` options can |
| 99 |
be set for ``stashpop`` sub-command. But, as for ``reset`` and ``stash`` |
| 100 |
sub-commands these options should have no impact. |
| 101 |
|
| 102 |
The stash collection to restore can be specified as argument to ``stashpop`` |
| 103 |
sub-command. Either as: |
| 104 |
|
| 105 |
* a stash index: 0 for the most recent stash, 1 for the one before it |
| 106 |
* a stash collection name (e.g., *stash-<milliseconds>*) |
| 107 |
|
| 108 |
Error is obtained and processing stops if: |
| 109 |
|
| 110 |
* stash index does not correspond to an existing stash collection (for |
| 111 |
currently set collection target) |
| 112 |
* stash collection name does not correspond to an existing collection (for |
| 113 |
currently set collection target) |
| 114 |
* stash collection exists but cannot be accessed |
| 115 |
* stash collection cannot be removed |
| 116 |
|
| 117 |
If stash collection to pop is not different than current environment, |
| 118 |
collection restore will not change a thing and stash collection will be |
| 119 |
removed. |
| 120 |
|
| 121 |
stashrm sub-command |
| 122 |
------------------- |
| 123 |
|
| 124 |
:subcmd:`stashrm` sub-command delete a stash collection file. |
| 125 |
|
| 126 |
General properties: |
| 127 |
|
| 128 |
* Shortcut name: none |
| 129 |
* Accepted option: none |
| 130 |
* Expected number of argument: 0 or 1 |
| 131 |
* Accept boolean variant specification: no |
| 132 |
* Parse module version specification: no |
| 133 |
* Fully read modulefile when checking validity: yes |
| 134 |
* Sub-command only called from top level: yes |
| 135 |
* Lead to modulefile evaluation: no |
| 136 |
|
| 137 |
``stashrm`` is equivalent to :subcmd:`saverm stash-\<xxx\><saverm>`. |
| 138 |
|
| 139 |
The stash collection to delete can be specified as argument to ``stashrm`` |
| 140 |
sub-command. Either as: |
| 141 |
|
| 142 |
* a stash index: 0 for the most recent stash, 1 for the one before it |
| 143 |
* a stash collection name (e.g., *stash-<milliseconds>*) |
| 144 |
|
| 145 |
Error is obtained and processing stops if: |
| 146 |
|
| 147 |
* stash index does not correspond to an existing stash collection (for |
| 148 |
currently set collection target) |
| 149 |
* stash collection name does not correspond to an existing collection (for |
| 150 |
currently set collection target) |
| 151 |
* stash collection exists but cannot be accessed |
| 152 |
* stash collection cannot be removed |
| 153 |
|
| 154 |
stashshow sub-command |
| 155 |
--------------------- |
| 156 |
|
| 157 |
:subcmd:`stashshow` sub-command displays the content of a stash collection file. |
| 158 |
|
| 159 |
General properties: |
| 160 |
|
| 161 |
* Shortcut name: none |
| 162 |
* Accepted option: none |
| 163 |
* Expected number of argument: 0 or 1 |
| 164 |
* Accept boolean variant specification: no |
| 165 |
* Parse module version specification: no |
| 166 |
* Fully read modulefile when checking validity: yes |
| 167 |
* Sub-command only called from top level: yes |
| 168 |
* Lead to modulefile evaluation: no |
| 169 |
|
| 170 |
``stashshow`` is equivalent to :subcmd:`saveshow stash-\<xxx\><saveshow>`. |
| 171 |
|
| 172 |
The stash collection to display can be specified as argument to ``stashshow`` |
| 173 |
sub-command. Either as: |
| 174 |
|
| 175 |
* a stash index: 0 for the most recent stash, 1 for the one before it |
| 176 |
* a stash collection name (e.g., *stash-<milliseconds>*) |
| 177 |
|
| 178 |
Error is obtained and processing stops if: |
| 179 |
|
| 180 |
* stash index does not correspond to an existing stash collection (for |
| 181 |
currently set collection target) |
| 182 |
* stash collection name does not correspond to an existing collection (for |
| 183 |
currently set collection target) |
| 184 |
* stash collection exists but cannot be accessed |
| 185 |
* stash collection cannot be removed |
| 186 |
|
| 187 |
stashclear sub-command |
| 188 |
---------------------- |
| 189 |
|
| 190 |
:subcmd:`stashclear` sub-command delete all stash collection files. |
| 191 |
|
| 192 |
General properties: |
| 193 |
|
| 194 |
* Shortcut name: none |
| 195 |
* Accepted option: none |
| 196 |
* Expected number of argument: 0 |
| 197 |
* Accept boolean variant specification: no |
| 198 |
* Parse module version specification: no |
| 199 |
* Fully read modulefile when checking validity: yes |
| 200 |
* Sub-command only called from top level: yes |
| 201 |
* Lead to modulefile evaluation: no |
| 202 |
|
| 203 |
``stashclear`` removes stash collection of currently defined |
| 204 |
``collection_target``. |
| 205 |
|
| 206 |
``stashclear`` proceeds without a confirmation message and does not output |
| 207 |
the list of stash collection removed, even in verbose mode. |
| 208 |
|
| 209 |
Error is obtained and processing stops if: |
| 210 |
|
| 211 |
* a stash collection cannot be removed |
| 212 |
|
| 213 |
stashlist sub-command |
| 214 |
--------------------- |
| 215 |
|
| 216 |
:subcmd:`stashlist` sub-command lists all stash collection files. |
| 217 |
|
| 218 |
General properties: |
| 219 |
|
| 220 |
* Shortcut name: none |
| 221 |
* Accepted option: :option:`--terse`, :option:`--long`, :option:`--json` |
| 222 |
* Expected number of argument: 0 |
| 223 |
* Accept boolean variant specification: no |
| 224 |
* Parse module version specification: no |
| 225 |
* Fully read modulefile when checking validity: yes |
| 226 |
* Sub-command only called from top level: yes |
| 227 |
* Lead to modulefile evaluation: no |
| 228 |
|
| 229 |
``stashlist`` is equivalent to :subcmd:`savelist stash-*<savelist>`. |
| 230 |
|
| 231 |
``stashlist`` lists stash collection of currently defined |
| 232 |
``collection_target``. |
| 233 |
|
| 234 |
Returned stash collections are listed in the reverse order (most recent |
| 235 |
collection first) and list index starts at 0. Index is this way consistent |
| 236 |
with stash index argument value that could be provided to ``stashpop``, |
| 237 |
``stashshow`` or ``stashrm`` sub-commands. |
| 238 |
|
| 239 |
``stashlist`` relies on ``savelist`` sub-command. A difference exists however: |
| 240 |
when no collection target is set, only the stash collections without a target |
| 241 |
defined are returned. |
| 242 |
|
| 243 |
Error is obtained and processing stops if: |
| 244 |
|
| 245 |
* stash collection exists but cannot be accessed |
| 246 |
|
| 247 |
savelist sub-command |
| 248 |
-------------------- |
| 249 |
|
| 250 |
:subcmd:`savelist` sub-command is adapted to filter out stash collections by |
| 251 |
default. Stash collections are reported if :option:`--all` option is set. |
| 252 |
|
| 253 |
.. vim:set tabstop=2 shiftwidth=2 expandtab autoindent: |