Commit c76852d0bff115720af3f27acdb084c59361e5f6

Michael Trier
Sat Jan 24 21:40:27 CET 2009

Tree SHA1: 1a32625
Parent SHA1: bcd57e3 (Corrected a problem with commits_between returning None.)
raw diff | raw patch

Lots of spring cleaning and added in Sphinx documentation.

Diff rendering mode:
inline
side by side


1		Michael Trier <mtrier _at_ gmail.com>
2		Alan Briolat
3		Florian Apolloner <florian _at_ apolloner.eu>
4		David Aguilar <davvid _at_ gmail.com>
5		Jelmer Vernooij <jelmer _at_ samba.org>
6		Steve Frécinaux <code _at_ istique.net>
7		Kai Lautaportti <kai _at_ lautaportti.fi>
8		Paul Sowden <paul _at_ idontsmoke.co.uk>
	1	GitPython was originally written by Michael Trier.
	2
	3	Contributors are:
	4
	5	-Michael Trier <mtrier _at_ gmail.com>
	6	-Alan Briolat
	7	-Florian Apolloner <florian _at_ apolloner.eu>
	8	-David Aguilar <davvid _at_ gmail.com>
	9	-Jelmer Vernooij <jelmer _at_ samba.org>
	10	-Steve Frécinaux <code _at_ istique.net>
	11	-Kai Lautaportti <kai _at_ lautaportti.fi>
	12	-Paul Sowden <paul _at_ idontsmoke.co.uk>
	13
	14	Portions derived from other open source works and are clearly marked.


7	7
8	8	General
9	9	-------
	10	* Added in Sphinx documentation.
	11
10	12	* Removed ambiguity between paths and treeishs. When calling commands that
11	13	accept treeish and path arguments and there is a path with the same name as
12	14	a treeish git cowardly refuses to pick one and asks for the command to use


1		Copyright (c) 2008, Michael Trier and contributors
	1	Copyright (C) 2008, 2009 Michael Trier and contributors
