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

[Michael J Gruber <drmicha@warpmail.net>]

Junio C Hamano venit, vidit, dixit 29.03.2011 20:25:
> Junio C Hamano <gitster@pobox.com> writes:
> 
>> Michael J Gruber <git@drmicha.warpmail.net> writes:
>>
>>> 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 <git@drmicha.warpmail.net>
>>> ---
>>> In fact, the long name '--reuse-message' is really misleading, but I've been
>>> around long enough to refrain from trying to change it ;)
>>
>> Yeah, it utterly is broken.  Why not fix it before people start making
>> serious use of notes?

You seriously ask why? Because I've banged my head way to often by
suggesting behavior changes!

> 
> Actually I take it back and throw it again after doubling it.  Not just
> the long name, but using -C/-c is already utterly broken.  These are meant
> to reuse (meta)data associated with an existing object, not using some
> data that happens to be stored in a random loose blob.  I don't think of
> any similar option anywhere in git.
> 
> Instead of mucking with the documentation, why not fix the behaviour to
> match what -C/-c/--reuse usually means, which is what the documentation
> describes?

Because it's not what the doc describes. The current version is easy to
misunderstand, but in connection with the example it is clear how it is
meant, and that's how it is implemented. If I were to reimplement it I
would:

- make "notes add -C/-c" really analogous to "commit -c/-C", i.e. do
"notes copy"

- make -F binary safe

and while at it rename "add" to "edit", because I've been bitten too
often by trying to add to a note using the "add" command. But all these
are behavior changes/incompatibilities, i.e. a no-go.

I don't mean to criticize the initial implementation of "notes", it just
shows that we detect rough ui edges only after using a feature. I'm all
for changes, I just rarely can get myself to making a hopeless feature
change patch any more.

Michael