DATALAD-DIFF(1)

💅 datalad diff — like, the manual page, but make it make sense

okay so you found yourself in the datalad diff(1) section of the General Commands Manual and honestly? slay, you're in the right place bestie. this one's about spotting what changed between two states of a dataset (or a whole dataset hierarchy, we love a recursive moment) 🦋

---

✨ NAME ✨

datalad diff — report differences between two states of a dataset (hierarchy). that's the whole vibe. comparing eras, if you will 👑

---

✨ SYNOPSIS ✨

datalad diff [-h] [-f REVISION] [-t REVISION] [-d DATASET] [--annex
       [{basic|availability|all}]] [--untracked {no|normal|all}] [-r]
       [-R LEVELS] [--version] [PATH ...]

---

✨ DESCRIPTION ✨

so the two states you're comparing? you hand them over via the --from and --to options. these state identifiers get evaluated in the context of the dataset — the one you specify, or the one that gets detected for you. ngl, that detection is doing a lot of heavy lifting 🫶

and if you're doing a recursive report on a dataset hierarchy? then for any subdataset, the corresponding state pairs get figured out from the subdataset record in the respective superdataset. only changes recorded in a subdataset between these two states get reported, and so on down the line. it's giving nesting dolls 💅

any paths you toss in as extra arguments? those constrain the difference report. and just like Git's diff, it will not error out when you specify a path that doesn't exist on the filesystem. iconic behavior honestly, no notes ✨

reports are very similar to those of the STATUS command — the distinguished content types and states are identical. same energy, different command 💖

🌸 Examples

show unsaved changes in a dataset:

% datalad diff

compare a previous dataset state identified by shasum against the current worktree:

% datalad diff --from <SHASUM>

compare two branches against each other:

% datalad diff --from branch1 --to branch2

show unsaved changes in the dataset and potential subdatasets:

% datalad diff -r

show unsaved changes made to a particular file:

% datalad diff <path/to/file>

---

✨ OPTIONS ✨

• PATH — path to constrain the report to. Constraints: value must be a string or value must be NONE. (yeah, a path that's also allowed to be nothing, we contain multitudes 🎀)
• -h, --help, --help-np — show this help message. --help-np forcefully disables the use of a pager for displaying the help message. no pager, no scrolling saga, just the facts bestie 😌
• -f REVISION, --from REVISION — original state to compare to, as given by any identifier that Git understands. Constraints: value must be a string [Default: 'HEAD']. so your baseline, your "before" pic, and it defaults to 'HEAD' in case you're feeling spontaneous 💅
• -t REVISION, --to REVISION — state to compare against the original state, as given by any identifier that Git understands. If none is specified, the state of the working tree will be compared. Constraints: value must be a string or value must be NONE. your "after" pic — and if you ghost this option entirely, the working tree steps in 🦋
• -d DATASET, --dataset DATASET — specify the dataset to query. If no dataset is given, an attempt is made to identify the dataset based on the current working directory. Constraints: Value must be a Dataset or a valid identifier of a Dataset (e.g. a path) or value must be NONE. literally just point at your dataset, or let it figure itself out 🧚
• --annex [{basic|availability|all}] — switch whether to include information on the annex content of individual files in the status report, such as recorded file size. By default no annex information is reported (faster). Three report modes are available: basic information like file size and key name ('basic'); additionally test whether file content is present in the local annex ('availability'; requires one or two additional file system stat calls, but does not call git-annex), this will add the result properties 'has_content' (boolean flag) and 'objloc' (absolute path to an existing annex object file); or 'all' which will report all available information (presently identical to 'availability'). The 'basic' mode will be assumed when this option is given, but no mode is specified. Constraints: value must be one of ('basic', 'availability', 'all'). so many modes, so little time — default is no annex info because speed is the moment 👑
• --untracked {no|normal|all} — if and how untracked content is reported when comparing a revision to the state of the working tree. 'no': no untracked content is reported; 'normal': untracked files and entire untracked directories are reported as such; 'all': report individual files even in fully untracked directories. Constraints: value must be one of ('no', 'normal', 'all') [Default: 'normal']. choose your fighter 🥊
• -r, --recursive — if set, recurse into potential subdatasets. go deeper. always deeper. 🌀
• -R LEVELS, --recursion-limit LEVELS — limit recursion into subdatasets to the given number of levels. Constraints: value must be convertible to type 'int' or value must be NONE. keeping the recursion from going feral, love that for us 🎀
• --version — show the module and its version which provides the command. the "who even are you" option, respectfully 💖

---

✨ AUTHORS ✨

datalad is developed by The DataLad Team and Contributors <team@datalad.org>. absolute icons, the whole team 🫶

---

okay that's the whole page bestie, no cap, every flag accounted for. this fine piece of documentation is datalad diff version 1.1.5, dated 2025-06-15, and it says datalad diff(1) down at the bottom too — so now you know exactly which era of the manual you're living in 🌈✨💜