0
# Git Operations
1

2
Low-level Git operations including commit creation, tree manipulation, blob handling, references, and tags. Provides direct access to Git objects and operations for advanced repository management.
3

4
## Capabilities
5

6
### Git Commit Operations
7

8
Create and manage Git commits with full control over commit metadata and tree structure.
9

10
```python { .api }
11
class Repository:
12
    def get_commits(
13
        self,
14
        sha: str = None,
15
        path: str = None,
16
        author: str = None,
17
        since: datetime = None,
18
        until: datetime = None
19
    ):
20
        """
21
        Get repository commits.
22
        
23
        Args:
24
            sha (str, optional): SHA or branch to start listing from
25
            path (str, optional): Filter commits touching this path
26
            author (str, optional): Filter by author
27
            since (datetime, optional): Only commits after this date
28
            until (datetime, optional): Only commits before this date
29
            
30
        Returns:
31
            PaginatedList[Commit]: List of commits
32
        """
33
    
34
    def get_commit(self, sha: str):
35
        """
36
        Get a specific commit.
37
        
38
        Args:
39
            sha (str): Commit SHA
40
            
41
        Returns:
42
            Commit: Commit object
43
        """
44
    
45
    def create_git_commit(
46
        self,
47
        message: str,
48
        tree: Union[GitTree, str],
49
        parents: list,
50
        author: InputGitAuthor = None,
51
        committer: InputGitAuthor = None
52
    ):
53
        """
54
        Create a Git commit object.
55
        
56
        Args:
57
            message (str): Commit message
58
            tree (Union[GitTree, str]): Tree object or SHA
59
            parents (list): List of parent commit SHAs
60
            author (InputGitAuthor, optional): Commit author
61
            committer (InputGitAuthor, optional): Commit committer
62
            
63
        Returns:
64
            GitCommit: Created commit object
65
        """
66
    
67
    def compare(self, base: str, head: str):
68
        """
69
        Compare two commits, branches, or tags.
70
        
71
        Args:
72
            base (str): Base commit, branch, or tag
73
            head (str): Head commit, branch, or tag
74
            
75
        Returns:
76
            Comparison: Comparison object with diff information
77
        """
78

79
class Commit:
80
    @property
81
    def sha(self) -> str: ...
82
    @property
83
    def commit(self) -> GitCommit: ...
84
    @property
85
    def author(self) -> NamedUser: ...
86
    @property
87
    def committer(self) -> NamedUser: ...
88
    @property
89
    def parents(self) -> list: ...
90
    @property
91
    def files(self) -> list: ...
92
    @property
93
    def stats(self) -> CommitStats: ...
94
    @property
95
    def html_url(self) -> str: ...
96
    
97
    def get_comments(self):
98
        """
99
        Get commit comments.
100
        
101
        Returns:
102
            PaginatedList[CommitComment]: List of comments
103
        """
104
    
105
    def create_comment(self, body: str, line: int = None, path: str = None):
106
        """
107
        Create a commit comment.
108
        
109
        Args:
110
            body (str): Comment body
111
            line (int, optional): Line number to comment on
112
            path (str, optional): File path to comment on
113
            
114
        Returns:
115
            CommitComment: Created comment
116
        """
117
    
118
    def get_statuses(self):
119
        """
120
        Get commit statuses.
121
        
122
        Returns:
123
            PaginatedList[CommitStatus]: List of statuses
124
        """
125
    
126
    def create_status(
127
        self,
128
        state: str,
129
        target_url: str = None,
130
        description: str = None,
131
        context: str = None
132
    ):
133
        """
134
        Create a commit status.
135
        
136
        Args:
137
            state (str): Status state ("pending", "success", "error", "failure")
138
            target_url (str, optional): URL for status details
139
            description (str, optional): Status description
140
            context (str, optional): Status context identifier
141
            
142
        Returns:
143
            CommitStatus: Created status
144
        """
145

146
class GitCommit:
147
    @property
148
    def sha(self) -> str: ...
149
    @property
150
    def message(self) -> str: ...
151
    @property
152
    def author(self) -> GitAuthor: ...
153
    @property
154
    def committer(self) -> GitAuthor: ...
155
    @property
156
    def tree(self) -> GitTree: ...
157
    @property
158
    def parents(self) -> list: ...
159
    @property
160
    def verification(self) -> GitCommitVerification: ...
161
```
162

