This is an archive of the discontinued Mercurial Phabricator instance.

Differential D5087

help: displaying documented aliases by default
ClosedPublic

Authored by rdamazio on Oct 13 2018, 10:26 AM.

Details

Reviewers
durin42
yuja
Group Reviewers
hg-reviewers
Commits
rHG444861dc1e55: help: displaying documented aliases by default
Summary

This makes aliases be displayed in "hg help" when they have a :doc config
entry, and also allows them to be assigned to a category with :category.

Diff Detail

Repository
rHG Mercurial
Lint
Lint Skipped
Unit
Unit Tests Skipped

Event Timeline

rdamazio created this revision.Oct 13 2018, 10:26 AM
rdamazio updated this revision to Diff 12127.Oct 14 2018, 6:32 AM
yuja added a subscriber: yuja.Oct 14 2018, 11:30 AM

@@ -507,16 +522,11 @@

f = fs[0]
syns[f] = ', '.join(fs)
func = e[0]

+ alias = getattr(func, 'alias', False)

if select and not select(f):
    continue
  • if (not select and name != 'shortlist' and
  • func.module != commands.name):
  • continue
  • if name == "shortlist":
  • if not getattr(func, 'helpbasic', False):
  • continue doc = pycompat.getdoc(func)
  • if filtercmd(ui, f, name, doc):

+ if filtercmd(ui, f, func, name, doc):

This makes extension commands get listed in "hg help". I think that's fine,
but can you split patches so we can backout if that causes problem?

rdamazio added a comment.Oct 18 2018, 11:25 PM
In D5087#76401, @yuja wrote:

@@ -507,16 +522,11 @@

f = fs[0]
syns[f] = ', '.join(fs)
func = e[0]

+ alias = getattr(func, 'alias', False)

if select and not select(f):
    continue
  • if (not select and name != 'shortlist' and
  • func.module != commands.name):
  • continue
  • if name == "shortlist":
  • if not getattr(func, 'helpbasic', False):
  • continue doc = pycompat.getdoc(func)
  • if filtercmd(ui, f, name, doc):

+ if filtercmd(ui, f, func, name, doc):

This makes extension commands get listed in "hg help". I think that's fine,
but can you split patches so we can backout if that causes problem?

Done. Sending another review for the extensions part.

yuja added a comment.Oct 23 2018, 7:35 AM

Queued the series for 4.9, many thanks.

@@ -523,16 +538,20 @@

f = fs[0]
syns[f] = ', '.join(fs)
func = e[0]

+ alias = getattr(func, 'alias', False)

Removed unused variable alias.

@@ -554,11 +557,14 @@

  1. drop prefix in old-style help lines so hg shows the alias self.help = self.help[4 + len(cmd):]

+ self.owndoc = 'doc' in cfg

doc = cfg.get('doc', pycompat.getdoc(fn))
if doc is not None:
    doc = pycompat.sysstr(doc)
self.__doc__ = doc

+ self.helpcategory = cfg.get('category', registrar.command.CATEGORY_NONE)

Maybe the default can be derived from the aliased command?

Closed by commit rHG444861dc1e55: help: displaying documented aliases by default (authored by rdamazio). · Explain WhyOct 23 2018, 7:39 AM
This revision was automatically updated to reflect the committed changes.

Revision Contents
Changeset List

PathPackages
Mmercurial/dispatch.py (9 lines)
Mmercurial/help.py (44 lines)
Mmercurial/registrar.py (4 lines)
Mtests/test-alias.t (14 lines)
Mtests/test-help.t (28 lines)

Diff 12256

mercurial/dispatch.py

