From 30ffa60377acb443033045a42ffecefdb0921ebb Mon Sep 17 00:00:00 2001 From: Pierre Habouzit Date: Fri, 21 Dec 2007 22:49:54 +0100 Subject: git-describe: Add a --match option to limit considered tags. Signed-off-by: Pierre Habouzit Signed-off-by: Junio C Hamano --- Documentation/git-describe.txt | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'Documentation/git-describe.txt') diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index ac23e28f27..9c7a032342 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -51,6 +51,10 @@ OPTIONS being employed to standard error. The tag name will still be printed to standard out. +--match :: + Only consider tags matching the given pattern (can be used to avoid + leaking private tags made from the repository). + EXAMPLES -------- -- cgit v1.2.3 From 5162e69732d13dd079919a389a6ace8878aad716 Mon Sep 17 00:00:00 2001 From: Dan McGee Date: Sat, 29 Dec 2007 00:20:38 -0600 Subject: Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P\w(\w|-)*?):(?P\S*?)(\[(?P.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P(http|https|ftp|file|mailto|callto|image|link)):(?P\S*?)(\[(?P.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee Signed-off-by: Junio C Hamano --- Documentation/git-describe.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/git-describe.txt') diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index ac23e28f27..0742152b81 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -123,4 +123,4 @@ Documentation by David Greaves, Junio C Hamano and the git-list Date: Sun, 24 Feb 2008 03:07:31 -0500 Subject: Teach git-describe --exact-match to avoid expensive tag searches Sometimes scripts want (or need) the annotated tag name that exactly matches a specific commit, or no tag at all. In such cases it can be difficult to determine if the output of `git describe $commit` is a real tag name or a tag+abbreviated commit. A common idiom is to run git-describe twice: if test $(git describe $commit) = $(git describe --abbrev=0 $commit) ... but this is a huge waste of time if the caller is just going to pick a different method to describe $commit or abort because it is not exactly an annotated tag. Setting the maximum number of candidates to 0 allows the caller to ask for only a tag that directly points at the supplied commit, or to have git-describe abort if no such item exists. Signed-off-by: Shawn O. Pearce Signed-off-by: Junio C Hamano --- Documentation/git-describe.txt | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'Documentation/git-describe.txt') diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index 1c3dfb40c6..fbb40a2916 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -45,6 +45,11 @@ OPTIONS candidates to describe the input committish consider up to candidates. Increasing above 10 will take slightly longer but may produce a more accurate result. + An of 0 will cause only exact matches to be output. + +--exact-match:: + Only output exact matches (a tag directly references the + supplied commit). This is a synonym for --candidates=0. --debug:: Verbosely display information about the searching strategy -- cgit v1.2.3 From 518120e3487a00148f8001454f1e76e484442a22 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Santi=20B=C3=A9jar?= Date: Mon, 25 Feb 2008 10:43:33 +0100 Subject: git-describe: --long shows the object name even for a tagged commit MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This is useful when you want to see parts of the commit object name in "describe" output, even when the commit in question happens to be a tagged version. Instead of just emitting the tag name, it will describe such a commit as v1.2-0-deadbeef (0th commit since tag v1.2 that points at object deadbeef....). Signed-off-by: Santi Béjar Signed-off-by: Junio C Hamano --- Documentation/git-describe.txt | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'Documentation/git-describe.txt') diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index 1c3dfb40c6..270b808755 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -51,6 +51,15 @@ OPTIONS being employed to standard error. The tag name will still be printed to standard out. +--long:: + Always output the long format (the tag, the number of commits + and the abbreviated commit name) even when it matches a tag. + This is useful when you want to see parts of the commit object name + in "describe" output, even when the commit in question happens to be + a tagged version. Instead of just emitting the tag name, it will + describe such a commit as v1.2-0-deadbeef (0th commit since tag v1.2 + that points at object deadbeef....). + --match :: Only consider tags matching the given pattern (can be used to avoid leaking private tags made from the repository). -- cgit v1.2.3 From b7893cde53eb2834deb16820eccb709d2636b81b Mon Sep 17 00:00:00 2001 From: Ian Hilt Date: Wed, 14 May 2008 14:30:55 -0400 Subject: Documentation/git-describe.txt: make description more readable Signed-off-by: Ian Hilt Credit-to: Kevin Ballard Signed-off-by: Junio C Hamano --- Documentation/git-describe.txt | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'Documentation/git-describe.txt') diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index 0742152b81..5e88b6e79a 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -13,9 +13,10 @@ SYNOPSIS DESCRIPTION ----------- The command finds the most recent tag that is reachable from a -commit, and if the commit itself is pointed at by the tag, shows -the tag. Otherwise, it suffixes the tag name with the number of -additional commits and the abbreviated object name of the commit. +commit. If the tag points to the commit, then only the tag is +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. OPTIONS -- cgit v1.2.3 From 9e1f0a85c68323830ea117092c55192b17aa3ac8 Mon Sep 17 00:00:00 2001 From: Christian Couder Date: Fri, 6 Jun 2008 09:07:32 +0200 Subject: documentation: move git(7) to git(1) As the "git" man page describes the "git" command at the end-user level, it seems better to move it to man section 1. Signed-off-by: Christian Couder Signed-off-by: Junio C Hamano --- Documentation/git-describe.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/git-describe.txt') diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index 69e1ab750d..3f0b7b2f47 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -142,4 +142,4 @@ Documentation by David Greaves, Junio C Hamano and the git-list Date: Sun, 8 Jun 2008 03:36:11 +0200 Subject: git-describe.txt: document --always Signed-off-by: Stephan Beyer Signed-off-by: Junio C Hamano --- Documentation/git-describe.txt | 3 +++ 1 file changed, 3 insertions(+) (limited to 'Documentation/git-describe.txt') diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index 3f0b7b2f47..9f6f483186 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -70,6 +70,9 @@ OPTIONS Only consider tags matching the given pattern (can be used to avoid leaking private tags made from the repository). +--always:: + Show uniquely abbreviated commit object as fallback. + EXAMPLES -------- -- cgit v1.2.3 From b1889c36d85514e5e70462294c561a02c2edfe2b Mon Sep 17 00:00:00 2001 From: Jonathan Nieder Date: Mon, 30 Jun 2008 01:09:04 -0500 Subject: Documentation: be consistent about "git-" versus "git " Since the git-* commands are not installed in $(bindir), using "git-command " in examples in the documentation is not a good idea. On the other hand, it is nice to be able to refer to each command using one hyphenated word. (There is no escaping it, anyway: man page names cannot have spaces in them.) This patch retains the dash in naming an operation, command, program, process, or action. Complete command lines that can be entered at a shell (i.e., without options omitted) are made to use the dashless form. The changes consist only of replacing some spaces with hyphens and vice versa. After a "s/ /-/g", the unpatched and patched versions are identical. Signed-off-by: Jonathan Nieder Signed-off-by: Junio C Hamano --- Documentation/git-describe.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'Documentation/git-describe.txt') diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index 9f6f483186..b6c86c2aea 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -8,7 +8,7 @@ git-describe - Show the most recent tag that is reachable from a commit SYNOPSIS -------- -'git-describe' [--all] [--tags] [--contains] [--abbrev=] ... +'git describe' [--all] [--tags] [--contains] [--abbrev=] ... DESCRIPTION ----------- @@ -78,7 +78,7 @@ EXAMPLES With something like git.git current tree, I get: - [torvalds@g5 git]$ git-describe parent + [torvalds@g5 git]$ git describe parent v1.0.4-14-g2414721 i.e. the current head of my "parent" branch is based on v1.0.4, @@ -94,7 +94,7 @@ of parent (which was `2414721b194453f058079d897d13c4e377f92dc6`). Doing a "git-describe" on a tag-name will just show the tag name: - [torvalds@g5 git]$ git-describe v1.0.4 + [torvalds@g5 git]$ git describe v1.0.4 v1.0.4 With --all, the command can use branch heads as references, so @@ -115,13 +115,13 @@ closest tagname without any suffix: SEARCH STRATEGY --------------- -For each committish supplied "git describe" will first look for +For each committish supplied "git-describe" will first look for a tag which tags exactly that commit. Annotated tags will always be preferred over lightweight tags, and tags with newer dates will always be preferred over tags with older dates. If an exact match is found, its name will be output and searching will stop. -If an exact match was not found "git describe" will walk back +If an exact match was not found "git-describe" will walk back through the commit history to locate an ancestor commit which has been tagged. The ancestor's tag will be output along with an abbreviation of the input committish's SHA1. -- cgit v1.2.3 From 483bc4f045881b998512ae814d6cf44d0c0cb493 Mon Sep 17 00:00:00 2001 From: Jonathan Nieder Date: Mon, 30 Jun 2008 13:56:34 -0500 Subject: Documentation formatting and cleanup Following what appears to be the predominant style, format names of commands and commandlines both as `teletype text`. While we're at it, add articles ("a" and "the") in some places, italicize the name of the command in the manual page synopsis line, and add a comma or two where it seems appropriate. Signed-off-by: Jonathan Nieder Signed-off-by: Junio C Hamano --- Documentation/git-describe.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'Documentation/git-describe.txt') diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index b6c86c2aea..51a0cc044f 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -92,7 +92,7 @@ of commits which would be displayed by "git log v1.0.4..parent". The hash suffix is "-g" + 7-char abbreviation for the tip commit of parent (which was `2414721b194453f058079d897d13c4e377f92dc6`). -Doing a "git-describe" on a tag-name will just show the tag name: +Doing a `git-describe` on a tag-name will just show the tag name: [torvalds@g5 git]$ git describe v1.0.4 v1.0.4 @@ -115,13 +115,13 @@ closest tagname without any suffix: SEARCH STRATEGY --------------- -For each committish supplied "git-describe" will first look for +For each committish supplied, `git-describe` will first look for a tag which tags exactly that commit. Annotated tags will always be preferred over lightweight tags, and tags with newer dates will always be preferred over tags with older dates. If an exact match is found, its name will be output and searching will stop. -If an exact match was not found "git-describe" will walk back +If an exact match was not found, `git-describe` will walk back through the commit history to locate an ancestor commit which has been tagged. The ancestor's tag will be output along with an abbreviation of the input committish's SHA1. @@ -129,7 +129,7 @@ abbreviation of the input committish's SHA1. If multiple tags were found during the walk then the tag which has the fewest commits different from the input committish will be selected and output. Here fewest commits different is defined as -the number of commits which would be shown by "git log tag..input" +the number of commits which would be shown by `git log tag..input` will be the smallest number of commits possible. -- cgit v1.2.3 From ba020ef5eb5fca3d757bd580ff117adaf81ca079 Mon Sep 17 00:00:00 2001 From: Jonathan Nieder Date: Thu, 3 Jul 2008 00:41:41 -0500 Subject: manpages: italicize git command names (which were in teletype font) The names of git commands are not meant to be entered at the commandline; they are just names. So we render them in italics, as is usual for command names in manpages. Using doit () { perl -e 'for (<>) { s/\`(git-[^\`.]*)\`/'\''\1'\''/g; print }' } for i in git*.txt config.txt diff*.txt blame*.txt fetch*.txt i18n.txt \ merge*.txt pretty*.txt pull*.txt rev*.txt urls*.txt do doit <"$i" >"$i+" && mv "$i+" "$i" done git diff . Signed-off-by: Jonathan Nieder Signed-off-by: Junio C Hamano --- Documentation/git-describe.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'Documentation/git-describe.txt') diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index 51a0cc044f..44b166888a 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -92,7 +92,7 @@ of commits which would be displayed by "git log v1.0.4..parent". The hash suffix is "-g" + 7-char abbreviation for the tip commit of parent (which was `2414721b194453f058079d897d13c4e377f92dc6`). -Doing a `git-describe` on a tag-name will just show the tag name: +Doing a 'git-describe' on a tag-name will just show the tag name: [torvalds@g5 git]$ git describe v1.0.4 v1.0.4 @@ -115,13 +115,13 @@ closest tagname without any suffix: SEARCH STRATEGY --------------- -For each committish supplied, `git-describe` will first look for +For each committish supplied, 'git-describe' will first look for a tag which tags exactly that commit. Annotated tags will always be preferred over lightweight tags, and tags with newer dates will always be preferred over tags with older dates. If an exact match is found, its name will be output and searching will stop. -If an exact match was not found, `git-describe` will walk back +If an exact match was not found, 'git-describe' will walk back through the commit history to locate an ancestor commit which has been tagged. The ancestor's tag will be output along with an abbreviation of the input committish's SHA1. -- cgit v1.2.3 From 59eb68aa2b4e52aa1d098e0d76c5130864ceff2e Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Mon, 21 Jul 2008 12:14:42 -0700 Subject: Update my e-mail address The old cox.net address is still getting mails from gitters. Signed-off-by: Junio C Hamano --- Documentation/git-describe.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/git-describe.txt') diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index 44b166888a..7fdda04bae 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -136,7 +136,7 @@ will be the smallest number of commits possible. Author ------ Written by Linus Torvalds , but somewhat -butchered by Junio C Hamano . Later significantly +butchered by Junio C Hamano . Later significantly updated by Shawn Pearce . Documentation -- cgit v1.2.3 From f448e24e2fe336621306b04b84e947bdd04f7ecc Mon Sep 17 00:00:00 2001 From: Abhijit Menon-Sen Date: Wed, 30 Jul 2008 15:03:43 +0530 Subject: Make the DESCRIPTION match ... items in the SYNOPSIS When the SYNOPSIS says e.g. "...", it is nice if the DESCRIPTION also mentions "..." and says the specified "paths" (note plural) are used for $whatever. This fixes the obvious mismatches. Signed-off-by: Abhijit Menon-Sen Signed-off-by: Junio C Hamano --- Documentation/git-describe.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation/git-describe.txt') diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index 7fdda04bae..c4dbc2ae34 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -21,8 +21,8 @@ abbreviated object name of the most recent commit. OPTIONS ------- -:: - The object name of the committish. +...:: + Committish object names to describe. --all:: Instead of using only the annotated tags, use any ref -- cgit v1.2.3 From 7e425c4fbbe9affffa822f154d8bb2d0da6699ef Mon Sep 17 00:00:00 2001 From: "Shawn O. Pearce" Date: Mon, 13 Oct 2008 07:39:46 -0700 Subject: describe: Make --tags and --all match lightweight tags more often MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Acked-By: Uwe Kleine-König Signed-off-by: Junio C Hamano --- Documentation/git-describe.txt | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) (limited to 'Documentation/git-describe.txt') diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index c4dbc2ae34..3d79f05995 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 annotated 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 -- cgit v1.2.3 From 323b9db839cc4e49008666e402aac3264e359423 Mon Sep 17 00:00:00 2001 From: Jon Loeliger Date: Mon, 12 Jan 2009 14:02:07 -0600 Subject: Fix Documentation typos surrounding the word 'handful'. Some instances replaced by "handful of", others use the word "few", a couple get a slight rewording. Signed-off-by: Jon Loeliger Signed-off-by: Junio C Hamano --- Documentation/git-describe.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/git-describe.txt') diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index 3d79f05995..a99b4ef943 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -87,7 +87,7 @@ With something like git.git current tree, I get: v1.0.4-14-g2414721 i.e. the current head of my "parent" branch is based on v1.0.4, -but since it has a handful commits on top of that, +but since it has a few commits on top of that, describe has added the number of additional commits ("14") and an abbreviated object name for the commit itself ("2414721") at the end. -- cgit v1.2.3 From b938f62a208d24f3d6bed260ceb809cd6b3924d7 Mon Sep 17 00:00:00 2001 From: Boyd Stephen Smith Jr Date: Thu, 22 Jan 2009 12:26:25 -0600 Subject: Fix Documentation for git-describe The documentation for git-describe says the default abbreviation is 8 hexadecimal digits while cache.c clearly shows DEFAULT_ABBREV set to 7. This patch corrects the documentation. Signed-off-by: Boyd Stephen Smith Jr Signed-off-by: Junio C Hamano --- Documentation/git-describe.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/git-describe.txt') diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index c4dbc2ae34..59a6fd17ab 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -38,7 +38,7 @@ OPTIONS Automatically implies --tags. --abbrev=:: - Instead of using the default 8 hexadecimal digits as the + Instead of using the default 7 hexadecimal digits as the abbreviated object name, use digits. --candidates=:: -- cgit v1.2.3