From bd322fa1320d83d027e085a71b2b7ae57aefdfb5 Mon Sep 17 00:00:00 2001 From: Michael Jones Date: Sun, 8 Jun 2014 19:23:13 +0100 Subject: [PATCH 1/5] Correct LIBGIT2_VERSION name and add documentation LIBGIT2_VERSION was previously recorded as LIBGIT2_VER_VERSION which is incorrect. We also add basic explanations to all the constants so that the page is a little less bare. Perhaps this should be done as autodoc style comments in the code but I guess not. --- docs/general.rst | 40 ++++++++++++++++++++++++++++++++++++---- 1 file changed, 36 insertions(+), 4 deletions(-) diff --git a/docs/general.rst b/docs/general.rst index bf0b3c1..b71e6e7 100644 --- a/docs/general.rst +++ b/docs/general.rst @@ -6,14 +6,45 @@ General :local: +Top level constants and exceptions from the library. + Constants ========= -.. py:data:: LIBGIT2_VER_MAJOR -.. py:data:: LIBGIT2_VER_MINOR -.. py:data:: LIBGIT2_VER_REVISION -.. py:data:: LIBGIT2_VER_VERSION +The following constants provide information about the version of the libgit2 +library that has been built against. The version number has a +``MAJOR.MINOR.REVISION`` format. +.. py:data:: LIBGIT2_VER_MAJOR + + Integer value of the major version number. For example, for the version + ``0.20.0``:: + + >>> print LIBGIT2_VER_MAJOR + 0 + +.. py:data:: LIBGIT2_VER_MINOR + + Integer value of the minor version number. For example, for the version + ``0.20.0``:: + + >>> print LIBGIT2_VER_MINOR + 20 + +.. py:data:: LIBGIT2_VER_REVISION + + Integer value of the revision version number. For example, for the version + ``0.20.0``:: + + >>> print LIBGIT2_VER_REVISION + 0 + +.. py:data:: LIBGIT2_VERSION + + The libgit2 version number as a string:: + + >>> print LIBGIT2_VERSION + '0.20.0' Errors ====== @@ -22,3 +53,4 @@ Errors :members: :show-inheritance: :undoc-members: + From 28ae47f42bcfee8ce5b33660798f6483a3e0f45d Mon Sep 17 00:00:00 2001 From: Michael Jones Date: Mon, 9 Jun 2014 22:28:04 +0100 Subject: [PATCH 2/5] Provide a doc example for discover_repository To clarify the behaviour and usage. --- docs/repository.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/repository.rst b/docs/repository.rst index c2bd0c2..1ce6191 100644 --- a/docs/repository.rst +++ b/docs/repository.rst @@ -33,6 +33,11 @@ Functions .. autofunction:: pygit2.discover_repository + Example:: + + >>> current_working_directory = os.getcwd() + >>> repository_path = discover_repository(current_working_directory) + >>> repo = Repository(repository_path) The Repository class From 83ccdd9c1fda5337e7b61324f25760f8a4850479 Mon Sep 17 00:00:00 2001 From: Michael Jones Date: Sun, 15 Jun 2014 11:28:26 +0100 Subject: [PATCH 3/5] Explain that reference targets are writable It might seem like a really obvious point to make but without emphasizing it, it isn't completely clear. I would like to mention this in the Branch section as well for how to point a branch at another commit but I can't see how to smoothly slide it in. --- src/reference.c | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/reference.c b/src/reference.c index e597e35..dbf6810 100644 --- a/src/reference.c +++ b/src/reference.c @@ -202,7 +202,10 @@ Reference_resolve(Reference *self, PyObject *args) PyDoc_STRVAR(Reference_target__doc__, "The reference target: If direct the value will be an Oid object, if it\n" "is symbolic it will be an string with the full name of the target\n" - "reference."); + "reference.\n" + "\n" + "The target is writable. Setting the Reference's target to another Oid\n" + "object will direct the reference to that Oid instead."); PyObject * Reference_target__get__(Reference *self) From 7296b921cceef795f55674479db6a8b32bfce09c Mon Sep 17 00:00:00 2001 From: Michael Jones Date: Sun, 15 Jun 2014 11:30:33 +0100 Subject: [PATCH 4/5] Fix spelling typo --- docs/references.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/references.rst b/docs/references.rst index 363e3ee..6ede2a7 100644 --- a/docs/references.rst +++ b/docs/references.rst @@ -45,7 +45,7 @@ Example. These two lines are equivalent:: Branches ==================== -Branches inherit from References, and additionally provide spetialized +Branches inherit from References, and additionally provide specialized accessors for some unique features. .. automethod:: pygit2.Repository.listall_branches From 1f111c08b631b38985f67bbc36d3fadfc4db152c Mon Sep 17 00:00:00 2001 From: Michael Jones Date: Sun, 15 Jun 2014 11:39:24 +0100 Subject: [PATCH 5/5] Provide example for Reference.log_append I would have found this useful when trying to do reflog additions. It might not be massively complex but examples always help. --- docs/references.rst | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/references.rst b/docs/references.rst index 6ede2a7..cccd68a 100644 --- a/docs/references.rst +++ b/docs/references.rst @@ -27,6 +27,23 @@ The Reference type .. automethod:: pygit2.Reference.resolve .. automethod:: pygit2.Reference.log .. automethod:: pygit2.Reference.log_append + + 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. + .. automethod:: pygit2.Reference.get_object