# References

Contents

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

class `pygit2.repository.``References`(repository)
  `__contains__`(name)
  `__getitem__`(name)
  `__iter__`()
  `create`(name, target, force=False)
  `delete`(name)
  `get`(key)
  `objects`

Example:

    >>> all_refs = list(repo.references)

    >>> master_ref = repo.lookup_reference("refs/heads/master")
    >>> commit = master_ref.peel() # or repo[master_ref.target]

    # Create a reference
    >>> ref = repo.references.create('refs/tags/version1', LAST_COMMIT)

    # Delete a reference
    >>> repo.references.delete('refs/tags/version1')

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

  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:

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

class `pygit2.repository.``Branches`(repository, flag=3)
  `__contains__`(name)
  `__getitem__`(name)
  `__iter__`()
  `create`(name, commit, force=False)
  `delete`(name)
  `get`(key)

Example:

    >>> # Listing all branches
    >>> branches_list = list(repo.branches)
    >>> # Local only
    >>> local_branches = list(repo.branches.local)
    >>> # Remote only
    >>> remote_branches = list(repo.branches.remote)

    >>> # Get a branch
    >>> branch = repo.branches['master']
    >>> other_branch = repo.branches['does-not-exist']  # Will raise a KeyError
    >>> other_branch = repo.branches.get('does-not-exist')  # Returns None

    >>> remote_branch = repo.branches.remote['upstream/feature']

    >>> # Create a local branch
    >>> new_branch = repo.branches.local.create('new-branch')

    >>> And delete it
    >>> 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:

    >>> head = repo.references.get('refs/heads/master')  # Returns None if not found
    >>> # Almost equivalent to
    >>> head = repo.references['refs/heads/master']  # Raises KeyError if not found
    >>> 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