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