error, error,
extensions, extensions,
fancyopts, fancyopts,
help, help,
hg, hg,
hook, hook,
profiling, profiling,
pycompat, pycompat,
registrar,
scmutil, scmutil,
ui as uimod, ui as uimod,
util, util,
) )
from .utils import ( from .utils import (
procutil, procutil,
stringutil, stringutil,
"of %i variable in alias '%s' definition.\n" "of %i variable in alias '%s' definition.\n"
% (int(m.groups()[0]), self.name)) % (int(m.groups()[0]), self.name))
return '' return ''
cmd = re.sub(br'\$(\d+|\$)', _checkvar, shdef) cmd = re.sub(br'\$(\d+|\$)', _checkvar, shdef)
cmd = aliasinterpolate(self.name, args, cmd) cmd = aliasinterpolate(self.name, args, cmd)
return ui.system(cmd, environ=env, return ui.system(cmd, environ=env,
blockedtag='alias_%s' % self.name) blockedtag='alias_%s' % self.name)
self.fn = fn self.fn = fn
self.alias = True
self._populatehelp(ui, name, shdef, self.fn) self._populatehelp(ui, name, shdef, self.fn)
return return
try: try:
args = pycompat.shlexsplit(self.definition) args = pycompat.shlexsplit(self.definition)
except ValueError as inst: except ValueError as inst:
self.badalias = (_("error in definition for alias '%s': %s") self.badalias = (_("error in definition for alias '%s': %s")
% (self.name, stringutil.forcebytestr(inst))) % (self.name, stringutil.forcebytestr(inst)))
try: try:
tableentry = cmdutil.findcmd(cmd, cmdtable, False)[1] tableentry = cmdutil.findcmd(cmd, cmdtable, False)[1]
if len(tableentry) > 2: if len(tableentry) > 2:
self.fn, self.opts, cmdhelp = tableentry self.fn, self.opts, cmdhelp = tableentry
else: else:
self.fn, self.opts = tableentry self.fn, self.opts = tableentry
cmdhelp = None cmdhelp = None
self.alias = True
self._populatehelp(ui, name, cmd, self.fn, cmdhelp) self._populatehelp(ui, name, cmd, self.fn, cmdhelp)
except error.UnknownCommand: except error.UnknownCommand:
self.badalias = (_("alias '%s' resolves to unknown command '%s'") self.badalias = (_("alias '%s' resolves to unknown command '%s'")
% (self.name, cmd)) % (self.name, cmd))
self.unknowncmd = True self.unknowncmd = True
except error.AmbiguousCommand: except error.AmbiguousCommand:
self.badalias = (_("alias '%s' resolves to ambiguous command '%s'") self.badalias = (_("alias '%s' resolves to ambiguous command '%s'")
% (self.name, cmd)) % (self.name, cmd))
def _populatehelp(self, ui, name, cmd, fn, defaulthelp=None): def _populatehelp(self, ui, name, cmd, fn, defaulthelp=None):
# confine strings to be passed to i18n.gettext() # confine strings to be passed to i18n.gettext()
cfg = {} cfg = {}
for k in ('doc', 'help'): for k in ('doc', 'help', 'category'):
v = ui.config('alias', '%s:%s' % (name, k), None) v = ui.config('alias', '%s:%s' % (name, k), None)
if v is None: if v is None:
continue continue
if not encoding.isasciistr(v): if not encoding.isasciistr(v):
self.badalias = (_("non-ASCII character in alias definition " self.badalias = (_("non-ASCII character in alias definition "
"'%s:%s'") % (name, k)) "'%s:%s'") % (name, k))
return return
cfg[k] = v cfg[k] = v
self.help = cfg.get('help', defaulthelp or '') self.help = cfg.get('help', defaulthelp or '')
if self.help and self.help.startswith("hg " + cmd): if self.help and self.help.startswith("hg " + cmd):
# drop prefix in old-style help lines so hg shows the alias # drop prefix in old-style help lines so hg shows the alias
self.help = self.help[4 + len(cmd):] self.help = self.help[4 + len(cmd):]
self.owndoc = 'doc' in cfg
doc = cfg.get('doc', pycompat.getdoc(fn)) doc = cfg.get('doc', pycompat.getdoc(fn))
if doc is not None: if doc is not None:
doc = pycompat.sysstr(doc) doc = pycompat.sysstr(doc)
self.__doc__ = doc self.__doc__ = doc
self.helpcategory = cfg.get('category', registrar.command.CATEGORY_NONE)
@property @property
def args(self): def args(self):
args = pycompat.maplist(util.expandpath, self.givenargs) args = pycompat.maplist(util.expandpath, self.givenargs)
return aliasargs(self.fn, args) return aliasargs(self.fn, args)
def __getattr__(self, name): def __getattr__(self, name):
adefaults = {r'norepo': True, r'intents': set(), adefaults = {r'norepo': True, r'intents': set(),
r'optionalrepo': False, r'inferrepo': False} r'optionalrepo': False, r'inferrepo': False}
"""like a typical command entry (func, opts, help), but is lazy""" """like a typical command entry (func, opts, help), but is lazy"""
def __init__(self, ui, name, definition, cmdtable, source): def __init__(self, ui, name, definition, cmdtable, source):
self.ui = ui self.ui = ui
self.name = name self.name = name
self.definition = definition self.definition = definition
self.cmdtable = cmdtable.copy() self.cmdtable = cmdtable.copy()
self.source = source self.source = source
self.alias = True
@util.propertycache @util.propertycache
def _aliasdef(self): def _aliasdef(self):
return cmdalias(self.ui, self.name, self.definition, self.cmdtable, return cmdalias(self.ui, self.name, self.definition, self.cmdtable,
self.source) self.source)
def __getitem__(self, n): def __getitem__(self, n):
aliasdef = self._aliasdef aliasdef = self._aliasdef

