gbp.git.repository.GitRepository(object) class documentation

@param path: path to git repo (or subdir)
@type path: C{str}
@param toplevel: whether path points to the toplevel dir of
    git repository
@type toplevel: C{bool}

The absolute path to the repository

The absolute path to git's metadata

Whether this is a bare repository

List of all tags in the repository

The currently checked out branch

SHA1 of the current HEAD

Rename branch

@param branch: name of the branch to be renamed
@param newbranch: new name of the branch

Create a new branch

@param branch: the branch's name
@param rev: where to start the branch from
@param force: reset branch HEAD to start point, if it already exists

If rev is None the branch starts from the current HEAD.

Delete branch I{branch}

@param branch: name of the branch to delete
@type branch: C{str}
@param remote: delete a remote branch
@param remote: C{bool}

On what branch is the current working copy

@return: current branch or C{None} in an empty repo
@rtype: C{str}
@raises GitRepositoryError: if HEAD is not a symbolic ref
  (e.g. when in detached HEAD state)

Check if the repository has branch named I{branch}.

@param branch: branch to look for
@param remote: only look for remote branches
@type remote: C{bool}
@return: C{True} if the repository has this branch, C{False} otherwise
@rtype: C{bool}

Switch to branch I{branch}

@param branch: name of the branch to switch to
@type branch: C{str}

Get the branch we'd merge from

@return: repo and branch we would merge from
@rtype: C{str}

Get the common ancestor between two commits

@param commit1: commit SHA1 or name of a branch or tag
@type commit1: C{str}
@param commit2: commit SHA1 or name of a branch or tag
@type commit2: C{str}
@return: SHA1 of the common ancestor
@rtype: C{str}

Merge changes from the named commit into the current branch

@param commit: the commit to merge from (usually a branch name or tag)
@type commit: C{str}
@param verbose: whether to print a summary after the merge
@type verbose: C{bool}
@param edit: whether to invoke an editor to edit the merge message
@type edit: C{bool}

Abort a merge

Check if an update I{from from_branch} to I{to_branch} would be a fast
forward or if the branch is up to date already.

@return: can_fast_forward, up_to_date
@rtype: C{tuple}

Get a list of local branches

@return: local branches
@rtype: C{list}

Get a list of remote branches

@return: remote branches
@rtype: C{list}

Update ref I{ref} to commit I{new} if I{ref} currently points to
I{old}

@param ref: the ref to update
@type ref: C{str}
@param new: the new value for ref
@type new: C{str}
@param old: the old value of ref
@type old: C{str}
@param msg: the reason for the update
@type msg: C{str}

Check if branch I{branch} contains commit I{commit}

@param branch: the branch the commit should be on
@type branch: C{str}
@param commit: the C{str} commit to check
@type commit: C{str}
@param remote: whether to check remote instead of local branches
@type remote: C{bool}

Set upstream branches for local branch

@param local_branch: name of the local branch
@type local_branch: C{str}
@param upstream: Remote branch in the form remote/branch, e.g. origin/master
@type upstream: C{str}

Get upstream branch for the local branch

@param local_branch: name fo the local branch
@type local_branch: C{str}
@return: upstream (remote/branch) or  '' if no upstream found
@rtype: C{str}

Create a new tag.

@param name: the tag's name
@type name: C{str}
@param msg: The tag message.
@type msg: C{str}
@param commit: the commit or object to create the tag at, default
    is I{HEAD}
@type commit: C{str}
@param sign: Whether to sing the tag
@type sign: C{bool}
@param keyid: the GPG keyid used to sign the tag
@type keyid: C{str}

Delete a tag named I{tag}

@param tag: the tag to delete
@type tag: C{str}

Check if the repository has a tag named I{tag}.

@param tag: tag to look for
@type tag: C{str}
@return: C{True} if the repository has that tag, C{False} otherwise
@rtype: C{bool}

Describe commit, relative to the latest tag reachable from it.

