MENU

GitHub公式ドキュメント更新で確認すべきTarWriterのHardLink変更点（.NET 11）

C#

GitHubの公式ドキュメント更新として確認すべき結論は、.NET 11のTarWriterで、ハードリンクされたファイルをtar化したときの出力形式が変わるという点です。これまで同じ実体を指す複数ファイルは、それぞれ独立したファイル内容としてtarアーカイブに格納されていました。今後は後続ファイルがHardLinkエントリとして書き込まれるため、アーカイブサイズは小さくなりやすい一方、展開先のファイルシステムや既存の検証ロジックによっては影響が出ます。Microsoft Learnの該当ページは2026年4月29日に更新され、.NET 11 Preview 3で導入された変更として説明されています。(Microsoft Learn)

目次

GitHubの公式ドキュメント更新で何が変わったか

今回の更新は、GitHub上のdotnet/docsリポジトリに追加された.NET 11向けの破壊的変更ドキュメントに関するものです。コミットでは「Breaking change docs: TarWriter now emits HardLink entries for hard-linked files (.NET 11)」として、docs/core/compatibility/core-libraries/11/tarwriter-hardlink-entries.mdなどが追加されています。(GitHub)

変更の中心は、System.Formats.Tar.TarWriterの挙動です。TarWriterは、複数のファイルが同じinodeにハードリンクされている場合、後続のファイルについてファイル内容を重複して書き込むのではなく、HardLinkエントリを書き込むようになります。Microsoft Learnでは、この変更を「behavioral change」、つまり動作変更として分類しています。(Microsoft Learn)

実務上は、次のように理解すると分かりやすいです。

観点以前の挙動.NET 11以降の挙動
ハードリンクされた複数ファイルそれぞれ独立したファイルとして内容を格納先頭ファイルは通常のファイル、後続はHardLinkエントリ
tarファイルのサイズ同じ内容が重複し、サイズが増えやすい重複が減り、サイズを抑えやすい
ファイル関係の保持ハードリンク関係は失われやすいハードリンク関係を保持しやすい
影響が出やすい処理少ないが非効率展開先・検証処理・独自tar処理で注意が必要

この変更は「tarファイルを作る処理」だけの話に見えますが、実際にはCI/CD、バックアップ、コンテナ関連処理、ビルド成果物の配布、クラウド環境への展開などに波及する可能性があります。

TarWriterとハードリンクの関係を整理する

TarWriterは、.NETのSystem.Formats.Tar名前空間で提供されるtarアーカイブ作成用APIです。C#アプリケーション内でファイルやディレクトリをtar形式にまとめる処理に使われます。

ハードリンクは、複数のファイル名が同じファイル実体を参照する仕組みです。たとえばLinux環境でfile1.txtとfile2.txtが同じinodeを指している場合、見た目は2つのファイルでも、中身は同じ実体を共有しています。

従来のTarWriterでは、このようなファイルをtarに入れると、file1.txtとfile2.txtの両方に同じ内容がコピーされていました。Microsoft Learnの説明でも、以前は同じinodeにハードリンクされたファイルが個別の独立ファイルとして扱われ、それぞれのファイル内容がアーカイブに複製されていたとされています。(Microsoft Learn)

.NET 11ではこの挙動が変わります。たとえばfile1.txtとfile2.txtが同じ実体を指す場合、file1.txtは通常のファイルとして格納され、file2.txtはfile1.txtを指すHardLinkエントリとして格納されます。(Microsoft Learn)

これはtar形式としては自然な挙動です。Microsoft Learnでも、今回の変更によりアーカイブサイズを削減し、ファイル間のハードリンク関係を保持できるほか、GNU tarなど広く使われているtar実装と整合すると説明されています。(Microsoft Learn)

影響を受ける可能性が高いシステム

すべての.NETアプリケーションが影響を受けるわけではありません。確認すべきなのは、.NETでtarを作成し、そのtarを別環境で展開・検証・再配布している処理です。

特に次のようなケースでは、影響確認を優先してください。

利用シーン確認すべき理由
CI/CDで成果物をtar化して配布している展開先のOSやファイルシステムがハードリンクを扱えるか確認が必要
Linux環境のファイル群を.NETアプリでアーカイブしているinode共有ファイルが含まれる可能性がある
バックアップや復元ツールを自作している復元後に「独立ファイル」になる前提だと結果が変わる
tarの中身を独自ツールで検査しているHardLinkエントリを想定していないと検査に失敗する可能性がある
クラウドストレージや一時領域へ展開している展開先がハードリンクをサポートしない場合がある
コンテナイメージ・ランタイム周辺の処理にtarを使っているtar内のリンク表現を正しく解釈できるか確認が必要

