FR: `jj help` improvements: more information about deprecated commands, their replacements, and also aliases

[drieber]

I am using jj backout as an example of a deprecated command, but my request applies to all deprecated commands.

• jj help backout explains the command, which is good, but it should also say that it is deprecated in favor of jj revert.
• jj help does not list backout. That's fine, however I think there should be a flag to jj help to produce output that includes deprecated commands.
• It would be very useful to have a way to get information about aliases.

Those features would make it much easier to understand documentation, examples, etc that refer to deprecated commands or use aliases.

[martinvonz]

I think the part about aliases is #2866

[drieber]

I looked a bit into what it takes to add a command-line flag to jj help for including the hidden commands, and saw the clap crate is used for managing commands/sub-commands, and saw we are using #[command(hide = true)] annotations to mark deprecated commands as hidden, e.g. here https://github.com/jj-vcs/jj/blob/1cdd79071e6101aa8c0c89634632c57197525c8b/cli/src/commands/backout.rs#L34 ... It seems to me we want to add some arg to jj help, say --verbose or --include-hidden, and have help.rs somehow override those "hide" annotations (to unhide) whenever --include-hidden=true.

I also noticed clap has a concept of short form versus long form, and there seems to be separate knobs for hidden in short form versus hidden in long form.

I don't know if the rest of this comment is useful, but here it goes:

I see this call chain: cmd_help (jj) -> try_get_matches_from -> try_get_matches_from_mut -> _do_parse -> _build_self -> check_help_and_version -> long_help_exists

https://docs.rs/clap_builder/4.5.37/src/clap_builder/builder/command.rs.html#5066

    fn long_help_exists_(&self) -> bool {
        debug!("Command::long_help_exists");
        // In this case, both must be checked. This allows the retention of
        // original formatting, but also ensures that the actual -h or --help
        // specified by the user is sent through. If hide_short_help is not included,
        // then items specified with hidden_short_help will also be hidden.
        let should_long = |v: &Arg| {
            !v.is_hide_set()
                && (v.get_long_help().is_some()
                    || v.is_hide_long_help_set()
                    || v.is_hide_short_help_set()
                    || (!v.is_hide_possible_values_set()
                        && v.get_possible_values()
                            .iter()
                            .any(PossibleValue::should_show_help)))
        };

        // Subcommands aren't checked because we prefer short help for them, deferring to
        // `cmd subcmd --help` for more.
        self.get_long_about().is_some()
            || self.get_before_long_help().is_some()
            || self.get_after_long_help().is_some()
            || self.get_arguments().any(should_long)
    }

So maybe we can change the annotations to hide deprecated commands in short help form, but not in long form?

I did not go any further than that.

[yuja]

So maybe we can change the annotations to hide deprecated commands in short help form, but not in long form?

Maybe no? I don't think jj -h (short) and jj --help (long) should differ in whether deprecated commands are listed.

[drieber]

So maybe we can change the annotations to hide deprecated commands in short help form, but not in long form?

Maybe no? I don't think jj -h (short) and jj --help (long) should differ in whether deprecated commands are listed.

Ok, I accept long help is not the correct way to show hidden commands. We can still add --show-hidden or something like that. How do you feel about that?

[yuja]

We can still add --show-hidden or something like that.

Yeah, jj help --show-hidden/--include-hidden? sounds good to me. (Things might get complicated if we wanted to support jj ... --help --show-hidden, though.)

[joyously]

Funny timing...I was just trying to list the config default values, and I thought it would be --show-default, but I had to do the --help to find out it's --include-defaults.