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
, orsvn
.
Raises: UnknownVCSType – if the repository type couldn’t be inferred
If
vcs
is not specified, it is inferred viaprobe()
.
-
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
, orsvn
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
, orsvn
Returns VCSRepo: The newly cloned repository
If
vcs
is not given, then the repository type is discovered fromsrcpath
viaprobe()
.
-
anyvcs.
create
(path, vcs)¶ Create a new repository
Parameters: - path (str) – The path where to create the repository.
- vcs (str) – Either
git
,hg
, orsvn
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
objectsRaises: - 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()
ortip()
)
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 ofCommitLogEntry
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.
-
readlink
(rev, path)¶ 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.
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.