API Reference¶

Actor¶

class git.actor.Actor(name, email)¶

Actors hold information about a person acting on the repository. They can be committers and authors or anything with a name and an email as mentioned in the git log entries.

classmethod from_string(string)¶

Create an Actor from a string.

str: is the string, which is expected to be in regular git format
Format: John Doe <jdoe@example.com>
Returns: Actor

Blob¶

class git.blob.Blob(repo, id, mode=None, name=None)¶

A Blob encapsulates a git blob object

DEFAULT_MIME_TYPE = 'text/plain'¶

basename¶

Returns: The basename of the Blobs file name

classmethod blame(repo, commit, file)¶

The blame information for the given file at the given commit

Returns: list: [git.Commit, list: [<line>]] A list of tuples associating a Commit object with a list of lines that changed within the given commit. The Commit objects will be given in order of appearance.

data¶

The binary contents of this blob.

Returns: str
NOTE: The data will be cached after the first access.

mime_type¶

The mime type of this file (based on the filename)

Returns: str
NOTE: Defaults to ‘text/plain’ in case the actual file type is unknown.

size¶

The size of this blob in bytes

Returns: int
NOTE: The size will be cached after the first access

Git¶

class git.cmd.Git(git_dir=None)¶

The Git class manages communication with the Git binary.

It provides a convenient interface to calling the Git binary, such as in:
g = Git( git_dir )
g.init()                               # calls 'git init' program
rval = g.ls_files()            # calls 'git ls-files' program
Debugging

Set the GIT_PYTHON_TRACE environment variable print each invocation of the command to stdout. Set its value to ‘full’ to see details about the returned values.

execute(command, istream=None, with_keep_cwd=False, with_extended_output=False, with_exceptions=True, with_raw_output=False)¶

Handles executing the command on the shell and consumes and returns the returned information (stdout)

command: The command argument list to execute. It should be a string, or a sequence of program arguments. The program to execute is the first item in the args sequence or string.
istream: Standard input filehandle passed to subprocess.Popen.
with_keep_cwd: Whether to use the current working directory from os.getcwd(). GitPython uses get_work_tree() as its working directory by default and get_git_dir() for bare repositories.
with_extended_output: Whether to return a (status, stdout, stderr) tuple.
with_exceptions: Whether to raise an exception when git returns a non-zero status.
with_raw_output: Whether to avoid stripping off trailing whitespace.

Returns:

str(output)                                  # extended_output = False (Default)
tuple(int(status), str(stdout), str(stderr)) # extended_output = True

Raise: GitCommandError
NOTE: If you add additional keyword arguments to the signature of this method, you must update the execute_kwargs tuple housed in this module.

get_dir¶

Returns: Git directory we are working on

transform_kwargs(**kwargs)¶: Transforms Python style kwargs into git command line options.

Commit¶

class git.commit.Commit(repo, id, tree=None, author=None, authored_date=None, committer=None, committed_date=None, message=None, parents=None)¶

Wraps a git Commit object.

This class will act lazily on some of its attributes and will query the value on demand only if it involves calling the git binary.

classmethod actor(line)¶

Parse out the actor (author or committer) info

Returns: [Actor, gmtime(acted at time)]

classmethod count(repo, ref, path='')¶

Count the number of commits reachable from this ref

repo: is the Repo
ref: is the ref from which to begin (SHA1 or name)
path: is an optional path
Returns: int

classmethod diff(repo, a, b=None, paths=None)¶

Creates diffs between a tree and the index or between two trees:

repo

is the Repo

a

is a named commit

b

is an optional named commit. Passing a list assumes you wish to omit the second named commit and limit the diff to the given paths.

paths

is a list of paths to limit the diff to.

Returns

git.Diff[]:

between tree and the index if only a is given
between two trees if a and b are given and are commits

diffs¶

Returns: git.Diff[] Diffs between this commit and its first parent or all changes if this commit is the first commit and has no parent.

classmethod find_all(repo, ref, path='', **kwargs)¶

Find all commits matching the given criteria. repo

is the Repo

ref: is the ref from which to begin (SHA1 or name)
path: is an optinal path, if set only Commits that include the path will be considered
kwargs: optional keyword arguments to git where max_count is the maximum number of commits to fetch skip is the number of commits to skip
Returns: git.Commit[]

id_abbrev¶

Returns: First 7 bytes of the commit’s sha id as an abbreviation of the full string.

classmethod list_from_string(repo, text)¶

Parse out commit information into a list of Commit objects

repo: is the Repo
text: is the text output from the git-rev-list command (raw format)
Returns: git.Commit[]

stats¶

Create a git stat from changes between this commit and its first parent or from all changes done if this is the very first commit.