@param commitish: the commit-ish to describe
@type commitish: C{str}
@param pattern: only look for tags matching I{pattern}
@type pattern: C{str}
@param longfmt: describe the commit in the long format
@type longfmt: C{bool}
@param always: return commit sha1 as fallback if no tag is found
@type always: C{bool}
@param abbrev: abbreviate sha1 to given length instead of the default
@type abbrev: None or C{long}
@param tags: enable matching a lightweight (non-annotated) tag
@type tags: C{bool}
@param exact_match: only output exact matches (a tag directly
references the supplied commit)
@type exact_match: C{bool}
@return: tag name plus/or the abbreviated sha1
@rtype: C{str}

Find the closest tag to a given commit

@param commit: the commit to describe
@type commit: C{str}
@param pattern: only look for tags matching I{pattern}
@type pattern: C{str}
@return: the found tag
@rtype: C{str}

Find the closest tag on a certain branch to a given commit

@param commit: the commit to describe
@type commit: C{str}
@type branch: C{str}
@param pattern: only look for tags matching I{pattern}
@type pattern: C{str}
@return: the found tag
@rtype: C{str}

List tags

@param pattern: only list tags matching I{pattern}
@type pattern: C{str}
@return: tags
@rtype: C{list} of C{str}

Verify a signed tag

@param tag: the tag's name
@type tag: C{str}
@return: Whether the signature on the tag could be verified
@rtype: C{bool}

Force HEAD to a specific commit

@param commit: commit to move HEAD to
@param hard: also update the working copy
@type hard: C{bool}

Does the repository contain any uncommitted modifications?

@param ignore_untracked: whether to ignore untracked files when
    checking the repository status
@type ignore_untracked: C{bool}
@param paths: only check changes on paths
@type paths: C{list} of C{stings}
@return: C{True} if the repository is clean, C{False} otherwise
    and Git's status message
@rtype: C{tuple}

Remove untracked files from the working tree.

@param directories: remove untracked directories, too
@type directories: C{bool}
@param force: satisfy git configuration variable clean.requireForce
@type force: C{bool}
@param dry_run: don’t actually remove anything
@type dry_run: C{bool}

Check status of repository.

@param pathlist: List of paths to check status for
@type pathlist: C{list}
@return C{dict} of C{lists} of paths, where key is a git status flag.
@rtype C{dict}

Is the repository empty?

@return: True if the repositorydoesn't have any commits,
    False otherwise
@rtype: C{bool}

Find the SHA1 of a given name

@param name: the name to look for
@type name: C{str}
@param short:  try to abbreviate SHA1 to given length
@type short: C{int}
@return: the name's sha1
@rtype: C{str}

Checkout treeish

@param treeish: the treeish to check out
@type treeish: C{str}

Check if the repository has the treeish object I{treeish}.

@param treeish: treeish object to look for
@type treeish: C{str}
@return: C{True} if the repository has that tree, C{False} otherwise
@rtype: C{bool}

Create a tree object from the current index

@param index_file: alternate index file to read changes from
@type index_file: C{str}
@return: the new tree object's sha1
@rtype: C{str}

Create a tree based on contents.

@param contents: same format as I{GitRepository.list_tree} output.
@type contents: C{list} of C{str}

Get type of a git repository object

@param obj: repository object
@type obj: C{str}
@return: type of the repository object
@rtype: C{str}

Get a trees content. It returns a list of objects that match the
'ls-tree' output: [mode, type, sha1, path].

@param treeish: the treeish object to list
@type treeish: C{str}
@param recurse: whether to list the tree recursively
@type recurse: C{bool}
@return: the tree
@rtype: C{list} of objects. See above.

Gets the config value associated with I{name}

@param name: config value to get
@return: fetched config value
@rtype: C{str}

Set a git config value in this repository

Sets the full name to use for git commits.

@param name: full name to use

Sets the email address to use for git commits.

@param email: email address to use

