| 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. |