Display Command Plan

Information and brainstorming about the planned hg display command.

1. Overview

Currently, Mercurial has a number of commands to show information. And, there are always new features that will introduce more concepts and commands for showing information.

Currently, when introducing a new class of data or a view that we wish to expose to the user, the strategy is to introduce a new command or overload an existing command, sometimes both. For example, there is a desire to formalize the wip/smartlog/underway/mine functionality that many have devised. There is also a desire to introduce a "topics" concept. In the current model, we'd need a new command for wip/smartlog/etc (that behaves a lot like a pre-defined alias of hg log). For topics, we'd likely overload hg topic[s] to both display and manipulate topics.

Adding new commands for every pre-defined query doesn't scale well and pollutes hg help. Overloading commands to perform read-only and write operations is arguably an UX anti-pattern: while having all functionality for a given concept in one command is nice, having a single command doing multiple discrete operations is not. Furthermore, a user may be surprised that a command they thought was read-only actually changes something.

We discussed this at the Mercurial 4.0 Sprint in Paris and decided that having a single command where we could hang pre-defined views of various data would be a good idea. Having such a command would:

• Help prevent an explosion of new query-related commands
• Create a clear separation between read and write operations (mitigates footguns)
• Avoids overloading the meaning of commands that manipulate data (bookmark, tag, branch, etc) (while we can't take away the existing behavior for BC reasons, we now won't introduce this behavior on new commands)
• Allows users to discover informational views more easily by aggregating them in a single location
• Lowers the barrier to creating the new views (since the barrier to creating a top-level command is relatively high)

2. Proposal

An hg display <view> command will provide a facility for easily showing data.

3. Sprint Discussion Notes

At the 4.0 Sprint, we discussed and discarded various alternatives to hg display.

We considered making hg log <view> perform this behavior. The main reason we can't do this is because a positional argument to hg log can be a file path and if there is a conflict between a path name and a view name, behavior is ambiguous. We could have introduced hg log --view or similar, but we felt that required too much typing (we don't want to require a command flag to show a view) and wasn't very discoverable. Furthermore, hg log is optimized for showing changelog data and there are things that hg display could display that aren't changelog centric.

For the command name, we would have preferred hg show because it is shorter and not ambigious with any other core command. However, a number of people have created hg show as effectively an alias to hg export. And, some were concerned that Git users used to git show being equivalent to hg export (in the common case) would be confused by a hg show doing something different.

We also considered hg view, but that is already used by the "hgk" extension.

"display" is an accurate description of what the command does. The biggest concern with "display" we identifier was "di" is a shared prefix with "diff." That concern can be addressed by forcing "di" or even "d" to redirect to "diff." So "display" was chosen as the command name.

4. Planned Views

We'll want hg display to have views for the following.

Things we have dedicated commands for now:

• bookmarks
• branches
• tags
• heads
• MQ series

Things we want to expose:

• smartlog/wip/underway (concise graph view of non-public changesets and other relevant changeset)
• "my" changesets (changesets where author == ui.username)
• current stack
• all stacks
• topics

5. Other Properties / Open Questions

Do we want to exclude the default template of hg display from BC so it can be tailored towards humans and changed in the future. We can make the formatter keywords BC so custom templates or styles like JSON can be used if BC is needed.

Do we want to hide integer revision numbers and only expose the hash fragment?

Do we want to use shortest(node) by default (instead of the 12 character hash fragment)?

CategoryDeveloper