oracular (1) datalad-create-sibling-gitlab.1.gz

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>.