Debian Codegraph @

doc/source/design/stash-environment.rst

raw
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: