0
# Porcelain API
1

2
High-level Git operations providing familiar Git command equivalents. The porcelain API offers convenient functions for common Git operations without requiring deep knowledge of Git internals.
3

4
## Capabilities
5

6
### Repository Management
7

8
Initialize, clone, and open Git repositories with various options and configurations.
9

10
```python { .api }
11
def init(
12
    path: str = ".",
13
    bare: bool = False,
14
    **kwargs
15
) -> Repo:
16
    """
17
    Initialize a new Git repository.
18
    
19
    Parameters:
20
    - path: Path where to create the repository
21
    - bare: Create a bare repository (no working tree)
22
    
23
    Returns:
24
    Repo object for the new repository
25
    """
26

27
def clone(
28
    source: str,
29
    target: str = None,
30
    bare: bool = False,
31
    checkout: bool = None,
32
    errstream: BinaryIO = None,
33
    outstream: BinaryIO = None,
34
    origin: str = "origin",
35
    depth: int = None,
36
    branch: str = None,
37
    progress: Callable = None,
38
    **kwargs
39
) -> Repo:
40
    """
41
    Clone a Git repository.
42
    
43
    Parameters:
44
    - source: URL or path of source repository
45
    - target: Local directory for cloned repository
46
    - bare: Create bare clone
47
    - checkout: Whether to checkout HEAD after clone
48
    - branch: Branch to clone
49
    - depth: Create shallow clone with specified depth
50
    - progress: Progress callback function
51
    
52
    Returns:
53
    Repo object for cloned repository
54
    """
55

56
def open_repo(path: str = ".") -> Repo:
57
    """
58
    Open an existing Git repository.
59
    
60
    Parameters:
61
    - path: Path to repository
62
    
63
    Returns:
64
    Repo object
65
    """
66

67
def open_repo_closing(path: str = "."):
68
    """
69
    Context manager for opening a repository that automatically closes it.
70
    
71
    Parameters:
72
    - path: Path to repository
73
    
74
    Returns:
75
    Context manager yielding Repo object
76
    """
77
```
78

79
### File Operations
80

81
Add, remove, and move files in the repository with staging area management.
82

83
```python { .api }
84
def add(
85
    repo,
86
    paths: List[str] = None,
87
    **kwargs
88
) -> None:
89
    """
90
    Add files to the staging area.
91
    
92
    Parameters:
93
    - repo: Repository object or path
94
    - paths: List of file paths to add
95
    """
96

97
def remove(
98
    repo,
99
    paths: List[str],
100
    cached: bool = False,
101
    **kwargs
102
) -> None:
103
    """
104
    Remove files from repository and/or working tree.
105
    
106
    Parameters:
107
    - repo: Repository object or path
108
    - paths: List of file paths to remove
109
    - cached: Only remove from index, keep in working tree
110
    """
111

112
def mv(
113
    repo,
114
    sources: List[str],
115
    destination: str,
116
    **kwargs
117
) -> None:
118
    """
119
    Move or rename files in the repository.
120
    
121
    Parameters:
122
    - repo: Repository object or path  
123
    - sources: Source file paths
124
    - destination: Destination path
125
    """
126

127
def clean(
128
    repo,
129
    target_dir: str = None,
130
    dry_run: bool = False,
131
    **kwargs
132
) -> List[str]:
133
    """
134
    Remove untracked files from working tree.
135
    
136
    Parameters:
137
    - repo: Repository object or path
138
    - target_dir: Directory to clean (default: repository root)
139
    - dry_run: Show what would be deleted without doing it
140
    
141
    Returns:
142
    List of files that were (or would be) removed
143
    """
144
```
145

146
### Commit Operations
147

148
Create commits, manage commit history, and handle commit metadata.
149

150
```python { .api }
151
def commit(
152
    repo,
153
    message: str = None,
154
    author: str = None,
155
    committer: str = None,
156
    encoding: str = "utf-8",
157
    no_verify: bool = False,
158
    **kwargs
159
) -> bytes:
160
    """
161
    Create a new commit.
162
    
163
    Parameters:
164
    - repo: Repository object or path
165
    - message: Commit message
166
    - author: Author in format "Name <email>"
167
    - committer: Committer in format "Name <email>"
168
    - encoding: Text encoding for commit message
169
    - no_verify: Skip pre-commit and commit-msg hooks
170
    
171
    Returns:
172
    SHA-1 hash of created commit
173
    """
174

175
def commit_tree(
176
    repo,
177
    tree: bytes,
178
    message: str,
179
    parents: List[bytes] = None,
180
    author: str = None,
181
    committer: str = None,
182
    **kwargs
183
) -> bytes:
184
    """
185
    Create commit object from tree.
186
    
187
    Parameters:
188
    - repo: Repository object or path
189
    - tree: Tree SHA-1 hash
190
    - message: Commit message
191
    - parents: List of parent commit SHA-1 hashes
192
    - author: Author in format "Name <email>"
193
    - committer: Committer in format "Name <email>"
194
    
195
    Returns:
196
    SHA-1 hash of created commit
197
    """
198
```
199

200
### Branch Management
201

202
Create, delete, and manage branches with tracking configuration.
203

204
```python { .api }
205
def branch_create(
206
    repo,
207
    name: str,
208
    objectish: str = "HEAD",
209
    **kwargs
210
) -> None:
211
    """
212
    Create a new branch.
213
    
214
    Parameters:
215
    - repo: Repository object or path
216
    - name: Branch name
217
    - objectish: Starting point (commit, branch, or tag)
218
    """
219

220
def branch_delete(
221
    repo,
222
    name: str,
223
    **kwargs
224
) -> None:
225
    """
226
    Delete a branch.
227
    
228
    Parameters:
229
    - repo: Repository object or path
230
    - name: Branch name to delete
231
    """
232

233
def branch_list(repo) -> List[bytes]:
234
    """
235
    List all branches.
236
    
237
    Parameters:
238
    - repo: Repository object or path
239
    
240
    Returns:
241
    List of branch names
242
    """
243

244
def active_branch(repo) -> bytes:
245
    """
246
    Get the currently active branch.
247
    
248
    Parameters:
249
    - repo: Repository object or path
250
    
251
    Returns:
252
    Current branch name
253
    """
254

255
def checkout(
256
    repo,
257
    committish: str = None,
258
    **kwargs
259
) -> None:
260
    """
261
    Checkout files or switch branches.
262
    
263
    Parameters:
264
    - repo: Repository object or path
265
    - committish: Branch, tag, or commit to checkout
266
    """
267

268
def checkout_branch(
269
    repo,
270
    name: str,
271
    **kwargs
272
) -> None:
273
    """
274
    Checkout a specific branch.
275
    
276
    Parameters:
277
    - repo: Repository object or path
278
    - name: Branch name to checkout
279
    """
280
```
281

282
### Remote Operations
283

284
Synchronize with remote repositories through push, pull, and fetch operations.
285

286
```python { .api }
287
def push(
288
    repo,
289
    remote_location: str = None,
290
    refspecs: List[str] = None,
291
    outstream: BinaryIO = None,
292
    errstream: BinaryIO = None,
293
    progress: Callable = None,
294
    **kwargs
295
) -> Dict[bytes, str]:
296
    """
297
    Push changes to remote repository.
298
    
299
    Parameters:
300
    - repo: Repository object or path
301
    - remote_location: Remote URL or name
302
    - refspecs: List of refspecs to push
303
    - progress: Progress callback function
304
    
305
    Returns:
306
    Dictionary mapping refs to push status
307
    """
308

309
def pull(
310
    repo,
311
    remote_location: str = None,
312
    refspecs: List[str] = None,
313
    outstream: BinaryIO = None,
314
    errstream: BinaryIO = None,
315
    fast_forward_only: bool = False,
316
    **kwargs
317
) -> None:
318
    """
319
    Pull changes from remote repository.
320
    
321
    Parameters:
322
    - repo: Repository object or path
323
    - remote_location: Remote URL or name
324
    - refspecs: List of refspecs to pull
325
    - fast_forward_only: Only allow fast-forward merges
326
    """
327

328
def fetch(
329
    repo,
330
    remote_location: str = None,
331
    refspecs: List[str] = None,
332
    outstream: BinaryIO = None,
333
    errstream: BinaryIO = None,
334
    progress: Callable = None,
335
    **kwargs
336
) -> Dict[bytes, bytes]:
337
    """
338
    Fetch changes from remote repository.
339
    
340
    Parameters:
341
    - repo: Repository object or path
342
    - remote_location: Remote URL or name
343
    - refspecs: List of refspecs to fetch
344
    - progress: Progress callback function
345
    
346
    Returns:
347
    Dictionary mapping remote refs to local refs
348
    """
349

350
def remote_add(
351
    repo,
352
    name: str,
353
    url: str,
354
    **kwargs
355
) -> None:
356
    """
357
    Add a remote repository.
358
    
359
    Parameters:
360
    - repo: Repository object or path
361
    - name: Remote name
362
    - url: Remote URL
363
    """
364

365
def remote_remove(
366
    repo,
367
    name: str,
368
    **kwargs
369
) -> None:
370
    """
371
    Remove a remote repository.
372
    
373
    Parameters:
374
    - repo: Repository object or path
375
    - name: Remote name to remove
376
    """
377

378
def ls_remote(
379
    remote: str,
380
    **kwargs
381
) -> Dict[bytes, bytes]:
382
    """
383
    List remote references.
384
    
385
    Parameters:
386
    - remote: Remote URL
387
    
388
    Returns:
389
    Dictionary mapping ref names to SHA-1 hashes
390
    """
391
```
392

393
### Status and Information
394

395
Get repository status, view history, and examine repository contents.
396

397
```python { .api }
398
def status(repo) -> PorterStatus:
399
    """
400
    Get repository status.
401
    
402
    Parameters:
403
    - repo: Repository object or path
404
    
405
    Returns:
406
    PorterStatus object with staged, unstaged, and untracked files
407
    """
408

409
def log(
410
    repo,
411
    paths: List[str] = None,
412
    outstream: BinaryIO = None,
413
    max_entries: int = None,
414
    reverse: bool = False,
415
    name_status: bool = False,
416
    **kwargs
417
) -> None:
418
    """
419
    Show commit history.
420
    
421
    Parameters:
422
    - repo: Repository object or path
423
    - paths: Limit to specific paths
424
    - outstream: Output stream for log
425
    - max_entries: Maximum number of entries to show
426
    - reverse: Show in reverse chronological order
427
    - name_status: Show file change status
428
    """
429

430
def show(
431
    repo,
432
    objects: List[str] = None,
433
    outstream: BinaryIO = None,
434
    **kwargs
435
) -> None:
436
    """
437
    Show object contents.
438
    
439
    Parameters:
440
    - repo: Repository object or path
441
    - objects: List of objects to show
442
    - outstream: Output stream
443
    """
444

445
def diff(
446
    repo,
447
    paths: List[str] = None,
448
    outstream: BinaryIO = None,
449
    **kwargs
450
) -> None:
451
    """
452
    Show differences between commits, commit and working tree, etc.
453
    
454
    Parameters:
455
    - repo: Repository object or path
456
    - paths: Limit to specific paths
457
    - outstream: Output stream for diff
458
    """
459

460
def describe(
461
    repo,
462
    committish: str = "HEAD",
463
    **kwargs
464
) -> str:
465
    """
466
    Describe a commit using the most recent tag.
467
    
468
    Parameters:
469
    - repo: Repository object or path
470
    - committish: Commit to describe
471
    
472
    Returns:
473
    Description string
474
    """
475
```
476

477
### Tag Management
478

479
Create, delete, and list tags with support for annotated and lightweight tags.
480

481
```python { .api }
482
def tag_create(
483
    repo,
484
    tag: str,
485
    author: str = None,
486
    message: str = None,
487
    annotated: bool = False,
488
    objectish: str = "HEAD",
489
    tag_time: int = None,
490
    tag_timezone: int = None,
491
    sign: bool = False,
492
    **kwargs
493
) -> Tag:
494
    """
495
    Create a new tag.
496
    
497
    Parameters:
498
    - repo: Repository object or path
499
    - tag: Tag name
500
    - author: Author in format "Name <email>"
501
    - message: Tag message (for annotated tags)
502
    - annotated: Create annotated tag
503
    - objectish: Object to tag
504
    - sign: Sign the tag with GPG
505
    
506
    Returns:
507
    Tag object
508
    """
509

510
def tag_delete(
511
    repo,
512
    name: str,
513
    **kwargs
514
) -> None:
515
    """
516
    Delete a tag.
517
    
518
    Parameters:
519
    - repo: Repository object or path
520
    - name: Tag name to delete
521
    """
522

523
def tag_list(
524
    repo,
525
    outstream: BinaryIO = None,
526
    **kwargs
527
) -> List[bytes]:
528
    """
529
    List all tags.
530
    
531
    Parameters:
532
    - repo: Repository object or path
533
    - outstream: Output stream for tag list
534
    
535
    Returns:
536
    List of tag names
537
    """
538
```
539

540
### Stash Operations
541

542
Save and restore working directory changes using Git's stash functionality.
543