mercurial/help.py

return ''.join(rst) return ''.join(rst)
def indicateomitted(rst, omitted, notomitted=None): def indicateomitted(rst, omitted, notomitted=None):
rst.append('\n\n.. container:: omitted\n\n %s\n\n' % omitted) rst.append('\n\n.. container:: omitted\n\n %s\n\n' % omitted)
if notomitted: if notomitted:
rst.append('\n\n.. container:: notomitted\n\n %s\n\n' % notomitted) rst.append('\n\n.. container:: notomitted\n\n %s\n\n' % notomitted)
def filtercmd(ui, cmd, kw, doc): def filtercmd(ui, cmd, func, kw, doc):
if not ui.debugflag and cmd.startswith("debug") and kw != "debug": if not ui.debugflag and cmd.startswith("debug") and kw != "debug":
# Debug command, and user is not looking for those.
return True return True
if not ui.verbose and doc and any(w in doc for w in _exclkeywords): if not ui.verbose:
if not kw and not doc:
# Command had no documentation, no point in showing it by default.
return True
if getattr(func, 'alias', False) and not getattr(func, 'owndoc', False):
# Alias didn't have its own documentation.
return True
if doc and any(w in doc for w in _exclkeywords):
# Documentation has excluded keywords.
return True
if kw == "shortlist" and not getattr(func, 'helpbasic', False):
# We're presenting the short list but the command is not basic.
return True return True
if ui.configbool('help', 'hidden-command.%s' % cmd): if ui.configbool('help', 'hidden-command.%s' % cmd):
# Configuration explicitly hides the command.
return True return True
return False return False
def filtertopic(ui, topic): def filtertopic(ui, topic):
return ui.configbool('help', 'hidden-topic.%s' % topic, False) return ui.configbool('help', 'hidden-topic.%s' % topic, False)
def topicmatch(ui, commands, kw): def topicmatch(ui, commands, kw):
"""Return help topics matching kw. """Return help topics matching kw.
if not filtertopic(ui, name): if not filtertopic(ui, name):
results['topics'].append((names[0], header)) results['topics'].append((names[0], header))
for cmd, entry in commands.table.iteritems(): for cmd, entry in commands.table.iteritems():
if len(entry) == 3: if len(entry) == 3:
summary = entry[2] summary = entry[2]
else: else:
summary = '' summary = ''
# translate docs *before* searching there # translate docs *before* searching there
docs = _(pycompat.getdoc(entry[0])) or '' func = entry[0]
docs = _(pycompat.getdoc(func)) or ''
if kw in cmd or lowercontains(summary) or lowercontains(docs): if kw in cmd or lowercontains(summary) or lowercontains(docs):
doclines = docs.splitlines() doclines = docs.splitlines()
if doclines: if doclines:
summary = doclines[0] summary = doclines[0]
cmdname = cmdutil.parsealiases(cmd)[0] cmdname = cmdutil.parsealiases(cmd)[0]
if filtercmd(ui, cmdname, kw, docs): if filtercmd(ui, cmdname, func, kw, docs):
continue continue
results['commands'].append((cmdname, summary)) results['commands'].append((cmdname, summary))
for name, docs in itertools.chain( for name, docs in itertools.chain(
extensions.enabled(False).iteritems(), extensions.enabled(False).iteritems(),
extensions.disabled().iteritems()): extensions.disabled().iteritems()):
if not docs: if not docs:
continue continue
name = name.rpartition('.')[-1] name = name.rpartition('.')[-1]
if lowercontains(name) or lowercontains(docs): if lowercontains(name) or lowercontains(docs):
# extension docs are already translated # extension docs are already translated
results['extensions'].append((name, docs.splitlines()[0])) results['extensions'].append((name, docs.splitlines()[0]))
try: try:
mod = extensions.load(ui, name, '') mod = extensions.load(ui, name, '')
except ImportError: except ImportError:
# debug message would be printed in extensions.load() # debug message would be printed in extensions.load()
continue continue
for cmd, entry in getattr(mod, 'cmdtable', {}).iteritems(): for cmd, entry in getattr(mod, 'cmdtable', {}).iteritems():
if kw in cmd or (len(entry) > 2 and lowercontains(entry[2])): if kw in cmd or (len(entry) > 2 and lowercontains(entry[2])):
cmdname = cmdutil.parsealiases(cmd)[0] cmdname = cmdutil.parsealiases(cmd)[0]
cmddoc = pycompat.getdoc(entry[0]) func = entry[0]
cmddoc = pycompat.getdoc(func)
if cmddoc: if cmddoc:
cmddoc = gettext(cmddoc).splitlines()[0] cmddoc = gettext(cmddoc).splitlines()[0]
else: else:
cmddoc = _('(no help text available)') cmddoc = _('(no help text available)')
if filtercmd(ui, cmdname, kw, cmddoc): if filtercmd(ui, cmdname, func, kw, cmddoc):
continue continue
results['extensioncommands'].append((cmdname, cmddoc)) results['extensioncommands'].append((cmdname, cmddoc))
return results return results
def loaddoc(topic, subdir=None): def loaddoc(topic, subdir=None):
"""Return a delayed loader for help/topic.txt.""" """Return a delayed loader for help/topic.txt."""
def loader(ui): def loader(ui):
h = {} h = {}
# Command -> string showing synonyms # Command -> string showing synonyms
syns = {} syns = {}
for c, e in commands.table.iteritems(): for c, e in commands.table.iteritems():
fs = cmdutil.parsealiases(c) fs = cmdutil.parsealiases(c)
f = fs[0] f = fs[0]
syns[f] = ', '.join(fs) syns[f] = ', '.join(fs)
func = e[0] func = e[0]
alias = getattr(func, 'alias', False)
if select and not select(f): if select and not select(f):
continue continue
# Only list built-in commands (defined in commands.py) and aliases
# (defined in dispatch.py), but not any other extensions.
# We don't want a circular dependency between this file and
# dispatch, so reference that by name.
# TODO(rdamazio): Just show commands from all extensions.
if (not select and name != 'shortlist' and if (not select and name != 'shortlist' and
func.__module__ != commands.__name__): func.__module__ != commands.__name__ and
continue func.__module__ != 'mercurial.dispatch'):
if name == "shortlist":
if not getattr(func, 'helpbasic', False):
continue continue
doc = pycompat.getdoc(func) doc = pycompat.getdoc(func)
if filtercmd(ui, f, name, doc): if filtercmd(ui, f, func, name, doc):
continue continue
doc = gettext(doc) doc = gettext(doc)
if not doc: if not doc:
doc = _("(no help text available)") doc = _("(no help text available)")
h[f] = doc.splitlines()[0].rstrip() h[f] = doc.splitlines()[0].rstrip()
cat = getattr(func, 'helpcategory', None) or ( cat = getattr(func, 'helpcategory', None) or (
registrar.command.CATEGORY_NONE) registrar.command.CATEGORY_NONE)
names, header, doc = topic[0:3] names, header, doc = topic[0:3]
if len(topic) > 3 and topic[3]: if len(topic) > 3 and topic[3]:
category = topic[3] category = topic[3]
else: else:
category = TOPIC_CATEGORY_NONE category = TOPIC_CATEGORY_NONE
topicname = names[0] topicname = names[0]
if not filtertopic(ui, topicname): if not filtertopic(ui, topicname):
topiccats.setdefault(category, []).append((topicname, header)) topiccats.setdefault(category, []).append(
(topicname, header))
# Check that all categories have an order. # Check that all categories have an order.
missing_order = set(topiccats.keys()) - set(TOPIC_CATEGORY_ORDER) missing_order = set(topiccats.keys()) - set(TOPIC_CATEGORY_ORDER)
if missing_order: if missing_order:
ui.develwarn( ui.develwarn(
'help categories missing from TOPIC_CATEGORY_ORDER: %s' % 'help categories missing from TOPIC_CATEGORY_ORDER: %s' %
missing_order) missing_order)

