login
Search
Hi, I'm trying to run git-describe on the open-iscsi git tree (git://git.kernel.org/pub/scm/linux/kernel/git/mnc/open-iscsi.git): [erez.zilber@erez-lx:/tmp/open-iscsi.git]$ git-branch -a * master origin/2.0-869-bugfix origin/HEAD origin/bnx2i origin/cxgb3i origin/master [erez.zilber@erez-lx:/tmp/open-iscsi.git]$ git-describe 2.0-868-rc1-81-g31c9d42 However, there are newer tags than 2.0-868-rc1: [erez.zilber@erez-lx:/tmp/open-iscsi.git]$ git-tag 2.0-868-rc1 2.0-869 2.0-869-rc2 2.0-869-rc3 2.0-869-rc4 2.0-869.1 2.0-869.2 2.0-870-rc1 From what I see in the man page "git-describe - Show the most recent tag that is reachable from a commit". In this repository, it doesn't look like that... Now, I switch to the "2.0-869-bugfix" branch: [erez.zilber@erez-lx:/tmp/open-iscsi.git]$ git-checkout -b 2.0-869-bugfix origin/2.0-869-bugfix Branch 2.0-869-bugfix set up to track remote branch refs/remotes/origin/2.0-869-bugfix. Switched to a new branch "2.0-869-bugfix" and running again git-describe: [erez.zilber@erez-lx:/tmp/open-iscsi.git]$ git-describe 2.0-868-rc1-33-g81133dd Only if I use the --tags flag, I get what I expected: [erez.zilber@erez-lx:/tmp/open-iscsi.git]$ git-describe --tags 2.0-869.2 Why is this happening? Thanks, Erez --
--tags
Instead of using only the annotated tags, use any tag found in
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.git/refs/tags.
--=20
=C2=B7O=C2=B7 Pierre Habouzit
=C2=B7=C2=B7O madcoder@debia=
n.org
OOO http://www.madism.org
I'm not sure that I understand the difference between tags and annotated tags. Anyway, if I move to the master branch, I see the following tags: [erez.zilber@erez-lx:/tmp/open-iscsi.git]$ ls .git/refs/tags/ 2.0-868-rc1 2.0-869 2.0-869.1 2.0-869.2 2.0-869-rc2 2.0-869-rc3 2.0-869-rc4 2.0-870-rc1 [erez.zilber@erez-lx:/tmp/open-iscsi.git]$ git-tag 2.0-868-rc1 2.0-869 2.0-869-rc2 2.0-869-rc3 2.0-869-rc4 2.0-869.1 2.0-869.2 2.0-870-rc1 However: [erez.zilber@erez-lx:/tmp/open-iscsi.git]$ git-describe --tags 2.0-868-rc1-81-g31c9d42 I was expecting to see 2.0-870-rc1 here. Erez --
tags.
a lightweight tag is just a reference. an annotated tag has a message
associated. Usually tags are meant as local help, whereas annotated tags
are the ones pushed to the repositories and that never change. That's
why many tools ignore non annotated tags by default unless you pass
That's because master is not at -rc1 exactly, but some commits
afterwards. Please read the git-describe manpage fully, it's _really_
well explained:
The command finds the most recent tag that is reachable from a commi=
t.
If the tag points to the commit, then only the tag is shown. Otherwi=
se,
it suffixes the tag name with the number of additional commits on top
of the tagged object and the abbreviated object name of the most rec=
ent
commit.
Which means that your master is 81 commits ahead of the exact 2.0-860-rc1 t=
ag,
at sha1 31c9d42
--=20
=C2=B7O=C2=B7 Pierre Habouzit
=C2=B7=C2=B7O madcoder@debia=
n.org
OOO http://www.madism.org
Scratch my previous answer, I was confused with too many digits (868 vs 870). In fact looking at the code, if there is an annotated tag in the ancestry, git describe will always prefer it to lightweight tags. the problem with lightweight tags is that they are meant to be moved, hence are not really something you want to base on to chose a uuid (which git-describe generates). --=20 =C2=B7O=C2=B7 Pierre Habouzit =C2=B7=C2=B7O madcoder@debia= n.org OOO http://www.madism.org
Signed-off-by: Pierre Habouzit <madcoder@debian.org> --- Documentation/git-describe.txt | 3 ++- 1 files changed, 2 insertions(+), 1 deletions(-) diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index c4dbc2a..9cc8c2f 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -30,7 +30,8 @@ OPTIONS =20 --tags:: Instead of using only the annotated tags, use any tag - found in `.git/refs/tags`. + found in `.git/refs/tags`. Though if an annotated tag is found in the + ancestry, it will always be preferred to lightweight tags. =20 --contains:: Instead of finding the tag that predates the commit, find --=20 1.6.0.2.516.g12936.dirty
As technically correct as the statement is, I read this and go "why do we even have --tags?". If I read builtin-describe.c right we only honor --tags on an exact match, or if there are no annotated tags at all in the history. I wonder if docs like this aren't better for --tags: --tags:: If a lightweight tag exactly matches, output it. If no annotated tag is found in the ancestry but a lightweight tag is found, output the lightweight tag. ? -- Shawn. --
sounds better indeed. --=20 =C2=B7O=C2=B7 Pierre Habouzit =C2=B7=C2=B7O madcoder@debia= n.org OOO http://www.madism.org
If the caller supplies --tags they want the lightweight, unannotated
tags to be searched for a match. If a lightweight tag is closer
in the history, it should be matched, even if an annotated tag is
reachable further back in the commit chain.
The same applies with --all when matching any other type of ref.
Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
---
This come out of the discussions earlier last week, where folks
were confused about the meaning of --tags and wanted to see it
behave as they expected, which was to match the nearest tag,
no matter its "type".
The code is unchanged from what I sent out before, but now it has
updated test vectors and a commit message.
Thoughts?
builtin-describe.c | 6 ++----
t/t6120-describe.sh | 8 ++++----
2 files changed, 6 insertions(+), 8 deletions(-)
diff --git a/builtin-describe.c b/builtin-describe.c
index ec404c8..fd54fec 100644
--- a/builtin-describe.c
+++ b/builtin-describe.c
@@ -15,8 +15,8 @@ static const char * const describe_usage[] = {
};
static int debug; /* Display lots of verbose info */
-static int all; /* Default to annotated tags only */
-static int tags; /* But allow any tags if --tags is specified */
+static int all; /* Any valid ref can be used */
+static int tags; /* Either lightweight or annotated tags */
static int longformat;
static int abbrev = DEFAULT_ABBREV;
static int max_candidates = 10;
@@ -112,8 +112,6 @@ static int compare_pt(const void *a_, const void *b_)
{
struct possible_tag *a = (struct possible_tag *)a_;
struct possible_tag *b = (struct possible_tag *)b_;
- if (a->name->prio != b->name->prio)
- return b->name->prio - a->name->prio;
if (a->depth != b->depth)
return a->depth - b->depth;
if (a->found_order != b->found_order)
diff --git a/t/t6120-describe.sh b/t/t6120-describe.sh
index 16cc635..e6c9e59 100755
--- a/t/t6120-describe.sh
+++ b/t/t6120-describe.sh
@@ -91,10 +91,10 @@ check_describe D-* HEAD^^
check_describe A-* HEAD^^2
...I would like to see an enhanced information in the documentation so that people remember that lightweight tags are not meant to be constant over time and that's a bad idea to use them. What the discussion showed, is that the people don't know about annotated tags, and git-describe should have a stub of documentation that points to git-tag(1) so that people learn about it. Apart from that, it feels fine. --=20 =C2=B7O=C2=B7 Pierre Habouzit =C2=B7=C2=B7O madcoder@debia= n.org OOO http://www.madism.org
The primary mode of operation without --tags of "describe" is about coming up with version numbers, and as such, it should try to base its output on immutable anchors as much as possible. For that reason, I think it should use "tag " line from the tag object, not the name of the ref, to describe the committish. They should match (otherwise fsck would say something about it) in practice, though... The patch is about --tags, which is not about such a strict "version number" generation, but about "come up with a closest ref", so in that light it feels perfectly fine. --
FWIW the use of "tag " line for an annotated tag being output is what 212945d4 (Teach git-describe to verify annotated tag names before output) was all about. That has been in tree since v1.5.5-rc0~86^2. So we already are doing (have been doing) exactly what you are asking for. Or did I misunderstand you? -- Shawn. --
If the caller supplies --tags they want the lightweight, unannotated tags to be searched for a match. If a lightweight tag is closer in the history, it should be matched, even if an annotated tag is reachable further back in the commit chain. The same applies with --all when matching any other type of ref. Signed-off-by: Shawn O. Pearce <spearce@spearce.org> Acked-By: Uwe Kleine-K�nig <ukleinek@strlen.de> --- Changes since v1 of this patch: - Documentation updates were added. - Comment for "tags" flag modified per Uwe's suggestion. Documentation/git-describe.txt | 9 +++++++-- builtin-describe.c | 6 ++---- t/t6120-describe.sh | 8 ++++---- 3 files changed, 13 insertions(+), 10 deletions(-) diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index c4dbc2a..40e061f 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -18,6 +18,9 @@ shown. Otherwise, it suffixes the tag name with the number of additional commits on top of the tagged object and the abbreviated object name of the most recent commit. +By default (without --all or --tags) `git describe` only shows +annotated tags. For more information about creating annoated tags +see the -a and -s options to linkgit:git-tag[1]. OPTIONS ------- @@ -26,11 +29,13 @@ OPTIONS --all:: Instead of using only the annotated tags, use any ref - found in `.git/refs/`. + found in `.git/refs/`. This option enables matching + any known branch, remote branch, or lightweight tag. --tags:: Instead of using only the annotated tags, use any tag - found in `.git/refs/tags`. + found in `.git/refs/tags`. This option enables matching + a lightweight (non-annotated) tag. --contains:: Instead of finding the tag that predates the commit, find diff --git a/builtin-describe.c b/builtin-describe.c index ec404c8..d2cfb1b 100644 --- a/builtin-describe.c +++ b/builtin-describe.c @@ -15,8 +15,8 @@ static const char * ...
In 99% of the cases, "--all" will then give back the currently checked out branch unless a revision is specified, right? -- Andreas Ericsson andreas.ericsson@op5.se OP5 AB www.op5.se Tel: +46 8-230225 Fax: +46 8-230231 --
Yup. `git describe --all` or `git describe --all HEAD` would kick back the current branch you have checked out, assuming you have a real branch under refs/heads and not some detached HEAD. IMHO, that's what the user asked for. -- Shawn. --
True. I think this will raise questions of its usability though, in particular if it considers remote branches too. Otoh, I've never seen the use for "git describe --all" earlier either, so I guess I think differently from those who want this feature. -- Andreas Ericsson andreas.ericsson@op5.se OP5 AB www.op5.se Tel: +46 8-230225 Fax: +46 8-230231 --
Maybe the last comment should better read: /* allow lightweight tags */ ? Apart from this one nitpick: Acked-By: Uwe Kleine-König <ukleinek@strlen.de> Thanks Uwe --
Hello, IMHO --tags should behave as Erez expected (because it's what I expected, too). As --tags currently behaves it's only usable in very rare cases (most of the time it only makes a difference on repos without any annotated tag). When do you pass --tags? Only if a lightweight tag is OK for an answer. And then I would prefer a "near" lightweight tag to a "farer" annotated one. Best regards Uwe --
The reason lightweight tags aren't considered is that they're often put somewhere to just mark some refs one wants to keep around, or as a sort of movable snapshot marker (we have "latest/build", "latest/tested" etc as lightweight tags). It's nifty to use lw tags for that since they can't be committed to by accident. That doesn't mean we want 'git describe' to start outputting "latest-build" whenever we want to pull a version number from it though. This was especially true before the creation of "git stash" and the reflog, but quite a lot of people still use them for similar purposes. In short; "git describe" output stays the way it is, or things will start unexpectedly breaking for quite a lot of people. -- Andreas Ericsson andreas.ericsson@op5.se OP5 AB www.op5.se Tel: +46 8-230225 Fax: +46 8-230231 --
I don't disagree. I've been tempted to write a patch to change the
behavior of git-describe so that --tags and --all control what names
are inserted into the candidate list, but don't control the ordering
of their selection.
I think this is all that is needed to make the behavior do what you
and Erez expected. But its a pretty big change in the results if
you are passing in --all or --tags today.
--8<--
[WIP] Change meaning of --tags and --all
---
builtin-describe.c | 6 ++----
1 files changed, 2 insertions(+), 4 deletions(-)
diff --git a/builtin-describe.c b/builtin-describe.c
index ec404c8..fd54fec 100644
--- a/builtin-describe.c
+++ b/builtin-describe.c
@@ -15,8 +15,8 @@ static const char * const describe_usage[] = {
};
static int debug; /* Display lots of verbose info */
-static int all; /* Default to annotated tags only */
-static int tags; /* But allow any tags if --tags is specified */
+static int all; /* Any valid ref can be used */
+static int tags; /* Either lightweight or annotated tags */
static int longformat;
static int abbrev = DEFAULT_ABBREV;
static int max_candidates = 10;
@@ -112,8 +112,6 @@ static int compare_pt(const void *a_, const void *b_)
{
struct possible_tag *a = (struct possible_tag *)a_;
struct possible_tag *b = (struct possible_tag *)b_;
- if (a->name->prio != b->name->prio)
- return b->name->prio - a->name->prio;
if (a->depth != b->depth)
return a->depth - b->depth;
if (a->found_order != b->found_order)
--
1.6.0.2.513.g6dbd
--
Shawn.
--
Hi Shawn, But it matches the documentation, and the expectations of Erez, me and (at least initially) Pierre. My POV is still: If you pass --all or --tags you have to be able to Mmmh, IMHO the comment for tags is misleading, its either annotated only or both. Best regards and thanks, Uwe --
I was agreeing with you. I've long felt that the --tags and --all behavior of git-describe was wrong. But something in the back of my mind tells me Junio felt otherwise. Its a change in behavior. Today users are getting annotated tags back from `git describe --tags` even if lightweight tags are closer. Once this code change is in they'll start to get lightweight tags. Previously `git describe --tags` never gave a lightweight tag if there was at least one annotated tag in the history. Now it will start to give the lightweight tags. Some users may see that as a Oh, yes, right. Thanks. I'll clean it up. -- Shawn. --
Hi Shawn, Right, and previously `git describe` didn't differ from `git describe --tags` in the presence of at least one annotated tag. This is the main I didn't get why the "dashless" change is relevant here. IMHO this one is/was harder for the user because it changed every command, and they had to start using bash completion if they didn't before. This one should only hurt the users of "git describe --tags", and I assume there are not that many. Still more as the documentation describes the behaviour the patch implements. Best regards Uwe --
I read that, but I still don't understand what happens in the open-iscsi tree: [erez.zilber@erez-lx:/tmp/open-iscsi.git]$ cat .git/refs/tags/2.0-870-rc1 5e80c8167c112687ae7b30b1e40af6f03088c56c The head is 12 commits from the 2.0-870-rc1 tag. Therefore, I expected to see something like 2.0-870-rc1-12-some_hash (not 2.0-868-rc1-81-g31c9d42). Erez --
An annotated tag is one created with "git tag -a" or "git tag -s". Other tags are considered "lightweight". They are supported for creating immutable quick-and-dirty savepoints for private use, while published tags are supposed to be annotated to give them some extra weight. You can use lightweight tags like normal tags (ie, and publish them), but then some assumptions in git will not be correct and you need to tell it so. Btw, the default update hook prevents lightweight (unannotated) tags from entering a repository you're pushing to, so this assumption is not something that's unique to just "describe". -- Andreas Ericsson andreas.ericsson@op5.se OP5 AB www.op5.se Tel: +46 8-230225 Fax: +46 8-230231 --
| Greg KH | Og dreams of kernels |
| Jens Axboe | [PATCH 31/33] Fusion: sg chaining support |
| Arnd Bergmann | Re: finding your own dead "CONFIG_" variables |
| Mark Brown | [PATCH 2/2] Subject: natsemi: Allow users to disable workaround for DspCfg reset |
| Tony Breeds | [LGUEST] Look in object dir for .config |
git: | |
| Brian Downing | Re: Git in a Nutshell guide |
| John Benes | Re: master has some toys |
| Matthias Lederhofer | [PATCH 4/7] introduce GIT_WORK_TREE to specify the work tree |
| Alexander Sulfrian | [RFC/PATCH] RE: git calls SSH_ASKPASS even if DISPLAY is not set |
| Junio C Hamano | Re: Rss produced by git is not valid xml? |
| Linux Kernel Mailing List | iSeries: fix section mismatch in iseries_veth |
| Linux Kernel Mailing List | ixbge: remove TX lock and redo TX accounting. |
| Linux Kernel Mailing List | ixgbe: fix several counter register errata |
| Linux Kernel Mailing List | b43: fix build with CONFIG_SSB_PCIHOST=n |
| Linux Kernel Mailing List | 9p: block-based virtio client |