openstack/deb-python-pygit2
Code Issues Proposed changes

docs: complete and improve organization

Browse Source
This commit is contained in:
J. David Ibáñez 2013-04-03 19:09:48 +02:00
parent 30e4367e91
commit 32e460fe16
17 changed files with 323 additions and 165 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
docs/config.rst
View File

@ -1,8 +1,18 @@
**********************************************************************
Configuration file
Configuration files
**********************************************************************
.. autoclass:: pygit2.Config
:members:
:show-inheritance:
:undoc-members:
.. autoattribute:: pygit2.Repository.config
The Config type
================
.. automethod:: pygit2.Config.get_system_config
.. automethod:: pygit2.Config.get_global_config
.. automethod:: pygit2.Config.foreach
.. automethod:: pygit2.Config.add_file
.. automethod:: pygit2.Config.get_multivar
.. automethod:: pygit2.Config.set_multivar
The :class:`Config` Mapping interface.

33
docs/diff.rst
View File

@ -2,7 +2,6 @@
Diff
**********************************************************************
A diff shows the changes between trees, an index or the working dir::
# Diff two trees
@ -19,12 +18,32 @@ A diff shows the changes between trees, an index or the working dir::
>>> tree = repo.head.tree
>>> diff = tree.diff()
The interface for a diff::
Diff.changes -- Dict of 'files' and 'hunks' for every change
Diff.patch -- a patch for every changeset
Diff.merge -- Merge two Diffs
The Diff type
====================
.. autoattribute:: pygit2.Diff.patch
.. automethod:: pygit2.Diff.merge
.. automethod:: pygit2.Diff.find_similar
.. autoclass:: pygit2.Diff
:members:
The Patch type
====================
.. autoattribute:: pygit2.Patch.old_file_path
.. autoattribute:: pygit2.Patch.new_file_path
.. autoattribute:: pygit2.Patch.old_oid
.. autoattribute:: pygit2.Patch.new_oid
.. autoattribute:: pygit2.Patch.status
.. autoattribute:: pygit2.Patch.similarity
.. autoattribute:: pygit2.Patch.hunks
The Hunk type
====================
.. autoattribute:: pygit2.Hunk.old_start
.. autoattribute:: pygit2.Hunk.old_lines
.. autoattribute:: pygit2.Hunk.new_start
.. autoattribute:: pygit2.Hunk.new_lines
.. autoattribute:: pygit2.Hunk.lines

28
docs/index-file.rst
View File

@ -1,28 +0,0 @@
**********************************************************************
Index file
**********************************************************************
Index read::
>>> index = repo.index
>>> index.read()
>>> oid = index['path/to/file'].oid # from path to object id
>>> blob = repo[oid] # from object id to object
Iterate over all entries of the index::
>>> for entry in index:
... print entry.path, entry.hex
Index write::
>>> index.add('path/to/file') # git add
>>> del index['path/to/file'] # git rm
>>> index.write() # don't forget to save the changes
.. autoclass:: pygit2.Index
:members: add, remove, clear, read, write, read_tree, write_tree, diff
.. autoclass:: pygit2.IndexEntry
:members: oid, hex, path, mode

4
docs/index.rst
View File

@ -36,10 +36,10 @@ Usage guide:
references
revparse
log
working-copy
diff
index-file
status
config
remotes
errors
More:

2
docs/log.rst
View File

@ -2,6 +2,8 @@
Commit log
**********************************************************************
.. automethod:: pygit2.Repository.walk
You can iterate through the revision history with repo.walk::
>>> from pygit2 import GIT_SORT_TIME

88
docs/objects.rst
View File

