Working on the docs, talk more about objects
This commit is contained in:
J. David Ibáñez
182
README.md
182
README.md
@@ -4,6 +4,10 @@ pygit2 - libgit2 bindings in Python
|
||||
pygit2 is a set of Python bindings to the libgit2 linkable C Git library.
|
||||
The supported versions of Python are 2.6, 2.7, 3.1 and 3.2
|
||||
|
||||
Through this text Python 3 is used for the inline examples. Also, the Python
|
||||
3 terminology is used (for instance we say text strings instead of unicode
|
||||
strings).
|
||||
|
||||
INSTALLING AND RUNNING
|
||||
========================
|
||||
|
||||
@@ -27,8 +31,124 @@ When those are installed, you can install pygit2:
|
||||
$ python setup.py test
|
||||
|
||||
|
||||
USING
|
||||
======
|
||||
Git objects
|
||||
===========
|
||||
|
||||
In the first place Git is a key-value storage system. The values stored are
|
||||
called *Git Objects*, there are four types (commits, trees, blobs and tags),
|
||||
each type there is a Python class:
|
||||
|
||||
# Open a repository
|
||||
>>> from pygit2 import Repository
|
||||
>>> repo = Repository('pygit2/.git')
|
||||
# Get the last commit
|
||||
>>> head = repo.lookup_reference('HEAD')
|
||||
>>> head = head.resolve()
|
||||
>>> commit = repo[head.oid]
|
||||
# Show commits and trees
|
||||
>>> commit
|
||||
<pygit2.Commit object at 0x7f9d2f3000b0>
|
||||
>>> commit.tree
|
||||
<pygit2.Tree object at 0x7f9d2f3000f0>
|
||||
|
||||
These four classes (``Commit``, ``Tree``, ``Blob`` and ``Tag``) inherit from
|
||||
the ``pygit2.Object`` base class, which provides shared behaviour. A Git
|
||||
object is identified by a unique *object id*, which is a binary byte string;
|
||||
this is often represented as an hexadecimal text string:
|
||||
|
||||
>>> commit.oid
|
||||
b'x\xde\xb5W\x8d\x01<\xdb\xdf\x08o\xa1\xd1\xa3\xe7\xd9\x82\xe8\x88\x8f'
|
||||
>>> commit.hex
|
||||
'78deb5578d013cdbdf086fa1d1a3e7d982e8888f'
|
||||
|
||||
The API of pygit2 accepts both the raw object id and its hexadecimal
|
||||
representation of the object id, the difference is done based on its type
|
||||
(a byte or a text string).
|
||||
|
||||
This is the common interface for all Git objects:
|
||||
|
||||
Object.type -- one of the GIT_OBJ_COMMIT, GIT_OBJ_TREE,
|
||||
GIT_OBJ_BLOB or GIT_OBJ_TAG constants
|
||||
Object.oid -- the object id, a byte string 20 bytes long
|
||||
Object.hex -- hexadecimal representation of the object id, a text
|
||||
string 40 chars long
|
||||
Object.read_raw() -- returns the byte string with the raw contents of the
|
||||
of the object
|
||||
|
||||
Objects can not be modified once they have been created.
|
||||
|
||||
|
||||
Commits
|
||||
-----------------
|
||||
|
||||
Commit.author -- the author of the commit
|
||||
Commit.committer -- the committer of the commit
|
||||
Commit.message -- the message, a text string
|
||||
Commit.tree -- the tree object attached to the commit
|
||||
Commit.parents -- the list of parent commits
|
||||
|
||||
The author and committer attributes of the commit are tuples with four
|
||||
elements, the author name and email, the unix time and time offset in
|
||||
minutes:
|
||||
|
||||
>>> commit.author
|
||||
('J. David Ibáñez', 'jdavid.ibp@gmail.com', 1315005198, 120)
|
||||
|
||||
Trees
|
||||
-----------------
|
||||
|
||||
A tree is a sorted collection of tree entries. It is similar to a folder or
|
||||
directory in a file system. Each entry points to another tree or a blob. A
|
||||
tree can be iterated, and partially implements the sequence and mapping
|
||||
interfaces:
|
||||
|
||||
# Number of entries
|
||||
>>> tree = commit.tree
|
||||
>>> len(tree)
|
||||
6
|
||||
# Iteratation
|
||||
>>> for entry in tree:
|
||||
... print(entry.hex, entry.name)
|
||||
...
|
||||
7151ca7cd3e59f3eab19c485cfbf3cb30928d7fa .gitignore
|
||||
c36f4cf1e38ec1bb9d9ad146ed572b89ecfc9f18 COPYING
|
||||
32b30b90b062f66957d6790c3c155c289c34424e README.md
|
||||
c87dae4094b3a6d10e08bc6c5ef1f55a7e448659 pygit2.c
|
||||
85a67270a49ef16cdd3d328f06a3e4b459f09b27 setup.py
|
||||
3d8985bbec338eb4d47c5b01b863ee89d044bd53 test
|
||||
# Get an entry by name
|
||||
>>> entry = tree['pygit2.c']
|
||||
>>> entry
|
||||
<pygit2.TreeEntry object at 0xcc10f0>
|
||||
# Get the object the entry points to
|
||||
>>> blob = repo[entry.oid]
|
||||
>>> blob
|
||||
<pygit2.Blob object at 0xcc12d0>
|
||||
|
||||
This is the interface of a tree entry:
|
||||
|
||||
TreeEntry.name -- name of the tree entry
|
||||
TreeEntry.oid -- the id of the git object
|
||||
TreeEntry.hex -- hexadecimal representation of the oid
|
||||
TreeEntry.attributes -- the Unix file attributes
|
||||
TreeEntry.to_object() -- returns the git object (equivalent to repo[entry.oid])
|
||||
|
||||
Blobs
|
||||
-----------------
|
||||
|
||||
A blob is equivalent to a file in a file system.
|
||||
|
||||
Blob.data -- the contents of the blob, a byte string
|
||||
|
||||
Tags
|
||||
-----------------
|
||||
|
||||
XXX
|
||||
|
||||
|
||||
The repository
|
||||
=================
|
||||
|
||||
|
||||
Initialize a Git repository:
|
||||
|
||||
@@ -41,6 +161,26 @@ Open a repository:
|
||||
>>> from pygit2 import Repository
|
||||
>>> repo = Repository('test/.git')
|
||||
|
||||
|
||||
References
|
||||
=================
|
||||
|
||||
Reference lookup:
|
||||
|
||||
>>> master_ref = repo.lookup_reference("refs/heads/master")
|
||||
>>> commit = repo[master_ref.oid]
|
||||
|
||||
|
||||
Revision walking
|
||||
=================
|
||||
|
||||
>>> from pygit2 import GIT_SORT_TIME
|
||||
>>> for commit in repo.walk(oid, GIT_SORT_TIME):
|
||||
... print commit.hex
|
||||
|
||||
The index file
|
||||
=================
|
||||
|
||||
Index read:
|
||||
|
||||
>>> index = repo.index
|
||||
@@ -48,14 +188,6 @@ Index read:
|
||||
>>> oid = index['path/to/file'].oid # from path to object id
|
||||
>>> blob = repo[oid] # from object id to object
|
||||
|
||||
Inspect the status of the repository:
|
||||
|
||||
>>> from pygit2 import GIT_STATUS_CURRENT
|
||||
>>> status = repo.status()
|
||||
>>> for filepath, flags in status.items():
|
||||
... if flags != GIT_STATUS_CURRENT:
|
||||
... print "Filepath %s isn't clean" % filepath
|
||||
|
||||
Iterate over all entries of the index:
|
||||
|
||||
>>> for entry in index:
|
||||
@@ -67,23 +199,16 @@ Index write:
|
||||
>>> del index['path/to/file'] # git rm
|
||||
>>> index.write() # don't forget to save the changes
|
||||
|
||||
Revision walking:
|
||||
Status
|
||||
=================
|
||||
|
||||
>>> from pygit2 import GIT_SORT_TIME
|
||||
>>> for commit in repo.walk(oid, GIT_SORT_TIME):
|
||||
... print commit.hex
|
||||
Inspect the status of the repository:
|
||||
|
||||
Read commit information:
|
||||
|
||||
>>> master_ref = repo.lookup_reference("refs/heads/master") # Getting the Reference object
|
||||
>>> commit = repo[master_ref.oid]
|
||||
>>> [name, email, timestamp, tz_offset] = commit.author # Read the commit authored infos
|
||||
>>> tree = commit.tree # Access the tree of the commit
|
||||
|
||||
Iterate over all entries of the tree:
|
||||
|
||||
>>> for entry in tree:
|
||||
... print entry.name, entry.hex, entry.attributes
|
||||
>>> from pygit2 import GIT_STATUS_CURRENT
|
||||
>>> status = repo.status()
|
||||
>>> for filepath, flags in status.items():
|
||||
... if flags != GIT_STATUS_CURRENT:
|
||||
... print "Filepath %s isn't clean" % filepath
|
||||
|
||||
|
||||
CONTRIBUTING
|
||||
@@ -93,6 +218,13 @@ Fork libgit2/pygit2 on GitHub, make it awesomer (preferably in a branch named
|
||||
for the topic), send a pull request.
|
||||
|
||||
|
||||
TODO
|
||||
----------------
|
||||
|
||||
XXX
|
||||
|
||||
|
||||
|
||||
AUTHORS
|
||||
==============
|
||||
|
||||
|
||||
Reference in New Issue
Block a user