逆に、次のようなアプリケーションでは影響は限定的です。

条件影響
System.Formats.Tar.TarWriterを使っていない直接的な影響は基本的にない
tar化対象にハードリンクされたファイルがない出力結果は大きく変わりにくい
作成したtarを標準的なtarツールで展開するだけ多くの場合は問題になりにくいが、展開先の仕様確認は必要
すでにハードリンクを前提に運用しているむしろ期待に近い挙動になる可能性がある

破壊的変更として注意すべきポイント

今回の変更は、コンパイルエラーを発生させるタイプの変更ではありません。コード自体はそのまま動く可能性があります。しかし、生成されるtarアーカイブの中身が変わるため、運用上の差分が出ます。

tarファイルのサイズが変わる

ハードリンクされたファイルが多い場合、tarファイルのサイズが従来より小さくなる可能性があります。これは多くのケースでメリットですが、サイズをもとに処理を分岐している場合は注意が必要です。

たとえば、バックアップ結果のサイズを監視しているシステムで、急にtarサイズが小さくなると「バックアップ漏れ」と誤検知する可能性があります。サイズ減少そのものは正常でも、監視ルール側が旧挙動を前提にしているとアラートが出ます。

展開後のファイル関係が変わる

以前はtarから展開したとき、file1.txtとfile2.txtが独立したファイルとして復元される前提で運用していたケースがあるかもしれません。.NET 11以降では、tar内にHardLinkエントリが含まれるため、展開後にハードリンク関係が復元される可能性があります。

これは「正しい復元」に近い挙動ですが、アプリケーションによっては問題になります。たとえば、展開後に片方のファイルだけを書き換えるテストをしている場合、ハードリンク関係が維持されていると、もう片方にも変更が反映される可能性があります。

展開先がハードリンクをサポートしない場合がある

Microsoft Learnでは、HardLinkエントリを含むtarをハードリンク非対応のファイルシステムに展開すると、IOExceptionがスローされると説明されています。また、新しいTarExtractOptionsを使うことで、ハードリンクとして展開するか、別ファイルとしてコピーするかを指定できるとされています。(Microsoft Learn)

これはクラウド管理者やソリューションアーキテクトにとって重要です。開発環境ではLinux上で問題なく展開できても、本番の一時領域、ネットワークドライブ、制限されたコンテナ環境、特殊なマウント先では失敗する可能性があります。

独自のtarパーサーや検証ロジックが失敗する可能性がある

社内ツールでtarの中身を検証している場合、HardLinkエントリを正しく扱えるか確認してください。

よくある失敗例は次の通りです。

失敗しやすい処理起きる問題
tar内の全エントリを通常ファイルとして扱うHardLinkエントリで想定外の分岐になる
各ファイルに必ず本文データがある前提でハッシュ計算する後続エントリに内容がないため検証結果が変わる
ファイル数とデータブロック数を単純比較するエントリ数は同じでも実データ量が減る
展開後に独立ファイルとして編集するハードリンク関係により変更が波及する可能性がある
セキュリティスキャンでリンク先を確認しない実体ファイルとリンクエントリの関係を見落とす

影響を確認するための実務チェックリスト

今回のGitHub公式ドキュメント更新を受けて、開発チームや運用チームは次の順で確認すると効率的です。

確認項目具体的な確認内容優先度
TarWriterの利用有無System.Formats.Tar、TarWriter、WriteEntry、WriteEntryAsyncをコード検索する高
.NET 11への移行予定対象プロジェクトが.NET 11 Previewまたは正式版へ移行する予定があるか確認する高
tar化対象のファイル構造ハードリンクされたファイルが含まれるか、Linux環境でls -liなどを使って確認する高
展開先の環境Linux、Windows、コンテナ、ネットワークストレージなど、展開先がハードリンクを扱えるか確認する高
既存テストtarサイズ、エントリ種別、ハッシュ値、復元結果を検証しているテストを確認する中
監視・アラートバックアップサイズや成果物サイズの変化を異常扱いしていないか確認する中
セキュリティレビューリンクエントリの扱いが既存ポリシーに合っているか確認する中

最初にやるべきことは、コードベース全体でTarWriterを検索することです。影響範囲が限定できれば、移行作業は大きくなりません。

既存挙動を維持したい場合の対応

アプリケーションが「ハードリンクされたファイルでも内容を複製してtarに入れる」挙動に依存している場合は、TarWriterOptionsのHardLinkModeをTarHardLinkMode.CopyContentsに設定します。Microsoft Learnでも、以前の挙動を復元する方法としてこの設定が紹介されています。(Microsoft Learn)

