Update describe documentation.
[git/git.git] / builtin-describe.c
CommitLineData
908e5310
LT
1#include "cache.h"
2#include "commit.h"
635d4134 3#include "tag.h"
908e5310 4#include "refs.h"
9a0eaf83 5#include "builtin.h"
908e5310 6
8713ab30
SP
7#define SEEN (1u<<0)
8#define MAX_TAGS (FLAG_BITS - 1)
9
2d9e7c9f
JH
10static const char describe_usage[] =
11"git-describe [--all] [--tags] [--abbrev=<n>] <committish>*";
908e5310 12
8713ab30 13static int debug; /* Display lots of verbose info */
96f1e58f
DR
14static int all; /* Default to annotated tags only */
15static int tags; /* But allow any tags if --tags is specified */
2d9e7c9f 16static int abbrev = DEFAULT_ABBREV;
8713ab30 17static int max_candidates = 10;
908e5310 18
e7eb5034 19struct commit_name {
64deb858 20 int prio; /* annotated tag = 2, tag = 1, head = 0 */
5a2282de 21 char path[FLEX_ARRAY]; /* more */
e7eb5034 22};
cf69fd49
SP
23static const char *prio_names[] = {
24 "head", "lightweight", "annotated",
25};
908e5310 26
64deb858 27static void add_to_known_names(const char *path,
80dbae03 28 struct commit *commit,
64deb858 29 int prio)
908e5310 30{
e7eb5034
SP
31 struct commit_name *e = commit->util;
32 if (!e || e->prio < prio) {
33 size_t len = strlen(path)+1;
34 free(e);
35 e = xmalloc(sizeof(struct commit_name) + len);
36 e->prio = prio;
37 memcpy(e->path, path, len);
38 commit->util = e;
908e5310 39 }
908e5310
LT
40}
41
8da19775 42static int get_name(const char *path, const unsigned char *sha1, int flag, void *cb_data)
908e5310
LT
43{
44 struct commit *commit = lookup_commit_reference_gently(sha1, 1);
64deb858
JH
45 struct object *object;
46 int prio;
47
908e5310
LT
48 if (!commit)
49 return 0;
64deb858 50 object = parse_object(sha1);
2d9e7c9f
JH
51 /* If --all, then any refs are used.
52 * If --tags, then any tags are used.
53 * Otherwise only annotated tags are used.
54 */
64deb858 55 if (!strncmp(path, "refs/tags/", 10)) {
1974632c 56 if (object->type == OBJ_TAG)
64deb858
JH
57 prio = 2;
58 else
59 prio = 1;
60 }
61 else
62 prio = 0;
63
635d4134 64 if (!all) {
64deb858
JH
65 if (!prio)
66 return 0;
67 if (!tags && prio < 2)
635d4134 68 return 0;
635d4134 69 }
64deb858 70 add_to_known_names(all ? path + 5 : path + 10, commit, prio);
908e5310
LT
71 return 0;
72}
73
80dbae03 74struct possible_tag {
80dbae03 75 struct commit_name *name;
cf69fd49
SP
76 int depth;
77 int found_order;
8713ab30 78 unsigned flag_within;
80dbae03
SP
79};
80
cf69fd49
SP
81static int compare_pt(const void *a_, const void *b_)
82{
83 struct possible_tag *a = (struct possible_tag *)a_;
84 struct possible_tag *b = (struct possible_tag *)b_;
85 if (a->name->prio != b->name->prio)
86 return b->name->prio - a->name->prio;
87 if (a->depth != b->depth)
88 return a->depth - b->depth;
89 if (a->found_order != b->found_order)
90 return a->found_order - b->found_order;
91 return 0;
92}
93
554fe20d 94static void describe(const char *arg, int last_one)
908e5310 95{
4c34a2c5 96 unsigned char sha1[20];
8713ab30 97 struct commit *cmit, *gave_up_on = NULL;
908e5310
LT
98 struct commit_list *list;
99 static int initialized = 0;
100 struct commit_name *n;
cf69fd49 101 struct possible_tag all_matches[MAX_TAGS];
8713ab30
SP
102 unsigned int match_cnt = 0, annotated_cnt = 0, cur_match;
103 unsigned long seen_commits = 0;
908e5310 104
31fff305
DL
105 if (get_sha1(arg, sha1))
106 die("Not a valid object name %s", arg);
4c34a2c5
JH
107 cmit = lookup_commit_reference(sha1);
108 if (!cmit)
31fff305 109 die("%s is not a valid '%s' object", arg, commit_type);
4c34a2c5 110
908e5310
LT
111 if (!initialized) {
112 initialized = 1;
cb5d709f 113 for_each_ref(get_name, NULL);
908e5310
LT
114 }
115
e7eb5034 116 n = cmit->util;
908e5310
LT
117 if (n) {
118 printf("%s\n", n->path);
119 return;
120 }
121
8713ab30
SP
122 if (debug)
123 fprintf(stderr, "searching to describe %s\n", arg);
124
908e5310 125 list = NULL;
8713ab30 126 cmit->object.flags = SEEN;
908e5310
LT
127 commit_list_insert(cmit, &list);
128 while (list) {
80dbae03 129 struct commit *c = pop_commit(&list);
dccd0c2a 130 struct commit_list *parents = c->parents;
8713ab30 131 seen_commits++;
e7eb5034 132 n = c->util;
908e5310 133 if (n) {
8713ab30
SP
134 if (match_cnt < max_candidates) {
135 struct possible_tag *t = &all_matches[match_cnt++];
136 t->name = n;
137 t->depth = seen_commits - 1;
138 t->flag_within = 1u << match_cnt;
8a8169c0 139 t->found_order = match_cnt;
8713ab30
SP
140 c->object.flags |= t->flag_within;
141 if (n->prio == 2)
142 annotated_cnt++;
143 }
144 else {
145 gave_up_on = c;
146 break;
147 }
148 }
149 for (cur_match = 0; cur_match < match_cnt; cur_match++) {
150 struct possible_tag *t = &all_matches[cur_match];
151 if (!(c->object.flags & t->flag_within))
152 t->depth++;
153 }
154 if (annotated_cnt && !list) {
155 if (debug)
156 fprintf(stderr, "finished search at %s\n",
157 sha1_to_hex(c->object.sha1));
158 break;
dccd0c2a
SP
159 }
160 while (parents) {
161 struct commit *p = parents->item;
162 parse_commit(p);
8713ab30 163 if (!(p->object.flags & SEEN))
dccd0c2a 164 insert_by_date(p, &list);
8713ab30 165 p->object.flags |= c->object.flags;
dccd0c2a 166 parents = parents->next;
80dbae03
SP
167 }
168 }
8713ab30 169 free_commit_list(list);
80dbae03 170
8713ab30 171 if (!match_cnt)
80dbae03
SP
172 die("cannot describe '%s'", sha1_to_hex(cmit->object.sha1));
173
cf69fd49 174 qsort(all_matches, match_cnt, sizeof(all_matches[0]), compare_pt);
8713ab30
SP
175 if (debug) {
176 for (cur_match = 0; cur_match < match_cnt; cur_match++) {
177 struct possible_tag *t = &all_matches[cur_match];
cf69fd49
SP
178 fprintf(stderr, " %-11s %8d %s\n",
179 prio_names[t->name->prio],
8713ab30
SP
180 t->depth, t->name->path);
181 }
182 fprintf(stderr, "traversed %lu commits\n", seen_commits);
183 if (gave_up_on) {
184 fprintf(stderr,
185 "more than %i tags found; listed %i most recent\n"
186 "gave up search at %s\n",
187 max_candidates, max_candidates,
188 sha1_to_hex(gave_up_on->object.sha1));
189 }
80dbae03 190 }
f127404c
AP
191 if (abbrev == 0)
192 printf("%s\n", all_matches[0].name->path );
193 else
237fb6ca
SP
194 printf("%s-%d-g%s\n", all_matches[0].name->path,
195 all_matches[0].depth,
196 find_unique_abbrev(cmit->object.sha1, abbrev));
80dbae03 197
8713ab30
SP
198 if (!last_one)
199 clear_commit_marks(cmit, -1);
908e5310
LT
200}
201
9a0eaf83 202int cmd_describe(int argc, const char **argv, const char *prefix)
908e5310
LT
203{
204 int i;
205
206 for (i = 1; i < argc; i++) {
207 const char *arg = argv[i];
908e5310 208
4c34a2c5
JH
209 if (*arg != '-')
210 break;
8713ab30
SP
211 else if (!strcmp(arg, "--debug"))
212 debug = 1;
4c34a2c5 213 else if (!strcmp(arg, "--all"))
908e5310 214 all = 1;
4c34a2c5 215 else if (!strcmp(arg, "--tags"))
2d9e7c9f 216 tags = 1;
4c34a2c5 217 else if (!strncmp(arg, "--abbrev=", 9)) {
2d9e7c9f 218 abbrev = strtoul(arg + 9, NULL, 10);
f127404c 219 if (abbrev != 0 && (abbrev < MINIMUM_ABBREV || 40 < abbrev))
2d9e7c9f 220 abbrev = DEFAULT_ABBREV;
2d9e7c9f 221 }
8713ab30
SP
222 else if (!strncmp(arg, "--candidates=", 13)) {
223 max_candidates = strtoul(arg + 13, NULL, 10);
224 if (max_candidates < 1)
225 max_candidates = 1;
226 else if (max_candidates > MAX_TAGS)
227 max_candidates = MAX_TAGS;
228 }
4c34a2c5 229 else
908e5310 230 usage(describe_usage);
908e5310 231 }
4c34a2c5 232
8c599c74 233 save_commit_buffer = 0;
8112894d 234
5b6df8e4 235 if (argc <= i)
fec9ebf1 236 describe("HEAD", 1);
4c34a2c5 237 else
fec9ebf1
JH
238 while (i < argc) {
239 describe(argv[i], (i == argc - 1));
240 i++;
241 }
4c34a2c5 242
908e5310
LT
243 return 0;
244}