diff --git a/docs/objects.rst b/docs/objects.rst index a277a3a..6f778e9 100644 --- a/docs/objects.rst +++ b/docs/objects.rst @@ -1,5 +1,5 @@ ********************************************************************** -Git objects +Git Objects ********************************************************************** There are four types of Git objects: blobs, trees, commits and tags. For each @@ -11,9 +11,42 @@ type. :local: -Objects +Object lookup ================= +In the previous chapter we learnt about Object IDs. With an oid we can ask the +repository to get the associated object. To do that the ``Repository`` class +implementes a subset of the mapping interface. + +.. method:: Repository.get(oid, default=None) + + Return the Git object for the given *oid*, returns the *default* value if + there's no object in the repository with that oid. The oid can be an Oid + object, or an hexadecimal string. + + Example:: + + >>> from pygit2 import Repository + >>> repo = Repository('path/to/pygit2') + >>> obj = repo.get("101715bf37440d32291bde4f58c3142bcf7d8adb") + >>> obj + <_pygit2.Commit object at 0x7ff27a6b60f0> + +.. method:: Repository[oid] + + Return the Git object for the given oid, raise ``KeyError`` if there's no + object in the repository with that oid. The oid can be an Oid object, or + an hexadecimal string. + +.. method:: oid in Repository + + Returns True if there is an object in the Repository with that oid, False + if there is not. The oid can be an Oid object, or an hexadecimal string. + + +The Object base type +==================== + The Object type is a base type, it is not possible to make instances of it, in any way. @@ -51,40 +84,59 @@ This is the common interface for all Git objects: .. automethod:: pygit2.Object.read_raw - - - - - Blobs ================= -A blob is equivalent to a file in a file system.:: +A blob is just a raw byte string. They are the Git equivalent to files in +a filesytem. - >>> # create a blob out of memory - >>> oid = repo.create_blob('foo bar') - >>> blob = repo[oid] - >>> blob.data - 'foo bar' - >>> oid - '\x96\xc9\x06um{\x91\xc4S"a|\x92\x95\xe4\xa8\rR\xd1\xc5' +This is their API: .. autoattribute:: pygit2.Blob.data + + Example, print the contents of the ``.gitignore`` file:: + + >>> blob = repo["d8022420bf6db02e906175f64f66676df539f2fd"] + >>> print blob.data + MANIFEST + build + dist + .. autoattribute:: pygit2.Blob.size -To create new blobs use the Repository API: + Example:: + + >>> print blob.size + 130 + +Creating blobs +-------------- + +There are a number of methods in the repository to create new blobs, and add +them to the Git object database: .. automethod:: pygit2.Repository.create_blob + + Example: + + >>> oid = repo.create_blob('foo bar') # Creates blob from bytes string + >>> blob = repo[oid] + >>> blob.data + 'foo bar' + .. automethod:: pygit2.Repository.create_blob_fromworkdir .. automethod:: pygit2.Repository.create_blob_fromdisk -It is also possible to get the oid for a blob without really adding it to -the Git object database: +There are also some functions to calculate the oid for a byte string without +creating the blob object: .. autofunction:: pygit2.hash .. autofunction:: pygit2.hashfile + + + Trees ================= diff --git a/docs/repository.rst b/docs/repository.rst index 2f34c14..24f0674 100644 --- a/docs/repository.rst +++ b/docs/repository.rst @@ -9,16 +9,19 @@ existing one. :local: -Creating a repository +Functions =================================== .. autofunction:: pygit2.init_repository -Example:: + Example:: + + >>> from pygit2 import init_repository + >>> repo = init_repository('test') # Creates a non-bare repository + >>> repo = init_repository('test', bare=True) # Creates a bare repository + +.. autofunction:: pygit2.discover_repository - >>> from pygit2 import init_repository - >>> repo = init_repository('test') # Creates a non-bare repository - >>> repo = init_repository('test', bare=True) # Creates a bare repository The Repository class @@ -47,9 +50,3 @@ Below there are some general attributes and methods: .. autoattribute:: pygit2.Repository.is_empty .. automethod:: pygit2.Repository.read .. automethod:: pygit2.Repository.write - - -Utilities -========= - -.. autofunction:: pygit2.discover_repository diff --git a/src/blob.c b/src/blob.c index 289160c..465d8d6 100644 --- a/src/blob.c +++ b/src/blob.c @@ -42,7 +42,8 @@ Blob_size__get__(Blob *self) PyDoc_STRVAR(Blob_data__doc__, - "Raw data. This is the same as Blob.read_raw()"); + "The contents of the blob, a bytes string. This is the same as\n" + "Blob.read_raw()"); PyGetSetDef Blob_getseters[] = { GETTER(Blob, size), diff --git a/src/repository.c b/src/repository.c index fe63f67..59c4443 100644 --- a/src/repository.c +++ b/src/repository.c @@ -592,9 +592,10 @@ Repository_walk(Repository *self, PyObject *args) PyDoc_STRVAR(Repository_create_blob__doc__, - "create_blob(data) -> bytes\n" - "\n" - "Create a new blob from memory."); + "create_blob(data) -> Oid\n" + "\n" + "Create a new blob from a bytes string. The blob is added to the Git\n" + "object database. Returns the oid of the blob."); PyObject * Repository_create_blob(Repository *self, PyObject *args) @@ -616,9 +617,11 @@ Repository_create_blob(Repository *self, PyObject *args) PyDoc_STRVAR(Repository_create_blob_fromworkdir__doc__, - "create_blob_fromworkdir(path) -> bytes\n" - "\n" - "Create a new blob from a file within the working directory (raise an error otherwise)."); + "create_blob_fromworkdir(path) -> Oid\n" + "\n" + "Create a new blob from a file within the working directory. The given\n" + "path must be relative to the working directory, if it is not an error\n" + "is raised."); PyObject * Repository_create_blob_fromworkdir(Repository *self, PyObject *args) @@ -639,9 +642,9 @@ Repository_create_blob_fromworkdir(Repository *self, PyObject *args) PyDoc_STRVAR(Repository_create_blob_fromdisk__doc__, - "create_blob_fromdisk(path) -> bytes\n" - "\n" - "Create a new blob from a file anywhere (no working directory check)."); + "create_blob_fromdisk(path) -> Oid\n" + "\n" + "Create a new blob from a file anywhere (no working directory check)."); PyObject * Repository_create_blob_fromdisk(Repository *self, PyObject *args)