using System.Formats.Tar;
using System.IO;

string filePath1 = "file1.txt";
string filePath2 = "file2.txt";

File.WriteAllText(filePath1, "Hello, world!");
File.CreateHardLink(filePath2, filePath1);

var options = new TarWriterOptions
{
    HardLinkMode = TarHardLinkMode.CopyContents
};

using (var stream = File.Create("archive.tar"))
using (var writer = new TarWriter(stream, options, leaveOpen: false))
{
    writer.WriteEntry(filePath1, "file1.txt");
    writer.WriteEntry(filePath2, "file2.txt");
}

TarHardLinkModeにはPreserveLinkとCopyContentsの値があり、APIリファレンスではPreserveLinkが値0、CopyContentsが値1として示されています。(Microsoft Learn)

判断基準はシンプルです。

目的推奨設定
tarサイズを抑えたい既定挙動のまま、ハードリンクを保持する
ハードリンク関係を正しく復元したい既定挙動のまま、ハードリンクを保持する
展開後に完全に独立したファイルとして扱いたいTarHardLinkMode.CopyContentsを指定する
展開先がハードリンク非対応の可能性が高い作成時または展開時にコピー動作を検討する
旧バージョンと同じ成果物を維持したいTarHardLinkMode.CopyContentsを指定する

ポイントは、単に「新挙動が良い」「旧挙動が良い」と決めないことです。配布先、展開先、検証方法まで含めて判断する必要があります。

展開処理ではTarExtractOptionsも確認する

今回の変更では、作成時のTarWriterOptionsだけでなく、展開時のTarExtractOptionsも重要です。TarExtractOptionsは.NET 11向けのAPIリファレンスに掲載されており、プロパティとしてHardLinkModeとOverwriteFilesが示されています。(Microsoft Learn)

展開側で確認すべき観点は次の通りです。

確認観点実務でのチェック内容
展開先がハードリンク対応かローカルディスク、コンテナ内FS、ネットワークドライブ、クラウド同期領域で動作確認する
失敗時の例外処理IOException発生時に再試行、コピー展開、エラーログ出力を行うか決める
展開後の編集処理ハードリンク関係が残った状態で片方だけ編集して問題ないか確認する
監査ログどのエントリが通常ファイルで、どれがHardLinkか記録できるようにする
セキュリティリンク先パスの扱いが安全か、意図しない参照にならないか確認する

特に、開発環境と本番環境でファイルシステムが違う場合は注意が必要です。開発者のLinuxマシンでは問題なく動いても、CIランナー、Windows環境、コンテナボリューム、ネットワーク共有では挙動が異なることがあります。

開発チームが移行前に行うべきテスト

.NET 11への移行準備では、単体テストだけでなく、tarファイルの実体を確認するテストを追加すると安全です。

tar内のエントリ種別を確認する

従来のテストでは「ファイルが含まれているか」だけを確認していたかもしれません。今回の変更では、ファイル名だけでなく、エントリ種別も確認してください。

確認すべき項目は次の通りです。

テスト項目期待する確認結果
通常ファイルのエントリ先頭ファイルが通常ファイルとして格納される
ハードリンクされた後続ファイルHardLinkエントリとして格納される
リンク先後続エントリが正しい先頭ファイルを参照している
展開結果展開先で期待通りのファイル関係になる
旧挙動維持設定CopyContents指定時に内容が複製される

展開先ごとに検証する

tarは「作れたら終わり」ではありません。作成したtarを実際に使う場所で展開できるかが重要です。

最低限、次の環境で確認することをおすすめします。

環境確認理由
開発者のローカル環境基本動作を素早く確認できる
CI/CDランナー実際のビルド・配布処理に近い
本番に近いLinux環境inodeやハードリンクの挙動を確認しやすい
Windows環境運用対象に含まれる場合は必須
コンテナ内ベースイメージやマウント方式で差が出る可能性がある
ネットワークストレージハードリンク非対応や制限付きの可能性がある

監視ルールを見直す

tarサイズが小さくなることは、基本的には改善です。しかし、運用監視では「いつもより小さい成果物」が異常として扱われることがあります。

たとえば、バックアップファイルのサイズが一定以上であることを監視している場合、.NET 11移行後にサイズが急減してアラートが出る可能性があります。移行前後でサイズ差を比較し、正常な差分として説明できるようにしておきましょう。

クラウド管理者・アーキテクトが見るべき運用影響

開発者だけでなく、クラウド管理者やソリューションアーキテクトも今回の変更を確認する価値があります。理由は、tarアーカイブがアプリケーション配布や環境構築の中間成果物として使われることが多いからです。

