Please unhide some hidden commands

[Eli Zaretskii]

I suggest that the following hidden commands be "unhidden", because they seem very useful and neither debugging nor developer-oriented:

added
bundle-info
file-id
find-merge-base
inventory
lookup-revision
modified
revision-info

[Jelmer Vernooij (jelmer)]

Hi Eli,

I don't agree these are not developer/debug commands, as they all deal with bzr internals (file ids and revision ids). Every unhidden command means making the list of commands new users are confronted with longer, so I think we should be careful what we add. That said, perhaps there is use in making some of these debug commands visible.

IIRC added and modified overlap with functionality already available elsewhere, and they are up for deletion. inventory has (at least as normal users are concerned) the same functionality as ls.

"bundle-info" ideally should be merged into "info".

I would argue that lookup-revision, find-merge-base, revision-info and file-id are developer-oriented or debugging commands. In normal use, users should never have to touch them. last revision information is already available in the form of "bzr revno" and "bzr version-info".

[Eli Zaretskii (eliz)]

I see your point about adding confusion for new users, and I agree.

However, please note that commands are not just for new users. Veteran users that are not bzr developers are also worthy of being catered to by bzr...

Also, when you say these commands are fo debugging, you probably mean that this is how they cam into existence. While that is probably true, I would argue that once they do exist, their fate should be decided by their utility for mere mortals, not by the historical curiosities.

Now for the specific points you made.

Commands slated for deletion of course don't need to be documented.

Merging this hidden functionality with existing non-hidden commands is also an okay solution.

lookup-revision and revision-info are handy for showing revision-id given a revno and vice versa. I don't see how "revno" or "version-info" can help here, except for the current tip revision. Am I missing something?

Likewise for find-merge-base and file-id: what other commands can show this information? I agree that this info is probably needed only rarely, but what's wrong with advertising rarely used commands?

[Vincent Ladeuil (vila)]

>>>>> Eli Zaretskii writes:

    > I see your point about adding confusion for new users, and I
    > agree. However, please note that commands are not just for new
    > users. Veteran users that are not bzr developers are also worthy
    > of being catered to by bzr...

Right, that's exactly where *I* (the feeling may be shared or not, I
never asked) have some hesitations about revealing them: they tend to be
lest tested and are certainly not supported as the other commands. If an
implementation change break them, we may just decide to delete them.

    > Also, when you say these commands are fo debugging, you probably
    > mean that this is how they cam into existence.

Mostly, AFAIK.

    > While that is probably true, I would argue that once they do
    > exist, their fate should be decided by their utility for mere
    > mortals, not by the historical curiosities.

This is open to debate indeed,

    > Now for the specific points you made.

    > Commands slated for deletion of course don't need to be
    > documented.

As said above, we may change our mind faster on the hidden commands...

    > Merging this hidden functionality with existing non-hidden
    > commands is also an okay solution.

As jelmer mentioned, this is really what we want to do for 'added' and
such: enhance ls so they become useless.

    > lookup-revision

1 test, but the code is trivial too.

    > and revision-info

Better coverage but tested only against the default format. Ad-hoc, but
may fail with older formats without notice (though if it fail, that
would probably be for a new format and may be fixed for all formats at
that point).

It's also ~designed to accept a revision not in the branch ancestry

    > are handy for showing revision-id given a revno and vice versa. I
    > don't see how "revno" or "version-info" can help here, except for
    > the current tip revision. Am I missing something?

You're right.

Firing 'bzr log' is not an alternative either :)

    > Likewise for find-merge-base and file-id: what other commands can
    > show this information? I agree that this info is probably needed
    > only rarely, but what's wrong with advertising rarely used
    > commands?

Now, showing them if some config option (bzr.help.show_hidden ?) is set
(once and for all) in bazaar.conf (and stay off by default for
newcomers)... I don't see why we shouldn't show them.

[Jelmer Vernooij (jelmer)]