544
```python { .api }
545
def stash_list(repo) -> List[bytes]:
546
    """
547
    List all stashes.
548
    
549
    Parameters:
550
    - repo: Repository object or path
551
    
552
    Returns:
553
    List of stash references
554
    """
555

556
def stash_push(
557
    repo,
558
    message: str = None,
559
    **kwargs
560
) -> bytes:
561
    """
562
    Save current changes to stash.
563
    
564
    Parameters:
565
    - repo: Repository object or path
566
    - message: Stash message
567
    
568
    Returns:
569
    Stash reference
570
    """
571

572
def stash_pop(
573
    repo,
574
    stash: str = None,
575
    **kwargs
576
) -> None:
577
    """
578
    Apply and remove a stash.
579
    
580
    Parameters:
581
    - repo: Repository object or path
582
    - stash: Stash reference (default: most recent)
583
    """
584

585
def stash_drop(
586
    repo,
587
    stash: str = None,
588
    **kwargs
589
) -> None:
590
    """
591
    Delete a stash.
592
    
593
    Parameters:
594
    - repo: Repository object or path
595
    - stash: Stash reference (default: most recent)
596
    """
597
```
598

599
### Advanced Operations
600

601
Complex Git operations including merge, rebase, cherry-pick, and bisect.
602

603
```python { .api }
604
def merge(
605
    repo: Union[str, os.PathLike, Repo],
606
    committish: Union[str, bytes, Commit, Tag],
607
    no_commit: bool = False,
608
    no_ff: bool = False,
609
    message: str = None,
610
    author: str = None,
611
    committer: str = None,
612
) -> tuple[bytes, list]:
613
    """
614
    Merge a commit into the current branch.
615
    
616
    Parameters:
617
    - repo: Repository object or path
618
    - committish: Branch or commit to merge
619
    - no_commit: If True, do not create a merge commit
620
    - no_ff: If True, force creation of a merge commit
621
    - message: Optional merge commit message
622
    - author: Optional author for merge commit
623
    - committer: Optional committer for merge commit
624
    
625
    Returns:
626
    Tuple of (merge_commit_sha, conflicts)
627
    """
628

629
def merge_tree(
630
    repo,
631
    base_tree: Optional[Union[str, bytes, Tree, Commit, Tag]],
632
    our_tree: Union[str, bytes, Tree, Commit, Tag],
633
    their_tree: Union[str, bytes, Tree, Commit, Tag],
634
) -> tuple[bytes, list[bytes]]:
635
    """
636
    Perform a three-way tree merge without touching the working directory.
637
    
638
    Parameters:
639
    - repo: Repository containing the trees
640
    - base_tree: Tree-ish of the common ancestor (or None)
641
    - our_tree: Tree-ish of our side of the merge
642
    - their_tree: Tree-ish of their side of the merge
643
    
644
    Returns:
645
    Tuple of (merged_tree_id, conflicts)
646
    """
647

648
def cherry_pick(
649
    repo: Union[str, os.PathLike, Repo],
650
    committish: Union[str, bytes, Commit, Tag, None],
651
    no_commit: bool = False,
652
    continue_: bool = False,
653
    abort: bool = False,
654
) -> bytes:
655
    """
656
    Cherry-pick a commit onto the current branch.
657
    
658
    Parameters:
659
    - repo: Repository object or path
660
    - committish: Commit to cherry-pick
661
    - no_commit: If True, do not create a commit after applying changes
662
    - continue_: Continue an in-progress cherry-pick after resolving conflicts
663
    - abort: Abort an in-progress cherry-pick
664
    
665
    Returns:
666
    SHA of newly created commit, or None if no_commit=True
667
    """
668

669
def revert(
670
    repo: Union[str, os.PathLike, Repo],
671
    commits: Union[str, bytes, Commit, Tag, list],
672
    no_commit: bool = False,
673
    message: str = None,
674
    author: str = None,
675
    committer: str = None,
676
) -> bytes:
677
    """
678
    Revert one or more commits.
679
    
680
    Parameters:
681
    - repo: Repository object or path
682
    - commits: List of commit-ish to revert, or a single commit-ish
683
    - no_commit: If True, apply changes but don't commit
684
    - message: Optional commit message
685
    - author: Optional author for revert commit
686
    - committer: Optional committer for revert commit
687
    
688
    Returns:
689
    SHA1 of new revert commit, or None if no_commit=True
690
    """
691

692
def rebase(
693
    repo: Union[Repo, str],
694
    upstream: Union[bytes, str],
695
    onto: Optional[Union[bytes, str]] = None,
696
    branch: Optional[Union[bytes, str]] = None,
697
    abort: bool = False,
698
    continue_rebase: bool = False,
699
    skip: bool = False,
700
) -> list[bytes]:
701
    """
702
    Rebase commits onto another branch.
703
    
704
    Parameters:
705
    - repo: Repository to rebase in
706
    - upstream: Upstream branch/commit to rebase onto
707
    - onto: Specific commit to rebase onto (defaults to upstream)
708
    - branch: Branch to rebase (defaults to current branch)
709
    - abort: Abort an in-progress rebase
710
    - continue_rebase: Continue an in-progress rebase
711
    - skip: Skip current commit and continue rebase
712
    
713
    Returns:
714
    List of new commit SHAs created by rebase
715
    """
716

717
def reset(
718
    repo: Union[str, os.PathLike, Repo],
719
    mode: str,
720
    treeish: Union[str, bytes, Commit, Tree, Tag] = "HEAD",
721
) -> None:
722
    """
723
    Reset current HEAD to specified state.
724
    
725
    Parameters:
726
    - repo: Repository object or path
727
    - mode: Reset mode ("soft", "mixed", "hard")
728
    - treeish: Target tree or commit
729
    """
730

731
def reset_file(
732
    repo,
733
    file_path: str,
734
    target: Union[str, bytes, Commit, Tree, Tag] = b"HEAD",
735
    symlink_fn = None,
736
) -> None:
737
    """
738
    Reset a specific file to a commit or branch.
739
    
740
    Parameters:
741
    - repo: Repository object
742
    - file_path: File to reset, relative to repository path
743
    - target: Branch or commit to reset to
744
    - symlink_fn: Optional symlink function
745
    """
746
```
747

748
### Bisect Operations
749

750
Binary search through commit history to find bugs.
751

