The primary API

Opening and Creating

In addition to instantiating subclasses of anyvcs.common.VCSRepo directly, you can also these utility functions which will infer the type based on the given parameters.

anyvcs.open(path, vcs=None)

Open an existing repository

Parameters:
  • path (str) – The path of the repository
  • vcs – If specified, assume the given repository type to avoid auto-detection. Either git, hg, or svn.
Raises:

UnknownVCSType – if the repository type couldn’t be inferred

If vcs is not specified, it is inferred via probe().

anyvcs.probe(path)

Probe a repository for its type.

Parameters:path (str) – The path of the repository
Raises:UnknownVCSType – if the repository type couldn’t be inferred
Returns str:either git, hg, or svn

This function employs some heuristics to guess the type of the repository.

anyvcs.clone(srcpath, destpath, vcs=None)

Clone an existing repository.

Parameters:
  • srcpath (str) – Path to an existing repository
  • destpath (str) – Desired path of new repository
  • vcs (str) – Either git, hg, or svn
Returns VCSRepo:
 

The newly cloned repository

If vcs is not given, then the repository type is discovered from srcpath via probe().

anyvcs.create(path, vcs)

Create a new repository

Parameters:
  • path (str) – The path where to create the repository.
  • vcs (str) – Either git, hg, or svn

VCSRepo

class anyvcs.common.VCSRepo(path, encoding='utf-8')

The most base type

ancestor(rev1, rev2)

Find most recent common ancestor of two revisions

Parameters:
  • rev1 – First revision.
  • rev2 – Second revision.
Returns:

The common ancestor revision between the two.
blame(rev, path)

Blame (a.k.a. annotate, praise) a file

Parameters:
  • rev – The revision to blame.
  • path (str) – The path to blame.
Returns:

list of annotated lines of the given path
Return type:

list of BlameInfo objects
Raises:
  • PathDoesNotExist – if the path does not exist.
  • BadFileType – if the path is not a file.
branches()

Get list of branches

Returns:The branches in the repository
Return type:list of str
canonical_rev(rev)

Get the canonical revision identifier

Parameters:rev – The revision to canonicalize.
Returns:The canonicalized revision

The canonical revision is the revision which is natively supported by the underlying VCS type. In some cases, anyvcs may annotate a revision identifier to also encode branch information which is not safe to use directly with the VCS itself (e.g. as created by compose_rev()). This method is a means of converting back to canonical form.

cat(rev, path)

Get file contents

Parameters:
  • rev – The revision to use.
  • path (str) – The path to the file. Must be a file.
Returns:

The contents of the file.
Return type:

str or bytes
Raises:
  • PathDoesNotExist – If the path does not exist.
  • BadFileType – If the path is not a file.
changed(rev)

Files that changed from the rev’s parent(s)

Parameters:rev (list of FileChangeInfo.) – The revision to get the files that changed.
compose_rev(branch, rev)

Compose a revision identifier which encodes branch and revision.

Parameters:
  • branch (str) – A branch name
  • rev – A revision (can be canonical or as constructed by compose_rev() or tip())

The revision identifier encodes branch and revision information according to the particular VCS type. This is a means to unify the various branching models under a common interface.

diff(rev_a, rev_b, path=None)

Diff of two revisions

Parameters:
  • rev_a – The start revision.
  • rev_b – The end revision.
  • path (None or str) – If not None, return diff for only that file.
Returns str:

The diff.

The returned string contains the unified diff from rev_a to rev_b with a prefix of one (suitable for input to patch -p1).

empty()

Test if the repository contains any commits

Returns bool:True if the repository contains no commits.

Commits that exist by default (e.g. a zero commit) are not counted.

heads()

Get list of heads

Returns:The heads in the repository
Return type:list of str
log(revrange=None, limit=None, firstparent=False, merges=None, path=None, follow=False)

Get commit logs

Parameters:
  • revrange – Either a single revision or a range of revisions as a 2-element list or tuple.
  • limit (int) – Limit the number of log entries.
  • firstparent (bool) – Only follow the first parent of merges.
  • merges (bool) – True means only merges, False means no merges, None means both merges and non-merges.
  • path (str) – Only match commits containing changes on this path.
  • follow (bool) – Follow file history across renames.
Returns:

log information
Return type:

CommitLogEntry or list of CommitLogEntry

If revrange is None, return a list of all log entries in reverse chronological order.

If revrange is a single revision, return a single log entry.

If revrange is a 2 element list [A,B] or tuple (A,B), return a list of log entries starting at B and following that branch back to A or one of its ancestors (not inclusive. If A is None, follow branch B back to the beginning of history. If B is None, list all descendants in reverse chronological order.

ls(rev, path, recursive=False, recursive_dirs=False, directory=False, report=())

List directory or file

Parameters:
  • rev – The revision to use.
  • path – The path to list. May start with a ‘/’ or not. Directories may end with a ‘/’ or not.
  • recursive – Recursively list files in subdirectories.
  • recursive_dirs – Used when recursive=True, also list directories.
  • directory – If path is a directory, list path itself instead of its contents.
  • report – A list or tuple of extra attributes to return that may require extra processing. Recognized values are ‘size’, ‘target’, ‘executable’, and ‘commit’.

Returns a list of dictionaries with the following keys:

type
The type of the file: ‘f’ for file, ‘d’ for directory, ‘l’ for symlink.
name
The name of the file. Not present if directory=True.
size
The size of the file. Only present for files when ‘size’ is in report.
target
The target of the symlink. Only present for symlinks when ‘target’ is in report.
executable
True if the file is executable, False otherwise. Only present for files when ‘executable’ is in report.

Raises PathDoesNotExist if the path does not exist.

pdiff(rev)

Diff from the rev’s parent(s)

Parameters:rev – The rev to compute the diff from its parent.
Returns str:The diff.

The returned string is a unified diff that the rev introduces with a prefix of one (suitable for input to patch -p1).

private_path

Get the path to a directory which can be used to store arbitrary data

This directory should not conflict with any of the repository internals. The directory should be created if it does not already exist.

Get symbolic link target

Parameters:
  • rev – The revision to use.
  • path (str) – The path to the file. Must be a symbolic link.
Returns str:

The target of the symbolic link.
Raises:
  • PathDoesNotExist – if the path does not exist.
  • BadFileType – if the path is not a symbolic link.
tags()

Get list of tags

Returns:The tags in the repository
Return type:list of str
tip(head)

Find the tip of a named head

Parameters:head (str) – name of head to look up
Returns:revision identifier of head

The returned identifier should be a valid input for VCSRepo.ls(). and respect the branch name in the returned identifier if applicable.

BlameInfo

class anyvcs.common.BlameInfo(rev, author, date, line)

Represents an annotated line in a file for a blame view.

Variables:
  • rev – Revision at which the line was last changed
  • author (str) – Author of the change
  • date (datetime) – Timestamp of the change
  • line (str) – Line data from the file.

CommitLogEntry

class anyvcs.common.CommitLogEntry(rev, parents, date, author, message)

Represents a single entry in the commit log

Variables:
  • rev – Revision name
  • parents – Parents of the revision
  • date (datetime) – Timestamp of the revision
  • author (str) – Author of the revision
  • message (str) – Message from committer
subject

First line of the commit message.

FileChangeInfo

class anyvcs.common.FileChangeInfo(path, status, copy=None)

Represents a change to a single path.

Variables:
  • path (str) – The path that was changed.
  • status (str) – VCS-specific code for the change type.
  • copy – The source path copied from, if any.