特に次の設計判断に関わります。

設計領域確認ポイント
成果物配布tarの受け取り側がHardLinkエントリを処理できるか
バックアップ設計復元後にハードリンク関係を維持すべきか、独立ファイルにすべきか
ストレージ設計展開先がハードリンクをサポートするか
CI/CD設計ランナー環境と本番環境で展開結果が一致するか
セキュリティ設計リンクエントリを含むアーカイブの検査ルールがあるか
障害対応展開失敗時にIOExceptionをどう扱うか

アーキテクチャ上の判断では、効率だけを見てはいけません。ハードリンク関係を保持することが正しい業務もあれば、復元後は独立ファイルのほうが安全な業務もあります。

たとえば、ソフトウェア配布パッケージではサイズ削減とtar互換性がメリットになりやすいです。一方、バックアップ復元後に各ファイルを個別に編集する業務では、CopyContentsを使って独立ファイルとして扱うほうが分かりやすい場合があります。

よくある誤解と注意点

GitHub自体のtar出力仕様が変わるという意味ではない

今回の更新は、GitHubサービス全体のアーカイブ仕様変更ではありません。対象は、GitHub上で管理されているMicrosoftDocs系の.NETドキュメントで説明されている、.NET 11のSystem.Formats.Tar.TarWriterの動作変更です。

そのため、GitHubリポジトリのダウンロードzipやGitHub Actionsのすべての成果物が一律に変わる、という意味ではありません。あくまで、自分たちの.NETアプリケーションがTarWriterを使ってtarを作る場合に確認すべき変更です。

コンパイルが通るから安全とは限らない

この変更は動作変更です。APIの呼び出しコードがそのままコンパイルできても、生成物の内容が変わります。テストでは、コードの成功・失敗だけでなく、tarの中身と展開結果まで確認してください。

tarサイズの減少をすぐ異常と判断しない

ハードリンクされたファイルが多い場合、tarサイズが小さくなるのは自然です。ただし、サイズ減少が本当にハードリンク処理によるものかを確認するため、移行前後で同じ入力ファイルを使って比較するのが安全です。

旧挙動に戻すべきかは用途で判断する

TarHardLinkMode.CopyContentsを指定すれば、ハードリンクされたファイル内容を複製する旧挙動に近づけられます。ただし、無条件に旧挙動へ戻すと、せっかくのサイズ削減やリンク関係保持のメリットを失います。

判断の軸は次の3つです。

判断軸確認すること
互換性受け取り側や展開先がHardLinkエントリを扱えるか
正確性ハードリンク関係を保持することが業務上正しいか
運用性障害時に原因を追いやすい構成か

移行準備の進め方

.NET 11への移行を予定しているチームは、次の順で対応すると手戻りを減らせます。

手順作業内容
1コードベースでTarWriter、WriteEntry、WriteEntryAsyncを検索する
2tar化対象にハードリンクされたファイルが含まれるか確認する
3.NET 10以前と.NET 11で同じ入力をtar化し、エントリ種別とサイズを比較する
4展開先環境でHardLinkエントリを含むtarを展開できるか確認する
5独立ファイルとして復元したい場合はTarHardLinkMode.CopyContentsを検討する
6展開時にTarExtractOptionsを使うべき箇所を洗い出す
7監視、ログ、テスト、ドキュメントを更新する

この変更は、早めに確認すれば対応しやすいタイプの破壊的変更です。逆に、.NET 11移行後にバックアップ復元やCI/CDの展開処理で初めて気づくと、原因調査に時間がかかります。

まとめ：TarWriterを使う.NET 11移行ではtarの中身まで確認する

今回のGitHub公式ドキュメント更新で確認すべき点は、.NET 11のTarWriterがハードリンクされたファイルに対してHardLinkエントリを出力するようになることです。これは、アーカイブサイズ削減やハードリンク関係の保持というメリットがある一方、展開先のファイルシステム、独自検証ツール、監視ルール、バックアップ復元処理に影響する可能性があります。

まずは、自社のコードでSystem.Formats.Tar.TarWriterを使っているかを確認してください。使っている場合は、ハードリンクを含む入力データで.NET 11移行前後のtarを比較し、展開結果まで検証することが重要です。旧挙動が必要な場合はTarWriterOptions.HardLinkMode = TarHardLinkMode.CopyContentsを検討し、展開側ではTarExtractOptionsの利用も確認しておきましょう。

C#
GitHub C# Microsoft Learn .NET 11 TarWriter

この記事を書いた人

佐藤健司のアバター 佐藤健司

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows／Office（Teams・Excel）からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。

関連記事

コメント

コメントする

目次