752
```python { .api }
753
def bisect_start(
754
    repo: Union[str, os.PathLike, Repo] = ".",
755
    bad: Optional[Union[str, bytes, Commit, Tag]] = None,
756
    good: Optional[Union[str, bytes, Commit, Tag, list]] = None,
757
    paths = None,
758
    no_checkout: bool = False,
759
    term_bad: str = "bad",
760
    term_good: str = "good",
761
) -> bytes:
762
    """
763
    Start a new bisect session.
764
    
765
    Parameters:
766
    - repo: Repository object or path
767
    - bad: The bad commit (defaults to HEAD)
768
    - good: List of good commits or a single good commit
769
    - paths: Optional paths to limit bisect to
770
    - no_checkout: If True, don't checkout commits during bisect
771
    - term_bad: Term to use for bad commits
772
    - term_good: Term to use for good commits
773
    
774
    Returns:
775
    SHA of next commit to test
776
    """
777

778
def bisect_bad(
779
    repo: Union[str, os.PathLike, Repo] = ".",
780
    rev: Optional[Union[str, bytes, Commit, Tag]] = None,
781
) -> bytes:
782
    """
783
    Mark a commit as bad.
784
    
785
    Parameters:
786
    - repo: Repository object or path
787
    - rev: Commit to mark as bad (defaults to HEAD)
788
    
789
    Returns:
790
    SHA of next commit to test, or None if bisect is complete
791
    """
792

793
def bisect_good(
794
    repo: Union[str, os.PathLike, Repo] = ".",
795
    rev: Optional[Union[str, bytes, Commit, Tag]] = None,
796
) -> bytes:
797
    """
798
    Mark a commit as good.
799
    
800
    Parameters:
801
    - repo: Repository object or path
802
    - rev: Commit to mark as good (defaults to HEAD)
803
    
804
    Returns:
805
    SHA of next commit to test, or None if bisect is complete
806
    """
807

808
def bisect_skip(
809
    repo: Union[str, os.PathLike, Repo] = ".",
810
    revs: Optional[Union[str, bytes, Commit, Tag, list]] = None,
811
) -> bytes:
812
    """
813
    Skip one or more commits during bisect.
814
    
815
    Parameters:
816
    - repo: Repository object or path
817
    - revs: List of commits to skip (defaults to [HEAD])
818
    
819
    Returns:
820
    SHA of next commit to test, or None if bisect is complete
821
    """
822

823
def bisect_reset(
824
    repo: Union[str, os.PathLike, Repo] = ".",
825
    commit: Optional[Union[str, bytes, Commit, Tag]] = None,
826
) -> None:
827
    """
828
    Reset bisect state and return to original branch/commit.
829
    
830
    Parameters:
831
    - repo: Repository object or path
832
    - commit: Optional commit to reset to (defaults to original branch)
833
    """
834

835
def bisect_log(repo: Union[str, os.PathLike, Repo] = ".") -> str:
836
    """
837
    Get the bisect log.
838
    
839
    Parameters:
840
    - repo: Repository object or path
841
    
842
    Returns:
843
    The bisect log as a string
844
    """
845

846
def bisect_replay(repo: Union[str, os.PathLike, Repo], log_file) -> None:
847
    """
848
    Replay a bisect log.
849
    
850
    Parameters:
851
    - repo: Repository object or path
852
    - log_file: Path to log file or file-like object
853
    """
854
```
855

856
### Notes Operations
857

858
Manage Git notes for annotating objects.
859

860
```python { .api }
861
def notes_add(
862
    repo,
863
    object_sha,
864
    note,
865
    ref: bytes = b"commits",
866
    author = None,
867
    committer = None,
868
    message = None,
869
) -> bytes:
870
    """
871
    Add or update a note for an object.
872
    
873
    Parameters:
874
    - repo: Repository object or path
875
    - object_sha: SHA of the object to annotate
876
    - note: Note content
877
    - ref: Notes ref to use (defaults to "commits")
878
    - author: Author identity (defaults to committer)
879
    - committer: Committer identity (defaults to config)
880
    - message: Commit message for the notes update
881
    
882
    Returns:
883
    SHA of the new notes commit
884
    """
885

886
def notes_remove(
887
    repo,
888
    object_sha,
889
    ref: bytes = b"commits",
890
    author = None,
891
    committer = None,
892
    message = None,
893
) -> bytes:
894
    """
895
    Remove a note for an object.
896
    
897
    Parameters:
898
    - repo: Repository object or path
899
    - object_sha: SHA of the object to remove notes from
900
    - ref: Notes ref to use (defaults to "commits")
901
    - author: Author identity (defaults to committer)
902
    - committer: Committer identity (defaults to config)
903
    - message: Commit message for the notes removal
904
    
905
    Returns:
906
    SHA of new notes commit, or None if no note existed
907
    """
908

909
def notes_show(
910
    repo: Union[str, os.PathLike, Repo],
911
    object_sha,
912
    ref: bytes = b"commits",
913
) -> bytes:
914
    """
915
    Show the note for an object.
916
    
917
    Parameters:
918
    - repo: Repository object or path
919
    - object_sha: SHA of the object
920
    - ref: Notes ref to use (defaults to "commits")
921
    
922
    Returns:
923
    Note content as bytes, or None if no note exists
924
    """
925

926
def notes_list(repo: RepoPath, ref: bytes = b"commits") -> list[tuple]:
927
    """
928
    List all notes in a notes ref.
929
    
930
    Parameters:
931
    - repo: Repository object or path
932
    - ref: Notes ref to use (defaults to "commits")
933
    
934
    Returns:
935
    List of tuples of (object_sha, note_content)
936
    """
937
```
938

939
### Repository Maintenance
940

941
Garbage collection, object management, and repository optimization.
942

