vcs.backends.git

GitRepository

class vcs.backends.git.GitRepository(repo_path, create=False, src_url=None, update_after_clone=False, bare=False)

Git repository backend.

clone(url, update_after_clone=True, bare=False)

Tries to clone changes from external location.

Parameters:

• update_after_clone – If set to False, git won’t checkout working directory
• bare – If set to True, repository would be cloned into bare git repository (no working directory at all).

fetch(url)

Tries to pull changes from external location.

get_changeset(revision=None)

Returns GitChangeset object representing commit from git repository at the given revision or head (most recent commit) if None given.

get_changesets(start=None, end=None, start_date=None, end_date=None, branch_name=None, reverse=False)

Returns iterator of GitChangeset objects from start to end (both are inclusive), in ascending date order (unless reverse is set).

Parameters:

• start – changeset ID, as str; first returned changeset
• end – changeset ID, as str; last returned changeset
• start_date – if specified, changesets with commit date less than start_date would be filtered out from returned set
• end_date – if specified, changesets with commit date greater than end_date would be filtered out from returned set
• branch_name – if specified, changesets not reachable from given branch would be filtered out from returned set
• reverse – if True, returned generator would be reversed (meaning that returned changesets would have descending date order)

Raises:

• BranchDoesNotExistError – If given branch_name does not exist.
• ChangesetDoesNotExistError – If changeset for given start or end could not be found.

get_config_value(section, name, config_file=None)

Returns configuration value for a given [section] and name.

Parameters:

• section – Section we want to retrieve value from
• name – Name of configuration we want to retrieve
• config_file – A path to file which should be used to retrieve configuration from (might also be a list of file paths)

get_diff(rev1, rev2, path=None, ignore_whitespace=False, context=3)

Returns (git like) diff, as plain text. Shows changes introduced by rev2 since rev1.

Parameters:

• rev1 – Entry point from which diff is shown. Can be self.EMPTY_CHANGESET - in this case, patch showing all the changes since empty state of the repository until rev2
• rev2 – Until which revision changes should be shown.
• ignore_whitespace – If set to True, would not show whitespace changes. Defaults to False.
• context – How many lines before/after changed lines should be shown. Defaults to 3.

get_hook_location()

returns absolute path to location where hooks are stored

get_user_email(config_file=None)

Returns user’s email from global configuration file.

Parameters:config_file – A path to file which should be used to retrieve configuration from (might also be a list of file paths)

get_user_name(config_file=None)

Returns user’s name from global configuration file.

Parameters:config_file – A path to file which should be used to retrieve configuration from (might also be a list of file paths)

in_memory_changeset

Returns GitInMemoryChangeset object for this repository.

last_change

Returns last change made on this repository as datetime object

pull(url)

Tries to pull changes from external location.

remove_tag(name, user, message=None, date=None)

Removes tag with the given name.

Parameters:

• name – name of the tag to be removed
• user – full username, i.e.: “Joe Doe <joe.doe@example.com>”
• message – message of the tag’s removal commit
• date – date of tag’s removal commit

Raises TagDoesNotExistError:  

if tag with given name does not exists

revisions

Returns list of revisions’ ids, in ascending order. Being lazy attribute allows external tools to inject shas from cache.

tag(name, user, revision=None, message=None, date=None, **kwargs)

Creates and returns a tag for the given revision.

Parameters:

• name – name for new tag
• user – full username, i.e.: “Joe Doe <joe.doe@example.com>”
• revision – changeset id for which new tag would be created
• message – message of the tag’s commit
• date – date of tag’s commit

Raises TagAlreadyExistError:  

if tag with same name already exists

workdir

Returns Workdir instance for this repository.

GitChangeset

class vcs.backends.git.GitChangeset(repository, revision)

Bases: vcs.backends.base.BaseChangeset

Represents state of the repository at single revision.

id

Returns string identifying this changeset.

Returns same as raw_id attribute.

raw_id

Returns raw string identifying this changeset.

Returns raw string identifing this changeset (40-length sha)

short_id

Returns shortened version of raw_id attribute, as string, identifying this changeset, useful for web representation.

Returns shortened version of raw_id (first 12 characters)

revision

Returns integer identifying this changeset.

Returns integer representing changeset.

parents

Returns list of parents changesets.

Returns list of parents changesets.

added

Returns list of added FileNode objects.

Returns list of added FileNode objects.

changed

Returns list of modified FileNode objects.

Returns list of changed FileNode objects.

removed

Returns list of removed FileNode objects.

Returns list of removed RemovedFileNode objects.

Note

Remember that those RemovedFileNode instances are only dummy FileNode objects and trying to access most of it’s attributes or methods would raise NodeError exception.

added

Returns list of added FileNode objects.

