From cb55d94209519a8cd432cd9fddb1a736fa88c617 2024-12-22 12:57:23
From: M Bussonnier <bussonniermatthias@gmail.com>
Date: 2024-12-22 12:57:23
Subject: [PATCH] Python vs IPython: recommend %cd, %env over !cd, !export (#14629)

https://ipython.readthedocs.io/en/latest/interactive/python-ipython-diff.html#shell-assignment
The quick overview mentioned `!cd DIR` among examples of shell commands
one might use — but that doesn't work as user would hope (can only
affect commands in same ! e.g. `!cd /; pwd`).

That's not as bad now that `!cd` prints a warning, but IMHO better to
provide the right mental model up front.

=> Replaced that with minimal motivation why `!cd` and `!export` can't
work, recommending some %magic alternatives;
moved it out of examples to not distract, and right before Magics
section.
---

diff --git a/docs/source/interactive/python-ipython-diff.rst b/docs/source/interactive/python-ipython-diff.rst
index 246f074..0265f2f 100644
--- a/docs/source/interactive/python-ipython-diff.rst
+++ b/docs/source/interactive/python-ipython-diff.rst
@@ -152,13 +152,7 @@ This allows to execute simple commands when present in beginning of the line:
     In[1]: !pwd
     /User/home/
 
-Change directory:
-
-.. code-block:: ipython
-
-    In[1]: !cd /var/etc
-
-Or edit file:
+Edit file:
 
 .. code-block:: ipython
 
@@ -198,6 +192,10 @@ You can combine the different possibilities in for loops, conditions, functions.
         !cp $file {file.split('.')[0] + '.bak'}
 
 
+Each ``!`` gets executed in a separate shell, so changing directory by ``!cd`` or env vars ``!export FOO=bar`` will have no effect.
+Use instead the built-in magics ``%cd DIR/`` (there are also ``%pushd DIR/``, ``%dirs``, ``%popd``) and ``%env FOO=bar``.
+
+
 Magics
 ------