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 analo‐
       gous 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.

       NOTE   At the moment, only URLs for the special remotes 'web' (git-annex built-in) and 'datalad' are rec‐
              ognized 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 nec‐
       essary 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  addi‐
       tion 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

       PATH   paths to copy (and possibly a target path to copy to). Constraints: value must be a string or val‐
              ue 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

       -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 un‐
              saved. 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  charac‐
              ter).

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

datalad copy-file 1.1.5                            2025-03-03                               datalad copy-file(1)