# References

Contents

- References
  - The Reference type
  - The HEAD
  - Branches
  - The Branch type
  - The reference log
  - Notes
    - The Note type

`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 for `HEAD`, you have to get the Reference object for `HEAD` and call `log_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)

class `pygit2.``RefLogEntry`

  Reference log object.

  `committer`

    Committer.

  `message`

    Message.

  `oid_new`

    New oid.

  `oid_old`

    Old oid.

## 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.

### 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