Return: git.Stats

summary¶

Returns: First line of the commit message.

Diff¶

class git.diff.Diff(repo, a_path, b_path, a_commit, b_commit, a_mode, b_mode, new_file, deleted_file, rename_from, rename_to, diff)¶

A Diff contains diff information between two commits.

classmethod list_from_string(repo, text)¶

Errors¶

Module containing all exceptions thrown througout the git package,

exception git.errors.GitCommandError(command, status, stderr=None)¶: Thrown if execution of the git command fails with non-zero status code.

exception git.errors.InvalidGitRepositoryError¶: Thrown if the given repository appears to have an invalid format.

exception git.errors.NoSuchPathError¶: Thrown if a path could not be access by the system.

Head¶

class git.head.Head(name, commit)¶

A Head is a named reference to a Commit. Every Head instance contains a name and a Commit object.

Examples:

>>> repo = Repo("/path/to/repo")
>>> head = repo.heads[0]

>>> head.name
'master'

>>> head.commit
<git.Commit "1c09f116cbc2cb4100fb6935bb162daa4723f455">

>>> head.commit.id
'1c09f116cbc2cb4100fb6935bb162daa4723f455'

classmethod find_all(repo, **kwargs)¶

Find all Heads in the repository

repo

is the Repo

kwargs

Additional options given as keyword arguments, will be passed to git-for-each-ref

Returns

git.Head[]

List is sorted by committerdate

classmethod from_string(repo, line)¶

Create a new Head instance from the given string.

repo: is the Repo
line: is the formatted head information

Format:

name: [a-zA-Z_/]+
<null byte>
id: [0-9A-Fa-f]{40}

Returns: git.Head

classmethod list_from_string(repo, text)¶

Parse out head information into a list of head objects

repo: is the Repo
text: is the text output from the git-for-each-ref command
Returns: git.Head[]

Lazy¶

class git.lazy.LazyMixin¶

lazy_properties = []¶

Repo¶

class git.repo.Repo(path=None)¶

Represents a git repository and allows you to query references, gather commit information, generate diffs, create and clone repositories query the log.

DAEMON_EXPORT_FILE = 'git-daemon-export-ok'¶

active_branch¶

The name of the currently active branch.

Returns: str (the branch name)

alternates¶: Retrieve a list of alternates paths or set a list paths to be used as alternates

archive_tar(treeish='master', prefix=None)¶

Archive the given treeish

treeish: is the treeish name/id (default ‘master’)
prefix: is the optional prefix to prepend to each filename in the archive

Examples:

>>> repo.archive_tar
<String containing tar archive>

>>> repo.archive_tar('a87ff14')
<String containing tar archive for commit a87ff14>

>>> repo.archive_tar('master', 'myproject/')
<String containing tar bytes archive, whose files are prefixed with 'myproject/'>

Returns: str (containing bytes of tar archive)

archive_tar_gz(treeish='master', prefix=None)¶

Archive and gzip the given treeish

treeish: is the treeish name/id (default ‘master’)
prefix: is the optional prefix to prepend to each filename in the archive

Examples:

>>> repo.archive_tar_gz
<String containing tar.gz archive>

>>> repo.archive_tar_gz('a87ff14')
<String containing tar.gz archive for commit a87ff14>

>>> repo.archive_tar_gz('master', 'myproject/')
<String containing tar.gz archive and prefixed with 'myproject/'>

Returns: str (containing the bytes of tar.gz archive)

blob(id)¶

The Blob object for the given id

id: is the SHA1 id of the blob
Returns: git.Blob

branches¶

A list of Head objects representing the branch heads in this repo

Returns: git.Head[]

commit(id, path='')¶

The Commit object for the specified id

id: is the SHA1 identifier of the commit
path: is an optional path, if set the returned commit must contain the path.
Returns: git.Commit

commit_count(start='master', path='')¶

The number of commits reachable by the given branch/commit

start: is the branch/commit name (default ‘master’)
path: is an optional path Commits that do not contain the path will not contribute to the count.
Returns: int

commit_deltas_from(other_repo, ref='master', other_ref='master')¶

Returns a list of commits that is in other_repo but not in self

Returns: git.Commit[]

commit_diff(commit)¶

The commit diff for the given commit: commit is the commit name/id
Returns: git.Diff[]

commits(start='master', path='', max_count=10, skip=0)¶

A list of Commit objects representing the history of a given ref/commit

start

is the branch/commit name (default ‘master’)

path

is an optional path to limit the returned commits to Commits that do not contain that path will not be returned.

max_count

is the maximum number of commits to return (default 10)

skip: is the number of commits to skip (default 0) which will effectively move your commit-window by the given number.

