README

   1 ==========
   2 GitPython
   3 ==========
   4
   5 GitPython is a python library used to interact with Git repositories.
   6
   7 GitPython is a port of the grit_ library in Ruby created by
   8 Tom Preston-Werner and Chris Wanstrath.
   9
  10 .. _grit: http://grit.rubyforge.org
  11
  12 The ``method_missing`` stuff was `taken from this blog post`_.
  13
  14 .. _taken from this blog post: http://blog.iffy.us/?p=43
  15
  16 REQUIREMENTS
  17 ============
  18
  19 * Git_ tested with 1.5.3.7
  20 * `Python Nose`_ - used for running the tests
  21 * `Mock by Michael Foord`_ used for tests
  22
  23 .. _Git: http://git.or.cz/
  24 .. _Python Nose: http://code.google.com/p/python-nose/
  25 .. _Mock by Michael Foord: http://www.voidspace.org.uk/python/mock.html
  26
  27 INSTALL
  28 =======
  29
  30         python setup.py install
  31
  32 SOURCE
  33 ======
  34
  35 GitPython's git repo is available on Gitorious, which can be browsed at:
  36
  37 http://gitorious.org/projects/git-python/
  38
  39 and cloned from:
  40
  41 git://gitorious.org/git-python/mainline.git
  42
  43 USAGE
  44 =====
  45
  46 GitPython provides object model access to your git repository. Once you have
  47 created a repository object, you can traverse it to find parent commit(s),
  48 trees, blobs, etc.
  49
  50 Initialize a Repo object
  51 ************************
  52
  53 The first step is to create a ``Repo`` object to represent your repository.
  54
  55         >>> from git_python import *
  56         >>> repo = Repo("/Users/mtrier/Development/git-python")
  57
  58 In the above example, the directory ``/Users/mtrier/Development/git-python``
  59 is my working repository and contains the ``.git`` directory. You can also
  60 initialize GitPython with a bare repository.
  61
  62         >>> repo = Repo.create("/var/git/git-python.git")
  63
  64 Getting a list of commits
  65 *************************
  66
  67 From the ``Repo`` object, you can get a list of ``Commit``
  68 objects.
  69
  70         >>> repo.commits()
  71         [<GitPython.Commit "207c0c4418115df0d30820ab1a9acd2ea4bf4431">,
  72          <GitPython.Commit "a91c45eee0b41bf3cdaad3418ca3850664c4a4b4">,
  73          <GitPython.Commit "e17c7e11aed9e94d2159e549a99b966912ce1091">,
  74          <GitPython.Commit "bd795df2d0e07d10e0298670005c0e9d9a5ed867">]
  75
  76 Called without arguments, ``Repo.commits`` returns a list of up to ten commits
  77 reachable by the master branch (starting at the latest commit). You can ask
  78 for commits beginning at a different branch, commit, tag, etc.
  79
  80         >>> repo.commits('mybranch')
  81         >>> repo.commits('40d3057d09a7a4d61059bca9dca5ae698de58cbe')
  82         >>> repo.commits('v0.1')
  83
  84 You can specify the maximum number of commits to return.
  85
  86         >>> repo.commits('master', 100)
  87
  88 If you need paging, you can specify a number of commits to skip.
  89
  90         >>> repo.commits('master', 10, 20)
  91
  92 The above will return commits 21-30 from the commit list.
  93
  94 The Commit object
  95 *****************
  96
  97 Commit objects contain information about a specific commit.
  98
  99         >>> head = repo.commits()[0]
 100
 101         >>> head.id
 102         '207c0c4418115df0d30820ab1a9acd2ea4bf4431'
 103
 104         >>> head.parents
 105         [<GitPython.Commit "a91c45eee0b41bf3cdaad3418ca3850664c4a4b4">]
 106
 107         >>> head.tree
 108         <GitPython.Tree "563413aedbeda425d8d9dcbb744247d0c3e8a0ac">
 109
 110         >>> head.author
 111         <GitPython.Actor "Michael Trier <mtrier@gmail.com>">
 112
 113         >>> head.authored_date
 114         (2008, 5, 7, 5, 0, 56, 2, 128, 0)
 115
 116         >>> head.committer
 117         <GitPython.Actor "Michael Trier <mtrier@gmail.com>">
 118
 119         >>> head.committed_date
 120         (2008, 5, 7, 5, 0, 56, 2, 128, 0)
 121
 122         >>> head.message
 123         'cleaned up a lot of test information. Fixed escaping so it works with
 124         subprocess.'
 125
 126 Note: date time is represented in a `struct_time`_ format.  Conversion to
 127 human readable form can be accomplished with the various time module methods.
 128
 129         >>> import time
 130         >>> time.asctime(head.committed_date)
 131         'Wed May 7 05:56:02 2008'
 132
 133         >>> time.strftime("%a, %d %b %Y %H:%M", head.committed_date)
 134         'Wed, 7 May 2008 05:56'
 135
 136 .. _struct_time: http://docs.python.org/lib/module-time.html
 137
 138 You can traverse a commit's ancestry by chaining calls to ``parents``.
 139
 140         >>> repo.commits()[0].parents[0].parents[0].parents[0]
 141
 142 The above corresponds to ``master^^^`` or ``master~3`` in git parlance.
 143
 144 The Tree object
 145 ***************
 146
 147 A tree records pointers to the contents of a directory. Let's say you want
 148 the root tree of the latest commit on the master branch.
 149
 150         >>> tree = repo.commits()[0].tree
 151         <GitPython.Tree "a006b5b1a8115185a228b7514cdcd46fed90dc92">
 152
 153         >>> tree.id
 154         'a006b5b1a8115185a228b7514cdcd46fed90dc92'
 155
 156 Once you have a tree, you can get the contents.
 157
 158         >>> contents = tree.contents
 159         [<GitPython.Blob "6a91a439ea968bf2f5ce8bb1cd8ddf5bf2cad6c7">,
 160          <GitPython.Blob "e69de29bb2d1d6434b8b29ae775ad8c2e48c5391">,
 161          <GitPython.Tree "eaa0090ec96b054e425603480519e7cf587adfc3">,
 162          <GitPython.Blob "980e72ae16b5378009ba5dfd6772b59fe7ccd2df">]
 163
 164 This tree contains three ``Blob`` objects and one ``Tree`` object. The trees
 165 are subdirectories and the blobs are files. Trees below the root have
 166 additional attributes.
 167
 168         >>> contents = tree.contents[-2]
 169         <GitPython.Tree "e5445b9db4a9f08d5b4de4e29e61dffda2f386ba">
 170
 171         >>> contents.name
 172         'test'
 173
 174         >>> contents.mode
 175         '040000'
 176
 177 There is a convenience method that allows you to get a named sub-object
 178 from a tree.
 179
 180         >>> tree/"lib"
 181         <GitPython.Tree "c1c7214dde86f76bc3e18806ac1f47c38b2b7a30">
 182
 183 You can also get a tree directly from the repository if you know its name.
 184
 185         >>> repo.tree()
 186         <GitPython.Tree "master">
 187
 188         >>> repo.tree("c1c7214dde86f76bc3e18806ac1f47c38b2b7a30")
 189         <GitPython.Tree "c1c7214dde86f76bc3e18806ac1f47c38b2b7a30">
 190
 191 The Blob object
 192 ***************
 193
 194 A blob represents a file. Trees often contain blobs.
 195
 196         >>> blob = tree.contents[-1]
 197         <GitPython.Blob "b19574431a073333ea09346eafd64e7b1908ef49">
 198
 199 A blob has certain attributes.
 200
 201         >>> blob.name
 202         'urls.py'
 203
 204         >>> blob.mode
 205         '100644'
 206
 207         >>> blob.mime_type
 208         'text/x-python'
 209
 210         >>> blob.size
 211         415
 212
 213 You can get the data of a blob as a string.
 214
 215         >>> blob.data
 216         "from django.conf.urls.defaults import *\nfrom django.conf..."
 217
 218 You can also get a blob directly from the repo if you know its name.
 219
 220         >>> repo.blob("b19574431a073333ea09346eafd64e7b1908ef49")
 221         <GitPython.Blob "b19574431a073333ea09346eafd64e7b1908ef49">
 222
 223 What Else?
 224 **********
 225
 226 There is more stuff in there, like the ability to tar or gzip repos, stats,
 227 log, blame, and probably a few other things.  Additionally calls to the git
 228 instance are handled through a ``method_missing`` construct, which makes
 229 available any git commands directly, with a nice conversion of Python dicts
 230 to command line parameters.
 231
 232 Check the unit tests, they're pretty exhaustive.
 233
 234 LICENSE
 235 =======
 236
 237 New BSD License.  See the LICENSE file.