1datalad status(1) General Commands Manual datalad status(1)
2
6 datalad status - report on the state of dataset content.
7
9 datalad status [-h] [-d DATASET] [--annex [{basic|availability|all}]]
10 [--untracked {no|normal|all}] [-r] [-R LEVELS]
11 [-e {no|commit|full}] [-t {raw|eval}] [--version] [PATH ...]
12
16 This is an analog to `git status` that is simultaneously crippled and
17 more powerful. It is crippled, because it only supports a fraction of
18 the functionality of its counter part and only distinguishes a subset
19 of the states that Git knows about. But it is also more powerful as it
20 can handle status reports for a whole hierarchy of datasets, with the
21 ability to report on a subset of the content (selection of paths)
22 across any number of datasets in the hierarchy.
23 Path conventions
25 All reports are guaranteed to use absolute paths that are underneath
26 the given or detected reference dataset, regardless of whether query
27 paths are given as absolute or relative paths (with respect to the
28 working directory, or to the reference dataset, when such a dataset is
29 given explicitly). Moreover, so-called "explicit relative paths" (i.e.
30 paths that start with respect to the current working directory regard‐
31 less of whether a reference dataset with specified.
32 When it is necessary to address a subdataset record in a superdataset
34 without causing a status query for the state _within_ the subdataset
35 itself, this can be achieved by explicitly providing a reference
36 dataset and the path to the root of the subdataset like so::
37 datalad status --dataset . subdspath
39 In contrast, when the state of the subdataset within the superdataset
41 is not relevant, a status query for the content of the subdataset can
42 be obtained by adding a trailing path separator to the query path
43 (rsync-like syntax)::
44 datalad status --dataset . subdspath/
46 When both aspects are relevant (the state of the subdataset content and
48 the state of the subdataset within the superdataset), both queries can
49 be combined::
50 datalad status --dataset . subdspath subdspath/
52 When performing a recursive status query, both status aspects of sub‐
54 dataset are always included in the report.
55 Content types
57 The following content types are distinguished:
58 - 'dataset' -- any top-level dataset, or any subdataset that is proper‐
60 ly registered in superdataset - 'directory' -- any directory that does
61 not qualify for type 'dataset' - 'file' -- any file, or any symlink
62 that is placeholder to an annexed file when annex-status reporting is
63 enabled - 'symlink' -- any symlink that is not used as a placeholder
64 for an annexed
65 file
67 Content states
69 The following content states are distinguished:
70 - 'clean' - 'added' - 'modified' - 'deleted' - 'untracked'
72 Examples
74 Report on the state of a dataset::
75 % datalad status
77 Report on the state of a dataset and all subdatasets::
79 % datalad status -r
81 Address a subdataset record in a superdataset without causing a status
83 query for the state _within_ the subdataset itself::
84 % datalad status -d . mysubdataset
86 Get a status query for the state within the subdataset without causing
88 a status query for the superdataset (using trailing path separator in
89 the query path):::
90 % datalad status -d . mysubdataset/
92 Report on the state of a subdataset in a superdataset and on the state
94 within the subdataset::
95 % datalad status -d . mysubdataset mysubdataset/
97 Report the file size of annexed content in a dataset::
99 % datalad status --annex
101
104 PATH path to be evaluated. Constraints: value must be a string or
105 value must be NONE
106 -h, --help, --help-np
109 show this help message. --help-np forcefully disables the use of
110 a pager for displaying the help message
111 -d DATASET, --dataset DATASET
113 specify the dataset to query. If no dataset is given, an attempt
114 is made to identify the dataset based on the current working di‐
115 rectory. Constraints: Value must be a Dataset or a valid identi‐
116 fier of a Dataset (e.g. a path) or value must be NONE
117 --annex [{basic|availability|all}]
119 Switch whether to include information on the annex content of
120 individual files in the status report, such as recorded file
121 size. By default no annex information is reported (faster).
122 Three report modes are available: basic information like file
123 size and key name ('basic'); additionally test whether file con‐
124 tent is present in the local annex ('availability'; requires one
125 or two additional file system stat calls, but does not call git-
126 annex), this will add the result properties 'has_content' (bool‐
127 ean flag) and 'objloc' (absolute path to an existing annex ob‐
128 ject file); or 'all' which will report all available information
129 (presently identical to 'availability'). The 'basic' mode will
130 be assumed when this option is given, but no mode is specified.
131 Constraints: value must be one of ('basic', 'availability',
132 'all')
133 --untracked {no|normal|all}
135 If and how untracked content is reported when comparing a revi‐
136 sion to the state of the working tree. 'no': no untracked con‐
137 tent is reported; 'normal': untracked files and entire untracked
138 directories are reported as such; 'all': report individual files
139 even in fully untracked directories. Constraints: value must be
140 one of ('no', 'normal', 'all') [Default: 'normal']
141 -r, --recursive
143 if set, recurse into potential subdatasets.
144 -R LEVELS, --recursion-limit LEVELS
146 limit recursion into subdatasets to the given number of levels.
147 Constraints: value must be convertible to type 'int' or value
148 must be NONE
149 -e {no|commit|full}, --eval-subdataset-state {no|commit|full}
151 Evaluation of subdataset state (clean vs. modified) can be ex‐
152 pensive for deep dataset hierarchies as subdataset have to be
153 tested recursively for uncommitted modifications. Setting this
154 option to 'no' or 'commit' can substantially boost performance
155 by limiting what is being tested. With 'no' no state is evaluat‐
156 ed and subdataset result records typically do not contain a
157 'state' property. With 'commit' only a discrepancy of the HEAD
158 commit shasum of a subdataset and the shasum recorded in the su‐
159 perdataset's record is evaluated, and the 'state' result proper‐
160 ty only reflects this aspect. With 'full' any other modification
161 is considered too (see the 'untracked' option for further tai‐
162 loring modification testing). Constraints: value must be one of
163 ('no', 'commit', 'full') [Default: 'full']
164 -t {raw|eval}, --report-filetype {raw|eval}
166 THIS OPTION IS IGNORED. It will be removed in a future release.
167 Dataset component types are always reported as-is (previous
168 'raw' mode), unless annex-reporting is enabled with the --annex
169 option, in which case symlinks that represent annexed files will
170 be reported as type='file'. Constraints: value must be one of
171 ('raw', 'eval')
172 --version
174 show the module and its version which provides the command
175
177 datalad is developed by The DataLad Team and Contributors <team@datal‐
178 ad.org>.
179datalad status 0.19.3 2023-08-11 datalad status(1)