943
```python { .api }
944
def gc(
945
    repo,
946
    auto: bool = False,
947
    aggressive: bool = False,
948
    prune: bool = True,
949
    grace_period: Optional[int] = 1209600,
950
    dry_run: bool = False,
951
    progress = None,
952
) -> GCStats:
953
    """
954
    Run garbage collection on a repository.
955
    
956
    Parameters:
957
    - repo: Repository object or path
958
    - auto: If True, only run gc if needed
959
    - aggressive: If True, use more aggressive settings
960
    - prune: If True, prune unreachable objects
961
    - grace_period: Grace period in seconds for pruning (default 2 weeks)
962
    - dry_run: If True, only report what would be done
963
    - progress: Optional progress callback
964
    
965
    Returns:
966
    GCStats object with garbage collection statistics
967
    """
968

969
def prune(
970
    repo,
971
    grace_period: Optional[int] = None,
972
    dry_run: bool = False,
973
    progress = None,
974
) -> None:
975
    """
976
    Prune/clean up a repository's object store.
977
    
978
    Parameters:
979
    - repo: Repository object or path
980
    - grace_period: Grace period in seconds for removing temporary files
981
    - dry_run: If True, only report what would be done
982
    - progress: Optional progress callback
983
    """
984

985
def repack(repo: RepoPath) -> None:
986
    """
987
    Repack loose files in a repository.
988
    
989
    Parameters:
990
    - repo: Repository object or path
991
    """
992

993
def pack_objects(
994
    repo,
995
    object_ids,
996
    packf,
997
    idxf,
998
    delta_window_size = None,
999
    deltify = None,
1000
    reuse_deltas: bool = True,
1001
    pack_index_version = None,
1002
) -> None:
1003
    """
1004
    Pack objects into a file.
1005
    
1006
    Parameters:
1007
    - repo: Repository object or path
1008
    - object_ids: List of object ids to write
1009
    - packf: File-like object to write to
1010
    - idxf: File-like object to write to (can be None)
1011
    - delta_window_size: Sliding window size for searching deltas
1012
    - deltify: Whether to deltify objects
1013
    - reuse_deltas: Allow reuse of existing deltas while deltifying
1014
    - pack_index_version: Pack index version to use (1, 2, or 3)
1015
    """
1016

1017
def unpack_objects(pack_path, target: str = ".") -> int:
1018
    """
1019
    Unpack objects from a pack file into the repository.
1020
    
1021
    Parameters:
1022
    - pack_path: Path to the pack file to unpack
1023
    - target: Path to the repository to unpack into
1024
    
1025
    Returns:
1026
    Number of objects unpacked
1027
    """
1028

1029
def count_objects(repo: RepoPath = ".", verbose: bool = False) -> CountObjectsResult:
1030
    """
1031
    Count unpacked objects and their disk usage.
1032
    
1033
    Parameters:
1034
    - repo: Repository object or path
1035
    - verbose: Whether to return verbose information
1036
    
1037
    Returns:
1038
    CountObjectsResult object with detailed statistics
1039
    """
1040

1041
def fsck(repo: RepoPath) -> Iterator[tuple[bytes, Exception]]:
1042
    """
1043
    Check a repository for errors.
1044
    
1045
    Parameters:
1046
    - repo: Repository object or path
1047
    
1048
    Returns:
1049
    Iterator over errors/warnings as (sha, exception) tuples
1050
    """
1051

1052
def archive(
1053
    repo,
1054
    committish: Optional[Union[str, bytes, Commit, Tag]] = None,
1055
    outstream = default_bytes_out_stream,
1056
    errstream = default_bytes_err_stream,
1057
) -> None:
1058
    """
1059
    Create an archive.
1060
    
1061
    Parameters:
1062
    - repo: Repository object or path
1063
    - committish: Commit SHA1 or ref to use
1064
    - outstream: Output stream (defaults to stdout)
1065
    - errstream: Error stream (defaults to stderr)
1066
    """
1067

1068
def update_server_info(repo: RepoPath = ".") -> None:
1069
    """
1070
    Update server info files for a repository.
1071
    
1072
    Parameters:
1073
    - repo: Repository object or path
1074
    """
1075

1076
def write_commit_graph(repo: RepoPath = ".", reachable: bool = True) -> None:
1077
    """
1078
    Write a commit graph file for a repository.
1079
    
1080
    Parameters:
1081
    - repo: Repository object or path
1082
    - reachable: If True, include all commits reachable from refs
1083
    """
1084

1085
def pack_refs(repo: RepoPath, all: bool = False) -> None:
1086
    """
1087
    Pack references into a single file for efficiency.
1088
    
1089
    Parameters:
1090
    - repo: Repository object or path
1091
    - all: Pack all refs, not just heads and tags
1092
    """
1093

1094
def write_tree(repo: RepoPath) -> bytes:
1095
    """
1096
    Write a tree object from the index.
1097
    
1098
    Parameters:
1099
    - repo: Repository for which to write tree
1100
    
1101
    Returns:
1102
    Tree id for the tree that was written
1103
    """
1104
```
1105

1106
### Submodule Operations
1107

1108
Manage Git submodules within repositories.
1109

1110
```python { .api }
1111
def submodule_add(
1112
    repo: Union[str, os.PathLike, Repo],
1113
    url,
1114
    path = None,
1115
    name = None,
1116
) -> None:
1117
    """
1118
    Add a new submodule.
1119
    
1120
    Parameters:
1121
    - repo: Repository object or path
1122
    - url: URL of repository to add as submodule
1123
    - path: Path where submodule should live
1124
    - name: Name for the submodule
1125
    """
1126

1127
def submodule_init(repo: Union[str, os.PathLike, Repo]) -> None:
1128
    """
1129
    Initialize submodules.
1130
    
1131
    Parameters:
1132
    - repo: Repository object or path
1133
    """
1134

1135
def submodule_list(repo: RepoPath) -> Iterator[tuple[str, str]]:
1136
    """
1137
    List submodules.
1138
    
1139
    Parameters:
1140
    - repo: Repository object or path
1141
    
1142
    Returns:
1143
    Iterator of (path, sha) tuples
1144
    """
1145

1146
def submodule_update(
1147
    repo: Union[str, os.PathLike, Repo],
1148
    paths = None,
1149
    init: bool = False,
1150
    force: bool = False,
1151
    errstream = None,
1152
) -> None:
1153
    """
1154
    Update submodules.
1155
    
1156
    Parameters:
1157
    - repo: Repository object or path
1158
    - paths: Optional list of specific submodule paths to update
1159
    - init: If True, initialize submodules first
1160
    - force: Force update even if local changes exist
1161
    - errstream: Error stream for output
1162
    """
1163
```
1164

1165
### LFS Operations
1166

1167
Complete Git LFS (Large File Storage) support functions.
1168

