References¶
Contents
-
Repository.
listall_references
() → [str, ...]¶ Return a list with all the references in the repository.
-
Repository.
lookup_reference
(name) → Reference¶ Lookup a reference by its name in a repository.
Example:
>>> all_refs = repo.listall_references()
>>> master_ref = repo.lookup_reference("refs/heads/master")
>>> commit = master_ref.get_object() # or repo[master_ref.target]
The Reference type¶
-
class
pygit2.
Reference
¶ Reference.
-
Reference.
name
¶ The full name of the reference.
-
Reference.
shorthand
¶ The shorthand “human-readable” name of the reference.
-
Reference.
target
¶ The reference target: If direct the value will be an Oid object, if it is symbolic it will be an string with the full name of the target reference.
-
Reference.
type
¶ Type, either GIT_REF_OID or GIT_REF_SYMBOLIC.
-
Reference.
set_target
(target[, message])¶ Set the target of this reference.
Update the reference using the given signature and message. These will be used to fill the reflog entry which will be created as a result of this update
Arguments:
- target
- The new target for this reference
- message
- Message to use for the reflog.
-
Reference.
delete
()¶ Delete this reference. It will no longer be valid!
-
Reference.
rename
(new_name)¶ Rename the reference.
-
Reference.
resolve
() → Reference¶ Resolve a symbolic reference and return a direct reference.
-
Reference.
peel
(type=None) → object¶ Retrieve an object of the given type by recursive peeling.
If no type is provided, the first non-tag object will be returned.
-
Reference.
log
() → RefLogIter¶ Retrieves the current reference log.
Example:
>>> branch = repository.lookup_reference("refs/heads/master") >>> branch.target = another_commit.id >>> committer = Signature('Cecil Committer', 'cecil@committers.tld') >>> branch.log_append(another_commit.id, committer, "changed branch target using pygit2")
This creates a reflog entry in
git reflog master
which looks like:7296b92 master@{10}: changed branch target using pygit2
In order to make an entry in
git reflog
, ie. the reflog forHEAD
, you have to get the Reference object forHEAD
and calllog_append
on that.
-
Reference.
get_object
() → object¶ Retrieves the object the current reference is pointing to.
This method is deprecated, please use Reference.peel() instead.
The HEAD¶
Example. These two lines are equivalent:
>>> head = repo.lookup_reference('HEAD').resolve()
>>> head = repo.head
-
Repository.
head
¶ Current head reference of the repository.
-
Repository.
head_is_detached
¶ A repository’s HEAD is detached when it points directly to a commit instead of a branch.
-
Repository.
head_is_unborn
¶ An unborn branch is one named from HEAD but which doesn’t exist in the refs namespace, because it doesn’t have any commit to point to.
Branches¶
Branches inherit from References, and additionally provide specialized accessors for some unique features.
-
Repository.
listall_branches
([flag]) → [str, ...]¶ Return a list with all the branches in the repository.
The flag may be:
- GIT_BRANCH_LOCAL - return all local branches (set by default)
- GIT_BRANCH_REMOTE - return all remote-tracking branches
- GIT_BRANCH_ALL - return local branches and remote-tracking branches
-
Repository.
lookup_branch
(branch_name[, branch_type]) → Branch¶ Returns the Git reference for the given branch name (local or remote). If branch_type is GIT_BRANCH_REMOTE, you must include the remote name in the branch name (eg ‘origin/master’).
-
Repository.
create_branch
(name, commit, force=False) → Branch¶ Create a new branch “name” which points to a commit.
Arguments:
- force
- If True branches will be overridden, otherwise (the default) an exception is raised.
Examples:
repo.create_branch('foo', repo.head.get_object(), force=False)
Example:
>>> local_branches = repo.listall_branches()
>>> # equivalent to
>>> local_branches = repo.listall_branches(pygit2.GIT_BRANCH_LOCAL)
>>> remote_branches = repo.listall_branches(pygit2.GIT_BRANCH_REMOTE)
>>> all_branches = repo.listall_branches(pygit2.GIT_BRANCH_REMOTE |
pygit2.GIT_BRANCH_LOCAL)
>>> master_branch = repo.lookup_branch('master')
>>> # equivalent to
>>> master_branch = repo.lookup_branch('master',
pygit2.GIT_BRANCH_LOCAL)
>>> remote_branch = repo.lookup_branch('upstream/feature',
pygit2.GIT_BRANCH_REMOTE)
The Branch type¶
-
Branch.
branch_name
¶ The name of the local or remote branch.
-
Branch.
remote_name
¶ The name of the remote set to be the upstream of this branch.
-
Branch.
upstream
¶ The branch’s upstream branch or None if this branch does not have an upstream set. Set to None to unset the upstream configuration.
-
Branch.
upstream_name
¶ The name of the reference set to be the upstream of this one
-
Branch.
rename
(name, force=False)¶ Move/rename an existing local branch reference. The new branch name will be checked for validity. Returns the new branch.
-
Branch.
delete
()¶ Delete this branch. It will no longer be valid!
-
Branch.
is_head
()¶ True if HEAD points at the branch, False otherwise.
The reference log¶
Example:
>>> head = repo.lookup_reference('refs/heads/master')
>>> for entry in head.log():
... print(entry.message)
Notes¶
-
Repository.
notes
()¶
-
Repository.
create_note
(message, author, committer, annotated_id[, ref, force]) → Oid¶ Create a new note for an object, return its SHA-ID.If no ref is given ‘refs/notes/commits’ will be used.
-
Repository.
lookup_note
(annotated_id[, ref]) → Note¶ Lookup a note for an annotated object in a repository.