Merge pull request #17 from lyrixx/feat-enhancement

Added some enhancement

Author: Alexandre Salomé

doc/api.rst

@@ -11,6 +11,7 @@ API documentation
    api/commit
    api/blame
    api/blob
+   api/branch
    api/tree
    api/log
    api/diff

doc/api/branch.rst

@@ -0,0 +1,16 @@
+Branch
+======
+
+To access a *Branch*, starting from a repository object:
+
+.. code-block:: php
+
+    $repository = new Gitonomy\Git\Repository('/path/to/repository');
+    $branch = $repository->getReferences()->getBranch('master');
+
+You can check is the branch is a local or remote one:
+
+.. code-block:: php
+
+    $branch->isLocal();
+    $branch->isRemote();

doc/api/commit.rst

@@ -94,12 +94,33 @@ To access the message, you can use the *getMessage* method:
     $commit->getMessage();
 
 For your convenience, this library provides a shortcut method to keep only the
-first line or first 80 characters if the first line is too long:
+first line or first 50 characters if the first line is too long:
 
 .. code-block:: php
 
     $commit->getShortMessage();
 
+You can customize it like this:
+
+.. code-block:: php
+
+    $commit->getShortMessage(45, true, '.');
+
+* The first parameter is the max length of the message.
+* The second parameter determine if the last word should be cut or preserved
+* The third parameter is the separator
+
+There are also two other methods for your convenience:
+
+.. code-block:: php
+
+    // The first line
+    $commit->getSubjectMessage();
+
+    // The body (rest of the message)
+    $commit->getBodyMessage();
+
+
 Diff of a commit
 ----------------
 
@@ -137,3 +158,12 @@ Here is a very straightforward example:
     echo"  Author: ".$last->getAuthorName()."\n";
     echo"    Date: ".$last->getAuthorDate()->format('d/m/Y')."\n";
     echo" Message: ".$last->getMessage();
+
+Find every branches containing a commit
+---------------------------------------
+
+.. code-block:: php
+
+    $branches       = $commit->getIncludingBranches($includeLocalBranches, $includeRemoteBranches);
+    $localBranches  = $commit->getIncludingBranches(true, false);
+    $remoteBranches = $commit->getIncludingBranches(false, true);

doc/api/references.rst

@@ -23,17 +23,21 @@ If you want to access all branches or all tags:
 
 .. code-block:: php
 
-    $branches = $repository->getBranches();
-    $tags     = $repository->getTags();
-    $all      = $repository->getAll();
+    $branches       = $repository->getBranches();
+    $localBranches  = $repository->getLocalBranches();
+    $remoteBranches = $repository->getRemoteBranches();
+    $tags           = $repository->getTags();
+    $all            = $repository->getAll();
 
 To get a given branch or tag, call *getBranch* or *getTag* on the
 *ReferenceBag*. Those methods return *Branch* and *Tag* objects:
 
 .. code-block:: php
 
-    $master = $references->getBranch('master');
-    $v0_1 = $references->getTag('0.1');
+    $master  = $references->getBranch('master');
+    $feat123 = $references->getLocalBranch('feat123');
+    $feat456 = $references->getRemoteBranch('origin/feat456');
+    $v0_1    = $references->getTag('0.1');
 
 If the reference cannot be resolved, a *ReferenceNotFoundException* will be
 thrown.

src/Gitonomy/Git/Commit.php

@@ -111,13 +111,6 @@ class Commit
      */
     private $message;
 
-    /**
-     * Short message of the commit.
-     *
-     * @var string
-     */
-    private $shortMessage;
-
     /**
      * Constructor.
      *
@@ -266,36 +259,97 @@ public function getLastModification($path, $lastHash = null)
     }
 
     /**
-     * Returns the first line of the commit, and the first 80 characters.
+     * Returns the first line of the commit, and the first 50 characters.
+     *
+     * Ported from https://github.com/fabpot/Twig-extensions/blob/d67bc7e69788795d7905b52d31188bbc1d390e01/lib/Twig/Extensions/Extension/Text.php#L52-L109
+     *
+     * @param integer $length
+     * @param boolean $preserve
+     * @param string  $separator
      *
      * @return string
      */
