Reference

This module provides interface to the objects:

  • Project - represents a repository

  • Commit - represents a commit in a repository

  • Tree - represents a directory and its content. Each Commit has a root tree.

  • File - represents a file path, including all parent directories/trees

  • Blob - Binary Large OBject, represents a file content.

  • Author - represents a combination of author name and email.

Commit, Tree and Blob are a straightforward representation of objects used by Git internally. It will be helpful to read Chapter 2 of Pro Git book (free and Open Source) for better understanding of these objects.

Common methods

All objects have a unique key. For git objects (Commit, Tree, Blob) it is the object SHA hash; for Project it is the project URI; for File it is the filename; for Author it is the author name and email. Objects of the same type and having the same key will be considered equivalent:

>>> sha = 'f2a7fcdc51450ab03cb364415f14e634fa69b62c'
>>> Commit(sha) == Commit(sha)
True

It is possible to iterate all objects of a given type using .all()

classmethod _Base.all()

E.g. to iterate all repositories of user2589 on github:

>>> for project in Project.all():
...     print project.uri

GitObject methods

These methods are shared by Commit, Tree, Blob.

All git objects are instantiated by a 40-byte hex string SHA or a 20-byte binary SHA. In most cases you will use hex form, the latter way is needed only fore relatively rare cases you need to interface with binary data.

>>> Commit('f2a7fcdc51450ab03cb364415f14e634fa69b62c')
>>> Commit(b'\xf2\xa7\xfc\xdcQE\n\xb0<\xb3dA_\x14\xe64\xfai\xb6,')

Whatever form of SHA was used to instantiate the object, it will have properties:

  • sha - 40-byte hex string

  • bin_sha - 20 bytes binary string

All git objects, when coerced to str, will return their internal representation. It is mostly important for Blob to access the file content.

Class reference

class oscar.Project(uri)

Projects are iterable:

>>> for commit in Project('user2589_minicms'):  
...     print(commit.sha)

Commits can be checked for membership in a project, either by their SHA hash or by a Commit object itself:

Commit: https://github.com/user2589/minicms/commit/e38126db >>> sha = ‘e38126dbca6572912013621d2aa9e6f7c50f36bc’ >>> sha in Project(‘user2589_minicms’) True >>> Commit(sha) in Project(‘user2589_minicms’) True

property commit_shas

SHA1 of all commits in the project

>>> Project(b'user2589_django-currencies').commit_shas
...         
('2dbcd43f077f2b5511cc107d63a0b9539a6aa2a7',
 '7572fc070c44f85e2a540f9a5a05a95d1dd2662d')
property commits

A generator of all Commit objects in the project. It has the same effect as iterating a Project instance itself, with some additional validation of commit dates.

>>> tuple(Project('user2589_django-currencies').commits)
...       
(<Commit: 2dbcd43f077f2b5511cc107d63a0b9539a6aa2a7>,
 <Commit: 7572fc070c44f85e2a540f9a5a05a95d1dd2662d>)
property commits_fp

Get a commit chain by following only the first parent, to mimic https://git-scm.com/docs/git-log#git-log—first-parent . Thus, you only get a small subset of the full commit tree:

>>> p = Project(b'user2589_minicms')
>>> set(c.sha for c in p.commits_fp).issubset(p.commit_shas)
True

In scenarios where branches are not important, it can save a lot of computing.

Yields:

Commit –

binary commit shas, following first parent only,

from the latest to the earliest.

property head

Get the HEAD commit of the repository

>>> Project('user2589_minicms').head
<Commit: f2a7fcdc51450ab03cb364415f14e634fa69b62c>
>>> Project('RoseTHERESA_SimpleCMS').head
<Commit: a47afa002ccfd3e23920f323b172f78c5c970250>
property tail

Get the first commit SHA by following first parents

>>> Project(b'user2589_minicms').tail
'1e971a073f40d74a1e72e07c682e1cba0bae159b'
class oscar.Commit(sha)

A git commit object.

Commits have some special properties. Most of object properties provided by this project are lazy, i.e. they are computed when you access them for the first time. The following Commit properties will be instantiated all at once on the first access to any of them.

  • tree: root Tree of the commit

  • parent_shas: tuple of parent commit sha hashes

  • message: str, first line of the commit message

  • full_message: str, full commit message

  • author: str, Name <email>

  • authored_at: str, unix_epoch+timezone

  • committer: str, Name <email>

  • committed_at: str, unix_epoch+timezone

property blob_shas

SHA hashes of all blobs in the commit

>>> Commit('af0048f4aac8f4760bf9b816e01524d7fb20a3fc').blob_shas
...        
('b2f49ffef1c8d7ce83a004b34035f917713e2766',
 'c92011c5ccc32a9248bd929a6e56f846ac5b8072',
 'bf3c2d2df2ef710f995b590ac3e2c851b592c871')
property blobs

A generator of Blob objects included in this commit

>>> tuple(Commit('af0048f4aac8f4760bf9b816e01524d7fb20a3fc').blobs)
...              
(<Blob: b2f49ffef1c8d7ce83a004b34035f917713e2766>,
 <Blob: c92011c5ccc32a9248bd929a6e56f846ac5b8072>,
 <Blob: bf3c2d2df2ef710f995b590ac3e2c851b592c871>)
property child_shas

Children commit binary sha hashes. Basically, this is a reverse parent_shas

