From aae138245be8d71ca6290fb1858aed20dfa4bb73 Mon Sep 17 00:00:00 2001
From: Oleksii Holub <1935960+Tyrrrz@users.noreply.github.com>
Date: Fri, 6 Dec 2024 21:11:59 +0200
Subject: [PATCH] Expose `ArgumentsBuilder.Escape(...)` (#265)

---
 CliWrap/Builders/ArgumentsBuilder.cs | 11 ++++++++++-
 Readme.md                            |  4 ++++
 2 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/CliWrap/Builders/ArgumentsBuilder.cs b/CliWrap/Builders/ArgumentsBuilder.cs
index 361c5dd7..3b474f41 100644
--- a/CliWrap/Builders/ArgumentsBuilder.cs
+++ b/CliWrap/Builders/ArgumentsBuilder.cs
@@ -142,7 +142,16 @@ public ArgumentsBuilder Add(IEnumerable<IFormattable> values, bool escape) =>
 
 public partial class ArgumentsBuilder
 {
-    private static string Escape(string argument)
+    /// <summary>
+    /// Escapes special characters (spaces, slashes, and quotes) in the specified string, ensuring that the output
+    /// is correctly interpreted as a single argument when passed to a command-line application.
+    /// </summary>
+    /// <remarks>
+    /// In most cases, you should not need to use this method, as <see cref="ArgumentsBuilder" /> already escapes
+    /// arguments automatically. This method is provided for advanced scenarios where you need to escape arguments
+    /// manually.
+    /// </remarks>
+    public static string Escape(string argument)
     {
         // Implementation reference:
         // https://github.com/dotnet/runtime/blob/9a50493f9f1125fda5e2212b9d6718bc7cdbc5c0/src/libraries/System.Private.CoreLib/src/System/PasteArguments.cs#L10-L79
diff --git a/Readme.md b/Readme.md
index c47c7f1a..1f1f59a2 100644
--- a/Readme.md
+++ b/Readme.md
@@ -219,6 +219,10 @@ var cmd = Cli.Wrap("git")
 > This method expects all arguments to be correctly escaped and formatted ahead of time — which can be cumbersome to do yourself.
 > Formatting errors may result in unexpected bugs and security vulnerabilities.
 
+> **Note**:
+> There are some [obscure scenarios](https://github.com/Tyrrrz/CliWrap/issues/263), where you may need to assemble the command-line arguments yourself.
+> In such cases, you can use the `ArgumentsBuilder.Escape(...)` method to escape individual arguments manually.
+
 #### `WithWorkingDirectory(...)`
 
 Sets the working directory of the child process.