diff --git a/docs/recipes/git-cherry-pick.rst b/docs/recipes/git-cherry-pick.rst
index 310e236..8e740a9 100644
--- a/docs/recipes/git-cherry-pick.rst
+++ b/docs/recipes/git-cherry-pick.rst
@@ -49,7 +49,7 @@ example `three-argument rebases`_.
     repo = pygit2.Repository('/path/to/repo')
 
     cherry = repo.revparse_single('9e044d03c')
-    basket = repo.lookup_branch('basket')
+    basket = repo.branches.get('basket')
 
     base      = repo.merge_base(cherry.oid, basket.target)
     base_tree = cherry.parents[0].tree
diff --git a/docs/references.rst b/docs/references.rst
index 0682f0e..c0a0bea 100644
--- a/docs/references.rst
+++ b/docs/references.rst
@@ -69,28 +69,35 @@ Branches
 Branches inherit from References, and additionally provide specialized
 accessors for some unique features.
 
-.. automethod:: pygit2.Repository.listall_branches
-.. automethod:: pygit2.Repository.lookup_branch
-.. automethod:: pygit2.Repository.create_branch
+.. automethod:: pygit2.Repository.Branches.create
+.. automethod:: pygit2.Repository.Branches.delete
+.. automethod:: pygit2.Repository.Branches.get
+.. automethod:: pygit2.Repository.Branches.__getitem__
+.. automethod:: pygit2.Repository.Branches.__iter__
+.. automethod:: pygit2.Repository.Branches.__contains__
 
 Example::
 
-    >>> local_branches = repo.listall_branches()
-    >>> # equivalent to
-    >>> local_branches = repo.listall_branches(pygit2.GIT_BRANCH_LOCAL)
+    >>> # Listing all branches
+    >>> branches_list = list(repo.branches)
+    >>> # Local only
+    >>> local_branches = list(repo.branches.local)
+    >>> # Remote only
+    >>> remote_branches = list(repo.branches.remote)
 
-    >>> remote_branches = repo.listall_branches(pygit2.GIT_BRANCH_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
 
-    >>> all_branches = repo.listall_branches(pygit2.GIT_BRANCH_REMOTE |
-                                             pygit2.GIT_BRANCH_LOCAL)
+    >>> remote_branch = repo.branches.remote['upstream/feature']
 
-    >>> master_branch = repo.lookup_branch('master')
-    >>> # equivalent to
-    >>> master_branch = repo.lookup_branch('master',
-                                           pygit2.GIT_BRANCH_LOCAL)
+    >>> # Create a local branch
+    >>> new_branch = repo.branches.local.create('new-branch')
+
+    >>> And delete it
+    >>> repo.branches.delete('new-branch')
 
-    >>> remote_branch = repo.lookup_branch('upstream/feature',
-                                           pygit2.GIT_BRANCH_REMOTE)
 
 The Branch type
 ====================