diff options
Diffstat (limited to 'Documentation/git-describe.txt')
| -rw-r--r-- | Documentation/git-describe.txt | 52 |
1 files changed, 44 insertions, 8 deletions
diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index c8f28c8c86..e027fb8c4b 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -3,14 +3,14 @@ git-describe(1) NAME ---- -git-describe - Describe a commit using the most recent tag reachable from it - +git-describe - Give an object a human readable name based on an available ref SYNOPSIS -------- [verse] 'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>...] 'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>] +'git describe' <blob> DESCRIPTION ----------- @@ -24,15 +24,26 @@ 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]. +If the given object refers to a blob, it will be described +as `<commit-ish>:<path>`, such that the blob can be found +at `<path>` in the `<commit-ish>`, which itself describes the +first commit in which this blob occurs in a reverse revision walk +from HEAD. + OPTIONS ------- <commit-ish>...:: Commit-ish object names to describe. Defaults to HEAD if omitted. --dirty[=<mark>]:: - Describe the working tree. - It means describe HEAD and appends <mark> (`-dirty` by - default) if the working tree is dirty. +--broken[=<mark>]:: + Describe the state of the working tree. When the working + tree matches HEAD, the output is the same as "git describe + HEAD". If the working tree has local modification "-dirty" + is appended to it. If a repository is corrupt and Git + cannot determine if there is local modification, Git will + error out, unless `--broken' is given, which appends + the suffix "-broken" instead. --all:: Instead of using only the annotated tags, use any ref @@ -82,8 +93,25 @@ OPTIONS --match <pattern>:: Only consider tags matching the given `glob(7)` pattern, - excluding the "refs/tags/" prefix. This can be used to avoid - leaking private tags from the repository. + excluding the "refs/tags/" prefix. If used with `--all`, it also + considers local branches and remote-tracking references matching the + pattern, excluding respectively "refs/heads/" and "refs/remotes/" + prefix; references of other types are never considered. If given + multiple times, a list of patterns will be accumulated, and tags + matching any of the patterns will be considered. Use `--no-match` to + clear and reset the list of patterns. + +--exclude <pattern>:: + Do not consider tags matching the given `glob(7)` pattern, excluding + the "refs/tags/" prefix. If used with `--all`, it also does not consider + local branches and remote-tracking references matching the pattern, + excluding respectively "refs/heads/" and "refs/remotes/" prefix; + references of other types are never considered. If given multiple times, + a list of patterns will be accumulated and tags matching any of the + patterns will be excluded. When combined with --match a tag will be + considered when it matches at least one --match pattern and does not + match any of the --exclude patterns. Use `--no-exclude` to clear and + reset the list of patterns. --always:: Show uniquely abbreviated commit object as fallback. @@ -154,7 +182,7 @@ is found, its name will be output and searching will stop. 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 commit-ish's SHA-1. If '--first-parent' was +abbreviation of the input commit-ish's SHA-1. If `--first-parent` was specified then the walk will only consider the first parent of each commit. @@ -164,6 +192,14 @@ selected and output. Here fewest commits different is defined as the number of commits which would be shown by `git log tag..input` will be the smallest number of commits possible. +BUGS +---- + +Tree objects as well as tag objects not pointing at commits, cannot be described. +When describing blobs, the lightweight tags pointing at blobs are ignored, +but the blob is still described as <committ-ish>:<path> despite the lightweight +tag being favorable. + GIT --- Part of the linkgit:git[1] suite |