Scroll to navigation

datalad copy-file(1) General Commands Manual datalad copy-file(1)

NAME

datalad copy-file - copy files and their availability metadata from one dataset to another.

SYNOPSIS

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

DESCRIPTION

The difference to a system copy command is that here additional content availability information, such as registered URLs, is also copied to the target dataset. Moreover, potentially required git-annex special remote configurations are detected in a source dataset and are applied to a target dataset in an analogous fashion. It is possible to copy a file for which no content is available locally, by just copying the required metadata on content identity and availability.

At the moment, only URLs for the special remotes 'web' (git-annex built-in) and 'datalad' are recognized and transferred.

The interface is modeled after the POSIX 'cp' command, but with one additional way to specify what to copy where: --specs-from allows the caller to flexibly input source-destination path pairs.

This command can copy files out of and into a hierarchy of nested datasets. Unlike with other DataLad command, the --recursive switch does not enable recursion into subdatasets, but is analogous to the POSIX 'cp' command switch and enables subdirectory recursion, regardless of dataset boundaries. It is not necessary to enable recursion in order to save changes made to nested target subdatasets.

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


% 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::


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

OPTIONS

paths to copy (and possibly a target path to copy to). Constraints: value must be a string or value must be NONE

show this help message. --help-np forcefully disables the use of a pager for displaying the help message
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
copy directories recursively.
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
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).
a description of the state or the changes made to a dataset. Constraints: value must be a string or value must be NONE
show the module and its version which provides the command

AUTHORS


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

2024-08-31 datalad copy-file 1.1.3