.. -*- mode: rst -*- .. vi: set ft=rst sts=4 ts=4 sw=4 et tw=79: .. _chap_design_drop: *********************** Drop dataset components *********************** .. topic:: Specification scope and status This specification is a proposal, subject to review and further discussion. It is now partially implemented in the `drop` command. §1 The :command:`drop` command is the antagonist of :command:`get`. Whatever a `drop` can do, should be undoable by a subsequent :command:`get` (given unchanged remote availability). §2 Like :command:`get`, :command:`drop` primarily operates on a mandatory path specification (to discover relevant files and sudatasets to operate on). §3 :command:`drop` has ``--what`` parameter that serves as an extensible "mode-switch" to cover all relevant scenarios, like 'drop all file content in the work-tree' (e.g. ``--what files``, default, `#5858 `__), 'drop all keys from any branch' (i.e. ``--what allkeys``, `#2328 `__), but also '"drop" AKA uninstall entire subdataset hierarchies' (e.g. ``--what all``), or drop preferred content (``--what preferred-content``, `#3122 `__). §4 :command:`drop` prevents data loss by default (`#4750 `__). Like :command:`get` it features a ``--reckless`` "mode-switch" to disable some or all potentially slow safety mechanism, i.e. 'key available in sufficient number of other remotes', 'main or all branches pushed to remote(s)' (`#1142 `__), 'only check availability of keys associated with the worktree, but not other branches'. "Reckless operation" can be automatic, when following a reckless :command:`get` (`#4744 `__). §5 :command:`drop` properly manages annex lifetime information, e.g. by announcing an annex as ``dead`` on removal of a repository (`#3887 `__). §6 Like :command:`get`, drop supports parallelization `#1953 `__ §7 `datalad drop` is not intended to be a comprehensive frontend to `git annex drop` (e.g. limited support for e.g. `#1482 `__ outside standard use cases like `#2328 `__). .. note:: It is understood that the current `uninstall` command is largely or completely made obsolete by this :command:`drop` concept. §8 Given the development in `#5842 `__ towards the complete obsolescence of `remove` it becomes necessary to import one of its proposed features: §9 :command:`drop` should be able to recognize a botched attempt to delete a dataset with a plain rm -rf, and act on it in a meaningful way, even if it is just hinting at chmod + rm -rf. Use cases ========= The following use cases operate in the dataset hierarchy depicted below:: super ├── dir │ ├── fileD1 │ └── fileD2 ├── fileS1 ├── fileS2 ├── subA │ ├── fileA │ ├── subsubC │ │ ├── fileC │ └── subsubD └── subB └── fileB Unless explicitly stated, all command are assumed to be executed in the root of `super`. - U1: ``datalad drop fileS1`` Drops the file content of `file1` (as currently done by :command:`drop`) - U2: ``datalad drop dir`` Drop all file content in the directory (``fileD{1,2}``; as currently done by :command:`drop` - U3: ``datalad drop subB`` Drop all file content from the entire `subB` (`fileB`) - U4: ``datalad drop subB --what all`` Same as above (default ``--what files``), because it is not operating in the context of a superdataset (no automatic upward lookups). Possibly hint at next usage pattern). - U5: ``datalad drop -d . subB --what all`` Drop all from the superdataset under this path. I.e. drop all from the subdataset and drop the subdataset itself (AKA uninstall) - U6: ``datalad drop subA --what all`` Error: "``subA`` contains subdatasets, forgot --recursive?" - U7: ``datalad drop -d . subA -r --what all`` Drop all content from the subdataset (``fileA``) and its subdatasets (``fileC``), uninstall the subdataset (``subA``) and its subdatasets (``subsubC``, ``subsubD``) - U8: ``datalad drop subA -r --what all`` Same as above, but keep ``subA`` installed - U9: ``datalad drop sub-A -r`` Drop all content from the subdataset and its subdatasets (``fileA``, ``fileC``) - U10: ``datalad drop . -r --what all`` Drops all file content and subdatasets, but leaves the superdataset repository behind - U11: ``datalad drop -d . subB`` Does nothing and hints at alternative usage, see https://github.com/datalad/datalad/issues/5832#issuecomment-889656335 - U12: ``cd .. && datalad drop super/dir`` Like :command:`get`, errors because the execution is not associated with a dataset. This avoids complexities, when the given `path`'s point to multiple (disjoint) datasets. It is understood that it could be done, but it is intentionally not done. `datalad -C super drop dir` or `datalad drop -d super super/dir` would work.