[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Monotone-devel] More descriptive help summary
From: |
William Uther |
Subject: |
Re: [Monotone-devel] More descriptive help summary |
Date: |
Mon, 9 Apr 2007 10:10:02 +1000 |
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.
Then if they use "mtn help <command group>" you might get something
like this:
% mtn help workspace
Usage: mtn [OPTION...] command [ARG...]
--confdir <arg> set location of configuration directory
--db [ -d ] <arg> set name of database
--debug print debug log to stderr while running
--dump <arg> file to dump debugging log to, on failure
--full-version print detailed version number, then exit
--help [ -h ] display help message
--key [ -k ] <arg> set key for signatures
--keydir <arg> set location of key store
--log <arg> file to write the log to
--norc do not load ~/.monotone/monotonerc or _MTN/
monotonerc lua files
--nostd do not load standard lua hooks
--quiet suppress verbose, informational and progress
messages
--rcfile <arg> load extra rc file
--reallyquiet suppress warning, verbose, informational and
progress messages
--root <arg> limit search for workspace to specified root
--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
--ticker <arg> set ticker style (count|dot|none)
--version print version number, then exit
--xargs [ -@ ] <arg> insert command line arguments taken from the
given file
Commands for workspace manipulation:
add Adds files to the workspace
attr Manages file attributes
commit, ci Commits workspace changes to the database
drop, rm Drops files from the workspace
mkdir Creates directories and adds them to the
workspace
pivot_root Renames the root directory
pluck Applies changes made at arbitrary places in
history
rename, mv Renames entries in the workspace
revert Reverts files and/or directories
update Updates the workspace
Use "mtn help <command>" for more information on a particular command.
Finally, the output for "mtn help <command>" would be the same as
currently.
Does that meet your requirements of helpfulness?
Cheers,
Will :-}