datalad.api.create_sibling_gitlab

datalad.api.create_sibling_gitlab(path=None, site=None, project=None, layout=None, dataset=None, recursive=False, recursion_limit=None, name=None, existing='error', access=None, publish_depends=None, description=None, dryrun=False)

Create dataset sibling at a GitLab site

A Git repository can be created at any location/path a given user has appropriate permissions for. 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. Three different project layouts for nested datasets are supported (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.

Configuration

All configuration switches and options for GitLab sibling creation can be provided arguments to the command. However, it is also possible to specify a particular setup in a dataset’s configuration. This is particularly important when managing large collections of datasets. Configuration options are:

“datalad.gitlab-default-site”
Name of the default GitLab site (see –site)
“datalad.gitlab-SITENAME-siblingname”
Name of the sibling configured for the local dataset that points to the GitLab instance SITENAME (see –name)
“datalad.gitlab-SITENAME-layout”
Project layout used at the GitLab instance SITENAME (see –layout)
“datalad.gitlab-SITENAME-access”
Access method used for the GitLab instance SITENAME (see –access)
“datalad.gitlab-SITENAME-project”
Project location/path used for a datasets at GitLab instance SITENAME (see –project). Configuring this is useful for deriving project paths for subdatasets, relative to superdataset.

Examples

Parameters:
  • path – selectively create siblings for any datasets underneath a given path. By default only the root dataset is considered. [Default: None]
  • site (None or str, optional) – 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. [Default: None]
  • project (None or str, optional) – 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. [Default: None]
  • layout ({None, 'hierarchy', 'collection', 'flat'}, optional) – 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. [Default: None]
  • dataset (Dataset or None, optional) – 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. [Default: None]
  • recursive (bool, optional) – if set, recurse into potential subdataset. [Default: False]
  • recursion_limit (int or None, optional) – limit recursion into subdataset to the given number of levels. [Default: None]
  • name (str or None, optional) – 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. [Default: None]
  • existing ({'skip', 'error', 'reconfigure'}, optional) – 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. [Default: ‘error’]
  • access ({None, 'http', 'ssh', 'ssh+http'}, optional) – 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. [Default: None]
  • publish_depends (list of str or None, optional) – 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’. Multiple dependencies can be given as a list of sibling names. [Default: None]
  • description (str or None, optional) – brief description for the GitLab project (displayed on the site). [Default: None]
  • dryrun (bool, optional) – 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. [Default: False]
  • on_failure ({'ignore', 'continue', 'stop'}, optional) – behavior to perform on failure: ‘ignore’ any failure is reported, but does not cause an exception; ‘continue’ if any failure occurs an exception will be raised at the end, but processing other actions will continue for as long as possible; ‘stop’: processing will stop on first failure and an exception is raised. A failure is any result with status ‘impossible’ or ‘error’. Raised exception is an IncompleteResultsError that carries the result dictionaries of the failures in its failed attribute. [Default: ‘continue’]
  • proc_post – Like proc_pre, but procedures are executed after the main command has finished. [Default: None]
  • proc_pre – DataLad procedure to run prior to the main command. The argument a list of lists with procedure names and optional arguments. Procedures are called in the order their are given in this list. It is important to provide the respective target dataset to run a procedure on as the dataset argument of the main command. [Default: None]
  • result_filter (callable or None, optional) – if given, each to-be-returned status dictionary is passed to this callable, and is only returned if the callable’s return value does not evaluate to False or a ValueError exception is raised. If the given callable supports **kwargs it will additionally be passed the keyword arguments of the original API call. [Default: None]
  • result_renderer ({'default', 'json', 'json_pp', 'tailored'} or None, optional) – format of return value rendering on stdout. [Default: None]
  • result_xfm ({'datasets', 'successdatasets-or-none', 'paths', 'relpaths', 'metadata'} or callable or None, optional) – if given, each to-be-returned result status dictionary is passed to this callable, and its return value becomes the result instead. This is different from result_filter, as it can perform arbitrary transformation of the result value. This is mostly useful for top- level command invocations that need to provide the results in a particular format. Instead of a callable, a label for a pre-crafted result transformation can be given. [Default: None]
  • return_type ({'generator', 'list', 'item-or-list'}, optional) – return value behavior switch. If ‘item-or-list’ a single value is returned instead of a one-item return value list, or a list in case of multiple return values. None is return in case of an empty list. [Default: ‘list’]