From 8d6888ec6aee97f8b2b395e7e075dd00d9689c25 Mon Sep 17 00:00:00 2001 From: Jonathan Nieder Date: Sat, 8 May 2010 22:21:34 -0500 Subject: [PATCH] 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 ) Explain this trick (thanks, Johan!) in the manual. Add an ordinary example, too, to keep this esoteric one company. Cc: Johan Herland Cc: Thomas Rast Cc: Jeff King Signed-off-by: Jonathan Nieder Signed-off-by: Junio C Hamano --- Documentation/git-notes.txt | 38 ++++++++++++++++++++++++++++++++++++- t/t3307-notes-man.sh | 38 +++++++++++++++++++++++++++++++++++++ 2 files changed, 75 insertions(+), 1 deletion(-) create mode 100755 t/t3307-notes-man.sh diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index af12c3c9e..97b9d81e2 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=:: 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 :: --reuse-message=:: - Reuse the note message from the given note object. + Take the note message from the given blob object (for + example, another note). -c :: --reedit-message=:: @@ -147,6 +152,37 @@ object, in which case the history of the notes can be read with `git log -p -g `. +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 ' 72a144e2 +$ git show -s 72a144e +[...] + Signed-off-by: Junio C Hamano + +Notes: + Tested-by: Johannes Sixt +------------ + +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 and diff --git a/t/t3307-notes-man.sh b/t/t3307-notes-man.sh new file mode 100755 index 000000000..3269f2eeb --- /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 + EOF + git notes add -m "Acked-by: A C Ker " 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 -- 2.26.2