Debian Codegraph @

docs/source/design/drop.rst

raw
1 .. -*- mode: rst -*-
2 .. vi: set ft=rst sts=4 ts=4 sw=4 et tw=79:
3
4 .. _chap_design_drop:
5
6 ***********************
7 Drop dataset components
8 ***********************
9
10 .. topic:: Specification scope and status
11
12 This specification is a proposal, subject to review and further discussion.
13 It is now partially implemented in the `drop` command.
14
15 §1 The :command:`drop` command is the antagonist of :command:`get`. Whatever a
16 `drop` can do, should be undoable by a subsequent :command:`get` (given
17 unchanged remote availability).
18
19 §2 Like :command:`get`, :command:`drop` primarily operates on a mandatory path
20 specification (to discover relevant files and sudatasets to operate on).
21
22 §3 :command:`drop` has ``--what`` parameter that serves as an extensible
23 "mode-switch" to cover all relevant scenarios, like 'drop all file content in
24 the work-tree' (e.g. ``--what files``, default, `#5858
25 <https://github.com/datalad/datalad/issues/5858>`__), 'drop all keys from any
26 branch' (i.e. ``--what allkeys``, `#2328
27 <https://github.com/datalad/datalad/issues/2328>`__), but also '"drop" AKA
28 uninstall entire subdataset hierarchies' (e.g. ``--what all``), or drop
29 preferred content (``--what preferred-content``, `#3122
30 <https://github.com/datalad/datalad/issues/3122>`__).
31
32 §4 :command:`drop` prevents data loss by default (`#4750
33 <https://github.com/datalad/datalad/issues/4750>`__). Like :command:`get` it
34 features a ``--reckless`` "mode-switch" to disable some or all potentially slow
35 safety mechanism, i.e. 'key available in sufficient number of other remotes',
36 'main or all branches pushed to remote(s)' (`#1142
37 <https://github.com/datalad/datalad/issues/1142>`__), 'only check availability
38 of keys associated with the worktree, but not other branches'. "Reckless
39 operation" can be automatic, when following a reckless :command:`get` (`#4744
40 <https://github.com/datalad/datalad/issues/4744>`__).
41
42 §5 :command:`drop` properly manages annex lifetime information, e.g. by announcing
43 an annex as ``dead`` on removal of a repository (`#3887
44 <https://github.com/datalad/datalad/issues/3887>`__).
45
46 §6 Like :command:`get`, drop supports parallelization `#1953
47 <https://github.com/datalad/datalad/issues/1953>`__
48
49 §7 `datalad drop` is not intended to be a comprehensive frontend to `git annex
50 drop` (e.g. limited support for e.g. `#1482
51 <https://github.com/datalad/datalad/issues/1482>`__ outside standard use cases
52 like `#2328 <https://github.com/datalad/datalad/issues/2328>`__).
53
54 .. note::
55 It is understood that the current `uninstall` command is largely or
56 completely made obsolete by this :command:`drop` concept.
57
58 §8 Given the development in `#5842
59 <https://github.com/datalad/datalad/issues/5842>`__ towards the complete
60 obsolescence of `remove` it becomes necessary to import one of its proposed
61 features:
62
63 §9 :command:`drop` should be able to recognize a botched attempt to delete a
64 dataset with a plain rm -rf, and act on it in a meaningful way, even if it is
65 just hinting at chmod + rm -rf.
66
67
68 Use cases
69 =========
70
71 The following use cases operate in the dataset hierarchy depicted below::
72
73 super
74 ├── dir
75 │ ├── fileD1
76 │ └── fileD2
77 ├── fileS1
78 ├── fileS2
79 ├── subA
80 │ ├── fileA
81 │ ├── subsubC
82 │ │ ├── fileC
83 │ └── subsubD
84 └── subB
85 └── fileB
86
87 Unless explicitly stated, all command are assumed to be executed in the root of `super`.
88
89 - U1: ``datalad drop fileS1``
90
91 Drops the file content of `file1` (as currently done by :command:`drop`)
92
93 - U2: ``datalad drop dir``
94
95 Drop all file content in the directory (``fileD{1,2}``; as currently done by
96 :command:`drop`
97
98 - U3: ``datalad drop subB``
99
100 Drop all file content from the entire `subB` (`fileB`)
101
102 - U4: ``datalad drop subB --what all``
103
104 Same as above (default ``--what files``), because it is not operating in the
105 context of a superdataset (no automatic upward lookups). Possibly hint at
106 next usage pattern).
107
108 - U5: ``datalad drop -d . subB --what all``
109
110 Drop all from the superdataset under this path. I.e. drop all from the
111 subdataset and drop the subdataset itself (AKA uninstall)
112
113 - U6: ``datalad drop subA --what all``
114
115 Error: "``subA`` contains subdatasets, forgot --recursive?"
116
117 - U7: ``datalad drop -d . subA -r --what all``
118
119 Drop all content from the subdataset (``fileA``) and its subdatasets
120 (``fileC``), uninstall the subdataset (``subA``) and its subdatasets
121 (``subsubC``, ``subsubD``)
122
123 - U8: ``datalad drop subA -r --what all``
124
125 Same as above, but keep ``subA`` installed
126
127 - U9: ``datalad drop sub-A -r``
128
129 Drop all content from the subdataset and its subdatasets (``fileA``,
130 ``fileC``)
131
132 - U10: ``datalad drop . -r --what all``
133
134 Drops all file content and subdatasets, but leaves the superdataset
135 repository behind
136
137 - U11: ``datalad drop -d . subB``
138
139 Does nothing and hints at alternative usage, see
140 https://github.com/datalad/datalad/issues/5832#issuecomment-889656335
141
142 - U12: ``cd .. && datalad drop super/dir``
143
144 Like :command:`get`, errors because the execution is not associated with a
145 dataset. This avoids complexities, when the given `path`'s point to multiple
146 (disjoint) datasets. It is understood that it could be done, but it is
147 intentionally not done. `datalad -C super drop dir` or `datalad drop -d super
148 super/dir` would work.