NAME

datalad create-sibling-gitlab - create dataset sibling at a GitLab site

SYNOPSIS

datalad create-sibling-gitlab [-h] [--site SITENAME] [--project NAME/LOCATION] [--layout {hierarchy|collection|flat}] [--dataset DATASET] [-r] [-R LEVELS] [-s NAME] [--existing {skip|error|reconfigure}] [--access {http|ssh|ssh+http}] [--publish-depends SIBLINGNAME] [--description DESCRIPTION] [--dryrun] [PATH ...]

DESCRIPTION

An existing GitLab project, or a project created via the GitLab web interface can be configured as a sibling with the siblings command. Alternativly, this command can create a GitLab project at any location/path a given user has appropriate permissions for. This is particulary helpful for recursive sibling creation for subdatasets. API access and authentication are implemented via python-gitlab, and all its features are supported. A particular GitLab site must be configured in a named section of a python-gitlab.cfg file (see https://python-gitlab.readthedocs.io/en/stable/cli.html#configuration for details), such as::

[mygit] url = https://git.example.com api_version = 4 private_token = abcdefghijklmnopqrst

Subsequently, this site is identified by its name ('mygit' in the example above).

(Recursive) sibling creation for all, or a selected subset of subdatasets is supported with three different project layouts (see --layout):

"hierarchy" Each dataset is placed into its own group, and the actual GitLab project for a dataset is put in a project named "_repo_" inside this group. Using this layout, arbitrarily deep hierarchies of nested datasets can be represented, while the hierarchical structure is reflected in the project path. This is the default layout, if no project path is specified. "flat" All datasets are placed in the same group. The name of a project is its relative path within the root dataset, with all path separator characters replaced by '--'. "collection" This is a hybrid layout, where the root dataset is placed in a "_repo_" project inside a group, and all nested subdatasets are represented inside the group using a "flat" layout.

GitLab cannot host dataset content. However, in combination with other data sources (and siblings), publishing a dataset to GitLab can facilitate distribution and exchange, while still allowing any dataset consumer to obtain actual data content from alternative sources.

OPTIONS

PATH

selectively create siblings for any datasets underneath a given path. By default only the root dataset is considered.

-h, --help, --help-np

show this help message. --help-np forcefully disables the use of a pager for displaying the help message

--site SITENAME

name of the GitLab site to create a sibling at. Must match an existing python-gitlab configuration section with location and authentication settings (see https://python-gitlab.readthedocs.io/en/stable/cli.html#configuration). By default the dataset configuration is consulted. Constraints: value must be NONE, or value must be a string

--project NAME/LOCATION

project path at the GitLab site. If a subdataset of the reference dataset is processed, its project path is automatically determined by the LAYOUT configuration, by default. Constraints: value must be NONE, or value must be a string

--layout {hierarchy|collection|flat}

layout of projects at the GitLab site, if a collection, or a hierarchy of datasets and subdatasets is to be created. By default the dataset configuration is consulted. Constraints: value must be one of (None, 'hierarchy', 'collection', 'flat')

--dataset DATASET, -d DATASET

reference or root dataset. If no path constraints are given, a sibling for this dataset will be created. In this and all other cases, the reference dataset is also consulted for the GitLab configuration, and desired project layout. If no dataset is given, an attempt is made to identify the dataset based on the current working directory. Constraints: Value must be a Dataset or a valid identifier of a Dataset (e.g. a path)

-r, --recursive

if set, recurse into potential subdataset.

-R LEVELS, --recursion-limit LEVELS

limit recursion into subdataset to the given number of levels. Constraints: value must be convertible to type 'int'

-s NAME, --name NAME

name to represent the GitLab sibling remote in the local dataset installation. If not specified a name is looked up in the dataset configuration, or defaults to the SITE name. Constraints: value must be a string

--existing {skip|error|reconfigure}

desired behavior when already existing or configured siblings are discovered. 'skip': ignore; 'error': fail, if access URLs differ; 'reconfigure': use the existing repository and reconfigure the local dataset to use it as a sibling. Constraints: value must be one of ('skip', 'error', 'reconfigure') [Default: 'error']

--access {http|ssh|ssh+http}

access method used for data transfer to and from the sibling. 'ssh': read and write access used the SSH protocol; 'http': read and write access use HTTP requests; 'ssh+http': read access is done via HTTP and write access performed with SSH. Dataset configuration is consulted for a default, 'http' is used otherwise. Constraints: value must be one of (None, 'http', 'ssh', 'ssh+http')

--publish-depends SIBLINGNAME

add a dependency such that the given existing sibling is always published prior to the new sibling. This equals setting a configuration item 'remote.SIBLINGNAME.datalad-publish-depends'. This option can be given more than once to configure multiple dependencies. Constraints: value must be a string

--description DESCRIPTION

brief description for the GitLab project (displayed on the site). Constraints: value must be a string

--dryrun

If this flag is set, no communication with GitLab is performed, and no repositories will be created. Instead would-be repository names and configurations are reported for all relevant datasets.

AUTHORS

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