Update help text and documentation for history -t argument (#1440)

* Update help text and documentation for history -t argument

Clarified that this actually re-runs the select commands since the expected output from the commands isn't saved in the history along with the commands themselves.

* Update 2.6.0 release date in preparation for a release

* Fixed unit test

* Fix self.last_resort typo

Author: tleonhardt

CHANGELOG.md

@@ -1,10 +1,11 @@
-## 2.6.0 (May TBD, 2025)
+## 2.6.0 (May 31, 2025)
 
 - Breaking Change
     - `cmd2` 2.6 supports Python 3.9+ (removed support for Python 3.8)
 - Enhancements
-    - Add support for Python 3.14
+    - Added support for Python 3.14
     - Added new `Cmd.ppretty()` method for pretty printing arbitrary Python data structures
+    - Clarified help text for `-t`/`--transcript` argument to the `history` command
 
 ## 2.5.11 (January 25, 2025)
 

cmd2/cmd2.py

@@ -4502,7 +4502,7 @@ def do_py(self, _: argparse.Namespace) -> Optional[bool]:
 
         :return: True if running of commands should stop.
         """
-        # self.last_resort will be set by _run_python()
+        # self.last_result will be set by _run_python()
         return self._run_python()
 
     run_pyscript_parser = argparse_custom.DEFAULT_ARGUMENT_PARSER(description="Run a Python script file inside the console")
@@ -4537,7 +4537,7 @@ def do_run_pyscript(self, args: argparse.Namespace) -> Optional[bool]:
             # Overwrite sys.argv to allow the script to take command line arguments
             sys.argv = [args.script_path, *args.script_arguments]
 
-            # self.last_resort will be set by _run_python()
+            # self.last_result will be set by _run_python()
             py_return = self._run_python(pyscript=args.script_path)
         finally:
             # Restore command line arguments to original state
@@ -4632,7 +4632,7 @@ def do_ipy(self, _: argparse.Namespace) -> Optional[bool]:  # pragma: no cover
         '-t',
         '--transcript',
         metavar='TRANSCRIPT_FILE',
-        help='output commands and results to a transcript file,\nimplies -s',
+        help='create a transcript file by re-running the commands,\nimplies both -r and -s',
         completer=path_complete,
     )
     history_action_group.add_argument('-c', '--clear', action='store_true', help='clear all history')
@@ -4730,7 +4730,7 @@ def do_history(self, args: argparse.Namespace) -> Optional[bool]:
             try:
                 self.run_editor(fname)
 
-                # self.last_resort will be set by do_run_script()
+                # self.last_result will be set by do_run_script()
                 return self.do_run_script(utils.quote_string(fname))
             finally:
                 os.remove(fname)
@@ -4750,7 +4750,7 @@ def do_history(self, args: argparse.Namespace) -> Optional[bool]:
                 self.pfeedback(f"{len(history)} command{plural} saved to {full_path}")
                 self.last_result = True
         elif args.transcript:
-            # self.last_resort will be set by _generate_transcript()
+            # self.last_result will be set by _generate_transcript()
             self._generate_transcript(list(history.values()), args.transcript)
         else:
             # Display the history items retrieved
@@ -5093,7 +5093,7 @@ def do_run_script(self, args: argparse.Namespace) -> Optional[bool]:
             self._script_dir.append(os.path.dirname(expanded_path))
 
             if args.transcript:
-                # self.last_resort will be set by _generate_transcript()
+                # self.last_result will be set by _generate_transcript()
                 self._generate_transcript(
                     script_commands,
                     os.path.expanduser(args.transcript),

docs/features/history.md

@@ -127,6 +127,10 @@ The `history` command can also save both the commands and their output to a text
 
 The `--transcript` option implies `--run`: the commands must be re-run in order to capture their output to the transcript file.
 
+!!! warning
+
+    Unlike the `-o`/`--output-file` option, the `-t`/`--transcript` option will actually run the selected history commands again. This is necessary for creating a transcript file since the history saves the commands themselves but does not save their output. Please note that a side-effect of this is that the commands will appear again at the end of the history.
+
 The last action the history command can perform is to clear the command history using `-c` or `--clear`:
 
     (Cmd) history -c

tests/conftest.py

@@ -65,8 +65,8 @@ def verify_help_text(
   -o, --output_file FILE
                         output commands to a script file, implies -s
   -t, --transcript TRANSCRIPT_FILE
-                        output commands and results to a transcript file,
-                        implies -s
+                        create a transcript file by re-running the commands,
+                        implies both -r and -s
   -c, --clear           clear all history
 
 formatting: