1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
|
<!DOCTYPE html>
<html>
<head>
<title>
The Codex »
Refs and Names
</title>
<link
rel='stylesheet'
type='text/css'
href='http://fonts.googleapis.com/css?family=Buenard:400,700&subset=latin,latin-ext'>
<link
rel="stylesheet"
type="text/css"
href="../../media/css/reset.css">
<link
rel="stylesheet"
type="text/css"
href="../../media/css/grimoire.css">
</head>
<body>
<div id="shell">
<ol id="breadcrumbs">
<li class="crumb-0 not-last">
<a href="../../">index</a>
</li>
<li class="crumb-1 not-last">
<a href="../">git</a>
</li>
<li class="crumb-2 not-last">
<a href="./">theory-and-practice</a>
</li>
<li class="crumb-3 last">
refs-and-names
</li>
</ol>
<div id="article">
<h1 id="refs-and-names">Refs and Names</h1>
<p>Git's <a href="objects">object system</a> stores most of the data for projects tracked in
Git, but only provides SHA-1 hashes. This is basically useless if you want to
make practical use of Git, so Git also has a naming mechanism called “refs”
that provide human-meaningful names for objects.</p>
<p>There are two kinds of refs:</p>
<ul>
<li>
<p>“Normal” refs, which are names that resolve directly to SHA-1 hashes. These
are the vast majority of refs in most repositories.</p>
</li>
<li>
<p>“Symbolic” refs, which are names that resolve to other refs. In most
repositories, only a few of these appear. (Circular references are possible
with symbolic refs. Git will refuse to resolve these.)</p>
</li>
</ul>
<p>Anywhere you could use a SHA-1, you can use a ref instead. Git interprets them
identically, after resolving the ref down to the SHA-1.</p>
<h2 id="namespaces">Namespaces</h2>
<p>Every operation in Git that uses a name of some sort, including branching
(branch names), tagging (tag names), fetching (remote-tracking branch names),
and pushing (many kinds of name), expands those names to refs, using a
namespace convention. The following namespaces are common:</p>
<ul>
<li>
<p><code>refs/heads/NAME</code>: branches. The branch name is the ref name with
<code>refs/heads/</code> removed. Names generally point to commits.</p>
</li>
<li>
<p><code>refs/remotes/REMOTE/NAME</code>: “remote-tracking” branches. These are maintained
in tandem by <code>git remote</code> and <code>git fetch</code>, to cache the state of other
repositories. Names generally point to commits.</p>
</li>
<li>
<p><code>refs/tags/NAME</code>: tags. The tag name is the ref name with <code>refs/heads/</code>
removed. Names generally point to commits or tag objects.</p>
</li>
<li>
<p><code>refs/bisect/STATE</code>: <code>git bisect</code> markers for known-good and known-bad
revisions, from which the rest of the bisect state can be derived.</p>
</li>
</ul>
<p>There are also a few special refs directly in the <code>refs/</code> namespace, most
notably:</p>
<ul>
<li><code>refs/stash</code>: The most recent stash entry, as maintained by <code>git stash</code>.
(Other stash entries are maintained by a separate system.) Names generally
point to commits.</li>
</ul>
<p>Tools can invent new refs for their own purposes, or manipulate existing refs;
the convention is that tools that use refs (which is, as I said, most of them)
respect the state of the ref as if they'd created that state themselves,
rather than sanity-checking the ref before using it.</p>
<h2 id="special-refs">Special refs</h2>
<p>There are a handful of special refs used by Git commands for their own
operation. These refs do <em>not</em> begin with <code>refs/</code>:</p>
<ul>
<li>
<p><code>HEAD</code>: the “current” commit for most operations. This is set when checking
out a commit, and many revision-related commands default to <code>HEAD</code> if not
given a revision to operate on. <code>HEAD</code> can either be a symbolic ref
(pointing to a branch ref) or a normal ref (pointing directly to a commit),
and is very frequently a symbolic ref.</p>
</li>
<li>
<p><code>MERGE_HEAD</code>: during a merge, <code>MERGE_HEAD</code> resolves to the commit whose
history is being merged.</p>
</li>
<li>
<p><code>ORIG_HEAD</code>: set by operations that change <code>HEAD</code> in potentially destructive
ways by resolving <code>HEAD</code> before making the change.</p>
</li>
<li>
<p><code>CHERRY_PICK_HEAD</code> is set during <code>git cherry-pick</code> to the commit whose
changes are being copied.</p>
</li>
<li>
<p><code>FETCH_HEAD</code> is set by the forms of <code>git fetch</code> that fetch a single ref, and
points to the commit the fetched ref pointed to.</p>
</li>
</ul>
<h2 id="examining-and-manipulating-refs">Examining and manipulating refs</h2>
<p>The <code>git show-ref</code> command will list the refs in namespaces under <code>refs</code> in
your repository, printing the SHA-1 hashes they resolve to. Pass <code>--head</code> to
also include <code>HEAD</code>.</p>
<p>The following commands can be used to manipulate refs directly:</p>
<ul>
<li>
<p><code>git update-ref <ref> <sha1></code> forcibly sets <code><ref></code> to the passed <code><sha1></code>.</p>
</li>
<li>
<p><code>git update-ref -d <ref></code> deletes a ref.</p>
</li>
<li>
<p><code>git symbolic-ref <ref></code> prints the target of <code><ref></code>, if <code><ref></code> is a
symbolic ref. (It will fail with an error message for normal refs.)</p>
</li>
<li>
<p><code>git symbolic-ref <ref> <target></code> forcibly makes <code><ref></code> a symbolic ref
pointing to <code><target></code>.</p>
</li>
</ul>
<p>Additionally, you can see what ref a given name resolves to using <code>git
rev-parse --symbolic-full-name <name></code> or <code>git show-ref <name></code>.</p>
</div>
<div id="comments">
<div id="disqus_thread"></div>
<script type="text/javascript">
/* * * CONFIGURATION VARIABLES: EDIT BEFORE PASTING INTO YOUR WEBPAGE * * */
var disqus_shortname = 'grimoire'; // required: replace example with your forum shortname
/* * * DON'T EDIT BELOW THIS LINE * * */
(function() {
var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
dsq.src = 'http://' + disqus_shortname + '.disqus.com/embed.js';
(document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
})();
</script>
<noscript>Please enable JavaScript to view the <a href="http://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>
<a href="http://disqus.com" class="dsq-brlink">comments powered by <span class="logo-disqus">Disqus</span></a>
</div>
<div id="footer">
<p>
The Codex —
Powered by <a href="http://markdoc.org/">Markdoc</a>.
<a href="https://bitbucket.org/ojacobson/grimoire.ca/src/master/wiki/git/theory-and-practice/refs-and-names.md">See this page on Bitbucket</a> (<a href="https://bitbucket.org/ojacobson/grimoire.ca/history-node/master/wiki/git/theory-and-practice/refs-and-names.md">history</a>).
</p>
</div>
</div>
</body>
</html>
|
