1datalad create-sibling-githubG(e1n)eral Commands Madnautaallad create-sibling-github(1)
2
6 datalad create-sibling-github - create dataset sibling on GitHub.org
7 (or an enterprise deployment).
8
10 datalad create-sibling-github [-h] [--dataset DATASET] [-r] [-R LEVELS]
11 [-s NAME] [--existing {skip|error|reconfigure|replace}]
12 [--github-login TOKEN] [--credential NAME] [--github-
13 organization NAME] [--access-protocol {https|ssh|https-ssh}]
14 [--publish-depends SIBLINGNAME] [--private]
15 [--description DESCRIPTION] [--dryrun] [--dry-run] [--api URL]
16 [--version] [<org-name>/]<repo-(base)name>
17
21 GitHub is a popular commercial solution for code hosting and collabora‐
22 tive development. GitHub cannot host dataset content (but see LFS,
23 http://handbook.datalad.org/r.html?LFS). However, in combination with
24 other data sources and siblings, publishing a dataset to GitHub can fa‐
25 cilitate distribution and exchange, while still allowing any dataset
26 consumer to obtain actual data content from alternative sources.
27 In order to be able to use this command, a personal access token has to
29 be generated on the platform (Account->Settings->Developer Set‐
30 tings->Personal access tokens->Generate new token).
31 This command can be configured with "datalad.create-sibling-ghlike.ex‐
33 tra-remote-settings.NETLOC.KEY=VALUE" in order to add any local KEY =
34 VALUE configuration to the created sibling in the local `.git/config`
35 file. NETLOC is the domain of the Github instance to apply the configu‐
36 ration for. This leads to a behavior that is equivalent to calling
37 datalad's ``siblings('configure', ...)``||``siblings configure`` com‐
38 mand with the respective KEY-VALUE pair after creating the sibling.
39 The configuration, like any other, could be set at user- or system lev‐
40 el, so users do not need to add this configuration to every sibling
41 created with the service at NETLOC themselves.
42 Changed in version 0.16
44 The API has been aligned with the some ``create-sibling-...``
45 commands of other GitHub-like services, such as GOGS, GIN,
46 GitTea.
47 Deprecated in version 0.16
49 The ``--dryrun`` option will be removed in a future release, use
50 the renamed ``--dry-run`` option instead.
51 The ``--github-login`` option will be removed in a future
52 release, use the ``--credential`` option instead.
53 The ``--github-organization`` option will be
54 removed in a future release, prefix the reposity name with ``<org>/``
55 instead.
56 Examples
58 Use a new sibling on GIN as a common data source that is auto- avail‐
59 able when cloning from GitHub::
60 % datalad create-sibling-gin myrepo -s gin
62 # the sibling on GitHub will be used for collaborative work
64 % datalad create-sibling-github myrepo -s github
65 # register the storage of the public GIN repo as a data source
67 % datalad siblings configure -s gin --as-common-datasrc gin-storage
68 # announce its availability on github
70 % datalad push --to github
71
73 [<org-name>/]<repo-(base)name>
74 repository name, optionally including an '<organization>/' pre‐
75 fix if the repository shall not reside under a user's namespace.
76 When operating recursively, a suffix will be appended to this
77 name for each subdataset. Constraints: value must be a string
78 -h, --help, --help-np
81 show this help message. --help-np forcefully disables the use of
82 a pager for displaying the help message
83 --dataset DATASET, -d DATASET
85 dataset to create the publication target for. If not given, an
86 attempt is made to identify the dataset based on the current
87 working directory. Constraints: Value must be a Dataset or a
88 valid identifier of a Dataset (e.g. a path) or value must be
89 NONE
90 -r, --recursive
92 if set, recurse into potential subdatasets.
93 -R LEVELS, --recursion-limit LEVELS
95 limit recursion into subdatasets to the given number of levels.
96 Constraints: value must be convertible to type 'int' or value
97 must be NONE
98 -s NAME, --name NAME
100 name of the sibling in the local dataset installation (remote
101 name). Constraints: value must be a string or value must be NONE
102 [Default: 'github']
103 --existing {skip|error|reconfigure|replace}
105 behavior when already existing or configured siblings are dis‐
106 covered: skip the dataset ('skip'), update the configuration
107 ('reconfigure'), or fail ('error'). DEPRECATED DANGER ZONE: With
108 'replace', an existing repository will be irreversibly removed,
109 re-initialized, and the sibling (re-)configured (thus implies
110 'reconfigure'). REPLACE could lead to data loss! In interactive
111 sessions a confirmation prompt is shown, an exception is raised
112 in non-interactive sessions. The 'replace' mode will be removed
113 in a future release. Constraints: value must be one of ('skip',
114 'error', 'reconfigure', 'replace') [Default: 'error']
115 --github-login TOKEN
117 Deprecated, use the credential parameter instead. If given must
118 be a personal access token. Constraints: value must be a string
119 or value must be NONE
120 --credential NAME
122 name of the credential providing a personal access token to be
123 used for authorization. The token can be supplied via configura‐
124 tion setting 'datalad.credential.<name>.token', or environment
125 variable DATALAD_CREDENTIAL_<NAME>_TOKEN, or will be queried
126 from the active credential store using the provided name. If
127 none is provided, the host-part of the API URL is used as a name
128 (e.g. 'https://api.github.com' -> 'api.github.com'). Con‐
129 straints: value must be a string or value must be NONE
130 --github-organization NAME
132 Deprecated, prepend a repo name with an '<orgname>/' prefix in‐
133 stead. Constraints: value must be a string or value must be NONE
134 --access-protocol {https|ssh|https-ssh}
136 access protocol/URL to configure for the sibling. With 'https-
137 ssh' SSH will be used for write access, whereas HTTPS is used
138 for read access. Constraints: value must be one of ('https',
139 'ssh', 'https-ssh') [Default: 'https']
140 --publish-depends SIBLINGNAME
142 add a dependency such that the given existing sibling is always
143 published prior to the new sibling. This equals setting a con‐
144 figuration item 'remote.SIBLINGNAME.datalad-publish-depends'.
145 This option can be given more than once to configure multiple
146 dependencies. Constraints: value must be a string or value must
147 be NONE
148 --private
150 if set, create a private repository.
151 --description DESCRIPTION
153 Brief description, displayed on the project's page. Constraints:
154 value must be a string or value must be NONE
155 --dryrun
157 Deprecated. Use the renamed ``--dry-run`` parameter.
158 --dry-run
160 if set, no repository will be created, only tests for sibling
161 name collisions will be performed, and would-be repository names
162 are reported for all relevant datasets.
163 --api URL
165 URL of the GitHub instance API. Constraints: value must be a
166 string or value must be NONE [Default: 'https://api.github.com']
167 --version
169 show the module and its version which provides the command
170
172 datalad is developed by The DataLad Team and Contributors <team@datal‐
173 ad.org>.
174datalad create-sibling-github 0.19.23023-08-11 datalad create-sibling-github(1)