1169
```python { .api }
1170
def lfs_init(repo: Union[str, os.PathLike, Repo] = ".") -> None:
1171
    """
1172
    Initialize Git LFS in a repository.
1173
    
1174
    Parameters:
1175
    - repo: Repository object or path
1176
    """
1177

1178
def lfs_track(
1179
    repo: Union[str, os.PathLike, Repo] = ".",
1180
    patterns = None,
1181
) -> list[str]:
1182
    """
1183
    Track file patterns with Git LFS.
1184
    
1185
    Parameters:
1186
    - repo: Repository object or path
1187
    - patterns: List of file patterns to track (e.g., ["*.bin", "*.pdf"])
1188
    
1189
    Returns:
1190
    List of tracked patterns
1191
    """
1192

1193
def lfs_untrack(
1194
    repo: Union[str, os.PathLike, Repo] = ".",
1195
    patterns = None,
1196
) -> list[str]:
1197
    """
1198
    Untrack file patterns from Git LFS.
1199
    
1200
    Parameters:
1201
    - repo: Repository object or path
1202
    - patterns: List of file patterns to untrack
1203
    
1204
    Returns:
1205
    List of remaining tracked patterns
1206
    """
1207

1208
def lfs_clean(
1209
    repo: Union[str, os.PathLike, Repo] = ".",
1210
    path = None,
1211
) -> bytes:
1212
    """
1213
    Clean a file by converting it to an LFS pointer.
1214
    
1215
    Parameters:
1216
    - repo: Repository object or path
1217
    - path: Path to file to clean (relative to repo root)
1218
    
1219
    Returns:
1220
    LFS pointer content as bytes
1221
    """
1222

1223
def lfs_smudge(
1224
    repo: Union[str, os.PathLike, Repo] = ".",
1225
    pointer_content = None,
1226
) -> bytes:
1227
    """
1228
    Smudge an LFS pointer by retrieving the actual content.
1229
    
1230
    Parameters:
1231
    - repo: Repository object or path
1232
    - pointer_content: LFS pointer content as bytes
1233
    
1234
    Returns:
1235
    Actual file content as bytes
1236
    """
1237

1238
def lfs_ls_files(
1239
    repo: Union[str, os.PathLike, Repo] = ".",
1240
    ref = None,
1241
) -> list[tuple[str, str, int]]:
1242
    """
1243
    List files tracked by Git LFS.
1244
    
1245
    Parameters:
1246
    - repo: Repository object or path
1247
    - ref: Git ref to check (defaults to HEAD)
1248
    
1249
    Returns:
1250
    List of (path, oid, size) tuples for LFS files
1251
    """
1252

1253
def lfs_migrate(
1254
    repo: Union[str, os.PathLike, Repo] = ".",
1255
    include = None,
1256
    exclude = None,
1257
    everything: bool = False,
1258
) -> int:
1259
    """
1260
    Migrate files to Git LFS.
1261
    
1262
    Parameters:
1263
    - repo: Repository object or path
1264
    - include: Patterns of files to include
1265
    - exclude: Patterns of files to exclude
1266
    - everything: Migrate all files above a certain size
1267
    
1268
    Returns:
1269
    Number of migrated files
1270
    """
1271

1272
def lfs_fetch(
1273
    repo: Union[str, os.PathLike, Repo] = ".",
1274
    remote: str = "origin",
1275
    refs = None,
1276
) -> int:
1277
    """
1278
    Fetch LFS objects from remote.
1279
    
1280
    Parameters:
1281
    - repo: Repository object or path
1282
    - remote: Remote name (default: origin)
1283
    - refs: Specific refs to fetch LFS objects for (default: all refs)
1284
    
1285
    Returns:
1286
    Number of objects fetched
1287
    """
1288

1289
def lfs_pull(
1290
    repo: Union[str, os.PathLike, Repo] = ".",
1291
    remote: str = "origin",
1292
) -> int:
1293
    """
1294
    Pull LFS objects for current checkout.
1295
    
1296
    Parameters:
1297
    - repo: Repository object or path
1298
    - remote: Remote name (default: origin)
1299
    
1300
    Returns:
1301
    Number of objects fetched
1302
    """
1303

1304
def lfs_push(
1305
    repo: Union[str, os.PathLike, Repo] = ".",
1306
    remote: str = "origin",
1307
    refs = None,
1308
) -> int:
1309
    """
1310
    Push LFS objects to remote.
1311
    
1312
    Parameters:
1313
    - repo: Repository object or path
1314
    - remote: Remote name (default: origin)
1315
    - refs: Specific refs to push LFS objects for
1316
    
1317
    Returns:
1318
    Number of objects pushed
1319
    """
1320

1321
def lfs_status(repo: Union[str, os.PathLike, Repo] = ".") -> dict[str, list[str]]:
1322
    """
1323
    Show status of LFS files.
1324
    
1325
    Parameters:
1326
    - repo: Repository object or path
1327
    
1328
    Returns:
1329
    Dict with status information
1330
    """
1331

1332
def lfs_pointer_check(
1333
    repo: Union[str, os.PathLike, Repo] = ".",
1334
    paths = None,
1335
) -> dict:
1336
    """
1337
    Check if files are valid LFS pointers.
1338
    
1339
    Parameters:
1340
    - repo: Repository object or path
1341
    - paths: List of file paths to check (if None, check all files)
1342
    
1343
    Returns:
1344
    Dict mapping paths to LFSPointer objects
1345
    """
1346
```
1347

1348
### Worktree Operations
1349

1350
Complete worktree management functions for multiple working trees.
1351

1352
```python { .api }
1353
def worktree_list(repo = ".") -> list:
1354
    """
1355
    List all worktrees for a repository.
1356
    
1357
    Parameters:
1358
    - repo: Repository object or path
1359
    
1360
    Returns:
1361
    List of WorkTreeInfo objects
1362
    """
1363

1364
def worktree_add(
1365
    repo = ".",
1366
    path = None,
1367
    branch = None,
1368
    commit = None,
1369
    detach: bool = False,
1370
    force: bool = False,
1371
) -> str:
1372
    """
1373
    Add a new worktree.
1374
    
1375
    Parameters:
1376
    - repo: Repository object or path
1377
    - path: Path for new worktree
1378
    - branch: Branch to checkout (creates if doesn't exist)
1379
    - commit: Specific commit to checkout
1380
    - detach: Create with detached HEAD
1381
    - force: Force creation even if branch is already checked out
1382
    
1383
    Returns:
1384
    Path to the newly created worktree
1385
    """
1386

1387
def worktree_remove(
1388
    repo = ".",
1389
    path = None,
1390
    force: bool = False,
1391
) -> None:
1392
    """
1393
    Remove a worktree.
1394
    
1395
    Parameters:
1396
    - repo: Repository object or path
1397
    - path: Path to worktree to remove
1398
    - force: Force removal even if there are local changes
1399
    """
1400

1401
def worktree_prune(
1402
    repo = ".",
1403
    dry_run: bool = False,
1404
    expire = None,
1405
) -> list[str]:
1406
    """
1407
    Prune worktree administrative files.
1408
    
1409
    Parameters:
1410
    - repo: Repository object or path
1411
    - dry_run: Only show what would be removed
1412
    - expire: Only prune worktrees older than this many seconds
1413
    
1414
    Returns:
1415
    List of pruned worktree names
1416
    """
1417

1418
def worktree_lock(
1419
    repo = ".",
1420
    path = None,
1421
    reason = None,
1422
) -> None:
1423
    """
1424
    Lock a worktree to prevent it from being pruned.
1425
    
1426
    Parameters:
1427
    - repo: Repository object or path
1428
    - path: Path to worktree to lock
1429
    - reason: Optional reason for locking
1430
    """
1431

1432
def worktree_unlock(
1433
    repo = ".",
1434
    path = None,
1435
) -> None:
1436
    """
1437
    Unlock a worktree.
1438
    
1439
    Parameters:
1440
    - repo: Repository object or path
1441
    - path: Path to worktree to unlock
1442
    """
1443

1444
def worktree_move(
1445
    repo = ".",
1446
    old_path = None,
1447
    new_path = None,
1448
) -> None:
1449
    """
1450
    Move a worktree to a new location.
1451
    
1452
    Parameters:
1453
    - repo: Repository object or path
1454
    - old_path: Current path of worktree
1455
    - new_path: New path for worktree
1456
    """
1457
```
1458