-    public function getShortMessage($limit = 50)
+    public function getShortMessage($length = 50, $preserve = false, $separator = '...')
     {
         $this->initialize();
 
-        if (null !== $this->shortMessage) {
-            return $this->shortMessage;
-        }
+        $message = $this->getSubjectMessage();
 
-        $pos    = mb_strpos($this->message, "\n");
-        $length = mb_strlen($this->message);
+        if (function_exists('mb_substr')) {
+            if (mb_strlen($message) > $length) {
+                if ($preserve) {
+                    if (false !== ($breakpoint = mb_strpos($message, ' ', $length))) {
+                        $length = $breakpoint;
+                    }
+                }
 
-        if (false === $pos) {
-            if ($length < $limit) {
-                $shortMessage = $this->message;
-            } else {
-                $shortMessage = mb_substr($this->message, 0, $limit).'...';
+                return rtrim(mb_substr($message, 0, $length)) . $separator;
             }
+
+            return $message;
         } else {
-            if ($pos < $limit) {
-                $shortMessage = mb_substr($this->message, 0, $pos);
+            if (strlen($message) > $length) {
+                if ($preserve) {
+                    if (false !== ($breakpoint = strpos($message, ' ', $length))) {
+                        $length = $breakpoint;
+                    }
+                }
+
+                return rtrim(substr($message, 0, $length)) . $separator;
+            }
+
+            return $message;
+        }
+    }
+
+    /**
+     * Find branch containing the commit
+     *
+     * @param boolean $local  set true to try to locate a commit on local repository
+     * @param boolean $remote set true to try to locate a commit on remote repository
+     *
+     * @return array An array of Reference\Branch
+     */
+    public function getIncludingBranches($local = true, $remote = true)
+    {
+        $arguments = array('--contains', $this->hash);
+
+        if ($local && $remote) {
+            $arguments[] = '-a';
+        } elseif (!$local && $remote) {
+            $arguments[] = '-r';
+        } elseif (!$local && !$remote) {
+            throw new \InvalidArgumentException('You should a least set one argument to true');
+        }
+
+        try {
+            $result = $this->repository->run('branch', $arguments);
+        } catch (\Exception $e) {
+            return array();
+        }
+
+        if (!$result) {
+            return array();
+        }
+
+        $branchesName = explode("\n", trim(str_replace('*', '', $result)));
+        $branchesName = array_filter($branchesName, function($v) { return false === strpos($v, '->');});
+        $branchesName = array_map('trim', $branchesName);
+
+        $references = $this->repository->getReferences();
+
+        $branches = array();
+        foreach ($branchesName as $branchName) {
+            if (false === $local) {
+                $branches[] = $references->getRemoteBranch($branchName);
+            } elseif (0 === strrpos($branchName, 'remotes/')) {
+                $branches[] = $references->getRemoteBranch(str_replace('remotes/', '', $branchName));
             } else {
-                $shortMessage = mb_substr($this->message, 0, $limit).'...';
+                $branches[] = $references->getBranch($branchName);
             }
         }
 
-        return $this->shortMessage = $shortMessage;
+        return $branches;
     }
 
     /**
@@ -381,4 +435,35 @@ public function getMessage()
 
         return $this->message;
     }
+
+    /**
+     * Returns the subject message (the first line)
+     *
+     * @return string The subject message
+     */
+    public function getSubjectMessage()
+    {
+        $message = $this->getMessage();
+
+        $lines = explode("\n", $message);
+
+        return reset($lines);
+    }
+
+    /**
+     * Return the body message
+     *
+     * @return string The body message
+     */
+    public function getBodyMessage()
+    {
+        $message = $this->getMessage();
+
+        $lines = explode("\n", $message);
+
+        array_shift($lines);
+        array_shift($lines);
+
+        return implode("\n", $lines);
+    }
 }

src/Gitonomy/Git/Exception/ReferenceNotFoundException.php

@@ -16,6 +16,6 @@ class ReferenceNotFoundException extends \InvalidArgumentException implements Gi
 {
     public function __construct($reference)
     {
-        parent::__construct(sprintf('Reference not found'));
+        parent::__construct(sprintf('Reference not found: "%s"', $reference));
     }
 }

src/Gitonomy/Git/Reference/Branch.php

@@ -21,15 +21,42 @@
  */
 class Branch extends Reference
 {
+    private $local = null;
+
     /**
      * {@inheritdoc}
      */
     public function getName()
     {
-        if (!preg_match('#^refs/heads/(.*)$#', $this->fullname, $vars)) {
-            throw new \RuntimeException(sprintf('Cannot extract branch name from "%s"', $this->fullname));
+        if (preg_match('#^refs/heads/(?<name>.*)$#', $this->fullname, $vars)) {
+            return $vars['name'];
+        }
+
+        if (preg_match('#^refs/remotes/(?<remote>[^/]*)/(?<name>.*)$#', $this->fullname, $vars)) {
+            return $vars['remote'].'/'.$vars['name'];
         }
 
-        return $vars[1];
+        throw new \RuntimeException(sprintf('Cannot extract branch name from "%s"', $this->fullname));
+    }
+
+    public function isRemote()
+    {
+        $this->detectBranchType();
+
+        return !$this->local;
+    }
+
+    public function isLocal()
+    {
+        $this->detectBranchType();
+
+        return $this->local;
+    }
+
+    private function detectBranchType()
+    {
+        if (null === $this->local) {
+            $this->local = !preg_match('#^refs/remotes/(?<remote>[^/]*)/(?<name>.*)$#', $this->fullname);
+        }
     }
 }