Returns

git.Commit[]

commits_between(frm, to)¶

The Commits objects that are reachable via to but not via frm Commits are returned in chronological order.

from: is the branch/commit name of the younger item
to: is the branch/commit name of the older item
Returns: git.Commit[]

commits_since(start='master', path='', since='1970-01-01')¶

The Commits objects that are newer than the specified date. Commits are returned in chronological order.

start: is the branch/commit name (default ‘master’)
path: is an optional path to limit the returned commits to.
since: is a string representing a date/time
Returns: git.Commit[]

classmethod create(path, mkdir=True, **kwargs)¶

Initialize a bare git repository at the given path

path: is the full path to the repo (traditionally ends with /<name>.git)
mkdir: if specified will create the repository directory if it doesn’t already exists. Creates the directory with a mode=0755.
kwargs: keyword arguments serving as additional options to the git init command

Examples:

git.Repo.init_bare('/var/git/myrepo.git')

Returns: git.Repo (the newly created repo)

daemon_export¶: If True, git-daemon may export this repository

description¶: the project’s description

diff(a, b, *paths)¶

The diff from commit a to commit b, optionally restricted to the given file(s)

a: is the base commit
b: is the other commit
paths: is an optional list of file paths on which to restrict the diff
Returns: str

fork_bare(path, **kwargs)¶

Fork a bare git repository from this repo

path: is the full path of the new repo (traditionally ends with /<name>.git)
kwargs: keyword arguments to be given to the git clone command
Returns: git.Repo (the newly forked repo)

heads¶

A list of Head objects representing the branch heads in this repo

Returns: git.Head[]

classmethod init_bare(path, mkdir=True, **kwargs)¶

Initialize a bare git repository at the given path

path: is the full path to the repo (traditionally ends with /<name>.git)
mkdir: if specified will create the repository directory if it doesn’t already exists. Creates the directory with a mode=0755.
kwargs: keyword arguments serving as additional options to the git init command

Examples:

git.Repo.init_bare('/var/git/myrepo.git')

Returns: git.Repo (the newly created repo)

is_dirty¶

Return the status of the index.

Returns: True, if the index has any uncommitted changes, otherwise False
NOTE: Working tree changes that have not been staged will not be detected !

log(commit='master', path=None, **kwargs)¶

The Commit for a treeish, and all commits leading to it.

kwargs: keyword arguments specifying flags to be used in git-log command, i.e.: max_count=1 to limit the amount of commits returned
Returns: git.Commit[]

tags¶

A list of Tag objects that are available in this repo

Returns: git.Tag[]

tree(treeish='master')¶

The Tree object for the given treeish reference

treeish: is the reference (default ‘master’)

Examples:

repo.tree('master')

Returns: git.Tree

Stats¶

class git.stats.Stats(repo, total, files)¶

Represents stat information as presented by git at the end of a merge. It is created from the output of a diff operation.

Example:

c = Commit( sha1 )
s = c.stats
s.total         # full-stat-dict
s.files         # dict( filepath : stat-dict )

stat-dict

A dictionary with the following keys and values:

deletions = number of deleted lines as int
insertions = number of inserted lines as int
lines = total number of lines changed as int, or deletions + insertions

full-stat-dict

In addition to the items in the stat-dict, it features additional information:

files = number of changed files as int

classmethod list_from_string(repo, text)¶

Create a Stat object from output retrieved by git-diff.

Returns: git.Stat

Tag¶

class git.tag.Tag(name, commit)¶

classmethod find_all(repo, **kwargs)¶

Find all Tags in the repository

repo

is the Repo

kwargs

Additional options given as keyword arguments, will be passed to git-for-each-ref

Returns

git.Tag[]

List is sorted by committerdate

classmethod from_string(repo, line)¶

Create a new Tag instance from the given string.

repo: is the Repo
line: is the formatted tag information

Format:

name: [a-zA-Z_/]+
<null byte>
id: [0-9A-Fa-f]{40}

Returns: git.Tag

classmethod list_from_string(repo, text)¶

Parse out tag information into an array of Tag objects

repo: is the Repo
text: is the text output from the git-for-each command
Returns: git.Tag[]

Tree¶

class git.tree.Tree(repo, id, mode=None, name=None)¶

basename¶

static content_from_string(repo, text)¶

Parse a content item and create the appropriate object

repo

is the Repo

text: is the single line containing the items data in git ls-tree format

Returns

git.Blob or git.Tree

get(key)¶

items()¶

keys()¶

values()¶

Utils¶

git.utils.dashify(string)¶

git.utils.is_git_dir(d)¶: This is taken from the git setup.c:is_git_directory function.

git.utils.touch(filename)¶