From 3a728fb508ea3eea8033a9e338c61a6421ad21b2 Mon Sep 17 00:00:00 2001 From: nulltoken Date: Tue, 13 Nov 2012 16:35:24 +0100 Subject: object: introduce git_describe_object() --- include/git2.h | 1 + include/git2/common.h | 2 ++ include/git2/describe.h | 66 +++++++++++++++++++++++++++++++++++++++++++++++++ include/git2/errors.h | 1 + 4 files changed, 70 insertions(+) create mode 100644 include/git2/describe.h (limited to 'include') 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; /** -- cgit v1.2.3 From 1f501a086b4a9103f5ef5540c82c57d8559f0aff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20Mart=C3=ADn=20Nieto?= Date: Tue, 30 Sep 2014 04:58:02 +0200 Subject: describe: rename _object() to _commit() We don't describe arbitrary object, so let's give it the name of the one object type we accept. --- include/git2/describe.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'include') diff --git a/include/git2/describe.h b/include/git2/describe.h index 8a00d258a..0a845f6be 100644 --- a/include/git2/describe.h +++ b/include/git2/describe.h @@ -55,7 +55,7 @@ typedef struct git_describe_opts { GIT_DESCRIBE_DEFAULT_MAX_CANDIDATES_TAGS, \ GIT_DESCRIBE_DEFAULT_ABBREVIATED_SIZE} -GIT_EXTERN(int) git_describe_object( +GIT_EXTERN(int) git_describe_commit( git_buf *out, git_object *committish, git_describe_opts *opts); -- cgit v1.2.3 From 3b6534b80768e8751b398cd3aeffb888e374c8d4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20Mart=C3=ADn=20Nieto?= Date: Tue, 30 Sep 2014 07:19:14 +0200 Subject: describe: split into gather and format steps Instead of printing out to the buffer inside the information-gathering phase, write the data to a intermediate result structure. This allows us to split the options into gathering options and formatting options, simplifying the gathering code. --- include/git2/describe.h | 27 +++++++++++++++++++++++---- 1 file changed, 23 insertions(+), 4 deletions(-) (limited to 'include') diff --git a/include/git2/describe.h b/include/git2/describe.h index 0a845f6be..6007b004e 100644 --- a/include/git2/describe.h +++ b/include/git2/describe.h @@ -38,10 +38,8 @@ 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; @@ -53,13 +51,34 @@ typedef struct git_describe_opts { #define GIT_DESCRIBE_OPTIONS_INIT { \ GIT_DESCRIBE_OPTIONS_VERSION, \ GIT_DESCRIBE_DEFAULT_MAX_CANDIDATES_TAGS, \ - GIT_DESCRIBE_DEFAULT_ABBREVIATED_SIZE} +} + +typedef struct { + unsigned int version; + + unsigned int abbreviated_size; + + int always_use_long_format; + char *dirty_suffix; +} git_describe_format_options; + +#define GIT_DESCRIBE_FORMAT_OPTIONS_VERSION 1 +#define GIT_DESCRIBE_FORMAT_OPTIONS_INIT { \ + GIT_DESCRIBE_FORMAT_OPTIONS_VERSION, \ + GIT_DESCRIBE_DEFAULT_ABBREVIATED_SIZE, \ + } + +typedef struct git_describe_result git_describe_result; GIT_EXTERN(int) git_describe_commit( - git_buf *out, + git_describe_result **result, git_object *committish, git_describe_opts *opts); +GIT_EXTERN(int) git_describe_format(git_buf *out, const git_describe_result *result, const git_describe_format_options *opts); + +GIT_EXTERN(void) git_describe_result_free(git_describe_result *result); + /** @} */ GIT_END_DECL -- cgit v1.2.3 From fd8126e4c605e749ed6ab1e31ac32366adc8cc8f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20Mart=C3=ADn=20Nieto?= Date: Tue, 30 Sep 2014 08:54:52 +0200 Subject: describe: implement describing the workdir When we describe the workdir, we perform a describe on HEAD and then check to see if the worktree is dirty. If it is and we have a suffix string, we append that to the buffer. --- include/git2/describe.h | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'include') diff --git a/include/git2/describe.h b/include/git2/describe.h index 6007b004e..8b80e1806 100644 --- a/include/git2/describe.h +++ b/include/git2/describe.h @@ -75,6 +75,11 @@ GIT_EXTERN(int) git_describe_commit( git_object *committish, git_describe_opts *opts); +GIT_EXTERN(int) git_describe_workdir( + git_describe_result **out, + git_repository *repo, + git_describe_opts *opts); + GIT_EXTERN(int) git_describe_format(git_buf *out, const git_describe_result *result, const git_describe_format_options *opts); GIT_EXTERN(void) git_describe_result_free(git_describe_result *result); -- cgit v1.2.3 From 25345c0cbe1493d63bbc9d309d7fcf0f84df741b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20Mart=C3=ADn=20Nieto?= Date: Tue, 30 Sep 2014 09:18:22 +0200 Subject: describe: rename git_describe_opts to git_describe_options And implement the option init functions for this and the format options. --- include/git2/describe.h | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) (limited to 'include') diff --git a/include/git2/describe.h b/include/git2/describe.h index 8b80e1806..bdbdfcfff 100644 --- a/include/git2/describe.h +++ b/include/git2/describe.h @@ -32,9 +32,9 @@ typedef enum { * 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; + * git_describe_options opts = GIT_DESCRIBE_OPTIONS_INIT; */ -typedef struct git_describe_opts { +typedef struct git_describe_options { unsigned int version; unsigned int max_candidates_tags; /** default: 10 */ @@ -42,7 +42,7 @@ typedef struct git_describe_opts { const char *pattern; int only_follow_first_parent; int show_commit_oid_as_fallback; -} git_describe_opts; +} git_describe_options; #define GIT_DESCRIBE_DEFAULT_MAX_CANDIDATES_TAGS 10 #define GIT_DESCRIBE_DEFAULT_ABBREVIATED_SIZE 7 @@ -53,6 +53,8 @@ typedef struct git_describe_opts { GIT_DESCRIBE_DEFAULT_MAX_CANDIDATES_TAGS, \ } +GIT_EXTERN(int) git_describe_init_options(git_describe_options *opts, unsigned int version); + typedef struct { unsigned int version; @@ -68,17 +70,19 @@ typedef struct { GIT_DESCRIBE_DEFAULT_ABBREVIATED_SIZE, \ } +GIT_EXTERN(int) git_describe_init_format_options(git_describe_format_options *opts, unsigned int version); + typedef struct git_describe_result git_describe_result; GIT_EXTERN(int) git_describe_commit( git_describe_result **result, git_object *committish, - git_describe_opts *opts); + git_describe_options *opts); GIT_EXTERN(int) git_describe_workdir( git_describe_result **out, git_repository *repo, - git_describe_opts *opts); + git_describe_options *opts); GIT_EXTERN(int) git_describe_format(git_buf *out, const git_describe_result *result, const git_describe_format_options *opts); -- cgit v1.2.3 From a3b9270dcfe61ce3429f82b514b302667d05bfc5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20Mart=C3=ADn=20Nieto?= Date: Tue, 30 Sep 2014 09:32:24 +0200 Subject: describe: document the API --- include/git2/describe.h | 74 +++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 71 insertions(+), 3 deletions(-) (limited to 'include') diff --git a/include/git2/describe.h b/include/git2/describe.h index bdbdfcfff..66b88c4fa 100644 --- a/include/git2/describe.h +++ b/include/git2/describe.h @@ -20,6 +20,13 @@ */ GIT_BEGIN_DECL +/** + * Reference lookup strategy + * + * These behave like the --tags and --all optios to git-describe, + * namely they say to look for any reference in either refs/tags/ or + * refs/ respectively. + */ typedef enum { GIT_DESCRIBE_DEFAULT, GIT_DESCRIBE_TAGS, @@ -29,8 +36,8 @@ typedef enum { /** * Describe options structure * - * Zero out for defaults. Initialize with `GIT_DESCRIBE_OPTIONS_INIT` macro to - * correctly set the `version` field. E.g. + * Initialize with `GIT_DESCRIBE_OPTIONS_INIT` macro to correctly set + * the `version` field. E.g. * * git_describe_options opts = GIT_DESCRIBE_OPTIONS_INIT; */ @@ -40,7 +47,17 @@ typedef struct git_describe_options { unsigned int max_candidates_tags; /** default: 10 */ unsigned int describe_strategy; /** default: GIT_DESCRIBE_DEFAULT */ const char *pattern; + /** + * When calculating the distance from the matching tag or + * reference, only walk down the first-parent ancestry. + */ int only_follow_first_parent; + /** + * If no matching tag or reference is found, the describe + * operation would normally fail. If this option is set, it + * will instead fall back to showing the full id of the + * commit. + */ int show_commit_oid_as_fallback; } git_describe_options; @@ -55,12 +72,28 @@ typedef struct git_describe_options { GIT_EXTERN(int) git_describe_init_options(git_describe_options *opts, unsigned int version); +/** + * Options for formatting the describe string + */ typedef struct { unsigned int version; + /** + * Size of the abbreviated commit id to use. This value is the + * lower bound for the length of the abbreviated string. The + * default is 7. + */ unsigned int abbreviated_size; + /** + * Set to use the long format even when a shorter name could be used. + */ int always_use_long_format; + + /** + * If the workdir is dirty and this is set, this string will + * be appended to the description string. + */ char *dirty_suffix; } git_describe_format_options; @@ -74,18 +107,53 @@ GIT_EXTERN(int) git_describe_init_format_options(git_describe_format_options *op typedef struct git_describe_result git_describe_result; +/** + * Describe a commit + * + * Perform the describe operation on the given committish object. + * + * @param result pointer to store the result. You must free this once + * you're done with it. + * @param committish a committish to describe + * @param opts the lookup options + */ GIT_EXTERN(int) git_describe_commit( git_describe_result **result, git_object *committish, git_describe_options *opts); +/** + * Describe a commit + * + * Perform the describe operation on the current commit and the + * worktree. After peforming describe on HEAD, a status is run and the + * description is considered to be dirty if there are. + * + * @param result pointer to store the result. You must free this once + * you're done with it. + * @param repo the repository in which to perform the describe + * @param opts the lookup options + */ GIT_EXTERN(int) git_describe_workdir( git_describe_result **out, git_repository *repo, git_describe_options *opts); -GIT_EXTERN(int) git_describe_format(git_buf *out, const git_describe_result *result, const git_describe_format_options *opts); +/** + * Print the describe result to a buffer + * + * @param result the result from `git_describe_commit()` or + * `git_describe_workdir()`. + * @param opt the formatting options + */ +GIT_EXTERN(int) git_describe_format( + git_buf *out, + const git_describe_result *result, + const git_describe_format_options *opts); +/** + * Free the describe result. + */ GIT_EXTERN(void) git_describe_result_free(git_describe_result *result); /** @} */ -- cgit v1.2.3