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
|
.. _intro_toplevel:
==================
Overview / Install
==================
GitPython is a python library used to interact with git repositories, high-level like git-porcelain, or low-level like git-plumbing.
It provides abstractions of git objects for easy access of repository data, and additionally allows you to access the git repository more directly using either a pure python implementation, or the faster, but more resource intensive git command implementation.
The object database implementation is optimized for handling large quantities of objects and large datasets, which is achieved by using low-level structures and data streaming.
Requirements
============
* `Python`_ 3.0 or newer
* `Git`_ 1.7.0 or newer
It should also work with older versions, but it may be that some operations
involving remotes will not work as expected.
* `GitDB`_ - a pure python git database implementation
* `Python Nose`_ - used for running the tests
* `Mock by Michael Foord`_ used for tests. Requires version 0.5
.. _Python: https://www.python.org
.. _Git: https://git-scm.com/
.. _Python Nose: https://nose.readthedocs.io/en/latest/
.. _Mock by Michael Foord: http://www.voidspace.org.uk/python/mock.html
.. _GitDB: https://pypi.python.org/pypi/gitdb
Installing GitPython
====================
Installing GitPython is easily done using
`pip`_. Assuming it is
installed, just run the following from the command-line:
.. sourcecode:: none
# pip install gitpython
This command will download the latest version of GitPython from the
`Python Package Index <http://pypi.python.org/pypi/GitPython>`_ and install it
to your system. More information about ``pip`` and pypi can be found
here:
* `install pip <https://pip.pypa.io/en/latest/installing.html>`_
* `pypi <https://pypi.python.org/pypi/GitPython>`_
.. _pip: https://pip.pypa.io/en/latest/installing.html
Alternatively, you can install from the distribution using the ``setup.py``
script:
.. sourcecode:: none
# python setup.py install
.. note:: In this case, you have to manually install `GitDB`_ as well. It would be recommended to use the :ref:`git source repository <source-code-label>` in that case.
Limitations
===========
Leakage of System Resources
---------------------------
GitPython is not suited for long-running processes (like daemons) as it tends to
leak system resources. It was written in a time where destructors (as implemented
in the `__del__` method) still ran deterministically.
In case you still want to use it in such a context, you will want to search the
codebase for `__del__` implementations and call these yourself when you see fit.
Another way assure proper cleanup of resources is to factor out GitPython into a
separate process which can be dropped periodically.
Getting Started
===============
* :ref:`tutorial-label` - This tutorial provides a walk-through of some of
the basic functionality and concepts used in GitPython. It, however, is not
exhaustive so you are encouraged to spend some time in the
:ref:`api_reference_toplevel`.
API Reference
=============
An organized section of the GitPython API is at :ref:`api_reference_toplevel`.
.. _source-code-label:
Source Code
===========
GitPython's git repo is available on GitHub, which can be browsed at:
* https://github.com/gitpython-developers/GitPython
and cloned using::
$ git clone https://github.com/gitpython-developers/GitPython git-python
Initialize all submodules to obtain the required dependencies with::
$ cd git-python
$ git submodule update --init --recursive
Finally verify the installation by running the `nose powered <https://github.com/nose-devs/nose>`_ unit tests::
$ nosetests
Questions and Answers
=====================
Please use stackoverflow for questions, and don't forget to tag it with `gitpython` to assure the right people see the question in a timely manner.
http://stackoverflow.com/questions/tagged/gitpython
Issue Tracker
=============
The issue tracker is hosted by GitHub:
https://github.com/gitpython-developers/GitPython/issues
License Information
===================
GitPython is licensed under the New BSD License. See the LICENSE file for
more information.
|
