## page was renamed from DisplayCommandPlan #pragma section-numbers 2 <> = Show Command Plan = Information and brainstorming about the planned `hg show` command. <> == 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) == Proposal == An `hg show ` command will provide a facility for easily showing data. == Sprint Discussion Notes == At the 4.0 Sprint, we discussed and discarded various alternatives to `hg display`. We considered making `hg log ` 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. == Planned Views == We'll want 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 == Other Properties / Open Questions == Do we want to exclude the default template of `hg show` 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 CategoryNewFeatures