[PATCH] commit: move help about --amend into verbose section

[Matt Mackall]

On Thu, 2012-07-12 at 11:27 +0200, Martin Geisler wrote:
> Adrian Buehlmann <adrian at cadifra.com> writes:
> 
> > On 2012-07-11 12:52, Martin Geisler wrote:
> >> Adrian Buehlmann <adrian at cadifra.com> writes:
> >> 
> >>> # HG changeset patch
> >>> # User Adrian Buehlmann <adrian at cadifra.com>
> >>> # Date 1341994525 -7200
> >>> # Node ID f7d6aed0b593c7574effce913229bee4f623cf3a
> >>> # Parent  6defd83a3657c5acf46284c25b3d4e6c045f5a96
> >>> commit: move help about --amend into verbose section
> >>>
> >>> This is a pretty advanced feature. It should be ok to require
> >>> --verbose to get that text.
> >> 
> >> I would like to keep the description of --amend in the main text. I
> >> fear that few users will notice the 'use "hg -v help commit" to show
> >> more info' line at the bottom. Even if they do notice, then they
> >> might assume that it'll just show the boring global options and so
> >> disregard it.
> >
> > I think that's a general question, and the answer has already be given
> > by Matt having accepted and used verbose sections.
> >
> > If there is a section applicable to the verbose pattern, then I think
> > it's surely advanced, rarely used, longwinded things like the details
> > about --amend, which is pretty scaring for new users anyway, talking
> > about bundles and whatnot.
> 
> I hope --amend will be a commonly used flag in the future. I 'qimport;
> qrefresh; qfinish' daily and some of that could be replaced with the
> simpler --amend flag.

I disagree with hiding --amend, but I do still think there's stuff in
update that's too verbose. For instance, this bit:

    The following rules apply when the working directory contains uncommitted
    changes:

    1. If neither -c/--check nor -C/--clean is specified, and if the requested
       changeset is an ancestor or descendant of the working directory's
       parent, the uncommitted changes are merged into the requested changeset
       and the merged result is left uncommitted. If the requested changeset
       is not an ancestor or descendant (that is, it is on another branch),
       the update is aborted and the uncommitted changes are preserved.
    2. With the -c/--check option, the update is aborted and the uncommitted
       changes are preserved.
    3. With the -C/--clean option, uncommitted changes are discarded and the
       working directory is updated to the requested changeset.

That's getting down to a lawyerly level of precision. It's great for
reference, but it's too much for "what's this command about?" sort of
queries.

> >> I don't think it would look very pretty and knowing myself, I would
> >> be a little annoyed that the software "hides" information for me :)
> >
> > We already do have that hiding (see above). So that decision has
> > already been made.
> 
> We've been hiding usage examples here and there. That's okay since we're
> hiding the easy stuff. You're talking about hiding the more advanced
> stuff, which I feel goes in the opposite direction.

Actually, I've put dozens of power-user examples in the verbose help of
various commands, I don't consider it the "easy stuff" at all. For
instance, this bit in 'hg help -v log':

    - summary of all changesets after the last tag:

        hg log -r "last(tagged())::" --template "{desc|firstline}\n"

-- 
Mathematics is the supreme nostalgia of our time.