From b3e417fd055c1d9a8b0b76a1ba831de6b277b86b Mon Sep 17 00:00:00 2001 From: kerty Date: Thu, 20 Feb 2025 20:02:11 +0300 Subject: [PATCH] Add documentation for transient prompt --- CHANGELOG.rst | 1 + doc_src/cmds/fish_prompt.rst | 4 +++- doc_src/interactive.rst | 2 ++ doc_src/prompt.rst | 39 ++++++++++++++++++++++++++++++++++++ doc_src/tutorial.rst | 23 +++++++++++++++++++++ 5 files changed, 68 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index e5a551d02..474f09870 100644 --- a/CHANGELOG.rst +++ b/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. diff --git a/doc_src/cmds/fish_prompt.rst b/doc_src/cmds/fish_prompt.rst index 097bac4bd..503297553 100644 --- a/doc_src/cmds/fish_prompt.rst +++ b/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 ` 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. diff --git a/doc_src/interactive.rst b/doc_src/interactive.rst index 23453d6fd..264db2c5b 100644 --- a/doc_src/interactive.rst +++ b/doc_src/interactive.rst @@ -217,6 +217,8 @@ This prompt is determined by running the :doc:`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 `, the output of :doc:`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 `. 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``. diff --git a/doc_src/prompt.rst b/doc_src/prompt.rst index 3b3d02aa4..9fa26c9ea 100644 --- a/doc_src/prompt.rst +++ b/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 --------------- diff --git a/doc_src/tutorial.rst b/doc_src/tutorial.rst index 36fdd1ff6..65badf655 100644 --- a/doc_src/tutorial.rst +++ b/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.