1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>GitPython Tutorial — GitPython 2.0.9dev0 documentation</title>
<link rel="stylesheet" href="_static/default.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '2.0.9dev0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="top" title="GitPython 2.0.9dev0 documentation" href="index.html" />
<link rel="next" title="API Reference" href="reference.html" />
<link rel="prev" title="Whats New in 0.3" href="whatsnew.html" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head>
<body role="document">
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="gitpython-tutorial">
<span id="tutorial-label"></span><h1>GitPython Tutorial<a class="headerlink" href="#gitpython-tutorial" title="Permalink to this headline">¶</a></h1>
<p>GitPython provides object model access to your git repository. This tutorial is composed of multiple sections, most of which explains a real-life usecase.</p>
<p>All code presented here originated from <a class="reference external" href="https://github.com/gitpython-developers/GitPython/blob/master/git/test/test_docs.py">test_docs.py</a> to assure correctness. Knowing this should also allow you to more easily run the code for your own testing purposes, all you need is a developer installation of git-python.</p>
<div class="section" id="meet-the-repo-type">
<h2>Meet the Repo type<a class="headerlink" href="#meet-the-repo-type" title="Permalink to this headline">¶</a></h2>
<p>The first step is to create a <a class="reference internal" href="reference.html#git.repo.base.Repo" title="git.repo.base.Repo"><code class="xref py py-class docutils literal"><span class="pre">git.Repo</span></code></a> object to represent your repository.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="kn">from</span> <span class="nn">git</span> <span class="kn">import</span> <span class="n">Repo</span>
<span class="n">join</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span>
<span class="c1"># rorepo is a Repo instance pointing to the git-python repository.</span>
<span class="c1"># For all you know, the first argument to Repo is a path to the repository</span>
<span class="c1"># you want to work with</span>
<span class="n">repo</span> <span class="o">=</span> <span class="n">Repo</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">rorepo</span><span class="o">.</span><span class="n">working_tree_dir</span><span class="p">)</span>
<span class="k">assert</span> <span class="ow">not</span> <span class="n">repo</span><span class="o">.</span><span class="n">bare</span>
</pre></div>
</div>
<p>In the above example, the directory <code class="docutils literal"><span class="pre">self.rorepo.working_tree_dir</span></code> equals <code class="docutils literal"><span class="pre">/Users/mtrier/Development/git-python</span></code> and is my working repository which contains the <code class="docutils literal"><span class="pre">.git</span></code> directory. You can also initialize GitPython with a <em>bare</em> repository.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="n">bare_repo</span> <span class="o">=</span> <span class="n">Repo</span><span class="o">.</span><span class="n">init</span><span class="p">(</span><span class="n">join</span><span class="p">(</span><span class="n">rw_dir</span><span class="p">,</span> <span class="s1">'bare-repo'</span><span class="p">),</span> <span class="n">bare</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="k">assert</span> <span class="n">bare_repo</span><span class="o">.</span><span class="n">bare</span>
</pre></div>
</div>
<p>A repo object provides high-level access to your data, it allows you to create and delete heads, tags and remotes and access the configuration of the repository.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="n">repo</span><span class="o">.</span><span class="n">config_reader</span><span class="p">()</span> <span class="c1"># get a config reader for read-only access</span>
<span class="n">cw</span> <span class="o">=</span> <span class="n">repo</span><span class="o">.</span><span class="n">config_writer</span><span class="p">()</span> <span class="c1"># get a config writer to change configuration</span>
<span class="n">cw</span><span class="o">.</span><span class="n">release</span><span class="p">()</span> <span class="c1"># call release() to be sure changes are written and locks are released</span>
</pre></div>
</div>
<p>Query the active branch, query untracked files or whether the repository data has been modified.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="k">assert</span> <span class="ow">not</span> <span class="n">bare_repo</span><span class="o">.</span><span class="n">is_dirty</span><span class="p">()</span> <span class="c1"># check the dirty state</span>
<span class="n">repo</span><span class="o">.</span><span class="n">untracked_files</span> <span class="c1"># retrieve a list of untracked files</span>
<span class="c1"># ['my_untracked_file']</span>
</pre></div>
</div>
<p>Clone from existing repositories or initialize new empty ones.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="n">cloned_repo</span> <span class="o">=</span> <span class="n">repo</span><span class="o">.</span><span class="n">clone</span><span class="p">(</span><span class="n">join</span><span class="p">(</span><span class="n">rw_dir</span><span class="p">,</span> <span class="s1">'to/this/path'</span><span class="p">))</span>
<span class="k">assert</span> <span class="n">cloned_repo</span><span class="o">.</span><span class="n">__class__</span> <span class="ow">is</span> <span class="n">Repo</span> <span class="c1"># clone an existing repository</span>
<span class="k">assert</span> <span class="n">Repo</span><span class="o">.</span><span class="n">init</span><span class="p">(</span><span class="n">join</span><span class="p">(</span><span class="n">rw_dir</span><span class="p">,</span> <span class="s1">'path/for/new/repo'</span><span class="p">))</span><span class="o">.</span><span class="n">__class__</span> <span class="ow">is</span> <span class="n">Repo</span>
</pre></div>
</div>
<p>Archive the repository contents to a tar file.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="n">repo</span><span class="o">.</span><span class="n">archive</span><span class="p">(</span><span class="nb">open</span><span class="p">(</span><span class="n">join</span><span class="p">(</span><span class="n">rw_dir</span><span class="p">,</span> <span class="s1">'repo.tar'</span><span class="p">),</span> <span class="s1">'wb'</span><span class="p">))</span>
</pre></div>
</div>
<div class="section" id="advanced-repo-usage">
<h3>Advanced Repo Usage<a class="headerlink" href="#advanced-repo-usage" title="Permalink to this headline">¶</a></h3>
<p>And of course, there is much more you can do with this type, most of the following will be explained in greater detail in specific tutorials. Don’t worry if you don’t understand some of these examples right away, as they may require a thorough understanding of gits inner workings.</p>
<p>Query relevant repository paths ...</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="k">assert</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">isdir</span><span class="p">(</span><span class="n">cloned_repo</span><span class="o">.</span><span class="n">working_tree_dir</span><span class="p">)</span> <span class="c1"># directory with your work files</span>
<span class="k">assert</span> <span class="n">cloned_repo</span><span class="o">.</span><span class="n">git_dir</span><span class="o">.</span><span class="n">startswith</span><span class="p">(</span><span class="n">cloned_repo</span><span class="o">.</span><span class="n">working_tree_dir</span><span class="p">)</span> <span class="c1"># directory containing the git repository</span>
<span class="k">assert</span> <span class="n">bare_repo</span><span class="o">.</span><span class="n">working_tree_dir</span> <span class="ow">is</span> <span class="bp">None</span> <span class="c1"># bare repositories have no working tree</span>
</pre></div>
</div>
<p><a class="reference internal" href="reference.html#git.refs.head.Head" title="git.refs.head.Head"><code class="xref py py-class docutils literal"><span class="pre">Heads</span></code></a> Heads are branches in git-speak. <a class="reference internal" href="reference.html#git.refs.reference.Reference" title="git.refs.reference.Reference"><code class="xref py py-class docutils literal"><span class="pre">References</span></code></a> are pointers to a specific commit or to other references. Heads and <a class="reference internal" href="reference.html#git.refs.tag.TagReference" title="git.refs.tag.TagReference"><code class="xref py py-class docutils literal"><span class="pre">Tags</span></code></a> are a kind of references. GitPython allows you to query them rather intuitively.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="k">assert</span> <span class="n">repo</span><span class="o">.</span><span class="n">head</span><span class="o">.</span><span class="n">ref</span> <span class="o">==</span> <span class="n">repo</span><span class="o">.</span><span class="n">heads</span><span class="o">.</span><span class="n">master</span> <span class="c1"># head is a symbolic reference pointing to master</span>
<span class="k">assert</span> <span class="n">repo</span><span class="o">.</span><span class="n">tags</span><span class="p">[</span><span class="s1">'0.3.5'</span><span class="p">]</span> <span class="o">==</span> <span class="n">repo</span><span class="o">.</span><span class="n">tag</span><span class="p">(</span><span class="s1">'refs/tags/0.3.5'</span><span class="p">)</span> <span class="c1"># you can access tags in various ways too</span>
<span class="k">assert</span> <span class="n">repo</span><span class="o">.</span><span class="n">refs</span><span class="o">.</span><span class="n">master</span> <span class="o">==</span> <span class="n">repo</span><span class="o">.</span><span class="n">heads</span><span class="p">[</span><span class="s1">'master'</span><span class="p">]</span> <span class="c1"># .refs provides access to all refs, i.e. heads ...</span>
<span class="k">if</span> <span class="s1">'TRAVIS'</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">os</span><span class="o">.</span><span class="n">environ</span><span class="p">:</span>
<span class="k">assert</span> <span class="n">repo</span><span class="o">.</span><span class="n">refs</span><span class="p">[</span><span class="s1">'origin/master'</span><span class="p">]</span> <span class="o">==</span> <span class="n">repo</span><span class="o">.</span><span class="n">remotes</span><span class="o">.</span><span class="n">origin</span><span class="o">.</span><span class="n">refs</span><span class="o">.</span><span class="n">master</span> <span class="c1"># ... remotes ...</span>
<span class="k">assert</span> <span class="n">repo</span><span class="o">.</span><span class="n">refs</span><span class="p">[</span><span class="s1">'0.3.5'</span><span class="p">]</span> <span class="o">==</span> <span class="n">repo</span><span class="o">.</span><span class="n">tags</span><span class="p">[</span><span class="s1">'0.3.5'</span><span class="p">]</span> <span class="c1"># ... and tags</span>
</pre></div>
</div>
<p>You can also create new heads ...</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="n">new_branch</span> <span class="o">=</span> <span class="n">cloned_repo</span><span class="o">.</span><span class="n">create_head</span><span class="p">(</span><span class="s1">'feature'</span><span class="p">)</span> <span class="c1"># create a new branch ...</span>
<span class="k">assert</span> <span class="n">cloned_repo</span><span class="o">.</span><span class="n">active_branch</span> <span class="o">!=</span> <span class="n">new_branch</span> <span class="c1"># which wasn't checked out yet ...</span>
<span class="k">assert</span> <span class="n">new_branch</span><span class="o">.</span><span class="n">commit</span> <span class="o">==</span> <span class="n">cloned_repo</span><span class="o">.</span><span class="n">active_branch</span><span class="o">.</span><span class="n">commit</span> <span class="c1"># and which points to the checked-out commit</span>
<span class="c1"># It's easy to let a branch point to the previous commit, without affecting anything else</span>
<span class="c1"># Each reference provides access to the git object it points to, usually commits</span>
<span class="k">assert</span> <span class="n">new_branch</span><span class="o">.</span><span class="n">set_commit</span><span class="p">(</span><span class="s1">'HEAD~1'</span><span class="p">)</span><span class="o">.</span><span class="n">commit</span> <span class="o">==</span> <span class="n">cloned_repo</span><span class="o">.</span><span class="n">active_branch</span><span class="o">.</span><span class="n">commit</span><span class="o">.</span><span class="n">parents</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
</pre></div>
</div>
<p>... and tags ...</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="n">past</span> <span class="o">=</span> <span class="n">cloned_repo</span><span class="o">.</span><span class="n">create_tag</span><span class="p">(</span><span class="s1">'past'</span><span class="p">,</span> <span class="n">ref</span><span class="o">=</span><span class="n">new_branch</span><span class="p">,</span>
<span class="n">message</span><span class="o">=</span><span class="s2">"This is a tag-object pointing to </span><span class="si">%s</span><span class="s2">"</span> <span class="o">%</span> <span class="n">new_branch</span><span class="o">.</span><span class="n">name</span><span class="p">)</span>
<span class="k">assert</span> <span class="n">past</span><span class="o">.</span><span class="n">commit</span> <span class="o">==</span> <span class="n">new_branch</span><span class="o">.</span><span class="n">commit</span> <span class="c1"># the tag points to the specified commit</span>
<span class="k">assert</span> <span class="n">past</span><span class="o">.</span><span class="n">tag</span><span class="o">.</span><span class="n">message</span><span class="o">.</span><span class="n">startswith</span><span class="p">(</span><span class="s2">"This is"</span><span class="p">)</span> <span class="c1"># and its object carries the message provided</span>
<span class="n">now</span> <span class="o">=</span> <span class="n">cloned_repo</span><span class="o">.</span><span class="n">create_tag</span><span class="p">(</span><span class="s1">'now'</span><span class="p">)</span> <span class="c1"># This is a tag-reference. It may not carry meta-data</span>
<span class="k">assert</span> <span class="n">now</span><span class="o">.</span><span class="n">tag</span> <span class="ow">is</span> <span class="bp">None</span>
</pre></div>
</div>
<p>You can traverse down to <a class="reference internal" href="reference.html#git.objects.base.Object" title="git.objects.base.Object"><code class="xref py py-class docutils literal"><span class="pre">git</span> <span class="pre">objects</span></code></a> through references and other objects. Some objects like <a class="reference internal" href="reference.html#git.objects.commit.Commit" title="git.objects.commit.Commit"><code class="xref py py-class docutils literal"><span class="pre">commits</span></code></a> have additional meta-data to query.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="k">assert</span> <span class="n">now</span><span class="o">.</span><span class="n">commit</span><span class="o">.</span><span class="n">message</span> <span class="o">!=</span> <span class="n">past</span><span class="o">.</span><span class="n">commit</span><span class="o">.</span><span class="n">message</span>
<span class="c1"># You can read objects directly through binary streams, no working tree required</span>
<span class="k">assert</span> <span class="p">(</span><span class="n">now</span><span class="o">.</span><span class="n">commit</span><span class="o">.</span><span class="n">tree</span> <span class="o">/</span> <span class="s1">'VERSION'</span><span class="p">)</span><span class="o">.</span><span class="n">data_stream</span><span class="o">.</span><span class="n">read</span><span class="p">()</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s1">'ascii'</span><span class="p">)</span><span class="o">.</span><span class="n">startswith</span><span class="p">(</span><span class="s1">'2'</span><span class="p">)</span>
<span class="c1"># You can traverse trees as well to handle all contained files of a particular commit</span>
<span class="n">file_count</span> <span class="o">=</span> <span class="mi">0</span>
<span class="n">tree_count</span> <span class="o">=</span> <span class="mi">0</span>
<span class="n">tree</span> <span class="o">=</span> <span class="n">past</span><span class="o">.</span><span class="n">commit</span><span class="o">.</span><span class="n">tree</span>
<span class="k">for</span> <span class="n">item</span> <span class="ow">in</span> <span class="n">tree</span><span class="o">.</span><span class="n">traverse</span><span class="p">():</span>
<span class="n">file_count</span> <span class="o">+=</span> <span class="n">item</span><span class="o">.</span><span class="n">type</span> <span class="o">==</span> <span class="s1">'blob'</span>
<span class="n">tree_count</span> <span class="o">+=</span> <span class="n">item</span><span class="o">.</span><span class="n">type</span> <span class="o">==</span> <span class="s1">'tree'</span>
<span class="k">assert</span> <span class="n">file_count</span> <span class="ow">and</span> <span class="n">tree_count</span> <span class="c1"># we have accumulated all directories and files</span>
<span class="k">assert</span> <span class="nb">len</span><span class="p">(</span><span class="n">tree</span><span class="o">.</span><span class="n">blobs</span><span class="p">)</span> <span class="o">+</span> <span class="nb">len</span><span class="p">(</span><span class="n">tree</span><span class="o">.</span><span class="n">trees</span><span class="p">)</span> <span class="o">==</span> <span class="nb">len</span><span class="p">(</span><span class="n">tree</span><span class="p">)</span> <span class="c1"># a tree is iterable itself to traverse its children</span>
</pre></div>
</div>
<p><a class="reference internal" href="reference.html#git.remote.Remote" title="git.remote.Remote"><code class="xref py py-class docutils literal"><span class="pre">Remotes</span></code></a> allow to handle fetch, pull and push operations, while providing optional real-time progress information to <a class="reference internal" href="reference.html#git.util.RemoteProgress" title="git.util.RemoteProgress"><code class="xref py py-class docutils literal"><span class="pre">progress</span> <span class="pre">delegates</span></code></a>.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="kn">from</span> <span class="nn">git</span> <span class="kn">import</span> <span class="n">RemoteProgress</span>
<span class="k">class</span> <span class="nc">MyProgressPrinter</span><span class="p">(</span><span class="n">RemoteProgress</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">update</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">op_code</span><span class="p">,</span> <span class="n">cur_count</span><span class="p">,</span> <span class="n">max_count</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">message</span><span class="o">=</span><span class="s1">''</span><span class="p">):</span>
<span class="k">print</span><span class="p">(</span><span class="n">op_code</span><span class="p">,</span> <span class="n">cur_count</span><span class="p">,</span> <span class="n">max_count</span><span class="p">,</span> <span class="n">cur_count</span> <span class="o">/</span> <span class="p">(</span><span class="n">max_count</span> <span class="ow">or</span> <span class="mf">100.0</span><span class="p">),</span> <span class="n">message</span> <span class="ow">or</span> <span class="s2">"NO MESSAGE"</span><span class="p">)</span>
<span class="c1"># end</span>
<span class="k">assert</span> <span class="nb">len</span><span class="p">(</span><span class="n">cloned_repo</span><span class="o">.</span><span class="n">remotes</span><span class="p">)</span> <span class="o">==</span> <span class="mi">1</span> <span class="c1"># we have been cloned, so there should be one remote</span>
<span class="k">assert</span> <span class="nb">len</span><span class="p">(</span><span class="n">bare_repo</span><span class="o">.</span><span class="n">remotes</span><span class="p">)</span> <span class="o">==</span> <span class="mi">0</span> <span class="c1"># this one was just initialized</span>
<span class="n">origin</span> <span class="o">=</span> <span class="n">bare_repo</span><span class="o">.</span><span class="n">create_remote</span><span class="p">(</span><span class="s1">'origin'</span><span class="p">,</span> <span class="n">url</span><span class="o">=</span><span class="n">cloned_repo</span><span class="o">.</span><span class="n">working_tree_dir</span><span class="p">)</span>
<span class="k">assert</span> <span class="n">origin</span><span class="o">.</span><span class="n">exists</span><span class="p">()</span>
<span class="k">for</span> <span class="n">fetch_info</span> <span class="ow">in</span> <span class="n">origin</span><span class="o">.</span><span class="n">fetch</span><span class="p">(</span><span class="n">progress</span><span class="o">=</span><span class="n">MyProgressPrinter</span><span class="p">()):</span>
<span class="k">print</span><span class="p">(</span><span class="s2">"Updated </span><span class="si">%s</span><span class="s2"> to </span><span class="si">%s</span><span class="s2">"</span> <span class="o">%</span> <span class="p">(</span><span class="n">fetch_info</span><span class="o">.</span><span class="n">ref</span><span class="p">,</span> <span class="n">fetch_info</span><span class="o">.</span><span class="n">commit</span><span class="p">))</span>
<span class="c1"># create a local branch at the latest fetched master. We specify the name statically, but you have all</span>
<span class="c1"># information to do it programatically as well.</span>
<span class="n">bare_master</span> <span class="o">=</span> <span class="n">bare_repo</span><span class="o">.</span><span class="n">create_head</span><span class="p">(</span><span class="s1">'master'</span><span class="p">,</span> <span class="n">origin</span><span class="o">.</span><span class="n">refs</span><span class="o">.</span><span class="n">master</span><span class="p">)</span>
<span class="n">bare_repo</span><span class="o">.</span><span class="n">head</span><span class="o">.</span><span class="n">set_reference</span><span class="p">(</span><span class="n">bare_master</span><span class="p">)</span>
<span class="k">assert</span> <span class="ow">not</span> <span class="n">bare_repo</span><span class="o">.</span><span class="n">delete_remote</span><span class="p">(</span><span class="n">origin</span><span class="p">)</span><span class="o">.</span><span class="n">exists</span><span class="p">()</span>
<span class="c1"># push and pull behave very similarly</span>
</pre></div>
</div>
<p>The <a class="reference internal" href="reference.html#git.index.base.IndexFile" title="git.index.base.IndexFile"><code class="xref py py-class docutils literal"><span class="pre">index</span></code></a> is also called stage in git-speak. It is used to prepare new commits, and can be used to keep results of merge operations. Our index implementation allows to stream date into the index, which is useful for bare repositories that do not have a working tree.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="k">assert</span> <span class="n">new_branch</span><span class="o">.</span><span class="n">checkout</span><span class="p">()</span> <span class="o">==</span> <span class="n">cloned_repo</span><span class="o">.</span><span class="n">active_branch</span> <span class="c1"># checking out a branch adjusts the working tree</span>
<span class="k">assert</span> <span class="n">new_branch</span><span class="o">.</span><span class="n">commit</span> <span class="o">==</span> <span class="n">past</span><span class="o">.</span><span class="n">commit</span> <span class="c1"># Now the past is checked out</span>
<span class="n">new_file_path</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">cloned_repo</span><span class="o">.</span><span class="n">working_tree_dir</span><span class="p">,</span> <span class="s1">'my-new-file'</span><span class="p">)</span>
<span class="nb">open</span><span class="p">(</span><span class="n">new_file_path</span><span class="p">,</span> <span class="s1">'wb'</span><span class="p">)</span><span class="o">.</span><span class="n">close</span><span class="p">()</span> <span class="c1"># create new file in working tree</span>
<span class="n">cloned_repo</span><span class="o">.</span><span class="n">index</span><span class="o">.</span><span class="n">add</span><span class="p">([</span><span class="n">new_file_path</span><span class="p">])</span> <span class="c1"># add it to the index</span>
<span class="c1"># Commit the changes to deviate masters history</span>
<span class="n">cloned_repo</span><span class="o">.</span><span class="n">index</span><span class="o">.</span><span class="n">commit</span><span class="p">(</span><span class="s2">"Added a new file in the past - for later merege"</span><span class="p">)</span>
<span class="c1"># prepare a merge</span>
<span class="n">master</span> <span class="o">=</span> <span class="n">cloned_repo</span><span class="o">.</span><span class="n">heads</span><span class="o">.</span><span class="n">master</span> <span class="c1"># right-hand side is ahead of us, in the future</span>
<span class="n">merge_base</span> <span class="o">=</span> <span class="n">cloned_repo</span><span class="o">.</span><span class="n">merge_base</span><span class="p">(</span><span class="n">new_branch</span><span class="p">,</span> <span class="n">master</span><span class="p">)</span> <span class="c1"># allwos for a three-way merge</span>
<span class="n">cloned_repo</span><span class="o">.</span><span class="n">index</span><span class="o">.</span><span class="n">merge_tree</span><span class="p">(</span><span class="n">master</span><span class="p">,</span> <span class="n">base</span><span class="o">=</span><span class="n">merge_base</span><span class="p">)</span> <span class="c1"># write the merge result into index</span>
<span class="n">cloned_repo</span><span class="o">.</span><span class="n">index</span><span class="o">.</span><span class="n">commit</span><span class="p">(</span><span class="s2">"Merged past and now into future ;)"</span><span class="p">,</span>
<span class="n">parent_commits</span><span class="o">=</span><span class="p">(</span><span class="n">new_branch</span><span class="o">.</span><span class="n">commit</span><span class="p">,</span> <span class="n">master</span><span class="o">.</span><span class="n">commit</span><span class="p">))</span>
<span class="c1"># now new_branch is ahead of master, which probably should be checked out and reset softly.</span>
<span class="c1"># note that all these operations didn't touch the working tree, as we managed it ourselves.</span>
<span class="c1"># This definitely requires you to know what you are doing :) !</span>
<span class="k">assert</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">basename</span><span class="p">(</span><span class="n">new_file_path</span><span class="p">)</span> <span class="ow">in</span> <span class="n">new_branch</span><span class="o">.</span><span class="n">commit</span><span class="o">.</span><span class="n">tree</span> <span class="c1"># new file is now in tree</span>
<span class="n">master</span><span class="o">.</span><span class="n">commit</span> <span class="o">=</span> <span class="n">new_branch</span><span class="o">.</span><span class="n">commit</span> <span class="c1"># let master point to most recent commit</span>
<span class="n">cloned_repo</span><span class="o">.</span><span class="n">head</span><span class="o">.</span><span class="n">reference</span> <span class="o">=</span> <span class="n">master</span> <span class="c1"># we adjusted just the reference, not the working tree or index</span>
</pre></div>
</div>
<p><code class="xref py py-class docutils literal"><span class="pre">Submodules</span></code> represent all aspects of git submodules, which allows you query all of their related information, and manipulate in various ways.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="c1"># create a new submodule and check it out on the spot, setup to track master branch of `bare_repo`</span>
<span class="c1"># As our GitPython repository has submodules already that point to github, make sure we don't</span>
<span class="c1"># interact with them</span>
<span class="k">for</span> <span class="n">sm</span> <span class="ow">in</span> <span class="n">cloned_repo</span><span class="o">.</span><span class="n">submodules</span><span class="p">:</span>
<span class="k">assert</span> <span class="ow">not</span> <span class="n">sm</span><span class="o">.</span><span class="n">remove</span><span class="p">()</span><span class="o">.</span><span class="n">exists</span><span class="p">()</span> <span class="c1"># after removal, the sm doesn't exist anymore</span>
<span class="n">sm</span> <span class="o">=</span> <span class="n">cloned_repo</span><span class="o">.</span><span class="n">create_submodule</span><span class="p">(</span><span class="s1">'mysubrepo'</span><span class="p">,</span> <span class="s1">'path/to/subrepo'</span><span class="p">,</span> <span class="n">url</span><span class="o">=</span><span class="n">bare_repo</span><span class="o">.</span><span class="n">git_dir</span><span class="p">,</span> <span class="n">branch</span><span class="o">=</span><span class="s1">'master'</span><span class="p">)</span>
<span class="c1"># .gitmodules was written and added to the index, which is now being committed</span>
<span class="n">cloned_repo</span><span class="o">.</span><span class="n">index</span><span class="o">.</span><span class="n">commit</span><span class="p">(</span><span class="s2">"Added submodule"</span><span class="p">)</span>
<span class="k">assert</span> <span class="n">sm</span><span class="o">.</span><span class="n">exists</span><span class="p">()</span> <span class="ow">and</span> <span class="n">sm</span><span class="o">.</span><span class="n">module_exists</span><span class="p">()</span> <span class="c1"># this submodule is defintely available</span>
<span class="n">sm</span><span class="o">.</span><span class="n">remove</span><span class="p">(</span><span class="n">module</span><span class="o">=</span><span class="bp">True</span><span class="p">,</span> <span class="n">configuration</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span> <span class="c1"># remove the working tree</span>
<span class="k">assert</span> <span class="n">sm</span><span class="o">.</span><span class="n">exists</span><span class="p">()</span> <span class="ow">and</span> <span class="ow">not</span> <span class="n">sm</span><span class="o">.</span><span class="n">module_exists</span><span class="p">()</span> <span class="c1"># the submodule itself is still available</span>
<span class="c1"># update all submodules, non-recursively to save time, this method is very powerful, go have a look</span>
<span class="n">cloned_repo</span><span class="o">.</span><span class="n">submodule_update</span><span class="p">(</span><span class="n">recursive</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
<span class="k">assert</span> <span class="n">sm</span><span class="o">.</span><span class="n">module_exists</span><span class="p">()</span> <span class="c1"># The submodules working tree was checked out by update</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="examining-references">
<h2>Examining References<a class="headerlink" href="#examining-references" title="Permalink to this headline">¶</a></h2>
<p><a class="reference internal" href="reference.html#git.refs.reference.Reference" title="git.refs.reference.Reference"><code class="xref py py-class docutils literal"><span class="pre">References</span></code></a> are the tips of your commit graph from which you can easily examine the history of your project.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="kn">import</span> <span class="nn">git</span>
<span class="n">repo</span> <span class="o">=</span> <span class="n">git</span><span class="o">.</span><span class="n">Repo</span><span class="o">.</span><span class="n">clone_from</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_small_repo_url</span><span class="p">(),</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">rw_dir</span><span class="p">,</span> <span class="s1">'repo'</span><span class="p">),</span> <span class="n">branch</span><span class="o">=</span><span class="s1">'master'</span><span class="p">)</span>
<span class="n">heads</span> <span class="o">=</span> <span class="n">repo</span><span class="o">.</span><span class="n">heads</span>
<span class="n">master</span> <span class="o">=</span> <span class="n">heads</span><span class="o">.</span><span class="n">master</span> <span class="c1"># lists can be accessed by name for convenience</span>
<span class="n">master</span><span class="o">.</span><span class="n">commit</span> <span class="c1"># the commit pointed to by head called master</span>
<span class="n">master</span><span class="o">.</span><span class="n">rename</span><span class="p">(</span><span class="s1">'new_name'</span><span class="p">)</span> <span class="c1"># rename heads</span>
<span class="n">master</span><span class="o">.</span><span class="n">rename</span><span class="p">(</span><span class="s1">'master'</span><span class="p">)</span>
</pre></div>
</div>
<p><a class="reference internal" href="reference.html#git.refs.tag.TagReference" title="git.refs.tag.TagReference"><code class="xref py py-class docutils literal"><span class="pre">Tags</span></code></a> are (usually immutable) references to a commit and/or a tag object.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="n">tags</span> <span class="o">=</span> <span class="n">repo</span><span class="o">.</span><span class="n">tags</span>
<span class="n">tagref</span> <span class="o">=</span> <span class="n">tags</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
<span class="n">tagref</span><span class="o">.</span><span class="n">tag</span> <span class="c1"># tags may have tag objects carrying additional information</span>
<span class="n">tagref</span><span class="o">.</span><span class="n">commit</span> <span class="c1"># but they always point to commits</span>
<span class="n">repo</span><span class="o">.</span><span class="n">delete_tag</span><span class="p">(</span><span class="n">tagref</span><span class="p">)</span> <span class="c1"># delete or</span>
<span class="n">repo</span><span class="o">.</span><span class="n">create_tag</span><span class="p">(</span><span class="s2">"my_tag"</span><span class="p">)</span> <span class="c1"># create tags using the repo for convenience</span>
</pre></div>
</div>
<p>A <a class="reference internal" href="reference.html#git.refs.symbolic.SymbolicReference" title="git.refs.symbolic.SymbolicReference"><code class="xref py py-class docutils literal"><span class="pre">symbolic</span> <span class="pre">reference</span></code></a> is a special case of a reference as it points to another reference instead of a commit.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="n">head</span> <span class="o">=</span> <span class="n">repo</span><span class="o">.</span><span class="n">head</span> <span class="c1"># the head points to the active branch/ref</span>
<span class="n">master</span> <span class="o">=</span> <span class="n">head</span><span class="o">.</span><span class="n">reference</span> <span class="c1"># retrieve the reference the head points to</span>
<span class="n">master</span><span class="o">.</span><span class="n">commit</span> <span class="c1"># from here you use it as any other reference</span>
</pre></div>
</div>
<p>Access the <a class="reference internal" href="reference.html#git.refs.log.RefLog" title="git.refs.log.RefLog"><code class="xref py py-class docutils literal"><span class="pre">reflog</span></code></a> easily.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="n">log</span> <span class="o">=</span> <span class="n">master</span><span class="o">.</span><span class="n">log</span><span class="p">()</span>
<span class="n">log</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="c1"># first (i.e. oldest) reflog entry</span>
<span class="n">log</span><span class="p">[</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span> <span class="c1"># last (i.e. most recent) reflog entry</span>
</pre></div>
</div>
</div>
<div class="section" id="modifying-references">
<h2>Modifying References<a class="headerlink" href="#modifying-references" title="Permalink to this headline">¶</a></h2>
<p>You can easily create and delete <a class="reference internal" href="reference.html#git.refs.reference.Reference" title="git.refs.reference.Reference"><code class="xref py py-class docutils literal"><span class="pre">reference</span> <span class="pre">types</span></code></a> or modify where they point to.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="n">new_branch</span> <span class="o">=</span> <span class="n">repo</span><span class="o">.</span><span class="n">create_head</span><span class="p">(</span><span class="s1">'new'</span><span class="p">)</span> <span class="c1"># create a new one</span>
<span class="n">new_branch</span><span class="o">.</span><span class="n">commit</span> <span class="o">=</span> <span class="s1">'HEAD~10'</span> <span class="c1"># set branch to another commit without changing index or working trees</span>
<span class="n">repo</span><span class="o">.</span><span class="n">delete_head</span><span class="p">(</span><span class="n">new_branch</span><span class="p">)</span> <span class="c1"># delete an existing head - only works if it is not checked out</span>
</pre></div>
</div>
<p>Create or delete <a class="reference internal" href="reference.html#git.refs.tag.TagReference" title="git.refs.tag.TagReference"><code class="xref py py-class docutils literal"><span class="pre">tags</span></code></a> the same way except you may not change them afterwards.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="n">new_tag</span> <span class="o">=</span> <span class="n">repo</span><span class="o">.</span><span class="n">create_tag</span><span class="p">(</span><span class="s1">'my_new_tag'</span><span class="p">,</span> <span class="n">message</span><span class="o">=</span><span class="s1">'my message'</span><span class="p">)</span>
<span class="c1"># You cannot change the commit a tag points to. Tags need to be re-created</span>
<span class="bp">self</span><span class="o">.</span><span class="n">failUnlessRaises</span><span class="p">(</span><span class="ne">AttributeError</span><span class="p">,</span> <span class="nb">setattr</span><span class="p">,</span> <span class="n">new_tag</span><span class="p">,</span> <span class="s1">'commit'</span><span class="p">,</span> <span class="n">repo</span><span class="o">.</span><span class="n">commit</span><span class="p">(</span><span class="s1">'HEAD~1'</span><span class="p">))</span>
<span class="n">repo</span><span class="o">.</span><span class="n">delete_tag</span><span class="p">(</span><span class="n">new_tag</span><span class="p">)</span>
</pre></div>
</div>
<p>Change the <a class="reference internal" href="reference.html#git.refs.symbolic.SymbolicReference" title="git.refs.symbolic.SymbolicReference"><code class="xref py py-class docutils literal"><span class="pre">symbolic</span> <span class="pre">reference</span></code></a> to switch branches cheaply (without adjusting the index or the working tree).</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="n">new_branch</span> <span class="o">=</span> <span class="n">repo</span><span class="o">.</span><span class="n">create_head</span><span class="p">(</span><span class="s1">'another-branch'</span><span class="p">)</span>
<span class="n">repo</span><span class="o">.</span><span class="n">head</span><span class="o">.</span><span class="n">reference</span> <span class="o">=</span> <span class="n">new_branch</span>
</pre></div>
</div>
</div>
<div class="section" id="understanding-objects">
<h2>Understanding Objects<a class="headerlink" href="#understanding-objects" title="Permalink to this headline">¶</a></h2>
<p>An Object is anything storable in git’s object database. Objects contain information about their type, their uncompressed size as well as the actual data. Each object is uniquely identified by a binary SHA1 hash, being 20 bytes in size, or 40 bytes in hexadecimal notation.</p>
<p>Git only knows 4 distinct object types being <a class="reference internal" href="reference.html#git.objects.blob.Blob" title="git.objects.blob.Blob"><code class="xref py py-class docutils literal"><span class="pre">Blobs</span></code></a>, <a class="reference internal" href="reference.html#git.objects.tree.Tree" title="git.objects.tree.Tree"><code class="xref py py-class docutils literal"><span class="pre">Trees</span></code></a>, <a class="reference internal" href="reference.html#git.objects.commit.Commit" title="git.objects.commit.Commit"><code class="xref py py-class docutils literal"><span class="pre">Commits</span></code></a> and <a class="reference internal" href="reference.html#git.objects.tag.TagObject" title="git.objects.tag.TagObject"><code class="xref py py-class docutils literal"><span class="pre">Tags</span></code></a>.</p>
<p>In GitPython, all objects can be accessed through their common base, can be compared and hashed. They are usually not instantiated directly, but through references or specialized repository functions.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="n">hc</span> <span class="o">=</span> <span class="n">repo</span><span class="o">.</span><span class="n">head</span><span class="o">.</span><span class="n">commit</span>
<span class="n">hct</span> <span class="o">=</span> <span class="n">hc</span><span class="o">.</span><span class="n">tree</span>
<span class="n">hc</span> <span class="o">!=</span> <span class="n">hct</span>
<span class="n">hc</span> <span class="o">!=</span> <span class="n">repo</span><span class="o">.</span><span class="n">tags</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
<span class="n">hc</span> <span class="o">==</span> <span class="n">repo</span><span class="o">.</span><span class="n">head</span><span class="o">.</span><span class="n">reference</span><span class="o">.</span><span class="n">commit</span>
</pre></div>
</div>
<p>Common fields are ...</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="k">assert</span> <span class="n">hct</span><span class="o">.</span><span class="n">type</span> <span class="o">==</span> <span class="s1">'tree'</span> <span class="c1"># preset string type, being a class attribute</span>
<span class="k">assert</span> <span class="n">hct</span><span class="o">.</span><span class="n">size</span> <span class="o">></span> <span class="mi">0</span> <span class="c1"># size in bytes</span>
<span class="k">assert</span> <span class="nb">len</span><span class="p">(</span><span class="n">hct</span><span class="o">.</span><span class="n">hexsha</span><span class="p">)</span> <span class="o">==</span> <span class="mi">40</span>
<span class="k">assert</span> <span class="nb">len</span><span class="p">(</span><span class="n">hct</span><span class="o">.</span><span class="n">binsha</span><span class="p">)</span> <span class="o">==</span> <span class="mi">20</span>
</pre></div>
</div>
<p><a class="reference internal" href="reference.html#git.objects.base.IndexObject" title="git.objects.base.IndexObject"><code class="xref py py-class docutils literal"><span class="pre">Index</span> <span class="pre">objects</span></code></a> are objects that can be put into git’s index. These objects are trees, blobs and submodules which additionally know about their path in the file system as well as their mode.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="k">assert</span> <span class="n">hct</span><span class="o">.</span><span class="n">path</span> <span class="o">==</span> <span class="s1">''</span> <span class="c1"># root tree has no path</span>
<span class="k">assert</span> <span class="n">hct</span><span class="o">.</span><span class="n">trees</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">path</span> <span class="o">!=</span> <span class="s1">''</span> <span class="c1"># the first contained item has one though</span>
<span class="k">assert</span> <span class="n">hct</span><span class="o">.</span><span class="n">mode</span> <span class="o">==</span> <span class="mi">0</span><span class="n">o40000</span> <span class="c1"># trees have the mode of a linux directory</span>
<span class="k">assert</span> <span class="n">hct</span><span class="o">.</span><span class="n">blobs</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">mode</span> <span class="o">==</span> <span class="mi">0</span><span class="n">o100644</span> <span class="c1"># blobs have a specific mode though comparable to a standard linux fs</span>
</pre></div>
</div>
<p>Access <a class="reference internal" href="reference.html#git.objects.blob.Blob" title="git.objects.blob.Blob"><code class="xref py py-class docutils literal"><span class="pre">blob</span></code></a> data (or any object data) using streams.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="n">hct</span><span class="o">.</span><span class="n">blobs</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">data_stream</span><span class="o">.</span><span class="n">read</span><span class="p">()</span> <span class="c1"># stream object to read data from</span>
<span class="n">hct</span><span class="o">.</span><span class="n">blobs</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">stream_data</span><span class="p">(</span><span class="nb">open</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">rw_dir</span><span class="p">,</span> <span class="s1">'blob_data'</span><span class="p">),</span> <span class="s1">'wb'</span><span class="p">))</span> <span class="c1"># write data to given stream</span>
</pre></div>
</div>
</div>
<div class="section" id="the-commit-object">
<h2>The Commit object<a class="headerlink" href="#the-commit-object" title="Permalink to this headline">¶</a></h2>
<p><a class="reference internal" href="reference.html#git.objects.commit.Commit" title="git.objects.commit.Commit"><code class="xref py py-class docutils literal"><span class="pre">Commit</span></code></a> objects contain information about a specific commit. Obtain commits using references as done in <a class="reference internal" href="#examining-references">Examining References</a> or as follows.</p>
<p>Obtain commits at the specified revision</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="n">repo</span><span class="o">.</span><span class="n">commit</span><span class="p">(</span><span class="s1">'master'</span><span class="p">)</span>
<span class="n">repo</span><span class="o">.</span><span class="n">commit</span><span class="p">(</span><span class="s1">'v0.8.1'</span><span class="p">)</span>
<span class="n">repo</span><span class="o">.</span><span class="n">commit</span><span class="p">(</span><span class="s1">'HEAD~10'</span><span class="p">)</span>
</pre></div>
</div>
<p>Iterate 50 commits, and if you need paging, you can specify a number of commits to skip.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="n">fifty_first_commits</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="n">repo</span><span class="o">.</span><span class="n">iter_commits</span><span class="p">(</span><span class="s1">'master'</span><span class="p">,</span> <span class="n">max_count</span><span class="o">=</span><span class="mi">50</span><span class="p">))</span>
<span class="k">assert</span> <span class="nb">len</span><span class="p">(</span><span class="n">fifty_first_commits</span><span class="p">)</span> <span class="o">==</span> <span class="mi">50</span>
<span class="c1"># this will return commits 21-30 from the commit list as traversed backwards master</span>
<span class="n">ten_commits_past_twenty</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="n">repo</span><span class="o">.</span><span class="n">iter_commits</span><span class="p">(</span><span class="s1">'master'</span><span class="p">,</span> <span class="n">max_count</span><span class="o">=</span><span class="mi">10</span><span class="p">,</span> <span class="n">skip</span><span class="o">=</span><span class="mi">20</span><span class="p">))</span>
<span class="k">assert</span> <span class="nb">len</span><span class="p">(</span><span class="n">ten_commits_past_twenty</span><span class="p">)</span> <span class="o">==</span> <span class="mi">10</span>
<span class="k">assert</span> <span class="n">fifty_first_commits</span><span class="p">[</span><span class="mi">20</span><span class="p">:</span><span class="mi">30</span><span class="p">]</span> <span class="o">==</span> <span class="n">ten_commits_past_twenty</span>
</pre></div>
</div>
<p>A commit object carries all sorts of meta-data</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="n">headcommit</span> <span class="o">=</span> <span class="n">repo</span><span class="o">.</span><span class="n">head</span><span class="o">.</span><span class="n">commit</span>
<span class="k">assert</span> <span class="nb">len</span><span class="p">(</span><span class="n">headcommit</span><span class="o">.</span><span class="n">hexsha</span><span class="p">)</span> <span class="o">==</span> <span class="mi">40</span>
<span class="k">assert</span> <span class="nb">len</span><span class="p">(</span><span class="n">headcommit</span><span class="o">.</span><span class="n">parents</span><span class="p">)</span> <span class="o">></span> <span class="mi">0</span>
<span class="k">assert</span> <span class="n">headcommit</span><span class="o">.</span><span class="n">tree</span><span class="o">.</span><span class="n">type</span> <span class="o">==</span> <span class="s1">'tree'</span>
<span class="k">assert</span> <span class="n">headcommit</span><span class="o">.</span><span class="n">author</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s1">'Sebastian Thiel'</span>
<span class="k">assert</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">headcommit</span><span class="o">.</span><span class="n">authored_date</span><span class="p">,</span> <span class="nb">int</span><span class="p">)</span>
<span class="k">assert</span> <span class="n">headcommit</span><span class="o">.</span><span class="n">committer</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s1">'Sebastian Thiel'</span>
<span class="k">assert</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">headcommit</span><span class="o">.</span><span class="n">committed_date</span><span class="p">,</span> <span class="nb">int</span><span class="p">)</span>
<span class="k">assert</span> <span class="n">headcommit</span><span class="o">.</span><span class="n">message</span> <span class="o">!=</span> <span class="s1">''</span>
</pre></div>
</div>
<p>Note: date time is represented in a <code class="docutils literal"><span class="pre">seconds</span> <span class="pre">since</span> <span class="pre">epoch</span></code> format. Conversion to human readable form can be accomplished with the various <a class="reference external" href="http://docs.python.org/library/time.html">time module</a> methods.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="kn">import</span> <span class="nn">time</span>
<span class="n">time</span><span class="o">.</span><span class="n">asctime</span><span class="p">(</span><span class="n">time</span><span class="o">.</span><span class="n">gmtime</span><span class="p">(</span><span class="n">headcommit</span><span class="o">.</span><span class="n">committed_date</span><span class="p">))</span>
<span class="n">time</span><span class="o">.</span><span class="n">strftime</span><span class="p">(</span><span class="s2">"%a, </span><span class="si">%d</span><span class="s2"> %b %Y %H:%M"</span><span class="p">,</span> <span class="n">time</span><span class="o">.</span><span class="n">gmtime</span><span class="p">(</span><span class="n">headcommit</span><span class="o">.</span><span class="n">committed_date</span><span class="p">))</span>
</pre></div>
</div>
<p>You can traverse a commit’s ancestry by chaining calls to <code class="docutils literal"><span class="pre">parents</span></code></p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="k">assert</span> <span class="n">headcommit</span><span class="o">.</span><span class="n">parents</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">parents</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">parents</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">==</span> <span class="n">repo</span><span class="o">.</span><span class="n">commit</span><span class="p">(</span><span class="s1">'master^^^'</span><span class="p">)</span>
</pre></div>
</div>
<p>The above corresponds to <code class="docutils literal"><span class="pre">master^^^</span></code> or <code class="docutils literal"><span class="pre">master~3</span></code> in git parlance.</p>
</div>
<div class="section" id="the-tree-object">
<h2>The Tree object<a class="headerlink" href="#the-tree-object" title="Permalink to this headline">¶</a></h2>
<p>A <a class="reference internal" href="reference.html#git.objects.tree.Tree" title="git.objects.tree.Tree"><code class="xref py py-class docutils literal"><span class="pre">tree</span></code></a> records pointers to the contents of a directory. Let’s say you want the root tree of the latest commit on the master branch</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="n">tree</span> <span class="o">=</span> <span class="n">repo</span><span class="o">.</span><span class="n">heads</span><span class="o">.</span><span class="n">master</span><span class="o">.</span><span class="n">commit</span><span class="o">.</span><span class="n">tree</span>
<span class="k">assert</span> <span class="nb">len</span><span class="p">(</span><span class="n">tree</span><span class="o">.</span><span class="n">hexsha</span><span class="p">)</span> <span class="o">==</span> <span class="mi">40</span>
</pre></div>
</div>
<p>Once you have a tree, you can get its contents</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="k">assert</span> <span class="nb">len</span><span class="p">(</span><span class="n">tree</span><span class="o">.</span><span class="n">trees</span><span class="p">)</span> <span class="o">></span> <span class="mi">0</span> <span class="c1"># trees are subdirectories</span>
<span class="k">assert</span> <span class="nb">len</span><span class="p">(</span><span class="n">tree</span><span class="o">.</span><span class="n">blobs</span><span class="p">)</span> <span class="o">></span> <span class="mi">0</span> <span class="c1"># blobs are files</span>
<span class="k">assert</span> <span class="nb">len</span><span class="p">(</span><span class="n">tree</span><span class="o">.</span><span class="n">blobs</span><span class="p">)</span> <span class="o">+</span> <span class="nb">len</span><span class="p">(</span><span class="n">tree</span><span class="o">.</span><span class="n">trees</span><span class="p">)</span> <span class="o">==</span> <span class="nb">len</span><span class="p">(</span><span class="n">tree</span><span class="p">)</span>
</pre></div>
</div>
<p>It is useful to know that a tree behaves like a list with the ability to query entries by name</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="k">assert</span> <span class="n">tree</span><span class="p">[</span><span class="s1">'smmap'</span><span class="p">]</span> <span class="o">==</span> <span class="n">tree</span> <span class="o">/</span> <span class="s1">'smmap'</span> <span class="c1"># access by index and by sub-path</span>
<span class="k">for</span> <span class="n">entry</span> <span class="ow">in</span> <span class="n">tree</span><span class="p">:</span> <span class="c1"># intuitive iteration of tree members</span>
<span class="k">print</span><span class="p">(</span><span class="n">entry</span><span class="p">)</span>
<span class="n">blob</span> <span class="o">=</span> <span class="n">tree</span><span class="o">.</span><span class="n">trees</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">blobs</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="c1"># let's get a blob in a sub-tree</span>
<span class="k">assert</span> <span class="n">blob</span><span class="o">.</span><span class="n">name</span>
<span class="k">assert</span> <span class="nb">len</span><span class="p">(</span><span class="n">blob</span><span class="o">.</span><span class="n">path</span><span class="p">)</span> <span class="o"><</span> <span class="nb">len</span><span class="p">(</span><span class="n">blob</span><span class="o">.</span><span class="n">abspath</span><span class="p">)</span>
<span class="k">assert</span> <span class="n">tree</span><span class="o">.</span><span class="n">trees</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">name</span> <span class="o">+</span> <span class="s1">'/'</span> <span class="o">+</span> <span class="n">blob</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="n">blob</span><span class="o">.</span><span class="n">path</span> <span class="c1"># this is how the relative blob path is generated</span>
<span class="k">assert</span> <span class="n">tree</span><span class="p">[</span><span class="n">blob</span><span class="o">.</span><span class="n">path</span><span class="p">]</span> <span class="o">==</span> <span class="n">blob</span> <span class="c1"># you can use paths like 'dir/file' in tree[...]</span>
</pre></div>
</div>
<p>There is a convenience method that allows you to get a named sub-object from a tree with a syntax similar to how paths are written in a posix system</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="k">assert</span> <span class="n">tree</span> <span class="o">/</span> <span class="s1">'smmap'</span> <span class="o">==</span> <span class="n">tree</span><span class="p">[</span><span class="s1">'smmap'</span><span class="p">]</span>
<span class="k">assert</span> <span class="n">tree</span> <span class="o">/</span> <span class="n">blob</span><span class="o">.</span><span class="n">path</span> <span class="o">==</span> <span class="n">tree</span><span class="p">[</span><span class="n">blob</span><span class="o">.</span><span class="n">path</span><span class="p">]</span>
</pre></div>
</div>
<p>You can also get a commit’s root tree directly from the repository</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="c1"># This example shows the various types of allowed ref-specs</span>
<span class="k">assert</span> <span class="n">repo</span><span class="o">.</span><span class="n">tree</span><span class="p">()</span> <span class="o">==</span> <span class="n">repo</span><span class="o">.</span><span class="n">head</span><span class="o">.</span><span class="n">commit</span><span class="o">.</span><span class="n">tree</span>
<span class="n">past</span> <span class="o">=</span> <span class="n">repo</span><span class="o">.</span><span class="n">commit</span><span class="p">(</span><span class="s1">'HEAD~5'</span><span class="p">)</span>
<span class="k">assert</span> <span class="n">repo</span><span class="o">.</span><span class="n">tree</span><span class="p">(</span><span class="n">past</span><span class="p">)</span> <span class="o">==</span> <span class="n">repo</span><span class="o">.</span><span class="n">tree</span><span class="p">(</span><span class="n">past</span><span class="o">.</span><span class="n">hexsha</span><span class="p">)</span>
<span class="k">assert</span> <span class="n">repo</span><span class="o">.</span><span class="n">tree</span><span class="p">(</span><span class="s1">'v0.8.1'</span><span class="p">)</span><span class="o">.</span><span class="n">type</span> <span class="o">==</span> <span class="s1">'tree'</span> <span class="c1"># yes, you can provide any refspec - works everywhere</span>
</pre></div>
</div>
<p>As trees allow direct access to their intermediate child entries only, use the traverse method to obtain an iterator to retrieve entries recursively</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="k">assert</span> <span class="nb">len</span><span class="p">(</span><span class="n">tree</span><span class="p">)</span> <span class="o"><</span> <span class="nb">len</span><span class="p">(</span><span class="nb">list</span><span class="p">(</span><span class="n">tree</span><span class="o">.</span><span class="n">traverse</span><span class="p">()))</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If trees return Submodule objects, they will assume that they exist at the current head’s commit. The tree it originated from may be rooted at another commit though, that it doesn’t know. That is why the caller would have to set the submodule’s owning or parent commit using the <code class="docutils literal"><span class="pre">set_parent_commit(my_commit)</span></code> method.</p>
</div>
</div>
<div class="section" id="the-index-object">
<h2>The Index Object<a class="headerlink" href="#the-index-object" title="Permalink to this headline">¶</a></h2>
<p>The git index is the stage containing changes to be written with the next commit or where merges finally have to take place. You may freely access and manipulate this information using the <a class="reference internal" href="reference.html#git.index.base.IndexFile" title="git.index.base.IndexFile"><code class="xref py py-class docutils literal"><span class="pre">IndexFile</span></code></a> object.
Modify the index with ease</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="n">index</span> <span class="o">=</span> <span class="n">repo</span><span class="o">.</span><span class="n">index</span>
<span class="c1"># The index contains all blobs in a flat list</span>
<span class="k">assert</span> <span class="nb">len</span><span class="p">(</span><span class="nb">list</span><span class="p">(</span><span class="n">index</span><span class="o">.</span><span class="n">iter_blobs</span><span class="p">()))</span> <span class="o">==</span> <span class="nb">len</span><span class="p">([</span><span class="n">o</span> <span class="k">for</span> <span class="n">o</span> <span class="ow">in</span> <span class="n">repo</span><span class="o">.</span><span class="n">head</span><span class="o">.</span><span class="n">commit</span><span class="o">.</span><span class="n">tree</span><span class="o">.</span><span class="n">traverse</span><span class="p">()</span> <span class="k">if</span> <span class="n">o</span><span class="o">.</span><span class="n">type</span> <span class="o">==</span> <span class="s1">'blob'</span><span class="p">])</span>
<span class="c1"># Access blob objects</span>
<span class="k">for</span> <span class="p">(</span><span class="n">path</span><span class="p">,</span> <span class="n">stage</span><span class="p">),</span> <span class="n">entry</span> <span class="ow">in</span> <span class="n">index</span><span class="o">.</span><span class="n">entries</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
<span class="k">pass</span>
<span class="n">new_file_path</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">repo</span><span class="o">.</span><span class="n">working_tree_dir</span><span class="p">,</span> <span class="s1">'new-file-name'</span><span class="p">)</span>
<span class="nb">open</span><span class="p">(</span><span class="n">new_file_path</span><span class="p">,</span> <span class="s1">'w'</span><span class="p">)</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
<span class="n">index</span><span class="o">.</span><span class="n">add</span><span class="p">([</span><span class="n">new_file_path</span><span class="p">])</span> <span class="c1"># add a new file to the index</span>
<span class="n">index</span><span class="o">.</span><span class="n">remove</span><span class="p">([</span><span class="s1">'LICENSE'</span><span class="p">])</span> <span class="c1"># remove an existing one</span>
<span class="k">assert</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">isfile</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">repo</span><span class="o">.</span><span class="n">working_tree_dir</span><span class="p">,</span> <span class="s1">'LICENSE'</span><span class="p">))</span> <span class="c1"># working tree is untouched</span>
<span class="k">assert</span> <span class="n">index</span><span class="o">.</span><span class="n">commit</span><span class="p">(</span><span class="s2">"my commit message"</span><span class="p">)</span><span class="o">.</span><span class="n">type</span> <span class="o">==</span> <span class="s1">'commit'</span> <span class="c1"># commit changed index</span>
<span class="n">repo</span><span class="o">.</span><span class="n">active_branch</span><span class="o">.</span><span class="n">commit</span> <span class="o">=</span> <span class="n">repo</span><span class="o">.</span><span class="n">commit</span><span class="p">(</span><span class="s1">'HEAD~1'</span><span class="p">)</span> <span class="c1"># forget last commit</span>
<span class="kn">from</span> <span class="nn">git</span> <span class="kn">import</span> <span class="n">Actor</span>
<span class="n">author</span> <span class="o">=</span> <span class="n">Actor</span><span class="p">(</span><span class="s2">"An author"</span><span class="p">,</span> <span class="s2">"author@example.com"</span><span class="p">)</span>
<span class="n">committer</span> <span class="o">=</span> <span class="n">Actor</span><span class="p">(</span><span class="s2">"A committer"</span><span class="p">,</span> <span class="s2">"committer@example.com"</span><span class="p">)</span>
<span class="c1"># commit by commit message and author and committer</span>
<span class="n">index</span><span class="o">.</span><span class="n">commit</span><span class="p">(</span><span class="s2">"my commit message"</span><span class="p">,</span> <span class="n">author</span><span class="o">=</span><span class="n">author</span><span class="p">,</span> <span class="n">committer</span><span class="o">=</span><span class="n">committer</span><span class="p">)</span>
</pre></div>
</div>
<p>Create new indices from other trees or as result of a merge. Write that result to a new index file for later inspection.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="kn">from</span> <span class="nn">git</span> <span class="kn">import</span> <span class="n">IndexFile</span>
<span class="c1"># loads a tree into a temporary index, which exists just in memory</span>
<span class="n">IndexFile</span><span class="o">.</span><span class="n">from_tree</span><span class="p">(</span><span class="n">repo</span><span class="p">,</span> <span class="s1">'HEAD~1'</span><span class="p">)</span>
<span class="c1"># merge two trees three-way into memory</span>
<span class="n">merge_index</span> <span class="o">=</span> <span class="n">IndexFile</span><span class="o">.</span><span class="n">from_tree</span><span class="p">(</span><span class="n">repo</span><span class="p">,</span> <span class="s1">'HEAD~10'</span><span class="p">,</span> <span class="s1">'HEAD'</span><span class="p">,</span> <span class="n">repo</span><span class="o">.</span><span class="n">merge_base</span><span class="p">(</span><span class="s1">'HEAD~10'</span><span class="p">,</span> <span class="s1">'HEAD'</span><span class="p">))</span>
<span class="c1"># and persist it</span>
<span class="n">merge_index</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">rw_dir</span><span class="p">,</span> <span class="s1">'merged_index'</span><span class="p">))</span>
</pre></div>
</div>
</div>
<div class="section" id="handling-remotes">
<h2>Handling Remotes<a class="headerlink" href="#handling-remotes" title="Permalink to this headline">¶</a></h2>
<p><a class="reference internal" href="reference.html#git.remote.Remote" title="git.remote.Remote"><code class="xref py py-class docutils literal"><span class="pre">Remotes</span></code></a> are used as alias for a foreign repository to ease pushing to and fetching from them</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="n">empty_repo</span> <span class="o">=</span> <span class="n">git</span><span class="o">.</span><span class="n">Repo</span><span class="o">.</span><span class="n">init</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">rw_dir</span><span class="p">,</span> <span class="s1">'empty'</span><span class="p">))</span>
<span class="n">origin</span> <span class="o">=</span> <span class="n">empty_repo</span><span class="o">.</span><span class="n">create_remote</span><span class="p">(</span><span class="s1">'origin'</span><span class="p">,</span> <span class="n">repo</span><span class="o">.</span><span class="n">remotes</span><span class="o">.</span><span class="n">origin</span><span class="o">.</span><span class="n">url</span><span class="p">)</span>
<span class="k">assert</span> <span class="n">origin</span><span class="o">.</span><span class="n">exists</span><span class="p">()</span>
<span class="k">assert</span> <span class="n">origin</span> <span class="o">==</span> <span class="n">empty_repo</span><span class="o">.</span><span class="n">remotes</span><span class="o">.</span><span class="n">origin</span> <span class="o">==</span> <span class="n">empty_repo</span><span class="o">.</span><span class="n">remotes</span><span class="p">[</span><span class="s1">'origin'</span><span class="p">]</span>
<span class="n">origin</span><span class="o">.</span><span class="n">fetch</span><span class="p">()</span> <span class="c1"># assure we actually have data. fetch() returns useful information</span>
<span class="c1"># Setup a local tracking branch of a remote branch</span>
<span class="n">empty_repo</span><span class="o">.</span><span class="n">create_head</span><span class="p">(</span><span class="s1">'master'</span><span class="p">,</span> <span class="n">origin</span><span class="o">.</span><span class="n">refs</span><span class="o">.</span><span class="n">master</span><span class="p">)</span> <span class="c1"># create local branch "master" from remote branch "master"</span>
<span class="n">empty_repo</span><span class="o">.</span><span class="n">heads</span><span class="o">.</span><span class="n">master</span><span class="o">.</span><span class="n">set_tracking_branch</span><span class="p">(</span><span class="n">origin</span><span class="o">.</span><span class="n">refs</span><span class="o">.</span><span class="n">master</span><span class="p">)</span> <span class="c1"># set local "master" to track remote "master</span>
<span class="n">empty_repo</span><span class="o">.</span><span class="n">heads</span><span class="o">.</span><span class="n">master</span><span class="o">.</span><span class="n">checkout</span><span class="p">()</span> <span class="c1"># checkout local "master" to working tree</span>
<span class="c1"># Three above commands in one:</span>
<span class="n">empty_repo</span><span class="o">.</span><span class="n">create_head</span><span class="p">(</span><span class="s1">'master'</span><span class="p">,</span> <span class="n">origin</span><span class="o">.</span><span class="n">refs</span><span class="o">.</span><span class="n">master</span><span class="p">)</span><span class="o">.</span><span class="n">set_tracking_branch</span><span class="p">(</span><span class="n">origin</span><span class="o">.</span><span class="n">refs</span><span class="o">.</span><span class="n">master</span><span class="p">)</span><span class="o">.</span><span class="n">checkout</span><span class="p">()</span>
<span class="c1"># rename remotes</span>
<span class="n">origin</span><span class="o">.</span><span class="n">rename</span><span class="p">(</span><span class="s1">'new_origin'</span><span class="p">)</span>
<span class="c1"># push and pull behaves similarly to `git push|pull`</span>
<span class="n">origin</span><span class="o">.</span><span class="n">pull</span><span class="p">()</span>
<span class="n">origin</span><span class="o">.</span><span class="n">push</span><span class="p">()</span>
<span class="c1"># assert not empty_repo.delete_remote(origin).exists() # create and delete remotes</span>
</pre></div>
</div>
<p>You can easily access configuration information for a remote by accessing options as if they where attributes. The modification of remote configuration is more explicit though.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="k">assert</span> <span class="n">origin</span><span class="o">.</span><span class="n">url</span> <span class="o">==</span> <span class="n">repo</span><span class="o">.</span><span class="n">remotes</span><span class="o">.</span><span class="n">origin</span><span class="o">.</span><span class="n">url</span>
<span class="n">cw</span> <span class="o">=</span> <span class="n">origin</span><span class="o">.</span><span class="n">config_writer</span>
<span class="n">cw</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="s2">"pushurl"</span><span class="p">,</span> <span class="s2">"other_url"</span><span class="p">)</span>
<span class="n">cw</span><span class="o">.</span><span class="n">release</span><span class="p">()</span>
<span class="c1"># Please note that in python 2, writing origin.config_writer.set(...) is totally safe.</span>
<span class="c1"># In py3 __del__ calls can be delayed, thus not writing changes in time.</span>
</pre></div>
</div>
<p>You can also specify per-call custom environments using a new context manager on the Git command, e.g. for using a specific SSH key. The following example works with <cite>git</cite> starting at <em>v2.3</em>:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">ssh_cmd</span> <span class="o">=</span> <span class="s1">'ssh -i id_deployment_key'</span>
<span class="k">with</span> <span class="n">repo</span><span class="o">.</span><span class="n">git</span><span class="o">.</span><span class="n">custom_environment</span><span class="p">(</span><span class="n">GIT_SSH_COMMAND</span><span class="o">=</span><span class="n">ssh_cmd</span><span class="p">):</span>
<span class="n">repo</span><span class="o">.</span><span class="n">remotes</span><span class="o">.</span><span class="n">origin</span><span class="o">.</span><span class="n">fetch</span><span class="p">()</span>
</pre></div>
</div>
<p>This one sets a custom script to be executed in place of <cite>ssh</cite>, and can be used in <cite>git</cite> prior to <em>v2.3</em>:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">ssh_executable</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">rw_dir</span><span class="p">,</span> <span class="s1">'my_ssh_executable.sh'</span><span class="p">)</span>
<span class="k">with</span> <span class="n">repo</span><span class="o">.</span><span class="n">git</span><span class="o">.</span><span class="n">custom_environment</span><span class="p">(</span><span class="n">GIT_SSH</span><span class="o">=</span><span class="n">ssh_executable</span><span class="p">):</span>
<span class="n">repo</span><span class="o">.</span><span class="n">remotes</span><span class="o">.</span><span class="n">origin</span><span class="o">.</span><span class="n">fetch</span><span class="p">()</span>
</pre></div>
</div>
<p>Here’s an example executable that can be used in place of the <cite>ssh_executable</cite> above:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span>#!/bin/sh
ID_RSA=/var/lib/openshift/5562b947ecdd5ce939000038/app-deployments/id_rsa
exec /usr/bin/ssh -o StrictHostKeyChecking=no -i $ID_RSA "$@"
</pre></div>
</div>
<p>Please note that the script must be executable (i.e. <cite>chomd +x script.sh</cite>). <cite>StrictHostKeyChecking=no</cite> is used to avoid prompts asking to save the hosts key to <cite>~/.ssh/known_hosts</cite>, which happens in case you run this as daemon.</p>
<p>You might also have a look at <cite>Git.update_environment(...)</cite> in case you want to setup a changed environment more permanently.</p>
</div>
<div class="section" id="submodule-handling">
<h2>Submodule Handling<a class="headerlink" href="#submodule-handling" title="Permalink to this headline">¶</a></h2>
<p><a class="reference internal" href="reference.html#git.objects.submodule.base.Submodule" title="git.objects.submodule.base.Submodule"><code class="xref py py-class docutils literal"><span class="pre">Submodules</span></code></a> can be conveniently handled using the methods provided by GitPython, and as an added benefit, GitPython provides functionality which behave smarter and less error prone than its original c-git implementation, that is GitPython tries hard to keep your repository consistent when updating submodules recursively or adjusting the existing configuration.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="n">repo</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">rorepo</span>
<span class="n">sms</span> <span class="o">=</span> <span class="n">repo</span><span class="o">.</span><span class="n">submodules</span>
<span class="k">assert</span> <span class="nb">len</span><span class="p">(</span><span class="n">sms</span><span class="p">)</span> <span class="o">==</span> <span class="mi">1</span>
<span class="n">sm</span> <span class="o">=</span> <span class="n">sms</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
<span class="k">assert</span> <span class="n">sm</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s1">'gitdb'</span> <span class="c1"># git-python has gitdb as single submodule ...</span>
<span class="k">assert</span> <span class="n">sm</span><span class="o">.</span><span class="n">children</span><span class="p">()[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s1">'smmap'</span> <span class="c1"># ... which has smmap as single submodule</span>
<span class="c1"># The module is the repository referenced by the submodule</span>
<span class="k">assert</span> <span class="n">sm</span><span class="o">.</span><span class="n">module_exists</span><span class="p">()</span> <span class="c1"># the module is available, which doesn't have to be the case.</span>
<span class="k">assert</span> <span class="n">sm</span><span class="o">.</span><span class="n">module</span><span class="p">()</span><span class="o">.</span><span class="n">working_tree_dir</span><span class="o">.</span><span class="n">endswith</span><span class="p">(</span><span class="s1">'gitdb'</span><span class="p">)</span>
<span class="c1"># the submodule's absolute path is the module's path</span>
<span class="k">assert</span> <span class="n">sm</span><span class="o">.</span><span class="n">abspath</span> <span class="o">==</span> <span class="n">sm</span><span class="o">.</span><span class="n">module</span><span class="p">()</span><span class="o">.</span><span class="n">working_tree_dir</span>
<span class="k">assert</span> <span class="nb">len</span><span class="p">(</span><span class="n">sm</span><span class="o">.</span><span class="n">hexsha</span><span class="p">)</span> <span class="o">==</span> <span class="mi">40</span> <span class="c1"># Its sha defines the commit to checkout</span>
<span class="k">assert</span> <span class="n">sm</span><span class="o">.</span><span class="n">exists</span><span class="p">()</span> <span class="c1"># yes, this submodule is valid and exists</span>
<span class="c1"># read its configuration conveniently</span>
<span class="k">assert</span> <span class="n">sm</span><span class="o">.</span><span class="n">config_reader</span><span class="p">()</span><span class="o">.</span><span class="n">get_value</span><span class="p">(</span><span class="s1">'path'</span><span class="p">)</span> <span class="o">==</span> <span class="n">sm</span><span class="o">.</span><span class="n">path</span>
<span class="k">assert</span> <span class="nb">len</span><span class="p">(</span><span class="n">sm</span><span class="o">.</span><span class="n">children</span><span class="p">())</span> <span class="o">==</span> <span class="mi">1</span> <span class="c1"># query the submodule hierarchy</span>
</pre></div>
</div>
<p>In addition to the query functionality, you can move the submodule’s repository to a different path <<code class="docutils literal"><span class="pre">move(...)</span></code>>, write its configuration <<code class="docutils literal"><span class="pre">config_writer().set_value(...).release()</span></code>>, update its working tree <<code class="docutils literal"><span class="pre">update(...)</span></code>>, and remove or add them <<code class="docutils literal"><span class="pre">remove(...)</span></code>, <code class="docutils literal"><span class="pre">add(...)</span></code>>.</p>
<p>If you obtained your submodule object by traversing a tree object which is not rooted at the head’s commit, you have to inform the submodule about its actual commit to retrieve the data from by using the <code class="docutils literal"><span class="pre">set_parent_commit(...)</span></code> method.</p>
<p>The special <a class="reference internal" href="reference.html#git.objects.submodule.root.RootModule" title="git.objects.submodule.root.RootModule"><code class="xref py py-class docutils literal"><span class="pre">RootModule</span></code></a> type allows you to treat your master repository as root of a hierarchy of submodules, which allows very convenient submodule handling. Its <code class="docutils literal"><span class="pre">update(...)</span></code> method is reimplemented to provide an advanced way of updating submodules as they change their values over time. The update method will track changes and make sure your working tree and submodule checkouts stay consistent, which is very useful in case submodules get deleted or added to name just two of the handled cases.</p>
<p>Additionally, GitPython adds functionality to track a specific branch, instead of just a commit. Supported by customized update methods, you are able to automatically update submodules to the latest revision available in the remote repository, as well as to keep track of changes and movements of these submodules. To use it, set the name of the branch you want to track to the <code class="docutils literal"><span class="pre">submodule.$name.branch</span></code> option of the <em>.gitmodules</em> file, and use GitPython update methods on the resulting repository with the <code class="docutils literal"><span class="pre">to_latest_revision</span></code> parameter turned on. In the latter case, the sha of your submodule will be ignored, instead a local tracking branch will be updated to the respective remote branch automatically, provided there are no local changes. The resulting behaviour is much like the one of svn::externals, which can be useful in times.</p>
</div>
<div class="section" id="obtaining-diff-information">
<h2>Obtaining Diff Information<a class="headerlink" href="#obtaining-diff-information" title="Permalink to this headline">¶</a></h2>
<p>Diffs can generally be obtained by subclasses of <a class="reference internal" href="reference.html#git.diff.Diffable" title="git.diff.Diffable"><code class="xref py py-class docutils literal"><span class="pre">Diffable</span></code></a> as they provide the <code class="docutils literal"><span class="pre">diff</span></code> method. This operation yields a <a class="reference internal" href="reference.html#git.diff.DiffIndex" title="git.diff.DiffIndex"><code class="xref py py-class docutils literal"><span class="pre">DiffIndex</span></code></a> allowing you to easily access diff information about paths.</p>
<p>Diffs can be made between the Index and Trees, Index and the working tree, trees and trees as well as trees and the working copy. If commits are involved, their tree will be used implicitly.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="n">hcommit</span> <span class="o">=</span> <span class="n">repo</span><span class="o">.</span><span class="n">head</span><span class="o">.</span><span class="n">commit</span>
<span class="n">hcommit</span><span class="o">.</span><span class="n">diff</span><span class="p">()</span> <span class="c1"># diff tree against index</span>
<span class="n">hcommit</span><span class="o">.</span><span class="n">diff</span><span class="p">(</span><span class="s1">'HEAD~1'</span><span class="p">)</span> <span class="c1"># diff tree against previous tree</span>
<span class="n">hcommit</span><span class="o">.</span><span class="n">diff</span><span class="p">(</span><span class="bp">None</span><span class="p">)</span> <span class="c1"># diff tree against working tree</span>
<span class="n">index</span> <span class="o">=</span> <span class="n">repo</span><span class="o">.</span><span class="n">index</span>
<span class="n">index</span><span class="o">.</span><span class="n">diff</span><span class="p">()</span> <span class="c1"># diff index against itself yielding empty diff</span>
<span class="n">index</span><span class="o">.</span><span class="n">diff</span><span class="p">(</span><span class="bp">None</span><span class="p">)</span> <span class="c1"># diff index against working copy</span>
<span class="n">index</span><span class="o">.</span><span class="n">diff</span><span class="p">(</span><span class="s1">'HEAD'</span><span class="p">)</span> <span class="c1"># diff index against current HEAD tree</span>
</pre></div>
</div>
<p>The item returned is a DiffIndex which is essentially a list of Diff objects. It provides additional filtering to ease finding what you might be looking for.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="c1"># Traverse added Diff objects only</span>
<span class="k">for</span> <span class="n">diff_added</span> <span class="ow">in</span> <span class="n">hcommit</span><span class="o">.</span><span class="n">diff</span><span class="p">(</span><span class="s1">'HEAD~1'</span><span class="p">)</span><span class="o">.</span><span class="n">iter_change_type</span><span class="p">(</span><span class="s1">'A'</span><span class="p">):</span>
<span class="k">print</span><span class="p">(</span><span class="n">diff_added</span><span class="p">)</span>
</pre></div>
</div>
<p>Use the diff framework if you want to implement git-status like functionality.</p>
<ul class="simple">
<li>A diff between the index and the commit’s tree your HEAD points to</li>
</ul>
<blockquote>
<div><ul class="simple">
<li>use <code class="docutils literal"><span class="pre">repo.index.diff(repo.head.commit)</span></code></li>
</ul>
</div></blockquote>
<ul class="simple">
<li>A diff between the index and the working tree</li>
</ul>
<blockquote>
<div><ul class="simple">
<li>use <code class="docutils literal"><span class="pre">repo.index.diff(None)</span></code></li>
</ul>
</div></blockquote>
<ul class="simple">
<li>A list of untracked files</li>
</ul>
<blockquote>
<div><ul class="simple">
<li>use <code class="docutils literal"><span class="pre">repo.untracked_files</span></code></li>
</ul>
</div></blockquote>
</div>
<div class="section" id="switching-branches">
<h2>Switching Branches<a class="headerlink" href="#switching-branches" title="Permalink to this headline">¶</a></h2>
<p>To switch between branches similar to <code class="docutils literal"><span class="pre">git</span> <span class="pre">checkout</span></code>, you effectively need to point your HEAD symbolic reference to the new branch and reset your index and working copy to match. A simple manual way to do it is the following one</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="c1"># Reset our working tree 10 commits into the past</span>
<span class="n">past_branch</span> <span class="o">=</span> <span class="n">repo</span><span class="o">.</span><span class="n">create_head</span><span class="p">(</span><span class="s1">'past_branch'</span><span class="p">,</span> <span class="s1">'HEAD~10'</span><span class="p">)</span>
<span class="n">repo</span><span class="o">.</span><span class="n">head</span><span class="o">.</span><span class="n">reference</span> <span class="o">=</span> <span class="n">past_branch</span>
<span class="k">assert</span> <span class="ow">not</span> <span class="n">repo</span><span class="o">.</span><span class="n">head</span><span class="o">.</span><span class="n">is_detached</span>
<span class="c1"># reset the index and working tree to match the pointed-to commit</span>
<span class="n">repo</span><span class="o">.</span><span class="n">head</span><span class="o">.</span><span class="n">reset</span><span class="p">(</span><span class="n">index</span><span class="o">=</span><span class="bp">True</span><span class="p">,</span> <span class="n">working_tree</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="c1"># To detach your head, you have to point to a commit directy</span>
<span class="n">repo</span><span class="o">.</span><span class="n">head</span><span class="o">.</span><span class="n">reference</span> <span class="o">=</span> <span class="n">repo</span><span class="o">.</span><span class="n">commit</span><span class="p">(</span><span class="s1">'HEAD~5'</span><span class="p">)</span>
<span class="k">assert</span> <span class="n">repo</span><span class="o">.</span><span class="n">head</span><span class="o">.</span><span class="n">is_detached</span>
<span class="c1"># now our head points 15 commits into the past, whereas the working tree</span>
<span class="c1"># and index are 10 commits in the past</span>
</pre></div>
</div>
<p>The previous approach would brutally overwrite the user’s changes in the working copy and index though and is less sophisticated than a <code class="docutils literal"><span class="pre">git-checkout</span></code>. The latter will generally prevent you from destroying your work. Use the safer approach as follows.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="c1"># checkout the branch using git-checkout. It will fail as the working tree appears dirty</span>
<span class="bp">self</span><span class="o">.</span><span class="n">failUnlessRaises</span><span class="p">(</span><span class="n">git</span><span class="o">.</span><span class="n">GitCommandError</span><span class="p">,</span> <span class="n">repo</span><span class="o">.</span><span class="n">heads</span><span class="o">.</span><span class="n">master</span><span class="o">.</span><span class="n">checkout</span><span class="p">)</span>
<span class="n">repo</span><span class="o">.</span><span class="n">heads</span><span class="o">.</span><span class="n">past_branch</span><span class="o">.</span><span class="n">checkout</span><span class="p">()</span>
</pre></div>
</div>
</div>
<div class="section" id="initializing-a-repository">
<h2>Initializing a repository<a class="headerlink" href="#initializing-a-repository" title="Permalink to this headline">¶</a></h2>
<p>In this example, we will initialize an empty repository, add an empty file to the index, and commit the change.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="kn">import</span> <span class="nn">git</span>
<span class="n">repo_dir</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">rw_dir</span><span class="p">,</span> <span class="s1">'my-new-repo'</span><span class="p">)</span>
<span class="n">file_name</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">repo_dir</span><span class="p">,</span> <span class="s1">'new-file'</span><span class="p">)</span>
<span class="n">r</span> <span class="o">=</span> <span class="n">git</span><span class="o">.</span><span class="n">Repo</span><span class="o">.</span><span class="n">init</span><span class="p">(</span><span class="n">repo_dir</span><span class="p">)</span>
<span class="c1"># This function just creates an empty file ...</span>
<span class="nb">open</span><span class="p">(</span><span class="n">file_name</span><span class="p">,</span> <span class="s1">'wb'</span><span class="p">)</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
<span class="n">r</span><span class="o">.</span><span class="n">index</span><span class="o">.</span><span class="n">add</span><span class="p">([</span><span class="n">file_name</span><span class="p">])</span>
<span class="n">r</span><span class="o">.</span><span class="n">index</span><span class="o">.</span><span class="n">commit</span><span class="p">(</span><span class="s2">"initial commit"</span><span class="p">)</span>
</pre></div>
</div>
<p>Please have a look at the individual methods as they usually support a vast amount of arguments to customize their behavior.</p>
</div>
<div class="section" id="using-git-directly">
<h2>Using git directly<a class="headerlink" href="#using-git-directly" title="Permalink to this headline">¶</a></h2>
<p>In case you are missing functionality as it has not been wrapped, you may conveniently use the <a class="reference internal" href="reference.html#git.cmd.Git" title="git.cmd.Git"><code class="xref py py-class docutils literal"><span class="pre">git</span></code></a> command directly. It is owned by each repository instance.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span> <span class="n">git</span> <span class="o">=</span> <span class="n">repo</span><span class="o">.</span><span class="n">git</span>
<span class="n">git</span><span class="o">.</span><span class="n">checkout</span><span class="p">(</span><span class="s1">'HEAD'</span><span class="p">,</span> <span class="n">b</span><span class="o">=</span><span class="s2">"my_new_branch"</span><span class="p">)</span> <span class="c1"># create a new branch</span>
<span class="n">git</span><span class="o">.</span><span class="n">branch</span><span class="p">(</span><span class="s1">'another-new-one'</span><span class="p">)</span>
<span class="n">git</span><span class="o">.</span><span class="n">branch</span><span class="p">(</span><span class="s1">'-D'</span><span class="p">,</span> <span class="s1">'another-new-one'</span><span class="p">)</span> <span class="c1"># pass strings for full control over argument order</span>
<span class="n">git</span><span class="o">.</span><span class="n">for_each_ref</span><span class="p">()</span> <span class="c1"># '-' becomes '_' when calling it</span>
</pre></div>
</div>
<p>The return value will by default be a string of the standard output channel produced by the command.</p>
<p>Keyword arguments translate to short and long keyword arguments on the command-line.
The special notion <code class="docutils literal"><span class="pre">git.command(flag=True)</span></code> will create a flag without value like <code class="docutils literal"><span class="pre">command</span> <span class="pre">--flag</span></code>.</p>
<p>If <code class="docutils literal"><span class="pre">None</span></code> is found in the arguments, it will be dropped silently. Lists and tuples passed as arguments will be unpacked recursively to individual arguments. Objects are converted to strings using the <code class="docutils literal"><span class="pre">str(...)</span></code> function.</p>
</div>
<div class="section" id="object-databases">
<h2>Object Databases<a class="headerlink" href="#object-databases" title="Permalink to this headline">¶</a></h2>
<p><a class="reference internal" href="reference.html#git.repo.base.Repo" title="git.repo.base.Repo"><code class="xref py py-class docutils literal"><span class="pre">git.Repo</span></code></a> instances are powered by its object database instance which will be used when extracting any data, or when writing new objects.</p>
<p>The type of the database determines certain performance characteristics, such as the quantity of objects that can be read per second, the resource usage when reading large data files, as well as the average memory footprint of your application.</p>
<div class="section" id="gitdb">
<h3>GitDB<a class="headerlink" href="#gitdb" title="Permalink to this headline">¶</a></h3>
<p>The GitDB is a pure-python implementation of the git object database. It is the default database to use in GitPython 0.3. Its uses less memory when handling huge files, but will be 2 to 5 times slower when extracting large quantities small of objects from densely packed repositories:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">repo</span> <span class="o">=</span> <span class="n">Repo</span><span class="p">(</span><span class="s2">"path/to/repo"</span><span class="p">,</span> <span class="n">odbt</span><span class="o">=</span><span class="n">GitDB</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="gitcmdobjectdb">
<h3>GitCmdObjectDB<a class="headerlink" href="#gitcmdobjectdb" title="Permalink to this headline">¶</a></h3>
<p>The git command database uses persistent git-cat-file instances to read repository information. These operate very fast under all conditions, but will consume additional memory for the process itself. When extracting large files, memory usage will be much higher than the one of the <code class="docutils literal"><span class="pre">GitDB</span></code>:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">repo</span> <span class="o">=</span> <span class="n">Repo</span><span class="p">(</span><span class="s2">"path/to/repo"</span><span class="p">,</span> <span class="n">odbt</span><span class="o">=</span><span class="n">GitCmdObjectDB</span><span class="p">)</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="git-command-debugging-and-customization">
<h2>Git Command Debugging and Customization<a class="headerlink" href="#git-command-debugging-and-customization" title="Permalink to this headline">¶</a></h2>
<p>Using environment variables, you can further adjust the behaviour of the git command.</p>
<ul class="simple">
<li><strong>GIT_PYTHON_TRACE</strong></li>
</ul>
<blockquote>
<div><ul class="simple">
<li>If set to non-0, all executed git commands will be shown as they happen</li>
<li>If set to <em>full</em>, the executed git command _and_ its entire output on stdout and stderr will be shown as they happen</li>
</ul>
<p><strong>NOTE</strong>: All logging is outputted using a Python logger, so make sure your program is configured to show INFO-level messages. If this is not the case, try adding the following to your program:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">logging</span>
<span class="n">logging</span><span class="o">.</span><span class="n">basicConfig</span><span class="p">(</span><span class="n">level</span><span class="o">=</span><span class="n">logging</span><span class="o">.</span><span class="n">INFO</span><span class="p">)</span>
</pre></div>
</div>
</div></blockquote>
<ul class="simple">
<li><strong>GIT_PYTHON_GIT_EXECUTABLE</strong></li>
</ul>
<blockquote>
<div><ul class="simple">
<li>If set, it should contain the full path to the git executable, e.g. <em>c:\Program Files (x86)\Git\bin\git.exe</em> on windows or <em>/usr/bin/git</em> on linux.</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="and-even-more">
<h2>And even more ...<a class="headerlink" href="#and-even-more" title="Permalink to this headline">¶</a></h2>
<p>There is more functionality in there, like the ability to archive repositories, get stats and logs, blame, and probably a few other things that were not mentioned here.</p>
<p>Check the unit tests for an in-depth introduction on how each function is supposed to be used.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">GitPython Tutorial</a><ul>
<li><a class="reference internal" href="#meet-the-repo-type">Meet the Repo type</a><ul>
<li><a class="reference internal" href="#advanced-repo-usage">Advanced Repo Usage</a></li>
</ul>
</li>
<li><a class="reference internal" href="#examining-references">Examining References</a></li>
<li><a class="reference internal" href="#modifying-references">Modifying References</a></li>
<li><a class="reference internal" href="#understanding-objects">Understanding Objects</a></li>
<li><a class="reference internal" href="#the-commit-object">The Commit object</a></li>
<li><a class="reference internal" href="#the-tree-object">The Tree object</a></li>
<li><a class="reference internal" href="#the-index-object">The Index Object</a></li>
<li><a class="reference internal" href="#handling-remotes">Handling Remotes</a></li>
<li><a class="reference internal" href="#submodule-handling">Submodule Handling</a></li>
<li><a class="reference internal" href="#obtaining-diff-information">Obtaining Diff Information</a></li>
<li><a class="reference internal" href="#switching-branches">Switching Branches</a></li>
<li><a class="reference internal" href="#initializing-a-repository">Initializing a repository</a></li>
<li><a class="reference internal" href="#using-git-directly">Using git directly</a></li>
<li><a class="reference internal" href="#object-databases">Object Databases</a><ul>
<li><a class="reference internal" href="#gitdb">GitDB</a></li>
<li><a class="reference internal" href="#gitcmdobjectdb">GitCmdObjectDB</a></li>
</ul>
</li>
<li><a class="reference internal" href="#git-command-debugging-and-customization">Git Command Debugging and Customization</a></li>
<li><a class="reference internal" href="#and-even-more">And even more ...</a></li>
</ul>
</li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="index.html">Documentation overview</a><ul>
<li>Previous: <a href="whatsnew.html" title="previous chapter">Whats New in 0.3</a></li>
<li>Next: <a href="reference.html" title="next chapter">API Reference</a></li>
</ul></li>
</ul>
</div>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/tutorial.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
©Copyright (C) 2008, 2009 Michael Trier and contributors, 2010-2015 Sebastian Thiel.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 1.4.1</a>
& <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.7</a>
|
<a href="_sources/tutorial.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>
|
