[PATCH] git-notes.txt: clarify -C vs. copy and -F

The current description of '-C' together with the analogy to 'git commit
-C' can lead to the wrong conclusion that '-C' copies notes between
objects. Make this clearer by rewording and pointing to 'copy'.

The example for attaching binary notes with 'git hash-object' followed
by 'git notes add -C' immediately raises the question: "Why not use 'git
notes add -F'?". Answer it (the latter is not binary-safe).

Signed-off-by: Michael J Gruber <redacted>
---
In fact, the long name '--reuse-message' is really misleading, but I've been
around long enough to refrain from trying to change it ;)

 Documentation/git-notes.txt |    7 +++++--
 1 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
index 296f314..c63b593 100644
--- a/Documentation/git-notes.txt
+++ b/Documentation/git-notes.txt

@@ -138,8 +138,9 @@ OPTIONS
 
 -C <object>::
 --reuse-message=<object>::
-	Take the note message from the given blob object (for
-	example, another note).
+	Take the given blob object (for	example, another note) as the
+	note message. (Use `git notes copy <object>` instead to
+	copy notes between objects.) 
 
 -c <object>::
 --reedit-message=<object>::

@@ -272,6 +273,8 @@ $ blob=$(git hash-object -w a.out)
 $ git notes --ref=built add -C "$blob" HEAD
 ------------
 
+(You cannot simply use `git notes --ref=built add -F a.out HEAD`
+because that is not binary-safe.)
 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.

-- 
1.7.4.1.607.g888da

On Tuesday 29 March 2011, Michael J Gruber wrote:

The current description of '-C' together with the analogy to 'git
commit -C' can lead to the wrong conclusion that '-C' copies notes
between objects. Make this clearer by rewording and pointing to
'copy'.

The example for attaching binary notes with 'git hash-object'
followed by 'git notes add -C' immediately raises the question: "Why
not use 'git notes add -F'?". Answer it (the latter is not
binary-safe).

Signed-off-by: Michael J Gruber <redacted>

Acked-by: Johan Herland <redacted>


...Johan

-- 
Johan Herland, [off-list ref]
www.herland.net