DATALAD-COPY-FILE(1)

✨ datalad copy-file — the datalad manual, bestie edition ✨

okay so this is datalad copy-file(1) from the General Commands Manual and honestly? it's giving "cp but with ✨lore✨". let's get into it 💅

🌸 NAME 🌸

datalad copy-file — copy files and their availability metadata from one dataset to another. yes bestie, the vibes travel with the file 🫶

---

🎀 SYNOPSIS 🎀

datalad copy-file [-h] [-d DATASET] [--recursive] [--target-dir DIRECTORY] [--specs-from SOURCE] [-m MESSAGE] [--version] [PATH ...]

🦋 DESCRIPTION 🦋

so like, the whole difference between this and a plain system copy command? here we ALSO copy the extra content availability info — think registered URLs and stuff like that — over to the target dataset. and on top of that, any git-annex special remote configurations that the source dataset potentially needs get detected in the source dataset and then applied to the target dataset in an analogous fashion. icon behavior, no cap 👑

and here's the part that lowkey blows my mind: you can copy a file for which no content is available locally — you literally just copy the required metadata about content identity and availability. the file's soul, not the file. the way that works is so main character energy fr 😭

NOTE — At the moment, only URLs for the special remotes 'web' (git-annex built-in) and 'datalad' are recognized and transferred. so don't come for me about other remotes, that's just where we're at 🙈

the interface is modeled after the POSIX 'cp' command, but with one extra little trick for specifying what to copy where: --specs-from lets the caller flexibly input source-destination path pairs. flexible! we love a flexible queen 💖

this command can copy files out of and into a hierarchy of nested datasets. and here's the plot twist: unlike with other DataLad commands, the --recursive switch does NOT enable recursion into subdatasets. instead it's analogous to the POSIX 'cp' command switch — it enables subdirectory recursion, regardless of dataset boundaries. also, it is not necessary to enable recursion in order to save changes made to nested target subdatasets. so like, don't overthink it bestie ✨

🌈 Examples 🌈

copy a file into a dataset 'myds' using a path and a target directory specification, and save its addition to 'myds':

% datalad copy-file path/to/myfile -d path/to/myds

copy a file to a dataset 'myds' and save it under a new name by providing two paths:

% datalad copy-file path/to/myfile path/to/myds/new -d path/to/myds

copy a file into a dataset without saving it (chaotic, love that for you):

% datalad copy-file path/to/myfile -t path/to/myds

copy a directory and its subdirectories into a dataset 'myds' and save the addition in 'myds':

% datalad copy-file path/to/dir -r -d path/to/myds

copy files using a path and optionally target specification from a file:

% datalad copy-file -d path/to/myds --specs-from specfile

read a specification from stdin and pipe the output of a find command into the copy-file command (pipes?? we stan 🧚):

% find <expr> | datalad copy-file -d path/to/myds --specs-from -

---

💜 OPTIONS 💜

• PATH — paths to copy (and possibly a target path to copy to). Constraints: value must be a string or value must be NONE.
• -h, --help, --help-np — show this help message. --help-np forcefully disables the use of a pager for displaying the help message. (forcefully! 💀)
• -d DATASET, --dataset DATASET — root dataset to save after copy operations are completed. All destination paths must be within this dataset, or its subdatasets. If no dataset is given, dataset modifications will be left unsaved. Constraints: Value must be a Dataset or a valid identifier of a Dataset (e.g. a path) or value must be NONE.
• --recursive, -r — copy directories recursively.
• --target-dir DIRECTORY, -t DIRECTORY — copy all source files into this DIRECTORY. This value is overridden by any explicit destination path provided via --specs-from. When not given, this defaults to the path of the dataset specified via --dataset. Constraints: value must be a string or value must be NONE.
• --specs-from SOURCE — read list of source (and destination) path names from a given file, or stdin (with '-'). Each line defines either a source path, or a source/destination path pair (separated by a null byte character).
• -m MESSAGE, --message MESSAGE — a description of the state or the changes made to a dataset. Constraints: value must be a string or value must be NONE.
• --version — show the module and its version which provides the command.

---

👑 AUTHORS 👑

datalad is developed by The DataLad Team and Contributors <team@datalad.org>.

---

🌸 and that's the whole page bestie!! 💖 this was datalad copy-file version 1.1.5, dated 2025-06-15 — go forth and copy responsibly, ilysm 🫶✨🎀