Commit: https://github.com/user2589/minicms/commit/1e971a07 >>> Commit(‘1e971a073f40d74a1e72e07c682e1cba0bae159b’).child_shas (‘9bd02434b834979bb69d0b752a403228f2e385e8’,)

property children

A generator of children Commit objects

Commit: https://github.com/user2589/minicms/commit/1e971a07 >>> tuple(Commit(‘1e971a073f40d74a1e72e07c682e1cba0bae159b’).children) (<Commit: 9bd02434b834979bb69d0b752a403228f2e385e8>,)

property parents

A generator of parent commits. If you only need hashes (and not Commit objects), use .parent_sha instead

Commit: https://github.com/user2589/minicms/commit/e38126db >>> c = Commit(‘e38126dbca6572912013621d2aa9e6f7c50f36bc’) >>> tuple(c.parents) (<Commit: ab124ab4baa42cd9f554b7bb038e19d4e3647957>,)

property project_names

URIs of projects including this commit. This property can be used to find all forks of a project by its first commit.

Commit: https://github.com/user2589/minicms/commit/f2a7fcdc >>> c = Commit(‘f2a7fcdc51450ab03cb364415f14e634fa69b62c’) >>> isinstance(c.project_names, tuple) True >>> len(c.project_names) > 0 True >>> ‘user2589_minicms’ in c.project_names True

property projects

A generator of Project s, in which this commit is included.

class oscar.Tree(sha)

A representation of git tree object, basically - a directory.

Trees are iterable. Each element of the iteration is a 3-tuple: (mode, filename, sha)

  • mode is an ASCII decimal string similar to file mode

    in Unix systems. Subtrees always have mode “40000”

  • filename is a string filename, not including directories

  • sha is a 40 bytes hex string representing file content Blob SHA

Note

iteration is not recursive. For a recursive walk, use Tree.traverse() or Tree.files

Both files and blobs can be checked for membership, either by their id (filename or SHA) or a corresponding object:

>>> tree = Tree("d4ddbae978c9ec2dc3b7b3497c2086ecf7be7d9d")
>>> '.gitignore' in tree
True
>>> File('.keep') in tree
False
>>> '83d22195edc1473673f1bf35307aea6edf3c37e3' in tree
True
>>> Blob('83d22195edc1473673f1bf35307aea6edf3c37e3') in tree
True

len(tree) returns the number of files under the tree, including files in subtrees but not the subtrees themselves:

>>> len(Tree("d4ddbae978c9ec2dc3b7b3497c2086ecf7be7d9d"))
16
property blob_shas

A tuple of all file content shas, including files in subdirectories

property blobs

A generator of Blob objects with file content. It does include files in subdirectories.

>>> tuple(Tree('d20520ef8c1537a42628b72d481b8174c0a1de84').blobs
...       )  
(<Blob: 2bdf5d686c6cd488b706be5c99c3bb1e166cf2f6>, ...,
 <Blob: c006bef767d08b41633b380058a171b7786b71ab>)
property files

A dict of all files and their content/blob sha under this tree. It includes recursive files (i.e. files in subdirectories). It does NOT include subdirectories themselves.

traverse()

Recursively traverse the tree This will generate 3-tuples of the same format as direct tree iteration, but will recursively include subtrees content.

Yields:

Tuple[bytes, bytes, bytes] – (mode, filename, blob/tree sha)

>>> c = Commit(u'1e971a073f40d74a1e72e07c682e1cba0bae159b')
>>> len(list(c.tree.traverse()))
8
>>> c = Commit(u'e38126dbca6572912013621d2aa9e6f7c50f36bc')
>>> len(list(c.tree.traverse()))
36
class oscar.File(path)

Files are initialized with a path, starting from a commit root tree:

>>> File(b'.gitignore')  
>>> File(b'docs/Index.rst')
property commit_shas

SHA1 of all commits changing this file

NOTE: this relation considers only diff with the first parent, which substantially limits its application

>>> commits = File('minicms/templatetags/minicms_tags.py').commit_shas
>>> len(commits) > 0
True
>>> isinstance(commits, tuple)
True
>>> isinstance(commits[0], str)
True
>>> len(commits[0]) == 40
True
property commits

All commits changing the file

>>> cs = tuple(File('minicms/templatetags/minicms_tags.py').commits)
>>> len(cs) > 0
True
>>> isinstance(cs[0], Commit)
True
class oscar.Blob(sha)
property commit_shas

SHAs of Commits in which this blob have been introduced or modified.

NOTE: commits removing this blob are not included

property commits

Commits where this blob has been added or changed

NOTE: commits removing this blob are not included

property data

Content of the blob

class oscar.Author(full_email)

Authors are initialized with a combination of name and email, as they appear in git configuration.

>>> Author('John Doe <john.doe@aol.com>')

At this point we don’t have a relation to map all aliases of the same author, so keep in mind this object represents an alias, not a person.

property commit_shas

SHA1 of all commits authored by the Author

>>> commits = Author('user2589 <valiev.m@gmail.com>').commit_shas
>>> len(commits) > 50
True
>>> isinstance(commits, tuple)
True
>>> isinstance(commits[0], str)
True
>>> len(commits[0]) == 40
True
property commits

A generator of all Commit objects authored by the Author

>>> commits = tuple(
...     Author('user2589 <user2589@users.noreply.github.com>').commits)
>>> len(commits) > 40
True
>>> isinstance(commits[0], Commit)
True