doc/tutorial.txt

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