From cced2057ea95f7db62a5adc199a4bf9081b13510 Mon Sep 17 00:00:00 2001
From: cjbarth <chrisjbarth@hotmail.com>
Date: Tue, 5 Jul 2016 00:04:16 -0400
Subject: [PATCH] Add support to `describe` a commit (#88)

---
 README.md               |  4 ++++
 src/commit.coffee       | 20 ++++++++++++++++++++
 test/commit.test.coffee | 15 +++++++++++++++
 3 files changed, 39 insertions(+)

diff --git a/README.md b/README.md
index b072115..8c64067 100644
--- a/README.md
+++ b/README.md
@@ -259,7 +259,11 @@ Checkout files.
 `Date`
 ### `Commit#message`
 `String`
+### `Commit#description([refs, [first_parent, ]]callback)`
 
+ * refs - String (`all`, `tags`, or `null` for default of unannotated tags).
+ * first_parent - Boolean (follow lineage or include all ancestry).
+ * callback - `(err, description)` (`description` is String).
 
 ## Head
 ### `Head#name`
diff --git a/src/commit.coffee b/src/commit.coffee
index af2b5d2..22c087a 100644
--- a/src/commit.coffee
+++ b/src/commit.coffee
@@ -16,6 +16,26 @@ module.exports = class Commit
       _.map parents, (parent) =>
         new Commit @repo, parent
 
+    # Public: `git describe <id>`.
+    #
+    # id           - Commit sha-1
+    # refs         - ["all" or "tags"]; default is annotated tags
+    # first_parent - A boolean indicating only the first parent should be followed.
+    # callback     - Receives `(err, description)`.
+    #
+    @describe = (refs, first_parent, callback) =>
+      [first_parent, callback] = [callback, first_parent] if !callback
+      [refs, callback] = [callback, refs] if !callback
+      options = {};
+      options.all = true if refs == "all"
+      options.tags = true if refs == "tags"
+      options.first-parent = true if !!first_parent
+      options.long = true
+
+      @repo.git "describe", options, @id
+      , (err, stdout, stderr) ->
+        return callback err if err
+        return callback null, stdout.trim()
 
   toJSON: ->
     {@id, @author, @authored_date, @committer, @committed_date, @message}
diff --git a/test/commit.test.coffee b/test/commit.test.coffee
index d9df01d..0d53325 100644
--- a/test/commit.test.coffee
+++ b/test/commit.test.coffee
@@ -33,3 +33,18 @@ describe "Commit", ->
 
     it "has the parent commit", ->
       parents[0].id.should.eql parent.id
+
+  describe "#describe", ->
+    repo   = fixtures.branched
+    commit = null
+    before (done) ->
+      repo.commits "something", (err, commits) ->
+        commit = commits[0]
+        done err
+
+    it "should be a long description", (done) ->
+      repo.commits "something", (err, commits) ->
+        commit.describe 'all', (err, description) ->
+          # long descriptions have a '-g' in them to separate the sha-1
+          (/-g/.test description).should.eql true
+          done err