Add dry run option, test, and documentation

docs/usage.rst

@@ -383,6 +383,22 @@ Would run both ``install`` commands, but skip the ``run`` command:
     nox > Skipping pytest run, as --install-only is set.
     nox > Session tests was successful.
 
+Skipping every command and only outputting the commands that would be run
+-------------------------------------------------------------------------
+
+If you want to see what commands would be run without actually running them, you can use ``--dry-run``:
+
+.. code-block:: console
+
+    nox --dry-run
+    nox > Would run session tests but --dry-run is set.
+    nox > Running session tests
+    nox > Creating virtualenv using python3.7 in ./.nox/tests
+    nox > python -m pip install pytest
+    nox > python -m pip install .
+    nox > python -m pytest
+    nox > Session tests was successful.
+
 
 Forcing non-interactive behavior
 --------------------------------

nox/_options.py

@@ -626,6 +626,13 @@ def _tag_completer(
         hidden=True,
         default=os.getcwd,
     ),
+    _option_set.Option(
+        "dry_run",
+        "--dry-run",
+        group=options.groups["execution"],
+        action="store_true",
+        help="Print the commands that would run without running them.",
+    ),
 )
 
 

nox/sessions.py

@@ -405,6 +405,10 @@ def run(
             msg = "First argument to `session.run` is a list. Did you mean to use `session.run(*args)`?"
             raise ValueError(msg)
 
+        if self._runner.global_config.dry_run:
+            logger.info(f"Would run: {args}, but --dry-run is set.")
+            return None
+
         if self._runner.global_config.install_only:
             logger.info(f"Skipping {args[0]} run, as --install-only is set.")
             return None
@@ -481,6 +485,11 @@ def run_install(
             Default: ``0.2``
         :type terminate_timeout: float or None
         """
+
+        if self._runner.global_config.dry_run:
+            logger.info(f"Would run: {args}, but --dry-run is set.")
+            return None
+
         if (
             self._runner.global_config.no_install
             and self._runner.venv is not None
@@ -664,6 +673,10 @@ def conda_install(
         if not args:
             raise ValueError("At least one argument required to install().")
 
+        if self._runner.global_config.dry_run:
+            logger.info(f"Would run: {args}, but --dry-run is set.")
+            return None
+
         if self._runner.global_config.no_install and (
             isinstance(venv, PassthroughEnv) or venv._reused
         ):
@@ -761,6 +774,9 @@ def install(
                 "A session without a virtualenv can not install dependencies."
             )
         if isinstance(venv, PassthroughEnv):
+            if self._runner.global_config.dry_run:
+                logger.info(f"Would run: {args}, but --dry-run is set.")
+                return None
             if self._runner.global_config.no_install:
                 return
             raise ValueError(
@@ -772,6 +788,10 @@ def install(
         if not args:
             raise ValueError("At least one argument required to install().")
 
+        if self._runner.global_config.dry_run:
+            logger.info(f"Would run: {args}, but --dry-run is set.")
+            return
+
         if self._runner.global_config.no_install and venv._reused:
             return
 

tests/test_sessions.py

@@ -287,6 +287,14 @@ def test_run_install_only_should_install(self):
             **run_with_defaults(paths=mock.ANY, silent=True, env={}, external="error"),
         )
 
+    def test_run_dry_run(self):
+        session, _ = self.make_session_and_runner()
+
+        with mock.patch("nox.command.run", autospec=True) as run:
+            session.run(sys.executable, "--version", dry_run=True)
+
+        run.assert_not_called()
+
     def test_run_success(self):
         session, _ = self.make_session_and_runner()
         result = session.run(sys.executable, "-c", "print(123)")