object: introduce git_describe_object()

4 files changed, 70 insertions, 0 deletions

diff --git a/include/git2.h b/include/git2.h
index f74976061..6713b4961 100644
--- a/include/git2.h
+++ b/include/git2.h
@@ -19,6 +19,7 @@
 #include "git2/commit.h"
 #include "git2/common.h"
 #include "git2/config.h"
+#include "git2/describe.h"
 #include "git2/diff.h"
 #include "git2/errors.h"
 #include "git2/filter.h"
diff --git a/include/git2/common.h b/include/git2/common.h
index 32237efed..ceb27205a 100644
--- a/include/git2/common.h
+++ b/include/git2/common.h
@@ -83,6 +83,8 @@ GIT_BEGIN_DECL
  */
 #define GIT_OID_HEX_ZERO "0000000000000000000000000000000000000000"
 
+#define FLAG_BITS 27
+
 /**
  * Return the version of the libgit2 library
  * being currently used.
diff --git a/include/git2/describe.h b/include/git2/describe.h
new file mode 100644
index 000000000..8a00d258a
--- /dev/null
+++ b/include/git2/describe.h
@@ -0,0 +1,66 @@
+/*
+ * Copyright (C) the libgit2 contributors. All rights reserved.
+ *
+ * This file is part of libgit2, distributed under the GNU GPL v2 with
+ * a Linking Exception. For full terms see the included COPYING file.
+ */
+#ifndef INCLUDE_git_describe_h__
+#define INCLUDE_git_describe_h__
+
+#include "common.h"
+#include "types.h"
+#include "buffer.h"
+
+/**
+ * @file git2/describe.h
+ * @brief Git describing routines
+ * @defgroup git_describe Git describing routines
+ * @ingroup Git
+ * @{
+ */
+GIT_BEGIN_DECL
+
+typedef enum {
+	GIT_DESCRIBE_DEFAULT,
+	GIT_DESCRIBE_TAGS,
+	GIT_DESCRIBE_ALL,
+} git_describe_strategy_t;
+
+/**
+ * Describe options structure
+ *
+ * Zero out for defaults.  Initialize with `GIT_DESCRIBE_OPTIONS_INIT` macro to
+ * correctly set the `version` field.  E.g.
+ *
+ *		git_describe_opts opts = GIT_DESCRIBE_OPTIONS_INIT;
+ */
+typedef struct git_describe_opts {
+	unsigned int version;
+
+	unsigned int max_candidates_tags; /** default: 10 */
+	unsigned int abbreviated_size;
+	unsigned int describe_strategy; /** default: GIT_DESCRIBE_DEFAULT */
+	const char *pattern;
+	int always_use_long_format;
+	int only_follow_first_parent;
+	int show_commit_oid_as_fallback;
+} git_describe_opts;
+
+#define GIT_DESCRIBE_DEFAULT_MAX_CANDIDATES_TAGS 10
+#define GIT_DESCRIBE_DEFAULT_ABBREVIATED_SIZE 7
+
+#define GIT_DESCRIBE_OPTIONS_VERSION 1
+#define GIT_DESCRIBE_OPTIONS_INIT { \
+	GIT_DESCRIBE_OPTIONS_VERSION, \
+	GIT_DESCRIBE_DEFAULT_MAX_CANDIDATES_TAGS, \
+	GIT_DESCRIBE_DEFAULT_ABBREVIATED_SIZE}
+
+GIT_EXTERN(int) git_describe_object(
+	git_buf *out,
+	git_object *committish,
+	git_describe_opts *opts);
+
+/** @} */
+GIT_END_DECL
+
+#endif
diff --git a/include/git2/errors.h b/include/git2/errors.h
index e22f0d86d..287498423 100644
--- a/include/git2/errors.h
+++ b/include/git2/errors.h
@@ -87,6 +87,7 @@ typedef enum {
 	GITERR_REVERT,
 	GITERR_CALLBACK,
 	GITERR_CHERRYPICK,
+	GITERR_DESCRIBE,
 } git_error_t;
 
 /**