gh-76303: Improve documentation of the -x command line option (GH-155559)

https://github.com/python/cpython/commit/4b04d5abcd8476af4c4a67fcf2263c856fdabb47
commit: 4b04d5abcd8476af4c4a67fcf2263c856fdabb47
branch: main
author: Serhiy Storchaka <[email protected]>
committer: serhiy-storchaka <[email protected]>
date: 2026-08-11T17:45:45+03:00
summary:

gh-76303: Improve documentation of the -x command line option (GH-155559)

Expand the documentation for the -x command-line option to explain its
purpose and usage for turning Python scripts into Windows batch files,
with examples of batch file header lines.

Co-authored-by: Rory Glenn <[email protected]>
Co-authored-by: Brian Schubert <[email protected]>

files:
M Doc/using/cmdline.rst

diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst
index 677fbbae3f4219a..bd75afc18d03aea 100644
--- a/Doc/using/cmdline.rst
+++ b/Doc/using/cmdline.rst
@@ -519,7 +519,25 @@ Miscellaneous options
 .. option:: -x
 
    Skip the first line of the source, allowing use of non-Unix forms of
-   ``#!cmd``.  This is intended for a DOS specific hack only.
+   ``#!cmd``.
+
+   This can be used to turn a Python script into a Windows batch file.
+   Similarly to adding a shebang line and setting the executable bit on Unix,
+   the extension of the Python script can be changed to ``.bat`` and the
+   following line can be added at the start of the script:
+
+   .. code-block:: batch
+
+      @py -x "%~f0" %* & exit /b
+
+   Or, to specify the path to the Python interpreter explicitly:
+
+   .. code-block:: batch
+
+      @"C:\Path\to\python.exe" -x "%~f0" %* & exit /b
+
+   Unlike a shebang line which is a Python comment, this line is not valid
+   Python syntax, and the :option:`-x` option is needed to skip it.
 
 
 .. option:: -X

_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]