NAME

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

SYNOPSIS

       datalad   create-sibling-gitlab   [-h]   [--site   SITENAME]   [--project   NAME/LOCATION]
              [--layout  {collection|flat}]  [--dataset  DATASET]  [-r]  [-R  LEVELS]  [-s  NAME]
              [--existing  {skip|error|reconfigure}]  [--access  {http|ssh|ssh+http}] [--publish-
              depends SIBLINGNAME] [--description DESCRIPTION] [--dryrun] [--dry-run] [--version]
              [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. Alternatively, this command can  create
       a  GitLab  project at any location/path a given user has appropriate permissions for. This
       is particularly 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-usage.html#configuration-file-format
       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 two different project layouts (see --layout):

       "flat" All datasets are placed as GitLab projects in the same group. The project  name  of
       the    top-level    dataset   follows   the   configured   datalad.gitlab-SITENAME-project
       configuration. The project names of contained subdatasets extend the configured name  with
       the  subdatasets'  s  relative  path  within  the  root  dataset,  with all path separator
       characters replaced by '-'. This  path  separator  is  configurable  (see  Configuration).
       "collection"   A   new   group  is  created  for  the  dataset  hierarchy,  following  the
       datalad.gitlab-SITENAME-project configuration. The root dataset is placed in  a  "project"
       project  inside  this  group,  and all nested subdatasets are represented inside the group
       using a "flat" layout. The root datasets project name is configurable (see Configuration).

       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
       Many  configuration  switches  and  options for GitLab sibling creation can be provided as
       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.
         The root-level group ("location") needs to be created beforehand via
         GitLab's web interface.  "datalad.gitlab-default-projectname"
         The collection layout publishes (sub)datasets as projects
         with a custom name. The default name "project" can be overridden with
         this configuration.  "datalad.gitlab-default-pathseparator"
         The flat and collection layout represent subdatasets with project names
         that correspond to their path within the superdataset, with the regular  path  separator
       replaced
         with a "-": superdataset-subdataset. This configuration can be used to override
         this default separator.

       This            command            can            be            configured            with
       "datalad.create-sibling-ghlike.extra-remote-settings.NETLOC.KEY=VALUE" in order to add any
       local  KEY  =  VALUE configuration to the created sibling in the local `.git/config` file.
       NETLOC is the domain of the Gitlab instance to apply the configuration for.  This leads to
       a   behavior   that   is   equivalent   to   calling   datalad's   ``siblings('configure',
       ...)``||``siblings configure`` command with the respective KEY-VALUE pair  after  creating
       the sibling.  The configuration, like any other, could be set at user- or system level, so
       users do not need to add this configuration to every sibling created with the  service  at
       NETLOC themselves.

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-usage.html#configuration).    By
              default the dataset configuration is consulted. Constraints: value must be NONE  or
              value must be a string

       --project NAME/LOCATION
              project  name/location 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. Users need to create the root-level GitLab group (NAME)
              via the webinterface before running the command. Constraints: value must be NONE or
              value must be a string

       --layout {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 ('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) or value must be NONE

       -r, --recursive
              if set, recurse into potential subdatasets.

       -R LEVELS, --recursion-limit LEVELS
              limit recursion into subdatasets to the given number of levels. Constraints:  value
              must be convertible to type 'int' or value must be NONE

       -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 or value must be NONE

       --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 ('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  or
              value must be NONE

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

       --dryrun
              Deprecated. Use the renamed ``--dry-run`` parameter.

       --dry-run
              if set, no repository will be created, only  tests  for  name  collisions  will  be
              performed, and would-be repository names are reported for all relevant datasets.

       --version
              show the module and its version which provides the command

AUTHORS

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