1datalad create-sibling(1) General Commands Manual datalad create-sibling(1)
2
6 datalad create-sibling - create a dataset sibling on a UNIX-like Shell
7 (local or SSH)-accessible machine
8
10 datalad create-sibling [-h] [-s [NAME]] [--target-dir PATH] [--target-
11 url URL] [--target-pushurl URL] [--dataset DATASET] [-r]
12 [-R LEVELS] [--existing MODE]
13 [--shared {false|true|umask|group|all|world|everybody|0xxx}]
14 [--group GROUP] [--ui {false|true|html_filename}] [--as-common-
15 datasrc NAME] [--publish-by-default REFSPEC] [--publish-
16 depends SIBLINGNAME] [--annex-wanted EXPR] [--annex-group EXPR]
17 [--annex-groupwanted EXPR] [--inherit] [--since SINCE]
18 [--version] [SSHURL]
19
23 Given a local dataset, and a path or SSH login information this command
24 creates a remote dataset repository and configures it as a dataset sib‐
25 ling to be used as a publication target (see PUBLISH command).
26 Various properties of the remote sibling can be configured (e.g. name
28 location on the server, read and write access URLs, and access permis‐
29 sions.
30 Optionally, a basic web-viewer for DataLad datasets can be installed at
32 the remote location.
33 This command supports recursive processing of dataset hierarchies, cre‐
35 ating a remote sibling for each dataset in the hierarchy. By default,
36 remote siblings are created in hierarchical structure that reflects the
37 organization on the local file system. However, a simple templating
38 mechanism is provided to produce a flat list of datasets (see --tar‐
39 get-dir).
40
42 SSHURL Login information for the target server. This can be given as a
43 URL (ssh://host/path), SSH-style (user@host:path) or just a lo‐
44 cal path. Unless overridden, this also serves the future
45 dataset's access URL and path on the server. Constraints: value
46 must be a string
47 -h, --help, --help-np
50 show this help message. --help-np forcefully disables the use of
51 a pager for displaying the help message
52 -s [NAME], --name [NAME]
54 sibling name to create for this publication target. If RECURSIVE
55 is set, the same name will be used to label all the subdatasets'
56 siblings. When creating a target dataset fails, no sibling is
57 added. Constraints: value must be a string or value must be NONE
58 --target-dir PATH
60 path to the directory *on the server* where the dataset shall be
61 created. By default this is set to the URL (or local path) spec‐
62 ified via SSHURL. If a relative path is provided here, it is in‐
63 terpreted as being relative to the user's home directory on the
64 server (or relative to SSHURL, when that is a local path). Addi‐
65 tional features are relevant for recursive processing of
66 datasets with subdatasets. By default, the local dataset struc‐
67 ture is replicated on the server. However, it is possible to
68 provide a template for generating different target directory
69 names for all (sub)datasets. Templates can contain certain
70 placeholder that are substituted for each (sub)dataset. For ex‐
71 ample: "/mydirectory/dataset%RELNAME". Supported placeholders:
72 %RELNAME - the name of the datasets, with any slashes replaced
73 by dashes. Constraints: value must be a string or value must be
74 NONE
75 --target-url URL
77 "public" access URL of the to-be-created target dataset(s) (de‐
78 fault: SSHURL). Accessibility of this URL determines the access
79 permissions of potential consumers of the dataset. As with `tar‐
80 get_dir`, templates (same set of placeholders) are supported.
81 Also, if specified, it is provided as the annex description.
82 Constraints: value must be a string or value must be NONE
83 --target-pushurl URL
85 In case the TARGET_URL cannot be used to publish to the dataset,
86 this option specifies an alternative URL for this purpose. As
87 with `target_url`, templates (same set of placeholders) are sup‐
88 ported. Constraints: value must be a string or value must be
89 NONE
90 --dataset DATASET, -d DATASET
92 specify the dataset to create the publication target for. If no
93 dataset is given, an attempt is made to identify the dataset
94 based on the current working directory. Constraints: Value must
95 be a Dataset or a valid identifier of a Dataset (e.g. a path) or
96 value must be NONE
97 -r, --recursive
99 if set, recurse into potential subdatasets.
100 -R LEVELS, --recursion-limit LEVELS
102 limit recursion into subdatasets to the given number of levels.
103 Constraints: value must be convertible to type 'int' or value
104 must be NONE
105 --existing MODE
107 action to perform, if a sibling is already configured under the
108 given name and/or a target (non-empty) directory already exists.
109 In this case, a dataset can be skipped ('skip'), the sibling
110 configuration be updated ('reconfigure'), or process interrupts
111 with error ('error'). DANGER ZONE: If 'replace' is used, an ex‐
112 isting target directory will be forcefully removed, re-initial‐
113 ized, and the sibling (re-)configured (thus implies 'reconfig‐
114 ure'). REPLACE could lead to data loss, so use with care. To
115 minimize possibility of data loss, in interactive mode DataLad
116 will ask for confirmation, but it would raise an exception in
117 non-interactive mode. Constraints: value must be one of ('skip',
118 'error', 'reconfigure', 'replace') [Default: 'error']
119 --shared {false|true|umask|group|all|world|everybody|0xxx}
121 if given, configures the access permissions on the server for
122 multi-users (this could include access by a webserver!). Possi‐
123 ble values for this option are identical to those of `git init
124 --shared` and are described in its documentation. Constraints:
125 value must be a string or value must be convertible to type bool
126 or value must be NONE
127 --group GROUP
129 Filesystem group for the repository. Specifying the group is
130 particularly important when --shared=group. Constraints: value
131 must be a string or value must be NONE
132 --ui {false|true|html_filename}
134 publish a web interface for the dataset with an optional user-
135 specified name for the html at publication target. defaults to
136 `index.html` at dataset root. Constraints: value must be con‐
137 vertible to type bool or value must be a string [Default: False]
138 --as-common-datasrc NAME
140 configure the created sibling as a common data source of the
141 dataset that can be automatically used by all consumers of the
142 dataset (technical: git-annex auto-enabled special remote).
143 --publish-by-default REFSPEC
145 add a refspec to be published to this sibling by default if
146 nothing specified. Constraints: value must be a string or value
147 must be NONE
148 --publish-depends SIBLINGNAME
150 add a dependency such that the given existing sibling is always
151 published prior to the new sibling. This equals setting a con‐
152 figuration item 'remote.SIBLINGNAME.datalad-publish-depends'.
153 This option can be given more than once to configure multiple
154 dependencies. Constraints: value must be a string or value must
155 be NONE
156 --annex-wanted EXPR
158 expression to specify 'wanted' content for the repository/sib‐
159 ling. See https://git-annex.branchable.com/git-annex-wanted/ for
160 more information. Constraints: value must be a string or value
161 must be NONE
162 --annex-group EXPR
164 expression to specify a group for the repository. See
165 https://git-annex.branchable.com/git-annex-group/ for more in‐
166 formation. Constraints: value must be a string or value must be
167 NONE
168 --annex-groupwanted EXPR
170 expression for the groupwanted. Makes sense only if --annex-
171 wanted="groupwanted" and annex-group is given too. See
172 https://git-annex.branchable.com/git-annex-groupwanted/ for more
173 information. Constraints: value must be a string or value must
174 be NONE
175 --inherit
177 if sibling is missing, inherit settings (git config, git annex
178 wanted/group/groupwanted) from its super-dataset.
179 --since SINCE
181 limit processing to subdatasets that have been changed since a
182 given state (by tag, branch, commit, etc). This can be used to
183 create siblings for recently added subdatasets. If '^' is given,
184 the last state of the current branch at the sibling is taken as
185 a starting point. Constraints: value must be a string or value
186 must be NONE
187 --version
189 show the module and its version which provides the command
190
192 datalad is developed by The DataLad Team and Contributors <team@datal‐
193 ad.org>.
194datalad create-sibling 0.19.3 2023-08-11 datalad create-sibling(1)