On 09/04/2007, at 5:13 AM, Julio M. Merino Vidal wrote:
I find that the current summary of commands printed by "mtn help"
is too terse and therefore not as useful as it would be. It is
nice to see all available commands grouped by category but this is
of few use if you don't understand what their compact name means
or even less if you are new to monotone.
I understand where you are coming from, and I can see a use for the
type of longer help you suggested. But I'm not sure I like the
length of sample help output you provided. I think it is good to
try and keep the help down to 1 (or 2) screenfuls. More than that
and I stop using the help command for a quick refresher.
I'm going to brainstorm a few possible solutions:
- re-organise the commands so there are fewer of them?
- Don't show help at all for rare commands
- extend the "mtn help <command>" syntax to "mtn help <command group>"
- include help on using help at the bottom of the main help command.
- While we're at it, it would be great if you could use help on
subcommands: "mtn help db init"
I guess I'd use the heuristic that you want to remove information
from the initial help screen that isn't commonly used, but make
sure you have instructions on how to get it if you need it.
Some suggested output (without code, making it all hot air really):
% mtn help
Usage: mtn [OPTION...] command [ARG...]
Common global arguments:
--db [ -d ] <arg> set name of database
--help [ -h ] display help message
--key [ -k ] <arg> set key for signatures
--quiet suppress verbose, informational and
progress messages
--ssh-sign <arg> sign with ssh-agent, 'yes' to sign with ssh
if key
found, 'no' to force monotone to sign,
'check' to sign
with both and compare
--version print version number, then exit
command groups:
automation, database, debug, informative, key, cert, network,
packet, rcs, review,
tree, vars, workspace
common commands:
annotate Prints an annotated copy of a file
diff Shows current differences
list Shows database objects
log Prints history in reverse order
status Shows workspace's status information
serve Serves the database to connecting clients
sync Synchronizes branches with a netsync server
checkout Checks out a revision from the database
into a directory
merge Merges unmerged heads of a branch
add Adds files to the workspace
commit Commits workspace changes to the database
rename Renames entries in the workspace
drop Drops files from the workspace
update Updates the workspace
Use "mtn help <command group>" for more information on commands in
that group, or
use "mtn help <command>" for more information on a particular command.