@matheusbsbs / matheus-bagliano / commits / c0990ff36f
Fork 0

Add man page for git-show-ref

Signed-off-by: Jonas Fonseca <fonseca@diku.dk> Signed-off-by: Junio C Hamano <junkio@cox.net>

Jonas Fonseca committed Sep 18, 2006 at 14:32 UTC c0990ff36f0b9b8e806c8f649a0888d05bb22c37
1 file changed +136
Documentation/git-show-ref.txt new
+136
@@ -0,0 +1,136 @@
1 +git-show-ref(1)
2 +===============
3 +
4 +NAME
5 +----
6 +git-show-ref - List references in a local repository
7 +
8 +SYNOPSIS
9 +--------
10 +[verse]
11 +'git-show-ref' [-q|--quiet] [--verify] [-h|--head] [-d|--dereference]
12 + [--tags] [--heads] [--] <pattern>...
13 +
14 +DESCRIPTION
15 +-----------
16 +
17 +Displays references available in a local repository along with the associated
18 +commit IDs. Results can be filtered using a pattern and tags can be
19 +dereferenced into object IDs. Additionally, it can be used to test whether a
20 +particular ref exists.
21 +
22 +Use of this utility is encouraged in favor of directly accessing files under
23 +in the `.git` directory.
24 +
25 +OPTIONS
26 +-------
27 +
28 +-h, --head::
29 +
30 + Show the HEAD reference.
31 +
32 +--tags, --heads::
33 +
34 + Limit to only "refs/heads" and "refs/tags", respectively. These
35 + options are not mutually exclusive; when given both, references stored
36 + in "refs/heads" and "refs/tags" are displayed.
37 +
38 +-d, --dereference::
39 +
40 + Dereference tags into object IDs. They will be shown with "^{}"
41 + appended.
42 +
43 +--verify::
44 +
45 + Enable stricter reference checking by requiring an exact ref path.
46 + Aside from returning an error code of 1, it will also print an error
47 + message if '--quiet' was not specified.
48 +
49 +-q, --quiet::
50 +
51 + Do not print any results to stdout. When combined with '--verify' this
52 + can be used to silently check if a reference exists.
53 +
54 +<pattern>::
55 +
56 + Show references matching one or more patterns.
57 +
58 +OUTPUT
59 +------
60 +
61 +The output is in the format: '<SHA-1 ID>' '<space>' '<reference name>'.
62 +
63 +-----------------------------------------------------------------------------
64 +$ git show-ref --head --dereference
65 +832e76a9899f560a90ffd62ae2ce83bbeff58f54 HEAD
66 +832e76a9899f560a90ffd62ae2ce83bbeff58f54 refs/heads/master
67 +832e76a9899f560a90ffd62ae2ce83bbeff58f54 refs/heads/origin
68 +3521017556c5de4159da4615a39fa4d5d2c279b5 refs/tags/v0.99.9c
69 +6ddc0964034342519a87fe013781abf31c6db6ad refs/tags/v0.99.9c^{}
70 +055e4ae3ae6eb344cbabf2a5256a49ea66040131 refs/tags/v1.0rc4
71 +423325a2d24638ddcc82ce47be5e40be550f4507 refs/tags/v1.0rc4^{}
72 +...
73 +-----------------------------------------------------------------------------
74 +
75 +EXAMPLE
76 +-------
77 +
78 +To show all references called "master", whether tags or heads or anything
79 +else, and regardless of how deep in the reference naming hierarchy they are,
80 +use:
81 +
82 +-----------------------------------------------------------------------------
83 + git show-ref master
84 +-----------------------------------------------------------------------------
85 +
86 +This will show "refs/heads/master" but also "refs/remote/other-repo/master",
87 +if such references exists.
88 +
89 +When using the '--verify' flag, the command requires an exact path:
90 +
91 +-----------------------------------------------------------------------------
92 + git show-ref --verify refs/heads/master
93 +-----------------------------------------------------------------------------
94 +
95 +will only match the exact branch called "master".
96 +
97 +If nothing matches, gitlink:git-show-ref[1] will return an error code of 1,
98 +and in the case of verification, it will show an error message.
99 +
100 +For scripting, you can ask it to be quiet with the "--quiet" flag, which
101 +allows you to do things like
102 +
103 +-----------------------------------------------------------------------------
104 + git-show-ref --quiet --verify -- "refs/heads/$headname" ||
105 + echo "$headname is not a valid branch"
106 +-----------------------------------------------------------------------------
107 +
108 +to check whether a particular branch exists or not (notice how we don't
109 +actually want to show any results, and we want to use the full refname for it
110 +in order to not trigger the problem with ambiguous partial matches).
111 +
112 +To show only tags, or only proper branch heads, use "--tags" and/or "--heads"
113 +respectively (using both means that it shows tags and heads, but not other
114 +random references under the refs/ subdirectory).
115 +
116 +To do automatic tag object dereferencing, use the "-d" or "--dereference"
117 +flag, so you can do
118 +
119 +-----------------------------------------------------------------------------
120 + git show-ref --tags --dereference
121 +-----------------------------------------------------------------------------
122 +
123 +to get a listing of all tags together with what they dereference.
124 +
125 +SEE ALSO
126 +--------
127 +gitlink:git-ls-remote[1], gitlink:git-peek-remote[1]
128 +
129 +AUTHORS
130 +-------
131 +Written by Linus Torvalds <torvalds@osdl.org>.
132 +Man page by Jonas Fonseca <fonseca@diku.dk>.
133 +
134 +GIT
135 +---
136 +Part of the gitlink:git[7] suite