0
# Repository Management
1

2
Comprehensive repository operations including content management, branch operations, collaboration features, webhooks, and repository settings. Supports both repository-level and Git-level operations.
3

4
## Capabilities
5

6
### Repository Access and Information
7

8
Get repository objects and access repository metadata, statistics, and properties.
9

10
```python { .api }
11
class Github:
12
    def get_repo(self, full_name_or_id: Union[str, int]) -> Repository:
13
        """
14
        Get a repository by full name or ID.
15
        
16
        Args:
17
            full_name_or_id (Union[str, int]): Repository full name (owner/repo) or ID
18
            
19
        Returns:
20
            Repository: Repository object
21
        """
22

23
class Repository:
24
    # Repository properties
25
    @property
26
    def name(self) -> str: ...
27
    @property
28
    def full_name(self) -> str: ...
29
    @property
30
    def description(self) -> str: ...
31
    @property
32
    def language(self) -> str: ...
33
    @property
34
    def private(self) -> bool: ...
35
    @property
36
    def fork(self) -> bool: ...
37
    @property
38
    def forks_count(self) -> int: ...
39
    @property
40
    def stargazers_count(self) -> int: ...
41
    @property
42
    def watchers_count(self) -> int: ...
43
    @property
44
    def size(self) -> int: ...
45
    @property
46
    def default_branch(self) -> str: ...
47
    @property
48
    def topics(self) -> list: ...
49
```
50

51
### Content Management
52

53
Read, create, update, and delete repository files and directories.
54

55
```python { .api }
56
class Repository:
57
    def get_contents(self, path: str, ref: str = None):
58
        """
59
        Get contents of a file or directory.
60
        
61
        Args:
62
            path (str): Path to file or directory
63
            ref (str, optional): Branch, tag, or commit SHA
64
            
65
        Returns:
66
            Union[ContentFile, list[ContentFile]]: File content or directory listing
67
        """
68
    
69
    def get_readme(self):
70
        """
71
        Get repository README file.
72
        
73
        Returns:
74
            ContentFile: README file content
75
        """
76
    
77
    def create_file(
78
        self,
79
        path: str,
80
        message: str,
81
        content: str,
82
        branch: str = None,
83
        committer: InputGitAuthor = None,
84
        author: InputGitAuthor = None
85
    ):
86
        """
87
        Create a new file in the repository.
88
        
89
        Args:
90
            path (str): Path where file should be created
91
            message (str): Commit message
92
            content (str): File content
93
            branch (str, optional): Branch name (defaults to default branch)
94
            committer (InputGitAuthor, optional): Committer information
95
            author (InputGitAuthor, optional): Author information
96
            
97
        Returns:
98
            dict: Created file information with commit details
99
        """
100
    
101
    def update_file(
102
        self,
103
        path: str,
104
        message: str,
105
        content: str,
106
        sha: str,
107
        branch: str = None,
108
        committer: InputGitAuthor = None,
109
        author: InputGitAuthor = None
110
    ):
111
        """
112
        Update an existing file in the repository.
113
        
114
        Args:
115
            path (str): Path to file to update
116
            message (str): Commit message
117
            content (str): New file content
118
            sha (str): Current file SHA
119
            branch (str, optional): Branch name
120
            committer (InputGitAuthor, optional): Committer information
121
            author (InputGitAuthor, optional): Author information
122
            
123
        Returns:
124
            dict: Updated file information with commit details
125
        """
126
    
127
    def delete_file(
128
        self,
129
        path: str,
130
        message: str,
131
        sha: str,
132
        branch: str = None,
133
        committer: InputGitAuthor = None,
134
        author: InputGitAuthor = None
135
    ):
136
        """
137
        Delete a file from the repository.
138
        
139
        Args:
140
            path (str): Path to file to delete
141
            message (str): Commit message
142
            sha (str): Current file SHA
143
            branch (str, optional): Branch name
144
            committer (InputGitAuthor, optional): Committer information
145
            author (InputGitAuthor, optional): Author information
146
            
147
        Returns:
148
            dict: Deletion commit details
149
        """
150
```
151

152
### Branch and Reference Management
153

154
Manage branches, tags, and Git references.
155

156
```python { .api }
157
class Repository:
158
    def get_branches(self):
159
        """
160
        Get all branches in the repository.
161
        
162
        Returns:
163
            PaginatedList[Branch]: List of branches
164
        """
165
    
166
    def get_branch(self, branch: str):
167
        """
168
        Get a specific branch.
169
        
170
        Args:
171
            branch (str): Branch name
172
            
173
        Returns:
174
            Branch: Branch object
175
        """
176
    
177
    def get_git_refs(self, subspace: str = None):
178
        """
179
        Get Git references.
180
        
181
        Args:
182
            subspace (str, optional): Reference subspace (e.g., "heads", "tags")
183
            
184
        Returns:
185
            PaginatedList[GitRef]: List of Git references
186
        """
187
    
188
    def get_git_ref(self, ref: str):
189
        """
190
        Get a specific Git reference.
191
        
192
        Args:
193
            ref (str): Reference name (e.g., "heads/main", "tags/v1.0")
194
            
195
        Returns:
196
            GitRef: Git reference object
197
        """
198
    
199
    def create_git_ref(self, ref: str, sha: str):
200
        """
201
        Create a Git reference.
202
        
203
        Args:
204
            ref (str): Reference name
205
            sha (str): SHA of the object to point to
206
            
207
        Returns:
208
            GitRef: Created Git reference
209
        """
210
    
211
    def get_tags(self):
212
        """
213
        Get repository tags.
214
        
215
        Returns:
216
            PaginatedList[Tag]: List of tags
217
        """
218
```
219

