0
# Repository Operations
1
2
Complete repository management including creation, forking, starring, watching, branch operations, collaborator management, and repository settings.
3
4
## Capabilities
5
6
### Repository Access & Information
7
8
Core repository operations for accessing and retrieving repository information.
9
10
```python { .api }
11
class GitHub:
12
def repository(self, owner, repository):
13
"""
14
Get a repository by owner and name.
15
16
Args:
17
owner (str): Repository owner username or organization
18
repository (str): Repository name
19
20
Returns:
21
Repository: Repository object or None if not found
22
"""
23
24
def repositories(self, type=None, sort="created", direction="desc"):
25
"""
26
List the authenticated user's repositories.
27
28
Args:
29
type (str, optional): Repository type ('all', 'owner', 'public', 'private', 'member')
30
sort (str): Sort by ('created', 'updated', 'pushed', 'full_name')
31
direction (str): Sort direction ('asc', 'desc')
32
33
Returns:
34
iterator: Iterator of Repository objects
35
"""
36
37
def repositories_by(self, username, type="owner", sort="created", direction="desc"):
38
"""
39
List a user's public repositories.
40
41
Args:
42
username (str): GitHub username
43
type (str): Repository type ('all', 'owner', 'member')
44
sort (str): Sort by ('created', 'updated', 'pushed', 'full_name')
45
direction (str): Sort direction ('asc', 'desc')
46
47
Returns:
48
iterator: Iterator of Repository objects
49
"""
50
51
def all_repositories(self, since=None):
52
"""
53
List all public repositories on GitHub.
54
55
Args:
56
since (int, optional): Repository ID to start from
57
58
Returns:
59
iterator: Iterator of Repository objects
60
"""
61
```
62
63
**Usage Examples:**
64
65
```python
66
import github3
67
68
gh = github3.login(token='your_token')
69
70
# Get a specific repository
71
repo = gh.repository('octocat', 'Hello-World')
72
print(f"Repository: {repo.full_name}")
73
print(f"Description: {repo.description}")
74
print(f"Stars: {repo.stargazers_count}")
75
print(f"Language: {repo.language}")
76
77
# List authenticated user's repositories
78
for repo in gh.repositories():
79
print(f"{repo.full_name} - {repo.description}")
80
81
# List user's public repositories
82
for repo in gh.repositories_by('octocat'):
83
print(f"{repo.name} - Created: {repo.created_at}")
84
```
85
86
### Repository Creation & Management
87
88
Operations for creating, updating, and managing repositories.
89
90
```python { .api }
91
class GitHub:
92
def create_repository(self, name, description="", homepage="", private=False,
93
has_issues=True, has_projects=True, has_wiki=True,
94
team_id=None, auto_init=False, gitignore_template="",
95
license_template="", allow_squash_merge=True,
96
allow_merge_commit=True, allow_rebase_merge=True):
97
"""
98
Create a new repository for the authenticated user.
99
100
Args:
101
name (str): Repository name
102
description (str): Repository description
103
homepage (str): Homepage URL
104
private (bool): Whether repository is private
105
has_issues (bool): Enable issue tracker
106
has_projects (bool): Enable projects
107
has_wiki (bool): Enable wiki
108
team_id (int, optional): Team ID for organization repos
109
auto_init (bool): Initialize with README
110
gitignore_template (str): .gitignore template name
111
license_template (str): License template name
112
allow_squash_merge (bool): Allow squash merging
113
allow_merge_commit (bool): Allow merge commits
114
allow_rebase_merge (bool): Allow rebase merging
115
116
Returns:
117
Repository: Created repository object
118
"""
119
120
```
121
122
**Usage Examples:**
123
124
```python
125
# Create a personal repository
126
repo = gh.create_repository(
127
name='my-new-repo',
128
description='A test repository',
129
private=True,
130
auto_init=True,
131
gitignore_template='Python',
132
license_template='mit'
133
)
134
print(f"Created: {repo.html_url}")
135
136
# Create organization repository (via Organization object)
137
org = gh.organization('my-org')
138
org_repo = org.create_repository(
139
'team-project',
140
description='Team collaboration project',
141
has_projects=True
142
)
143
```
144
145
### Repository Starring & Watching
146
147
Operations for starring and watching repositories.
148
149
```python { .api }
150
class GitHub:
151
def starred(self):
152
"""
153
List repositories starred by the authenticated user.
154
155
Returns:
156
iterator: Iterator of StarredRepository objects
157
"""
158
159
def starred_by(self, username):
160
"""
161
List repositories starred by a user.
162
163
Args:
164
username (str): GitHub username
165
166
Returns:
167
iterator: Iterator of Repository objects
168
"""
169
170
def star(self, owner, repo):
171
"""
172
Star a repository.
173
174
Args:
175
owner (str): Repository owner
176
repo (str): Repository name
177
178
Returns:
179
bool: True if successful
180
"""
181
182
def unstar(self, owner, repo):
183
"""
184
Unstar a repository.
185
186
Args:
187
owner (str): Repository owner
188
repo (str): Repository name
189
190
Returns:
191
bool: True if successful
192
"""
193
194
def subscriptions_for(self, username):
195
"""
196
List repositories watched by a user.
197
198
Args:
199
username (str): GitHub username
200
201
Returns:
202
iterator: Iterator of Repository objects
203
"""
204
```
205
206
**Usage Examples:**
207
208
```python
209
# List starred repositories
210
for repo in gh.starred():
211
print(f"⭐ {repo.repository.full_name}")
212
213
# Star/unstar repositories
214
gh.star('octocat', 'Hello-World')
215
gh.unstar('octocat', 'Spoon-Knife')
216
217
# List watched repositories
218
for repo in gh.subscriptions_for('octocat'):
219
print(f"👁 {repo.full_name}")
220
```
221
222
### Forking Operations
223
224
Repository forking operations.
225
226
```python { .api }
227
class Repository:
228
def create_fork(self, organization=None):
229
"""
230
Create a fork of this repository.
231
232
Args:
233
organization (str, optional): Organization to fork to
234
235
Returns:
236
Repository: Forked repository object
237
"""
238
239
def forks(self, sort="newest"):
240
"""
241
List forks of this repository.
242
243
Args:
244
sort (str): Sort by ('newest', 'oldest', 'stargazers')
245
246
Returns:
247
iterator: Iterator of Repository objects
248
"""
249
```
250
251
### Branch Management
252
253
Operations for managing repository branches and references.
254
255
```python { .api }
256
class Repository:
257
def branches(self, protected=None):
258
"""
259
List repository branches.
260
261
Args:
262
protected (bool, optional): Filter by protection status
263
264
Returns:
265
iterator: Iterator of Branch objects
266
"""
267
268
def branch(self, name):
269
"""
270
Get a specific branch.
271
272
Args:
273
name (str): Branch name
274
275
Returns:
276
Branch: Branch object or None
277
"""
278
279
def create_branch_ref(self, ref, sha):
280
"""
281
Create a new branch reference.
282
283
Args:
284
ref (str): Reference name (e.g., 'refs/heads/new-branch')
285
sha (str): SHA of commit to point to
286
287
Returns:
288
Reference: Created reference object
289
"""
290
291
def tag(self, sha, tag, message, obj_type, tagger, lightweight=False):
292
"""
293
Create a tag.
294
295
Args:
296
sha (str): SHA of object to tag
297
tag (str): Tag name
298
message (str): Tag message
299
obj_type (str): Object type ('commit', 'tree', 'blob')
300
tagger (dict): Tagger information
301
lightweight (bool): Create lightweight tag
302
303
Returns:
304
Tag: Created tag object
305
"""
306
```
307
308
### Repository Settings & Configuration
309
310
Managing repository settings, webhooks, and configuration.
311
312
```python { .api }
313
class Repository:
314
def edit(self, name=None, description=None, homepage=None, private=None,
315
has_issues=None, has_projects=None, has_wiki=None, **kwargs):
316
"""
317
Edit repository settings.
318
319
Args:
320
name (str, optional): New repository name
321
description (str, optional): New description
322
homepage (str, optional): Homepage URL
323
private (bool, optional): Privacy setting
324
has_issues (bool, optional): Enable issues
325
has_projects (bool, optional): Enable projects
326
has_wiki (bool, optional): Enable wiki
327
**kwargs: Additional repository settings
328
329
Returns:
330
bool: True if successful
331
"""
332
333
def delete(self):
334
"""
335
Delete this repository.
336
337
Returns:
338
bool: True if successful
339
"""
340
341
def create_hook(self, name, config, events=["push"], active=True):
342
"""
343
Create a webhook.
344
345
Args:
346
name (str): Hook name (e.g., 'web')
347
config (dict): Hook configuration
348
events (list): List of events to trigger on
349
active (bool): Whether hook is active
350
351
Returns:
352
Hook: Created webhook object
353
"""
354
355
def hooks(self):
356
"""
357
List repository webhooks.
358
359
Returns:
360
iterator: Iterator of Hook objects
361
"""
362
```
363
364
### Collaborator Management
365
366
Managing repository collaborators and permissions.
367
368
```python { .api }
369
class Repository:
370
def collaborators(self, affiliation="all"):
371
"""
372
List repository collaborators.
373
374
Args:
375
affiliation (str): Affiliation type ('outside', 'direct', 'all')
376
377
Returns:
378
iterator: Iterator of Collaborator objects
379
"""
380
381
def is_collaborator(self, username):
382
"""
383
Check if user is a collaborator.
384
385
Args:
386
username (str): GitHub username
387
388
Returns:
389
bool: True if user is collaborator
390
"""
391
392
def add_collaborator(self, username, permission="push"):
393
"""
394
Add a collaborator to the repository.
395
396
Args:
397
username (str): GitHub username
398
permission (str): Permission level ('pull', 'push', 'admin')
399
400
Returns:
401
bool: True if successful
402
"""
403
404
def remove_collaborator(self, username):
405
"""
406
Remove a collaborator from the repository.
407
408
Args:
409
username (str): GitHub username
410
411
Returns:
412
bool: True if successful
413
"""
414
```
415
416
### Repository Content Operations
417
418
Managing repository content including files and directories.
419
420
```python { .api }
421
class Repository:
422
def contents(self, path="", ref=None):
423
"""
424
Get repository contents at a path.
425
426
Args:
427
path (str): File or directory path
428
ref (str, optional): Branch, tag, or commit SHA
429
430
Returns:
431
Contents or list: Contents object(s)
432
"""
433
434
def create_file(self, path, message, content, branch=None, committer=None, author=None):
435
"""
436
Create a new file in the repository.
437
438
Args:
439
path (str): File path
440
message (str): Commit message
441
content (str or bytes): File content
442
branch (str, optional): Branch name
443
committer (dict, optional): Committer information
444
author (dict, optional): Author information
445
446
Returns:
447
dict: Created file information
448
"""
449
450
def update_file(self, path, message, content, sha, branch=None, committer=None, author=None):
451
"""
452
Update an existing file in the repository.
453
454
Args:
455
path (str): File path
456
message (str): Commit message
457
content (str or bytes): New file content
458
sha (str): Current file SHA
459
branch (str, optional): Branch name
460
committer (dict, optional): Committer information
461
author (dict, optional): Author information
462
463
Returns:
464
dict: Updated file information
465
"""
466
467
def delete_file(self, path, message, sha, branch=None, committer=None, author=None):
468
"""
469
Delete a file from the repository.
470
471
Args:
472
path (str): File path
473
message (str): Commit message
474
sha (str): Current file SHA
475
branch (str, optional): Branch name
476
committer (dict, optional): Committer information
477
author (dict, optional): Author information
478
479
Returns:
480
dict: Deletion information
481
"""
482
```
483
484
## Repository Model Classes
485
486
```python { .api }
487
class Repository:
488
"""Full repository object with all data and methods."""
489
id: int
490
name: str
491
full_name: str
492
owner: 'User'
493
private: bool
494
html_url: str
495
description: str
496
fork: bool
497
homepage: str
498
language: str
499
forks_count: int
500
stargazers_count: int
501
watchers_count: int
502
size: int
503
default_branch: str
504
open_issues_count: int
505
has_issues: bool
506
has_projects: bool
507
has_wiki: bool
508
has_pages: bool
509
has_downloads: bool
510
archived: bool
511
disabled: bool
512
pushed_at: str
513
created_at: str
514
updated_at: str
515
clone_url: str
516
ssh_url: str
517
git_url: str
518
519
def edit(self, **kwargs): ...
520
def delete(self): ...
521
def create_fork(self, organization=None): ...
522
def branches(self): ...
523
def collaborators(self): ...
524
def create_hook(self, name, config, events=["push"]): ...
525
526
class ShortRepository:
527
"""Abbreviated repository object for listings."""
528
id: int
529
name: str
530
full_name: str
531
owner: 'ShortUser'
532
private: bool
533
description: str
534
535
class StarredRepository:
536
"""Repository with starring information."""
537
starred_at: str
538
repository: 'Repository'
539
540
class Branch:
541
"""Repository branch."""
542
name: str
543
commit: 'ShortCommit'
544
protected: bool
545
546
class Contents:
547
"""File or directory contents."""
548
type: str # 'file' or 'dir'
549
size: int
550
name: str
551
path: str
552
content: str
553
encoding: str
554
sha: str
555
url: str
556
git_url: str
557
html_url: str
558
download_url: str
559
560
class Hook:
561
"""Repository webhook."""
562
id: int
563
name: str
564
active: bool
565
events: list
566
config: dict
567
updated_at: str
568
created_at: str
569
```