focal (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  {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 [PATH ...]]

DESCRIPTION

       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.

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