[PATCH 2/8] Documentation/notes: describe content of notes blobs
- From
Jonathan Nieder <jrnieder@gmail.com>
- Date
- May 9, 2010, 03:21 UTC
- Message-ID
- <20100509032134.GB7958@progeny.tock>
- In-Reply-To
- <20100509031357.GA7926@progeny.tock>
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> --- Documentation/git-notes.txt | 38 +++++++++++++++++++++++++++++++++++++- t/t3307-notes-man.sh | 38 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 75 insertions(+), 1 deletions(-) create mode 100755 t/t3307-notes-man.sh
diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index af12c3c..97b9d81 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -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 diff --git a/t/t3307-notes-man.sh b/t/t3307-notes-man.sh new file mode 100755 index 0000000..3269f2e --- /dev/null +++ b/t/t3307-notes-man.sh @@ -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
-- 1.7.1