1459
### Utility Functions
1460

1461
Helpful utility functions for repository analysis and operations.
1462

1463
```python { .api }
1464
def reflog(
1465
    repo: RepoPath = ".",
1466
    ref: bytes = b"HEAD",
1467
    all: bool = False,
1468
) -> Iterator:
1469
    """
1470
    Show reflog entries for a reference or all references.
1471
    
1472
    Parameters:
1473
    - repo: Repository object or path
1474
    - ref: Reference name (defaults to HEAD)
1475
    - all: If True, show reflogs for all refs
1476
    
1477
    Returns:
1478
    Iterator over ReflogEntry objects or (ref_name, ReflogEntry) tuples
1479
    """
1480

1481
def check_ignore(
1482
    repo: RepoPath,
1483
    paths,
1484
    no_index: bool = False,
1485
    quote_path: bool = True,
1486
) -> Iterator[str]:
1487
    """
1488
    Debug gitignore files.
1489
    
1490
    Parameters:
1491
    - repo: Repository object or path
1492
    - paths: List of paths to check for
1493
    - no_index: Don't check index
1494
    - quote_path: If True, quote non-ASCII characters in returned paths
1495
    
1496
    Returns:
1497
    Iterator over ignored files
1498
    """
1499

1500
def annotate(
1501
    repo: RepoPath,
1502
    path,
1503
    committish: Optional[Union[str, bytes, Commit, Tag]] = None,
1504
) -> list:
1505
    """
1506
    Annotate the history of a file (blame).
1507
    
1508
    Parameters:
1509
    - repo: Repository object or path
1510
    - path: Path to annotate
1511
    - committish: Commit id to find path in
1512
    
1513
    Returns:
1514
    List of ((Commit, TreeChange), line) tuples
1515
    """
1516

1517
def format_patch(
1518
    repo = ".",
1519
    committish = None,
1520
    outstream = sys.stdout,
1521
    outdir = None,
1522
    n: int = 1,
1523
    stdout: bool = False,
1524
    version = None,
1525
) -> list[str]:
1526
    """
1527
    Generate patches suitable for git am.
1528
    
1529
    Parameters:
1530
    - repo: Repository object or path
1531
    - committish: Commit-ish or commit range to generate patches for
1532
    - outstream: Stream to write to if stdout=True
1533
    - outdir: Directory to write patch files to
1534
    - n: Number of patches to generate if committish is None
1535
    - stdout: Write patches to stdout instead of files
1536
    - version: Version string to include in patches
1537
    
1538
    Returns:
1539
    List of patch filenames that were created
1540
    """
1541

1542
def filter_branch(
1543
    repo = ".",
1544
    branch = "HEAD",
1545
    filter_fn = None,
1546
    filter_author = None,
1547
    filter_committer = None,
1548
    filter_message = None,
1549
    tree_filter = None,
1550
    index_filter = None,
1551
    parent_filter = None,
1552
    commit_filter = None,
1553
    subdirectory_filter = None,
1554
    prune_empty: bool = False,
1555
    tag_name_filter = None,
1556
    force: bool = False,
1557
    keep_original: bool = True,
1558
    refs = None,
1559
) -> dict:
1560
    """
1561
    Rewrite branch history by creating new commits with filtered properties.
1562
    
1563
    Parameters:
1564
    - repo: Repository object or path
1565
    - branch: Branch to rewrite (defaults to HEAD)
1566
    - filter_fn: Optional callable to filter commit properties
1567
    - filter_author: Optional callable to filter author
1568
    - filter_committer: Optional callable to filter committer
1569
    - filter_message: Optional callable to filter commit message
1570
    - tree_filter: Optional callable for tree modifications
1571
    - index_filter: Optional callable for index modifications
1572
    - parent_filter: Optional callable to modify parent list
1573
    - commit_filter: Optional callable for commit filtering
1574
    - subdirectory_filter: Optional subdirectory path to extract
1575
    - prune_empty: Whether to prune commits that become empty
1576
    - tag_name_filter: Optional callable to rename tags
1577
    - force: Force operation even if branch has been filtered
1578
    - keep_original: Keep original refs under refs/original/
1579
    - refs: List of refs to rewrite
1580
    
1581
    Returns:
1582
    Dict mapping old commit SHAs to new commit SHAs
1583
    """
1584

1585
def for_each_ref(
1586
    repo: Union[Repo, str] = ".",
1587
    pattern: Optional[Union[str, bytes]] = None,
1588
) -> list[tuple[bytes, bytes, bytes]]:
1589
    """
1590
    Iterate over all refs that match the (optional) pattern.
1591
    
1592
    Parameters:
1593
    - repo: Repository object or path
1594
    - pattern: Optional glob patterns to filter the refs with
1595
    
1596
    Returns:
1597
    List of bytes tuples with: (sha, object_type, ref_name)
1598
    """
1599

1600
def ls_files(repo: RepoPath) -> list[bytes]:
1601
    """
1602
    List all files in an index.
1603
    
1604
    Parameters:
1605
    - repo: Repository object or path
1606
    
1607
    Returns:
1608
    Sorted list of file paths in the index
1609
    """
1610

1611
def ls_tree(
1612
    repo,
1613
    treeish: Union[str, bytes, Commit, Tree, Tag] = b"HEAD",
1614
    outstream = sys.stdout,
1615
    recursive: bool = False,
1616
    name_only: bool = False,
1617
) -> None:
1618
    """
1619
    List contents of a tree.
1620
    
1621
    Parameters:
1622
    - repo: Repository object or path
1623
    - treeish: Tree id to list
1624
    - outstream: Output stream (defaults to stdout)
1625
    - recursive: Whether to recursively list files
1626
    - name_only: Only print item name
1627
    """
1628

1629
def rev_list(
1630
    repo: RepoPath,
1631
    commits,
1632
    outstream = sys.stdout,
1633
) -> None:
1634
    """
1635
    Lists commit objects in reverse chronological order.
1636
    
1637
    Parameters:
1638
    - repo: Repository object or path
1639
    - commits: Commits over which to iterate
1640
    - outstream: Stream to write to
1641
    """
1642

1643
def get_object_by_path(
1644
    repo,
1645
    path,
1646
    committish: Optional[Union[str, bytes, Commit, Tag]] = None,
1647
):
1648
    """
1649
    Get an object by path.
1650
    
1651
    Parameters:
1652
    - repo: Repository object or path
1653
    - path: Path to look up
1654
    - committish: Commit to look up path in
1655
    
1656
    Returns:
1657
    A ShaFile object
1658
    """
1659

1660
def find_unique_abbrev(
1661
    object_store,
1662
    object_id,
1663
    min_length: int = 7,
1664
) -> str:
1665
    """
1666
    Find the shortest unique abbreviation for an object ID.
1667
    
1668
    Parameters:
1669
    - object_store: Object store to search in
1670
    - object_id: The full object ID to abbreviate
1671
    - min_length: Minimum length of abbreviation (default 7)
1672
    
1673
    Returns:
1674
    The shortest unique prefix of the object ID
1675
    """
1676

1677
def check_mailmap(repo: RepoPath, contact) -> str:
1678
    """
1679
    Check canonical name and email of contact.
1680
    
1681
    Parameters:
1682
    - repo: Repository object or path
1683
    - contact: Contact name and/or email
1684
    
1685
    Returns:
1686
    Canonical contact data
1687
    """
1688

1689
def get_branch_remote(repo: Union[str, os.PathLike, Repo]) -> bytes:
1690
    """
1691
    Return the active branch's remote name, if any.
1692
    
1693
    Parameters:
1694
    - repo: Repository to open
1695
    
1696
    Returns:
1697
    Remote name
1698
    """
1699

1700
def get_branch_merge(
1701
    repo: RepoPath,
1702
    branch_name = None,
1703
) -> bytes:
1704
    """
1705
    Return the branch's merge reference (upstream branch), if any.
1706
    
1707
    Parameters:
1708
    - repo: Repository to open
1709
    - branch_name: Name of the branch (defaults to active branch)
1710
    
1711
    Returns:
1712
    Merge reference name (e.g. b"refs/heads/main")
1713
    """
1714

1715
def set_branch_tracking(
1716
    repo: Union[str, os.PathLike, Repo],
1717
    branch_name,
1718
    remote_name,
1719
    remote_ref,
1720
) -> None:
1721
    """
1722
    Set up branch tracking configuration.
1723
    
1724
    Parameters:
1725
    - repo: Repository to open
1726
    - branch_name: Name of the local branch
1727
    - remote_name: Name of the remote (e.g. b"origin")
1728
    - remote_ref: Remote reference to track (e.g. b"refs/heads/main")
1729
    """
1730

1731
def symbolic_ref(
1732
    repo: RepoPath,
1733
    ref_name,
1734
    force: bool = False,
1735
) -> None:
1736
    """
1737
    Set git symbolic ref into HEAD.
1738
    
1739
    Parameters:
1740
    - repo: Repository object or path
1741
    - ref_name: Short name of the new ref
1742
    - force: Force settings without checking if it exists in refs/heads
1743
    """
1744

1745
def update_head(
1746
    repo: RepoPath,
1747
    target,
1748
    detached: bool = False,
1749
    new_branch = None,
1750
) -> None:
1751
    """
1752
    Update HEAD to point at a new branch/commit.
1753
    
1754
    Parameters:
1755
    - repo: Repository object or path
1756
    - target: Branch or committish to switch to
1757
    - detached: Create a detached head
1758
    - new_branch: New branch to create
1759
    """
1760
```
1761

