Debian Codegraph @

docs/source/design/dataset_argument.rst

raw
1 .. -*- mode: rst -*-
2 .. vi: set ft=rst sts=4 ts=4 sw=4 et tw=79:
3
4 .. _chap_design_dataset_argument:
5
6 ********************
7 ``dataset`` argument
8 ********************
9
10 .. topic:: Specification scope and status
11
12 This specification describes the current implementation.
13
14 All commands which operate on datasets have a ``dataset`` argument (``-d`` or
15 ``--dataset`` for the :term:`CLI`) to identify a single dataset as the
16 context of an operation.
17 If ``--dataset`` argument is not provided, the context of an operation is command-specific.
18 For example, `clone` command will consider the :term:`dataset` which is being cloned to be the context.
19 But typically, a dataset which current working directory belongs to is the context of an operation.
20 In the latter case, if operation (e.g., `get`) does not find a dataset in current working directory, operation fails with an ``NoDatasetFound`` error.
21
22
23 Impact on relative path resolution
24 ==================================
25
26 With one exception, the nature of a provided ``dataset`` argument does **not**
27 impact the interpretation of relative paths. Relative paths are always considered
28 to be relative to the process working directory.
29
30 The one exception to this rule is passing a ``Dataset`` object instance as
31 ``dataset`` argument value in the Python API. In this, and only this, case, a
32 relative path is interpreted as relative to the root of the respective dataset.
33
34
35 Special values
36 ==============
37
38 There are some pre-defined "shortcut" values for dataset arguments:
39
40 ``^``
41 Represents to the topmost superdataset that contains the dataset the current
42 directory is part of.
43 ``^.``
44 Represents the root directory of the dataset the current directory is part of.
45 ``///``
46 Represents the "default" dataset located under `$HOME/datalad/`.
47
48
49 Use cases
50 =========
51
52 Save modification in superdataset hierarchy
53 -------------------------------------------
54
55 Sometimes it is convenient to work only in the context of a subdataset.
56 Executing a ``datalad save <subdataset content>`` will record changes to the
57 subdataset, but will leave existing superdatasets dirty, as the subdataset
58 state change will not be saved there. Using the ``dataset`` argument it is
59 possible to redefine the scope of the save operation. For example::
60
61 datalad save -d^ <subdataset content>
62
63 will perform the exact same save operation in the subdataset, but additionally
64 save all subdataset state changes in all superdatasets until the root of a
65 dataset hierarchy. Except for the specification of the dataset scope there is
66 no need to adjust path arguments or change the working directory.