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

From: Michael J Gruber <drmicha@warpmail.net>
Date: Mar 29, 2011, 18:36 UTC
Message-ID: <4D9226B4.20806@warpmail.net>
In-Reply-To: <7v7hbhss0g.fsf@alter.siamese.dyndns.org>

Junio C Hamano venit, vidit, dixit 29.03.2011 20:25:

Show 19 quoted lines

> 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!

Show 10 quoted lines

> 
> 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