Patchwork [2,of,9] help: let 'hg help debug' show the list of secret debug commands

login
register
mail settings
Submitter Mads Kiilerich
Date March 18, 2014, 11:33 p.m.
Message ID <ab2a99f9f3396fb705bd.1395185630@localhost.localdomain>
Download mbox | patch
Permalink /patch/3973/
State Accepted
Commit be87397f98c9692364946485796a8768861c05f5
Headers show

Comments

Mads Kiilerich - March 18, 2014, 11:33 p.m.
# HG changeset patch
# User Mads Kiilerich <madski@unity3d.com>
# Date 1394896444 -3600
#      Sat Mar 15 16:14:04 2014 +0100
# Node ID ab2a99f9f3396fb705bd621fd5b2de04783ac101
# Parent  ffaeeb8d43872aca4c329937b793c6b4919ce192
help: let 'hg help debug' show the list of secret debug commands

The names of the debug commands are not easy to remember and they are not easy
to find.
Siddharth Agarwal - March 19, 2014, 2:58 a.m.
On 03/18/2014 04:33 PM, Mads Kiilerich wrote:
> # HG changeset patch
> # User Mads Kiilerich <madski@unity3d.com>
> # Date 1394896444 -3600
> #      Sat Mar 15 16:14:04 2014 +0100
> # Node ID ab2a99f9f3396fb705bd621fd5b2de04783ac101
> # Parent  ffaeeb8d43872aca4c329937b793c6b4919ce192
> help: let 'hg help debug' show the list of secret debug commands
>
> The names of the debug commands are not easy to remember and they are not easy
> to find.

hg help --debug?