Determine a sane values for author name and author email from git's
config and environment variables.

@return: name and email
@rtype: L{GitModifier}

Get a list of remote repositories

@return: remote repositories
@rtype: C{dict} of C{GitRemote}

Get all remote repositories

@deprecated: Use get_remotes() instead

@return: remote repositories
@rtype: C{list} of C{str}

Do we know about a remote named I{name}?

@param name: name of the remote repository
@type name: C{str}
@return: C{True} if the remote repositore is known, C{False} otherwise
@rtype: C{bool}

Add a tracked remote repository

@param name: the name to use for the remote
@type name: C{str}
@param url: the url to add
@type url: C{str}
@param tags: whether to fetch tags
@type tags: C{bool}
@param fetch: whether to fetch immediately from the remote side
@type fetch: C{bool}

Download objects and refs from another repository.

@param repo: repository to fetch from
@type repo: C{str}
@param tags: whether to fetch all tag objects
@type tags: C{bool}
@param depth: deepen the history of (shallow) repository to depth I{depth}
@type depth: C{int}
@param refspec: refspec to use instead of the default from git config
@type refspec: C{str}
@param all_remotes: fetch all remotes
@type all_remotes: C{bool}

Fetch and merge from another repository

@param repo: repository to fetch from
@type repo: C{str}
@param ff_only: only merge if this results in a fast forward merge
@type ff_only: C{bool}
@param all_remotes: fetch all remotes
@type all_remotes: C{bool}

Push changes to the remote repo

@param repo: repository to push to
@type repo: C{str}
@param src: the source ref to push
@type src: C{str}
@param dst: the name of the destination ref to push to
@type dst: C{str}
@param ff_only: only push if it's a fast forward update
@type ff_only: C{bool}
@param force: force push, can cause the remote repository to lose
commits; use it with care
@type force: C{bool}
@param tags: push all refs under refs/tags, in addition to other refs
@type tags: C{bool}
@param dry_run: dry run
@type dry_run: C{bool}

Push a tag to the remote repo

@param repo: repository to push to
@type repo: C{str}
@param tag: the name of the tag
@type tag: C{str}
@param dry_run: dry run
@type dry_run: C{bool}

Add files to a the repository

@param paths: list of files to add
@type paths: list or C{str}
@param force: add files even if they would be ignored by .gitignore
@type force: C{bool}
@param index_file: alternative index file to use
@param work_tree: alternative working tree to use

Remove files from the repository

@param paths: list of files to remove
@param paths: C{list} or C{str}
@param verbose: be verbose
@type verbose: C{bool}

List files in index and working tree

@param types: list of types to show
@type types: C{list}
@return: list of files as byte string
@rtype: C{list} of C{str}

Hash a single file and write it into the object database

@param filename: the filename to the content of the file to hash
@type filename: C{bytestr}
@param filters: whether to run filters
@type filters: C{bool}
@return: the hash of the file
@rtype: C{str}

Rename file, directory, or symlink

Commit currently staged files to the repository

@param msg: commit message
@type msg: C{str}
@param author_info: authorship information
@type author_info: L{GitModifier}
@param edit: whether to spawn an editor to edit the commit info
@type edit: C{bool}

Commit all changes to the repository
@param msg: commit message
@type msg: C{str}
@param author_info: authorship information
@type author_info: L{GitModifier}

Commit the given files to the repository

@param files: file or files to commit
@type files: C{str} or C{list}
@param msg: commit message
@type msg: C{str}
@param author_info: authorship information
@type author_info: L{GitModifier}

Replace the current tip of branch I{branch} with the contents from I{unpack_dir}

@param unpack_dir: content to add
@type unpack_dir: C{str}
@param msg: commit message to use
@type msg: C{str}
@param branch: branch to add the contents of unpack_dir to
@type branch: C{str}
@param other_parents: additional parents of this commit
@type other_parents: C{list} of C{str}
@param author: author information to use for commit
@type author: C{dict} with keys I{name}, I{email}, I{date}
@param committer: committer information to use for commit
@type committer: C{dict} with keys I{name}, I{email}, I{date}
    or L{GitModifier}