220
### Collaboration and Permissions
221

222
Manage repository collaborators, permissions, and access control.
223

224
```python { .api }
225
class Repository:
226
    def get_collaborators(self, affiliation: str = None):
227
        """
228
        Get repository collaborators.
229
        
230
        Args:
231
            affiliation (str, optional): Filter by affiliation ("outside", "direct", "all")
232
            
233
        Returns:
234
            PaginatedList[NamedUser]: List of collaborators
235
        """
236
    
237
    def add_to_collaborators(self, collaborator: str, permission: str = None):
238
        """
239
        Add a collaborator to the repository.
240
        
241
        Args:
242
            collaborator (str): Username of collaborator to add
243
            permission (str, optional): Permission level ("pull", "push", "admin")
244
        """
245
    
246
    def remove_from_collaborators(self, collaborator: str):
247
        """
248
        Remove a collaborator from the repository.
249
        
250
        Args:
251
            collaborator (str): Username of collaborator to remove
252
        """
253
    
254
    def get_permission(self, user: str):
255
        """
256
        Get user's permission level for the repository.
257
        
258
        Args:
259
            user (str): Username
260
            
261
        Returns:
262
            str: Permission level
263
        """
264
```
265

266
### Webhook Management
267

268
Create and manage repository webhooks for event notifications.
269

270
```python { .api }
271
class Repository:
272
    def get_hooks(self):
273
        """
274
        Get repository webhooks.
275
        
276
        Returns:
277
            PaginatedList[Hook]: List of webhooks
278
        """
279
    
280
    def get_hook(self, id: int):
281
        """
282
        Get a specific webhook.
283
        
284
        Args:
285
            id (int): Webhook ID
286
            
287
        Returns:
288
            Hook: Webhook object
289
        """
290
    
291
    def create_hook(
292
        self,
293
        name: str,
294
        config: dict,
295
        events: list = None,
296
        active: bool = True
297
    ):
298
        """
299
        Create a repository webhook.
300
        
301
        Args:
302
            name (str): Webhook name (usually "web")
303
            config (dict): Webhook configuration (url, content_type, etc.)
304
            events (list, optional): List of events to trigger webhook
305
            active (bool, optional): Whether webhook is active
306
            
307
        Returns:
308
            Hook: Created webhook
309
        """
310

311
class Hook:
312
    def edit(
313
        self,
314
        name: str = None,
315
        config: dict = None,
316
        events: list = None,
317
        active: bool = None
318
    ):
319
        """
320
        Edit webhook configuration.
321
        
322
        Args:
323
            name (str, optional): Webhook name
324
            config (dict, optional): Updated configuration
325
            events (list, optional): Updated events list
326
            active (bool, optional): Active status
327
        """
328
    
329
    def delete(self):
330
        """Delete the webhook."""
331
    
332
    def test(self):
333
        """
334
        Test the webhook.
335
        
336
        Returns:
337
            bool: Test result
338
        """
339
    
340
    def ping(self):
341
        """
342
        Ping the webhook.
343
        
344
        Returns:
345
            bool: Ping result
346
        """
347
```
348

349
### Repository Statistics and Traffic
350

351
Access repository statistics, traffic data, and analytics.
352

353
```python { .api }
354
class Repository:
355
    def get_stats_contributors(self):
356
        """
357
        Get contributor statistics.
358
        
359
        Returns:
360
            list[StatsContributor]: Contributor statistics
361
        """
362
    
363
    def get_stats_commit_activity(self):
364
        """
365
        Get weekly commit activity.
366
        
367
        Returns:
368
            list[StatsCommitActivity]: Weekly commit statistics
369
        """
370
    
371
    def get_stats_code_frequency(self):
372
        """
373
        Get code frequency statistics.
374
        
375
        Returns:
376
            list[StatsCodeFrequency]: Code frequency data
377
        """
378
    
379
    def get_stats_participation(self):
380
        """
381
        Get participation statistics.
382
        
383
        Returns:
384
            StatsParticipation: Participation data
385
        """
386
    
387
    def get_stats_punch_card(self):
388
        """
389
        Get punch card statistics.
390
        
391
        Returns:
392
            list[StatsPunchCard]: Punch card data
393
        """
394
    
395
    def get_clones_traffic(self, per: str = None):
396
        """
397
        Get repository clone traffic.
398
        
399
        Args:
400
            per (str, optional): Grouping ("day" or "week")
401
            
402
        Returns:
403
            Clones: Clone traffic data
404
        """
405
    
406
    def get_views_traffic(self, per: str = None):
407
        """
408
        Get repository view traffic.
409
        
410
        Args:
411
            per (str, optional): Grouping ("day" or "week")
412
            
413
        Returns:
414
            View: View traffic data
415
        """
416
```
417

