0
# Git Operations
1
2
Low-level Git object access including blobs, trees, commits, references, and tags for advanced repository manipulation and Git operations.
3
4
## Capabilities
5
6
### Git Object Access
7
8
Accessing low-level Git objects (blobs, trees, commits, tags).
9
10
```python { .api }
11
class Repository:
12
def git_blob(self, sha):
13
"""
14
Get a Git blob object.
15
16
Args:
17
sha (str): SHA of the blob
18
19
Returns:
20
Blob: Blob object or None
21
"""
22
23
def git_tree(self, sha, recursive=False):
24
"""
25
Get a Git tree object.
26
27
Args:
28
sha (str): SHA of the tree
29
recursive (bool): Get tree recursively
30
31
Returns:
32
Tree: Tree object or None
33
"""
34
35
def git_commit(self, sha):
36
"""
37
Get a Git commit object.
38
39
Args:
40
sha (str): SHA of the commit
41
42
Returns:
43
Commit: Commit object or None
44
"""
45
46
def git_tag(self, sha):
47
"""
48
Get a Git tag object.
49
50
Args:
51
sha (str): SHA of the tag
52
53
Returns:
54
Tag: Tag object or None
55
"""
56
```
57
58
### References Management
59
60
Managing Git references (branches, tags, etc.).
61
62
```python { .api }
63
class Repository:
64
def refs(self, subspace=""):
65
"""
66
List Git references.
67
68
Args:
69
subspace (str, optional): Reference subspace ('heads', 'tags', etc.)
70
71
Returns:
72
iterator: Iterator of Reference objects
73
"""
74
75
def ref(self, ref):
76
"""
77
Get a specific reference.
78
79
Args:
80
ref (str): Reference name (e.g., 'heads/master', 'tags/v1.0')
81
82
Returns:
83
Reference: Reference object or None
84
"""
85
86
def create_ref(self, ref, sha):
87
"""
88
Create a new reference.
89
90
Args:
91
ref (str): Reference name (e.g., 'refs/heads/new-branch')
92
sha (str): SHA to point to
93
94
Returns:
95
Reference: Created reference object
96
"""
97
98
class Reference:
99
def update(self, sha, force=False):
100
"""
101
Update this reference to point to a new SHA.
102
103
Args:
104
sha (str): New SHA to point to
105
force (bool): Force update even if not fast-forward
106
107
Returns:
108
bool: True if successful
109
"""
110
111
def delete(self):
112
"""
113
Delete this reference.
114
115
Returns:
116
bool: True if successful
117
"""
118
```
119
120
### Commit Operations
121
122
Creating and managing commits.
123
124
```python { .api }
125
class Repository:
126
def create_commit(self, message, tree, parents, author=None, committer=None):
127
"""
128
Create a new commit.
129
130
Args:
131
message (str): Commit message
132
tree (str): SHA of the tree object
133
parents (list): List of parent commit SHAs
134
author (dict, optional): Author information
135
committer (dict, optional): Committer information
136
137
Returns:
138
Commit: Created commit object
139
"""
140
141
def create_tree(self, tree, base_tree=None):
142
"""
143
Create a new tree.
144
145
Args:
146
tree (list): List of tree entries
147
base_tree (str, optional): Base tree SHA
148
149
Returns:
150
Tree: Created tree object
151
"""
152
153
def create_blob(self, content, encoding="utf-8"):
154
"""
155
Create a new blob.
156
157
Args:
158
content (str or bytes): Blob content
159
encoding (str): Content encoding
160
161
Returns:
162
Blob: Created blob object
163
"""
164
```
165
166
### Tag Operations
167
168
Creating and managing Git tags.
169
170
```python { .api }
171
class Repository:
172
def create_tag(self, tag, message, sha, obj_type, tagger, lightweight=False):
173
"""
174
Create a Git tag.
175
176
Args:
177
tag (str): Tag name
178
message (str): Tag message
179
sha (str): SHA of object to tag
180
obj_type (str): Object type ('commit', 'tree', 'blob')
181
tagger (dict): Tagger information
182
lightweight (bool): Create lightweight tag
183
184
Returns:
185
Tag: Created tag object
186
"""
187
188
def tags(self):
189
"""
190
List repository tags.
191
192
Returns:
193
iterator: Iterator of RepoTag objects
194
"""
195
196
def tag(self, name):
197
"""
198
Get a tag by name.
199
200
Args:
201
name (str): Tag name
202
203
Returns:
204
RepoTag: Tag object or None
205
"""
206
```
207
208
## Git Object Model Classes
209
210
```python { .api }
211
class Blob:
212
"""Git blob object (file content)."""
213
sha: str
214
size: int
215
encoding: str
216
content: str
217
url: str
218
219
class Tree:
220
"""Git tree object (directory)."""
221
sha: str
222
url: str
223
tree: list # List of tree entries
224
truncated: bool
225
226
class TreeEntry:
227
"""Entry in a Git tree."""
228
path: str
229
mode: str
230
type: str # 'blob', 'tree'
231
size: int
232
sha: str
233
url: str
234
235
class CommitTree(Tree):
236
"""Tree in commit context."""
237
pass
238
239
class Commit:
240
"""Git commit object."""
241
sha: str
242
url: str
243
html_url: str
244
author: dict # name, email, date
245
committer: dict # name, email, date
246
message: str
247
tree: 'CommitTree'
248
parents: list # List of parent commits
249
verification: dict # Signature verification info
250
251
class Reference:
252
"""Git reference (branch/tag)."""
253
ref: str
254
url: str
255
object: dict # type, sha, url
256
257
def update(self, sha, force=False): ...
258
def delete(self): ...
259
260
class Tag:
261
"""Git annotated tag object."""
262
sha: str
263
url: str
264
tag: str
265
message: str
266
tagger: dict # name, email, date
267
object: dict # type, sha, url
268
verification: dict
269
270
class RepoTag:
271
"""Repository tag."""
272
name: str
273
commit: 'ShortCommit'
274
zipball_url: str
275
tarball_url: str
276
277
class GitObject:
278
"""Generic Git object."""
279
sha: str
280
type: str
281
url: str
282
283
class Hash:
284
"""Git hash/SHA object."""
285
sha: str
286
url: str
287
```
288
289
## Advanced Git Operations
290
291
### Creating Complex Commits
292
293
```python
294
# Create a new file and commit it
295
repo = gh.repository('owner', 'repo')
296
297
# Create blob for new file content
298
blob = repo.create_blob('print("Hello, World!")')
299
300
# Get current tree
301
master_ref = repo.ref('heads/master')
302
current_commit = repo.git_commit(master_ref.object['sha'])
303
current_tree = repo.git_tree(current_commit.tree.sha)
304
305
# Create new tree with the file
306
tree_data = []
307
for entry in current_tree.tree:
308
tree_data.append({
309
'path': entry.path,
310
'mode': entry.mode,
311
'type': entry.type,
312
'sha': entry.sha
313
})
314
315
# Add new file
316
tree_data.append({
317
'path': 'hello.py',
318
'mode': '100644',
319
'type': 'blob',
320
'sha': blob.sha
321
})
322
323
# Create new tree
324
new_tree = repo.create_tree(tree_data)
325
326
# Create commit
327
commit = repo.create_commit(
328
message='Add hello.py',
329
tree=new_tree.sha,
330
parents=[current_commit.sha],
331
author={
332
'name': 'Author Name',
333
'email': 'author@example.com',
334
'date': '2023-01-01T00:00:00Z'
335
}
336
)
337
338
# Update master reference
339
master_ref.update(commit.sha)
340
```
341
342
### Working with References
343
344
```python
345
# List all references
346
for ref in repo.refs():
347
print(f"{ref.ref} -> {ref.object['sha']}")
348
349
# List only branches
350
for ref in repo.refs('heads'):
351
print(f"Branch: {ref.ref.split('/')[-1]}")
352
353
# List only tags
354
for ref in repo.refs('tags'):
355
print(f"Tag: {ref.ref.split('/')[-1]}")
356
357
# Create new branch
358
new_branch = repo.create_ref('refs/heads/feature-branch', commit.sha)
359
```