@ -37,24 +37,30 @@ Objects can not be modified once they have been created.
This is the common interface for all Git objects:
.. autoclass:: pygit2.Object
:members: type, oid, hex, read_raw
.. autoattribute:: pygit2.Object.oid
.. autoattribute:: pygit2.Object.hex
.. autoattribute:: pygit2.Object.type
.. automethod:: pygit2.Object.read_raw
Commits
-----------------
=================
A commit is a snapshot of the working dir with meta informations like author,
committer and others.
.. autoclass:: pygit2.Commit
:members: author, committer, message, message_encoding, tree, parents,
commit_time, commit_time_offset
:show-inheritance:
.. autoattribute:: pygit2.Commit.author
.. autoattribute:: pygit2.Commit.committer
.. autoattribute:: pygit2.Commit.message
.. autoattribute:: pygit2.Commit.message_encoding
.. autoattribute:: pygit2.Commit.tree
.. autoattribute:: pygit2.Commit.parents
.. autoattribute:: pygit2.Commit.commit_time
.. autoattribute:: pygit2.Commit.commit_time_offset
Signatures
.............
-------------
The author and committer attributes of commit objects are ``Signature``
objects::
@ -62,12 +68,16 @@ objects::
>>> commit.author
<pygit2.Signature object at 0x7f75e9b1f5f8>
.. autoclass:: pygit2.Signature
:members: name, email, time, offset
.. autoattribute:: pygit2.Signature.name
.. autoattribute:: pygit2.Signature.email
.. autoattribute:: pygit2.Signature.time
.. autoattribute:: pygit2.Signature.offset
Creating commits
................
----------------
.. automethod:: pygit2.Repository.create_commit
Commits can be created by calling the ``create_commit`` method of the
repository with the following parameters::
@ -85,7 +95,7 @@ repository with the following parameters::
Trees
-----------------
=================
A tree is a sorted collection of tree entries. It is similar to a folder or
directory in a file system. Each entry points to another tree or a blob. A
@ -118,19 +128,28 @@ interfaces::
>>> blob
<pygit2.Blob object at 0xcc12d0>
.. autoclass:: pygit2.Tree
:members:
:show-inheritance:
:undoc-members:
.. automethod:: pygit2.Tree.diff
.. autoclass:: pygit2.TreeEntry
:members: name, oid, hex, filemode, to_object
:show-inheritance:
:undoc-members:
.. autoattribute:: pygit2.TreeEntry.name
.. autoattribute:: pygit2.TreeEntry.oid
.. autoattribute:: pygit2.TreeEntry.hex
.. autoattribute:: pygit2.TreeEntry.filemode
.. automethod:: pygit2.TreeEntry.to_object
Creating trees
--------------------
.. automethod:: pygit2.Repository.TreeBuilder
.. automethod:: pygit2.TreeBuilder.insert
.. automethod:: pygit2.TreeBuilder.remove
.. automethod:: pygit2.TreeBuilder.clear
.. automethod:: pygit2.TreeBuilder.write
Blobs
-----------------
=================
A blob is equivalent to a file in a file system.::
@ -142,19 +161,28 @@ A blob is equivalent to a file in a file system.::
>>> oid
'\x96\xc9\x06um{\x91\xc4S"a|\x92\x95\xe4\xa8\rR\xd1\xc5'
.. autoclass:: pygit2.Blob
:members:
:show-inheritance:
:undoc-members:
.. autoattribute:: pygit2.Blob.data
.. autoattribute:: pygit2.Blob.size
Creating blobs
--------------------
.. automethod:: pygit2.Repository.create_blob
.. automethod:: pygit2.Repository.create_blob_fromfile
Tags
-----------------
=================
A tag is a static label for a commit. See references for more information.
.. autoattribute:: pygit2.Tag.name
.. autoattribute:: pygit2.Tag.target
.. autoattribute:: pygit2.Tag.tagger
.. autoattribute:: pygit2.Tag.message
.. autoclass:: pygit2.Tag
:members:
:show-inheritance:
:undoc-members:
Creating tags
--------------------
.. automethod:: pygit2.Repository.create_tag

46
docs/references.rst
View File

@ -2,6 +2,9 @@
References
**********************************************************************
.. automethod:: pygit2.Repository.listall_references
.. automethod:: pygit2.Repository.lookup_reference
Reference lookup::
>>> all_refs = repo.listall_references()
@ -22,9 +25,42 @@ The interface for RefLogEntry::
RefLogEntry.oid_new -- oid of new reference
.. Autogenerated
The Reference type
====================
.. autoclass:: pygit2.Reference
:members:
:show-inheritance:
:undoc-members:
.. autoattribute:: pygit2.Reference.name
.. autoattribute:: pygit2.Reference.oid
.. autoattribute:: pygit2.Reference.hex
.. autoattribute:: pygit2.Reference.target
.. autoattribute:: pygit2.Reference.type
.. automethod:: pygit2.Reference.delete
.. automethod:: pygit2.Reference.rename
.. automethod:: pygit2.Reference.resolve
.. automethod:: pygit2.Reference.log
The reference log
--------------------
.. autoattribute:: pygit2.RefLogEntry.oid_new
.. autoattribute:: pygit2.RefLogEntry.oid_old
.. autoattribute:: pygit2.RefLogEntry.message
.. autoattribute:: pygit2.RefLogEntry.committer
Notes
====================
.. automethod:: pygit2.Repository.notes
.. automethod:: pygit2.Repository.create_note
.. automethod:: pygit2.Repository.lookup_note
The Note type
--------------------
.. autoattribute:: pygit2.Note.annotated_id
.. autoattribute:: pygit2.Note.oid
.. autoattribute:: pygit2.Note.message
.. automethod:: pygit2.Note.remove

