run(fix[trim]): Capture output faithfully

why: The runner trimmed each captured line and dropped blank lines,
so whitespace-significant output was corrupted: captured diffs were
rejected by `git apply`, `cat-file blob` lost indentation and blank
lines, and multi-line stderr was concatenated into one run-on line.
Single-token reads like `rev-parse HEAD` hid the defect.

what:
- Capture stdout/stderr verbatim; decode once; trim only the whole
  output (str.rstrip), preserving leading indentation, blank lines,
  and interior structure.
- Add `trim` (default True). Pass `trim=False` for byte-faithful
  output -- diffs that feed `git apply`, exact blob contents.
- Rejoin stderr without smashing lines together.
- Correct the Svn.blame doctest, which had encoded the stripped output.
- Cover trim=False fidelity, the default trim contract, and stderr
  line preservation with functional tests.

Author: tony

src/libvcs/_internal/run.py

@@ -149,6 +149,7 @@ def run(
     umask: int = -1,
     log_in_real_time: bool = False,
     check_returncode: bool = True,
+    trim: bool = True,
     callback: ProgressCallbackProtocol | None = None,
     timeout: float | None = None,
 ) -> str:
@@ -157,6 +158,13 @@ def run(
     Run 'args' in a shell and return the combined contents of stdout and
     stderr (Blocking). Throws an exception if the command exits non-zero.
 
+    Output is captured verbatim. When ``trim`` is True (the default) a single
+    pass of :meth:`str.rstrip` removes trailing whitespace from the whole
+    output, preserving leading indentation, blank lines, and interior
+    structure. Pass ``trim=False`` for byte-faithful output -- for example a
+    ``git diff`` destined for ``git apply``, which requires the trailing
+    newline, or ``git cat-file blob`` whose contents must round-trip exactly.
+
     Keyword arguments are passthrough to :class:`subprocess.Popen`.
 
     Parameters
@@ -181,6 +189,13 @@ def run(
         Indicate whether a ``libvcs.exc.CommandError`` should be raised if return
         code is different from 0.
 
+    trim : bool
+        When True (default), strip trailing whitespace from the whole output
+        for the convenient "bare value" reads callers expect (e.g.
+        ``rev-parse HEAD``). When False, return the output verbatim, including
+        any trailing newline, so whitespace-significant output (diffs, blob
+        contents) round-trips exactly.
+
     callback : ProgressCallbackProtocol
         callback to return output as a command executes, accepts a function signature
         of ``(output, timestamp)``. Example usage::
@@ -273,29 +288,25 @@ def progress_cb(output: t.AnyStr, timestamp: datetime.datetime) -> None:
         callback(output="\r", timestamp=datetime.datetime.now())
 
     if proc.stdout is not None:
-        stdout_lines: list[bytes] = (
-            timeout_stdout.split(b"\n")
+        raw_stdout: bytes = (
+            timeout_stdout
             if timeout_stdout is not None
-            else proc.stdout.readlines()
+            else b"".join(proc.stdout.readlines())
         )
-        lines: t.Iterable[bytes] = filter(
-            None,
-            (line.strip() for line in stdout_lines),
-        )
-        all_output = console_to_str(b"\n".join(lines))
+        all_output = console_to_str(raw_stdout)
+        if trim:
+            all_output = all_output.rstrip()
     else:
         all_output = ""
     if code and proc.stderr is not None:
-        stderr_raw: list[bytes] = (
-            timeout_stderr.split(b"\n")
+        raw_stderr: bytes = (
+            timeout_stderr
             if timeout_stderr is not None
-            else proc.stderr.readlines()
-        )
-        stderr_lines: t.Iterable[bytes] = filter(
-            None,
-            (line.strip() for line in stderr_raw),
+            else b"".join(proc.stderr.readlines())
         )
-        all_output = console_to_str(b"".join(stderr_lines))
+        all_output = console_to_str(raw_stderr)
+        if trim:
+            all_output = all_output.rstrip()
     output = "".join(all_output)
     if code != 0 and check_returncode:
         raise exc.CommandError(

src/libvcs/cmd/svn.py

@@ -387,7 +387,7 @@ def blame(
         >>> svn.commit(path=new_file, message='My new commit')
         '...'
         >>> svn.blame('new.txt')
-        '4        ... example text'
+        '     4 ... example text'
         """
         local_flags: list[str] = [str(target)]
 

tests/cmd/test_git.py

@@ -2704,3 +2704,80 @@ def test_rev_list_all_parameter(git_repo: GitSync) -> None:
 
     # _all=True should return strictly more commits (the other-branch commit)
     assert count_with_all > count_no_all
+
+
+def test_run_trim_false_preserves_diff(git_repo: GitSync) -> None:
+    """run(trim=False) returns byte-faithful output a patch tool can apply.
+
+    The default per-line trimming dropped leading indentation and blank
+    context lines and removed the trailing newline, so a captured
+    ``git diff`` was rejected by ``git apply`` as a corrupt patch.
+    """
+    base = (
+        "def greet(name):\n"
+        '    message = "hello, " + name\n'
+        "\n"
+        "    print(message)\n"
+        "    return message\n"
+    )
+    target = git_repo.path / "greet.py"
+    target.write_text(base)
+    git_repo.cmd.run(["add", "greet.py"])
+    git_repo.cmd.run(["commit", "-m", "Add greet.py"])
+    target.write_text(base.replace("hello, ", "hi, "))
+
+    faithful = subprocess.run(
+        ["git", "diff", "--no-color", "--", "greet.py"],
+        cwd=git_repo.path,
+        capture_output=True,
+        text=True,
+        check=True,
+    ).stdout
+    captured = git_repo.cmd.run(["diff", "--no-color", "--", "greet.py"], trim=False)
+    assert captured == faithful
+
+    # Restore the clean pre-image so the captured patch can be validated.
+    target.write_text(base)
+    check = subprocess.run(
+        ["git", "apply", "--check"],
+        cwd=git_repo.path,
+        input=captured,
+        capture_output=True,
+        text=True,
+    )
+    assert check.returncode == 0, check.stderr
+
+
+def test_run_trim_false_preserves_blob(git_repo: GitSync) -> None:
+    """run(trim=False) round-trips file contents byte-for-byte."""
+    base = "a\n    indented\n\nb\n"
+    target = git_repo.path / "blob.txt"
+    target.write_text(base)
+    git_repo.cmd.run(["add", "blob.txt"])
+    git_repo.cmd.run(["commit", "-m", "Add blob.txt"])
+
+    blob = git_repo.cmd.run(["cat-file", "blob", "HEAD:blob.txt"], trim=False)
+    assert blob == base
+
+
+def test_run_default_trims_trailing_newline(git_repo: GitSync) -> None:
+    """Default run() keeps the no-trailing-newline contract callers rely on."""
+    sha = git_repo.cmd.run(["rev-parse", "HEAD"])
+
+    assert "\n" not in sha
+    assert sha == sha.strip()
+
+
+def test_run_failure_preserves_stderr_lines(git_repo: GitSync) -> None:
+    """A failed command keeps stderr line structure in CommandError.output.
+
+    Previously stderr lines were rejoined with no separator, smashing a
+    multi-line git error into a single run-on string.
+    """
+    with pytest.raises(exc.CommandError) as excinfo:
+        git_repo.cmd.run(["push", "no-such-remote", "HEAD"])
+
+    output = excinfo.value.output
+    assert "\n" in output
+    assert "does not appear to be a git repository" in output
+    assert "Could not read from remote repository" in output