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>
This commit is contained in:
Jonathan Nieder 2010-05-08 22:21:34 -05:00 коммит произвёл Junio C Hamano
Родитель 9eb3f816de
Коммит 8d6888ec6a
2 изменённых файлов: 75 добавлений и 1 удалений

Просмотреть файл

@ -101,15 +101,20 @@ OPTIONS
Use the given note message (instead of prompting).
If multiple `-m` options are given, their values
are concatenated as separate paragraphs.
Lines starting with `#` and empty lines other than a
single line between paragraphs will be stripped out.
-F <file>::
--file=<file>::
Take the note message from the given file. Use '-' to
read the note message from the standard input.
Lines starting with `#` and empty lines other than a
single line between paragraphs will be stripped out.
-C <object>::
--reuse-message=<object>::
Reuse the note message from the given note object.
Take the note message from the given blob object (for
example, another note).
-c <object>::
--reedit-message=<object>::
@ -147,6 +152,37 @@ object, in which case the history of the notes can be read with
`git log -p -g <refname>`.
EXAMPLES
--------
You can use notes to add annotations with information that was not
available at the time a commit was written.
------------
$ git notes add -m 'Tested-by: Johannes Sixt <j6t@kdbg.org>' 72a144e2
$ git show -s 72a144e
[...]
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Notes:
Tested-by: Johannes Sixt <j6t@kdbg.org>
------------
In principle, a note is a regular Git blob, and any kind of
(non-)format is accepted. You can binary-safely create notes from
arbitrary files using 'git hash-object':
------------
$ cc *.c
$ blob=$(git hash-object -w a.out)
$ git notes --ref=built add -C "$blob" HEAD
------------
Of course, it doesn't make much sense to display non-text-format notes
with 'git log', so if you use such notes, you'll probably need to write
some special-purpose tools to do something useful with them.
Author
------
Written by Johannes Schindelin <johannes.schindelin@gmx.de> and

38
t/t3307-notes-man.sh Executable file
Просмотреть файл

@ -0,0 +1,38 @@
#!/bin/sh
test_description='Examples from the git-notes man page
Make sure the manual is not full of lies.'
. ./test-lib.sh
test_expect_success 'setup' '
test_commit A &&
test_commit B &&
test_commit C
'
test_expect_success 'example 1: notes to add an Acked-by line' '
cat <<-\EOF >expect &&
B
Notes:
Acked-by: A C Ker <acker@example.com>
EOF
git notes add -m "Acked-by: A C Ker <acker@example.com>" B &&
git show -s B^{commit} >log &&
tail -n 4 log >actual &&
test_cmp expect actual
'
test_expect_success 'example 2: binary notes' '
cp "$TEST_DIRECTORY"/test4012.png .
git checkout B &&
blob=$(git hash-object -w test4012.png) &&
git notes --ref=logo add -C "$blob" &&
git notes --ref=logo copy B C &&
git notes --ref=logo show C >actual &&
test_cmp test4012.png actual
'
test_done