Skip to content

Commit

Permalink
docs: working on the repository chapter (in progress)
Browse files Browse the repository at this point in the history
jdavid committed Jan 27, 2013
1 parent b0235e7 commit 93b8c63
Showing 3 changed files with 84 additions and 49 deletions.
22 changes: 14 additions & 8 deletions docs/repository.rst
Original file line number Diff line number Diff line change
@@ -2,21 +2,27 @@
The repository
**********************************************************************

Everything starts by opening an existing repository::

>>> from pygit2 import Repository
>>> repo = Repository('pygit2/.git')
.. autofunction:: pygit2.init_repository

Or by creating a new one::
This is how to create non-bare repository::

>>> from pygit2 import init_repository
>>> bare = False
>>> repo = init_repository('test', bare)


.. autofunction:: pygit2.init_repository

.. autofunction:: pygit2.discover_repository


.. autoclass:: pygit2.Repository
:members:
:members: path, workdir, is_bare, is_empty, revparse_single, read, write,
create_blob, create_blob_fromfile, create_commit,
create_reference, create_tag, TreeBuilder, walk,
listall_references, lookup_reference, packall_references, head,
head_is_detached, head_is_orphaned, index, status, status_file,
config

To open an existing repository::

>>> from pygit2 import Repository
>>> repo = Repository('pygit2/.git')
15 changes: 12 additions & 3 deletions src/pygit2.c
Original file line number Diff line number Diff line change
@@ -58,6 +58,11 @@ extern PyTypeObject RefLogEntryType;
extern PyTypeObject SignatureType;



PyDoc_STRVAR(init_repository__doc__,
"init_repository(path, bare) -> Repository\n\n"
"Creates a new Git repository in the given path.");

PyObject *
init_repository(PyObject *self, PyObject *args)
{
@@ -86,6 +91,11 @@ init_repository(PyObject *self, PyObject *args)
return NULL;
};


PyDoc_STRVAR(discover_repository__doc__,
"discover_repository(path[, across_fs[, ceiling_dirs]]) -> str\n\n"
"Look for a git repository and return its path.");

PyObject *
discover_repository(PyObject *self, PyObject *args)
{
@@ -107,10 +117,9 @@ discover_repository(PyObject *self, PyObject *args)
};

PyMethodDef module_methods[] = {
{"init_repository", init_repository, METH_VARARGS,
"Creates a new Git repository in the given folder."},
{"init_repository", init_repository, METH_VARARGS, init_repository__doc__},
{"discover_repository", discover_repository, METH_VARARGS,
"Look for a git repository and return its path."},
discover_repository__doc__},
{NULL}
};

96 changes: 58 additions & 38 deletions src/pygit2/repository.c
Original file line number Diff line number Diff line change
@@ -194,8 +194,12 @@ Repository_as_iter(Repository *self)
return PyObject_GetIter(accum);
}


PyDoc_STRVAR(Repository_head__doc__,
"Current head reference of the repository.");

PyObject *
Repository_head(Repository *self)
Repository_get_head(Repository *self)
{
git_reference *head;
const git_oid *oid;
@@ -219,11 +223,9 @@ Repository_head(Repository *self)
}


PyDoc_STRVAR(
Repository_head_is_detached_doc,
"A repository's HEAD is detached when it points directly to a commit\n"
"instead of a branch.\n"
);
PyDoc_STRVAR(Repository_head_is_detached__doc__,
"A repository's HEAD is detached when it points directly to a commit "
"instead of a branch.");

PyObject *
Repository_head_is_detached(Repository *self)
@@ -235,11 +237,9 @@ Repository_head_is_detached(Repository *self)
}


PyDoc_STRVAR(
Repository_head_is_orphaned_doc,
"An orphan branch is one named from HEAD but which doesn't exist in\n"
"the refs namespace, because it doesn't have any commit to point to.\n"
);
PyDoc_STRVAR(Repository_head_is_orphaned__doc__,
"An orphan 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.");

PyObject *
Repository_head_is_orphaned(Repository *self)
@@ -251,10 +251,8 @@ Repository_head_is_orphaned(Repository *self)
}


PyDoc_STRVAR(
Repository_is_empty_doc,
"Check if a repository is empty\n"
);
PyDoc_STRVAR(Repository_is_empty__doc__,
"Check if a repository is empty.");

PyObject *
Repository_is_empty(Repository *self)
@@ -266,10 +264,8 @@ Repository_is_empty(Repository *self)
}


PyDoc_STRVAR(
Repository_is_bare_doc,
"Check if a repository is a bare repository.\n"
);
PyDoc_STRVAR(Repository_is_bare__doc__,
"Check if a repository is a bare repository.");

PyObject *
Repository_is_bare(Repository *self)
@@ -403,6 +399,9 @@ Repository_write(Repository *self, PyObject *args)
return git_oid_to_python(oid.id);
}


