Permalink
Browse files

Merge commit 'github-patrikf/master'

  • Loading branch information...
2 parents 1fe005d + 98025cb commit 6291efee820b81b15d9789285a5f6a90a5bf4152 @soult soult committed Jun 2, 2009
Showing with 1,823 additions and 29 deletions.
  1. +1 −0 .gitignore
  2. +1,514 −0 Doxyfile
  3. +133 −0 doc/mainpage.doxygen
  4. +39 −21 lib/git.class.php
  5. +3 −0 lib/git_blob.class.php
  6. +43 −1 lib/git_commit.class.php
  7. +61 −0 lib/git_object.class.php
  8. +29 −7 lib/git_tree.class.php
View
@@ -0,0 +1 @@
+doc/html
View
1,514 Doxyfile

Large diffs are not rendered by default.

Oops, something went wrong.
View
@@ -0,0 +1,133 @@
+/**
+
+@mainpage API Documentation
+
+@section remarks General Remarks
+
+In its current state, the interface provided by glip is still very close to
+git's format for storing objects. You can examine a particular object in its
+on-disk representation with <tt>git cat-file -p HASH</tt>. It is a good idea
+to get familiar with some git internals, although if you have already used
+git, many things are quite straightforward.
+
+If you find the glip API to be lacking in some respect—extend it! :-)
+
+The glip homepage is at <http://fimml.at/glip>.
+
+
+@section using Using glip
+
+To use glip from your PHP code, simply include lib/glip.php.
+
+
+@section sha1 SHA-1 Names
+
+Since git objects are uniquely identified by their SHA-1 hash, many glip
+functions expect you to pass a hash or return one. There are two common
+representations for SHA-1 hashes:
+
+- the human-readable 40-character hexadecimal representation, e.g. \c
+ b1950c3ed1a8121abec98075548da4b03d82a8e3, and
+- the machine-readable 20-character binary representation.
+
+glip provides sha1_hex() and sha1_bin() to convert between the two
+representations.
+
+@attention The glip classes always operate on SHA-1 hashes in binary
+representation.
+
+
+@section reading Reading from a git repository
+
+A git repository is represented by a Git instance. The constructor expects a
+path to either a bare git repository, or the .git directory of a non-bare repository.
+
+@code
+$repo = new Git('test.git');
+@endcode
+
+All objects in the repository are mapped to instances of GitObject subclass,
+i.e. GitBlob, GitTree or GitCommit. If you know the SHA-1 hash of a git
+object, you can use Git::getObject to create a corresponding GitObject
+instance.
+
+@code
+$some_object = $repo->getObject(sha1_bin('b1950c3ed1a8121abec98075548da4b03d82a8e3'));
+@endcode
+
+In most cases, you will not know the SHA-1 hash of the object you want yet.
+Instead, you might want to look up the tip of a branch with Git::getTip:
+
+@code
+$master_name = $repo->getTip('master');
+$master = $repo->getObject($master_name);
+@endcode
+
+@todo It should be possible to look up any ref, not only branches.
+
+In a common git repository, this will give you a GitCommit instance in
+$master, referring to the last commit made to the @em master branch.
+
+GitObject%s hold all related data in public attributes. For example,
+GitCommit::$summary contains the commit summary of a particular commit.
+Utility functions are provided to make it easier to perform common functions.
+
+@section writing Writing to a git repository
+
+To change things in a repository, you currently have to directly make changes
+to the underlying git objects, no abstract interface is provided by glip yet.
+Once again, feel free to contribute.
+
+Creating a new object can be done in two ways:
+
+- starting with an existing object, or
+- starting from scratch.
+
+@code
+$object = clone $similar_object;
+/* OR */
+$object = new GitBlob($repo); /* or GitTree or GitCommit */
+@endcode
+
+@note
+It is good practice to use \c clone when modifying an object you received from
+Git::getObject() or another glip function calling it. Objects might be cached
+across Git::getObject() calls in future.
+
+You should then modify the object's public attributes accordingly, either
+directly or through helper functions like GitTree::updateNode(). When you're
+finished modifying, you need to update glip's internal cached hash value by
+using GitObject::rehash().
+
+@attention
+GitObject::getName() and all functions relying on it (including glip
+functions) may behave strangely if you fail to call GitObject::rehash() after
+modifying public attributes. This can ultimately lead to corrupted
+repositories.
+
+@note
+For performance reasons, you should not call GitObject::rehash() unless you
+really have to.
+
+@code
+$object = new GitBlob($repo);
+$object->data = "Hello World\n";
+$object->rehash();
+@endcode
+
+You can now use GitObject::getName() to get the object's SHA-1 sum and
+possibly reference it in other GitObject%s.
+
+The object has not written to disk yet. To do so, use GitObject::write():
+@code
+$object->write();
+@endcode
+
+Et voilà! You just wrote a new object to a git repository from PHP. If you
+actually execute the example code listed here, the result will be similar to
+that of <tt>echo Hello World | git hash-object -w --stdin</tt>.
+
+The same procedure applies to GitTree and GitCommit as well, just that they
+have different attributes to modify.
+
+*/
View
@@ -25,11 +25,25 @@
require_once('git_commit_stamp.class.php');
require_once('git_tree.class.php');
+/**
+ * @relates Git
+ * @brief Convert a SHA-1 hash from hexadecimal to binary representation.
+ *
+ * @param $hex (string) The hash in hexadecimal representation.
+ * @returns (string) The hash in binary representation.
+ */
function sha1_bin($hex)
{
return pack('H40', $hex);
}
+/**
+ * @relates Git
+ * @brief Convert a SHA-1 hash from binary to hexadecimal representation.
+ *
+ * @param $bin (string) The hash in binary representation.
+ * @returns (string) The hash in hexadecimal representation.
+ */
function sha1_hex($bin)
{
return bin2hex($bin);
@@ -85,9 +99,9 @@ public function __construct($dir)
}
/**
- * Tries to find $object_name in the fanout table in $f at $offset.
- *
- * @return array The range where the object can be located (first possible
+ * @brief Tries to find $object_name in the fanout table in $f at $offset.
+ *
+ * @returns array The range where the object can be located (first possible
* location and past-the-end location)
*/
protected function readFanout($f, $object_name, $offset)
@@ -109,10 +123,10 @@ protected function readFanout($f, $object_name, $offset)
}
/**
- * Try to find an object in a pack.
+ * @brief Try to find an object in a pack.
*
- * @param string $object_name name of the object (binary SHA1)
- * @return array an array consisting of the name of the pack (string) and
+ * @param $object_name (string) name of the object (binary SHA1)
+ * @returns (array) an array consisting of the name of the pack (string) and
* the byte offset inside it, or NULL if not found
*/
protected function findPackedObject($object_name)
@@ -198,11 +212,11 @@ protected function findPackedObject($object_name)
}
/**
- * Apply the git delta $delta to the byte sequence $base.
+ * @brief Apply the git delta $delta to the byte sequence $base.
*
- * @param string $delta the delta to apply
- * @param string $base the sequence to patch
- * @return string the patched byte sequence
+ * @param $delta (string) the delta to apply
+ * @param $base (string) the sequence to patch
+ * @returns (string) the patched byte sequence
*/
protected function applyDelta($delta, $base)
{
@@ -240,11 +254,11 @@ protected function applyDelta($delta, $base)
}
/**
- * Unpack an object from a pack.
+ * @brief Unpack an object from a pack.
*
- * @param resource $pack open .pack file
- * @param resource $object_offset offset of the object in the pack
- * @return array an array consisting of the object type (int) and the
+ * @param $pack (resource) open .pack file
+ * @param $object_offset (integer) offset of the object in the pack
+ * @returns (array) an array consisting of the object type (int) and the
* binary representation of the object (string)
*/
protected function unpackObject($pack, $object_offset)
@@ -320,11 +334,12 @@ protected function unpackObject($pack, $object_offset)
}
/**
- * Fetch an object in its binary representation by name.
+ * @brief Fetch an object in its binary representation by name.
+ *
* Throws an exception if the object cannot be found.
*
- * @param string $object_name name of the object (binary SHA1)
- * @return array an array consisting of the object type (int) and the
+ * @param $object_name (string) name of the object (binary SHA1)
+ * @returns (array) an array consisting of the object type (int) and the
* binary representation of the object (string)
*/
protected function getRawObject($object_name)
@@ -367,10 +382,10 @@ protected function getRawObject($object_name)
}
/**
- * Fetch an object in its PHP representation.
+ * @brief Fetch an object in its PHP representation.
*
- * @param string $name name of the object (binary SHA1)
- * @return GitObject the object
+ * @param $name (string) name of the object (binary SHA1)
+ * @returns (GitObject) the object
*/
public function getObject($name)
{
@@ -382,7 +397,10 @@ public function getObject($name)
}
/**
- * Returns the tip of $branch (binary sha1).
+ * @brief Look up a branch.
+ *
+ * @param $branch (string) The branch to look up, defaulting to @em master.
+ * @returns (string) The tip of the branch (binary sha1).
*/
public function getTip($branch='master')
{
View
@@ -22,6 +22,9 @@
class GitBlob extends GitObject
{
+ /**
+ * @brief The data contained in this blob.
+ */
public $data = NULL;
public function __construct($repo)
View
@@ -23,11 +23,36 @@
class GitCommit extends GitObject
{
+ /**
+ * @brief (string) The tree referenced by this commit, as binary sha1
+ * string.
+ */
public $tree;
+
+ /**
+ * @brief (array of string) Parent commits of this commit, as binary sha1
+ * strings.
+ */
public $parents;
+
+ /**
+ * @brief (GitCommitStamp) The author of this commit.
+ */
public $author;
+
+ /**
+ * @brief (GitCommitStamp) The committer of this commit.
+ */
public $committer;
+
+ /**
+ * @brief (string) Commit summary, i.e. the first line of the commit message.
+ */
public $summary;
+
+ /**
+ * @brief (string) Everything after the first line of the commit message.
+ */
public $detail;
public function __construct($repo)
@@ -74,7 +99,11 @@ public function _serialize()
return $s;
}
- /* returns history in topological order */
+ /**
+ * @brief Get commit history in topological order.
+ *
+ * @returns (array of GitCommit)
+ */
public function getHistory()
{
if ($this->history)
@@ -114,11 +143,24 @@ public function getHistory()
return $r;
}
+ /**
+ * @brief Get the tree referenced by this commit.
+ *
+ * @returns The GitTree referenced by this commit.
+ */
public function getTree()
{
return $this->repo->getObject($this->tree);
}
+ /**
+ * @copybrief GitTree::find()
+ *
+ * This is a convenience function calling GitTree::find() on the commit's
+ * tree.
+ *
+ * @copydetails GitTree::find()
+ */
public function find($path)
{
return $this->getTree()->find($path);
Oops, something went wrong.

0 comments on commit 6291efe

Please sign in to comment.