On Mon, 2011-04-04 at 17:57 +0000, Eli Zaretskii wrote:
> I see your point about adding confusion for new users, and I agree.
>
> However, please note that commands are not just for new users. Veteran
> users that are not bzr developers are also worthy of being catered to by
> bzr...
>
> Also, when you say these commands are fo debugging, you probably mean
> that this is how they cam into existence. While that is probably true,
> I would argue that once they do exist, their fate should be decided by
> their utility for mere mortals, not by the historical curiosities.
It's unrelated to their origin. These commands are only really useful
during debugging - e.g. when trying to find out why a file wasn't
merged, or why a merge went wrong. Normal users shouldn't have to bother
with e.g. file ids. Perhaps diagnostics is a better term?

Independent of how to call them, I'm not sure these commands should be
visible in "bzr help commands". Perhaps we should consider other ways to
make the "bzr help commands" list smaller, e.g. categorizing the
commands.

Cheers,

Jelmer

[Martin Pool (mbp)]

I don't think the fact they are less tested or possibly not maintained
indefinitely is a good reason to keep them hidden. If somebody needs
that function, having a way to run it now is better than not, even if
there is a chance it's buggy. If we expect to remove it, we can say
so in the help.

A separate category for commands that are a bit obscure but not
actually hidden may be good.

[Martin Pool (mbp)]

As it happens michaelh1 has just now asked on irc about how to find
out where he branched from trunk, to which find-merge-base is one
answer.

[Eli Zaretskii (eliz)]

> It's unrelated to their origin. These commands are only really useful
> during debugging - e.g. when trying to find out why a file wasn't
> merged, or why a merge went wrong. Normal users shouldn't have to bother
> with e.g. file ids. Perhaps diagnostics is a better term?

Well, diagnostics is something bzr users should be able to know how to do, up to certain limit, don't you think?

> Independent of how to call them, I'm not sure these commands should be
> visible in "bzr help commands".

Having them appear in a separate list makes them harder to find. This is the main point of this bug report: make some of the currently hidden commands be more visible, including appear in "help commands" and in the User Reference manual. I frequently catch myself trying desperately to recall the name of a particular command I used to great success just a few days ago. It doesn't help that the list in the manual and in "help commands" doesn't show them, because it means I need to remember to look in yet another list.

[John A Meinel (jameinel)]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 4/5/2011 1:05 AM, Martin Pool wrote:
> As it happens michaelh1 has just now asked on irc about how to find
> out where he branched from trunk, to which find-merge-base is one
> answer.
>

bzr log -r ancestor:../trunk

Is another, though that takes into account where you merged trunk.

But then again, so does 'find-merge-base'. To get an accurate
set-difference function that gives all revisions in THIS that aren't in
OTHER: bzr missing --mine --include-merged probably. Though that doesn't
give you the 'one revision back in trunk' if that is what you are
looking for.

John
=:->

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (Cygwin)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAk2a3NkACgkQJdeBCYSNAAMV6QCgiiCBcpqZUNmN6Ijn8ABdbGNu
LuUAoLh+VHcjX56dDh1epMR304/sLjAL
=hfLO
-----END PGP SIGNATURE-----

[Eli Zaretskii (eliz)]

It would be fine to add the currently "hidden" functionality to existing commands, perhaps under some optional switches. For example, lookup-revision and revision-info could be some special forms of output from "bzr revno" or "bzr version-info" (e.g., if the latter could accept a revisionspec as an argument).

I'm also okay with "bzr log -r ancestor:../trunk" as replacement for find-merge-base, but then please make their performance comparable, because right now find-merge-base blows "bzr log" out of the water, performance-wise. Observe:

eliz@fencepost:~/bzr/emacs/emacs-23$ time bzr log --line -r ancestor:../trunk
100531: Chong Yidong 2011-03-19 Backport fix for Bug#8219 from trunk.

real 0m13.940s
user 0m10.880s
sys 0m0.290s

eliz@fencepost:~/bzr/emacs/emacs-23$ time bzr find-merge-base . ../trunk
merge base is revision <email address hidden>

real 0m1.835s
user 0m1.730s
sys 0m0.100s

On Windows, the numbers are 20 sec and 5 sec respectively, also mostly in user-space.