Merge pull request #206 from chu11/faq_prompt

faqs: add entry on shell prompt

Author: mergify[bot]

auto_examples/auto_examples_jupyter.zip

@@ -71,8 +71,6 @@ F58 to another using the :core:man1:`flux-job` ``id`` subcommand, e.g.
    airline-alibi-index--tuna-maximum-adam
    $ flux job cancel airline-alibi-index--tuna-maximum-adam
 
-.. _flux_run_mac:
-
 With copy-and-paste, auto-completion, globbing, etc., it shouldn't be necessary
 to *type* a job ID with the ``ƒ`` prefix that often, but should you need to,
 use your terminal's method for inputting a
@@ -89,13 +87,51 @@ If your `Konsole <https://konsole.kde.org/>`_ terminal displays ``ƒ`` as ``Æ``
 check that Settings →  Edit →  Profile →  Advanced →  Encoding: Default
 Character Encoding is set to ``UTF-8``, not ``ISO8859-1``.
 
+.. _flux_run_mac:
+
 Does flux run on a Mac?
 =======================
 
 Not yet. We have an open `issue <https://github.com/flux-framework/flux-core/issues/2892>`_
 on GitHub tracking the progress towards the goal of natively compiling on a
 mac. In the meantime, you can use Docker, see: :ref:`quickstart`.
 
+.. _flux_shell_prompt:
+
+Can you recommend a shell prompt?
+=================================
+
+It can sometimes be tricky dealing with Flux hierarchies of instances.  A common
+shell prompt adjustment used by Flux users adds Flux resource size and
+instance depth into the prompt.  For example, the following prompt shows that
+we have 64 nodes of resources and are at depth 1.
+
+.. code-block:: console
+
+    [s=64,d=1] $
+
+To add this prompt into your shell, you can cut and paste the below or use it to
+adjust your current shell prompt.  Note that the initial call to ``flux getattr size``
+is simply used to test if you are currently running on a system with Flux or not.
+
+Cut and paste for ``.bashrc``
+
+.. code-block:: sh
+
+    flux getattr size > /dev/null 2>&1
+    if [ $? -eq 0 ]; then
+        export PS1="[s=$(flux getattr size),d=$(flux getattr instance-level)] $"
+    fi
+
+Cut and paste for ``.cshrc``
+
+.. code-block:: sh
+
+    flux getattr size >& /dev/null
+    if ( $? == 0 ) then
+        set prompt="[s=`flux getattr size`,d=`flux getattr instance-level`] $"
+    endif
+
 .. _bug_report_how:
 
 How do I report a bug?