first implementation of debug-mode - #29

Author: alexandresalome

doc/api.rst

@@ -1,45 +1,75 @@
-Administration of git repositories
+Create and access git repositories
 ==================================
 
-Initializing repositories
-:::::::::::::::::::::::::
+gitlib provides methods to initialize new repositories.
 
-Create a bare repository
-------------------------
+Create a repository
+-------------------
 
-You can create a bare repository using ``Admin::init``:
+To initialize a new repository, use method ``Admin::init``.
 
 .. code-block:: php
 
+    // Initialize a bare repository
     $repository = Gitonomy\Git\Admin::init('/path/to/repository');
 
-Create a repository with a working copy
----------------------------------------
+    // Initialize a non-bare repository
+    $repository = Gitonomy\Git\Admin::init('/path/to/repository', false);
 
-If you want to create a repository with a working directory, pass ``false`` as
-second argument:
-
-.. code-block:: php
-
-    $repository = Gitonomy\Git\Admin::init('/tmp/git_sandbox', 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:
 
 .. code-block:: php
 
+    // Clone to a bare repository
     $repository = Gitonomy\Git\Admin::cloneTo('/tmp/gitlib', 'https://github.com/gitonomy/gitlib.git');
 
-You can pass ``false`` and third argument to get a repository with a working copy.
+    // 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.
+
+Clone a Repository object
+-------------------------
 
 If you already have a Repository instance and want to clone it, you can use this shortcut:
 
 .. code-block:: 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:
+
+.. code-block:: 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);
+
+Execution logs
+--------------
+
+All methods seen above take an additional parameters after ``$debug``. This parameter is used to report
+everything happening in repository: ``$logger``.
+
+If you want a report of execution, inject logger via constructor or repository-creation methods:
+
+.. code-block:: php
+
+    $logger = new 
+
 References
 ::::::::::
 

doc/api/admin.rst

@@ -1,73 +0,0 @@
-Repository methods
-==================
-
-Creating a *Repository* object is possible, providing a *path* argument to the
-constructor:
-
-.. code-block:: php
-
-    $repository = new Repository('/path/to/repo');
-
-Test if a repository is bare
-----------------------------
-
-On a *Repository* object, you can method *isBare* to test it:
-
-.. code-block:: php
-
-    if ($repository->isBare()) {
-        echo "This repository is bare\n";
-    }
-
-Compute size of a repository
-----------------------------
-
-To know how much size a repository is using on your drive, you can use
-``getSize`` method on a *Repository* object.
-
-This method will basically compute the size of the folder, using system ``du`` tool.
-
-The returned size is in kilobytes:
-
-.. code-block:: php
-
-    $size = $repository->getSize();
-    echo "Your repository size is ".$size."KB";
-
-Access HEAD
------------
-
-``HEAD`` represents in git the version you are working on (in working tree).
-Your ``HEAD`` can be attached (using a reference) or detached (using a commit).
-
-.. code-block:: php
-
-    $head = $repository->getHead(); // Commit or Reference
-    $head = $repository->getHeadCommit(); // Commit
-
-    if ($repository->isHeadDetached()) {
-        echo "Sorry man\n";
-    }
-
-Logger
-------
-
-If you are developing, you may appreciate to have a logger inside repository, telling
-you every executed command.
-
-To do so, inject a logger inside the Repository:
-
-.. code-block:: php
-
-    $repository->setLogger(new Monolog\Logger('repository'));
-
-    $repository->run('fetch', array('--all'));
-
-This will output:
-
-.. code-block:: text
-
-    info run command: fetch "--all"
-    debug last command (fetch) duration: 23.24ms
-    debug last command (fetch) return code: 0
-    debug last command (fetch) output: Fetching origin

doc/api/repository.rst

@@ -0,0 +1,22 @@
+Debug-mode
+==========
+
+gitlib offers a debug mode, to make you see edge-cases of your usage. This is called
+debug-mode.
+
+Debug-mode is enabled by default. If you disable it, gitlib will behave differently:
+
+* when an error is met during execution, gitlib will try to minimize it, to not block
+  execution flow. Errors will still be reporter in logger.
+* logs will be more verbose. They will contain every output, every return code, every
+  possible information to ease debugging.
+
+If you want to disable exceptions and try to minimize as much as possible errors, pass
+``false`` when construction a repository:
+
+.. code-block:: php
+
+    $repository = new Gitonomy\Git\Repository($path'/tmp/repo', $debug = false)
+
+``$debug`` argument should be available in every method you can use to create a
+repository.

doc/debug.rst

@@ -17,14 +17,34 @@ to fetch informations from repository.
     $repository->run('fetch', array('--all'));
 
 
