Add documentation for transient prompt

CHANGELOG.rst

@@ -4,6 +4,7 @@ fish 4.1.0 (released ???)
 Notable improvements and fixes
 ------------------------------
 - Compound commands (``begin; echo 1; echo 2; end``) can now be now be abbreviated using braces (``{ echo1; echo 2 }``), like in other shells.
+- Fish now supports transient prompts: if ``fish_transient_prompt`` is set to 1, fish will reexecute prompt functions with the ``--final-rendering`` argument before running a commandline.
 - When tab completion results are truncated, any common directory name is omitted. E.g. if you complete "share/functions", and it includes the files "foo.fish" and "bar.fish",
   the completion pager will now show "…/foo.fish" and "…/bar.fish". This will make the candidates shorter and allow for more to be shown at once.
 - The self-installing configuration introduced in fish 4.0 has been changed.

doc_src/cmds/fish_prompt.rst

@@ -20,10 +20,12 @@ Synopsis
 Description
 -----------
 
-The ``fish_prompt`` function is executed when the prompt is to be shown, and the output is used as a prompt.
+The ``fish_prompt`` function is executed when the prompt is to be shown and, if ``fish_transient_prompt`` is set to 1, before running a commandline. The output of this function is used as a prompt.
 
 The exit status of commands within ``fish_prompt`` will not modify the value of :ref:`$status <variables-status>` outside of the ``fish_prompt`` function.
 
+When the function is executed before running a commandline, it is passed a ``--final-rendering`` argument.
+
 ``fish`` ships with a number of example prompts that can be chosen with the ``fish_config`` command.
 
 

doc_src/interactive.rst

@@ -217,6 +217,8 @@ This prompt is determined by running the :doc:`fish_prompt <cmds/fish_prompt>` a
 The output of the former is displayed on the left and the latter's output on the right side of the terminal.
 For :ref:`vi mode <vi-mode>`, the output of :doc:`fish_mode_prompt <cmds/fish_mode_prompt>` will be prepended on the left.
 
+If ``fish_transient_prompt`` is set to 1, fish will redraw the prompt with a ``--final-rendering`` argument before running a commandline, allowing you to change it before pushing it to the scrollback.
+
 Fish ships with a few prompts which you can see with :doc:`fish_config <cmds/fish_config>`. If you run just ``fish_config`` it will open a web interface [#]_ where you'll be shown the prompts and can pick which one you want. ``fish_config prompt show`` will show you the prompts right in your terminal.
 
 For example ``fish_config prompt choose disco`` will temporarily select the "disco" prompt. If you like it and decide to keep it, run ``fish_config prompt save``.

doc_src/prompt.rst

@@ -148,10 +148,49 @@ And it looks like:
 .. parsed-literal::
     :class: highlight
 
+    :green:`~/M/L/Oneknowing`>false
     :green:`~/M/L/Oneknowing`\ :red:`[1]`>_
 
 after we run ``false`` (which returns 1).
 
+Transient prompt
+----------------
+
+To enable transient prompt functionality, set the ``fish_transient_prompt`` variable to 1::
+
+  set -g fish_transient_prompt 1
+
+With this set, fish re-runs prompt functions with a ``--final-rendering`` argument before running a commandline.
+So you can use it to declutter your old prompts. For example if you want to see only the current directory name when you scroll up::
+
+  function fish_prompt
+      set -l last_status $status
+      set -l stat
+      set -l pwd
+      # Check if it's a transient or final prompt
+      if contains -- --final-rendering $argv
+          set pwd (path basename $PWD)
+      else
+          set pwd (prompt_pwd)
+          # Prompt status only if it's not 0
+          if test $last_status -ne 0
+              set stat (set_color red)"[$last_status]"(set_color normal)
+          end
+      end
+
+      string join '' -- (set_color green) $pwd (set_color normal) $stat '>'
+  end
+
+Now this would print:
+
+.. role:: green
+.. role:: red
+.. parsed-literal::
+    :class: highlight
+
+    :green:`Oneknowing`>false
+    :green:`~/M/L/Oneknowing`\ :red:`[1]`>_
+
 Save the prompt
 ---------------
 

doc_src/tutorial.rst

@@ -649,6 +649,29 @@ This prompt would look like:
     :purple:`02/06/13`
     :red:`/home/tutorial >` _
 
+You can make your prompt transient by setting ``fish_transient_prompt`` to 1. That means fish will redraw the prompt before running a commandline, so you can change it then. Usually this is used to trim it down to declutter your terminal's scrollback history. When it runs the prompt again, it will pass a ``--final-rendering`` argument, so check for this to distinguish::
+
+    function fish_prompt
+        if contains -- --final-rendering $argv
+            set_color F00
+            echo '$' (set_color normal)
+        else
+            set_color purple
+            date "+%m/%d/%y"
+            set_color F00
+            echo (pwd) '>' (set_color normal)
+        end
+    end
+
+
+This would look like:
+
+.. parsed-literal::
+    :class: highlight
+
+    :red:`$` command
+    :purple:`02/06/13`
+    :red:`/home/tutorial >` _
 
 You can choose among some sample prompts by running ``fish_config`` for a web UI or ``fish_config prompt`` for a simpler version inside your terminal.