summaryrefslogtreecommitdiff
path: root/Documentation/git-describe.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/git-describe.txt')
-rw-r--r--Documentation/git-describe.txt18
1 files changed, 16 insertions, 2 deletions
diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt
index c924c945ba..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,6 +24,12 @@ 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>...::
@@ -186,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