418
### Repository Settings and Management
419

420
Update repository settings, manage topics, and perform repository operations.
421

422
```python { .api }
423
class Repository:
424
    def edit(
425
        self,
426
        name: str = None,
427
        description: str = None,
428
        homepage: str = None,
429
        private: bool = None,
430
        has_issues: bool = None,
431
        has_wiki: bool = None,
432
        has_downloads: bool = None,
433
        default_branch: str = None,
434
        allow_squash_merge: bool = None,
435
        allow_merge_commit: bool = None,
436
        allow_rebase_merge: bool = None,
437
        delete_branch_on_merge: bool = None
438
    ):
439
        """
440
        Edit repository settings.
441
        
442
        Args:
443
            name (str, optional): Repository name
444
            description (str, optional): Repository description
445
            homepage (str, optional): Homepage URL
446
            private (bool, optional): Repository visibility
447
            has_issues (bool, optional): Enable issues
448
            has_wiki (bool, optional): Enable wiki
449
            has_downloads (bool, optional): Enable downloads
450
            default_branch (str, optional): Default branch name
451
            allow_squash_merge (bool, optional): Allow squash merging
452
            allow_merge_commit (bool, optional): Allow merge commits
453
            allow_rebase_merge (bool, optional): Allow rebase merging
454
            delete_branch_on_merge (bool, optional): Delete head branch after merge
455
        """
456
    
457
    def replace_topics(self, topics: list):
458
        """
459
        Replace repository topics.
460
        
461
        Args:
462
            topics (list): List of topic strings
463
        """
464
    
465
    def delete(self):
466
        """Delete the repository."""
467
    
468
    def create_fork(self, organization: str = None):
469
        """
470
        Fork the repository.
471
        
472
        Args:
473
            organization (str, optional): Organization to fork to
474
            
475
        Returns:
476
            Repository: Forked repository
477
        """
478
```
479

480
## Content File Operations
481

482
```python { .api }
483
class ContentFile:
484
    @property
485
    def name(self) -> str: ...
486
    @property
487
    def path(self) -> str: ...
488
    @property
489
    def sha(self) -> str: ...
490
    @property
491
    def size(self) -> int: ...
492
    @property
493
    def content(self) -> str: ...
494
    @property
495
    def decoded_content(self) -> bytes: ...
496
    @property
497
    def encoding(self) -> str: ...
498
    @property
499
    def type(self) -> str: ...  # "file" or "dir"
500
    
501
    def update(self, message: str, content: str, branch: str = None):
502
        """
503
        Update this file's content.
504
        
505
        Args:
506
            message (str): Commit message
507
            content (str): New content
508
            branch (str, optional): Branch name
509
        """
510
    
511
    def delete(self, message: str, branch: str = None):
512
        """
513
        Delete this file.
514
        
515
        Args:
516
            message (str): Commit message
517
            branch (str, optional): Branch name
518
        """
519
```
520

521
## Usage Examples
522

523
### Basic Repository Operations
524

525
```python
526
from github import Github, Auth
527

528
g = Github(auth=Auth.Token("your_token"))
529

530
# Get repository
531
repo = g.get_repo("owner/repository")
532
print(f"Repository: {repo.full_name}")
533
print(f"Description: {repo.description}")
534
print(f"Language: {repo.language}")
535
print(f"Stars: {repo.stargazers_count}")
536

537
# Get repository contents
538
contents = repo.get_contents("")  # Root directory
539
for content in contents:
540
    print(f"- {content.name} ({content.type})")
541

542
# Get specific file
543
readme = repo.get_readme()
544
print(f"README content: {readme.decoded_content.decode('utf-8')}")
545
```
546

547
### File Management
548

549
```python
550
from github import Github, Auth, InputGitAuthor
551

552
g = Github(auth=Auth.Token("your_token"))
553
repo = g.get_repo("owner/repository")
554

555
# Create a new file
556
author = InputGitAuthor("Your Name", "your.email@example.com")
557
result = repo.create_file(
558
    path="new-file.txt",
559
    message="Add new file",
560
    content="Hello, World!",
561
    author=author
562
)
563
print(f"Created file with SHA: {result['commit'].sha}")
564

565
# Update the file
566
file_content = repo.get_contents("new-file.txt")
567
repo.update_file(
568
    path="new-file.txt",
569
    message="Update file content",
570
    content="Hello, Updated World!",
571
    sha=file_content.sha,
572
    author=author
573
)
574
```
575

576
### Branch Management
577

578
```python
579
# List all branches
580
for branch in repo.get_branches():
581
    print(f"Branch: {branch.name}")
582

583
# Get specific branch
584
main_branch = repo.get_branch("main")
585
print(f"Main branch commit: {main_branch.commit.sha}")
586

587
# Create new branch
588
repo.create_git_ref(
589
    ref="refs/heads/new-feature",
590
    sha=main_branch.commit.sha
591
)
592
```