Autogenerated HTML docs for v1.7.3-rc0-38-g9ab5a
[git/jnareb-git.git] / git-notes.html
blob4c03e6a6eb8284e7579389abc2394a3538e2cca4
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-notes(1)</title>
308 </head>
309 <body>
310 <div id="header">
311 <h1>
312 git-notes(1) Manual Page
313 </h1>
314 <h2>NAME</h2>
315 <div class="sectionbody">
316 <p>git-notes -
317 Add or inspect object notes
318 </p>
319 </div>
320 </div>
321 <h2>SYNOPSIS</h2>
322 <div class="sectionbody">
323 <div class="verseblock">
324 <div class="content"><em>git notes</em> [list [&lt;object&gt;]]
325 <em>git notes</em> add [-f] [-F &lt;file&gt; | -m &lt;msg&gt; | (-c | -C) &lt;object&gt;] [&lt;object&gt;]
326 <em>git notes</em> copy [-f] ( --stdin | &lt;from-object&gt; &lt;to-object&gt; )
327 <em>git notes</em> append [-F &lt;file&gt; | -m &lt;msg&gt; | (-c | -C) &lt;object&gt;] [&lt;object&gt;]
328 <em>git notes</em> edit [&lt;object&gt;]
329 <em>git notes</em> show [&lt;object&gt;]
330 <em>git notes</em> remove [&lt;object&gt;]
331 <em>git notes</em> prune [-n | -v]</div></div>
332 </div>
333 <h2 id="_description">DESCRIPTION</h2>
334 <div class="sectionbody">
335 <div class="para"><p>Adds, removes, or reads notes attached to objects, without touching
336 the objects themselves.</p></div>
337 <div class="para"><p>By default, notes are saved to and read from <tt>refs/notes/commits</tt>, but
338 this default can be overridden. See the OPTIONS, CONFIGURATION, and
339 ENVIRONMENT sections below. If this ref does not exist, it will be
340 quietly created when it is first needed to store a note.</p></div>
341 <div class="para"><p>A typical use of notes is to supplement a commit message without
342 changing the commit itself. Notes can be shown by <em>git log</em> along with
343 the original commit message. To distinguish these notes from the
344 message stored in the commit object, the notes are indented like the
345 message, after an unindented line saying "Notes (&lt;refname&gt;):" (or
346 "Notes:" for <tt>refs/notes/commits</tt>).</p></div>
347 <div class="para"><p>To change which notes are shown by <em>git log</em>, see the
348 "notes.displayRef" configuration in <a href="git-log.html">git-log(1)</a>.</p></div>
349 <div class="para"><p>See the "notes.rewrite.&lt;command&gt;" configuration for a way to carry
350 notes across commands that rewrite commits.</p></div>
351 </div>
352 <h2 id="_subcommands">SUBCOMMANDS</h2>
353 <div class="sectionbody">
354 <div class="vlist"><dl>
355 <dt>
356 list
357 </dt>
358 <dd>
360 List the notes object for a given object. If no object is
361 given, show a list of all note objects and the objects they
362 annotate (in the format "&lt;note object&gt; &lt;annotated object&gt;").
363 This is the default subcommand if no subcommand is given.
364 </p>
365 </dd>
366 <dt>
368 </dt>
369 <dd>
371 Add notes for a given object (defaults to HEAD). Abort if the
372 object already has notes (use <tt>-f</tt> to overwrite an
373 existing note).
374 </p>
375 </dd>
376 <dt>
377 copy
378 </dt>
379 <dd>
381 Copy the notes for the first object onto the second object.
382 Abort if the second object already has notes, or if the first
383 object has none (use -f to overwrite existing notes to the
384 second object). This subcommand is equivalent to:
385 <tt>git notes add [-f] -C $(git notes list &lt;from-object&gt;) &lt;to-object&gt;</tt>
386 </p>
387 <div class="para"><p>In <tt>--stdin</tt> mode, take lines in the format</p></div>
388 <div class="listingblock">
389 <div class="content">
390 <pre><tt>&lt;from-object&gt; SP &lt;to-object&gt; [ SP &lt;rest&gt; ] LF</tt></pre>
391 </div></div>
392 <div class="para"><p>on standard input, and copy the notes from each &lt;from-object&gt; to its
393 corresponding &lt;to-object&gt;. (The optional <tt>&lt;rest&gt;</tt> is ignored so that
394 the command can read the input given to the <tt>post-rewrite</tt> hook.)</p></div>
395 </dd>
396 <dt>
397 append
398 </dt>
399 <dd>
401 Append to the notes of an existing object (defaults to HEAD).
402 Creates a new notes object if needed.
403 </p>
404 </dd>
405 <dt>
406 edit
407 </dt>
408 <dd>
410 Edit the notes for a given object (defaults to HEAD).
411 </p>
412 </dd>
413 <dt>
414 show
415 </dt>
416 <dd>
418 Show the notes for a given object (defaults to HEAD).
419 </p>
420 </dd>
421 <dt>
422 remove
423 </dt>
424 <dd>
426 Remove the notes for a given object (defaults to HEAD).
427 This is equivalent to specifying an empty note message to
428 the <tt>edit</tt> subcommand.
429 </p>
430 </dd>
431 <dt>
432 prune
433 </dt>
434 <dd>
436 Remove all notes for non-existing/unreachable objects.
437 </p>
438 </dd>
439 </dl></div>
440 </div>
441 <h2 id="_options">OPTIONS</h2>
442 <div class="sectionbody">
443 <div class="vlist"><dl>
444 <dt>
446 </dt>
447 <dt>
448 --force
449 </dt>
450 <dd>
452 When adding notes to an object that already has notes,
453 overwrite the existing notes (instead of aborting).
454 </p>
455 </dd>
456 <dt>
457 -m &lt;msg&gt;
458 </dt>
459 <dt>
460 --message=&lt;msg&gt;
461 </dt>
462 <dd>
464 Use the given note message (instead of prompting).
465 If multiple <tt>-m</tt> options are given, their values
466 are concatenated as separate paragraphs.
467 Lines starting with <tt>#</tt> and empty lines other than a
468 single line between paragraphs will be stripped out.
469 </p>
470 </dd>
471 <dt>
472 -F &lt;file&gt;
473 </dt>
474 <dt>
475 --file=&lt;file&gt;
476 </dt>
477 <dd>
479 Take the note message from the given file. Use <em>-</em> to
480 read the note message from the standard input.
481 Lines starting with <tt>#</tt> and empty lines other than a
482 single line between paragraphs will be stripped out.
483 </p>
484 </dd>
485 <dt>
486 -C &lt;object&gt;
487 </dt>
488 <dt>
489 --reuse-message=&lt;object&gt;
490 </dt>
491 <dd>
493 Take the note message from the given blob object (for
494 example, another note).
495 </p>
496 </dd>
497 <dt>
498 -c &lt;object&gt;
499 </dt>
500 <dt>
501 --reedit-message=&lt;object&gt;
502 </dt>
503 <dd>
505 Like <em>-C</em>, but with <em>-c</em> the editor is invoked, so that
506 the user can further edit the note message.
507 </p>
508 </dd>
509 <dt>
510 --ref &lt;ref&gt;
511 </dt>
512 <dd>
514 Manipulate the notes tree in &lt;ref&gt;. This overrides
515 <em>GIT_NOTES_REF</em> and the "core.notesRef" configuration. The ref
516 is taken to be in <tt>refs/notes/</tt> if it is not qualified.
517 </p>
518 </dd>
519 <dt>
521 </dt>
522 <dt>
523 --dry-run
524 </dt>
525 <dd>
527 Do not remove anything; just report the object names whose notes
528 would be removed.
529 </p>
530 </dd>
531 <dt>
533 </dt>
534 <dt>
535 --verbose
536 </dt>
537 <dd>
539 Report all object names whose notes are removed.
540 </p>
541 </dd>
542 </dl></div>
543 </div>
544 <h2 id="_discussion">DISCUSSION</h2>
545 <div class="sectionbody">
546 <div class="para"><p>Commit notes are blobs containing extra information about an object
547 (usually information to supplement a commit's message). These blobs
548 are taken from notes refs. A notes ref is usually a branch which
549 contains "files" whose paths are the object names for the objects
550 they describe, with some directory separators included for performance
551 reasons <br />[Permitted pathnames have the form
552 <em>ab</em><tt>/</tt><em>cd</em><tt>/</tt><em>ef</em><tt>/</tt><em>&#8230;</em><tt>/</tt><em>abcdef&#8230;</em>: a sequence of directory
553 names of two hexadecimal digits each followed by a filename with the
554 rest of the object ID.]<br />.</p></div>
555 <div class="para"><p>Every notes change creates a new commit at the specified notes ref.
556 You can therefore inspect the history of the notes by invoking, e.g.,
557 <tt>git log -p notes/commits</tt>. Currently the commit message only records
558 which operation triggered the update, and the commit authorship is
559 determined according to the usual rules (see <a href="git-commit.html">git-commit(1)</a>).
560 These details may change in the future.</p></div>
561 <div class="para"><p>It is also permitted for a notes ref to point directly to a tree
562 object, in which case the history of the notes can be read with
563 <tt>git log -p -g &lt;refname&gt;</tt>.</p></div>
564 </div>
565 <h2 id="_examples">EXAMPLES</h2>
566 <div class="sectionbody">
567 <div class="para"><p>You can use notes to add annotations with information that was not
568 available at the time a commit was written.</p></div>
569 <div class="listingblock">
570 <div class="content">
571 <pre><tt>$ git notes add -m 'Tested-by: Johannes Sixt &lt;j6t@kdbg.org&gt;' 72a144e2
572 $ git show -s 72a144e
573 [...]
574 Signed-off-by: Junio C Hamano &lt;gitster@pobox.com&gt;
576 Notes:
577 Tested-by: Johannes Sixt &lt;j6t@kdbg.org&gt;</tt></pre>
578 </div></div>
579 <div class="para"><p>In principle, a note is a regular Git blob, and any kind of
580 (non-)format is accepted. You can binary-safely create notes from
581 arbitrary files using <em>git hash-object</em>:</p></div>
582 <div class="listingblock">
583 <div class="content">
584 <pre><tt>$ cc *.c
585 $ blob=$(git hash-object -w a.out)
586 $ git notes --ref=built add -C "$blob" HEAD</tt></pre>
587 </div></div>
588 <div class="para"><p>Of course, it doesn't make much sense to display non-text-format notes
589 with <em>git log</em>, so if you use such notes, you'll probably need to write
590 some special-purpose tools to do something useful with them.</p></div>
591 </div>
592 <h2 id="_configuration">CONFIGURATION</h2>
593 <div class="sectionbody">
594 <div class="vlist"><dl>
595 <dt>
596 core.notesRef
597 </dt>
598 <dd>
600 Notes ref to read and manipulate instead of
601 <tt>refs/notes/commits</tt>. Must be an unabbreviated ref name.
602 This setting can be overridden through the environment and
603 command line.
604 </p>
605 </dd>
606 <dt>
607 notes.displayRef
608 </dt>
609 <dd>
611 Which ref (or refs, if a glob or specified more than once), in
612 addition to the default set by <tt>core.notesRef</tt> or
613 <em>GIT_NOTES_REF</em>, to read notes from when showing commit
614 messages with the <em>git log</em> family of commands.
615 This setting can be overridden on the command line or by the
616 <em>GIT_NOTES_DISPLAY_REF</em> environment variable.
617 See <a href="git-log.html">git-log(1)</a>.
618 </p>
619 </dd>
620 <dt>
621 notes.rewrite.&lt;command&gt;
622 </dt>
623 <dd>
625 When rewriting commits with &lt;command&gt; (currently <tt>amend</tt> or
626 <tt>rebase</tt>), if this variable is <tt>false</tt>, git will not copy
627 notes from the original to the rewritten commit. Defaults to
628 <tt>true</tt>. See also "<tt>notes.rewriteRef</tt>" below.
629 </p>
630 <div class="para"><p>This setting can be overridden by the <em>GIT_NOTES_REWRITE_REF</em>
631 environment variable.</p></div>
632 </dd>
633 <dt>
634 notes.rewriteMode
635 </dt>
636 <dd>
638 When copying notes during a rewrite, what to do if the target
639 commit already has a note. Must be one of <tt>overwrite</tt>,
640 <tt>concatenate</tt>, and <tt>ignore</tt>. Defaults to <tt>concatenate</tt>.
641 </p>
642 <div class="para"><p>This setting can be overridden with the <tt>GIT_NOTES_REWRITE_MODE</tt>
643 environment variable.</p></div>
644 </dd>
645 <dt>
646 notes.rewriteRef
647 </dt>
648 <dd>
650 When copying notes during a rewrite, specifies the (fully
651 qualified) ref whose notes should be copied. May be a glob,
652 in which case notes in all matching refs will be copied. You
653 may also specify this configuration several times.
654 </p>
655 <div class="para"><p>Does not have a default value; you must configure this variable to
656 enable note rewriting.</p></div>
657 <div class="para"><p>Can be overridden with the <em>GIT_NOTES_REWRITE_REF</em> environment variable.</p></div>
658 </dd>
659 </dl></div>
660 </div>
661 <h2 id="_environment">ENVIRONMENT</h2>
662 <div class="sectionbody">
663 <div class="vlist"><dl>
664 <dt>
665 <em>GIT_NOTES_REF</em>
666 </dt>
667 <dd>
669 Which ref to manipulate notes from, instead of <tt>refs/notes/commits</tt>.
670 This overrides the <tt>core.notesRef</tt> setting.
671 </p>
672 </dd>
673 <dt>
674 <em>GIT_NOTES_DISPLAY_REF</em>
675 </dt>
676 <dd>
678 Colon-delimited list of refs or globs indicating which refs,
679 in addition to the default from <tt>core.notesRef</tt> or
680 <em>GIT_NOTES_REF</em>, to read notes from when showing commit
681 messages.
682 This overrides the <tt>notes.displayRef</tt> setting.
683 </p>
684 <div class="para"><p>A warning will be issued for refs that do not exist, but a glob that
685 does not match any refs is silently ignored.</p></div>
686 </dd>
687 <dt>
688 <em>GIT_NOTES_REWRITE_MODE</em>
689 </dt>
690 <dd>
692 When copying notes during a rewrite, what to do if the target
693 commit already has a note.
694 Must be one of <tt>overwrite</tt>, <tt>concatenate</tt>, and <tt>ignore</tt>.
695 This overrides the <tt>core.rewriteMode</tt> setting.
696 </p>
697 </dd>
698 <dt>
699 <em>GIT_NOTES_REWRITE_REF</em>
700 </dt>
701 <dd>
703 When rewriting commits, which notes to copy from the original
704 to the rewritten commit. Must be a colon-delimited list of
705 refs or globs.
706 </p>
707 <div class="para"><p>If not set in the environment, the list of notes to copy depends
708 on the <tt>notes.rewrite.&lt;command&gt;</tt> and <tt>notes.rewriteRef</tt> settings.</p></div>
709 </dd>
710 </dl></div>
711 </div>
712 <h2 id="_author">Author</h2>
713 <div class="sectionbody">
714 <div class="para"><p>Written by Johannes Schindelin &lt;johannes.schindelin@gmx.de&gt; and
715 Johan Herland &lt;johan@herland.net&gt;</p></div>
716 </div>
717 <h2 id="_documentation">Documentation</h2>
718 <div class="sectionbody">
719 <div class="para"><p>Documentation by Johannes Schindelin and Johan Herland</p></div>
720 </div>
721 <h2 id="_git">GIT</h2>
722 <div class="sectionbody">
723 <div class="para"><p>Part of the <a href="git.html">git(7)</a> suite</p></div>
724 </div>
725 <div id="footer">
726 <div id="footer-text">
727 Last updated 2010-09-03 21:30:24 UTC
728 </div>
729 </div>
730 </body>
731 </html>