16
docs/remotes.rst Normal file
View File

@ -0,0 +1,16 @@
**********************************************************************
Remotes
**********************************************************************
.. autoattribute:: pygit2.Repository.remotes
.. automethod:: pygit2.Repository.create_remote
The Remote type
====================
.. autoattribute:: pygit2.Remote.name
.. autoattribute:: pygit2.Remote.url
.. autoattribute:: pygit2.Remote.fetchspec
.. automethod:: pygit2.Remote.fetch

51
docs/repository.rst
View File

@ -2,34 +2,45 @@
The repository
**********************************************************************
Everything starts either by creating a new repository, or by opening an
existing one.
Creating a repository
===================================
.. autofunction:: pygit2.init_repository
This is how to create non-bare repository::
This is how to create non-bare repository::
>>> from pygit2 import init_repository
>>> repo = init_repository('test')
>>> from pygit2 import init_repository
>>> repo = init_repository('test')
And this is how to create a bare repository::
And this is how to create a bare repository::
>>> from pygit2 import init_repository
>>> repo = init_repository('test', bare=True)
>>> from pygit2 import init_repository
>>> repo = init_repository('test', bare=True)
But one can also do::
But one can also do::
>>> from pygit2 import init_repository
>>> repo = init_repository('test', True)
.. autofunction:: pygit2.discover_repository
>>> from pygit2 import init_repository
>>> repo = init_repository('test', True)
.. autoclass:: pygit2.Repository
:members: path, workdir, is_bare, is_empty, revparse_single, read, write,
create_blob, create_blob_fromfile, create_commit, create_tag,
TreeBuilder, walk, create_reference, listall_references,
lookup_reference, packall_references, head, head_is_detached,
head_is_orphaned, index, status, status_file, config
The Repository class
===================================
To open an existing repository::
To open an existing repository::
>>> from pygit2 import Repository
>>> repo = Repository('pygit2/.git')
>>> from pygit2 import Repository
>>> repo = Repository('pygit2/.git')
.. autoattribute:: pygit2.Repository.path
.. autoattribute:: pygit2.Repository.workdir
.. autoattribute:: pygit2.Repository.is_bare
.. autoattribute:: pygit2.Repository.is_empty
.. automethod:: pygit2.Repository.read
.. automethod:: pygit2.Repository.write
.. autoattribute:: pygit2.Repository.head
.. autoattribute:: pygit2.Repository.head_is_detached
.. autoattribute:: pygit2.Repository.head_is_orphaned

2
docs/revparse.rst
View File

@ -2,6 +2,8 @@
Revision parsing
**********************************************************************
.. automethod:: pygit2.Repository.revparse_single
You can use any of the fancy `<rev>` forms supported by libgit2::
>>> commit = repo.revparse_single('HEAD^')

11
docs/status.rst
View File

@ -1,11 +0,0 @@
**********************************************************************
Status
**********************************************************************
Inspect the status of the repository::
>>> from pygit2 import GIT_STATUS_CURRENT
>>> status = repo.status()
>>> for filepath, flags in status.items():
... if flags != GIT_STATUS_CURRENT:
... print "Filepath %s isn't clean" % filepath

6
docs/utils.rst
View File

@ -2,6 +2,12 @@
Utilities
**********************************************************************
.. autofunction:: pygit2.discover_repository
.. autofunction:: pygit2.hash
.. autofunction:: pygit2.hashfile
.. automodule:: pygit2.utils
:members:
:show-inheritance:

66
docs/working-copy.rst Normal file
View File

