[API Proposal]: Add TarEntryFormat parameter to TarFile.CreateFromDirectory

[NikolaMilosavljevic]

Background and Motivation

Currently, TarFile.CreateFromDirectory always creates archives using TarEntryFormat.Pax. The underlying TarWriter class already supports all four formats, but TarFile.CreateFromDirectory doesn't expose this capability.

API Proposal (updated by @iremyux)

namespace System.Formats.Tar;

public static partial class TarFile
{
    // Existing (no changes):
    public static void CreateFromDirectory(string sourceDirectoryName, Stream destination, bool includeBaseDirectory);
    public static void CreateFromDirectory(string sourceDirectoryName, string destinationFileName, bool includeBaseDirectory);
    public static Task CreateFromDirectoryAsync(string sourceDirectoryName, Stream destination, bool includeBaseDirectory, CancellationToken cancellationToken = default);
    public static Task CreateFromDirectoryAsync(string sourceDirectoryName, string destinationFileName, bool includeBaseDirectory, CancellationToken cancellationToken = default);

    // New overloads:
+    public static void CreateFromDirectory(string sourceDirectoryName, Stream destination, bool includeBaseDirectory, TarEntryFormat format);
+    public static void CreateFromDirectory(string sourceDirectoryName, string destinationFileName, bool includeBaseDirectory, TarEntryFormat format);
+    public static Task CreateFromDirectoryAsync(string sourceDirectoryName, Stream destination, bool includeBaseDirectory, TarEntryFormat format, CancellationToken cancellationToken = default);
+    public static Task CreateFromDirectoryAsync(string sourceDirectoryName, string destinationFileName, bool includeBaseDirectory, TarEntryFormat format, CancellationToken cancellationToken = default);
}

API Usage (updated by @iremyux)

// Create a GNU format tar archive for Linux compatibility
TarFile.CreateFromDirectory("/source/dir", "/dest/archive.tar", includeBaseDirectory: true, TarEntryFormat.Gnu);

// Create a Ustar format archive for broader compatibility
TarFile.CreateFromDirectory("/source/dir", outputStream, includeBaseDirectory: false, TarEntryFormat.Ustar);

// Async version
await TarFile.CreateFromDirectoryAsync("/source/dir", "/dest/archive.tar", includeBaseDirectory: true, TarEntryFormat.Pax, cancellationToken);

[dotnet-policy-service]

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

[kasperk81]

implementation with default parameter when api is approved: main...kasperk81:runtime:patch-3

[richlander]

Related:

• Document Debian 13 TAR header warnings in .NET 10.0 known issues core#10171

[iremyux]

Triage: It looks reasonable and straight-forward to work on. We'll try to work on it for .NET 11.
Next step: API Proposal and implementation.

[kasperk81]

API Proposal: Allow selecting TarEntryFormat in TarFile.CreateFromDirectory

Summary

TarFile.CreateFromDirectory currently always uses TarEntryFormat.Pax.
Proposal: allow callers to specify the desired TarEntryFormat.

API Proposal

Option A — update existing API with defaulted parameter

namespace System.Formats.Tar
{
    /// <summary>
    /// Provides static methods for creating and extracting tar archives.
    /// </summary>
    public static class TarFile
    {
-        public static void CreateFromDirectory(
-            string sourceDirectoryName,
-            Stream destination,
-            bool includeBaseDirectory);

+        public static void CreateFromDirectory(
+            string sourceDirectoryName,
+            Stream destination,
+            bool includeBaseDirectory,
+            TarEntryFormat format = TarEntryFormat.Pax);

-        public static Task CreateFromDirectoryAsync(
-            string sourceDirectoryName,
-            Stream destination,
-            bool includeBaseDirectory,
-            CancellationToken cancellationToken = default);

+        public static Task CreateFromDirectoryAsync(
+            string sourceDirectoryName,
+            Stream destination,
+            bool includeBaseDirectory,
+            TarEntryFormat format = TarEntryFormat.Pax,
+            CancellationToken cancellationToken = default);

-        public static void CreateFromDirectory(
-            string sourceDirectoryName,
-            string destinationFileName,
-            bool includeBaseDirectory);

+        public static void CreateFromDirectory(
+            string sourceDirectoryName,
+            string destinationFileName,
+            bool includeBaseDirectory);

-        public static Task CreateFromDirectoryAsync(
-            string sourceDirectoryName,
-            string destinationFileName,
-            bool includeBaseDirectory,
-            CancellationToken cancellationToken = default);

+        public static Task CreateFromDirectoryAsync(
+            string sourceDirectoryName,
+            string destinationFileName,
+            bool includeBaseDirectory,
+            CancellationToken cancellationToken = default);
    }
}

Option B — keep existing signatures, add new overloads

namespace System.Formats.Tar
{
    public static class TarFile
    {
        // existing overloads (unchanged)
        public static void CreateFromDirectory(
            string sourceDirectoryName,
            Stream destination,
            bool includeBaseDirectory);

        public static void CreateFromDirectory(
            string sourceDirectoryName,
            string destinationFileName,
            bool includeBaseDirectory);

        public static Task CreateFromDirectoryAsync(
            string sourceDirectoryName,
            Stream destination,
            bool includeBaseDirectory,
            CancellationToken cancellationToken = default);

        public static Task CreateFromDirectoryAsync(
            string sourceDirectoryName,
            string destinationFileName,
            bool includeBaseDirectory,
            CancellationToken cancellationToken = default);

+        public static void CreateFromDirectory(
+            string sourceDirectoryName,
+            Stream destination,
+            bool includeBaseDirectory,
+            TarEntryFormat format);

+        public static void CreateFromDirectory(
+            string sourceDirectoryName,
+            string destinationFileName,
+            bool includeBaseDirectory,
+            TarEntryFormat format);

+        public static Task CreateFromDirectoryAsync(
+            string sourceDirectoryName,
+            Stream destination,
+            bool includeBaseDirectory,
+            TarEntryFormat format,
+            CancellationToken cancellationToken = default);

+        public static Task CreateFromDirectoryAsync(
+            string sourceDirectoryName,
+            string destinationFileName,
+            bool includeBaseDirectory,
+            TarEntryFormat format,
+            CancellationToken cancellationToken = default);
    }
}

Rationale

• Enables interoperability with tools expecting non-PAX formats.
• Option A makes format selection simple via defaulted parameter.
• Option B avoids signature changes and keeps existing overloads intact.

Risk

Low: the default behavior remains TarEntryFormat.Pax, so existing functionality is unchanged; introducing the new overloads does not break source or binary compatibility, and discoverability is straightforward as the new parameter or overload clearly indicates its purpose; potential risk is limited to callers explicitly choosing a non-PAX format, which is opt-in and expected.

[iremyux]

@kasperk81 Thank you for the API Proposal, I went ahead and edited the description.