DATALAD-ANNOTATE-PATHS(1)

💖 datalad annotate-paths(1) 💖

okay bestie, welcome to the datalad annotate-paths glow-up — a page from the General Commands Manual that's about to become your new obsession. grab a boba, we're doing path analysis ✨

---

✨ NAME ✨

datalad annotate-paths — analyze and act upon input paths 🦋

---

🌸 SYNOPSIS 🌸

datalad annotate-paths [-h] [-d DATASET] [-r] [-R LEVELS]
       [--action LABEL] [--unavailable-path-status LABEL]
       [--unavailable-path-msg message] [--nondataset-path-status LABEL]
       [--no-parentds-discovery] [--no-subds-discovery] [--revision-
       change-discovery] [--no-untracked-discovery] [--modified
       [MODIFIED]] [--version] [PATH ...]

---

🎀 DESCRIPTION 🎀

so basically, you hand it paths (or like, "location requests" if we're being fancy), it inspects them, and it annotates them with a whole lil stack of properties. the list of recognized properties is right down below, no gatekeeping 💅

🧚 Recognized path properties 🧚

• action — label of the action that triggered the path annotation
• annexkey — annex key for the content of a file
• logger — logger for reporting a message
• message — message (plus possible tsring expansion arguments)
• orig_request — original input by which a path was determined
• parentds — path of dataset containing the annotated path (superdataset for subdatasets)
• path — absolute path that is annotated
• process_content — flag that content underneath the path is to be processed
• process_updated_only — flag that only known dataset components are to be processed
• raw_input — flag whether this path was given as raw (non-annotated) input
• refds — path of a reference/base dataset the annotated path is part of
• registered_subds — flag whether a dataset is known to be a true subdataset of PARENTDS
• revision — the recorded commit for a subdataset in a superdataset
• revision_descr — a human-readable description of REVISION
• source_url — URL a dataset was installed from
• staged — flag whether a path is known to be "staged" in its containing dataset
• state — state indicator for a path in its containing dataset (clean, modified, absent (also for files), conflict)
• status — action result status (ok, notneeded, impossible, error)
• type — nature of the path (file, directory, dataset)
• url — registered URL for a subdataset in a superdataset

if modification detection is turned on, the results can also carry extra properties about the nature of the modification. go peek at the docs of the DIFF command for the tea 👀

---

🌈 OPTIONS 🌈

• PATH — path to be annotated. Constraints: value must be a string
• -h, --help, --help-np — show this help message. --help-np forcefully disables the use of a pager for displaying the help message
• -d DATASET, --dataset DATASET — an optional reference/base dataset for the paths. Constraints: Value must be a Dataset or a valid identifier of a Dataset (e.g. a path)
• -r, --recursive — if set, recurse into potential subdataset.
• -R LEVELS, --recursion-limit LEVELS — limit recursion into subdataset to the given number of levels. Constraints: value must be convertible to type 'int'
• --action LABEL — an "action" property value to include in the path annotation. Constraints: value must be a string
• --unavailable-path-status LABEL — a "status" property value to include in the annotation for paths that are underneath a dataset, but do not exist on the filesystem. Constraints: value must be a string [Default: '']
• --unavailable-path-msg message — a "message" property value to include in the annotation for paths that are underneath a dataset, but do not exist on the filesystem. Constraints: value must be a string
• --nondataset-path-status LABEL — a "status" property value to include in the annotation for paths that are not underneath any dataset. Constraints: value must be a string [Default: 'error']
• --no-parentds-discovery — Flag to disable reports of parent dataset information for any path, in particular dataset root paths. Disabling saves on command run time, if this information is not needed.
• --no-subds-discovery — Flag to disable reporting type='dataset' for subdatasets, even when they are not installed, or their mount point directory doesn't exist. Disabling saves on command run time, if this information is not needed.
• --revision-change-discovery — Flag to disable discovery of changes which were not yet committed. Disabling saves on command run time, if this information is not needed.
• --no-untracked-discovery — Flag to disable discovery of untracked changes. Disabling saves on command run time, if this information is not needed.
• --modified [MODIFIED] — comparison reference specification for modification detection. This can be (mostly) anything that git diff understands (commit, treeish, tag, etc). See the documentation of datalad diff --revision for details. Unmodified paths will not be annotated. If a requested path was not modified but some content underneath it was, then the request is replaced by the modified paths and those are annotated instead. This option can be used without an argument to test against changes that have been made, but have not yet been staged for a commit. Constraints: value must be a string, or value must be convertible to type bool
• --version — show the module and its version which provides the command

ngl bestie, those --no-*-discovery flags and --revision-change-discovery are literally just "turn the feature off to go faster" — if you don't need the info, disabling saves on command run time. slay, efficiency 💅

---

👑 AUTHORS 👑

datalad is developed by The DataLad Team and Contributors <team@datalad.org>. iconic behavior, fr fr 🫶

---

aaaand that's the whole page, bestie!! 🦋 this was datalad annotate-paths version 0.15.5, dated 2022-02-10, and yeah — that footer lives in the datalad annotate-paths(1) zone. go annotate some paths, you absolute main character 🌟💖