163
### Git Tree Operations
164

165
Manipulate Git tree objects for advanced file system operations.
166

167
```python { .api }
168
class Repository:
169
    def get_git_tree(self, sha: str, recursive: bool = False):
170
        """
171
        Get a Git tree object.
172
        
173
        Args:
174
            sha (str): Tree SHA
175
            recursive (bool, optional): Recursively fetch sub-trees
176
            
177
        Returns:
178
            GitTree: Tree object
179
        """
180
    
181
    def create_git_tree(self, tree: list, base_tree: str = None):
182
        """
183
        Create a Git tree object.  
184
        
185
        Args:
186
            tree (list): List of InputGitTreeElement objects
187
            base_tree (str, optional): Base tree SHA to build upon
188
            
189
        Returns:
190
            GitTree: Created tree object
191
        """
192

193
class GitTree:
194
    @property
195
    def sha(self) -> str: ...
196
    @property
197
    def tree(self) -> list: ...  # List of GitTreeElement objects
198
    @property
199
    def truncated(self) -> bool: ...
200

201
class GitTreeElement:
202
    @property
203
    def path(self) -> str: ...
204
    @property
205
    def mode(self) -> str: ...
206
    @property
207
    def type(self) -> str: ...  # "blob", "tree", "commit"
208
    @property
209
    def size(self) -> int: ...
210
    @property
211
    def sha(self) -> str: ...
212
    @property
213
    def url(self) -> str: ...
214

215
class InputGitTreeElement:
216
    def __init__(
217
        self,
218
        path: str,
219
        mode: str,
220
        type: str,
221
        content: str = None,
222
        sha: str = None
223
    ):
224
        """
225
        Input element for creating Git trees.
226
        
227
        Args:
228
            path (str): File path
229
            mode (str): File mode ("100644", "100755", "040000", "160000", "120000")
230
            type (str): Object type ("blob", "tree", "commit")
231
            content (str, optional): File content (for new files)
232
            sha (str, optional): Object SHA (for existing objects)
233
        """
234
```
235

236
### Input Helper Classes
237

238
Helper classes for providing structured input to Git and file operations.
239

240
```python { .api }
241
class InputFileContent:
242
    def __init__(self, content: str, new_name: str | None = None):
243
        """
244
        Input class for file content operations in gists and other file operations.
245
        
246
        Args:
247
            content (str): File content
248
            new_name (str, optional): New filename for the content
249
        """
250

251
class InputGitAuthor:
252
    def __init__(self, name: str, email: str, date: str = None):
253
        """
254
        Git author information for commits and tags.
255
        
256
        Args:
257
            name (str): Author name
258
            email (str): Author email  
259
            date (str, optional): Date in ISO 8601 format (defaults to current time)
260
        """
261
```
262

263
### Git Blob Operations
264

265
Handle Git blob objects for raw file content storage.
266

267
```python { .api }
268
class Repository:
269
    def get_git_blob(self, sha: str):
270
        """
271
        Get a Git blob object.
272
        
273
        Args:
274
            sha (str): Blob SHA
275
            
276
        Returns:
277
            GitBlob: Blob object
278
        """
279
    
280
    def create_git_blob(self, content: str, encoding: str):
281
        """
282
        Create a Git blob object.
283
        
284
        Args:
285
            content (str): Blob content
286
            encoding (str): Content encoding ("utf-8", "base64")
287
            
288
        Returns:
289
            GitBlob: Created blob object
290
        """
291

292
class GitBlob:
293
    @property
294
    def sha(self) -> str: ...
295
    @property
296
    def content(self) -> str: ...
297
    @property
298
    def encoding(self) -> str: ...
299
    @property
300
    def size(self) -> int: ...
301
    @property
302
    def url(self) -> str: ...
303
```
304