affected_files

Get’s a fast accessible file changes for given changeset

as_dict()

Returns dictionary with changeset’s attributes and their values.

author

author_email

Returns Author email address for given commit

author_name

Returns Author name for given commit

branch

changed

Returns list of modified FileNode objects.

children

Returns list of children changesets.

committer

committer_email

Returns Author email address for given commit

committer_name

Returns Author name for given commit

date

diff(ignore_whitespace=True, context=3)

fill_archive(stream=None, kind='tgz', prefix=None, subrepos=False)

Fills up given stream.

Parameters:

• stream – file like object.
• kind – one of following: zip, tgz or tbz2. Default: tgz.
• prefix – name of root directory in archive. Default is repository name and changeset’s raw_id joined with dash (repo-tip.<KIND>).
• subrepos – include subrepos in this archive.

Raises:

• ImproperArchiveTypeError – If given kind is wrong.
• VcsError – If given stream is None

get_chunked_archive(**kwargs)

Returns iterable archive. Tiny wrapper around fill_archive method.

Parameters:chunk_size – extra parameter which controls size of returned chunks. Default:8k.

get_file_annotate(path)

Returns a generator of four element tuples with

lineno, sha, changeset lazy loader and line

TODO: This function now uses os underlying ‘git’ command which is generally not good. Should be replaced with algorithm iterating commits.

get_file_changeset(path)

Returns last commit of the file at the given path.

get_file_content(path)

Returns content of the file at given path.

get_file_history(path, limit=None)

Returns history of file as reversed list of Changeset objects for which file at given path has been modified.

TODO: This function now uses os underlying ‘git’ and ‘grep’ commands which is generally not good. Should be replaced with algorithm iterating commits.

get_file_history_2(path)

Returns history of file as reversed list of Changeset objects for which file at given path has been modified.

get_file_mode(path)

Returns stat mode of the file at the given path.

get_file_size(path)

Returns size of the file at given path.

get_filenodes_generator()

Returns generator that yields all file nodes.

get_node(path)

get_nodes(path)

id

Returns string identifying this changeset.

last

next(branch=None)

parents

Returns list of parents changesets.

prev(branch=None)

raw_id

Returns raw string identifying this changeset.

removed

Returns list of removed FileNode objects.

revision

Returns integer identifying this changeset.

root

Returns RootNode object for this changeset.

short_id

Returns shortened version of raw_id attribute, as string, identifying this changeset, useful for web representation.

size

Returns total number of bytes from contents of all filenodes.

status

Returns modified, added, removed, deleted files for current changeset

tags

walk(topurl='')

Similar to os.walk method. Insted of filesystem it walks through changeset starting at given topurl. Returns generator of tuples (topnode, dirnodes, filenodes).

GitInMemoryChangeset

class vcs.backends.git.GitInMemoryChangeset(repository)

Bases: vcs.backends.base.BaseInMemoryChangeset

add(*filenodes)

Marks given FileNode objects as to be committed.

Raises:

• NodeAlreadyExistsError – if node with same path exists at latest changeset
• NodeAlreadyAddedError – if node with same path is already marked as added

change(*filenodes)

Marks given FileNode objects to be changed in next commit.

Raises:

• EmptyRepositoryError – if there are no changesets yet
• NodeAlreadyExistsError – if node with same path is already marked to be changed
• NodeAlreadyRemovedError – if node with same path is already marked to be removed
• NodeDoesNotExistError – if node doesn’t exist in latest changeset
• NodeNotChangedError – if node hasn’t really be changed

check_integrity(parents=None)

Checks in-memory changeset’s integrity. Also, sets parents if not already set.

Raises CommitError:  if any error occurs (i.e. NodeDoesNotExistError).

commit(message, author, parents=None, branch=None, date=None, **kwargs)

Performs in-memory commit (doesn’t check workdir in any way) and returns newly created Changeset. Updates repository’s revisions.

Parameters:

• message – message of the commit
• author – full username, i.e. “Joe Doe <joe.doe@example.com>”
• parents – single parent or sequence of parents from which commit would be derieved
• date – datetime.datetime instance. Defaults to datetime.datetime.now().
• branch – branch name, as string. If none given, default backend’s branch would be used.

Raises CommitError:  

if any error occurs while committing

get_ipaths()

Returns generator of paths from nodes marked as added, changed or removed.

get_paths()

Returns list of paths from nodes marked as added, changed or removed.

remove(*filenodes)

Marks given FileNode (or RemovedFileNode) objects to be removed in next commit.

Raises:

• NodeAlreadyRemovedError – if node has been already marked to be removed
• NodeAlreadyChangedError – if node has been already marked to be changed

reset()

Resets this instance to initial state (cleans added, changed and removed lists).