Edit File by line

[0] Fix | Delete

[1] Fix | Delete

[2] Fix | Delete

* This file is part of libgit2, distributed under the GNU GPL v2 with

[3] Fix | Delete

* a Linking Exception. For full terms see the included COPYING file.

[4] Fix | Delete

[5] Fix | Delete

#ifndef INCLUDE_git_describe_h__

[6] Fix | Delete

#define INCLUDE_git_describe_h__

[7] Fix | Delete

[8] Fix | Delete

#include "common.h"

[9] Fix | Delete

#include "types.h"

[10] Fix | Delete

#include "buffer.h"

[11] Fix | Delete

[12] Fix | Delete

/**

[13] Fix | Delete

* @file git2/describe.h

[14] Fix | Delete

* @brief Git describing routines

[15] Fix | Delete

* @defgroup git_describe Git describing routines

[16] Fix | Delete

* @ingroup Git

[17] Fix | Delete

* @{

[18] Fix | Delete

[19] Fix | Delete

GIT_BEGIN_DECL

[20] Fix | Delete

[21] Fix | Delete

/**

[22] Fix | Delete

* Reference lookup strategy

[23] Fix | Delete

[24] Fix | Delete

* These behave like the --tags and --all options to git-describe,

[25] Fix | Delete

* namely they say to look for any reference in either refs/tags/ or

[26] Fix | Delete

* refs/ respectively.

[27] Fix | Delete

[28] Fix | Delete

typedef enum {

[29] Fix | Delete

GIT_DESCRIBE_DEFAULT,

[30] Fix | Delete

GIT_DESCRIBE_TAGS,

[31] Fix | Delete

GIT_DESCRIBE_ALL,

[32] Fix | Delete

} git_describe_strategy_t;

[33] Fix | Delete

[34] Fix | Delete

/**

[35] Fix | Delete

* Describe options structure

[36] Fix | Delete

[37] Fix | Delete

* Initialize with `GIT_DESCRIBE_OPTIONS_INIT`. Alternatively, you can

[38] Fix | Delete

* use `git_describe_options_init`.

[39] Fix | Delete

[40] Fix | Delete

[41] Fix | Delete

typedef struct git_describe_options {

[42] Fix | Delete

unsigned int version;

[43] Fix | Delete

[44] Fix | Delete

unsigned int max_candidates_tags; /**< default: 10 */

[45] Fix | Delete

unsigned int describe_strategy; /**< default: GIT_DESCRIBE_DEFAULT */

[46] Fix | Delete

const char *pattern;

[47] Fix | Delete

