References

  • Repository.references
  • class pygit2.repository.References(repository)
    • contains(name)
    • getitem(name)
    • iter()
    • create(name, target, force=False)
    • delete(name)
    • get(key)
    • objects
    • Example:
  1. >>> all_refs = list(repo.references)
  2.  
  3. >>> master_ref = repo.lookup_reference("refs/heads/master")
  4. >>> commit = master_ref.peel() # or repo[master_ref.target]
  5.  
  6. # Create a reference
  7. >>> ref = repo.references.create('refs/tags/version1', LAST_COMMIT)
  8.  
  9. # Delete a reference
  10. >>> repo.references.delete('refs/tags/version1')

Functions

  • pygit2.referenceis_valid_name(_refname) → bool
  • Check if the passed string is a valid reference name.

Check if the passed string is a valid reference name.

Example:

  1. >>> from pygit2 import reference_is_valid_name>>> reference_is_valid_name("refs/heads/master")True>>> reference_is_valid_name("HEAD")True>>> reference_is_valid_name("refs/heads/..")False

The Reference type

  • class pygit2.Reference

  • Reference.

  • Reference.name

  • The full name of the reference.

  • Reference.raw_name

  • The full name of the reference (Bytes).

  • Reference.shorthand

  • The shorthand “human-readable” name of the reference.

  • Reference.raw_shorthand

  • The shorthand “human-readable” name of the reference (Bytes).

  • Reference.target

  • The reference target: If direct the value will be an Oid object, if itis symbolic it will be an string with the full name of the targetreference.

  • Reference.type

  • Type, either GIT_REF_OID or GIT_REF_SYMBOLIC.

  • Reference.eq(Reference)

  • Return self==value.

  • Reference.ne(Reference)

  • Return self!=value.

  • Reference.settarget(_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 createdas a result of this update.

Parameters:

  • 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:

  1. >>> branch = repository.lookup_reference("refs/heads/master")
  2. >>> branch.target = another_commit.id
  3. >>> committer = Signature('Cecil Committer', 'cecil@committers.tld')
  4. >>> branch.log_append(another_commit.id, committer,
  5.                       "changed branch target using pygit2")

This creates a reflog entry in git reflog master which looks like:

  1. 7296b92 master@{10}: changed branch target using pygit2

In order to make an entry in git reflog, ie. the reflog for HEAD, youhave to get the Reference object for HEAD and call log_append onthat.

The HEAD

Example. These two lines are equivalent:

  1. >>> head = repo.lookup_reference('HEAD').resolve()
  2. >>> 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 commitinstead of a branch.

  • Repository.head_is_unborn

  • An unborn branch is one named from HEAD but which doesn’t exist in therefs namespace, because it doesn’t have any commit to point to.

Branches

  • Repository.branches

  • Branches inherit from References, and additionally provide specializedaccessors for some unique features.

  • class pygit2.repository.Branches(repository, flag=3, commit=None)

    • contains(name)
    • getitem(name)
    • iter()
    • create(name, commit, force=False)
    • delete(name)
    • get(key)
    • withcommit(_commit)
    • Example:
  1. >>> # Listing all branches
  2. >>> branches_list = list(repo.branches)
  3. >>> # Local only
  4. >>> local_branches = list(repo.branches.local)
  5. >>> # Remote only
  6. >>> remote_branches = list(repo.branches.remote)
  7.  
  8. >>> # Get a branch
  9. >>> branch = repo.branches['master']
  10. >>> other_branch = repo.branches['does-not-exist']  # Will raise a KeyError
  11. >>> other_branch = repo.branches.get('does-not-exist')  # Returns None
  12.  
  13. >>> remote_branch = repo.branches.remote['upstream/feature']
  14.  
  15. >>> # Create a local branch
  16. >>> new_branch = repo.branches.local.create('new-branch')
  17.  
  18. >>> And delete it
  19. >>> repo.branches.delete('new-branch')

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.

  • Branch.is_checked_out()

  • True if branch is checked out by any repo connected to the current one, False otherwise.

The reference log

Example:

  1. >>> head = repo.references.get('refs/heads/master')  # Returns None if not found
  2. >>> # Almost equivalent to
  3. >>> head = repo.references['refs/heads/master']  # Raises KeyError if not found
  4. >>> for entry in head.log():
  5. ...     print(entry.message)
  • class pygit2.RefLogEntry

  • Reference log object.

    • committer

    • Committer.

    • message

    • Message.

    • oid_new

    • New oid.

    • oid_old

    • Old oid.

Notes

  • Repository.notes()
  • Repository.createnote(_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.lookupnote(_annotated_id[, ref]) → Note

  • Lookup a note for an annotated object in a repository.

The Note type

  • Note.annotated_id

  • id of the annotated object.

  • Note.id

  • Gets the id of the blob containing the note message

  • Note.message

  • Gets message of the note

  • Note.remove()

  • Removes a note for an annotated object