mercurial/registrar.py

`<options>` are keyword arguments (or `**options`) of option arguments `<options>` are keyword arguments (or `**options`) of option arguments
from the command line. from the command line.
See the WritingExtensions and MercurialApi documentation for more exhaustive See the WritingExtensions and MercurialApi documentation for more exhaustive
descriptions and examples. descriptions and examples.
""" """
# Command categories for grouping them in help output. # Command categories for grouping them in help output.
# These can also be specified for aliases, like:
# [alias]
# myalias = something
# myalias:category = repo
CATEGORY_REPO_CREATION = 'repo' CATEGORY_REPO_CREATION = 'repo'
CATEGORY_REMOTE_REPO_MANAGEMENT = 'remote' CATEGORY_REMOTE_REPO_MANAGEMENT = 'remote'
CATEGORY_COMMITTING = 'commit' CATEGORY_COMMITTING = 'commit'
CATEGORY_CHANGE_MANAGEMENT = 'management' CATEGORY_CHANGE_MANAGEMENT = 'management'
CATEGORY_CHANGE_ORGANIZATION = 'organization' CATEGORY_CHANGE_ORGANIZATION = 'organization'
CATEGORY_FILE_CONTENTS = 'files' CATEGORY_FILE_CONTENTS = 'files'
CATEGORY_CHANGE_NAVIGATION = 'navigation' CATEGORY_CHANGE_NAVIGATION = 'navigation'
CATEGORY_WORKING_DIRECTORY = 'wdir' CATEGORY_WORKING_DIRECTORY = 'wdir'

