Update documentation (#157)

README.md

@@ -1,21 +1,41 @@
-Git lib for Gitonomy
-====================
+Gitlib for Gitonomy
+===================
 
 [![Build Status](https://img.shields.io/travis/gitonomy/gitlib/master.svg?style=flat-square)](https://travis-ci.org/gitonomy/gitlib)
 [![StyleCI](https://github.styleci.io/repos/5709354/shield?branch=master)](https://github.styleci.io/repos/5709354)
-<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square" alt="Software License"></img></a>
+[![License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](https://opensource.org/licenses/MIT)
 
 This library provides methods to access Git repository from PHP.
 
 It makes shell calls, which makes it less performant than any solution.
 
 Anyway, it's convenient and don't need to build anything to use it. That's how we love it.
 
-*Documentation*: http://gitonomy.com/doc/gitlib/master/
+## Documentation
+
+* [Overview](doc/index.md)
+* [Debug](doc/debug.md)
+* [Development](doc/development.md)
+* [Installation](doc/installation.md)
+* API
+  + [Admin](doc/api/admin.md)
+  + [Blame](doc/api/blame.md)
+  + [Blob](doc/api/blob.md)
+  + [Branch](doc/api/branch.md)
+  + [Commit](doc/api/commit.md)
+  + [Diff](doc/api/diff.md)
+  + [Hooks](doc/api/hooks.md)
+  + [Log](doc/api/log.md)
+  + [References](doc/api/references.md)
+  + [Repository](doc/api/repository.md)
+  + [Revision](doc/api/revision.md)
+  + [Tree](doc/api/tree.md)
+  + [Working Copy](doc/api/workingcopy.md)
 
 ## Quick Start
 
-You can install git lib using [Composer](https://getcomposer.org/). Simply require the version you need:
+You can install gitlib using [Composer](https://getcomposer.org/). Simply
+require the version you need:
 
 ```bash
 $ composer require gitonomy/gitlib
@@ -26,7 +46,7 @@ or edit your `composer.json` file by hand:
 ```json
 {
     "require": {
-        "gitonomy/gitlib": "^1.1"
+        "gitonomy/gitlib": "^1.2"
     }
 }
 ```

composer.json

@@ -20,7 +20,6 @@
             "email": "alexandre.salome@gmail.com"
         }
     ],
-    "homepage": "http://gitonomy.com",
     "autoload": {
         "psr-4": {
             "Gitonomy\\Git\\": "src/Gitonomy/Git/"

doc/api/admin.md

@@ -0,0 +1,77 @@
+Create and access git repositories
+==================================
+
+gitlib provides methods to initialize new repositories.
+
+Create a repository
+-------------------
+
+To initialize a new repository, use method `Admin::init`.
+
+```php
+// Initialize a bare repository
+$repository = Gitonomy\Git\Admin::init('/path/to/repository');
+
+// Initialize a non-bare repository
+$repository = Gitonomy\Git\Admin::init('/path/to/repository', false);
+```
+
+Default behavior is to create a bare repository. If you want to
+initialize a repository with a working copy,pass `false` as third
+argument of Repository constructor.
+
+Cloning repositories
+--------------------
+
+You can clone a repository from an URL by doing:
+
+```php
+// Clone to a bare repository
+$repository = Gitonomy\Git\Admin::cloneTo('/tmp/gitlib', 'https://github.com/gitonomy/gitlib.git');
+
+// Clone to a non-bare repository
+$repository = Gitonomy\Git\Admin::cloneTo('/tmp/gitlib', 'https://github.com/gitonomy/gitlib.git', false);
+```
+
+Default behavior is to clone in a bare repository.
+
+You can also clone a repository and point it to a specific branch. In a
+non-bare repository, this branch will be checked out:
+
+```php
+// Clone to a bare repository
+$repository = Gitonomy\Git\Admin::cloneBranchTo('/tmp/gitlib', 'https://github.com/gitonomy/gitlib.git', 'a-branch');
+
+// Clone to a non-bare repository
+$repository = Gitonomy\Git\Admin::cloneBranchTo('/tmp/gitlib', 'https://github.com/gitonomy/gitlib.git', 'a-branch' false);
+```
+
+Clone a Repository object
+-------------------------
+
+If you already have a Repository instance and want to clone it, you can
+use this shortcut:
+
+```php
+$new = $repository->cloneTo('/tmp/clone');
+```
+
+Mirror a repository
+-------------------
+
+If you want to mirror fully a repository and all references, use the
+`mirrorTo` method. This method takes only two arguments, where to mirror
+and what to mirror:
+
+```php
+// Mirror to a bare repository
+$mirror = Gitonomy\Git\Admin::mirrorTo('/tmp/mirror', 'https://github.com/gitonomy/gitlib.git');
+
+// Mirror to a non-bare repository
+$mirror = Gitonomy\Git\Admin::mirrorTo('/tmp/mirror', 'https://github.com/gitonomy/gitlib.git', false);
+```
+
+### References
+
+-   <http://linux.die.net/man/1/git-init>
+-   <http://linux.die.net/man/1/git-clone>

doc/api/blame.md

@@ -0,0 +1,58 @@
+Blaming files
+=============
+
+Line-per-line iteration
+-----------------------
+
+To iterate on lines of a blame:
+
+```php
+$blame = $repository->getBlame('master', 'README.md');
+
+foreach ($blame->getLines() as $lineNumber => $line) {
+    $commit = $line->getCommit();
+    echo $lineNumber.': '.$line->getContent()."    - ".$commit->getAuthorName()."\n";
+}
+```
+
+The *getLines* method returns an array indexed starting from 1.
+
+As you can see, you can access the commit object related to the line you
+are iterating on.
+
+If you want to access directly a line:
+
+```php
+$line = $blame->getLine(32);
+```
+
+The Line object
+---------------
+
+LineObject represents an item of the blame file. It is composed of those
+informations:
+
+```php
+$line->getCommit();  // returns a Commit
+$line->getContent(); // returns text
+
+// you can access author from commmit:
+$author = $line->getCommit()->getAuthorName();
+```
+
+Group reading by commit
+-----------------------
+
+If you plan to display it, you'll probably need a version where lines
+from same commit are grouped.
+
+To do so, use the *getGroupedLines* method that will return an array
+like this:
+
+```php
+$blame = array(
+    array(Commit, array(1 => Line, 2 => Line, 3 => Line)),
+    array(Commit, array(4 => Line)),
+    array(Commit, array(5 => Line, 6 => Line))
+)
+```

doc/api/blob.rst → doc/api/blob.md

@@ -2,43 +2,43 @@ Blob
 ====
 
 In git, a blob represents a file content. You can't access the file name
-directly from the *Blob* object; the filename information is stored within
-the tree, not in the blob.
+directly from the *Blob* object; the filename information is stored
+within the tree, not in the blob.
 
-It means that for git, two files with different names but same content will
-have the same hash.
+It means that for git, two files with different names but same content
+will have the same hash.
 
 To access a repository *Blob*, you need the hash identifier:
 
-.. code-block:: php
-
-    $repository = new Gitonomy\Git\Repository('/path/to/repository');
-    $blob = $repository->getBlob('a7c8d2b4');
+```php
+$repository = new Gitonomy\Git\Repository('/path/to/repository');
+$blob = $repository->getBlob('a7c8d2b4');
+```
 
 Get content
 -----------
 
 To get content from a *Blob* object:
 
-.. code-block:: php
-
-    echo $blob->getContent();
+```php
+echo $blob->getContent();
+```
 
 File informations
 -----------------
 
 To get mimetype of a *Blob* object using finfo extension:
 
-.. code-block:: php
-
-    echo $blob->getMimetype();
+```php
+echo $blob->getMimetype();
+```
 
 You can also test if *Blob* is a text of a binary file:
 
-.. code-block:: php
-
-    if ($blob->isText()) {
-        echo $blob->getContent(), "\n";
-    } elseif ($blob->isBinary()) {
-        echo "File is binary\n";
-    }
+```php
+if ($blob->isText()) {
+    echo $blob->getContent(), "\n";
+} elseif ($blob->isBinary()) {
+    echo "File is binary\n";
+}
+```