Add support to describe a commit (#88)

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`

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}

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