2	2	All rights reserved.
3	3
4	4	Redistribution and use in source and binary forms, with or without


		1	# Makefile for Sphinx documentation
		2	#
		3
		4	# You can set these variables from the command line.
		5	SPHINXOPTS =
		6	SPHINXBUILD = sphinx-build
		7	PAPER =
		8
		9	# Internal variables.
		10	PAPEROPT_a4 = -D latex_paper_size=a4
		11	PAPEROPT_letter = -D latex_paper_size=letter
		12	ALLSPHINXOPTS = -d _build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
		13
		14	.PHONY: help clean html web pickle htmlhelp latex changes linkcheck
		15
		16	help:
		17	@echo "Please use \`make <target>' where <target> is one of"
		18	@echo " html to make standalone HTML files"
		19	@echo " pickle to make pickle files"
		20	@echo " json to make JSON files"
		21	@echo " htmlhelp to make HTML files and a HTML help project"
		22	@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
		23	@echo " changes to make an overview over all changed/added/deprecated items"
		24	@echo " linkcheck to check all external links for integrity"
		25
		26	clean:
		27	-rm -rf _build/*
		28
		29	html:
		30	mkdir -p _build/html _build/doctrees
		31	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) _build/html
		32	@echo
		33	@echo "Build finished. The HTML pages are in _build/html."
		34
		35	pickle:
		36	mkdir -p _build/pickle _build/doctrees
		37	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) _build/pickle
		38	@echo
		39	@echo "Build finished; now you can process the pickle files."
		40
		41	web: pickle
		42
		43	json:
		44	mkdir -p _build/json _build/doctrees
		45	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) _build/json
		46	@echo
		47	@echo "Build finished; now you can process the JSON files."
		48
		49	htmlhelp:
		50	mkdir -p _build/htmlhelp _build/doctrees
		51	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) _build/htmlhelp
		52	@echo
		53	@echo "Build finished; now you can run HTML Help Workshop with the" \
		54	".hhp project file in _build/htmlhelp."
		55
		56	latex:
		57	mkdir -p _build/latex _build/doctrees
		58	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex
		59	@echo
		60	@echo "Build finished; the LaTeX files are in _build/latex."
		61	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
		62	"run these through (pdf)latex."
		63
		64	changes:
		65	mkdir -p _build/changes _build/doctrees
		66	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) _build/changes
		67	@echo
		68	@echo "The overview file is in _build/changes."
		69
		70	linkcheck:
		71	mkdir -p _build/linkcheck _build/doctrees
		72	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) _build/linkcheck
		73	@echo
		74	@echo "Link check complete; look for any errors in the above output " \
		75	"or in _build/linkcheck/output.txt."


		1	# -- coding: utf-8 --
		2	#
		3	# GitPython documentation build configuration file, created by
		4	# sphinx-quickstart on Sat Jan 24 11:51:01 2009.
		5	#
		6	# This file is execfile()d with the current directory set to its containing dir.
		7	#
		8	# The contents of this file are pickled, so don't put values in the namespace
		9	# that aren't pickleable (module imports are okay, they're removed automatically).
		10	#
		11	# Note that not all possible configuration values are present in this
		12	# autogenerated file.
		13	#
		14	# All configuration values have a default; values that are commented out
		15	# serve to show the default.
		16
		17	import sys, os
		18
		19	# If your extensions are in another directory, add it here. If the directory
		20	# is relative to the documentation root, use os.path.abspath to make it
		21	# absolute, like shown here.
		22	#sys.path.append(os.path.abspath('.'))
		23	sys.path.insert(0, os.path.abspath('../lib'))
		24
		25	# General configuration
		26	# ---------------------
		27
		28	# Add any Sphinx extension module names here, as strings. They can be extensions
		29	# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
		30	extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest']
		31
		32	# Add any paths that contain templates here, relative to this directory.
		33	templates_path = ['templates']
		34
		35	# The suffix of source filenames.
		36	source_suffix = '.rst'
		37
		38	# The encoding of source files.
		39	#source_encoding = 'utf-8'
		40
		41	# The master toctree document.
		42	master_doc = 'index'
		43
		44	# General information about the project.
		45	project = u'GitPython'
		46	copyright = u'Copyright (C) 2008, 2009 Michael Trier and contributors'
		47
		48	# The version info for the project you're documenting, acts as replacement for
		49	# \|version\| and \|release\|, also used in various other places throughout the
		50	# built documents.
		51	#
		52	# The short X.Y version.
		53	version = '0.1.6'
		54	# The full version, including alpha/beta/rc tags.
		55	release = '0.1.6'
		56
		57	# The language for content autogenerated by Sphinx. Refer to documentation
		58	# for a list of supported languages.
		59	#language = None
		60
		61	# There are two options for replacing \|today\|: either, you set today to some
		62	# non-false value, then it is used:
		63	#today = ''
		64	# Else, today_fmt is used as the format for a strftime call.
		65	#today_fmt = '%B %d, %Y'
		66
		67	# List of documents that shouldn't be included in the build.
		68	#unused_docs = []
		69
		70	# List of directories, relative to source directory, that shouldn't be searched
		71	# for source files.
		72	exclude_trees = ['_build']
		73
		74	# The reST default role (used for this markup: `text`) to use for all documents.
		75	#default_role = None
		76
		77	# If true, '()' will be appended to :func: etc. cross-reference text.
		78	#add_function_parentheses = True
		79
		80	# If true, the current module name will be prepended to all description
		81	# unit titles (such as .. function::).
		82	#add_module_names = True
		83
		84	# If true, sectionauthor and moduleauthor directives will be shown in the
		85	# output. They are ignored by default.
		86	#show_authors = False
		87
		88	# The name of the Pygments (syntax highlighting) style to use.
		89	pygments_style = 'sphinx'
		90
		91
		92	# Options for HTML output
		93	# -----------------------
		94
		95	# The style sheet to use for HTML and HTML Help pages. A file of that name
		96	# must exist either in Sphinx' static/ path, or in one of the custom paths
		97	# given in html_static_path.
		98	html_style = 'default.css'
		99
		100	# The name for this set of Sphinx documents. If None, it defaults to
		101	# "<project> v<release> documentation".
		102	#html_title = None
		103
		104	# A shorter title for the navigation bar. Default is the same as html_title.
		105	#html_short_title = None
		106
		107	# The name of an image file (relative to this directory) to place at the top
		108	# of the sidebar.
		109	#html_logo = None
		110
		111	# The name of an image file (within the static path) to use as favicon of the
		112	# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
		113	# pixels large.
		114	#html_favicon = None
		115
		116	# Add any paths that contain custom static files (such as style sheets) here,
		117	# relative to this directory. They are copied after the builtin static files,
		118	# so a file named "default.css" will overwrite the builtin "default.css".
		119	html_static_path = ['static']
		120
		121	# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
		122	# using the given strftime format.
		123	#html_last_updated_fmt = '%b %d, %Y'
		124
		125	# If true, SmartyPants will be used to convert quotes and dashes to
		126	# typographically correct entities.
		127	#html_use_smartypants = True
		128
		129	# Custom sidebar templates, maps document names to template names.
		130	#html_sidebars = {}
		131
		132	# Additional templates that should be rendered to pages, maps page names to
		133	# template names.
		134	#html_additional_pages = {}
		135
		136	# If false, no module index is generated.
		137	#html_use_modindex = True
		138
		139	# If false, no index is generated.
		140	#html_use_index = True
		141
		142	# If true, the index is split into individual pages for each letter.
		143	#html_split_index = False
		144
		145	# If true, the reST sources are included in the HTML build as _sources/<name>.
		146	#html_copy_source = True
		147
		148	# If true, an OpenSearch description file will be output, and all pages will
		149	# contain a <link> tag referring to it. The value of this option must be the
		150	# base URL from which the finished HTML is served.
		151	#html_use_opensearch = ''
		152
		153	# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
		154	#html_file_suffix = ''
		155
		156	# Output file base name for HTML help builder.
		157	htmlhelp_basename = 'gitpythondoc'
		158
		159
		160	# Options for LaTeX output
		161	# ------------------------
		162
		163	# The paper size ('letter' or 'a4').
		164	#latex_paper_size = 'letter'
		165
		166	# The font size ('10pt', '11pt' or '12pt').
		167	#latex_font_size = '10pt'
		168
		169	# Grouping the document tree into LaTeX files. List of tuples
		170	# (source start file, target name, title, author, document class [howto/manual]).
		171	latex_documents = [
		172	('index', 'GitPython.tex', ur'GitPython Documentation',
		173	ur'Michael Trier', 'manual'),
		174	]
		175
		176	# The name of an image file (relative to this directory) to place at the top of
		177	# the title page.
		178	#latex_logo = None
		179
		180	# For "manual" documents, if this is true, then toplevel headings are parts,
		181	# not chapters.
		182	#latex_use_parts = False
		183
		184	# Additional stuff for the LaTeX preamble.
		185	#latex_preamble = ''
		186
		187	# Documents to append as an appendix to all manuals.
		188	#latex_appendices = []
		189
		190	# If false, no module index is generated.
		191	#latex_use_modindex = True


		1	.. GitPython documentation master file, created by sphinx-quickstart on Sat Jan 24 11:51:01 2009.
		2	You can adapt this file completely to your liking, but it should at least
		3	contain the root `toctree` directive.
		4
		5	GitPython Documentation
		6	=======================
		7
		8	Contents:
		9
		10	.. toctree::
		11	:maxdepth: 3
		12
		13	intro
		14	tutorial
		15	reference
		16
		17	Indices and tables
		18	==================
		19
		20	* :ref:`genindex`
		21	* :ref:`modindex`
		22	* :ref:`search`


		1	.. _intro_toplevel:
		2
		3	==================
		4	Overview / Install
		5	==================
		6
		7	GitPython is a python library used to interact with Git repositories.
		8
		9	GitPython is a port of the grit_ library in Ruby created by
		10	Tom Preston-Werner and Chris Wanstrath.
		11
		12	.. _grit: http://grit.rubyforge.org
		13
		14	Requirements
		15	============
		16
		17	* Git_ tested with 1.5.3.7
		18	* `Python Nose`_ - used for running the tests
		19	* `Mock by Michael Foord`_ used for tests. Requires 0.4
		20
		21	.. _Git: http://git-scm.com/
		22	.. _Python Nose: http://code.google.com/p/python-nose/
		23	.. _Mock by Michael Foord: http://www.voidspace.org.uk/python/mock.html
		24
		25	Installing GitPython
		26	====================
		27
		28	Installing GitPython is easily done using
		29	`setuptools`_. Assuming it is
		30	installed, just run the following from the command-line:
		31
		32	.. sourcecode:: none
		33
		34	# easy_install GitPython
		35
		36	This command will download the latest version of GitPython from the
		37	`Python Package Index <http://pypi.python.org/pypi/GitPython>`_ and install it
		38	to your system. More information about ``easy_install`` and pypi can be found
		39	here:
		40
		41	* `setuptools`_
		42	* `install setuptools <http://peak.telecommunity.com/DevCenter/EasyInstall#installation-instructions>`_
		43	* `pypi <http://pypi.python.org/pypi/SQLAlchemy>`_
		44
		45	.. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools
		46
		47	Alternatively, you can install from the distribution using the ``setup.py``
		48	script:
		49
		50	.. sourcecode:: none
		51
		52	# python setup.py install
		53
		54	Getting Started
		55	===============
		56
		57	* :ref:`tutorial_toplevel` - This tutorial provides a walk-through of some of
		58	the basic functionality and concepts used in GitPython. It, however, is not
		59	exhaustive so you are encouraged to spend some time in the
		60	:ref:`api_reference_toplevel`.
		61
		62	API Reference
		63	=============
		64
		65	An organized section of the GitPthon API is at :ref:`api_reference_toplevel`.
		66
		67	Source Code
		68	===========
		69
		70	GitPython's git repo is available on Gitorious, which can be browsed at:
		71
		72	http://gitorious.org/projects/git-python/
		73
		74	and cloned from:
		75
		76	git://gitorious.org/git-python/mainline.git
		77
		78	License Information
		79	===================
		80
		81	GitPython is licensed under the New BSD License. See the LICENSE file for
		82	more information.


		1	.. _api_reference_toplevel:
		2
		3	API Reference
		4	=============
		5
		6	Actor
		7	-----
		8
		9	.. automodule:: git.actor
		10	:members:
		11	:undoc-members:
		12
		13	Blob
		14	----
		15
		16	.. automodule:: git.blob
		17	:members:
		18	:undoc-members:
		19
		20	Git
		21	---
		22
		23	.. automodule:: git.cmd
		24	:members:
		25	:undoc-members:
		26
		27	Commit
		28	------
		29
		30	.. automodule:: git.commit
		31	:members:
		32	:undoc-members:
		33
		34	Diff
		35	----
		36
		37	.. automodule:: git.diff
		38	:members:
		39	:undoc-members:
		40
		41	Errors
		42	------
		43
		44	.. automodule:: git.errors
		45	:members:
		46	:undoc-members:
		47
		48	Head
		49	----
		50
		51	.. automodule:: git.head
		52	:members:
		53	:undoc-members:
		54
		55	Lazy
		56	----
		57
		58	.. automodule:: git.lazy
		59	:members:
		60	:undoc-members:
		61
		62	Repo
		63	----
		64
		65	.. automodule:: git.repo
		66	:members:
		67	:undoc-members:
		68
		69	Stats
		70	-----
		71
		72	.. automodule:: git.stats
		73	:members:
		74	:undoc-members:
		75
		76	Tag
		77	---
		78
		79	.. automodule:: git.tag
		80	:members:
		81	:undoc-members:
		82
		83	Tree
		84	----
		85
		86	.. automodule:: git.tree
		87	:members:
		88	:undoc-members:
		89
		90	Utils
		91	-----
		92
		93	.. automodule:: git.utils
		94	:members:
		95	:undoc-members:


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


	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		[<git.Commit "207c0c4418115df0d30820ab1a9acd2ea4bf4431">,
	31		<git.Commit "a91c45eee0b41bf3cdaad3418ca3850664c4a4b4">,
	32		<git.Commit "e17c7e11aed9e94d2159e549a99b966912ce1091">,
	33		<git.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', max_count=100)
	46
	47		If you need paging, you can specify a number of commits to skip.
	48
	49		>>> repo.commits('master', max_count=10, skip=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		[<git.Commit "a91c45eee0b41bf3cdaad3418ca3850664c4a4b4">]
	65
	66		>>> head.tree
	67		<git.Tree "563413aedbeda425d8d9dcbb744247d0c3e8a0ac">
	68
	69		>>> head.author
	70		<git.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		<git.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		<git.Tree "a006b5b1a8115185a228b7514cdcd46fed90dc92">
	111
	112		>>> tree.id
	113		'a006b5b1a8115185a228b7514cdcd46fed90dc92'
	114
	115		Once you have a tree, you can get the contents.
	116
	117		>>> contents = tree.values()
	118		[<git.Blob "6a91a439ea968bf2f5ce8bb1cd8ddf5bf2cad6c7">,
	119		<git.Blob "e69de29bb2d1d6434b8b29ae775ad8c2e48c5391">,
	120		<git.Tree "eaa0090ec96b054e425603480519e7cf587adfc3">,
	121		<git.Blob "980e72ae16b5378009ba5dfd6772b59fe7ccd2df">]
	122
	123		The tree is implements a dictionary protocol so it can be used and acts just
	124		like a dictionary with some additional properties.
	125
	126		>>> tree.items()
	127		[('lib', <git.Tree "310ebc9a0904531438bdde831fd6a27c6b6be58e">),
	128		('LICENSE', <git.Blob "6797c1421052efe2ded9efdbb498b37aeae16415">),
	129		('doc', <git.Tree "a58386dd101f6eb7f33499317e5508726dfd5e4f">),
	130		('MANIFEST.in', <git.Blob "7da4e346bb0a682e99312c48a1f452796d3fb988">),
	131		('.gitignore', <git.Blob "6870991011cc8d9853a7a8a6f02061512c6a8190">),
	132		('test', <git.Tree "c6f6ee37d328987bc6fb47a33fed16c7886df857">),
	133		('VERSION', <git.Blob "9faa1b7a7339db85692f91ad4b922554624a3ef7">),
	134		('AUTHORS', <git.Blob "9f649ef5448f9666d78356a2f66ba07c5fb27229">),
	135		('README', <git.Blob "9643dcf549f34fbd09503d4c941a5d04157570fe">),
	136		('ez_setup.py', <git.Blob "3031ad0d119bd5010648cf8c038e2bbe21969ecb">),
	137		('setup.py', <git.Blob "271074302aee04eb0394a4706c74f0c2eb504746">),
	138		('CHANGES', <git.Blob "0d236f3d9f20d5e5db86daefe1e3ba1ce68e3a97">)]
	139
	140		This tree contains three ``Blob`` objects and one ``Tree`` object. The trees
	141		are subdirectories and the blobs are files. Trees below the root have
	142		additional attributes.
	143
	144		>>> contents = tree["lib"]
	145		<git.Tree "c1c7214dde86f76bc3e18806ac1f47c38b2b7a3">
	146
	147		>>> contents.name
	148		'test'
	149
	150		>>> contents.mode
	151		'040000'
	152
	153		There is a convenience method that allows you to get a named sub-object
	154		from a tree with a syntax similar to how paths are written in an unix
	155		system.
	156
	157		>>> tree/"lib"
	158		<git.Tree "c1c7214dde86f76bc3e18806ac1f47c38b2b7a30">
	159
	160		You can also get a tree directly from the repository if you know its name.
	161
	162		>>> repo.tree()
	163		<git.Tree "master">
	164
	165		>>> repo.tree("c1c7214dde86f76bc3e18806ac1f47c38b2b7a30")
	166		<git.Tree "c1c7214dde86f76bc3e18806ac1f47c38b2b7a30">
	167
	168		The Blob object
	169		***************
	170
	171		A blob represents a file. Trees often contain blobs.
	172
	173		>>> blob = tree['urls.py']
	174		<git.Blob "b19574431a073333ea09346eafd64e7b1908ef49">
	175
	176		A blob has certain attributes.
	177
	178		>>> blob.name
	179		'urls.py'
	180
	181		>>> blob.mode
	182		'100644'
	183
	184		>>> blob.mime_type
	185		'text/x-python'
	186
	187		>>> blob.size
	188		415
	189
	190		You can get the data of a blob as a string.
	191
	192		>>> blob.data
	193		"from django.conf.urls.defaults import *\nfrom django.conf..."
	194
	195		You can also get a blob directly from the repo if you know its name.
	196
	197		>>> repo.blob("b19574431a073333ea09346eafd64e7b1908ef49")
	198		<git.Blob "b19574431a073333ea09346eafd64e7b1908ef49">
	199
	200		What Else?
	201		**********
	202
	203		There is more stuff in there, like the ability to tar or gzip repos, stats,
	204		log, blame, and probably a few other things. Additionally calls to the git
	205		instance are handled through a ``__getattr__`` construct, which makes
	206		available any git commands directly, with a nice conversion of Python dicts
	207		to command line parameters.
	208
	209		Check the unit tests, they're pretty exhaustive.


1	1	# __init__.py
2		# Copyright (C) 2008 Michael Trier (mtrier@gmail.com) and contributors
	2	# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
3	3	#
4	4	# This module is part of GitPython and is released under
5	5	# the BSD License: http://www.opensource.org/licenses/bsd-license.php


1	1	# actor.py
2		# Copyright (C) 2008 Michael Trier (mtrier@gmail.com) and contributors
	2	# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
3	3	#
4	4	# This module is part of GitPython and is released under
5	5	# the BSD License: http://www.opensource.org/licenses/bsd-license.php


1	1	# blob.py
2		# Copyright (C) 2008 Michael Trier (mtrier@gmail.com) and contributors
	2	# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
3	3	#
4	4	# This module is part of GitPython and is released under
5	5	# the BSD License: http://www.opensource.org/licenses/bsd-license.php


1	1	# cmd.py
2		# Copyright (C) 2008 Michael Trier (mtrier@gmail.com) and contributors
	2	# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
3	3	#
4	4	# This module is part of GitPython and is released under
5	5	# the BSD License: http://www.opensource.org/licenses/bsd-license.php


1	1	# commit.py
2		# Copyright (C) 2008 Michael Trier (mtrier@gmail.com) and contributors
	2	# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
3	3	#
4	4	# This module is part of GitPython and is released under
5	5	# the BSD License: http://www.opensource.org/licenses/bsd-license.php


1	1	# diff.py
2		# Copyright (C) 2008 Michael Trier (mtrier@gmail.com) and contributors
	2	# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
3	3	#
4	4	# This module is part of GitPython and is released under
5	5	# the BSD License: http://www.opensource.org/licenses/bsd-license.php


1	1	# errors.py
2		# Copyright (C) 2008 Michael Trier (mtrier@gmail.com) and contributors
	2	# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
3	3	#
4	4	# This module is part of GitPython and is released under
5	5	# the BSD License: http://www.opensource.org/licenses/bsd-license.php


1	1	# head.py
2		# Copyright (C) 2008 Michael Trier (mtrier@gmail.com) and contributors
	2	# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
3	3	#
4	4	# This module is part of GitPython and is released under
5	5	# the BSD License: http://www.opensource.org/licenses/bsd-license.php


1	1	# lazy.py
2		# Copyright (C) 2008 Michael Trier (mtrier@gmail.com) and contributors
	2	# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
3	3	#
4	4	# This module is part of GitPython and is released under
5	5	# the BSD License: http://www.opensource.org/licenses/bsd-license.php


1	1	# repo.py
2		# Copyright (C) 2008 Michael Trier (mtrier@gmail.com) and contributors
	2	# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
3	3	#
4	4	# This module is part of GitPython and is released under
5	5	# the BSD License: http://www.opensource.org/licenses/bsd-license.php


1	1	# stats.py
2		# Copyright (C) 2008 Michael Trier (mtrier@gmail.com) and contributors
	2	# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
3	3	#
4	4	# This module is part of GitPython and is released under
5	5	# the BSD License: http://www.opensource.org/licenses/bsd-license.php


1	1	# tag.py
2		# Copyright (C) 2008 Michael Trier (mtrier@gmail.com) and contributors
	2	# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
3	3	#
4	4	# This module is part of GitPython and is released under
5	5	# the BSD License: http://www.opensource.org/licenses/bsd-license.php


1	1	# tree.py
2		# Copyright (C) 2008 Michael Trier (mtrier@gmail.com) and contributors
	2	# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
3	3	#
4	4	# This module is part of GitPython and is released under
5	5	# the BSD License: http://www.opensource.org/licenses/bsd-license.php


1	1	# utils.py
2		# Copyright (C) 2008 Michael Trier (mtrier@gmail.com) and contributors
	2	# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
3	3	#
4	4	# This module is part of GitPython and is released under
5	5	# the BSD License: http://www.opensource.org/licenses/bsd-license.php


74	74	"Development Status :: 3 - Alpha",
75	75	"Intended Audience :: Developers",
76	76	"License :: OSI Approved :: BSD License",
	77	"Operating System :: OS Independent",
77	78	"Programming Language :: Python",
	79	"Programming Language :: Python :: 2.5",
	80	"Programming Language :: Python :: 2.6",
78	81	"Topic :: Software Development :: Libraries :: Python Modules",
79	82	]
80	83	)


1	1	# __init__.py
2		# Copyright (C) 2008 Michael Trier (mtrier@gmail.com) and contributors
	2	# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
3	3	#
4	4	# This module is part of GitPython and is released under
5	5	# the BSD License: http://www.opensource.org/licenses/bsd-license.php


1	1	# __init__.py
2		# Copyright (C) 2008 Michael Trier (mtrier@gmail.com) and contributors
	2	# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
3	3	#
4	4	# This module is part of GitPython and is released under
5	5	# the BSD License: http://www.opensource.org/licenses/bsd-license.php


1	1	# test_actor.py
2		# Copyright (C) 2008 Michael Trier (mtrier@gmail.com) and contributors
	2	# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
3	3	#
4	4	# This module is part of GitPython and is released under
5	5	# the BSD License: http://www.opensource.org/licenses/bsd-license.php


1	1	# test_blob.py
2		# Copyright (C) 2008 Michael Trier (mtrier@gmail.com) and contributors
	2	# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
3	3	#
4	4	# This module is part of GitPython and is released under
5	5	# the BSD License: http://www.opensource.org/licenses/bsd-license.php


1	1	# test_commit.py
2		# Copyright (C) 2008 Michael Trier (mtrier@gmail.com) and contributors
	2	# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
3	3	#
4	4	# This module is part of GitPython and is released under
5	5	# the BSD License: http://www.opensource.org/licenses/bsd-license.php


1	1	# test_diff.py
2		# Copyright (C) 2008 Michael Trier (mtrier@gmail.com) and contributors
	2	# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
3	3	#
4	4	# This module is part of GitPython and is released under
5	5	# the BSD License: http://www.opensource.org/licenses/bsd-license.php


1	1	# test_git.py
2		# Copyright (C) 2008 Michael Trier (mtrier@gmail.com) and contributors
	2	# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
3	3	#
4	4	# This module is part of GitPython and is released under
5	5	# the BSD License: http://www.opensource.org/licenses/bsd-license.php


1	1	# test_head.py
2		# Copyright (C) 2008 Michael Trier (mtrier@gmail.com) and contributors
	2	# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
3	3	#
4	4	# This module is part of GitPython and is released under
5	5	# the BSD License: http://www.opensource.org/licenses/bsd-license.php


1	1	# test_repo.py
2		# Copyright (C) 2008 Michael Trier (mtrier@gmail.com) and contributors
	2	# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
3	3	#
4	4	# This module is part of GitPython and is released under
5	5	# the BSD License: http://www.opensource.org/licenses/bsd-license.php


1	1	# test_stats.py
2		# Copyright (C) 2008 Michael Trier (mtrier@gmail.com) and contributors
	2	# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
3	3	#
4	4	# This module is part of GitPython and is released under
5	5	# the BSD License: http://www.opensource.org/licenses/bsd-license.php


1	1	# test_tag.py
2		# Copyright (C) 2008 Michael Trier (mtrier@gmail.com) and contributors
	2	# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
3	3	#
4	4	# This module is part of GitPython and is released under
5	5	# the BSD License: http://www.opensource.org/licenses/bsd-license.php


1	1	# test_tree.py
2		# Copyright (C) 2008 Michael Trier (mtrier@gmail.com) and contributors
	2	# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
3	3	#
4	4	# This module is part of GitPython and is released under
5	5	# the BSD License: http://www.opensource.org/licenses/bsd-license.php


1	1	# test_utils.py
2		# Copyright (C) 2008 Michael Trier (mtrier@gmail.com) and contributors
	2	# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
3	3	#
4	4	# This module is part of GitPython and is released under
5	5	# the BSD License: http://www.opensource.org/licenses/bsd-license.php


1	1	# __init__.py
2		# Copyright (C) 2008 Michael Trier (mtrier@gmail.com) and contributors
	2	# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
3	3	#
4	4	# This module is part of GitPython and is released under
5	5	# the BSD License: http://www.opensource.org/licenses/bsd-license.php


1	1	# asserts.py
2		# Copyright (C) 2008 Michael Trier (mtrier@gmail.com) and contributors
	2	# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
3	3	#
4	4	# This module is part of GitPython and is released under
5	5	# the BSD License: http://www.opensource.org/licenses/bsd-license.php


1	1	# helper.py
2		# Copyright (C) 2008 Michael Trier (mtrier@gmail.com) and contributors
	2	# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
3	3	#
4	4	# This module is part of GitPython and is released under
5	5	# the BSD License: http://www.opensource.org/licenses/bsd-license.php

Commit c76852d0bff115720af3f27acdb084c59361e5f6

Gitorious