Add the patch verbs: reading hunks, applying them, and unstaging

.gitattributes

@@ -24,6 +24,12 @@
 # them to avoid a spurious whole-file diff every time the solution is opened.
 *.sln text eol=crlf
 
+# Captured git diff output, kept exactly as git emitted it. A patch fixture mixes LF
+# structural lines with CRLF content lines by design, testing that the parser leaves
+# carriage returns alone, so eol normalization above would corrupt the very bytes the
+# test asserts on.
+GitIntegration.Test/Fixtures/patch-*.txt -text
+
 ###############################
 # Git Large File System (LFS) #
 ###############################

GitIntegration.Test/Builders/GitApplyBuilderTests.cs

@@ -0,0 +1,78 @@
+// Copyright (c) 2023-2026 ktsu-dev contributors
+
+namespace ktsu.GitIntegration.Test;
+
+using System;
+using System.IO;
+using System.Threading.Tasks;
+
+[TestClass]
+public class GitApplyBuilderTests
+{
+	[TestMethod]
+	public void MapsTheOptionFlags()
+	{
+		RecordingGitProcessRunner runner = new();
+
+		GitApplyBuilder index = new(runner, TestPaths.Root, "patch");
+		_ = index.ToIndex();
+		Assert.IsTrue(index.BuildArguments().Contains("--cached"));
+
+		GitApplyBuilder reversed = new(runner, TestPaths.Root, "patch");
+		_ = reversed.Reversed();
+		Assert.IsTrue(reversed.BuildArguments().Contains("--reverse"));
+
+		GitApplyBuilder checkOnly = new(runner, TestPaths.Root, "patch");
+		_ = checkOnly.Checked();
+		Assert.IsTrue(checkOnly.BuildArguments().Contains("--check"));
+	}
+
+	[TestMethod]
+	public void AlwaysSuppressesWhitespaceWarnings()
+	{
+		RecordingGitProcessRunner runner = new();
+		GitApplyBuilder builder = new(runner, TestPaths.Root, "patch");
+
+		Assert.IsTrue(
+			builder.BuildArguments().Contains("--whitespace=nowarn"),
+			"Staging content already on disk is not the moment to enforce a whitespace policy the user configured for authoring.");
+	}
+
+	[TestMethod]
+	public void RefusesEmptyPatchText()
+	{
+		RecordingGitProcessRunner runner = new();
+		GitRepository repository = new() { LocalPath = TestPaths.Root, ProcessRunner = runner };
+
+		_ = Assert.ThrowsExactly<ArgumentException>(() => _ = repository.Apply("   "));
+	}
+
+	[TestMethod]
+	public void RefusesPatchTextCarryingTheReplacementCharacter()
+	{
+		RecordingGitProcessRunner runner = new();
+		GitRepository repository = new() { LocalPath = TestPaths.Root, ProcessRunner = runner };
+
+		ArgumentException thrown = Assert.ThrowsExactly<ArgumentException>(
+			() => _ = repository.Apply("@@ -1 +1 @@\n-caf\uFFFD\n+cafe\n"),
+			"Bytes that are not valid UTF-8 decode to U+FFFD, and with ASCII context around them the patch applies and stages the replacement character while the working tree keeps the original bytes.");
+
+		StringAssert.Contains(thrown.Message, "U+FFFD", StringComparison.Ordinal);
+	}
+
+	[TestMethod]
+	public async Task DeletesTheTemporaryFileEvenWhenGitFailsAsync()
+	{
+		RecordingGitProcessRunner runner = new() { ExitCode = 1, StandardError = "error: corrupt patch" };
+		GitApplyBuilder builder = new(runner, TestPaths.Root, "not a patch\n");
+
+		_ = await Assert.ThrowsExactlyAsync<GitCommandException>(
+			async () => await builder.ExecuteAsync().ConfigureAwait(false)).ConfigureAwait(false);
+
+		string path = runner.LastArguments![^1];
+
+		Assert.IsFalse(
+			File.Exists(path),
+			"A failing patch must not leave files behind, and the failure the caller sees is git's, not the cleanup's.");
+	}
+}

GitIntegration.Test/Builders/GitBranchListBuilderTests.cs

