0
# Repository Operations
1

2
Comprehensive repository management including creation, modification, collaboration, and content operations for both authenticated and public repositories. This covers the full repository lifecycle from creation to archival.
3

4
## Capabilities
5

6
### Repository Retrieval
7

8
Access repositories by various identifiers and list repositories with flexible filtering options.
9

10
```python { .api }
11
def repository(self, owner, repository):
12
    """
13
    Retrieve a specific repository.
14
    
15
    Parameters:
16
    - owner (str, required): Repository owner username or organization
17
    - repository (str, required): Repository name
18
    
19
    Returns:
20
    Repository object with full details or None if not found
21
    """
22

23
def repository_with_id(self, number):
24
    """
25
    Retrieve repository using its unique GitHub ID.
26
    
27
    Parameters:
28
    - number (int, required): Repository's unique GitHub ID
29
    
30
    Returns:
31
    Repository object or None if not found
32
    """
33

34
def repositories(self, type=None, sort=None, direction=None, number=-1, etag=None):
35
    """
36
    List repositories for the authenticated user.
37
    
38
    Parameters:
39
    - type (str, optional): 'all', 'owner', 'public', 'private', 'member'
40
    - sort (str, optional): 'created', 'updated', 'pushed', 'full_name'
41
    - direction (str, optional): 'asc' or 'desc'
42
    - number (int): Number to return (-1 for all)
43
    - etag (str, optional): ETag from previous request
44
    
45
    Returns:
46
    Generator of ShortRepository objects
47
    """
48

49
def repositories_by(self, username, type=None, sort=None, direction=None, number=-1, etag=None):
50
    """
51
    List public repositories for a specific user.
52
    
53
    Parameters:
54
    - username (str, required): Target user's username
55
    - type (str, optional): 'all', 'owner', 'member'
56
    - sort (str, optional): 'created', 'updated', 'pushed', 'full_name'
57
    - direction (str, optional): 'asc' or 'desc'
58
    - number (int): Number to return (-1 for all)
59
    - etag (str, optional): ETag from previous request
60
    
61
    Returns:
62
    Generator of ShortRepository objects
63
    """
64

65
def all_repositories(self, number=-1, since=None, etag=None, per_page=None):
66
    """
67
    Iterate over every public repository in creation order.
68
    
69
    Parameters:
70
    - number (int): Number to return (-1 for all)
71
    - since (int, optional): Last repository ID seen for pagination
72
    - etag (str, optional): ETag from previous request
73
    - per_page (int, optional): Results per page
74
    
75
    Returns:
76
    Generator of ShortRepository objects
77
    """
78
```
79

80
### Usage Examples
81

82
```python
83
# Get specific repository
84
repo = gh.repository('octocat', 'Hello-World')
85
print(f"Repository: {repo.full_name}")
86
print(f"Description: {repo.description}")
87
print(f"Stars: {repo.stargazers_count}")
88

89
# Get repository by ID
90
repo = gh.repository_with_id(1296269)
91

92
# List authenticated user's repositories
93
for repo in gh.repositories(type='owner', sort='updated'):
94
    print(f"{repo.full_name} - {repo.updated_at}")
95

96
# List another user's repositories
97
for repo in gh.repositories_by('octocat', sort='created'):
98
    print(f"{repo.name} - Created: {repo.created_at}")
99

100
# Browse all public repositories
101
for repo in gh.all_repositories(number=100):
102
    print(f"{repo.full_name} - ID: {repo.id}")
103
```
104

105
### Repository Creation
106

107
Create new repositories with comprehensive configuration options for both personal and organizational use.
108

109
```python { .api }
110
def create_repository(self, name, description="", homepage="", private=False, has_issues=True, has_wiki=True, auto_init=False, gitignore_template="", has_projects=True):
111
    """
112
    Create a repository for the authenticated user.
113
    
114
    Parameters:
115
    - name (str, required): Repository name (max 100 characters)
116
    - description (str, optional): Repository description
117
    - homepage (str, optional): Homepage URL
118
    - private (bool): Create as private repository (default: False)
119
    - has_issues (bool): Enable issues (default: True)
120
    - has_wiki (bool): Enable wiki (default: True)
121
    - auto_init (bool): Initialize with README (default: False)
122
    - gitignore_template (str, optional): Gitignore template name
123
    - has_projects (bool): Enable projects (default: True)
124
    
125
    Returns:
126
    Repository object for the created repository
127
    """
128
```
129