305
### Git Reference Management
306

307
Manage Git references including branches, tags, and other refs.
308

309
```python { .api }
310
class Repository:
311
    def get_git_refs(self, subspace: str = None):
312
        """
313
        Get Git references.
314
        
315
        Args:
316
            subspace (str, optional): Reference namespace ("heads", "tags", "remotes")
317
            
318
        Returns:
319
            PaginatedList[GitRef]: List of references
320
        """
321
    
322
    def get_git_ref(self, ref: str):
323
        """
324
        Get a specific Git reference.
325
        
326
        Args:
327
            ref (str): Reference name (e.g., "heads/main", "tags/v1.0.0")
328
            
329
        Returns:
330
            GitRef: Reference object
331
        """
332
    
333
    def create_git_ref(self, ref: str, sha: str):
334
        """
335
        Create a Git reference.
336
        
337
        Args:
338
            ref (str): Reference name
339
            sha (str): SHA to point to
340
            
341
        Returns:
342
            GitRef: Created reference
343
        """
344

345
class GitRef:
346
    @property
347
    def ref(self) -> str: ...
348
    @property
349
    def object(self) -> GitObject: ...
350
    @property
351
    def url(self) -> str: ...
352
    
353
    def edit(self, sha: str, force: bool = False):
354
        """
355
        Update the reference.
356
        
357
        Args:
358
            sha (str): New SHA to point to
359
            force (bool, optional): Force update even if not fast-forward
360
        """
361
    
362
    def delete(self):
363
        """Delete the reference."""
364

365
class GitObject:
366
    @property
367
    def sha(self) -> str: ...
368
    @property
369
    def type(self) -> str: ...  # "commit", "tree", "blob", "tag"
370
    @property
371
    def url(self) -> str: ...
372
```
373

374
### Git Tag Operations
375

376
Create and manage Git tag objects for version marking and releases.
377

378
```python { .api }
379
class Repository:
380
    def get_git_tags(self):
381
        """
382
        Get Git tag objects.
383
        
384
        Returns:
385
            PaginatedList[GitTag]: List of tag objects
386
        """
387
    
388
    def get_git_tag(self, sha: str):
389
        """
390
        Get a specific Git tag object.
391
        
392
        Args:
393
            sha (str): Tag SHA
394
            
395
        Returns:
396
            GitTag: Tag object
397
        """
398
    
399
    def create_git_tag(
400
        self,
401
        tag: str,
402
        message: str,
403
        object: str,
404
        type: str,
405
        tagger: InputGitAuthor = None
406
    ):
407
        """
408
        Create a Git tag object.
409
        
410
        Args:
411
            tag (str): Tag name
412
            message (str): Tag message
413
            object (str): SHA of object to tag
414
            type (str): Type of object ("commit", "tree", "blob")
415
            tagger (InputGitAuthor, optional): Tag creator
416
            
417
        Returns:
418
            GitTag: Created tag object
419
        """
420

421
class GitTag:
422
    @property
423
    def sha(self) -> str: ...
424
    @property
425
    def tag(self) -> str: ...
426
    @property
427
    def message(self) -> str: ...
428
    @property
429
    def tagger(self) -> GitAuthor: ...
430
    @property
431
    def object(self) -> GitObject: ...
432
    @property
433
    def url(self) -> str: ...
434
```
435

436
### Git Author Information
437

438
Handle Git author and committer information for commits and tags.
439

440
```python { .api }
441
class GitAuthor:
442
    @property
443
    def name(self) -> str: ...
444
    @property
445
    def email(self) -> str: ...
446
    @property
447
    def date(self) -> datetime: ...
448

449
class InputGitAuthor:
450
    def __init__(self, name: str, email: str, date: str = None):
451
        """
452
        Git author information for commits and tags.
453
        
454
        Args:
455
            name (str): Author name
456
            email (str): Author email
457
            date (str, optional): Date in ISO 8601 format (defaults to current time)
458
        """
459
```
460

