It's not necessarily obvious how to perform a mirror, so add a recipe
which tells what git does as well as provide example code of how to
perform the same steps in pygit2.
In b3025e3fe I had written that when following my recipe, the repository
remains in cherry-picking mode afterwards. In issue #516 I was told that
Repository.state_cleanup() is needed to correct that. Therefore add it
to the recipe.
Also add a note near the documentation for cherry-pick, so that nobody
will overlook this again. Apparently there are other times when you need
to do Repository.state_cleanup() as well, but it's not documented, I
don't know when and I don't want to take the time and find out. So leave
it at that for now.
I'm not the guy who looks at examples in the first place and I guess
there are other people like me. When I wanted find out how to get
information out of a Diff, I looked at the documented methods and didn't
find anything. Only later @cmn showed me the [p for p in diff] example
in the documentation. Add a short piece of information that gives a hint
to those who prefer the dry API docs.
Add the way that worked for me. Not sure if it is idiomatic. When doing
the convenience-mode cherry-pick, the repo remains in cherry-picking
mode afterwards. I've already added an issue for this.
The submodule type has been implemented as a C type. When opening
a submodule's repository this leads to the bug that instead of an
actual pygit2.Repository being instantiated we only create an
object of the C Repository type.
As this is not trivially fixed within the C code, reimplement the
submodule type as a Python interface with CFFI. As submodules
provide no functionality that is usually accessed repeatedly the
code paths should not prove performance critical. In addition,
maintainability is improved by this reimplementation.
As @jdavid pointed out, Python 3 already provides a tzinfo subclass for
fixed UTC offsets. Incorporate this in the recipe. Leave the old code
with the self-made class, since many people are working with Python 2
and it is harder to find out there.
Make the diff generation more idiomatic and fix the assembling of the
timestamp. git-show normally prints the author time, so use this instead
of the commit time. Also fix how tzinfo is obtained. Of course we have
to use the author's time zone and not some fixed one as I had written
before.
I couldn't get the diff as shown in the git-show recipe. Therefore
update it to what I think it should be. Maybe there is a better way.
Also add a section on how to assemble a git show-like message. It took
me quite some searching in the Python docs to find out how to do it,
especially the date and time part. So this might save people time. I
wanted to add something that gives me a git show --stat equivalent, but
couldn't figure it out.
This commit allows blobs to be constructed from implementatons of the
'RawIOBase' ABC. This allows any conformant stream implementation to be added
as a blob.
This is useful in the case where the contents of the blob would be too large to
create from memory (as 'create_blob_fromstring' allows) and avoids having to
write the data to disk (as 'create_blob_fromworkdir' allows). The latter
operation is especially useful when reading data from a network socket, since
it avoids having to first commit all the data to disk.