@ -0,0 +1,66 @@
**********************************************************************
The Index file and the Working copy
**********************************************************************
.. autoattribute:: pygit2.Repository.index
Index read::
>>> index = repo.index
>>> index.read()
>>> oid = index['path/to/file'].oid # from path to object id
>>> blob = repo[oid] # from object id to object
Iterate over all entries of the index::
>>> for entry in index:
... print entry.path, entry.hex
Index write::
>>> index.add('path/to/file') # git add
>>> del index['path/to/file'] # git rm
>>> index.write() # don't forget to save the changes
The Index type
====================
.. automethod:: pygit2.Index.add
.. automethod:: pygit2.Index.remove
.. automethod:: pygit2.Index.clear
.. automethod:: pygit2.Index.read
.. automethod:: pygit2.Index.write
.. automethod:: pygit2.Index.read_tree
.. automethod:: pygit2.Index.write_tree
.. automethod:: pygit2.Index.diff
The IndexEntry type
--------------------
.. autoattribute:: pygit2.IndexEntry.oid
.. autoattribute:: pygit2.IndexEntry.hex
.. autoattribute:: pygit2.IndexEntry.path
.. autoattribute:: pygit2.IndexEntry.mode
Status
====================
.. automethod:: pygit2.Repository.status
.. automethod:: pygit2.Repository.status_file
Inspect the status of the repository::
>>> from pygit2 import GIT_STATUS_CURRENT
>>> status = repo.status()
>>> for filepath, flags in status.items():
... if flags != GIT_STATUS_CURRENT:
... print "Filepath %s isn't clean" % filepath
Checkout
====================
.. automethod:: pygit2.Repository.checkout

8
pygit2/__init__.py
View File

@ -41,6 +41,14 @@ import pygit2.utils
def init_repository(path, bare=False):
"""
Creates a new Git repository in the given path.
Arguments:
path
Path where to create the repository.
bare
Whether the repository will be bare or not.
"""
_pygit2.init_repository(path, bare)
return Repository(path)

99
src/pygit2.c
View File