> diff --git a/mercurial/help.py b/mercurial/help.py
> --- a/mercurial/help.py
> +++ b/mercurial/help.py
> @@ -311,6 +311,8 @@ def help_(ui, name, unknowncmd=False, fu
>           # list of commands
>           if name == "shortlist":
>               header = _('basic commands:\n\n')
> +        elif name == "debug":
> +            header = _('debug commands (internal and unsupported):\n\n')
>           else:
>               header = _('list of commands:\n\n')
>   
> @@ -326,7 +328,7 @@ def help_(ui, name, unknowncmd=False, fu
>               if name == "shortlist" and not f.startswith("^"):
>                   continue
>               f = f.lstrip("^")
> -            if not ui.debugflag and f.startswith("debug"):
> +            if not ui.debugflag and f.startswith("debug") and name != "debug":
>                   continue
>               doc = e[0].__doc__
>               if doc and 'DEPRECATED' in doc and not ui.verbose:
> diff --git a/tests/test-help.t b/tests/test-help.t
> --- a/tests/test-help.t
> +++ b/tests/test-help.t
> @@ -782,6 +782,67 @@ Test that default list of commands omits
>     use "hg -v help" to show builtin aliases and global options
>   
>   
> +Test list of internal help commands
> +
> +  $ hg help debug
> +  debug commands (internal and unsupported):
> +
> +   debugancestor
> +                 find the ancestor revision of two revisions in a given index
> +   debugbuilddag
> +                 builds a repo with a given DAG from scratch in the current
> +                 empty repo
> +   debugbundle   lists the contents of a bundle
> +   debugcheckstate
> +                 validate the correctness of the current dirstate
> +   debugcommands
> +                 list all available commands and options
> +   debugcomplete
> +                 returns the completion list associated with the given command
> +   debugdag      format the changelog or an index DAG as a concise textual
> +                 description
> +   debugdata     dump the contents of a data file revision
> +   debugdate     parse and display a date
> +   debugdirstate
> +                 show the contents of the current dirstate
> +   debugdiscovery
> +                 runs the changeset discovery protocol in isolation
> +   debugfileset  parse and apply a fileset specification
> +   debugfsinfo   show information detected about current filesystem
> +   debuggetbundle
> +                 retrieves a bundle from a repo
> +   debugignore   display the combined ignore pattern
> +   debugindex    dump the contents of an index file
> +   debugindexdot
> +                 dump an index DAG as a graphviz dot file
> +   debuginstall  test Mercurial installation
> +   debugknown    test whether node ids are known to a repo
> +   debuglabelcomplete
> +                 complete "labels" - tags, open branch names, bookmark names
> +   debugobsolete
> +                 create arbitrary obsolete marker
> +   debugoptDEP   (no help text available)
> +   debugpathcomplete
> +                 complete part or all of a tracked path
> +   debugpushkey  access the pushkey key/value protocol
> +   debugpvec     (no help text available)
> +   debugrebuilddirstate
> +                 rebuild the dirstate as it would look like for the given
> +                 revision
> +   debugrename   dump rename information
> +   debugrevlog   show data and statistics about a revlog
> +   debugrevspec  parse and apply a revision specification
> +   debugsetparents
> +                 manually set the parents of the current working directory
> +   debugsub      (no help text available)
> +   debugsuccessorssets
> +                 show set of successors for revision
> +   debugwalk     show how files match on given patterns
> +   debugwireargs
> +                 (no help text available)
> +
> +  use "hg -v help debug" to show builtin aliases and global options
> +
>   
>   Test list of commands with command with no help text
>   
> _______________________________________________
> Mercurial-devel mailing list
> Mercurial-devel@selenic.com
> https://urldefense.proofpoint.com/v1/url?u=http://selenic.com/mailman/listinfo/mercurial-devel&k=ZVNjlDMF0FElm4dQtryO4A%3D%3D%0A&r=%2FSg8Zq7yFXBOhOzuAORckw%3D%3D%0A&m=fS5rbfVFOYis3obS9%2BN02wP04LVjFPlWVQ8wi6xEc3U%3D%0A&s=e8c12d5f2491b3a74a891f60581a4346a984105051ff1189e40f79a604b7c9ca
Mads Kiilerich - March 19, 2014, 11:38 a.m.
On 03/19/2014 03:58 AM, Siddharth Agarwal wrote:
> On 03/18/2014 04:33 PM, Mads Kiilerich wrote:
>> # HG changeset patch
>> # User Mads Kiilerich <madski@unity3d.com>
>> # Date 1394896444 -3600
>> #      Sat Mar 15 16:14:04 2014 +0100
>> # Node ID ab2a99f9f3396fb705bd621fd5b2de04783ac101
>> # Parent  ffaeeb8d43872aca4c329937b793c6b4919ce192
>> help: let 'hg help debug' show the list of secret debug commands
>>
>> The names of the debug commands are not easy to remember and they are 
>> not easy
>> to find.
>
> hg help --debug?

Yes, that is an alternative.

But:

--debug is not really (besides this) related to the commands that have 
debug in their name. It is thus not that intuitive that --debug means 
that debug commands are shown.

--debug also just shows the extra debug commands in the middle of 
verbose output. Not as convenient.

The existing behaviour was also not consistent:

$ hg c
hg: command 'c' is ambiguous:
     cat checkout clone commit copy

$ hg help c
list of commands:

  cat           output the current or given revision of files
  clone         make a copy of an existing repository
  commit        commit the specified files or all outstanding changes
  copy          mark files as copied for the next commit

use "hg -v help c" to show builtin aliases and global options

$ hg debug
hg: command 'debug' is ambiguous:
     debugancestor debugbuilddag debugbundle debugcheckstate 
debugcommands debugcomplete debugconfig debugdag debugdata debugdate 
debugdirstate debugdiscovery debugfileset debugfsinfo debuggetbundle 
debugignore debugindex debugindexdot debuginstall debugknown 
debuglabelcomplete debugobsolete debugpathcomplete debugpushkey 
debugpvec debugrebuilddirstate debugrename debugrevlog debugrevspec 
debugsetparents debugsub debugsuccessorssets debugwalk debugwireargs

$ hg help debug
no commands defined


I think this simple change makes Mercurial more consistent and 
predictable and is worth it.

/Mads
Matt Mackall - March 19, 2014, 9:13 p.m.
On Tue, 2014-03-18 at 19:58 -0700, Siddharth Agarwal wrote:
> On 03/18/2014 04:33 PM, Mads Kiilerich wrote:
> > # HG changeset patch
> > # User Mads Kiilerich <madski@unity3d.com>
> > # Date 1394896444 -3600
> > #      Sat Mar 15 16:14:04 2014 +0100
> > # Node ID ab2a99f9f3396fb705bd621fd5b2de04783ac101
> > # Parent  ffaeeb8d43872aca4c329937b793c6b4919ce192
> > help: let 'hg help debug' show the list of secret debug commands
> >
> > The names of the debug commands are not easy to remember and they are not easy
> > to find.
> 
> hg help --debug?

We should probably arrange that 'hg help -k' finds them.

And perhaps add a note about 'help -k' to the short help so people stop
being surprised that it exists.
Chris Jerdonek - March 20, 2014, 7:45 a.m.
On Wed, Mar 19, 2014 at 2:13 PM, Matt Mackall <mpm@selenic.com> wrote:
> On Tue, 2014-03-18 at 19:58 -0700, Siddharth Agarwal wrote:
>> On 03/18/2014 04:33 PM, Mads Kiilerich wrote:
>> > # HG changeset patch
>> > # User Mads Kiilerich <madski@unity3d.com>
>> > # Date 1394896444 -3600
>> > #      Sat Mar 15 16:14:04 2014 +0100
>> > # Node ID ab2a99f9f3396fb705bd621fd5b2de04783ac101
>> > # Parent  ffaeeb8d43872aca4c329937b793c6b4919ce192
>> > help: let 'hg help debug' show the list of secret debug commands
>> >
>> > The names of the debug commands are not easy to remember and they are not easy
>> > to find.
>>
>> hg help --debug?
>
> We should probably arrange that 'hg help -k' finds them.
>
> And perhaps add a note about 'help -k' to the short help so people stop
> being surprised that it exists.

FYI, I created a bug in the tracker for this issue a few months ago (I
believe it is the same issue):

http://bz.selenic.com/show_bug.cgi?id=4132

It might be worth mentioning the bug number in the patch.  If anything
else needs to be decided, the bug can also be used for discussion.

--Chris
Mads Kiilerich - March 21, 2014, 2:32 a.m.
On 03/19/2014 10:13 PM, Matt Mackall wrote:
> On Tue, 2014-03-18 at 19:58 -0700, Siddharth Agarwal wrote:
>> On 03/18/2014 04:33 PM, Mads Kiilerich wrote:
>>> # HG changeset patch
>>> # User Mads Kiilerich <madski@unity3d.com>
>>> # Date 1394896444 -3600
>>> #      Sat Mar 15 16:14:04 2014 +0100
>>> # Node ID ab2a99f9f3396fb705bd621fd5b2de04783ac101
>>> # Parent  ffaeeb8d43872aca4c329937b793c6b4919ce192
>>> help: let 'hg help debug' show the list of secret debug commands
>>>
>>> The names of the debug commands are not easy to remember and they are not easy
>>> to find.
>> hg help --debug?
> We should probably arrange that 'hg help -k' finds them.


Yes. But would you do that instead of this change?

That and this patch would both fix cases where debug commands are 
special and hidden where the user wouldn't expect it. But if a user 
tries one of them and are surprised that it didn't work, then it will 
not help him that the other would have worked.

It is independent changes and I don't see any reason to not take this 
simple patch.

/Mads

> And perhaps add a note about 'help -k' to the short help so people stop
> being surprised that it exists.
Matt Mackall - March 22, 2014, 7:45 p.m.
On Wed, 2014-03-19 at 00:33 +0100, Mads Kiilerich wrote:
> # HG changeset patch
> # User Mads Kiilerich <madski@unity3d.com>
> # Date 1394896444 -3600
> #      Sat Mar 15 16:14:04 2014 +0100
> # Node ID ab2a99f9f3396fb705bd621fd5b2de04783ac101
> # Parent  ffaeeb8d43872aca4c329937b793c6b4919ce192
> help: let 'hg help debug' show the list of secret debug commands

Queued for default, thanks.

Patch

diff --git a/mercurial/help.py b/mercurial/help.py
--- a/mercurial/help.py
+++ b/mercurial/help.py
@@ -311,6 +311,8 @@  def help_(ui, name, unknowncmd=False, fu
         # list of commands
         if name == "shortlist":
             header = _('basic commands:\n\n')
+        elif name == "debug":
+            header = _('debug commands (internal and unsupported):\n\n')
         else:
             header = _('list of commands:\n\n')
 
@@ -326,7 +328,7 @@  def help_(ui, name, unknowncmd=False, fu
             if name == "shortlist" and not f.startswith("^"):
                 continue
             f = f.lstrip("^")
-            if not ui.debugflag and f.startswith("debug"):
+            if not ui.debugflag and f.startswith("debug") and name != "debug":
                 continue
             doc = e[0].__doc__
             if doc and 'DEPRECATED' in doc and not ui.verbose:
diff --git a/tests/test-help.t b/tests/test-help.t
--- a/tests/test-help.t
+++ b/tests/test-help.t
@@ -782,6 +782,67 @@  Test that default list of commands omits
   use "hg -v help" to show builtin aliases and global options
 
 
+Test list of internal help commands
+
+  $ hg help debug
+  debug commands (internal and unsupported):
+  
+   debugancestor
+                 find the ancestor revision of two revisions in a given index
+   debugbuilddag
+                 builds a repo with a given DAG from scratch in the current
+                 empty repo
+   debugbundle   lists the contents of a bundle
+   debugcheckstate
+                 validate the correctness of the current dirstate
+   debugcommands
+                 list all available commands and options
+   debugcomplete
+                 returns the completion list associated with the given command
+   debugdag      format the changelog or an index DAG as a concise textual
+                 description
+   debugdata     dump the contents of a data file revision
+   debugdate     parse and display a date
+   debugdirstate
+                 show the contents of the current dirstate
+   debugdiscovery
+                 runs the changeset discovery protocol in isolation
+   debugfileset  parse and apply a fileset specification
+   debugfsinfo   show information detected about current filesystem
+   debuggetbundle
+                 retrieves a bundle from a repo
+   debugignore   display the combined ignore pattern
+   debugindex    dump the contents of an index file
+   debugindexdot
+                 dump an index DAG as a graphviz dot file
+   debuginstall  test Mercurial installation
+   debugknown    test whether node ids are known to a repo
+   debuglabelcomplete
+                 complete "labels" - tags, open branch names, bookmark names
+   debugobsolete
+                 create arbitrary obsolete marker
+   debugoptDEP   (no help text available)
+   debugpathcomplete
+                 complete part or all of a tracked path
+   debugpushkey  access the pushkey key/value protocol
+   debugpvec     (no help text available)
+   debugrebuilddirstate
+                 rebuild the dirstate as it would look like for the given
+                 revision
+   debugrename   dump rename information
+   debugrevlog   show data and statistics about a revlog
+   debugrevspec  parse and apply a revision specification
+   debugsetparents
+                 manually set the parents of the current working directory
+   debugsub      (no help text available)
+   debugsuccessorssets
+                 show set of successors for revision
+   debugwalk     show how files match on given patterns
+   debugwireargs
+                 (no help text available)
+  
+  use "hg -v help debug" to show builtin aliases and global options
+
 
 Test list of commands with command with no help text