FR: Support for Alias Descriptions in Config and Help Output

[rwjblue-glean]

Summary

I'd like to request the ability to add descriptions to custom aliases in the config file, and have these descriptions appear in jj --help and jj help output.

Current Behavior

Currently, my aliases look like this in my config:

[aliases]
# short alias for squash
sq = ["squash"]

# find the nearest bookmark and move it forward to the nearest pushable revision
tug = ["bookmark", "move", "--from", "closest_bookmark(@)", "--to", "closest_pushable(@)"]

When running jj --help, I notice:

1. Simple aliases to built-in commands like b for bookmark show up as bookmark Manage bookmarks [default alias: b]
2. My simple alias sq doesn't show up similarly next to the squash command
3. Custom complex aliases like tug don't show up at all

This creates a real usability issue - for aliases that I use only occasionally (like tug), I often forget their exact semantics so I have to go back and manually review my config.toml file to remind myself what it does. This adds friction to my workflow and makes my custom aliases less useful than they could be.

Proposed Solution

I propose extending the alias configuration format to support descriptions, perhaps like:

[aliases]
sq = { command = ["squash"], description = "Short alias for squash command" }
tug = { 
  command = ["bookmark", "move", "--from", "closest_bookmark(@)", "--to", "closest_pushable(@)"],
  description = "Move nearest bookmark to nearest pushable revision"
}

With this change, the jj --help output could look something like:

Jujutsu (An experimental VCS)

Usage: jj [OPTIONS] <COMMAND>

Commands:
  abandon           Abandon a revision
  bookmark          Manage bookmarks [default alias: b]
  commit            Update the description and create a new change on top
  diff              Compare file contents between two revisions
  squash            Move changes from a revision into another revision [aliases: sq]
  status            Show high-level repo status [aliases: st]
  ...

Custom Aliases:
  tug               Move nearest bookmark to nearest pushable revision

Options:
  -h, --help        Print help (see a summary with '-h')
  ...

Benefits

1. Simple aliases like sq would be shown next to their commands, similar to how built-in aliases are shown
2. Complex aliases like tug would get their own section with descriptions
3. Most importantly, I wouldn't need to go back to my config file every time I forget what an occasionally-used alias does - I could just check the help output

---

Would this feature be useful to add to jj? I think it would make custom aliases much more integrated into the tool's workflow and reduce the cognitive load of remembering what each alias does.

[joyously]

I'm not sure this is the best approach, but did you know the aliases can be output with this? jj config list --include-defaults aliases

It's not very descriptive, though, and it's a very long command. Perhaps the help command could include this in its output?

[rwjblue-glean]

I'm not sure this is the best approach, but did you know the aliases can be output with this? jj config list --include-defaults aliases

I did not know that, thank you!

It's not very descriptive, though, and it's a very long command. Perhaps the help command could include this in its output?

Yeah, totally. It is also missing any descriptions that I've made in the config file (so unless I remember what some of the more "magical" incantations actually do, I'm in the same place of not knowing if the command I'm trying to select is the right one or not).

Part of the issue is that I'm not always sure if some command I'm remembering is an alias I've created or a built-in command, or a built-in commands alias. It just seems like as a user jj help or jj --help should tell me all the things that I can call on the command line after jj ... (completions already work like this for me, but you don't get any descriptions there).

I've read a ton of folks .jj/config.toml's across GitHub and nearly all of them have comment based descriptions above their custom revsets and aliases. I think the config having a first class way to add a description to aliases would enable the rest of the system (e.g.jj help and jj config list) to include that info.

[PhilipMetzger]

I think this relates to https://github.com/jj-vcs/jj/issues/5551

[salty-horse]

At the very least, jj help ALIASNAME should say what it's an alias of.

When a user sees someone talking about built-in aliases, they should be able to find out what they mean.

[PhilipMetzger]

There's a PR for this which also hasn't landed yet, see https://github.com/jj-vcs/jj/pull/3015.