On Wednesday 30 March 2011, Michael J Gruber wrote:
> I'm still wondering how large a
> change we're aiming at, given Junio's remarks. Things I would like to
> throw in:
>
> * options vs. arguments:
>
> "tag", "branch" etc. use options for subcommands, e.g. "tag -d", "branch
> -d" etc. "remote", "stash" use arguments, e.g. "remote add", "stash
> list". I don't see us unifying that, but we should decide about a
> direction to go for "new" commands and stick to that. I feel that
> options are the way to go. What I really feel strongly about is that we
> should decide once and then stick to that for future commands (and may
> be gradually revamping).
This is a big discussion, and I don't really have a strong opinion either
way (or on whether unification of options vs. arguments is really necessary
at all). In general, I like separating the "verb" of the command (_what_ to
do) from the "adverbs" (_how_ to do it). For some git commands, the verb is
right there in the name (e.g. "checkout", "add", "rm", etc.), so the options
are usually all "adverbs". Other commands, however, refer to one of git's
"subsystems" (for some very vague definition of "subsystem") as a "noun"
(e.g. "stash", "remote", "notes"), and the verb needs to be specified
(either as a subcommand, or as an option). In those cases, I personally
prefer the subcommand approach ("git noun verb --adverb") better than the
option approach ("git noun --verb --adverb"), so as to separate the verb
from the adverbs.
However, some commands (e.g. "branch", "tag") are _both_ "verbs" ("I want to
tag something") and "nouns" ("I want to add a tag"). By now, I'm thoroughly
used to "branch -d" and "tag -d", so e.g. "branch rm" and "tag rm" look a
bit foreign to me, although they probably follow the above principle more
closely...
Then you have weird cases that further complicate things: "rebase" is
usually a verb, but in "rebase --continue" or "rebase --abort" another verb
takes the focus, and I would probably prefer them as subcommands ("rebase
continue" and "rebase abort").
What can I say? Habits are hard to break, and this might be a case where
breaking them is more harmful than a somewhat messy command-line interface.
> * singular vs. plural:
>
> All our porcelain commands are singular even when they deal with
> multiple items (tag, branch, remote, submodule, ...). "notes" is the
> only exception, why not have it be "note"? (That would also open up a
> migration strategy, though the usual suspects may not even bother ;))
True, but would you want to use "note" as a verb or a noun?
Verb:
$ git note # to add/edit a note
$ git note -d # to remove a note
etc.
Noun:
$ git note add # to add/edit a note
$ git note rm # to remove a note
etc.
> * "notes message":
>
> The term seems to be used to distinguish between the content of a note
> and the note object (blob content vs. blob object). A regular git user
> may think it is the commit message in the notes log, i.e.:
>
> git log $(git notes get-ref)
>
> I'm wondering whether we should actually expose those note commit
> messages. If notes are shared then editing a note may require an
> explanation just like other commits do, especially when they get used
> for other things than "notes" in the proper sense.
>
> If we do that, then -m,-c,-C etc. would need to be analogous to "git
> commit -m,-c,-C", i.e. about note commit messages, not about the actual
> note. If we completely discard the possibility that users will look at
> the notes log and write note commit messages, we can use the "regular
> commit message <-> notes content" analogy for the options that we
> partially have now (and adjust -c,-C).
Interesting. Originally, I think "notes message" comes from the initial use
case of notes being an extension of the commit message. The "notes message"
is therefore what is shown next to the commit message, i.e. the blob
content. From that POV, the --reuse-message/--reedit-message options also
make some sense.
But it is apparent by now that simply extending the commit message will
probably not be the central use case for notes, and I agree that it makes
sense to revisit the terminology (both in the documentation and the options
themselves.)
As you say, -m/-c/-C should probably change to affect the commit message of
the note commit (and not affect the note content). I'm unsure whether -F
should follow along, or if we should reserve that for supplying note content
(binary-safely). I think I prefer the former, and would want a different
option for getting note contents from a file.
Obviously, copying notes from one object to another is covered by "git notes
copy", but I wonder if it still makes sense to provide a way to get note
contents from an existing blob SHA1 (i.e. what -c/-C does today).
Have fun! :)
...Johan
--
Johan Herland, <johan@xxxxxxxxxxx>
www.herland.net
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html