[API Proposal]: Add TarExtractOptions/TarCreateOptions

[tmds]

Background and motivation

The Tar API that is introduced in #65951 currently provides one option while creating: includeBaseDirectory, and one option while extracting: overwriteFiles.

There are many more options that would make sense, for example controlling the owner/group that gets stored in the tar-file when creating, and controlling whether the exact permissions should be restored (including the setgroup/setuser/sticky bit). See man tar for other options that a user may want to control.

Maybe we want to introduce option classes immediately, to avoid adding additional overloads to the Create/Extract methods.

API Proposal

namespace System.Formats.Tar;

public static partial class TarFile
{
-    public static void CreateFromDirectory(string sourceDirectoryName, Stream destination, bool includeBaseDirectory);
-    public static void CreateFromDirectory(string sourceDirectoryName, string destinationFileName, bool includeBaseDirectory);
-    public static void ExtractToDirectory(Stream source, string destinationDirectoryName, bool overwriteFiles);
-    public static void ExtractToDirectory(string sourceFileName, string destinationDirectoryName, bool overwriteFiles);
+    public static void CreateFromDirectory(string sourceDirectoryName, Stream destination, TarCreateOptions? options = null);
+    public static void CreateFromDirectory(string sourceDirectoryName, string destinationFileName, TarCreateOptions? options = null);
+    public static void ExtractToDirectory(Stream source, string destinationDirectoryName, TarExtractOptions? options = null);
+    public static void ExtractToDirectory(string sourceFileName, string destinationDirectoryName, TarExtractOptions? options = null);
}
public abstract partial class TarEntry
{
-    public void ExtractToFile(string destinationFileName, bool overwrite);    
+    public void ExtractToFile(string destinationFileName, TarExtractOptions? options = null);
}

+public sealed class TarExtractOptions
+{
+    public bool OverwriteFiles { get; set; } = true;
+}
+public sealed class TarCreateOptions
+{
+    public bool IncludeBaseDirectory { get; set; } = true;
+}

API Usage

TarFile.CreateFromDirectory("D:/SourceDirectory/", "D:/destination.tar", new() { IncludeBaseDirectory = false });

Alternative Designs

No response

Risks

No response

[ghost]

Tagging subscribers to this area: @dotnet/area-system-io
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

The Tar API that is introduced in #65951 currently provides one option while creating: includeBaseDirectory, and one option while extracting: overwriteFiles.

There are many more options that would make sense, for example controlling the owner/group that gets stored in the tar-file when creating, and controlling whether the exact permissions should be restored (including the setgroup/setuser/sticky bit). See man tar for other options that a user may want to control.

Maybe we want to introduce option classes immediately, to avoid adding additional overloads to the Create/Extract methods.

API Proposal

public static partial class TarFile
{
-    public static void CreateFromDirectory(string sourceDirectoryName, System.IO.Stream destination, bool includeBaseDirectory);
-    public static void CreateFromDirectory(string sourceDirectoryName, string destinationFileName, bool includeBaseDirectory);
-    public static void ExtractToDirectory(System.IO.Stream source, string destinationDirectoryName, bool overwriteFiles);
-    public static void ExtractToDirectory(string sourceFileName, string destinationDirectoryName, bool overwriteFiles);
+    public static void CreateFromDirectory(string sourceDirectoryName, System.IO.Stream destination, TarCreateOptions? options = null);
+    public static void CreateFromDirectory(string sourceDirectoryName, string destinationFileName, TarCreateOptions? options = null);
+    public static void ExtractToDirectory(System.IO.Stream source, string destinationDirectoryName, TarExtractOptions? options = null);
+    public static void ExtractToDirectory(string sourceFileName, string destinationDirectoryName, TarExtractOptions? options = null);
}
public abstract partial class TarEntry
{
-    public void ExtractToFile(string destinationFileName, bool overwrite);    
+    public void ExtractToFile(string destinationFileName, TarExtractOptions? options = null);
}

+public sealed class TarExtractOptions
+{
+    public bool OverwriteFiles { get; set; } = true;
+}
+public sealed class TarCreateOptions
+{
+    public bool IncludeBaseDirectory { get; set; } = true;
+}

API Usage

TarFile.CreateFromDirectory("D:/SourceDirectory/", "D:/destination.tar", new() { IncludeBaseDirectory = false });

Alternative Designs

No response

Risks

No response

Author:	tmds
Assignees:	-
Labels:	api-suggestion, area-System.IO, untriaged
Milestone:	-

[tmds]

cc @carlossanlop

[GSPP]

This issue has affected quite a few other .NET classes. It starts with one innocuous bool, and over time expands into a jungle of overloads. It seems wise to immediately use the options approach, and only that.

An alternative is to create a flags enum. Of course, that can only control boolean options.

[tmds]

cc @adamsitnik @eerhardt @bartonjs @stephentoub @terrajobst

[adamsitnik]

@carlossanlop PTAL

[carlossanlop]

We did discuss these options classes in the early design stages:

+public sealed class TarExtractOptions
+{
+    public bool OverwriteFiles { get; set; } = true;
+}
+public sealed class TarCreateOptions
+{
+    public bool IncludeBaseDirectory { get; set; } = true;
+}

But since we only had one setting to add, we didn't think they were needed. So the current static methods are sufficient with their current signature. I would definitely welcome creating the two proposed classes as soon as we have more than one setting to include.

There are many more options that would make sense, for example controlling the owner/group that gets stored in the tar-file when creating, and controlling whether the exact permissions should be restored (including the setgroup/setuser/sticky bit)

I'd be interested in exploring these items you mention, making sure they are proposed in a cross-platform way, because I can see some of these settings not being Windows friendly.