summaryrefslogtreecommitdiff
path: root/Documentation/git-describe.txt
AgeCommit message (Collapse)AuthorFilesLines
2017-09-20describe: teach --match to handle branches and remotesLibravatar Max Kirillov1-10/+14
When `git describe` uses `--match`, it matches only tags, basically ignoring the `--all` argument even when it is specified. Fix it by also matching branch name and $remote_name/$remote_branch_name, for remote-tracking references, with the specified patterns. Update documentation accordingly and add tests. Signed-off-by: Max Kirillov <max@max630.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-03-22builtin/describe: introduce --broken flagLibravatar Stefan Beller1-3/+8
git-describe tells you the version number you're at, or errors out, e.g. when you run it outside of a repository, which may happen when downloading a tar ball instead of using git to obtain the source code. To keep this property of only erroring out, when not in a repository, severe (submodule) errors must be downgraded to reporting them gently instead of having git-describe error out completely. To achieve that a flag '--broken' is introduced, which is in the same vein as '--dirty' but uses an actual child process to check for dirtiness. When that child dies unexpectedly, we'll append '-broken' instead of '-dirty'. Signed-off-by: Stefan Beller <sbeller@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-01-23describe: teach describe negative pattern matchesLibravatar Jacob Keller1-0/+10
Teach git-describe the `--exclude` option which will allow specifying a glob pattern of tags to ignore. This can be combined with the `--match` patterns to enable more flexibility in determining which tags to consider. For example, suppose you wish to find the first official release tag that contains a certain commit. If we assume that official release tags are of the form "v*" and pre-release candidates include "*rc*" in their name, we can now find the first release tag that introduces the commit abcdef: git describe --contains --match="v*" --exclude="*rc*" abcdef Add documentation, tests, and completion for this change. Signed-off-by: Jacob Keller <jacob.keller@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-01-23describe: teach --match to accept multiple patternsLibravatar Jacob Keller1-1/+4
Teach `--match` to be accepted multiple times, accumulating a list of patterns to match into a string list. Each pattern is inclusive, such that a tag need only match one of the provided patterns to be considered for matching. This extension is useful as it enables more flexibility in what tags match, and may avoid the need to run the describe command multiple times to get the same result. Add tests and update the documentation for this change. Signed-off-by: Jacob Keller <jacob.keller@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-06-28doc: typeset long command-line options as literalLibravatar Matthieu Moy1-1/+1
Similarly to the previous commit, use backquotes instead of forward-quotes, for long options. This was obtained with: perl -pi -e "s/'(--[a-z][a-z=<>-]*)'/\`\$1\`/g" *.txt and manual tweak to remove false positive in ascii-art (o'--o'--o' to describe rewritten history). Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-08-31Merge branch 'sg/describe-contains'Libravatar Junio C Hamano1-2/+2
"git describe" without argument defaulted to describe the HEAD commit, but "git describe --contains" didn't. Arguably, in a repository used for active development, such defaulting would not be very useful as the tip of branch is typically not tagged, but it is better to be consistent. * sg/describe-contains: describe --contains: default to HEAD when no commit-ish is given
2015-08-25describe --contains: default to HEAD when no commit-ish is givenLibravatar SZEDER Gábor1-2/+2
'git describe --contains' doesn't default to HEAD when no commit is given, and it doesn't produce any output, not even an error: ~/src/git ((v2.5.0))$ ./git describe --contains ~/src/git ((v2.5.0))$ ./git describe --contains HEAD v2.5.0^0 Unlike other 'git describe' options, the '--contains' code path is implemented by calling 'name-rev' with a bunch of options plus all the commit-ishes that were passed to 'git describe'. If no commit-ish was present, then 'name-rev' got invoked with none, which then leads to the behavior illustrated above. Porcelain commands usually default to HEAD when no commit-ish is given, and 'git describe' already does so in all other cases, so it should do so with '--contains' as well. Pass HEAD to 'name-rev' when no commit-ish is given on the command line to make '--contains' behave consistently with other 'git describe' options. While at it, use argv_array_pushv() instead of the loop to pass commit-ishes to 'git name-rev'. 'git describe's short help already indicates that the commit-ish is optional, but the synopsis in the man page doesn't, so update it accordingly as well. Signed-off-by: SZEDER Gábor <szeder@ira.uka.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-06-16Documentation/describe: improve one-line summaryLibravatar Matthieu Moy1-1/+1
git describe does not show 'the most recent tag that is reachable from a commit', but a descriptive name based on this tag. Fix the description to reflect that. Suggested-by: Albert Netymk <albertnetymk@gmail.com> Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-09-04use 'commit-ish' instead of 'committish'Libravatar Richard Hansen1-7/+7
Replace 'committish' in documentation and comments with 'commit-ish' to match gitglossary(7) and to be consistent with 'tree-ish'. The only remaining instances of 'committish' are: * variable, function, and macro names * "(also committish)" in the definition of commit-ish in gitglossary[7] Signed-off-by: Richard Hansen <rhansen@bbn.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-05-20describe: Add --first-parent optionLibravatar Mike Crowe1-1/+8
Only consider the first parent commit when walking the commit history. This is useful if you only wish to match tags on your branch after a merge. Signed-off-by: Mike Crowe <mac@mcrowe.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-04-15The name of the hash function is "SHA-1", not "SHA1"Libravatar Thomas Ackermann1-1/+1
Use "SHA-1" instead of "SHA1" whenever we talk about the hash function. When used as a programming symbol, we keep "SHA1". Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-03-25Merge branch 'maint-1.8.1' into maintLibravatar Junio C Hamano1-2/+3
* maint-1.8.1: bundle: Add colons to list headings in "verify" bundle: Fix "verify" output if history is complete Documentation: filter-branch env-filter example git-filter-branch.txt: clarify ident variables usage git-compat-util.h: Provide missing netdb.h definitions describe: Document --match pattern format Documentation/githooks: Explain pre-rebase parameters update-index: list supported idx versions and their features diff-options: unconfuse description of --color read-cache.c: use INDEX_FORMAT_{LB,UB} in verify_hdr() index-format.txt: mention of v4 is missing in some places
2013-02-24describe: Document --match pattern formatLibravatar Greg Price1-2/+3
It's not clear in git-describe(1) what kind of "pattern" should be passed to --match. Fix that. Signed-off-by: Greg Price <price@mit.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-01Documentation: the name of the system is 'Git', not 'git'Libravatar Thomas Ackermann1-1/+1
Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-08-06Documentation: do not mention .git/refs/* directoriesLibravatar Junio C Hamano1-2/+2
It is an implementation detail that a new tag is created by adding a file in the .git/refs/tags directory. The only thing the user needs to know is that a "git tag" creates a ref in the refs/tags namespace, and without "-f", it does not overwrite an existing tag. Inspired by a report from 乙酸鋰 <ch3cooli@gmail.com>; I think I caught all the existing mention in Documentation/ directory in the tip of 1.7.9.X maintenance track, but we may have added new ones since then. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-03-11doc: drop author/documentation sections from most pagesLibravatar Jeff King1-11/+0
The point of these sections is generally to: 1. Give credit where it is due. 2. Give the reader an idea of where to ask questions or file bug reports. But they don't do a good job of either case. For (1), they are out of date and incomplete. A much more accurate answer can be gotten through shortlog or blame. For (2), the correct contact point is generally git@vger, and even if you wanted to cc the contact point, the out-of-date and incomplete fields mean you're likely sending to somebody useless. So let's drop the fields entirely from all manpages except git(1) itself. We already point people to the mailing list for bug reports there, and we can update the Authors section to give credit to the major contributors and point to shortlog and blame for more information. Each page has a "This is part of git" footer, so people can follow that to the main git manpage.
2010-11-03Change incorrect uses of "remote branch" meaning "remote-tracking"Libravatar Matthieu Moy1-1/+1
"remote branch" is a branch hosted in a remote repository, while "remote-tracking branch" is a copy of such branch, hosted locally. The distinction is subtle when the copy is up-to-date, but rather fundamental to understand what "git fetch" and "git push" do. This patch should fix all incorrect usages in Documentation/ directory. Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-03-24Documentation: explain the meaning of "-g" in git-describe outputLibravatar Markus Heidelberg1-0/+3
Signed-off-by: Markus Heidelberg <markus.heidelberg@web.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-01-10Documentation: spell 'git cmd' without dash throughoutLibravatar Thomas Rast1-3/+3
The documentation was quite inconsistent when spelling 'git cmd' if it only refers to the program, not to some specific invocation syntax: both 'git-cmd' and 'git cmd' spellings exist. The current trend goes towards dashless forms, and there is precedent in 647ac70 (git-svn.txt: stop using dash-form of commands., 2009-07-07) to actively eliminate the dashed variants. Replace 'git-cmd' with 'git cmd' throughout, except where git-shell, git-cvsserver, git-upload-pack, git-receive-pack, and git-upload-archive are concerned, because those really live in the $PATH.
2009-11-10git-describe.txt: formatting fixLibravatar Junio C Hamano1-0/+1
A multi-line SYNOPSIS description must be marked as [verse] Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-11-10Merge branch 'jp/dirty-describe'Libravatar Junio C Hamano1-0/+6
* jp/dirty-describe: Teach "git describe" --dirty option
2009-11-04Fix documentation grammar typoLibravatar Gisle Aas1-1/+1
Introduced in 492cf3f (More precise description of 'git describe --abbrev', 2009-10-29) Signed-off-by: Gisle Aas <gisle@aas.no> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-10-30More precise description of 'git describe --abbrev'Libravatar Gisle Aas1-4/+13
Also adds a note about why the output in the examples might give different output today. Signed-off-by: Gisle Aas <gisle@aas.no> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-10-27Teach "git describe" --dirty optionLibravatar Jean Privat1-0/+6
With the --dirty option, git describe works on HEAD but append s"-dirty" iff the contents of the work tree differs from HEAD. E.g. $ git describe --dirty v1.6.5-15-gc274db7 $ echo >> Makefile $ git describe --dirty v1.6.5-15-gc274db7-dirty The --dirty option can also be used to specify what is appended, instead of the default string "-dirty". $ git describe --dirty=.mod v1.6.5-15-gc274db7.mod Many build scripts use `git describe` to produce a version number based on the description of HEAD (on which the work tree is based) + saying that if the build contains uncommitted changes. This patch helps the writing of such scripts since `git describe --dirty` does directly the intended thing. Three possiblities were considered while discussing this new feature: 1. Describe the work tree by default and describe HEAD only if "HEAD" is explicitly specified Pro: does the right thing by default (both for users and for scripts) Pro: other git commands that works on the work tree by default Con: breaks existing scripts used by the Linux kernel and other projects 2. Use --worktree instead of --dirty Pro: does what it says: "git describe --worktree" describes the work tree Con: other commands do not require a --worktree option when working on the work tree (it often is the default mode for them) Con: unusable with an optional value: "git describe --worktree=.mod" is quite unintuitive. 3. Use --dirty as in this patch Pro: makes sense to specify an optional value (what the dirty mark is) Pro: does not have any of the big cons of previous alternatives * does not break scripts * is not inconsistent with other git commands This patch takes the third approach. Signed-off-by: Jean Privat <jean@pryen.org> Acked-by: Shawn O. Pearce <spearce@spearce.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-01-23Merge branch 'maint'Libravatar Junio C Hamano1-1/+1
* maint: Fix Documentation for git-describe
2009-01-23Merge branch 'maint-1.6.0' into maintLibravatar Junio C Hamano1-1/+1
* maint-1.6.0: Fix Documentation for git-describe
2009-01-23Fix Documentation for git-describeLibravatar Boyd Stephen Smith Jr1-1/+1
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 <bss@iguanasuicide.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-01-13Fix Documentation typos surrounding the word 'handful'.Libravatar Jon Loeliger1-1/+1
Some instances replaced by "handful of", others use the word "few", a couple get a slight rewording. Signed-off-by: Jon Loeliger <jdl@freescale.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-10-17describe: Make --tags and --all match lightweight tags more oftenLibravatar Shawn O. Pearce1-2/+7
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> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-30Make the DESCRIPTION match <x>... items in the SYNOPSISLibravatar Abhijit Menon-Sen1-2/+2
When the SYNOPSIS says e.g. "<path>...", it is nice if the DESCRIPTION also mentions "<path>..." and says the specified "paths" (note plural) are used for $whatever. This fixes the obvious mismatches. Signed-off-by: Abhijit Menon-Sen <ams@toroid.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-21Update my e-mail addressLibravatar Junio C Hamano1-1/+1
The old cox.net address is still getting mails from gitters. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-05manpages: italicize git command names (which were in teletype font)Libravatar Jonathan Nieder1-3/+3
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 <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-01Documentation formatting and cleanupLibravatar Jonathan Nieder1-4/+4
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 <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-01Documentation: be consistent about "git-" versus "git "Libravatar Jonathan Nieder1-5/+5
Since the git-* commands are not installed in $(bindir), using "git-command <parameters>" 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 <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-06-08git-describe.txt: document --alwaysLibravatar Stephan Beyer1-0/+3
Signed-off-by: Stephan Beyer <s-beyer@gmx.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-06-06documentation: move git(7) to git(1)Libravatar Christian Couder1-1/+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 <chriscool@tuxfamily.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-05-14Merge branch 'maint-1.5.4' into maintLibravatar Junio C Hamano1-3/+4
* maint-1.5.4: Documentation/git-describe.txt: make description more readable
2008-05-14Documentation/git-describe.txt: make description more readableLibravatar Ian Hilt1-3/+4
Signed-off-by: Ian Hilt <ian.hilt@gmail.com> Credit-to: Kevin Ballard <kevin@sb.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-03-02Merge branch 'sb/describe-long'Libravatar Junio C Hamano1-0/+9
* sb/describe-long: git-describe: --long shows the object name even for a tagged commit
2008-02-25git-describe: --long shows the object name even for a tagged commitLibravatar Santi Béjar1-0/+9
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 <sbejar@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-02-24Teach git-describe --exact-match to avoid expensive tag searchesLibravatar Shawn O. Pearce1-0/+5
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 <spearce@spearce.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-02-11Merge branch 'ph/describe-match'Libravatar Junio C Hamano1-0/+4
* ph/describe-match: git-name-rev: add a --(no-)undefined option. git-describe: Add a --match option to limit considered tags.
2008-01-06Documentation: rename gitlink macro to linkgitLibravatar Dan McGee1-1/+1
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<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\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 <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-12-22git-describe: Add a --match option to limit considered tags.Libravatar Pierre Habouzit1-0/+4
Signed-off-by: Pierre Habouzit <madcoder@debian.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-06-07War on whitespaceLibravatar Junio C Hamano1-1/+0
This uses "git-apply --whitespace=strip" to fix whitespace errors that have crept in to our source files over time. There are a few files that need to have trailing whitespaces (most notably, test vectors). The results still passes the test, and build result in Documentation/ area is unchanged. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-05-21Teach git-describe how to run name-revLibravatar Shawn O. Pearce1-1/+6
Often users want to know not which tagged version a commit came after, but which tagged version a commit is contained within. This latter task is the job of git-name-rev, but most users are looking to git-describe to do the job. Junio suggested we make `git describe --contains` run the correct tool, `git name-rev`, and that's exactly what we do here. The output of name-rev was adjusted slightly through the new --name-only option, allowing describe to execv into name-rev and maintain its current output format. Signed-off-by: Shawn O. Pearce <spearce@spearce.org> Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-01-28Update describe documentation.Libravatar Junio C Hamano1-9/+22
Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-01-14Improve git-describe performance by reducing revision listing.Libravatar Shawn O. Pearce1-0/+30
My prior version of git-describe ran very slowly on even reasonably sized projects like git.git and linux.git as it tended to identify a large number of possible tags and then needed to generate the revision list for each of those tags to sort them and select the best tag to describe the input commit. All we really need is the number of commits in the input revision which are not in the tag. We can generate these counts during the revision walking and tag matching loop by assigning a color to each tag and coloring the commits as we walk them. This limits us to identifying no more than 26 possible tags, as there is limited space available within the flags field of struct commit. The limitation of 26 possible tags is hopefully not going to be a problem in real usage, as most projects won't create 26 maintenance releases and merge them back into a development trunk after the development trunk was tagged with a release candidate tag. If that does occur git-describe will start to revert to its old behavior of using the newer maintenance release tag to describe the development trunk, rather than the development trunk's own tag. The suggested workaround would be to retag the development trunk's tip. However since even 26 possible tags can take a while to generate a description for on some projects I'm defaulting the limit to 10 but offering the user --candidates to increase the number of possible matches if they need a more accurate result. I specifically chose 10 for the default as it seems unlikely projects will have more than 10 maintenance releases merged into a development trunk before retagging the development trunk, and it seems to perform about the same on linux.git as v1.4.4.4 git-describe. A large amount of debugging information was also added during the development of this change, so I've left it in to be toggled on with --debug. It may be useful to the end user to help them understand why git-describe took one particular tag over another. Signed-off-by: Shawn O. Pearce <spearce@spearce.org> Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-06-07Some doc typo fixesLibravatar Francis Daly1-1/+1
All should be clear enough, except perhaps committish / commitish. I just kept the more-used one within the current docs. [jc: with rephrasing of check-ref-format description later discussed on the list] Signed-off-by: Francis Daly <francis@daoine.org> Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-03-09Remove trailing dot after short descriptionLibravatar Fredrik Kuivinen1-1/+1
Signed-off-by: Fredrik Kuivinen <freku045@student.liu.se> Signed-off-by: Junio C Hamano <junkio@cox.net>