/**

[48] Fix | Delete

* When calculating the distance from the matching tag or

[49] Fix | Delete

* reference, only walk down the first-parent ancestry.

[50] Fix | Delete

[51] Fix | Delete

int only_follow_first_parent;

[52] Fix | Delete

/**

[53] Fix | Delete

* If no matching tag or reference is found, the describe

[54] Fix | Delete

* operation would normally fail. If this option is set, it

[55] Fix | Delete

* will instead fall back to showing the full id of the

[56] Fix | Delete

* commit.

[57] Fix | Delete

[58] Fix | Delete

int show_commit_oid_as_fallback;

[59] Fix | Delete

} git_describe_options;

[60] Fix | Delete

[61] Fix | Delete

#define GIT_DESCRIBE_DEFAULT_MAX_CANDIDATES_TAGS 10

[62] Fix | Delete

#define GIT_DESCRIBE_DEFAULT_ABBREVIATED_SIZE 7

[63] Fix | Delete

[64] Fix | Delete

#define GIT_DESCRIBE_OPTIONS_VERSION 1

[65] Fix | Delete

#define GIT_DESCRIBE_OPTIONS_INIT { \

[66] Fix | Delete

GIT_DESCRIBE_OPTIONS_VERSION, \

[67] Fix | Delete

GIT_DESCRIBE_DEFAULT_MAX_CANDIDATES_TAGS, \

[68] Fix | Delete

}

[69] Fix | Delete

[70] Fix | Delete

/**

[71] Fix | Delete

* Initialize git_describe_options structure

[72] Fix | Delete

[73] Fix | Delete

* Initializes a `git_describe_options` with default values. Equivalent to creating

[74] Fix | Delete

* an instance with GIT_DESCRIBE_OPTIONS_INIT.

[75] Fix | Delete

[76] Fix | Delete

* @param opts The `git_describe_options` struct to initialize.

[77] Fix | Delete

* @param version The struct version; pass `GIT_DESCRIBE_OPTIONS_VERSION`.

[78] Fix | Delete

* @return Zero on success; -1 on failure.

[79] Fix | Delete

[80] Fix | Delete

GIT_EXTERN(int) git_describe_options_init(git_describe_options *opts, unsigned int version);

[81] Fix | Delete

[82] Fix | Delete

/**

[83] Fix | Delete

* Describe format options structure

[84] Fix | Delete

[85] Fix | Delete

* Initialize with `GIT_DESCRIBE_FORMAT_OPTIONS_INIT`. Alternatively, you can

[86] Fix | Delete

* use `git_describe_format_options_init`.

[87] Fix | Delete

[88] Fix | Delete

[89] Fix | Delete

typedef struct {

[90] Fix | Delete

unsigned int version;

[91] Fix | Delete

[92] Fix | Delete

/**

[93] Fix | Delete

* Size of the abbreviated commit id to use. This value is the

[94] Fix | Delete

* lower bound for the length of the abbreviated string. The

[95] Fix | Delete

* default is 7.

[96] Fix | Delete

[97] Fix | Delete

unsigned int abbreviated_size;

[98] Fix | Delete

[99] Fix | Delete

/**

[100] Fix | Delete

* Set to use the long format even when a shorter name could be used.

[101] Fix | Delete

[102] Fix | Delete

int always_use_long_format;

[103] Fix | Delete

[104] Fix | Delete

/**

[105] Fix | Delete

* If the workdir is dirty and this is set, this string will

[106] Fix | Delete

* be appended to the description string.

[107] Fix | Delete

[108] Fix | Delete

const char *dirty_suffix;

[109] Fix | Delete

} git_describe_format_options;

[110] Fix | Delete

[111] Fix | Delete

#define GIT_DESCRIBE_FORMAT_OPTIONS_VERSION 1

[112] Fix | Delete

#define GIT_DESCRIBE_FORMAT_OPTIONS_INIT { \

[113] Fix | Delete

GIT_DESCRIBE_FORMAT_OPTIONS_VERSION, \

[114] Fix | Delete

GIT_DESCRIBE_DEFAULT_ABBREVIATED_SIZE, \

[115] Fix | Delete

}

[116] Fix | Delete

[117] Fix | Delete

/**

[118] Fix | Delete

* Initialize git_describe_format_options structure

[119] Fix | Delete

[120] Fix | Delete

* Initializes a `git_describe_format_options` with default values. Equivalent to creating

[121] Fix | Delete

* an instance with GIT_DESCRIBE_FORMAT_OPTIONS_INIT.

[122] Fix | Delete

[123] Fix | Delete

* @param opts The `git_describe_format_options` struct to initialize.

[124] Fix | Delete

* @param version The struct version; pass `GIT_DESCRIBE_FORMAT_OPTIONS_VERSION`.

[125] Fix | Delete

* @return Zero on success; -1 on failure.

[126] Fix | Delete

[127] Fix | Delete

GIT_EXTERN(int) git_describe_format_options_init(git_describe_format_options *opts, unsigned int version);

[128] Fix | Delete

[129] Fix | Delete

/**

[130] Fix | Delete

* A struct that stores the result of a describe operation.

[131] Fix | Delete

[132] Fix | Delete

typedef struct git_describe_result git_describe_result;

[133] Fix | Delete

[134] Fix | Delete

/**

[135] Fix | Delete

* Describe a commit

[136] Fix | Delete

[137] Fix | Delete

* Perform the describe operation on the given committish object.

[138] Fix | Delete

[139] Fix | Delete

* @param result pointer to store the result. You must free this once

[140] Fix | Delete

* you're done with it.

[141] Fix | Delete

* @param committish a committish to describe

[142] Fix | Delete

* @param opts the lookup options (or NULL for defaults)

[143] Fix | Delete

[144] Fix | Delete

GIT_EXTERN(int) git_describe_commit(

[145] Fix | Delete

git_describe_result **result,

[146] Fix | Delete

git_object *committish,

[147] Fix | Delete

git_describe_options *opts);

[148] Fix | Delete

[149] Fix | Delete

/**

[150] Fix | Delete

* Describe a commit

[151] Fix | Delete

[152] Fix | Delete

* Perform the describe operation on the current commit and the

[153] Fix | Delete

* worktree. After peforming describe on HEAD, a status is run and the

[154] Fix | Delete

* description is considered to be dirty if there are.

[155] Fix | Delete

[156] Fix | Delete

* @param out pointer to store the result. You must free this once

[157] Fix | Delete

* you're done with it.

[158] Fix | Delete

* @param repo the repository in which to perform the describe

[159] Fix | Delete

* @param opts the lookup options (or NULL for defaults)

[160] Fix | Delete

[161] Fix | Delete

GIT_EXTERN(int) git_describe_workdir(

[162] Fix | Delete

git_describe_result **out,

[163] Fix | Delete

git_repository *repo,

[164] Fix | Delete

git_describe_options *opts);

[165] Fix | Delete

[166] Fix | Delete

/**

[167] Fix | Delete

* Print the describe result to a buffer

[168] Fix | Delete

[169] Fix | Delete

* @param out The buffer to store the result

[170] Fix | Delete

* @param result the result from `git_describe_commit()` or

[171] Fix | Delete

* `git_describe_workdir()`.

[172] Fix | Delete

* @param opts the formatting options (or NULL for defaults)

[173] Fix | Delete

[174] Fix | Delete

GIT_EXTERN(int) git_describe_format(

[175] Fix | Delete

git_buf *out,

[176] Fix | Delete

const git_describe_result *result,

[177] Fix | Delete

const git_describe_format_options *opts);

[178] Fix | Delete

[179] Fix | Delete

/**

[180] Fix | Delete

* Free the describe result.

[181] Fix | Delete

[182] Fix | Delete

GIT_EXTERN(void) git_describe_result_free(git_describe_result *result);

[183] Fix | Delete

[184] Fix | Delete

/** @} */

[185] Fix | Delete

GIT_END_DECL

[186] Fix | Delete

[187] Fix | Delete

#endif

[188] Fix | Delete

[189] Fix | Delete