@ -66,9 +66,17 @@ extern PyTypeObject NoteIterType;
PyDoc_STRVAR(init_repository__doc__,
"init_repository(path, bare)\n"
"\n"
"Creates a new Git repository in the given path.");
"init_repository(path, bare)\n"
"\n"
"Creates a new Git repository in the given path.\n"
"\n"
"Arguments:\n"
"\n"
"path\n"
" Path where to create the repository.\n"
"\n"
"bare\n"
" Whether the repository will be bare or not.\n");
PyObject *
init_repository(PyObject *self, PyObject *args) {
@ -115,7 +123,7 @@ discover_repository(PyObject *self, PyObject *args)
};
PyDoc_STRVAR(hashfile__doc__,
"hash(path) -> bytes\n"
"hashfile(path) -> bytes\n"
"\n"
"Returns the oid of a new blob from a file path without actually writing \n"
"to the odb.");
@ -176,10 +184,15 @@ moduleinit(PyObject* m)
if (m == NULL)
return NULL;
/* Errors */
GitError = PyErr_NewException("_pygit2.GitError", NULL, NULL);
Py_INCREF(GitError);
PyModule_AddObject(m, "GitError", GitError);
/* Repository */
INIT_TYPE(RepositoryType, NULL, PyType_GenericNew)
ADD_TYPE(m, Repository);
/* Objects (make them with the Repository.create_XXX methods). */
INIT_TYPE(ObjectType, NULL, NULL)
INIT_TYPE(CommitType, &ObjectType, NULL)
@ -190,77 +203,53 @@ moduleinit(PyObject* m)
INIT_TYPE(TreeBuilderType, NULL, PyType_GenericNew)
INIT_TYPE(BlobType, &ObjectType, NULL)
INIT_TYPE(TagType, &ObjectType, NULL)
ADD_TYPE(m, Object);
ADD_TYPE(m, Commit);
ADD_TYPE(m, Signature);
ADD_TYPE(m, Tree);
ADD_TYPE(m, TreeEntry);
ADD_TYPE(m, TreeBuilder);
ADD_TYPE(m, Blob);
ADD_TYPE(m, Tag);
/* References */
INIT_TYPE(ReferenceType, NULL, PyType_GenericNew)
INIT_TYPE(RefLogEntryType, NULL, NULL)
INIT_TYPE(RefLogIterType, NULL, NULL)
INIT_TYPE(NoteType, NULL, NULL)
INIT_TYPE(NoteIterType, NULL, NULL)
ADD_TYPE(m, Reference);
ADD_TYPE(m, RefLogEntry);
ADD_TYPE(m, Note);
/* Index */
INIT_TYPE(IndexType, NULL, PyType_GenericNew)
INIT_TYPE(IndexEntryType, NULL, PyType_GenericNew)
INIT_TYPE(IndexIterType, NULL, NULL)
ADD_TYPE(m, Index);
ADD_TYPE(m, IndexEntry);
/* Diff */
INIT_TYPE(DiffType, NULL, NULL)
INIT_TYPE(DiffIterType, NULL, NULL)
INIT_TYPE(PatchType, NULL, NULL)
INIT_TYPE(HunkType, NULL, NULL)
ADD_TYPE(m, Diff);
ADD_TYPE(m, Patch);
ADD_TYPE(m, Hunk);
/* Log */
INIT_TYPE(WalkerType, NULL, PyType_GenericNew)
/* Config */
INIT_TYPE(ConfigType, NULL, PyType_GenericNew)
ADD_TYPE(m, Config);
/* Remote */
INIT_TYPE(RemoteType, NULL, NULL)
/* Notes */
INIT_TYPE(NoteType, NULL, NULL)
INIT_TYPE(NoteIterType, NULL, NULL)
Py_INCREF(GitError);
PyModule_AddObject(m, "GitError", GitError);
Py_INCREF(&RepositoryType);
PyModule_AddObject(m, "Repository", (PyObject *)&RepositoryType);
Py_INCREF(&ObjectType);
PyModule_AddObject(m, "Object", (PyObject *)&ObjectType);
Py_INCREF(&CommitType);
PyModule_AddObject(m, "Commit", (PyObject *)&CommitType);
Py_INCREF(&TreeEntryType);
PyModule_AddObject(m, "TreeEntry", (PyObject *)&TreeEntryType);
Py_INCREF(&TreeType);
PyModule_AddObject(m, "Tree", (PyObject *)&TreeType);
Py_INCREF(&ConfigType);
PyModule_AddObject(m, "Config", (PyObject *)&ConfigType);
Py_INCREF(&BlobType);
PyModule_AddObject(m, "Blob", (PyObject *)&BlobType);
Py_INCREF(&TagType);
PyModule_AddObject(m, "Tag", (PyObject *)&TagType);
Py_INCREF(&IndexType);
PyModule_AddObject(m, "Index", (PyObject *)&IndexType);
Py_INCREF(&IndexEntryType);
PyModule_AddObject(m, "IndexEntry", (PyObject *)&IndexEntryType);
Py_INCREF(&DiffType);
PyModule_AddObject(m, "Diff", (PyObject *)&DiffType);
Py_INCREF(&ReferenceType);
PyModule_AddObject(m, "Reference", (PyObject *)&ReferenceType);
Py_INCREF(&SignatureType);
PyModule_AddObject(m, "Signature", (PyObject *)&SignatureType);
Py_INCREF(&RemoteType);
PyModule_AddObject(m, "Remote", (PyObject *)&RemoteType);
Py_INCREF(&NoteType);
PyModule_AddObject(m, "Note", (PyObject *)&NoteType);
ADD_TYPE(m, Remote);
/* Constants */
PyModule_AddIntConstant(m, "GIT_OBJ_ANY", GIT_OBJ_ANY);
PyModule_AddIntConstant(m, "GIT_OBJ_COMMIT", GIT_OBJ_COMMIT);
PyModule_AddIntConstant(m, "GIT_OBJ_TREE", GIT_OBJ_TREE);

4
src/repository.c
View File

@ -1009,7 +1009,7 @@ Repository_TreeBuilder(Repository *self, PyObject *args)
PyDoc_STRVAR(Repository_create_remote__doc__,
"remote_create(name, url) -> Remote\n"
"create_remote(name, url) -> Remote\n"
"\n"
"Creates a new remote.");
@ -1036,7 +1036,7 @@ Repository_create_remote(Repository *self, PyObject *args)
}
PyDoc_STRVAR(Repository_remotes__doc__, "returns all configured remotes");
PyDoc_STRVAR(Repository_remotes__doc__, "Returns all configured remotes.");
PyObject *
Repository_remotes__get__(Repository *self)

4
src/utils.h
View File

@ -141,5 +141,9 @@ char * py_str_to_c_str(PyObject *value, const char *encoding);
if (new != NULL) type.tp_new = new; \
if (PyType_Ready(&type) < 0) return NULL;
#define ADD_TYPE(module, type) \
Py_INCREF(& type ## Type); \
PyModule_AddObject(module, #type, (PyObject *) & type ## Type);
#endif