0
# Repository Management
1
2
Core repository operations including initialization, opening, cloning, and basic repository information access. Provides the foundation for all Git operations through the Repository class and related functions.
3
4
## Capabilities
5
6
### Repository Creation and Access
7
8
Initialize new repositories, clone existing repositories, or open local repositories. These functions provide the primary entry points for Git operations.
9
10
```python { .api }
11
def init_repository(
12
path: str,
13
bare: bool = False,
14
flags: int = None,
15
mode: int = None,
16
workdir_path: str = None,
17
description: str = None,
18
template_path: str = None,
19
initial_head: str = None,
20
origin_url: str = None
21
) -> Repository:
22
"""
23
Create a new Git repository.
24
25
Parameters:
26
- path: Path where repository should be created
27
- bare: Create bare repository without working directory
28
- flags: Repository initialization flags
29
- mode: File permissions mode
30
- workdir_path: Path to working directory (bare repos only)
31
- description: Repository description
32
- template_path: Template directory path
33
- initial_head: Name of initial branch
34
- origin_url: URL of origin remote
35
36
Returns:
37
Repository object
38
"""
39
40
def clone_repository(
41
url: str,
42
path: str,
43
bare: bool = False,
44
repository: callable = None,
45
remote: callable = None,
46
checkout_branch: str = None,
47
callbacks: 'RemoteCallbacks' = None,
48
depth: int = 0,
49
proxy: bool | str = None
50
) -> Repository:
51
"""
52
Clone a remote repository.
53
54
Parameters:
55
- url: URL of repository to clone
56
- path: Local path for cloned repository
57
- bare: Create bare clone
58
- repository: Repository creation callback
59
- remote: Remote creation callback
60
- checkout_branch: Branch to checkout after clone
61
- callbacks: Remote operation callbacks
62
- depth: Shallow clone depth (0 = full history)
63
- proxy: Proxy configuration
64
65
Returns:
66
Repository object
67
"""
68
69
def discover_repository(path: str) -> str:
70
"""
71
Find the path of the Git repository containing the given path.
72
73
Parameters:
74
- path: Starting path for repository search
75
76
Returns:
77
Path to .git directory
78
"""
79
```
80
81
### Repository Class
82
83
The main interface for Git repository operations, providing access to all repository components and metadata.
84
85
```python { .api }
86
class Repository:
87
def __init__(self, path: str):
88
"""
89
Open existing Git repository.
90
91
Parameters:
92
- path: Path to repository or .git directory
93
"""
94
95
# Repository Properties
96
@property
97
def path(self) -> str:
98
"""Path to .git directory"""
99
100
@property
101
def workdir(self) -> str:
102
"""Path to working directory (None for bare repos)"""
103
104
@property
105
def is_bare(self) -> bool:
106
"""True if repository is bare"""
107
108
@property
109
def is_empty(self) -> bool:
110
"""True if repository has no commits"""
111
112
@property
113
def is_shallow(self) -> bool:
114
"""True if repository is shallow clone"""
115
116
@property
117
def head(self) -> Reference:
118
"""Reference to current HEAD"""
119
120
@property
121
def head_is_unborn(self) -> bool:
122
"""True if HEAD points to unborn branch"""
123
124
@property
125
def head_is_detached(self) -> bool:
126
"""True if HEAD is detached"""
127
128
# Repository Collections
129
@property
130
def references(self) -> References:
131
"""Repository references collection"""
132
133
@property
134
def branches(self) -> Branches:
135
"""Repository branches collection"""
136
137
@property
138
def remotes(self) -> RemoteCollection:
139
"""Repository remotes collection"""
140
141
@property
142
def config(self) -> Config:
143
"""Repository configuration"""
144
145
@property
146
def index(self) -> Index:
147
"""Repository index (staging area)"""
148
149
@property
150
def odb(self) -> Odb:
151
"""Object database"""
152
153
# Repository State
154
@property
155
def state(self) -> int:
156
"""Current repository state (merge, rebase, etc.)"""
157
158
def state_cleanup(self):
159
"""Clean up repository state after operations"""
160
161
# Object Access
162
def __getitem__(self, oid: str | Oid) -> Object:
163
"""Get object by OID"""
164
165
def __contains__(self, oid: str | Oid) -> bool:
166
"""Check if object exists in repository"""
167
168
def get(self, oid: str | Oid, default=None) -> Object:
169
"""Get object by OID with default"""
170
171
def revparse_single(self, revision: str) -> Object:
172
"""Parse revision string to single object"""
173
174
def revparse(self, revision: str) -> RevSpec:
175
"""Parse revision string"""
176
177
# Object Creation
178
def create_blob(self, data: bytes) -> Oid:
179
"""Create blob object from data"""
180
181
def create_blob_fromworkdir(self, path: str) -> Oid:
182
"""Create blob from working directory file"""
183
184
def create_blob_fromdisk(self, path: str) -> Oid:
185
"""Create blob from disk file"""
186
187
def create_blob_fromiobase(self, file: 'IO') -> Oid:
188
"""Create blob from IO stream"""
189
190
def create_tree(self, tree_builder: TreeBuilder) -> Oid:
191
"""Create tree object"""
192
193
def create_commit(
194
self,
195
update_ref: str,
196
author: Signature,
197
committer: Signature,
198
message: str,
199
tree: Oid,
200
parents: list[Oid]
201
) -> Oid:
202
"""Create commit object"""
203
204
def create_tag(
205
self,
206
name: str,
207
target: Oid,
208
tagger: Signature,
209
message: str,
210
force: bool = False
211
) -> Oid:
212
"""Create tag object"""
213
214
def create_branch(
215
self,
216
name: str,
217
commit: Commit,
218
force: bool = False
219
) -> Branch:
220
"""Create new branch"""
221
222
def create_reference_direct(
223
self,
224
name: str,
225
target: Oid,
226
force: bool = False,
227
message: str = None
228
) -> Reference:
229
"""Create direct reference"""
230
231
def create_reference_symbolic(
232
self,
233
name: str,
234
target: str,
235
force: bool = False,
236
message: str = None
237
) -> Reference:
238
"""Create symbolic reference"""
239
240
# Working Directory Operations
241
def status(self) -> dict[str, int]:
242
"""Get working directory status"""
243
244
def status_file(self, path: str) -> int:
245
"""Get status of single file"""
246
247
def checkout_head(self, **kwargs):
248
"""Checkout HEAD to working directory"""
249
250
def checkout_tree(self, treeish: Object, **kwargs):
251
"""Checkout tree to working directory"""
252
253
def checkout_index(self, **kwargs):
254
"""Checkout index to working directory"""
255
256
def reset(self, oid: Oid, reset_type: int):
257
"""Reset repository to commit"""
258
259
# Diff Operations
260
def diff(
261
self,
262
a: Object | str = None,
263
b: Object | str = None,
264
cached: bool = False,
265
**kwargs
266
) -> Diff:
267
"""Create diff between objects/trees"""
268
269
# Merge Operations
270
def merge_analysis(self, their_heads: list[Oid]) -> tuple[int, int]:
271
"""Analyze merge possibility"""
272
273
def merge(self, oid: Oid, **kwargs):
274
"""Perform merge operation"""
275
276
def merge_commits(self, our_commit: Oid, their_commit: Oid) -> Index:
277
"""Merge two commits"""
278
279
def merge_trees(
280
self,
281
ancestor: Oid,
282
ours: Oid,
283
theirs: Oid
284
) -> Index:
285
"""Merge three trees"""
286
287
# Search and History
288
def walk(self, oid: Oid, sort: int = None) -> Walker:
289
"""Create commit walker"""
290
291
def ahead_behind(self, local: Oid, upstream: Oid) -> tuple[int, int]:
292
"""Count commits ahead/behind"""
293
294
def descendant_of(self, commit: Oid, ancestor: Oid) -> bool:
295
"""Check if commit is descendant of ancestor"""
296
297
# Advanced Operations
298
def blame(
299
self,
300
path: str,
301
flags: int = None,
302
min_match_characters: int = None,
303
newest_commit: Oid = None,
304
oldest_commit: Oid = None,
305
min_line: int = None,
306
max_line: int = None
307
) -> Blame:
308
"""Generate blame information for file"""
309
310
def cherry_pick(self, commit: Oid, **kwargs):
311
"""Cherry-pick commit"""
312
313
def revert(self, commit: Oid, **kwargs):
314
"""Revert commit"""
315
316
def apply(self, diff: Diff, location: int = None):
317
"""Apply diff/patch"""
318
```
319
320
### Repository State Management
321
322
```python { .api }
323
# Repository State Constants
324
GIT_REPOSITORY_STATE_NONE: int
325
GIT_REPOSITORY_STATE_MERGE: int
326
GIT_REPOSITORY_STATE_REVERT: int
327
GIT_REPOSITORY_STATE_REBASE: int
328
GIT_REPOSITORY_STATE_BISECT: int
329
GIT_REPOSITORY_STATE_CHERRYPICK: int
330
GIT_REPOSITORY_STATE_APPLY_MAILBOX: int
331
332
# Reset Types
333
GIT_RESET_SOFT: int # Move HEAD only
334
GIT_RESET_MIXED: int # Move HEAD and index
335
GIT_RESET_HARD: int # Move HEAD, index, and working dir
336
```
337
338
### Usage Examples
339
340
#### Basic Repository Operations
341
342
```python
343
import pygit2
344
345
# Initialize new repository
346
repo = pygit2.init_repository('/path/to/new/repo')
347
348
# Open existing repository
349
repo = pygit2.Repository('/path/to/existing/repo')
350
351
# Clone repository
352
repo = pygit2.clone_repository(
353
'https://github.com/user/repo.git',
354
'/local/clone/path',
355
callbacks=pygit2.RemoteCallbacks()
356
)
357
358
# Check repository properties
359
print(f"Repository path: {repo.path}")
360
print(f"Working directory: {repo.workdir}")
361
print(f"Is bare: {repo.is_bare}")
362
print(f"Is empty: {repo.is_empty}")
363
```
364
365
#### Object Access and Creation
366
367
```python
368
# Get objects by OID
369
commit = repo[repo.head.target]
370
tree = repo[commit.tree]
371
372
# Create new blob
373
blob_oid = repo.create_blob(b"Hello, World!")
374
375
# Create signature
376
signature = pygit2.Signature('Author', 'author@example.com')
377
378
# Create commit
379
tree_oid = repo.index.write_tree()
380
commit_oid = repo.create_commit(
381
'HEAD',
382
signature,
383
signature,
384
'Commit message',
385
tree_oid,
386
[] # No parents for initial commit
387
)
388
```
389
390
#### Working Directory Status
391
392
```python
393
# Get repository status
394
status = repo.status()
395
for filepath, flags in status.items():
396
if flags & pygit2.GIT_STATUS_WT_NEW:
397
print(f"New file: {filepath}")
398
elif flags & pygit2.GIT_STATUS_WT_MODIFIED:
399
print(f"Modified file: {filepath}")
400
elif flags & pygit2.GIT_STATUS_WT_DELETED:
401
print(f"Deleted file: {filepath}")
402
403
# Check single file status
404
file_status = repo.status_file('README.md')
405
if file_status & pygit2.GIT_STATUS_WT_MODIFIED:
406
print("README.md is modified")
407
```