GitRepository: add describe() method

Provides more output options than find_tag().
- longfmt: for getting the tag name in the long format (tag, number of
  commits and sha1)
- always: for falling back to sha1 if no (matching) tag name is found
- abbrev: for defining the length of sha1 returned

Change GitRepository.find_tag() to use the the new method.

Signed-off-by: Markus Lehtonen <markus.lehtonen@linux.intel.com>

2 files changed, 66 insertions, 11 deletions

diff --git a/gbp/git/repository.py b/gbp/git/repository.py
index 5306e9e4..64792d89 100644
--- a/gbp/git/repository.py
+++ b/gbp/git/repository.py
@@ -598,6 +598,43 @@ class GitRepository(object):
         out, ret = self._git_getoutput('tag', [ '-l', tag ])
         return [ False, True ][len(out)]
 
+    def describe(self, commitish, pattern=None, longfmt=False, always=False,
+                 abbrev=None):
+        """
+        Describe commit, relative to the latest tag reachable from it.
+
+        @param commitish: the commit-ish to describe
+        @type commitish: C{str}
+        @param pattern: only look for tags matching I{pattern}
+        @type pattern: C{str}
+        @param longfmt: describe the commit in the long format
+        @type longfmt: C{bool}
+        @param always: return commit sha1 as fallback if no tag is found
+        @type always: C{bool}
+        @param abbrev: abbreviate sha1 to given length instead of the default
+        @type abbrev: None or C{long}
+        @return: tag name plus/or the abbreviated sha1
+        @rtype: C{str}
+        """
+        args = GitArgs()
+        args.add_true(pattern, ['--match' , pattern])
+        args.add_true(longfmt, '--long')
+        # 'long' and 'abbrev=0' are incompatible, behave similar to
+        # 'always' and 'abbrev=0'
+        if longfmt and abbrev == 0:
+            args.add('--abbrev=40')
+        elif abbrev is not None:
+            args.add('--abbrev=%s' % abbrev)
+        args.add_true(always, '--always')
+        args.add(commitish)
+
+        tag, err, ret = self._git_inout('describe', args.args,
+                                        capture_stderr=True)
+        if ret:
+            raise GitRepositoryError("Can't describe %s. Git error: %s" % \
+                                         (commitish, err.strip()))
+        return tag.strip()
+
     def find_tag(self, commit, pattern=None):
         """
         Find the closest tag to a given commit
@@ -609,16 +646,7 @@ class GitRepository(object):
         @return: the found tag
         @rtype: C{str}
         """
-        args =  [ '--abbrev=0' ]
-        if pattern:
-            args += [ '--match' , pattern ]
-        args += [ commit ]
-
-        tag, err, ret = self._git_inout('describe', args, capture_stderr=True)
-        if ret:
-            raise GitRepositoryError("Can't find tag for %s. Git error: %s" % \
-                                         (commit, err.strip()))
-        return tag.strip()
+        return self.describe(commit, pattern, abbrev=0)
 
     def get_tags(self, pattern=None):
         """
diff --git a/tests/test_GitRepository.py b/tests/test_GitRepository.py
index 5e11fad3..37b50f80 100644
--- a/tests/test_GitRepository.py
+++ b/tests/test_GitRepository.py
@@ -241,6 +241,33 @@ def test_tag():
     ['tag', 'tag2']
     """
 
+def test_describe():
+    """
+    Describe commit-ish
+
+    Methods tested:
+         - L{gbp.git.GitRepository.describe}
+
+    >>> import gbp.git
+    >>> repo = gbp.git.GitRepository(repo_dir)
+    >>> sha = repo.rev_parse('HEAD')
+    >>> repo.describe('HEAD')
+    'tag2'
+    >>> repo.describe('HEAD', longfmt=True) == 'tag2-0-g%s' % sha[:7]
+    True
+    >>> repo.describe('HEAD', pattern='foo*')
+    Traceback (most recent call last):
+    ...
+    GitRepositoryError: Can't describe HEAD. Git error: fatal: No names found, cannot describe anything.
+    >>> repo.describe('HEAD', pattern='foo*', always=True) == sha[:7]
+    True
+    >>> repo.describe('HEAD', always=True, abbrev=16)
+    'tag2'
+    >>> repo.describe('HEAD', pattern='foo*', always=True, abbrev=16) == sha[:16]
+    True
+    >>> tag = repo.describe('HEAD', longfmt=True, abbrev=16) == 'tag2-0-g%s' % sha[:16]
+    """
+
 def test_find_tag():
     """
     Find tags
@@ -255,7 +282,7 @@ def test_find_tag():
     >>> repo.find_tag('HEAD', pattern='foo*')
     Traceback (most recent call last):
     ...
-    GitRepositoryError: Can't find tag for HEAD. Git error: fatal: No names found, cannot describe anything.
+    GitRepositoryError: Can't describe HEAD. Git error: fatal: No names found, cannot describe anything.
     """
 
 def test_move_tag():