From c3bd05b426a0e3dec8224244c3c9c0431d1ff130 Mon Sep 17 00:00:00 2001 From: Sebastian Thiel Date: Thu, 1 Jul 2010 16:35:11 +0200 Subject: Added doc-index, which helps to keep documentation of prior but still somewhat supported versions alive --- doc/doc_index/0.1/reference.html | 1073 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 1073 insertions(+) create mode 100644 doc/doc_index/0.1/reference.html (limited to 'doc/doc_index/0.1/reference.html') diff --git a/doc/doc_index/0.1/reference.html b/doc/doc_index/0.1/reference.html new file mode 100644 index 00000000..ce56826c --- /dev/null +++ b/doc/doc_index/0.1/reference.html @@ -0,0 +1,1073 @@ + + + + + + + API Reference — GitPython v0.1.7 documentation + + + + + + + + + +
+

Navigation

+ +
+ +
+
+
+
+ +
+

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

+
+
+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
+
+ +
+
+

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.

+
+
+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)
+
+ +
+
+ + +
+
+
+
+
+

Table Of Contents

+ + +

Previous topic

+

GitPython Tutorial

+

This Page

+ + + +
+
+
+
+
+

Navigation

+ +
+
+ © Copyright Copyright (C) 2008-2010 Michael Trier and contributors. + Created using Sphinx 0.6.5. +
+ + \ No newline at end of file -- cgit v1.2.3