Autogenerated HTML docs for v1.7.6-345-g5c2f8
[git/jnareb-git.git] / git-update-ref.html
blob3b1afbb1d427eb02075cc9d495d58d01aeae273e
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.4.5" />
7 <title>git-update-ref(1)</title>
8 <style type="text/css">
9 /* Debug borders */
10 p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
12 border: 1px solid red;
16 body {
17 margin: 1em 5% 1em 5%;
20 a {
21 color: blue;
22 text-decoration: underline;
24 a:visited {
25 color: fuchsia;
28 em {
29 font-style: italic;
30 color: navy;
33 strong {
34 font-weight: bold;
35 color: #083194;
38 tt {
39 color: navy;
42 h1, h2, h3, h4, h5, h6 {
43 color: #527bbd;
44 font-family: sans-serif;
45 margin-top: 1.2em;
46 margin-bottom: 0.5em;
47 line-height: 1.3;
50 h1, h2, h3 {
51 border-bottom: 2px solid silver;
53 h2 {
54 padding-top: 0.5em;
56 h3 {
57 float: left;
59 h3 + * {
60 clear: left;
63 div.sectionbody {
64 font-family: serif;
65 margin-left: 0;
68 hr {
69 border: 1px solid silver;
72 p {
73 margin-top: 0.5em;
74 margin-bottom: 0.5em;
77 ul, ol, li > p {
78 margin-top: 0;
81 pre {
82 padding: 0;
83 margin: 0;
86 span#author {
87 color: #527bbd;
88 font-family: sans-serif;
89 font-weight: bold;
90 font-size: 1.1em;
92 span#email {
94 span#revnumber, span#revdate, span#revremark {
95 font-family: sans-serif;
98 div#footer {
99 font-family: sans-serif;
100 font-size: small;
101 border-top: 2px solid silver;
102 padding-top: 0.5em;
103 margin-top: 4.0em;
105 div#footer-text {
106 float: left;
107 padding-bottom: 0.5em;
109 div#footer-badges {
110 float: right;
111 padding-bottom: 0.5em;
114 div#preamble {
115 margin-top: 1.5em;
116 margin-bottom: 1.5em;
118 div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
119 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
120 div.admonitionblock {
121 margin-top: 1.5em;
122 margin-bottom: 1.5em;
124 div.admonitionblock {
125 margin-top: 2.5em;
126 margin-bottom: 2.5em;
129 div.content { /* Block element content. */
130 padding: 0;
133 /* Block element titles. */
134 div.title, caption.title {
135 color: #527bbd;
136 font-family: sans-serif;
137 font-weight: bold;
138 text-align: left;
139 margin-top: 1.0em;
140 margin-bottom: 0.5em;
142 div.title + * {
143 margin-top: 0;
146 td div.title:first-child {
147 margin-top: 0.0em;
149 div.content div.title:first-child {
150 margin-top: 0.0em;
152 div.content + div.title {
153 margin-top: 0.0em;
156 div.sidebarblock > div.content {
157 background: #ffffee;
158 border: 1px solid silver;
159 padding: 0.5em;
162 div.listingblock > div.content {
163 border: 1px solid silver;
164 background: #f4f4f4;
165 padding: 0.5em;
168 div.quoteblock {
169 padding-left: 2.0em;
170 margin-right: 10%;
172 div.quoteblock > div.attribution {
173 padding-top: 0.5em;
174 text-align: right;
177 div.verseblock {
178 padding-left: 2.0em;
179 margin-right: 10%;
181 div.verseblock > div.content {
182 white-space: pre;
184 div.verseblock > div.attribution {
185 padding-top: 0.75em;
186 text-align: left;
188 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
189 div.verseblock + div.attribution {
190 text-align: left;
193 div.admonitionblock .icon {
194 vertical-align: top;
195 font-size: 1.1em;
196 font-weight: bold;
197 text-decoration: underline;
198 color: #527bbd;
199 padding-right: 0.5em;
201 div.admonitionblock td.content {
202 padding-left: 0.5em;
203 border-left: 2px solid silver;
206 div.exampleblock > div.content {
207 border-left: 2px solid silver;
208 padding: 0.5em;
211 div.imageblock div.content { padding-left: 0; }
212 span.image img { border-style: none; }
213 a.image:visited { color: white; }
215 dl {
216 margin-top: 0.8em;
217 margin-bottom: 0.8em;
219 dt {
220 margin-top: 0.5em;
221 margin-bottom: 0;
222 font-style: normal;
223 color: navy;
225 dd > *:first-child {
226 margin-top: 0.1em;
229 ul, ol {
230 list-style-position: outside;
232 ol.arabic {
233 list-style-type: decimal;
235 ol.loweralpha {
236 list-style-type: lower-alpha;
238 ol.upperalpha {
239 list-style-type: upper-alpha;
241 ol.lowerroman {
242 list-style-type: lower-roman;
244 ol.upperroman {
245 list-style-type: upper-roman;
248 div.compact ul, div.compact ol,
249 div.compact p, div.compact p,
250 div.compact div, div.compact div {
251 margin-top: 0.1em;
252 margin-bottom: 0.1em;
255 div.tableblock > table {
256 border: 3px solid #527bbd;
258 thead {
259 font-family: sans-serif;
260 font-weight: bold;
262 tfoot {
263 font-weight: bold;
265 td > div.verse {
266 white-space: pre;
268 p.table {
269 margin-top: 0;
271 /* Because the table frame attribute is overriden by CSS in most browsers. */
272 div.tableblock > table[frame="void"] {
273 border-style: none;
275 div.tableblock > table[frame="hsides"] {
276 border-left-style: none;
277 border-right-style: none;
279 div.tableblock > table[frame="vsides"] {
280 border-top-style: none;
281 border-bottom-style: none;
285 div.hdlist {
286 margin-top: 0.8em;
287 margin-bottom: 0.8em;
289 div.hdlist tr {
290 padding-bottom: 15px;
292 dt.hdlist1.strong, td.hdlist1.strong {
293 font-weight: bold;
295 td.hdlist1 {
296 vertical-align: top;
297 font-style: normal;
298 padding-right: 0.8em;
299 color: navy;
301 td.hdlist2 {
302 vertical-align: top;
304 div.hdlist.compact tr {
305 margin: 0;
306 padding-bottom: 0;
309 .comment {
310 background: yellow;
313 @media print {
314 div#footer-badges { display: none; }
317 div#toctitle {
318 color: #527bbd;
319 font-family: sans-serif;
320 font-size: 1.1em;
321 font-weight: bold;
322 margin-top: 1.0em;
323 margin-bottom: 0.1em;
326 div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
327 margin-top: 0;
328 margin-bottom: 0;
330 div.toclevel2 {
331 margin-left: 2em;
332 font-size: 0.9em;
334 div.toclevel3 {
335 margin-left: 4em;
336 font-size: 0.9em;
338 div.toclevel4 {
339 margin-left: 6em;
340 font-size: 0.9em;
342 /* Overrides for manpage documents */
343 h1 {
344 padding-top: 0.5em;
345 padding-bottom: 0.5em;
346 border-top: 2px solid silver;
347 border-bottom: 2px solid silver;
349 h2 {
350 border-style: none;
352 div.sectionbody {
353 margin-left: 5%;
356 @media print {
357 div#toc { display: none; }
360 /* Workarounds for IE6's broken and incomplete CSS2. */
362 div.sidebar-content {
363 background: #ffffee;
364 border: 1px solid silver;
365 padding: 0.5em;
367 div.sidebar-title, div.image-title {
368 color: #527bbd;
369 font-family: sans-serif;
370 font-weight: bold;
371 margin-top: 0.0em;
372 margin-bottom: 0.5em;
375 div.listingblock div.content {
376 border: 1px solid silver;
377 background: #f4f4f4;
378 padding: 0.5em;
381 div.quoteblock-attribution {
382 padding-top: 0.5em;
383 text-align: right;
386 div.verseblock-content {
387 white-space: pre;
389 div.verseblock-attribution {
390 padding-top: 0.75em;
391 text-align: left;
394 div.exampleblock-content {
395 border-left: 2px solid silver;
396 padding-left: 0.5em;
399 /* IE6 sets dynamically generated links as visited. */
400 div#toc a:visited { color: blue; }
401 </style>
402 </head>
403 <body>
404 <div id="header">
405 <h1>
406 git-update-ref(1) Manual Page
407 </h1>
408 <h2>NAME</h2>
409 <div class="sectionbody">
410 <p>git-update-ref -
411 Update the object name stored in a ref safely
412 </p>
413 </div>
414 </div>
415 <h2 id="_synopsis">SYNOPSIS</h2>
416 <div class="sectionbody">
417 <div class="verseblock">
418 <div class="verseblock-content"><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;])</div>
419 <div class="verseblock-attribution">
420 </div></div>
421 </div>
422 <h2 id="_description">DESCRIPTION</h2>
423 <div class="sectionbody">
424 <div class="paragraph"><p>Given two arguments, stores the &lt;newvalue&gt; in the &lt;ref&gt;, possibly
425 dereferencing the symbolic refs. E.g. <tt>git update-ref HEAD
426 &lt;newvalue&gt;</tt> updates the current branch head to the new object.</p></div>
427 <div class="paragraph"><p>Given three arguments, stores the &lt;newvalue&gt; in the &lt;ref&gt;,
428 possibly dereferencing the symbolic refs, after verifying that
429 the current value of the &lt;ref&gt; matches &lt;oldvalue&gt;.
430 E.g. <tt>git update-ref refs/heads/master &lt;newvalue&gt; &lt;oldvalue&gt;</tt>
431 updates the master branch head to &lt;newvalue&gt; only if its current
432 value is &lt;oldvalue&gt;. You can specify 40 "0" or an empty string
433 as &lt;oldvalue&gt; to make sure that the ref you are creating does
434 not exist.</p></div>
435 <div class="paragraph"><p>It also allows a "ref" file to be a symbolic pointer to another
436 ref file by starting with the four-byte header sequence of
437 "ref:".</p></div>
438 <div class="paragraph"><p>More importantly, it allows the update of a ref file to follow
439 these symbolic pointers, whether they are symlinks or these
440 "regular file symbolic refs". It follows <strong>real</strong> symlinks only
441 if they start with "refs/": otherwise it will just try to read
442 them and update them as a regular file (i.e. it will allow the
443 filesystem to follow them, but will overwrite such a symlink to
444 somewhere else with a regular filename).</p></div>
445 <div class="paragraph"><p>If --no-deref is given, &lt;ref&gt; itself is overwritten, rather than
446 the result of following the symbolic pointers.</p></div>
447 <div class="paragraph"><p>In general, using</p></div>
448 <div class="literalblock">
449 <div class="content">
450 <pre><tt>git update-ref HEAD "$head"</tt></pre>
451 </div></div>
452 <div class="paragraph"><p>should be a <em>lot</em> safer than doing</p></div>
453 <div class="literalblock">
454 <div class="content">
455 <pre><tt>echo "$head" &gt; "$GIT_DIR/HEAD"</tt></pre>
456 </div></div>
457 <div class="paragraph"><p>both from a symlink following standpoint <strong>and</strong> an error checking
458 standpoint. The "refs/" rule for symlinks means that symlinks
459 that point to "outside" the tree are safe: they&#8217;ll be followed
460 for reading but not for writing (so we&#8217;ll never write through a
461 ref symlink to some other tree, if you have copied a whole
462 archive by creating a symlink tree).</p></div>
463 <div class="paragraph"><p>With <tt>-d</tt> flag, it deletes the named &lt;ref&gt; after verifying it
464 still contains &lt;oldvalue&gt;.</p></div>
465 </div>
466 <h2 id="_logging_updates">Logging Updates</h2>
467 <div class="sectionbody">
468 <div class="paragraph"><p>If config parameter "core.logAllRefUpdates" is true and the ref is one under
469 "refs/heads/", "refs/remotes/", "refs/notes/", or the symbolic ref HEAD; or
470 the file "$GIT_DIR/logs/&lt;ref&gt;" exists then <tt>git update-ref</tt> will append
471 a line to the log file "$GIT_DIR/logs/&lt;ref&gt;" (dereferencing all
472 symbolic refs before creating the log name) describing the change
473 in ref value. Log lines are formatted as:</p></div>
474 <div class="olist arabic"><ol class="arabic">
475 <li>
477 oldsha1 SP newsha1 SP committer LF
478 </p>
479 <div class="paragraph"><p>Where "oldsha1" is the 40 character hexadecimal value previously
480 stored in &lt;ref&gt;, "newsha1" is the 40 character hexadecimal value of
481 &lt;newvalue&gt; and "committer" is the committer&#8217;s name, email address
482 and date in the standard GIT committer ident format.</p></div>
483 </li>
484 </ol></div>
485 <div class="paragraph"><p>Optionally with -m:</p></div>
486 <div class="olist arabic"><ol class="arabic">
487 <li>
489 oldsha1 SP newsha1 SP committer TAB message LF
490 </p>
491 <div class="paragraph"><p>Where all fields are as described above and "message" is the
492 value supplied to the -m option.</p></div>
493 </li>
494 </ol></div>
495 <div class="paragraph"><p>An update will fail (without changing &lt;ref&gt;) if the current user is
496 unable to create a new log file, append to the existing log file
497 or does not have committer information available.</p></div>
498 </div>
499 <h2 id="_git">GIT</h2>
500 <div class="sectionbody">
501 <div class="paragraph"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
502 </div>
503 <div id="footer">
504 <div id="footer-text">
505 Last updated 2011-07-23 00:49:30 UTC
506 </div>
507 </div>
508 </body>
509 </html>