Documentation/notes: describe content of notes blobs
stripspace/text-based formatting kicks in when specifying the notes content with -m or -F, or when an editor is used to edit the notes. To binary-safely create notes from files, the following construct is required: git notes add -C $(git hash-object -w <file>) <object> Explain this trick (thanks, Johan!) in the manual. Add an ordinary example, too, to keep this esoteric one company. Cc: Johan Herland <johan@herland.net> Cc: Thomas Rast <trast@student.ethz.ch> Cc: Jeff King <peff@peff.net> Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Jonathan Nieder committed
May 8, 2010 at 22:21 UTC
8d6888ec6aee97f8b2b395e7e075dd00d9689c25
2 files changed
+75
-1
Documentation/git-notes.txt
+37
-1
@@ -101,15 +101,20 @@ OPTIONS
101
Use the given note message (instead of prompting).
102
If multiple `-m` options are given, their values
103
are concatenated as separate paragraphs.
104
+ Lines starting with `#` and empty lines other than a
105
+ single line between paragraphs will be stripped out.
106
107
-F <file>::
108
--file=<file>::
109
Take the note message from the given file. Use '-' to
110
read the note message from the standard input.
111
+ Lines starting with `#` and empty lines other than a
112
+ single line between paragraphs will be stripped out.
113
114
-C <object>::
115
--reuse-message=<object>::
112
- Reuse the note message from the given note object.
116
+ Take the note message from the given blob object (for
117
+ example, another note).
118
119
-c <object>::
120
--reedit-message=<object>::
@@ -147,6 +152,37 @@ object, in which case the history of the notes can be read with
152
`git log -p -g <refname>`.
153
154
155
+EXAMPLES
156
+--------
157
+
158
+You can use notes to add annotations with information that was not
159
+available at the time a commit was written.
160
+
161
+------------
162
+$ git notes add -m 'Tested-by: Johannes Sixt <j6t@kdbg.org>' 72a144e2
163
+$ git show -s 72a144e
164
+[...]
165
+ Signed-off-by: Junio C Hamano <gitster@pobox.com>
166
+
167
+Notes:
168
+ Tested-by: Johannes Sixt <j6t@kdbg.org>
169
+------------
170
+
171
+In principle, a note is a regular Git blob, and any kind of
172
+(non-)format is accepted. You can binary-safely create notes from
173
+arbitrary files using 'git hash-object':
174
+
175
+------------
176
+$ cc *.c
177
+$ blob=$(git hash-object -w a.out)
178
+$ git notes --ref=built add -C "$blob" HEAD
179
+------------
180
+
181
+Of course, it doesn't make much sense to display non-text-format notes
182
+with 'git log', so if you use such notes, you'll probably need to write
183
+some special-purpose tools to do something useful with them.
184
+
185
+
186
Author
187
------
188
Written by Johannes Schindelin <johannes.schindelin@gmx.de> and
t/t3307-notes-man.sh
new
+38
@@ -0,0 +1,38 @@
1
+#!/bin/sh
2
+
3
+test_description='Examples from the git-notes man page
4
+
5
+Make sure the manual is not full of lies.'
6
+
7
+. ./test-lib.sh
8
+
9
+test_expect_success 'setup' '
10
+ test_commit A &&
11
+ test_commit B &&
12
+ test_commit C
13
+'
14
+
15
+test_expect_success 'example 1: notes to add an Acked-by line' '
16
+ cat <<-\EOF >expect &&
17
+ B
18
+
19
+ Notes:
20
+ Acked-by: A C Ker <acker@example.com>
21
+ EOF
22
+ git notes add -m "Acked-by: A C Ker <acker@example.com>" B &&
23
+ git show -s B^{commit} >log &&
24
+ tail -n 4 log >actual &&
25
+ test_cmp expect actual
26
+'
27
+
28
+test_expect_success 'example 2: binary notes' '
29
+ cp "$TEST_DIRECTORY"/test4012.png .
30
+ git checkout B &&
31
+ blob=$(git hash-object -w test4012.png) &&
32
+ git notes --ref=logo add -C "$blob" &&
33
+ git notes --ref=logo copy B C &&
34
+ git notes --ref=logo show C >actual &&
35
+ test_cmp test4012.png actual
36
+'
37
+
38
+test_done