What should show in cmd2 history?

[kmvanbrunt]

@kotfu @tleonhardt
This question pertains to cmd2's history and not readline's.

Currently we put what the user typed in history. (statement.raw) Is there any reason why can't put what was run instead? (statement.command_and_args)

That would make it clearer when things like shortcuts and aliases are entered. You will have a record of what actually occurred.

[kotfu]

I had this same thought last time I fixed a transcript bug. It's confusing now because you can't see what actually got run when you type an alias. If we switched it it would be confusing because when you use the history command it won't show what you typed.

What do you think about a developer setting (not a user available setting) which would allow the developer to choose one of these behaviors?

[tleonhardt]

As long as it doesn't present too big of a maintenance headache, I like the idea of a developer setting which would allow ability to choose one of these behaviors; because as you discussed there is a potential confusion either way.

[kmvanbrunt]

What would the default be?

[kotfu]

I think the default should be to put what the user typed into the history. That's what cmd.cmd does, and that's what cmd2 has done thus far.

We need to proceed carefully here. A quick look at the code indicates that we could easily break transcripts by messing with this. statement.command_and_args excludes any output redirection clauses the user typed. Our current unit tests don't cover these types of scenarios very well, so if we proceed to make a change, I suggest we create more robust history and transcript tests, and then once those are committed and passing with no code changes to cmd2.Cmd, then we can start to implement this new setting.

A completely different alternative might be to add a new command line switch to the history command, which outputs the commands with shortcuts and aliases expanded. This would make it explicit, available to the user, and wouldn't break any existing functionality.

[kmvanbrunt]

What about adding a member to HistoryItem that's the resolved command? The history output could somehow print both if the raw is different than command_and_args.

[lancestarr]

I agree with @kotfu: by default, history should show what the user typed, and a command like history --expanded should expand macros and aliases. Why not make both available to users? That gives them the tools they need to work around any issue they have with one or the other.

Perhaps even a third option (history --verbose?) could do what Mr. @kmvanbrunt said--"print both if the raw is different than command_and_args."

This is almost totally unrelated, but it's about history. I don't like the default option that prints separators. If there's a good reason for that, it's fine; otherwise, I suggest that we make the default (non-script) look more like bash's history output (right-aligned entry numbers followed by left-aligned entries).

[kmvanbrunt]

Even if we add flags to the history command, I believe we still need to store both the raw and command_and_args values in HistoryItem. That way we only have to resolve the command once.

Plus, a user's parsing hooks might be dependent on state and resolve a command differently if run again. Therefore we need to store what was resolved at the time the user ran it.

[tleonhardt]

Excellent conversation and suggestions! So here is my summary and proposal of what we want to do moving forward:

• By default the history command will print what the user typed, just like it does now
• A new -x/--expanded flag will be added to the history command which expands aliases, macros, and shortcuts to show the fully-resolved command which got executed
  • Note: -e was already taken for --edit
• A new -v/--verbose flag will be added to the history command which will output both what the user typed and the fully resolved command
• The HistoryItem class will be modified to store both what the user typed and the resolved command
• The separators between history items in the printout will be removed and we will switch to a more bash-like presentation that starts with a right-aligned number followed by a left-aligned command

Does that work for everyone? Or is there something you thing should be different?

[lancestarr]

In my ideal world, history -v would always show the raw command first, then, only if the expanded command differs, show it also. I'd have to play with it to see whether I'd prefer the expanded command in a separate column (that is, the output would be in tabular format) or simply enclosed in parentheses or some other begin-end pair of characters. My main point is to get rid of the possible interpretation that it would always show both commands, even if they were identical. Given the other two ways to run the history command, I see no need for showing the duplicate information.

These flags will combine with the script output flag to remove the command numbers.

Do they also need to combine with the transcript output? I believe so--at least for the -x flag--but I bring it up just to see if anyone really cares about the transcript output. The help text for it is confusing and @kmvanbrunt and I weren't able to fix it or figure out (in the twenty seconds we spent on it) what it was really supposed to do. Does it save the results from every command you've run so it can show the results to you again? Does it rerun the commands? Or am I just confused about what it's supposed to do? Anyway, I figured one way to quell some of the confusion would be to eliminate it.

[tleonhardt]

@lancestarr I like the idea of history -v only showing both if they are different.

For transcript output, it actually re-runs the commands and generates a transcript for regression testing. I know this feature is a little confusing, but it is actually used by end users for their testing purposes. Generating a transcript in this fashion is typically much easier than doing it by hand. Perhaps we could clarify the help text for the -t flag to make it more clear. And yes, people really care about transcript output - I'm aware of one end user who no longer writes unit tests and writes transcript tests instead.

The Transcript based testing section of the cmd2 docs contains more info.

[kotfu]

I like all of this. One suggestion: lets add a deep copy of the Statement object to the HistoryItem instead of raw, command and args, etc. That way we are sure to have everything we might ever need, and can continue to encapsulate any code to split/join parts of the statement into that class.