diff --git a/README.rst b/README.rst index a352308..4761e29 100644 --- a/README.rst +++ b/README.rst @@ -6,407 +6,40 @@ pygit2 - libgit2 bindings in Python .. image:: https://secure.travis-ci.org/libgit2/pygit2.png :target: http://travis-ci.org/libgit2/pygit2 -pygit2 is a set of Python bindings to the libgit2 linkable C Git library. -The supported versions of Python are 2.6, 2.7, 3.1 and 3.2 +Pygit2 is a set of Python bindings to the libgit2 shared library, libgit2 +implements the core of Git. Pygit2 works with Python 2.6, 2.7, 3.1 and 3.2 -You can find an up-to-date api documentation at http://libgit2.github.com/pygit2. +Pygit2 links: -Through this text Python 3 is used for the inline examples. Also, the Python -3 terminology is used (for instance we say text strings instead of unicode -strings). +- http://github.com/libgit2/pygit2 -- Source code and issue tracker +- http://www.pygit2.org/ -- Documentation +- http://pypi.python.org/pypi/pygit2 -- Download -.. contents:: -********************************************************************** -Installing and running -********************************************************************** +Quick install guide +=================== -First you need to install the latest version of libgit2. -You can find platform-specific instructions to build the library in the libgit2 website: +1. Download libgit2 v0.17.0 + https://github.com/downloads/libgit2/libgit2/libgit2-0.17.0.tar.gz - http://libgit2.github.com +2. Build and install libgit2 + http://libgit2.github.com/#install -Also, make sure you have Python 2.6+ installed together with the Python development headers. +3. Install pygit2 with *pip*:: -When those are installed, you can install pygit2:: + $ pip install pygit2 - $ git clone git://github.com/libgit2/pygit2.git - $ cd pygit2 - $ python setup.py install - $ python setup.py test +For detailed instructions check the documentation, +http://www.pygit2.org/install.html -Building on \*nix (including OS X) -=================================== -If you installed libgit2 and pygit2 in one of the usual places, you -should be able to skip this section and just use the generic pygit2 -installation steps described above. This is the recommended -procedure. - -`Shared libraries`_ packaged by your distribution are usually in -``/usr/lib``. To keep manually installed libraries separate, they are -usually installed in ``/usr/local/lib``. If you installed libgit2 -using the default installation procedure (e.g. without specifying -``CMAKE_INSTALL_PREFIX``), you probably installed it under -``/usr/local/lib``. On some distributions (e.g. Ubuntu), -``/usr/local/lib`` is not in the linker's default search path (see the -`ld man page`_ for details), and you will get errors like:: - - $ python -c 'import pygit2' - Traceback (most recent call last): - File "", line 1, in - File "pygit2/__init__.py", line 29, in - from _pygit2 import * - ImportError: libgit2.so.0: cannot open shared object file: No such file or directory - -The following recipe shows how to install libgit2 and pygit2 on these -systems. First, download and install libgit2 (following the -instructions in the libgit2 ``README.md``):: - - $ git clone git://github.com/libgit2/libgit2.git - $ mkdir libgit2/build - $ cd libgit2/build - $ cmake .. - $ cmake --build . - $ sudo cmake --build . --target install - $ cd ../.. - -Now, download and install pygit2. You will probably have to set the -``LIBGIT2`` environment variable so the compiler can find the libgit2 -headers and libraries:: - - $ git clone git://github.com/libgit2/pygit2.git - $ cd pygit2 - $ export LIBGIT2="/usr/local" - $ export LDFLAGS="-Wl,-rpath='$LIBGIT2/lib',--enable-new-dtags $LDFLAGS" - $ python setup.py build - $ sudo python setup.py install - -This compiles the pygit2 libraries with a ``RUNPATH``, which bakes -extra library search paths directly into the binaries (see the `ld man -page`_ for details). With ``RUNPATH`` compiled in, you won't have to -use ``LD_LIBRARY_PATH``. You can check to ensure ``RUNPATH`` was set -with readelf_:: - - $ readelf --dynamic build/lib.linux-x86_64-3.2/_pygit2.cpython-32.so | grep PATH - 0x000000000000000f (RPATH) Library rpath: [/usr/local/lib] - 0x000000000000001d (RUNPATH) Library runpath: [/usr/local/lib] - -.. _Shared libraries: http://tldp.org/HOWTO/Program-Library-HOWTO/shared-libraries.html -.. _ld man page: http://linux.die.net/man/1/ld -.. _readelf: http://www.gnu.org/software/binutils/ - -Building on Windows -=================================== - -pygit2 expects to find the libgit2 installed files in the directory specified -in the ``LIBGIT2`` environment variable. - -In addition, make sure that libgit2 is build in "__cdecl" mode. -The following recipe shows you how to do it, assuming you're working -from a bash shell:: - - $ export LIBGIT2=C:/Dev/libgit2 - $ git clone git://github.com/libgit2/libgit2.git - $ cd libgit2 - $ mkdir build - $ cd build - $ cmake .. -DSTDCALL=OFF -DCMAKE_INSTALL_PREFIX=$LIBGIT2 -G "Visual Studio 9 2008" - $ cmake --build . --config release --target install - $ ctest -v - -At this point, you're ready to execute the generic pygit2 installation -steps described above. - - -********************************************************************** -Usage -********************************************************************** - -The repository -================= - -Everything starts by opening an existing repository:: - - >>> from pygit2 import Repository - >>> repo = Repository('pygit2/.git') - -Or by creating a new one:: - - >>> from pygit2 import init_repository - >>> bare = False - >>> repo = init_repository('test', bare) - -These are the basic attributes of a repository:: - - Repository.path -- path to the Git repository - Repository.workdir -- path to the working directory, None in the case of - a bare repo - - -Git objects -=========== - -In the first place Git is a key-value storage system. The values stored are -called *objects*, there are four types (commits, trees, blobs and tags), -for each type pygit2 has a Python class:: - - # Get the last commit - >>> head = repo.head - - # Show commits and trees - >>> commit - - >>> commit.tree - - -These four classes (``Commit``, ``Tree``, ``Blob`` and ``Tag``) inherit from -the ``Object`` base class, which provides shared behaviour. A Git object is -identified by a unique *object id*, which is a binary byte string; this is -often represented as an hexadecimal text string:: - - >>> commit.oid - b'x\xde\xb5W\x8d\x01<\xdb\xdf\x08o\xa1\xd1\xa3\xe7\xd9\x82\xe8\x88\x8f' - >>> commit.hex - '78deb5578d013cdbdf086fa1d1a3e7d982e8888f' - -The API of pygit2 accepts both the raw object id and its hexadecimal -representation, the difference is done based on its type (a byte or a text -string). - -This is the common interface for all Git objects:: - - Object.type -- one of the GIT_OBJ_COMMIT, GIT_OBJ_TREE, - GIT_OBJ_BLOB or GIT_OBJ_TAG constants - Object.oid -- the object id, a byte string 20 bytes long - Object.hex -- hexadecimal representation of the object id, a text - string 40 chars long - Object.read_raw() -- returns the byte string with the raw contents of the - of the object - -Objects can not be modified once they have been created. - - -Commits ------------------ - -A commit is a snapshot of the working dir with meta informations like author, -committer and others.:: - - Commit.author -- the author of the commit - Commit.committer -- the committer of the commit - Commit.message -- the message, a text string - Commit.tree -- the tree object attached to the commit - Commit.parents -- the list of parent commits - - -Signatures -............. - -The author and committer attributes of commit objects are ``Signature`` -objects:: - - >>> commit.author - - -This is their interface:: - - Signature.name -- person's name - Signature.email -- person's email address - Signature.time -- unix time - Signature.offset -- offset from utc in minutes - - -Creating commits -................ - -Commits can be created by calling the ``create_commit`` method of the -repository with the following parameters:: - - >>> author = Signature('Alice Author', 'alice@authors.tld') - >>> committer = Signature('Cecil Committer', 'cecil@committers.tld') - >>> tree = repo.TreeBuilder().write() - >>> repo.create_commit( - ... 'refs/heads/master', # the name of the reference to update - ... author, committer, 'one line commit message\n\ndetailed commit message', - ... tree, # binary string representing the tree object ID - ... [] # list of binary strings representing parents of the new commit - ... ) - '#\xe4>> tree = commit.tree - >>> len(tree) - 6 - - # Iteration - >>> for entry in tree: - ... print(entry.hex, entry.name) - ... - 7151ca7cd3e59f3eab19c485cfbf3cb30928d7fa .gitignore - c36f4cf1e38ec1bb9d9ad146ed572b89ecfc9f18 COPYING - 32b30b90b062f66957d6790c3c155c289c34424e README.md - c87dae4094b3a6d10e08bc6c5ef1f55a7e448659 pygit2.c - 85a67270a49ef16cdd3d328f06a3e4b459f09b27 setup.py - 3d8985bbec338eb4d47c5b01b863ee89d044bd53 test - - # Get an entry by name - >>> entry = tree['pygit2.c'] - >>> entry - - - # Get the object the entry points to - >>> blob = repo[entry.oid] - >>> blob - - -This is the interface of a tree entry:: - - TreeEntry.name -- name of the tree entry - TreeEntry.oid -- the id of the git object - TreeEntry.hex -- hexadecimal representation of the oid - TreeEntry.filemode -- the Unix file attributes - TreeEntry.to_object() -- returns the git object (equivalent to repo[entry.oid]) - - -Diff ------------------ - -A diff shows the changes between trees, an index or the working dir:: - - # Diff two trees - >>> t0 = repo.head.tree - >>> t1 = repo.head.parents[0].tree - >>> diff = t1.diff(t0) - >>> diff - - # Diff a tree with the index - >>> tree = repo.head.tree - >>> diff = tree.diff(repo.index) - - # Diff a tree with the current 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 - - -Blobs ------------------ - -A blob is equivalent to a file in a file system.:: - - # create a blob out of memory - >>> oid = repo.create_blob('foo bar') - >>> blob = repo[oid] - - Blob.data -- the contents of the blob, a byte string - -Tags ------------------ - -A tag is a static label for a commit. See references for more information. - - - -References -================= - -Reference lookup:: - - >>> all_refs = repo.listall_references() - >>> master_ref = repo.lookup_reference("refs/heads/master") - >>> commit = repo[master_ref.oid] - -Reference log:: - - >>> head = repo.lookup_reference('refs/heads/master') - >>> for entry in head.log(): - ... print(entry.message) - -The interface for RefLogEntry:: - - RefLogEntry.committer -- Signature of Committer - RefLogEntry.message -- the message of the RefLogEntry - RefLogEntry.oid_old -- oid of old reference - RefLogEntry.oid_new -- oid of new reference - -Revision parsing -================ - -You can use any of the fancy `` forms supported by libgit2:: - - >>> commit = repo.revparse_single('HEAD^') - -Revision walking -================= - -You can iterate through the revision history with repo.walk:: - - >>> from pygit2 import GIT_SORT_TIME - >>> for commit in repo.walk(oid, GIT_SORT_TIME): - ... print(commit.hex) - -The 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 - -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 - - -********************************************************************** Contributing -********************************************************************** +============ Fork libgit2/pygit2 on GitHub, make it awesomer (preferably in a branch named for the topic), send a pull request. -TODO -================= - -See issues - - Authors ============== @@ -446,4 +79,27 @@ pygit2 project (sorted alphabetically): License ============== -GPLv2 with linking exception. See COPYING for more details. +**GPLv2 with linking exception.** + +This program is free software; you can redistribute it and/or +modify it under the terms of the GNU General Public License, +version 2, as published by the Free Software Foundation. + +In addition to the permissions in the GNU General Public License, +the authors give you unlimited permission to link the compiled +version of this file into combinations with other programs, +and to distribute those combinations without any restriction +coming from the use of this file. (The General Public License +restrictions do apply in other respects; for example, they cover +modification of the file, and distribution when not linked into +a combined executable.) + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program; see the file COPYING. If not, write to +the Free Software Foundation, 51 Franklin Street, Fifth Floor, +Boston, MA 02110-1301, USA. diff --git a/docs/index.rst b/docs/index.rst index 8c527a3..10eb5f5 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -9,11 +9,16 @@ Welcome to pygit2's documentation! .. image:: https://secure.travis-ci.org/libgit2/pygit2.png :target: http://travis-ci.org/libgit2/pygit2 -pygit2 is a set of Python bindings to the libgit2 linkable C Git library. -The supported versions of Python are 2.6, 2.7, 3.1 and 3.2 +Pygit2 is a set of Python bindings to the libgit2 shared library, libgit2 +implements the core of Git. Pygit2 works with Python 2.6, 2.7, 3.1 and 3.2 +Pygit2 links: -Contents: +- http://github.com/libgit2/pygit2 -- Source code and issue tracker +- http://www.pygit2.org/ -- Documentation +- http://pypi.python.org/pypi/pygit2 -- Download + +Table of Contents: .. toctree:: :maxdepth: 2