Breaking change docs: TarWriter now emits HardLink entries for hard-linked files (.NET 11)

[Copilot]

Documents the .NET 11 Preview 3 behavioral change where TarWriter writes HardLink entries for files sharing the same inode instead of duplicating content—aligning with GNU tar behavior.

Changes

• New article docs/core/compatibility/core-libraries/11/tarwriter-hardlink-entries.md — covers previous/new behavior, reason for change, and migration path
• TOC (toc.yml) — new entry under .NET 11 Core .NET libraries
• Index (11.md) — new row in Core .NET libraries table

Key migration guidance

If content duplication is required, use the new TarWriterOptions.HardLinkMode:

var options = new TarWriterOptions(TarEntryFormat.Pax)
{
    HardLinkMode = TarHardLinkMode.CopyContents
};

using var writer = new TarWriter(stream, options, leaveOpen: false);

Also notes that extracting HardLink entries on file systems without hard link support throws IOException, and that .NET 11's new TarExtractOptions can be used to control extraction behavior.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• https://api.github.com/graphql
  • Triggering command: /usr/bin/gh gh auth status (http block)
  • Triggering command: `/usr/bin/gh gh pr create --repo dotnet/docs --base main --head copilot/breaking-change-use-hardlink-entries --title Breaking change: TarWriter uses HardLink entries for hard-linked files --body Adds a breaking change article documenting that TarWriter in .NET 11 Preview 3 now writes HardLink entries for files sharing the same inode, instead of duplicating file content.

Changes:

• New article: docs/core/compatibility/core-libraries/11/tarwriter --noprofile (http block)

• https://api.github.com/installation/repositories
  • Triggering command: /usr/bin/curl curl -sv -H Authorization: token ****** REDACTED docs/core/compatibility/core-libOUTPUT docs/core/compatibility/toc.yml bash 11/tarwriter-harcat (http block)
• https://api.github.com/repos/dotnet/docs
  • Triggering command: /usr/bin/curl curl -s -o /dev/null -w %{http_code} -H Authorization: token ****** -H Accept: application/vnd.github.v3+json REDACTED (http block)
  • Triggering command: /usr/bin/curl curl -s -H Authorization: token ****** REDACTED origin 75b540449e92b4886f43607fa02/.devcontainer/devcontainer.json 75b540449e92b4886f43607fa02/.prettierrc.json 75b540449e92b488bash 75b540449e92b488--norc 75b540449e92b488--noprofile 75b540449e92b4886f43607fa02/.eslintrc.json 75b5�� ode_modules/sharp/node_modules/detect-libc/package.json ode_modules/sharp/package.json ode_modules/semver/package.json ode_modules/nodebash ode_modules/node--norc ode_modules/node--noprofile ode_modules/color-name/package.json (http block)
• https://api.github.com/repos/dotnet/docs/contents/docs/core/compatibility/11.md
  • Triggering command: /usr/bin/curl curl -s -H Authorization: token ****** REDACTED --noprofile (http block)
• https://api.github.com/repos/dotnet/docs/git/refs/heads/copilot%2Fbreaking-change-use-hardlink-entries
  • Triggering command: /usr/bin/curl curl -s -X GET REDACTED -H Authorization: token ****** -H Accept: application/vnd.github.v3+json (http block)
• https://api.github.com/repos/dotnet/docs/pulls
  • Triggering command: /usr/bin/curl curl -s -X POST -H Authorization: token ****** -H Accept: application/vnd.github.v3+json REDACTED -d { "title": "Breaking change: TarWriter uses HardLink entries for hard-linked files", "body": "Adds a breaking change article documenting that TarWriter in .NET 11 Preview 3 now writes HardLink entries for files sharing the same inode, instead of d bash --no�� /php.ini (http block)
  • Triggering command: /usr/bin/curl curl -s -X POST -H Authorization: token ****** -H Accept: application/vnd.github.v3+json REDACTED -d {"title": "Breaking change: TarWriter uses HardLink entries for hard-linked files", "body": "Adds a breaking change article for issue #52683.", "head": "copilot/breaking-change-use-hardlink-entries", "base": "main"} gsign/gh-gpgsign-linux-x86_64 --no�� race (http block)
• https://api.github.com/user
  • Triggering command: /usr/bin/gh gh api user --jq .login (http block)
  • Triggering command: /usr/bin/curl curl -s -H Authorization: token ****** REDACTED es/11/ (http block)
  • Triggering command: /usr/bin/curl curl -sv -H Authorization: token ****** REDACTED (http block)
• https://api.github.com/vscs_internal/commit/sign
  • Triggering command: /home/REDACTED/work/_temp/copilot-developer-action-main/dist/gh-gpgsign/gh-gpgsign-linux-x86_64 /home/REDACTED/work/_temp/copilot-developer-action-main/dist/gh-gpgsign/gh-gpgsign-linux-x86_64 --status-fd=2 -bsau GitHub <noreply@github.com> (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

---

Internal previews

📄 File	🔗 Preview link
docs/core/compatibility/11.md	docs/core/compatibility/11
docs/core/compatibility/core-libraries/11/tarwriter-hardlink-entries.md	docs/core/compatibility/core-libraries/11/tarwriter-hardlink-entries
docs/core/compatibility/toc.yml	docs/core/compatibility/toc

[Copilot]

Pull request overview

Adds a new .NET 11 breaking-change article documenting updated System.Formats.Tar.TarWriter behavior for hard-linked files (subsequent entries become HardLink entries instead of duplicating contents), and wires the article into the compatibility navigation and index.

Changes:

• Adds a new breaking change article for TarWriter hard-link handling in .NET 11 Preview 3.
• Updates docs/core/compatibility/toc.yml to include the new article under .NET 11 Core .NET libraries.
• Updates docs/core/compatibility/11.md to list the new breaking change in the Core .NET libraries table.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
docs/core/compatibility/toc.yml	Adds the new breaking change article to the .NET 11 Core .NET libraries TOC.
docs/core/compatibility/core-libraries/11/tarwriter-hardlink-entries.md	New breaking change article describing the TarWriter hard-link entry behavior and mitigation option.
docs/core/compatibility/11.md	Adds the new breaking change entry to the .NET 11 index table.

[Copilot]

The article references new/related APIs (TarWriterOptions, HardLinkMode, and TarHardLinkMode.CopyContents) but doesn't use xref links for them. Adding xrefs helps readers navigate to the API docs and helps catch typos in type/member names during doc validation.

[Copilot]

TarExtractOptions is mentioned as the way to control hard-link extraction behavior, but it's not linked (xref) and isn't referenced elsewhere in the repo. Please add an xref (or link to the specific extraction API/overload that takes these options) so the docs validate the name and readers can find the correct API surface.

Suggested change

	Extracting a tar archive that contains `HardLink` entries to a file system without hard link support throws an <xref:System.IO.IOException>. Use the new `TarExtractOptions` class to specify whether to extract hard links as hard links or copy them as separate files. This enables extraction to file systems without hard link support.
	Extracting a tar archive that contains `HardLink` entries to a file system without hard link support throws an <xref:System.IO.IOException>. Use the new <xref:System.Formats.Tar.TarExtractOptions> class to specify whether to extract hard links as hard links or copy them as separate files. This enables extraction to file systems without hard link support.

[BillWagner]

This LGTM. I have one question for you to consider.

[BillWagner]

This article reads as Unix specific. (inode is a Unix term).

Does this apply on Windows? If not, should we state that?