restructured recipes

This commit is contained in:
Jiunn Haur Lim 2013-07-05 20:14:33 -04:00
parent 5dfabbd825
commit 38bd4c065d
8 changed files with 214 additions and 42 deletions

View File

@ -1,41 +0,0 @@
**********************************************************************
Quick examples
**********************************************************************
A list of some common command-line operations and their pygit2 equivalents.
Creating a new repository with ``git init``
>>> pygit2.init_repository('repo_name', False)
<pygit2.repository.Repository object at 0x10f08b680>
Viewing a commit with ``git show d370f56``
>>> repo = pygit2.Repository('/path/to/repository')
>>> commit = repo['d370f56']
Viewing the last commit message
>>> repo[repo.head.oid].message
'commit message'
Traversing the commit history with ``git log``
>>> last = repo[repo.head.oid]
>>> for commit in repo.walk(last.oid, pygit2.GIT_SORT_TIME):
>>> print(commit.message) # or some other operation
Listing all branches with ``git branch``
>>> regex = re.compile('^refs/heads/')
>>> filter(lambda r: regex.match(r), repo.listall_references())
Similarly, listing all tags with ``git tag``
>>> regex = re.compile('^refs/tags')
>>> filter(lambda r: regex.match(r), repo.listall_references())
Listing all files in the last commit
>>> for e in repo[repo.head.oid].tree:
>>> print(e.name)

View File

@ -25,7 +25,7 @@ Start:
:maxdepth: 1 :maxdepth: 1
install install
examples recipes
Usage guide: Usage guide:

26
docs/recipes.rst Normal file
View File

@ -0,0 +1,26 @@
**********************************************************************
pygit2 Recipes
**********************************************************************
A list of some standard git commands and their pygit2 equivalents. This
document is a work in progress, and is organized according to the `git man
page`_.
----------------------------------------------------------------------
High Level Commands
----------------------------------------------------------------------
======================================================================
Main porcelain commands
======================================================================
.. toctree::
:maxdepth: 1
git-branch (List, create, or delete branches.) <recipes/git-branch>
git-init (Create an empty git repository or reinitialize an existing one.) <recipes/git-init>
git-log (Show commit logs.) <recipes/git-log>
git-show (Show various types of objects.) <recipes/git-show>
git-tag (Create, list, delete or verify a tag object signed with GPG.) <recipes/git-tag>
.. _git man page: https://www.kernel.org/pub/software/scm/git/docs/git.html

View File

@ -0,0 +1,30 @@
**********************************************************************
git-branch
**********************************************************************
----------------------------------------------------------------------
Listing branches
----------------------------------------------------------------------
======================================================================
List all branches
======================================================================
.. code-block:: bash
$> git branch
.. code-block:: python
>>> regex = re.compile('^refs/heads/')
>>> branches = filter(lambda r: regex.match(r), repo.listall_references())
`Note that the next release will probably allow` ``repo.listall_branches()``.
----------------------------------------------------------------------
References
----------------------------------------------------------------------
- git-branch_.
.. _git-branch: https://www.kernel.org/pub/software/scm/git/docs/git-branch.html

41
docs/recipes/git-init.rst Normal file
View File

@ -0,0 +1,41 @@
**********************************************************************
git-init
**********************************************************************
----------------------------------------------------------------------
Creating a new repository
----------------------------------------------------------------------
======================================================================
Create bare repository
======================================================================
.. code-block:: bash
$> git init --bare relative/path
.. code-block:: python
>>> pygit2.init_repository('relative/path', True)
<pygit2.repository.Repository object at 0x10f08b680>
======================================================================
Create standard repository
======================================================================
.. code-block:: bash
$> git init relative/path
.. code-block:: python
>>> pygit2.init_repository('relative/path', False)
<pygit2.repository.Repository object at 0x10f08b680>
----------------------------------------------------------------------
References
----------------------------------------------------------------------
- git-init_.
.. _git-init: https://www.kernel.org/pub/software/scm/git/docs/git-init.html

43
docs/recipes/git-log.rst Normal file
View File

@ -0,0 +1,43 @@
**********************************************************************
git-log
**********************************************************************
----------------------------------------------------------------------
Showing HEAD commit logs
----------------------------------------------------------------------
======================================================================
Show HEAD commit
======================================================================
.. code-block:: bash
$> git log -1
.. code-block:: python
>>> commit = repo[repo.head.oid]
>>> commit.message
'commit message'
======================================================================
Traverse commit history
======================================================================
.. code-block:: bash
$> git log
.. code-block:: python
>>> last = repo[repo.head.oid]
>>> for commit in repo.walk(last.oid, pygit2.GIT_SORT_TIME):
>>> print(commit.message) # or some other operation
----------------------------------------------------------------------
References
----------------------------------------------------------------------
- git-log_.
.. _git-log: https://www.kernel.org/pub/software/scm/git/docs/git-log.html

49
docs/recipes/git-show.rst Normal file
View File

@ -0,0 +1,49 @@
**********************************************************************
git-show
**********************************************************************
----------------------------------------------------------------------
Showing a commit
----------------------------------------------------------------------
.. code-block:: bash
$> git show d370f56
.. code-block:: python
>>> repo = pygit2.Repository('/path/to/repository')
>>> commit = repo.revparse_single('d370f56')
======================================================================
Show log message
======================================================================
>>> message = commit.message
======================================================================
Show SHA hash
======================================================================
>>> hash = commit.hex
======================================================================
Show diff
======================================================================
>>> diff = commit.tree.diff()
======================================================================
Show all files in commit
======================================================================
>>> for e in commit.tree:
>>> print(e.name)
----------------------------------------------------------------------
References
----------------------------------------------------------------------
- git-show_.
.. _git-show: https://www.kernel.org/pub/software/scm/git/docs/git-show.html

24
docs/recipes/git-tag.rst Normal file
View File

@ -0,0 +1,24 @@
**********************************************************************
git-tag
**********************************************************************
----------------------------------------------------------------------
Showing all tags
----------------------------------------------------------------------
.. code-block:: bash
$> git tag
.. code-block:: python
>>> regex = re.compile('^refs/tags')
>>> filter(lambda r: regex.match(r), repo.listall_references())
----------------------------------------------------------------------
References
----------------------------------------------------------------------
- git-tag_.
.. _git-tag: https://www.kernel.org/pub/software/scm/git/docs/git-tag.html