Autogenerated HTML docs for v1.6.6-35-g1d85d
[git/jnareb-git.git] / git-update-ref.html
blob89c13b7e480d08a672ab4907d22c4d264654445f
1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
2 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
4 <head>
5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
6 <meta name="generator" content="AsciiDoc 8.2.5" />
7 <style type="text/css">
8 /* Debug borders */
9 p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
11 border: 1px solid red;
15 body {
16 margin: 1em 5% 1em 5%;
19 a {
20 color: blue;
21 text-decoration: underline;
23 a:visited {
24 color: fuchsia;
27 em {
28 font-style: italic;
31 strong {
32 font-weight: bold;
35 tt {
36 color: navy;
39 h1, h2, h3, h4, h5, h6 {
40 color: #527bbd;
41 font-family: sans-serif;
42 margin-top: 1.2em;
43 margin-bottom: 0.5em;
44 line-height: 1.3;
47 h1, h2, h3 {
48 border-bottom: 2px solid silver;
50 h2 {
51 padding-top: 0.5em;
53 h3 {
54 float: left;
56 h3 + * {
57 clear: left;
60 div.sectionbody {
61 font-family: serif;
62 margin-left: 0;
65 hr {
66 border: 1px solid silver;
69 p {
70 margin-top: 0.5em;
71 margin-bottom: 0.5em;
74 pre {
75 padding: 0;
76 margin: 0;
79 span#author {
80 color: #527bbd;
81 font-family: sans-serif;
82 font-weight: bold;
83 font-size: 1.1em;
85 span#email {
87 span#revision {
88 font-family: sans-serif;
91 div#footer {
92 font-family: sans-serif;
93 font-size: small;
94 border-top: 2px solid silver;
95 padding-top: 0.5em;
96 margin-top: 4.0em;
98 div#footer-text {
99 float: left;
100 padding-bottom: 0.5em;
102 div#footer-badges {
103 float: right;
104 padding-bottom: 0.5em;
107 div#preamble,
108 div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
109 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
110 div.admonitionblock {
111 margin-right: 10%;
112 margin-top: 1.5em;
113 margin-bottom: 1.5em;
115 div.admonitionblock {
116 margin-top: 2.5em;
117 margin-bottom: 2.5em;
120 div.content { /* Block element content. */
121 padding: 0;
124 /* Block element titles. */
125 div.title, caption.title {
126 font-family: sans-serif;
127 font-weight: bold;
128 text-align: left;
129 margin-top: 1.0em;
130 margin-bottom: 0.5em;
132 div.title + * {
133 margin-top: 0;
136 td div.title:first-child {
137 margin-top: 0.0em;
139 div.content div.title:first-child {
140 margin-top: 0.0em;
142 div.content + div.title {
143 margin-top: 0.0em;
146 div.sidebarblock > div.content {
147 background: #ffffee;
148 border: 1px solid silver;
149 padding: 0.5em;
152 div.listingblock {
153 margin-right: 0%;
155 div.listingblock > div.content {
156 border: 1px solid silver;
157 background: #f4f4f4;
158 padding: 0.5em;
161 div.quoteblock > div.content {
162 padding-left: 2.0em;
165 div.attribution {
166 text-align: right;
168 div.verseblock + div.attribution {
169 text-align: left;
172 div.admonitionblock .icon {
173 vertical-align: top;
174 font-size: 1.1em;
175 font-weight: bold;
176 text-decoration: underline;
177 color: #527bbd;
178 padding-right: 0.5em;
180 div.admonitionblock td.content {
181 padding-left: 0.5em;
182 border-left: 2px solid silver;
185 div.exampleblock > div.content {
186 border-left: 2px solid silver;
187 padding: 0.5em;
190 div.verseblock div.content {
191 white-space: pre;
194 div.imageblock div.content { padding-left: 0; }
195 div.imageblock img { border: 1px solid silver; }
196 span.image img { border-style: none; }
198 dl {
199 margin-top: 0.8em;
200 margin-bottom: 0.8em;
202 dt {
203 margin-top: 0.5em;
204 margin-bottom: 0;
205 font-style: italic;
207 dd > *:first-child {
208 margin-top: 0;
211 ul, ol {
212 list-style-position: outside;
214 div.olist2 ol {
215 list-style-type: lower-alpha;
218 div.tableblock > table {
219 border: 3px solid #527bbd;
221 thead {
222 font-family: sans-serif;
223 font-weight: bold;
225 tfoot {
226 font-weight: bold;
229 div.hlist {
230 margin-top: 0.8em;
231 margin-bottom: 0.8em;
233 div.hlist td {
234 padding-bottom: 5px;
236 td.hlist1 {
237 vertical-align: top;
238 font-style: italic;
239 padding-right: 0.8em;
241 td.hlist2 {
242 vertical-align: top;
245 @media print {
246 div#footer-badges { display: none; }
249 div#toctitle {
250 color: #527bbd;
251 font-family: sans-serif;
252 font-size: 1.1em;
253 font-weight: bold;
254 margin-top: 1.0em;
255 margin-bottom: 0.1em;
258 div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
259 margin-top: 0;
260 margin-bottom: 0;
262 div.toclevel2 {
263 margin-left: 2em;
264 font-size: 0.9em;
266 div.toclevel3 {
267 margin-left: 4em;
268 font-size: 0.9em;
270 div.toclevel4 {
271 margin-left: 6em;
272 font-size: 0.9em;
274 include1::./stylesheets/xhtml11-manpage.css[]
275 /* Workarounds for IE6's broken and incomplete CSS2. */
277 div.sidebar-content {
278 background: #ffffee;
279 border: 1px solid silver;
280 padding: 0.5em;
282 div.sidebar-title, div.image-title {
283 font-family: sans-serif;
284 font-weight: bold;
285 margin-top: 0.0em;
286 margin-bottom: 0.5em;
289 div.listingblock div.content {
290 border: 1px solid silver;
291 background: #f4f4f4;
292 padding: 0.5em;
295 div.quoteblock-content {
296 padding-left: 2.0em;
299 div.exampleblock-content {
300 border-left: 2px solid silver;
301 padding-left: 0.5em;
304 /* IE6 sets dynamically generated links as visited. */
305 div#toc a:visited { color: blue; }
306 </style>
307 <title>git-update-ref(1)</title>
308 </head>
309 <body>
310 <div id="header">
311 <h1>
312 git-update-ref(1) Manual Page
313 </h1>
314 <h2>NAME</h2>
315 <div class="sectionbody">
316 <p>git-update-ref -
317 Update the object name stored in a ref safely
318 </p>
319 </div>
320 </div>
321 <h2>SYNOPSIS</h2>
322 <div class="sectionbody">
323 <div class="para"><p><em>git update-ref</em> [-m &lt;reason&gt;] (-d &lt;ref&gt; [&lt;oldvalue&gt;] | [--no-deref] &lt;ref&gt; &lt;newvalue&gt; [&lt;oldvalue&gt;])</p></div>
324 </div>
325 <h2 id="_description">DESCRIPTION</h2>
326 <div class="sectionbody">
327 <div class="para"><p>Given two arguments, stores the &lt;newvalue&gt; in the &lt;ref&gt;, possibly
328 dereferencing the symbolic refs. E.g. <tt>git update-ref HEAD
329 &lt;newvalue&gt;</tt> updates the current branch head to the new object.</p></div>
330 <div class="para"><p>Given three arguments, stores the &lt;newvalue&gt; in the &lt;ref&gt;,
331 possibly dereferencing the symbolic refs, after verifying that
332 the current value of the &lt;ref&gt; matches &lt;oldvalue&gt;.
333 E.g. <tt>git update-ref refs/heads/master &lt;newvalue&gt; &lt;oldvalue&gt;</tt>
334 updates the master branch head to &lt;newvalue&gt; only if its current
335 value is &lt;oldvalue&gt;. You can specify 40 "0" or an empty string
336 as &lt;oldvalue&gt; to make sure that the ref you are creating does
337 not exist.</p></div>
338 <div class="para"><p>It also allows a "ref" file to be a symbolic pointer to another
339 ref file by starting with the four-byte header sequence of
340 "ref:".</p></div>
341 <div class="para"><p>More importantly, it allows the update of a ref file to follow
342 these symbolic pointers, whether they are symlinks or these
343 "regular file symbolic refs". It follows <strong>real</strong> symlinks only
344 if they start with "refs/": otherwise it will just try to read
345 them and update them as a regular file (i.e. it will allow the
346 filesystem to follow them, but will overwrite such a symlink to
347 somewhere else with a regular filename).</p></div>
348 <div class="para"><p>If --no-deref is given, &lt;ref&gt; itself is overwritten, rather than
349 the result of following the symbolic pointers.</p></div>
350 <div class="para"><p>In general, using</p></div>
351 <div class="literalblock">
352 <div class="content">
353 <pre><tt>git update-ref HEAD "$head"</tt></pre>
354 </div></div>
355 <div class="para"><p>should be a _lot_ safer than doing</p></div>
356 <div class="literalblock">
357 <div class="content">
358 <pre><tt>echo "$head" &gt; "$GIT_DIR/HEAD"</tt></pre>
359 </div></div>
360 <div class="para"><p>both from a symlink following standpoint <strong>and</strong> an error checking
361 standpoint. The "refs/" rule for symlinks means that symlinks
362 that point to "outside" the tree are safe: they'll be followed
363 for reading but not for writing (so we'll never write through a
364 ref symlink to some other tree, if you have copied a whole
365 archive by creating a symlink tree).</p></div>
366 <div class="para"><p>With <tt>-d</tt> flag, it deletes the named &lt;ref&gt; after verifying it
367 still contains &lt;oldvalue&gt;.</p></div>
368 </div>
369 <h2 id="_logging_updates">Logging Updates</h2>
370 <div class="sectionbody">
371 <div class="para"><p>If config parameter "core.logAllRefUpdates" is true or the file
372 "$GIT_DIR/logs/&lt;ref&gt;" exists then <tt>git update-ref</tt> will append
373 a line to the log file "$GIT_DIR/logs/&lt;ref&gt;" (dereferencing all
374 symbolic refs before creating the log name) describing the change
375 in ref value. Log lines are formatted as:</p></div>
376 <div class="olist"><ol>
377 <li>
379 oldsha1 SP newsha1 SP committer LF
380 </p>
381 <div class="para"><p>Where "oldsha1" is the 40 character hexadecimal value previously
382 stored in &lt;ref&gt;, "newsha1" is the 40 character hexadecimal value of
383 &lt;newvalue&gt; and "committer" is the committer's name, email address
384 and date in the standard GIT committer ident format.</p></div>
385 </li>
386 </ol></div>
387 <div class="para"><p>Optionally with -m:</p></div>
388 <div class="olist"><ol>
389 <li>
391 oldsha1 SP newsha1 SP committer TAB message LF
392 </p>
393 <div class="para"><p>Where all fields are as described above and "message" is the
394 value supplied to the -m option.</p></div>
395 </li>
396 </ol></div>
397 <div class="para"><p>An update will fail (without changing &lt;ref&gt;) if the current user is
398 unable to create a new log file, append to the existing log file
399 or does not have committer information available.</p></div>
400 </div>
401 <h2 id="_author">Author</h2>
402 <div class="sectionbody">
403 <div class="para"><p>Written by Linus Torvalds &lt;torvalds@osdl.org&gt;.</p></div>
404 </div>
405 <h2 id="_git">GIT</h2>
406 <div class="sectionbody">
407 <div class="para"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
408 </div>
409 <div id="footer">
410 <div id="footer-text">
411 Last updated 2009-12-03 09:12:51 UTC
412 </div>
413 </div>
414 </body>
415 </html>