1datalad create-sibling-gitlabG(e1n)eral Commands Madnautaallad create-sibling-gitlab(1)
2
6 datalad create-sibling-gitlab - create dataset sibling at a GitLab site
7
9 datalad create-sibling-gitlab [-h] [--site SITENAME] [--project
10 NAME/LOCATION] [--layout {collection|flat}] [--dataset DATASET]
11 [-r] [-R LEVELS] [-s NAME] [--existing {skip|error|reconfigure}]
12 [--access {http|ssh|ssh+http}] [--publish-depends SIBLINGNAME]
13 [--description DESCRIPTION] [--dryrun] [--dry-run] [--version]
14 [PATH ...]
15
19 An existing GitLab project, or a project created via the GitLab web in‐
20 terface can be configured as a sibling with the siblings command. Al‐
21 ternatively, this command can create a GitLab project at any loca‐
22 tion/path a given user has appropriate permissions for. This is partic‐
23 ularly helpful for recursive sibling creation for subdatasets. API ac‐
24 cess and authentication are implemented via python-gitlab, and all its
25 features are supported. A particular GitLab site must be configured in
26 a named section of a python-gitlab.cfg file (see https://python-git‐
27 lab.readthedocs.io/en/stable/cli-usage.html#configuration-file-format
28 for details), such as::
29 [mygit] url = https://git.example.com api_version = 4 private_token =
31 abcdefghijklmnopqrst
32 Subsequently, this site is identified by its name ('mygit' in the exam‐
34 ple above).
35 (Recursive) sibling creation for all, or a selected subset of sub‐
37 datasets is supported with two different project layouts (see --lay‐
38 out):
39 "flat" All datasets are placed as GitLab projects in the same group.
41 The project name of the top-level dataset follows the configured datal‐
42 ad.gitlab-SITENAME-project configuration. The project names of con‐
43 tained subdatasets extend the configured name with the subdatasets' s
44 relative path within the root dataset, with all path separator charac‐
45 ters replaced by '-'. This path separator is configurable (see Configu‐
46 ration). "collection" A new group is created for the dataset hierar‐
47 chy, following the datalad.gitlab-SITENAME-project configuration. The
48 root dataset is placed in a "project" project inside this group, and
49 all nested subdatasets are represented inside the group using a "flat"
50 layout. The root datasets project name is configurable (see Configura‐
51 tion).
52 GitLab cannot host dataset content. However, in combination with other
54 data sources (and siblings), publishing a dataset to GitLab can facili‐
55 tate distribution and exchange, while still allowing any dataset con‐
56 sumer to obtain actual data content from alternative sources.
57 Configuration
59 Many configuration switches and options for GitLab sibling creation can
60 be provided as arguments to the command. However, it is also possible
61 to specify a particular setup in a dataset's configuration. This is
62 particularly important when managing large collections of datasets.
63 Configuration options are:
64 "datalad.gitlab-default-site"
66 Name of the default GitLab site (see --site) "datalad.gitlab-SITE‐
67 NAME-siblingname"
68 Name of the sibling configured for the local dataset that points
69 to the GitLab instance SITENAME (see --name) "datalad.gitlab-SITE‐
70 NAME-layout"
71 Project layout used at the GitLab instance SITENAME (see --layout)
72 "datalad.gitlab-SITENAME-access"
73 Access method used for the GitLab instance SITENAME (see --access)
74 "datalad.gitlab-SITENAME-project"
75 Project "location/path" used for a datasets at GitLab instance
76 SITENAME (see --project). Configuring this is useful for deriving
77 project paths for subdatasets, relative to superdataset.
78 The root-level group ("location") needs to be created beforehand via
79 GitLab's web interface. "datalad.gitlab-default-projectname"
80 The collection layout publishes (sub)datasets as projects
81 with a custom name. The default name "project" can be overridden with
82 this configuration. "datalad.gitlab-default-pathseparator"
83 The flat and collection layout represent subdatasets with project
84 names
85 that correspond to their path within the superdataset, with the regu‐
86 lar path separator replaced
87 with a "-": superdataset-subdataset. This configuration can be used
88 to override
89 this default separator.
90 This command can be configured with "datalad.create-sibling-ghlike.ex‐
92 tra-remote-settings.NETLOC.KEY=VALUE" in order to add any local KEY =
93 VALUE configuration to the created sibling in the local `.git/config`
94 file. NETLOC is the domain of the Gitlab instance to apply the configu‐
95 ration for. This leads to a behavior that is equivalent to calling
96 datalad's ``siblings('configure', ...)``||``siblings configure`` com‐
97 mand with the respective KEY-VALUE pair after creating the sibling.
98 The configuration, like any other, could be set at user- or system lev‐
99 el, so users do not need to add this configuration to every sibling
100 created with the service at NETLOC themselves.
101
103 PATH selectively create siblings for any datasets underneath a given
104 path. By default only the root dataset is considered.
105 -h, --help, --help-np
108 show this help message. --help-np forcefully disables the use of
109 a pager for displaying the help message
110 --site SITENAME
112 name of the GitLab site to create a sibling at. Must match an
113 existing python-gitlab configuration section with location and
114 authentication settings (see https://python-gitlab.readthedo‐
115 cs.io/en/stable/cli-usage.html#configuration). By default the
116 dataset configuration is consulted. Constraints: value must be
117 NONE or value must be a string
118 --project NAME/LOCATION
120 project name/location at the GitLab site. If a subdataset of the
121 reference dataset is processed, its project path is automatical‐
122 ly determined by the LAYOUT configuration, by default. Users
123 need to create the root-level GitLab group (NAME) via the webin‐
124 terface before running the command. Constraints: value must be
125 NONE or value must be a string
126 --layout {collection|flat}
128 layout of projects at the GitLab site, if a collection, or a hi‐
129 erarchy of datasets and subdatasets is to be created. By default
130 the dataset configuration is consulted. Constraints: value must
131 be one of ('collection', 'flat')
132 --dataset DATASET, -d DATASET
134 reference or root dataset. If no path constraints are given, a
135 sibling for this dataset will be created. In this and all other
136 cases, the reference dataset is also consulted for the GitLab
137 configuration, and desired project layout. If no dataset is giv‐
138 en, an attempt is made to identify the dataset based on the cur‐
139 rent working directory. Constraints: Value must be a Dataset or
140 a valid identifier of a Dataset (e.g. a path) or value must be
141 NONE
142 -r, --recursive
144 if set, recurse into potential subdatasets.
145 -R LEVELS, --recursion-limit LEVELS
147 limit recursion into subdatasets to the given number of levels.
148 Constraints: value must be convertible to type 'int' or value
149 must be NONE
150 -s NAME, --name NAME
152 name to represent the GitLab sibling remote in the local dataset
153 installation. If not specified a name is looked up in the
154 dataset configuration, or defaults to the SITE name. Con‐
155 straints: value must be a string or value must be NONE
156 --existing {skip|error|reconfigure}
158 desired behavior when already existing or configured siblings
159 are discovered. 'skip': ignore; 'error': fail, if access URLs
160 differ; 'reconfigure': use the existing repository and reconfig‐
161 ure the local dataset to use it as a sibling. Constraints: value
162 must be one of ('skip', 'error', 'reconfigure') [Default: 'er‐
163 ror']
164 --access {http|ssh|ssh+http}
166 access method used for data transfer to and from the sibling.
167 'ssh': read and write access used the SSH protocol; 'http': read
168 and write access use HTTP requests; 'ssh+http': read access is
169 done via HTTP and write access performed with SSH. Dataset con‐
170 figuration is consulted for a default, 'http' is used otherwise.
171 Constraints: value must be one of ('http', 'ssh', 'ssh+http')
172 --publish-depends SIBLINGNAME
174 add a dependency such that the given existing sibling is always
175 published prior to the new sibling. This equals setting a con‐
176 figuration item 'remote.SIBLINGNAME.datalad-publish-depends'.
177 This option can be given more than once to configure multiple
178 dependencies. Constraints: value must be a string or value must
179 be NONE
180 --description DESCRIPTION
182 brief description for the GitLab project (displayed on the
183 site). Constraints: value must be a string or value must be NONE
184 --dryrun
186 Deprecated. Use the renamed ``--dry-run`` parameter.
187 --dry-run
189 if set, no repository will be created, only tests for name col‐
190 lisions will be performed, and would-be repository names are re‐
191 ported for all relevant datasets.
192 --version
194 show the module and its version which provides the command
195
197 datalad is developed by The DataLad Team and Contributors <team@datal‐
198 ad.org>.
199datalad create-sibling-gitlab 0.19.23023-08-11 datalad create-sibling-gitlab(1)