130
### Usage Examples
131

132
```python
133
# Create basic repository
134
repo = gh.create_repository('my-new-project')
135

136
# Create repository with full configuration
137
repo = gh.create_repository(
138
    name='advanced-project',
139
    description='A comprehensive project with all features',
140
    homepage='https://myproject.com',
141
    private=True,
142
    has_issues=True,
143
    has_wiki=True,
144
    auto_init=True,
145
    gitignore_template='Python',
146
    has_projects=True
147
)
148

149
print(f"Created repository: {repo.html_url}")
150
```
151

152
### Repository Starring
153

154
Manage repository stars for bookmarking and discovery of interesting projects.
155

156
```python { .api }
157
def star(self, username, repo):
158
    """
159
    Star a repository.
160
    
161
    Parameters:
162
    - username (str, required): Repository owner
163
    - repo (str, required): Repository name
164
    
165
    Returns:
166
    bool: True if successful, False otherwise
167
    """
168

169
def unstar(self, username, repo):
170
    """
171
    Remove star from a repository.
172
    
173
    Parameters:
174
    - username (str, required): Repository owner
175
    - repo (str, required): Repository name
176
    
177
    Returns:
178
    bool: True if successful, False otherwise
179
    """
180

181
def is_starred(self, username, repo):
182
    """
183
    Check if the authenticated user has starred a repository.
184
    
185
    Parameters:
186
    - username (str, required): Repository owner
187
    - repo (str, required): Repository name
188
    
189
    Returns:
190
    bool: True if starred, False otherwise
191
    """
192

193
def starred(self, sort=None, direction=None, number=-1, etag=None):
194
    """
195
    Iterate over repositories starred by the authenticated user.
196
    
197
    Parameters:
198
    - sort (str, optional): 'created' or 'updated'
199
    - direction (str, optional): 'asc' or 'desc'
200
    - number (int): Number to return (-1 for all)
201
    - etag (str, optional): ETag from previous request
202
    
203
    Returns:
204
    Generator of ShortRepository objects
205
    """
206

207
def starred_by(self, username, sort=None, direction=None, number=-1, etag=None):
208
    """
209
    Iterate over repositories starred by a specific user.
210
    
211
    Parameters:
212
    - username (str, required): Target user's username
213
    - sort (str, optional): 'created' or 'updated'
214
    - direction (str, optional): 'asc' or 'desc'
215
    - number (int): Number to return (-1 for all)
216
    - etag (str, optional): ETag from previous request
217
    
218
    Returns:
219
    Generator of ShortRepository objects
220
    """
221
```
222

223
### Usage Examples
224

225
```python
226
# Star a repository
227
success = gh.star('octocat', 'Hello-World')
228
if success:
229
    print("Repository starred successfully")
230

231
# Check if repository is starred
232
if gh.is_starred('octocat', 'Hello-World'):
233
    print("Repository is starred")
234

235
# List your starred repositories
236
for repo in gh.starred(sort='updated'):
237
    print(f"Starred: {repo.full_name}")
238

239
# List repositories starred by another user
240
for repo in gh.starred_by('octocat'):
241
    print(f"{repo.full_name} - {repo.stargazers_count} stars")
242

243
# Unstar a repository
244
gh.unstar('octocat', 'Hello-World')
245
```
246

247
### Repository Subscriptions
248

249
Manage repository watching/subscription status for notifications and activity tracking.
250

251
```python { .api }
252
def subscriptions(self, number=-1, etag=None):
253
    """
254
    Iterate over repositories subscribed to by the authenticated user.
255
    
256
    Parameters:
257
    - number (int): Number to return (-1 for all)
258
    - etag (str, optional): ETag from previous request
259
    
260
    Returns:
261
    Generator of ShortRepository objects
262
    """
263

264
def subscriptions_for(self, username, number=-1, etag=None):
265
    """
266
    Iterate over repositories subscribed to by a specific user.
267
    
268
    Parameters:
269
    - username (str, required): Target user's username
270
    - number (int): Number to return (-1 for all)  
271
    - etag (str, optional): ETag from previous request
272
    
273
    Returns:
274
    Generator of ShortRepository objects
275
    """
276
```
277