PyDoc_STRVAR(Repository_index__doc__, "Index file.");

PyObject *
Repository_get_index(Repository *self, void *closure)
{
@@ -434,12 +433,21 @@ Repository_get_index(Repository *self, void *closure)
return self->index;
}


PyDoc_STRVAR(Repository_path__doc__,
"The normalized path to the git repository.");

PyObject *
Repository_get_path(Repository *self, void *closure)
{
return to_path(git_repository_path(self->repo));
}


PyDoc_STRVAR(Repository_workdir__doc__,
"The normalized path to the working directory of the repository. "
"If the repository is bare, None will be returned.");

PyObject *
Repository_get_workdir(Repository *self, void *closure)
{
@@ -452,6 +460,13 @@ Repository_get_workdir(Repository *self, void *closure)
return to_path(c_path);
}


PyDoc_STRVAR(Repository_config__doc__,
"Get the configuration file for this repository.\n\n"
"If a configuration file has not been set, the default config set for the "
"repository will be returned, including global and system configurations "
"(if they are available).");

PyObject *
Repository_get_config(Repository *self, void *closure)
{
@@ -568,6 +583,12 @@ Repository_create_blob_fromfile(Repository *self, PyObject *args)
return git_oid_to_python(oid.id);
}


PyDoc_STRVAR(Repository_create_commit__doc__,
"create_commit(reference, author, committer, message, tree, parents"
"[, encoding]) -> bytes\n\n"
"Create a new commit object, return its SHA.");

PyObject *
Repository_create_commit(Repository *self, PyObject *args)
{
@@ -906,7 +927,7 @@ Repository_TreeBuilder(Repository *self, PyObject *args)

PyMethodDef Repository_methods[] = {
{"create_commit", (PyCFunction)Repository_create_commit, METH_VARARGS,
"Create a new commit object, return its SHA."},
Repository_create_commit__doc__},
{"create_tag", (PyCFunction)Repository_create_tag, METH_VARARGS,
"Create a new tag object, return its SHA."},
{"walk", (PyCFunction)Repository_walk, METH_VARARGS,
@@ -948,27 +969,21 @@ PyMethodDef Repository_methods[] = {
};

PyGetSetDef Repository_getseters[] = {
{"index", (getter)Repository_get_index, NULL, "index file. ", NULL},
{"path", (getter)Repository_get_path, NULL,
"The normalized path to the git repository.", NULL},
{"head", (getter)Repository_head, NULL,
"Current head reference of the repository.", NULL},
{"index", (getter)Repository_get_index, NULL, Repository_index__doc__,
NULL},
{"path", (getter)Repository_get_path, NULL, Repository_path__doc__, NULL},
{"head", (getter)Repository_get_head, NULL, Repository_head__doc__, NULL},
{"head_is_detached", (getter)Repository_head_is_detached, NULL,
Repository_head_is_detached_doc},
Repository_head_is_detached__doc__},
{"head_is_orphaned", (getter)Repository_head_is_orphaned, NULL,
Repository_head_is_orphaned_doc},
Repository_head_is_orphaned__doc__},
{"is_empty", (getter)Repository_is_empty, NULL,
Repository_is_empty_doc},
{"is_bare", (getter)Repository_is_bare, NULL,
Repository_is_bare_doc},
{"config", (getter)Repository_get_config, NULL,
"Get the configuration file for this repository.\n\n"
"If a configuration file has not been set, the default "
"config set for the repository will be returned, including "
"global and system configurations (if they are available).", NULL},
Repository_is_empty__doc__},
{"is_bare", (getter)Repository_is_bare, NULL, Repository_is_bare__doc__},
{"config", (getter)Repository_get_config, NULL, Repository_config__doc__,
NULL},
{"workdir", (getter)Repository_get_workdir, NULL,
"The normalized path to the working directory of the repository. "
"If the repository is bare, None will be returned.", NULL},
Repository_workdir__doc__, NULL},
{NULL}
};

@@ -989,6 +1004,11 @@ PyMappingMethods Repository_as_mapping = {
0, /* mp_ass_subscript */
};


PyDoc_STRVAR(Repository__doc__,
"Repository(path) -> Repository\n\n"
"Git repository.");

PyTypeObject RepositoryType = {
PyVarObject_HEAD_INIT(NULL, 0)
"_pygit2.Repository", /* tp_name */
@@ -1012,7 +1032,7 @@ PyTypeObject RepositoryType = {
Py_TPFLAGS_DEFAULT |
Py_TPFLAGS_BASETYPE |
Py_TPFLAGS_HAVE_GC, /* tp_flags */
"Git repository", /* tp_doc */
Repository__doc__, /* tp_doc */
(traverseproc)Repository_traverse, /* tp_traverse */
(inquiry)Repository_clear, /* tp_clear */
0, /* tp_richcompare */

0 comments on commit 93b8c63

Please sign in to comment.