1datalad copy-file(1)        General Commands Manual       datalad copy-file(1)
2
3
4

NAME

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

SYNOPSIS

10       datalad  copy-file   [-h]   [-d   DATASET]   [--recursive]   [--target-
11              dir  DIRECTORY]  [--specs-from  SOURCE] [-m MESSAGE] [--version]
12              [PATH ...]
13
14
15

DESCRIPTION

17       The difference to a system copy command is that here additional content
18       availability  information,  such  as registered URLs, is also copied to
19       the target dataset. Moreover, potentially  required  git-annex  special
20       remote  configurations are detected in a source dataset and are applied
21       to a target dataset in an analogous fashion. It is possible to  copy  a
22       file for which no content is available locally, by just copying the re‐
23       quired metadata on content identity and availability.
24
25       NOTE   At the moment, only URLs for the special remotes 'web'  (git-an‐
26              nex built-in) and 'datalad' are recognized and transferred.
27
28       The interface is modeled after the POSIX 'cp' command, but with one ad‐
29       ditional way to specify what to copy  where:  --specs-from  allows  the
30       caller to flexibly input source-destination path pairs.
31
32       This  command  can  copy  files  out  of and into a hierarchy of nested
33       datasets. Unlike with other DataLad  command,  the  --recursive  switch
34       does  not  enable  recursion  into subdatasets, but is analogous to the
35       POSIX 'cp' command switch and enables subdirectory  recursion,  regard‐
36       less  of dataset boundaries. It is not necessary to enable recursion in
37       order to save changes made to nested target subdatasets.
38
39   Examples
40       Copy a file into a dataset 'myds' using a path and a  target  directory
41       specification, and save its addition to 'myds'::
42
43        % datalad copy-file path/to/myfile -d path/to/myds
44
45       Copy a file to a dataset 'myds' and save it under a new name by provid‐
46       ing two paths::
47
48        % datalad copy-file path/to/myfile path/to/myds/new -d path/to/myds
49
50       Copy a file into a dataset without saving it::
51
52        % datalad copy-file path/to/myfile -t path/to/myds
53
54       Copy a directory and its subdirectories into a dataset 'myds' and  save
55       the addition in 'myds'::
56
57        % datalad copy-file path/to/dir -r -d path/to/myds
58
59       Copy  files  using  a  path  and optionally target specification from a
60       file::
61
62        % datalad copy-file -d path/to/myds --specs-from specfile
63
64       Read a specification from stdin and pipe the output of a  find  command
65       into the copy-file command::
66
67        % find <expr> | datalad copy-file -d path/to/myds --specs-from -
68
69

OPTIONS

71       PATH   paths  to  copy  (and  possibly  a target path to copy to). Con‐
72              straints: value must be a string or value must be NONE
73
74
75       -h, --help, --help-np
76              show this help message. --help-np forcefully disables the use of
77              a pager for displaying the help message
78
79       -d DATASET, --dataset DATASET
80              root  dataset  to  save after copy operations are completed. All
81              destination paths must be  within  this  dataset,  or  its  sub‐
82              datasets.  If no dataset is given, dataset modifications will be
83              left unsaved. Constraints: Value must be a Dataset  or  a  valid
84              identifier of a Dataset (e.g. a path) or value must be NONE
85
86       --recursive, -r
87              copy directories recursively.
88
89       --target-dir DIRECTORY, -t DIRECTORY
90              copy  all  source files into this DIRECTORY. This value is over‐
91              ridden by any explicit destination path  provided  via  --specs-
92              from.  When  not given, this defaults to the path of the dataset
93              specified via --dataset. Constraints: value must be a string  or
94              value must be NONE
95
96       --specs-from SOURCE
97              read  list  of  source (and destination) path names from a given
98              file, or stdin (with '-'). Each line  defines  either  a  source
99              path,  or  a  source/destination  path pair (separated by a null
100              byte character).
101
102       -m MESSAGE, --message MESSAGE
103              a description of the state or the changes  made  to  a  dataset.
104              Constraints: value must be a string or value must be NONE
105
106       --version
107              show the module and its version which provides the command
108

AUTHORS

110        datalad is developed by The DataLad Team and Contributors <team@datal‐
111       ad.org>.
112
113
114
115datalad copy-file 0.19.3          2023-08-11              datalad copy-file(1)