datalad create-sibling-github - create dataset sibling on
GitHub.
datalad create-sibling-github [-h]
[--dataset DATASET] [-r] [-R LEVELS] [-s NAME]
[--existing MODE] [--github-login NAME]
[--github-organization NAME] [--access-protocol {https|ssh}]
[--publish-depends SIBLINGNAME] [--private] [--dryrun] REPONAME
An existing GitHub project, or a project created via the GitHub
website can be configured as a sibling with the siblings command.
Alternatively, this command can create a repository under a user's GitHub
account, or any organization a user is a member of (given appropriate
permissions). This is particularly helpful for recursive sibling creation
for subdatasets. In such a case, a dataset hierarchy is represented as a
flat list of GitHub repositories.
GitHub cannot host dataset content (but LFS special remote could
be used, http://handbook.datalad.org/r.html?LFS). However, in combination
with other data sources (and siblings), publishing a dataset to GitHub can
facilitate distribution and exchange, while still allowing any dataset
consumer to obtain actual data content from alternative sources.
For GitHub authentication a personal access token is needed. Such
a token can be generated by visiting https://github.com/settings/tokens or
navigating via GitHub Web UI through: Settings -> Developer settings
-> Personal access tokens. We will first consult Git configuration
*hub.oauthtoken* for tokens possibly available there, and then from the
system credential store.
If you provide --github-login NAME, we will consider only tokens
associated with that GitHub login from *hub.oauthtoken*, and store/check the
token in credential store as associated with that specific login name.
- REPONAME
- GitHub repository name. When operating recursively, a suffix will be
appended to this name for each subdataset. Constraints: value must be a
string
- -h, --help,
--help-np
- show this help message. --help-np forcefully disables the use of a pager
for displaying the help message
- --dataset
DATASET, -d DATASET
- specify the dataset to create the publication target for. 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 GitHub repository in the local dataset installation.
Constraints: value must be a string [Default: 'github']
- --existing
MODE
- desired behavior when already existing or configured siblings are
discovered. In this case, a dataset can be skipped ('skip'), the sibling
configuration be updated ('reconfigure'), or process interrupts with error
('error'). DANGER ZONE: If 'replace' is used, an existing github
repository will be irreversibly removed, re-initialized, and the sibling
(re-)configured (thus implies 'reconfigure'). REPLACE could lead to data
loss, so use with care. To minimize possibility of data loss, in
interactive mode DataLad will ask for confirmation, but it would raise an
exception in non-interactive mode. Constraints: value must be one of
('skip', 'error', 'reconfigure', 'replace') [Default: 'error']
- --github-login
NAME
- GitHub user name or access token. Constraints: value must be a string
- --github-organization
NAME
- If provided, the repository will be created under this GitHub
organization. The respective GitHub user needs appropriate permissions.
Constraints: value must be a string
- --access-protocol
{https|ssh}
- Which access protocol/URL to configure for the sibling. Constraints: value
must be one of ('https', 'ssh') [Default: 'https']
- --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
- --private
- If this flag is set, the repository created on github will be marked as
private and only visible to those granted access or by membership of a
team/organization/etc.
- --dryrun
- If this flag is set, no communication with GitHub is performed, and no
repositories will be created. Instead would-be repository names are
reported for all relevant datasets.
datalad is developed by The DataLad Team and Contributors
<team@datalad.org>.