461
### Comparison and Diff Operations
462

463
Compare commits, branches, and view detailed diff information.
464

465
```python { .api }
466
class Comparison:
467
    @property
468
    def status(self) -> str: ...  # "behind", "ahead", "identical", "diverged"
469
    @property
470
    def ahead_by(self) -> int: ...
471
    @property
472
    def behind_by(self) -> int: ...
473
    @property
474
    def total_commits(self) -> int: ...
475
    @property
476
    def commits(self) -> list: ...
477
    @property
478
    def files(self) -> list: ...
479
    @property
480
    def merge_base_commit(self) -> Commit: ...
481
    @property
482
    def diff_url(self) -> str: ...
483
    @property
484
    def patch_url(self) -> str: ...
485
    @property
486
    def permalink_url(self) -> str: ...
487

488
class File:
489
    @property
490
    def filename(self) -> str: ...
491
    @property
492
    def status(self) -> str: ...  # "added", "removed", "modified", "renamed"
493
    @property
494
    def additions(self) -> int: ...
495
    @property
496
    def deletions(self) -> int: ...
497
    @property
498
    def changes(self) -> int: ...
499
    @property
500
    def sha(self) -> str: ...
501
    @property
502
    def blob_url(self) -> str: ...
503
    @property
504
    def raw_url(self) -> str: ...
505
    @property
506
    def contents_url(self) -> str: ...
507
    @property
508
    def patch(self) -> str: ...
509
    @property
510
    def previous_filename(self) -> str: ...  # For renamed files
511
```
512

513
### Commit Status and Checks
514

515
Manage commit statuses for continuous integration and status checks.
516

517
```python { .api }
518
class Repository:
519
    def get_commit_statuses(self, sha: str):
520
        """
521
        Get statuses for a commit.
522
        
523
        Args:
524
            sha (str): Commit SHA
525
            
526
        Returns:
527
            PaginatedList[CommitStatus]: List of statuses
528
        """
529
    
530
    def create_commit_status(
531
        self,
532
        sha: str,
533
        state: str,
534
        target_url: str = None,
535
        description: str = None,
536
        context: str = None
537
    ):
538
        """
539
        Create a commit status.
540
        
541
        Args:
542
            sha (str): Commit SHA
543
            state (str): Status state ("pending", "success", "error", "failure")
544
            target_url (str, optional): URL with status details
545
            description (str, optional): Short status description
546
            context (str, optional): Unique context identifier
547
            
548
        Returns:
549
            CommitStatus: Created status
550
        """
551
    
552
    def get_combined_status(self, ref: str):
553
        """
554
        Get combined status for a reference.
555
        
556
        Args:
557
            ref (str): Commit SHA, branch name, or tag name
558
            
559
        Returns:
560
            CommitCombinedStatus: Combined status information
561
        """
562

563
class CommitStatus:
564
    @property
565
    def state(self) -> str: ...
566
    @property
567
    def target_url(self) -> str: ...
568
    @property
569
    def description(self) -> str: ...
570
    @property
571
    def context(self) -> str: ...
572
    @property
573
    def creator(self) -> NamedUser: ...
574
    @property
575
    def created_at(self) -> datetime: ...
576
    @property
577
    def updated_at(self) -> datetime: ...
578

579
class CommitCombinedStatus:
580
    @property
581
    def state(self) -> str: ...
582
    @property
583
    def sha(self) -> str: ...
584
    @property
585
    def total_count(self) -> int: ...
586
    @property
587
    def statuses(self) -> list: ...
588
    @property
589
    def repository(self) -> Repository: ...
590
    @property
591
    def commit_url(self) -> str: ...
592
```
593

594
## Usage Examples
595

596
### Creating Files with Git Operations
597

