Note:
This page is primarily intended for developers of Mercurial.
Command NameSpace
Status: In Progress
Main proponents: Pierre-YvesDavid
![/!\](/moin-static/modernized/img/alert.png "/!\"){kind=small}
This is a speculative project and does not represent any firm decisions on future behavior.
Introduce official namespaces for commands (like normal, perf, debug, admin, etc…)
1. Goal
Explain what kind of problem are triggering this idea, why it is worth solving and the big picture of how you'll solve it.
As of Mercurial 5.6 we have a few command implicit "namespace"
- the "normal" command, that user are expected to touch and were we enforce a strong backward compatibility
- the "debug" command, that user are not expected to touch (but that some end up having to) and where we don't provide any backward compat (but end up having to)
- the "perf" command, that we use for performance benchmark
The current "debug" namespace is problematic because it mix:
- maintenance utility that we point the user at (eg: debugupgraderepo, debugrebuilddirstate)
- scripting utility command we need to maintain compatibility with (eg: debugcompletion)
thing we use for test (eg: debugbuildag)
- massive footguns that user keep confusing with candies (eg: debugsetparents)
So the idea it to:
Introduce official namespace notation hg namespace-command and "move" command into a limited but meaningful number of namespace.
2. Detailed description
It is important to note that the namespace plan aims at separating command into very high level category (command for users, admin, scrip, mercurial-developer, etc), and is not to be used for more detailled categories (eg: the helpcategory parameters of command, a phab- namespace, etc…). Mixing the two would mud the water and reduce the importance of the semantic barrier between the currently proposed
However, being able to use - in command name would be handy. They could use use for both "soft" namespacing (eg phab-, narrow-, …) and readability (eg: update-cache, upgrade-repo, add-remove, …).
So, should we aims at a different syntax for namespace than the simple group-commandwithnospace ? Here is a couple of idea:
capitalize the group name: eg ADMIN-strip, → quite ugly but effective
double the dash: eg admin--strip, → a bit odd, but with - folding, this is undistinguisable from admin-strip.
using underscore: eg admin_strip, → quite ugly, and the 90th called, they want their _ back
restrict long name to admin/command/test: → This rule out phab- style dash, which is not great.
Current idea for namespace we know we need
- "normal": everything things the user should touch, contains most of the current command in that space. (strong BC preserved)
admin-: command that are not meant to be used during "day to day" mercurial usage, but that has legitimate usage for server administration (eg: cache rebuilding) possible other name: maintenance-, tools-
debug-: for debug that nobody should touch unless they are a mercurial developper (no BC preserved)
perf-: for performance command (not structly necessary, but seems useful)
Tentative namespace
script-: for command to be used my script (eg: completion) possible other name: scriputil
exp-: a name space wher we could put experimental command until they behavior start to be backward compatible.
testutil or test for things we use in test only ?
footgun or dangerous for dangerous command (but I woudl rather not have such)
command |
possible new namespace |
notes |
verify |
admin |
|
recover |
admin |
|
rollback |
admin (or maybe footgun) |
this one is already (DEPRECATED) (DANGEROUS), but could make sense in that admin namespace |
serve |
(not really) admin |
if we had the namespace for a while and hg serve were landing today, it might make sense, but that is a bit late |
root |
(maybe) script |
not really convinced, but playing with ideas. the command is probably fine as it is |
command |
extensions |
possible new namespace |
notes |
censor |
censor |
admin |
|
lfconvert |
largefile |
admin |
|
relink |
relink |
admin |
|
gc |
remotefilelog |
admin |
|
repack |
remotefilelog |
admin |
|
verify |
remotefilelog |
admin |
|
convert |
convert |
admin |
|
fastexport |
fastexport |
admin |
command |
possible new namespace |
new name (namespace syntax not decided) |
notes |
debugantivirusrunning |
admin |
admin--is-antivirus-running |
|
debugapplystreamclonebundle |
admin |
admin--apply-stream-bundle |
(Maybe actually not ready to be used) |
debugcreatestreamclonebundle |
admin |
admin--creates-stream-bundle |
(Maybe actually not ready to be used) |
debugbackupbundle |
admin |
admin--list-backup-bundles |
|
debugnodemap |
admin (part of it) |
partially merged in admin--verify (and admin--rebuild-cache?) |
|
debugcheckstate |
admin |
merged into admin--verify |
|
debugcolor |
admin |
admin--color-info |
|
debugfsinfo |
admin |
admin--fs-info |
|
debuginstall |
admin |
admin--install-info |
|
debuglocks |
admin |
admin--locks |
|
debugrebuilddirstate |
admin |
merged into admin--rebuild-cache |
|
debugrebuildfncache |
admin |
merged into admin--rebuild-cache |
|
debugupdatecaches |
admin |
admin--rebuild-cache (with flags?) |
|
debugformat |
admin |
admin--format |
|
debugupgraderepo |
admin |
merged into admin--format |
|
debugcommands |
script |
script--complete-command-name |
|
debugcomplete |
script |
script--complete-command-args |
|
debugnamecomplete |
script |
script--complete-name |
|
debugpathcomplete |
script |
script--complete-path |
|
3. Roadmap
get mercurial to automatically fold - in command 
define the new syntax - define the new namespaces
- move the commands there