tests/test-alias.t

basic basic
$ hg myinit alias $ hg myinit alias
help help
$ hg help -c | grep myinit $ hg help -c | grep myinit
myinit This is my documented alias for init. myinit This is my documented alias for init.
$ hg help -c | grep mycommit $ hg help -c | grep mycommit
mycommit This is my alias with only doc. mycommit This is my alias with only doc.
$ hg help -c | grep cleanstatus $ hg help -c | grep cleanstatus
cleanstatus show changed files in the working directory [1]
$ hg help -c | grep lognull $ hg help -c | grep lognull
lognull Logs the null rev lognull Logs the null rev
$ hg help -c | grep dln $ hg help -c | grep dln
dln Logs the null rev [1]
$ hg help -c | grep recursivedoc $ hg help -c | grep recursivedoc
recursivedoc Logs the null rev in debug mode recursivedoc Logs the null rev in debug mode
$ hg help myinit $ hg help myinit
hg myinit [OPTIONS] [BLA] [BLE] hg myinit [OPTIONS] [BLA] [BLE]
alias for: hg init alias for: hg init
This is my documented alias for init. This is my documented alias for init.
defined by: * (glob) defined by: * (glob)
$ hg rebat $ hg rebat
this is rebate this is rebate
$ hg rebat --foo-bar $ hg rebat --foo-bar
this is rebate --foo-bar this is rebate --foo-bar
help for a shell alias help for a shell alias
$ hg help -c | grep rebate $ hg help -c | grep rebate
rebate This is my alias which just prints something. rebate This is my alias which just prints something.
$ hg help rebate $ hg help rebate
hg rebate [MYARGS] hg rebate [MYARGS]
shell alias for: echo this is %HG_ARGS% (windows !) shell alias for: echo this is %HG_ARGS% (windows !)
shell alias for: echo this is $HG_ARGS (no-windows !) shell alias for: echo this is $HG_ARGS (no-windows !)
This is my alias which just prints something. This is my alias which just prints something.