1762
### Server Operations
1763

1764
Git protocol server and daemon functionality.
1765

1766
```python { .api }
1767
def daemon(
1768
    path = ".",
1769
    address = None,
1770
    port = None,
1771
) -> None:
1772
    """
1773
    Run a daemon serving Git requests over TCP/IP.
1774
    
1775
    Parameters:
1776
    - path: Path to the directory to serve
1777
    - address: Optional address to listen on (defaults to ::)
1778
    - port: Optional port to listen on (defaults to TCP_GIT_PORT)
1779
    """
1780

1781
def web_daemon(
1782
    path = ".",
1783
    address = None,
1784
    port = None,
1785
) -> None:
1786
    """
1787
    Run a daemon serving Git requests over HTTP.
1788
    
1789
    Parameters:
1790
    - path: Path to the directory to serve
1791
    - address: Optional address to listen on (defaults to ::)
1792
    - port: Optional port to listen on (defaults to 80)
1793
    """
1794

1795
def upload_pack(
1796
    path = ".",
1797
    inf = None,
1798
    outf = None,
1799
) -> int:
1800
    """
1801
    Upload a pack file after negotiating its contents using smart protocol.
1802
    
1803
    Parameters:
1804
    - path: Path to the repository
1805
    - inf: Input stream to communicate with client
1806
    - outf: Output stream to communicate with client
1807
    
1808
    Returns:
1809
    Exit code (0 for success)
1810
    """
1811

1812
def receive_pack(
1813
    path = ".",
1814
    inf = None,
1815
    outf = None,
1816
) -> int:
1817
    """
1818
    Receive a pack file after negotiating its contents using smart protocol.
1819
    
1820
    Parameters:
1821
    - path: Path to the repository
1822
    - inf: Input stream to communicate with client
1823
    - outf: Output stream to communicate with client
1824
    
1825
    Returns:
1826
    Exit code (0 for success)
1827
    """
1828
```
1829

1830
### Sparse Checkout Operations
1831

1832
Manage sparse checkout patterns for partial working trees.
1833

1834
```python { .api }
1835
def sparse_checkout(
1836
    repo: Union[str, os.PathLike, Repo],
1837
    patterns = None,
1838
    force: bool = False,
1839
    cone: Union[bool, None] = None,
1840
) -> None:
1841
    """
1842
    Perform a sparse checkout in the repository.
1843
    
1844
    Parameters:
1845
    - repo: Repository object or path
1846
    - patterns: Optional list of sparse-checkout patterns to write
1847
    - force: Whether to force removal of locally modified files
1848
    - cone: Boolean indicating cone mode (True/False). If None, read from config
1849
    """
1850

1851
def cone_mode_init(repo: Union[str, os.PathLike, Repo]) -> None:
1852
    """
1853
    Initialize a repository to use sparse checkout in 'cone' mode.
1854
    
1855
    Parameters:
1856
    - repo: Repository object or path
1857
    """
1858

1859
def cone_mode_set(
1860
    repo: Union[str, os.PathLike, Repo],
1861
    dirs,
1862
    force: bool = False,
1863
) -> None:
1864
    """
1865
    Overwrite the existing 'cone-mode' sparse patterns with new directories.
1866
    
1867
    Parameters:
1868
    - repo: Repository object or path
1869
    - dirs: List of directory names to include
1870
    - force: Whether to forcibly discard local modifications
1871
    """
1872

1873
def cone_mode_add(
1874
    repo: Union[str, os.PathLike, Repo],
1875
    dirs,
1876
    force: bool = False,
1877
) -> None:
1878
    """
1879
    Add new directories to existing 'cone-mode' sparse-checkout patterns.
1880
    
1881
    Parameters:
1882
    - repo: Repository object or path
1883
    - dirs: List of directory names to add to the sparse-checkout
1884
    - force: Whether to forcibly discard local modifications
1885
    """
1886
```