Documentation for Branch type and Branch-related methods.

docs/references.rst

@@ -40,6 +40,46 @@ Example. These two lines are equivalent::
 .. autoattribute:: pygit2.Repository.head_is_detached
 .. autoattribute:: pygit2.Repository.head_is_orphaned
 
+Branches
+====================
+
+Branches inherit from References, and additionally provide spetialized
+accessors for some unique features.
+
+.. automethod:: pygit2.Repository.listall_branches
+.. automethod:: pygit2.Repository.lookup_branch
+.. automethod:: pygit2.Repository.create_branch
+
+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
+====================
+
+.. autoattribute:: pygit2.Branch.branch_name
+.. autoattribute:: pygit2.Branch.remote_name
+.. autoattribute:: pygit2.Branch.upstream
+.. autoattribute:: pygit2.Branch.upstream_name
+
+.. automethod:: pygit2.Branch.rename
+.. automethod:: pygit2.Branch.delete
+.. automethod:: pygit2.Branch.is_head
 
 The reference log
 ====================