tests/test-help.t

> @command(b'debugoptDEP', [(b'', b'dopt', None, b'option is (DEPRECATED)')]) > @command(b'debugoptDEP', [(b'', b'dopt', None, b'option is (DEPRECATED)')])
> @command(b'debugoptEXP', [(b'', b'eopt', None, b'option is (EXPERIMENTAL)')]) > @command(b'debugoptEXP', [(b'', b'eopt', None, b'option is (EXPERIMENTAL)')])
> def nohelp(ui, *args, **kwargs): > def nohelp(ui, *args, **kwargs):
> pass > pass
> >
> def uisetup(ui): > def uisetup(ui):
> ui.setconfig(b'alias', b'shellalias', b'!echo hi', b'helpext') > ui.setconfig(b'alias', b'shellalias', b'!echo hi', b'helpext')
> ui.setconfig(b'alias', b'hgalias', b'summary', b'helpext') > ui.setconfig(b'alias', b'hgalias', b'summary', b'helpext')
> ui.setconfig(b'alias', b'hgalias:doc', b'My doc', b'helpext')
> ui.setconfig(b'alias', b'hgalias:category', b'navigation', b'helpext')
> ui.setconfig(b'alias', b'hgaliasnodoc', b'summary', b'helpext')
> >
> EOF > EOF
$ echo '[extensions]' >> $HGRCPATH $ echo '[extensions]' >> $HGRCPATH
$ echo "helpext = `pwd`/helpext.py" >> $HGRCPATH $ echo "helpext = `pwd`/helpext.py" >> $HGRCPATH
Test for aliases Test for aliases
$ hg help | grep hgalias
hgalias My doc
$ hg help hgalias $ hg help hgalias
hg hgalias [--remote] hg hgalias [--remote]
alias for: hg summary alias for: hg summary
My doc
defined by: helpext
options:
--remote check for push and pull
(some details hidden, use --verbose to show complete help)
$ hg help hgaliasnodoc
hg hgaliasnodoc [--remote]
alias for: hg summary
summarize working directory state summarize working directory state
This generates a brief summary of the working directory state, including This generates a brief summary of the working directory state, including
parents, branch, commit status, phase and available updates. parents, branch, commit status, phase and available updates.
With the --remote option, this will check the default paths for incoming With the --remote option, this will check the default paths for incoming
and outgoing changes. This can be time-consuming. and outgoing changes. This can be time-consuming.
copy mark files as copied for the next commit copy mark files as copied for the next commit
diff diff repository (or selected files) diff diff repository (or selected files)
grep search revision history for a pattern in specified files grep search revision history for a pattern in specified files
Change navigation: Change navigation:
bisect subdivision search of changesets bisect subdivision search of changesets
heads show branch heads heads show branch heads
hgalias My doc
identify identify the working directory or specified revision identify identify the working directory or specified revision
log show revision history of entire repository or files log show revision history of entire repository or files
Working directory management: Working directory management:
add add the specified files on the next commit add add the specified files on the next commit
addremove add all new files, delete all missing files addremove add all new files, delete all missing files
files list tracked files files list tracked files
</td><td> </td><td>
show help for a given topic or a help overview show help for a given topic or a help overview
</td></tr> </td></tr>
<tr><td> <tr><td>
<a href="/help/hgalias"> <a href="/help/hgalias">
hgalias hgalias
</a> </a>
</td><td> </td><td>
My doc
</td></tr>
<tr><td>
<a href="/help/hgaliasnodoc">
hgaliasnodoc
</a>
</td><td>
summarize working directory state summarize working directory state
</td></tr> </td></tr>
<tr><td> <tr><td>
<a href="/help/identify"> <a href="/help/identify">
identify identify
</a> </a>
</td><td> </td><td>
identify the working directory or specified revision identify the working directory or specified revision