@@ -37,7 +37,7 @@ public void PinsTheExactFormatStringSentToGit()
 	{
 		// Asserted literally rather than through GitOutputFormats. The leading %(refname) is what
 		// lets the parser tell a local branch from a remote-tracking one and drop the remote HEAD
-		// symbolic reference, so silently losing it would break both behaviours at once.
+		// symbolic reference, so silently losing it would break both behaviors at once.
 		RecordingGitProcessRunner runner = new();
 		GitBranchListBuilder builder = new(runner, TestPaths.Root);
 

GitIntegration.Test/Builders/GitCommandBuilderTests.cs

@@ -10,7 +10,7 @@ namespace ktsu.GitIntegration.Test;
 [TestClass]
 public class GitCommandBuilderTests
 {
-	/// <summary>A minimal concrete builder, exercising only the base class behaviour.</summary>
+	/// <summary>A minimal concrete builder, exercising only the base class behavior.</summary>
 	private sealed class EchoBuilder(IGitProcessRunner runner, AbsoluteDirectoryPath? repositoryPath)
 		: GitCommandBuilder<string>(runner, repositoryPath)
 	{

GitIntegration.Test/Builders/GitInitBuilderTests.cs

@@ -70,7 +70,7 @@ public void RejectsNullArguments()
 	}
 
 	[TestMethod]
-	public async Task ProbesBeforeInitialisingAndReportsAFreshRepositoryAsync()
+	public async Task ProbesBeforeInitializingAndReportsAFreshRepositoryAsync()
 	{
 		ScriptedGitProcessRunner runner = new ScriptedGitProcessRunner()
 			.Then(standardError: "fatal: not a git repository (or any of the parent directories): .git\n", exitCode: 128)

GitIntegration.Test/Builders/GitPatchBuilderTests.cs

@@ -0,0 +1,119 @@
+// Copyright (c) 2023-2026 ktsu-dev contributors
+
+namespace ktsu.GitIntegration.Test;
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+
+[TestClass]
+public class GitPatchBuilderTests
+{
+	[TestMethod]
+	public void BuildsTheDefaultPatchVector()
+	{
+		RecordingGitProcessRunner runner = new();
+		GitPatchBuilder builder = new(runner, TestPaths.Root);
+
+		string[] expectedArguments =
+		[
+			"-C", TestPaths.Root.WeakString,
+			"--no-pager",
+			"-c", "core.quotepath=false",
+			"-c", "color.ui=false",
+			"-c", "diff.suppressBlankEmpty=false",
+			"diff",
+			"--no-ext-diff",
+			"--no-textconv",
+			"--no-color",
+			"--src-prefix=a/",
+			"--dst-prefix=b/",
+		];
+
+		Assert.AreSequenceEqual(expectedArguments, builder.BuildArguments());
+	}
+
+	[TestMethod]
+	public void AlwaysPinsBothPathPrefixes()
+	{
+		RecordingGitProcessRunner runner = new();
+		GitPatchBuilder builder = new(runner, TestPaths.Root);
+
+		IReadOnlyList<string> arguments = builder.BuildArguments();
+
+		Assert.IsTrue(
+			arguments.Contains("--src-prefix=a/"),
+			"diff.noprefix emits 'diff --git f.txt f.txt' and diff.mnemonicPrefix emits 'diff --git i/f.txt w/f.txt'. Neither header carries a new-side path this parser can read, and neither patch applies without -p0.");
+		Assert.IsTrue(
+			arguments.Contains("--dst-prefix=b/"),
+			"diff.noprefix emits 'diff --git f.txt f.txt' and diff.mnemonicPrefix emits 'diff --git i/f.txt w/f.txt'. Neither header carries a new-side path this parser can read, and neither patch applies without -p0.");
+	}
+
+	[TestMethod]
+	public void AlwaysDisablesBlankEmptySuppression()
+	{
+		RecordingGitProcessRunner runner = new();
+		GitPatchBuilder builder = new(runner, TestPaths.Root);
+
+		List<string> arguments = [.. builder.BuildArguments()];
+		int setting = arguments.IndexOf("diff.suppressBlankEmpty=false");
+
+		Assert.IsTrue(
+			setting > 0 && arguments[setting - 1] == "-c",
+			"diff.suppressBlankEmpty prints an empty context line as a bare newline, which ends the hunk body early and truncates the text a round trip depends on.");
+		Assert.IsTrue(
+			setting < arguments.IndexOf("diff"),
+			"Git reads -c only before the subcommand.");
+	}
+
+	[TestMethod]
+	public void MapsTheOptionFlags()
+	{
+		RecordingGitProcessRunner runner = new();
+
+		GitPatchBuilder staged = new(runner, TestPaths.Root);
+		_ = staged.Staged();
+		Assert.IsTrue(staged.BuildArguments().Contains("--cached"));
+
+		GitPatchBuilder context = new(runner, TestPaths.Root);
+		_ = context.WithContext(7);
+		Assert.IsTrue(context.BuildArguments().Contains("-U7"));
+
+		GitPatchBuilder renames = new(runner, TestPaths.Root);
+		_ = renames.DetectRenames();
+		Assert.IsTrue(renames.BuildArguments().Contains("--find-renames"));
+	}
+
+	[TestMethod]
+	public void NeverEmitsTheNulSeparator()
+	{
+		RecordingGitProcessRunner runner = new();
+		GitPatchBuilder builder = new(runner, TestPaths.Root);
+
+		Assert.IsFalse(
+			builder.BuildArguments().Contains("-z"),
+			"Patch format is line-based, and -z changes only the name-status framing this builder does not use.");
+	}
+
+	[TestMethod]
+	public void RefusesANegativeContextCount()
+	{
+		RecordingGitProcessRunner runner = new();
+		GitPatchBuilder builder = new(runner, TestPaths.Root);
+
+		_ = Assert.ThrowsExactly<ArgumentOutOfRangeException>(() => _ = builder.WithContext(-1));
+	}
+
+	[TestMethod]
+	public void RefusesAZeroContextCount()
+	{
+		RecordingGitProcessRunner runner = new();
+		GitPatchBuilder builder = new(runner, TestPaths.Root);
+
+		ArgumentOutOfRangeException thrown = Assert.ThrowsExactly<ArgumentOutOfRangeException>(
+			() => _ = builder.WithContext(0),
+			"git apply refuses a zero-context patch without --unidiff-zero, which IGitApplyBuilder does not offer, so this is the one pairing of the library's own two verbs that could never work.");
+
+		StringAssert.Contains(thrown.Message, "--unidiff-zero", StringComparison.Ordinal);
+	}
+}

GitIntegration.Test/Builders/GitPullBuilderTests.cs

@@ -195,7 +195,7 @@ public async Task ThrowsConflictWhenTheMergeLeavesConflictsAsync()
 	}
 
 	[TestMethod]
-	public async Task RecognisesARebaseConflictTooAsync()
+	public async Task RecognizesARebaseConflictTooAsync()
 	{
 		// A rebase reports its conflicts with different prose but the same "CONFLICT" marker, and
 		// leaves the repository mid-rebase rather than mid-merge. Both are conflicts to a caller.

GitIntegration.Test/Builders/GitRestoreBuilderTests.cs

@@ -0,0 +1,87 @@
+// Copyright (c) 2023-2026 ktsu-dev contributors
+
+namespace ktsu.GitIntegration.Test;
+
+using System;
+using System.Collections.Generic;
+using System.Threading.Tasks;
+
+using ktsu.Semantics.Paths;
+using ktsu.Semantics.Strings;
+
+[TestClass]
+public class GitRestoreBuilderTests
+{
+	[TestMethod]
+	public void BuildsTheRestoreVectorOnAModernGit()
+	{
+		RecordingGitProcessRunner runner = new();
+		GitRestoreBuilder builder = new(runner, TestPaths.Root, "f.txt".As<RelativeFilePath>());
+
+		IReadOnlyList<string> arguments = builder.BuildArguments();
+
+		Assert.IsTrue(arguments.Contains("restore"));
+		Assert.IsTrue(arguments.Contains("--staged"));
+		Assert.IsTrue(arguments.Contains("f.txt"));
+	}
+
+	[TestMethod]
+	public void SeparatesThePathWithABareDoubleDash()
+	{
+		RecordingGitProcessRunner runner = new();
+		GitRestoreBuilder builder = new(runner, TestPaths.Root, "f.txt".As<RelativeFilePath>());
+
+		string[] arguments = [.. builder.BuildArguments()];
+
+		Assert.AreSequenceEqual(
+			["restore", "--staged", "--", "f.txt"],
+			arguments[^4..],
+			"--end-of-options arrived in git 2.24, one release after restore, so the very versions this builder's reset fallback serves would read it as a pathspec and fail.");
+		Assert.IsFalse(
+			arguments.Contains("--end-of-options"),
+			"--end-of-options arrived in git 2.24, one release after restore, so the very versions this builder's reset fallback serves would read it as a pathspec and fail.");
+	}
+
+	[TestMethod]
+	public void RefusesANullPath()
+	{
+		RecordingGitProcessRunner runner = new();
+		GitRepository repository = new() { LocalPath = TestPaths.Root, ProcessRunner = runner };
+
+		_ = Assert.ThrowsExactly<ArgumentNullException>(() => _ = repository.Unstage(null!));
+	}
+
+	[TestMethod]
+	public async Task FallsBackToResetOnAGitOlderThanRestoreAsync()
+	{
+		// git restore arrived in 2.23. Below that, unstaging goes through reset HEAD instead, which
+		// every supported git understands.
+		ScriptedGitProcessRunner runner = new ScriptedGitProcessRunner()
+			.Then(standardOutput: "git version 2.22.0\n")
+			.Then(standardOutput: string.Empty);
+		GitRestoreBuilder builder = new(runner, TestPaths.Root, "f.txt".As<RelativeFilePath>());
+
+		_ = await builder.ExecuteAsync(TestContext.CancellationTokenSource.Token).ConfigureAwait(false);
+
+		string[] arguments = [.. runner.Invocations[1]];
+		Assert.AreSequenceEqual(["reset", "HEAD", "--", "f.txt"], arguments[^4..]);
+	}
+
+	[TestMethod]
+	public async Task TreatsExactlyTwoTwentyThreeAsSupportedAsync()
+	{
+		// The documented floor, asserted exactly: an off-by-one here silently falls back to reset
+		// for every user on the first version that supports restore.
+		ScriptedGitProcessRunner runner = new ScriptedGitProcessRunner()
+			.Then(standardOutput: "git version 2.23.0\n")
+			.Then(standardOutput: string.Empty);
+		GitRestoreBuilder builder = new(runner, TestPaths.Root, "f.txt".As<RelativeFilePath>());
+
+		_ = await builder.ExecuteAsync(TestContext.CancellationTokenSource.Token).ConfigureAwait(false);
+
+		string[] arguments = [.. runner.Invocations[1]];
+		Assert.AreSequenceEqual(["restore", "--staged", "--", "f.txt"], arguments[^4..]);
+	}
+
+	public TestContext TestContext { get; set; } = null!;
+}

GitIntegration.Test/Builders/GitStatusBuilderTests.cs

@@ -101,7 +101,7 @@ public void ConfigurationMethodsReturnTheSameBuilderForChaining()
 	}
 
 	[TestMethod]
-	public void RejectsAnUnrecognisedUntrackedFilesMode()
+	public void RejectsAnUnrecognizedUntrackedFilesMode()
 	{
 		RecordingGitProcessRunner runner = new();
 		GitStatusBuilder builder = new(runner, TestPaths.Root);

GitIntegration.Test/Builders/GitSubmoduleBuilderTests.cs

@@ -94,9 +94,9 @@ public async Task KeepsTheRecordedGitlinkApartFromTheCheckedOutCommitAsync()
 	}
 
 	[TestMethod]
-	public async Task ReportsNoCheckedOutCommitForAnUninitialisedSubmoduleAsync()
+	public async Task ReportsNoCheckedOutCommitForAnUninitializedSubmoduleAsync()
 	{
-		// git prints the recorded gitlink again for an uninitialised submodule, which would make it
+		// git prints the recorded gitlink again for an uninitialized submodule, which would make it
 		// indistinguishable from a synchronised one if it were reported verbatim. Nothing is checked
 		// out there, so nothing is reported. Note there is no describe suffix either.
 		ScriptedGitProcessRunner runner = new ScriptedGitProcessRunner()
@@ -107,7 +107,7 @@ public async Task ReportsNoCheckedOutCommitForAnUninitialisedSubmoduleAsync()
 		IReadOnlyList<GitSubmodule> submodules =
 			await builder.ExecuteAsync(TestContext.CancellationTokenSource.Token).ConfigureAwait(false);
 
-		Assert.AreEqual(GitSubmoduleState.Uninitialised, submodules[0].State);
+		Assert.AreEqual(GitSubmoduleState.Uninitialized, submodules[0].State);
 		Assert.IsNull(submodules[0].CheckedOutSha);
 		Assert.IsNull(submodules[0].Describe);
 	}
@@ -326,7 +326,7 @@ public void MapsEveryOptionToItsFlag()
 		RecordingGitProcessRunner runner = new();
 		GitSubmoduleUpdateBuilder builder = new(runner, TestPaths.Root);
 
-		_ = builder.Initialise().Recursive().FromRemote().Force().WithDepth(1);
+		_ = builder.Initialize().Recursive().FromRemote().Force().WithDepth(1);
 
 		string[] arguments = [.. builder.BuildArguments()];
 
@@ -363,7 +363,7 @@ public void ConfigurationMethodsReturnTheSameBuilderForChaining()
 		RecordingGitProcessRunner runner = new();
 		GitSubmoduleUpdateBuilder builder = new(runner, TestPaths.Root);
 
-		Assert.AreSame(builder, builder.Initialise().Recursive().FromRemote().Force().WithDepth(1));
+		Assert.AreSame(builder, builder.Initialize().Recursive().FromRemote().Force().WithDepth(1));
 	}
 }
 
@@ -434,7 +434,7 @@ public void PushEmitsItsOwnValueSet()
 	}
 
 	[TestMethod]
-	public void RejectsAnUnrecognisedEnumValue()
+	public void RejectsAnUnrecognizedEnumValue()
 	{
 		RecordingGitProcessRunner runner = new();