@param create_missing_branch: create I{branch} as detached branch if it
    doesn't already exist.
@type create_missing_branch: C{bool}

Commit a tree with commit msg I{msg} and parents I{parents}

@param tree: tree to commit
@param msg: commit message
@param parents: parents of this commit
@param author: authorship information
@type author: C{dict} with keys 'name' and 'email' or L{GitModifier}
@param committer: committer information
@type committer: C{dict} with keys 'name' and 'email'

Get commits from since to until touching paths

@param since: commit to start from
@type since: C{str}
@param until: last commit to get
@type until: C{str}
@param paths: only list commits touching paths
@type paths: C{list} of C{str}
@param num: maximum number of commits to fetch
@type num: C{int}
@param options: list of additional options passed to git log
@type  options: C{list} of C{str}ings
@param first_parent: only follow first parent when seeing a
                     merge commit
@type first_parent: C{bool}

Show a git object

@rtype: C{bytestr}

Get commmits matching I{regex}

@param regex: regular expression
@type regex: C{str}
@param since: where to start grepping (e.g. a branch)
@type since: C{str}

Gets the subject of a commit.

@deprecated: Use get_commit_info directly

@param commit: the commit to get the subject from
@return: the commit's subject
@rtype: C{str}

Look up data of a specific commit-ish. Dereferences given commit-ish
to the commit it points to.

@param commitish: the commit-ish to inspect
@return: the commit's including id, author, email, subject and body
@rtype: dict

Output the commits between start and end as patches in output_dir.

This outputs the revisions I{start...end} by default. When using
I{symmetric} to C{false} it uses I{start..end} instead.

@param start: the commit on the left side of the revision range
@param end: the commit on the right hand side of the revisino range
@param output_dir: directory to write the patches to
@param signature: whether to output a signature
@param thread: whether to include In-Reply-To references
@param symmetric: whether to use the symmetric difference (see above)

Apply a patch using git apply

Diff two git repository objects

@param obj1: first object
@type obj1: C{str}
@param obj2: second object
@type obj2: C{str}
@param paths: List of paths to diff
@type paths: C{list}
@param stat: Show diffstat
@type stat: C{bool} or C{int} or C{str}
@param summary: Show diffstat
@type summary: C{bool}
@param text: Generate textual diffs, treat all files as text
@type text: C{bool}
@param ignore_submodules: ignore changes to submodules
@type ignore_submodules: C{bool}
@return: diff
@rtype: C{binary}

Get file-status of two git repository objects

@param obj1: first object
@type obj1: C{str}
@param obj2: second object
@type obj2: C{str}
@return: name-status
@rtype: C{defaultdict} of C{str}

Create an archive from a treeish

@param format: the type of archive to create, e.g. 'tar.gz'
@type format: C{str}
@param prefix: prefix to prepend to each filename in the archive
@type prefix: C{str}
@param output: the name of the archive to create
@type output: C{str}
@param treeish: the treeish to create the archive from
@type treeish: C{str}
@param cwd: The directory to run in. Defaults to the current dir
@type cwd: C{str}

Cleanup unnecessary files and optimize the local repository

param auto: only cleanup if required
param auto: C{bool}

Does the repo have any submodules?

@param treeish: look into treeish
@type treeish: C{str}
@return: C{True} if the repository has any submodules, C{False}
    otherwise
@rtype: C{bool}

Add a submodule

@param repo_path: path to submodule
@type repo_path: C{str}

Update all submodules

@param init: whether to initialize the submodule if necessary
@type init: C{bool}
@param recursive: whether to update submodules recursively
@type recursive: C{bool}
@param fetch: whether to fetch new objects
@type fetch: C{bool}

List the submodules of treeish

@return: a list of submodule/commit-id tuples
@rtype: list of tuples