598
```python
599
from github import Github, Auth, InputGitAuthor, InputGitTreeElement
600
import base64
601

602
g = Github(auth=Auth.Token("your_token"))
603
repo = g.get_repo("owner/repository")
604

605
# Get current commit
606
main_branch = repo.get_branch("main")
607
base_commit = main_branch.commit
608

609
# Create a blob for new file content
610
content = "Hello, World!"
611
blob = repo.create_git_blob(content, "utf-8")
612

613
# Create tree element for the new file  
614
tree_element = InputGitTreeElement(
615
    path="hello.txt",
616
    mode="100644",  # Regular file
617
    type="blob",
618
    sha=blob.sha
619
)
620

621
# Create a new tree with the file
622
tree = repo.create_git_tree([tree_element], base_commit.commit.tree.sha)
623

624
# Create commit
625
author = InputGitAuthor("Your Name", "your.email@example.com")
626
commit = repo.create_git_commit(
627
    message="Add hello.txt file",
628
    tree=tree.sha,
629
    parents=[base_commit.sha],
630
    author=author
631
)
632

633
# Update main branch to point to new commit
634
ref = repo.get_git_ref("heads/main")
635
ref.edit(commit.sha)
636

637
print(f"Created commit: {commit.sha}")
638
```
639

640
### Working with Multiple Files
641

642
```python
643
# Create multiple files in one commit
644
files_to_create = [
645
    {"path": "src/main.py", "content": "print('Hello from main')"},
646
    {"path": "src/utils.py", "content": "def helper(): pass"},
647
    {"path": "README.md", "content": "# My Project"}
648
]
649

650
# Create blobs for all files
651
tree_elements = []
652
for file_info in files_to_create:
653
    blob = repo.create_git_blob(file_info["content"], "utf-8")
654
    tree_elements.append(InputGitTreeElement(
655
        path=file_info["path"],
656
        mode="100644",
657
        type="blob", 
658
        sha=blob.sha
659
    ))
660

661
# Create tree and commit
662
tree = repo.create_git_tree(tree_elements, base_commit.commit.tree.sha)
663
commit = repo.create_git_commit(
664
    message="Add project structure",
665
    tree=tree.sha,
666
    parents=[base_commit.sha],
667
    author=author
668
)
669

670
# Update branch
671
ref.edit(commit.sha)
672
```
673

674
### Branch and Tag Management
675

676
```python
677
# Create a new branch
678
repo.create_git_ref("refs/heads/feature-branch", commit.sha)
679

680
# Create an annotated tag
681
tag = repo.create_git_tag(
682
    tag="v1.0.0",
683
    message="Version 1.0.0 release",
684
    object=commit.sha,
685
    type="commit",
686
    tagger=author
687
)
688

689
# Create reference for the tag
690
repo.create_git_ref("refs/tags/v1.0.0", tag.sha)
691

692
print(f"Created tag: {tag.tag}")
693
```
694

695
### Commit Status Management
696

697
```python
698
# Create commit status for CI
699
status = repo.create_commit_status(
700
    sha=commit.sha,
701
    state="pending",
702
    target_url="https://ci.example.com/builds/123",
703
    description="Build is running",
704
    context="continuous-integration/jenkins"
705
)
706

707
# Update status after build completion
708
status = repo.create_commit_status(
709
    sha=commit.sha,
710
    state="success", 
711
    target_url="https://ci.example.com/builds/123",
712
    description="Build passed",
713
    context="continuous-integration/jenkins"
714
)
715

716
# Get all statuses for a commit
717
statuses = repo.get_commit_statuses(commit.sha)
718
for status in statuses:
719
    print(f"{status.context}: {status.state}")
720
```
721

722
### Comparing Commits
723

724
```python
725
# Compare two branches
726
comparison = repo.compare("main", "feature-branch")
727
print(f"Status: {comparison.status}")
728
print(f"Commits ahead: {comparison.ahead_by}")
729
print(f"Commits behind: {comparison.behind_by}")
730

731
# List changed files
732
for file in comparison.files:
733
    print(f"{file.status}: {file.filename} (+{file.additions}/-{file.deletions})")
734

735
# Get specific commit details
736
for commit in comparison.commits:
737
    print(f"Commit: {commit.sha[:8]} - {commit.commit.message}")
738
```