+Reference
+---------
+
+.. toctree::
+   :maxdepth: 1
+
+   api/create_repository
+   api/hooks
+   api/workingcopy
+   api/commit
+   api/blame
+   api/blob
+   api/branch
+   api/tree
+   api/log
+   api/diff
+   api/references
+   api/revision
+
+
 Documentation
 -------------
 
 .. toctree::
    :maxdepth: 2
 
    installation
-   api
+   debug
    development
 
 Missing features

doc/index.rst

@@ -25,14 +25,16 @@ class Admin
     /**
      * Initializes a repository and returns the instance.
      *
-     * @param string  $path Path to the repository
-     * @param boolean $bare Indicate to create a bare repository
+     * @param string          $path   path to the repository
+     * @param boolean         $bare   indicate to create a bare repository
+     * @param boolean         $debug  flag indicating if errors should be thrown
+     * @param LoggerInterface $logger logger for debug purposes
      *
      * @return Repository
      *
-     * @throws RuntimeException Directory exists or not writable
+     * @throws RuntimeException Directory exists or not writable (only if debug=true)
      */
-    public static function init($path, $bare = true, LoggerInterface $logger = null)
+    public static function init($path, $bare = true, $debug = true, LoggerInterface $logger = null)
     {
         $builder = ProcessBuilder::create(array('git', 'init', '-q'));
 
@@ -46,29 +48,69 @@ public static function init($path, $bare = true, LoggerInterface $logger = null)
         $process->run();
 
         if (!$process->isSuccessFul()) {
-            throw new \RuntimeException(sprintf('Error while initializing repository: %s', $process->getErrorOutput()));
+            $message = sprintf("Error on repository initialization, command wasn't successful (%s). Error output:\n%s", $process->getCommandLine(), $process->getErrorOutput());
+
+            if (null !== $logger) {
+                $logger->error($message);
+            }
+
+            if (true === $debug) {
+                throw new \RuntimeException($message);
+            }
         }
 
-        return new Repository($path, null, $logger);
+        return new Repository($path, $debug, $logger);
     }
 
-    public static function cloneTo($path, $url, $bare = true, LoggerInterface $logger = null)
+    /**
+     * Clone a repository to a local path.
+     *
+     * @param string          $path   indicates where to clone repository
+     * @param string          $url    url of repository to clone
+     * @param boolean         $bare   indicates if repository should be bare or have a working copy
+     * @param boolean         $debug  flag indicating if errors should be thrown
+     * @param LoggerInterface $logger logger for debug purpopses
+     *
+     * @return Repository
+     */
+    public static function cloneTo($path, $url, $bare = true, $debug = true, LoggerInterface $logger = null)
     {
         $options = array();
 
         if ($bare) {
             $options[] = '--bare';
         }
 
-        return static::cloneRepository($path, $url, $options, $logger);
+        return static::cloneRepository($path, $url, $options, $debug, $logger);
     }
 
-    public static function mirrorTo($path, $url, LoggerInterface $logger = null)
+    /**
+     * Mirrors a repository (fetch all revisions, not only branches).
+     *
+     * @param string          $path   indicates where to clone repository
+     * @param string          $url    url of repository to clone
+     * @param boolean         $debug  flag indicating if errors should be thrown
+     * @param LoggerInterface $logger logger for debug purpopses
+     *
+     * @return Repository
+     */
+    public static function mirrorTo($path, $url, $debug = true, LoggerInterface $logger = null)
     {
         return static::cloneRepository($path, $url, array('--mirror'), $logger);
     }
 
-    private static function cloneRepository($path, $url, array $options = array(), LoggerInterface $logger = null)
+    /**
+     * Internal method to launch effective ``git clone`` command.
+     *
+     * @param string          $path    indicates where to clone repository
+     * @param string          $url     url of repository to clone
+     * @param array           $options arguments to be added to the command-line
+     * @param boolean         $debug   flag indicating if errors should be thrown
+     * @param LoggerInterface $logger  logger for debug purpopses
+     *
+     * @return Repository
+     */
+    private static function cloneRepository($path, $url, array $options = array(), $debug = true, LoggerInterface $logger = null)
     {
         $builder = ProcessBuilder::create(array('git', 'clone', '-q'));
 
@@ -86,6 +128,6 @@ private static function cloneRepository($path, $url, array $options = array(), L
             throw new \RuntimeException(sprintf('Error while initializing repository: %s', $process->getErrorOutput()));
         }
 
-        return new Repository($path, null, $logger);
+        return new Repository($path, $debug, $logger);
     }
 }