diff --git a/docs/examples.rst b/docs/examples.rst deleted file mode 100644 index aeb6a5a..0000000 --- a/docs/examples.rst +++ /dev/null @@ -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) - - -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) diff --git a/docs/index.rst b/docs/index.rst index 59a8854..5d25e68 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -25,7 +25,7 @@ Start: :maxdepth: 1 install - examples + recipes Usage guide: diff --git a/docs/recipes.rst b/docs/recipes.rst new file mode 100644 index 0000000..019f863 --- /dev/null +++ b/docs/recipes.rst @@ -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.) + git-init (Create an empty git repository or reinitialize an existing one.) + git-log (Show commit logs.) + git-show (Show various types of objects.) + git-tag (Create, list, delete or verify a tag object signed with GPG.) + +.. _git man page: https://www.kernel.org/pub/software/scm/git/docs/git.html diff --git a/docs/recipes/git-branch.rst b/docs/recipes/git-branch.rst new file mode 100644 index 0000000..5db822b --- /dev/null +++ b/docs/recipes/git-branch.rst @@ -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 diff --git a/docs/recipes/git-init.rst b/docs/recipes/git-init.rst new file mode 100644 index 0000000..75211a9 --- /dev/null +++ b/docs/recipes/git-init.rst @@ -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) + + +====================================================================== +Create standard repository +====================================================================== + +.. code-block:: bash + + $> git init relative/path + +.. code-block:: python + + >>> pygit2.init_repository('relative/path', False) + + +---------------------------------------------------------------------- +References +---------------------------------------------------------------------- + +- git-init_. + +.. _git-init: https://www.kernel.org/pub/software/scm/git/docs/git-init.html diff --git a/docs/recipes/git-log.rst b/docs/recipes/git-log.rst new file mode 100644 index 0000000..e9c10b7 --- /dev/null +++ b/docs/recipes/git-log.rst @@ -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 diff --git a/docs/recipes/git-show.rst b/docs/recipes/git-show.rst new file mode 100644 index 0000000..0cba72d --- /dev/null +++ b/docs/recipes/git-show.rst @@ -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 diff --git a/docs/recipes/git-tag.rst b/docs/recipes/git-tag.rst new file mode 100644 index 0000000..8ed899e --- /dev/null +++ b/docs/recipes/git-tag.rst @@ -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