278
### Usage Examples
279

280
```python
281
# List your subscribed repositories
282
for repo in gh.subscriptions():
283
    print(f"Subscribed to: {repo.full_name}")
284

285
# List repositories another user subscribes to
286
for repo in gh.subscriptions_for('octocat'):
287
    print(f"{repo.full_name}")
288
```
289

290
### Repository Invitations
291

292
Manage collaboration invitations for repository access and permissions.
293

294
```python { .api }
295
def repository_invitations(self, number=-1, etag=None):
296
    """
297
    Iterate over repository invitations for the current user.
298
    
299
    Parameters:
300
    - number (int): Number to return (-1 for all)
301
    - etag (str, optional): ETag from previous request
302
    
303
    Returns:
304
    Generator of Invitation objects
305
    """
306
```
307

308
### Usage Examples
309

310
```python
311
# List pending repository invitations
312
for invitation in gh.repository_invitations():
313
    print(f"Invited to: {invitation.repository.full_name}")
314
    print(f"Invited by: {invitation.inviter.login}")
315
    print(f"Permissions: {invitation.permissions}")
316
```
317

318
## Repository Model Classes
319

320
```python { .api }
321
class Repository:
322
    """Full repository representation with all metadata and operations"""
323
    id: int
324
    name: str
325
    full_name: str
326
    description: str
327
    private: bool
328
    fork: bool
329
    url: str
330
    html_url: str
331
    clone_url: str
332
    ssh_url: str
333
    size: int
334
    stargazers_count: int
335
    watchers_count: int
336
    forks_count: int
337
    open_issues_count: int
338
    language: str
339
    created_at: datetime
340
    updated_at: datetime
341
    pushed_at: datetime
342
    default_branch: str
343
    # ... additional repository properties and methods
344

345
class ShortRepository:
346
    """Abbreviated repository representation for list operations"""
347
    id: int
348
    name: str
349
    full_name: str
350
    private: bool
351
    # ... essential repository properties
352

353
class StarredRepository:
354
    """Repository with starring timestamp information"""
355
    starred_at: datetime
356
    # ... includes all Repository properties
357

358
class Invitation:
359
    """Repository collaboration invitation"""
360
    id: int
361
    permissions: str
362
    created_at: datetime
363
    inviter: User
364
    repository: Repository
365
    # ... additional invitation properties
366
```
367

368
## Common Repository Patterns
369

370
### Repository Discovery
371
```python
372
# Find popular repositories
373
for repo in gh.search_repositories('language:python stars:>1000').get_iterator():
374
    print(f"{repo.repository.full_name} - {repo.repository.stargazers_count} stars")
375
```
376

377
### Repository Creation and Setup
378
```python
379
# Create and configure new repository
380
repo = gh.create_repository(
381
    name='my-project',
382
    description='My awesome project',
383
    auto_init=True,
384
    gitignore_template='Python'
385
)
386

387
# Add topics/tags
388
repo.replace_topics(['python', 'api', 'github'])
389
```
390

391
### Repository Management
392
```python
393
# Get repository details
394
repo = gh.repository('owner', 'repo-name')
395

396
# Check repository properties
397
if repo.private:
398
    print("This is a private repository")
399

400
if repo.fork:
401
    print(f"This is a fork of {repo.parent.full_name}")
402

403
# Access repository statistics
404
print(f"Stars: {repo.stargazers_count}")
405
print(f"Forks: {repo.forks_count}")
406
print(f"Issues: {repo.open_issues_count}")
407
```
408

409
### Collaboration Management
410
```python
411
# List repository contributors
412
for contributor in repo.contributors():
413
    print(f"{contributor.login}: {contributor.contributions} contributions")
414

415
# List repository collaborators
416
for collaborator in repo.collaborators():
417
    print(f"{collaborator.login} - {collaborator.permissions}")
418
```