Add partial multi-repo format test and doc caveat

Final review follow-ups: cover format on one repo of a multi-repo
project whose upstream models live only in prod state, warn in the
load_state docstring that plan/apply in multi-repo setups need it,
and clarify why the CLI gate sits outside the single-path block.

Signed-off-by: Joe Hartshorn <8881940+j-hartshorn@users.noreply.github.com>

Author: j-hartshorn

sqlmesh/cli/main.py

@@ -116,7 +116,7 @@ def cli(
     configure_console(ignore_warnings=ignore_warnings)
 
     load = True
-    # Outside the single-path block: applies regardless of --paths count.
+    # Local-only gating must hold for any number of --paths, so it stays outside the block below.
     load_state = ctx.invoked_subcommand not in LOCAL_ONLY_COMMANDS
 
     if len(paths) == 1:

sqlmesh/core/context.py

@@ -364,6 +364,8 @@ class GenericContext(BaseContext, t.Generic[C]):
         concurrent_tasks: The maximum number of tasks that can use the connection concurrently.
         load: Whether or not to automatically load all models and macros (default True).
         load_state: Whether to merge remote state into the local project during load (default True).
+            Only intended for local-only operations like format; plan/apply in multi-repo projects
+            require it to see models owned by other projects.
         console: The rich instance used for printing out CLI command results.
         users: A list of users to make known to SQLMesh.
     """

tests/cli/test_cli.py

@@ -2271,6 +2271,16 @@ def test_format_runs_without_state(runner: CliRunner, tmp_path: Path, mocker):
     mock.assert_not_called()
 
 
+def test_format_runs_without_state_multi_repo_partial(runner: CliRunner, copy_to_temp_path, mocker):
+    """Format one repo of a multi-repo project whose upstream models live only in prod state."""
+    repo_2 = copy_to_temp_path("examples/multi")[0] / "repo_2"
+    mock = _patch_state_access(mocker)
+
+    result = runner.invoke(cli, ["--gateway", "memory", "--paths", str(repo_2), "format"])
+    assert result.exit_code == 0, f"Format failed: {result.output}\nException: {result.exception}"
+    mock.assert_not_called()
+
+
 def test_lint_still_loads_state(runner: CliRunner, tmp_path: Path, mocker):
     """Guard that `lint` explicitly passes `load_state=True` and still reaches state sync."""
     mock = _setup_local_only_project(tmp_path, mocker)