[インデックス 12943] ファイルの概要

このドキュメントは、Go言語の標準ライブラリpathおよびpath/filepathパッケージにおけるClean関数のドキュメント修正に関するコミット（インデックス12943）について、その詳細な技術解説を提供します。

コミット

• コミットハッシュ: 5fc2af1f777f0544c2813e67ba92a26b0c8be4f2
• 作者: Rob Pike r@golang.org
• コミット日時: 2012年4月24日 火曜日 13:17:05 +1000

GitHub上でのコミットページへのリンク

https://github.com/golang/go/commit/5fc2af1f777f0544c2813e67ba92a26b0c8be4f2

元コミット内容

path: document that Clean deletes trailing slashes.

Fixes #3492.

R=golang-dev, rsc
CC=golang-dev
https://golang.org/cl/6112044

変更の背景

このコミットは、Go言語のpathおよびpath/filepathパッケージに存在するClean関数の振る舞いに関するドキュメントの明確化を目的としています。具体的には、Clean関数がパスの末尾のスラッシュ（trailing slashes）を削除するという重要な挙動が、既存のドキュメントに明示されていなかったため、ユーザーがその挙動を誤解する可能性がありました。

コミットメッセージにあるFixes #3492は、GitHubのIssue #3492（またはGoのバグトラッカーの対応するIssue）で報告された問題に対応していることを示しています。このIssueでは、path.Cleanが末尾のスラッシュを削除するにもかかわらず、そのことがドキュメントに記載されていないために混乱が生じていることが指摘されたと考えられます。

パスの正規化は、ファイルシステム操作やURL処理において非常に重要です。一貫性のないパス表現は、セキュリティ上の脆弱性（例: パストラバーサル攻撃）や、キャッシュの不整合、リソースの誤った参照などを引き起こす可能性があります。そのため、Clean関数の挙動は完全に透過的であるべきであり、そのドキュメントは可能な限り詳細かつ正確である必要があります。このコミットは、その正確性を向上させるためのものです。

前提知識の解説

Go言語のpathおよびpath/filepathパッケージ

Go言語には、パス操作のための2つの主要なパッケージがあります。

• pathパッケージ: スラッシュ（/）を区切り文字とする、Unixスタイルのパスを操作するためのユーティリティを提供します。これは主にURLパスや、オペレーティングシステムに依存しない汎用的なパス処理に使用されます。
• path/filepathパッケージ: オペレーティングシステム固有のパス区切り文字（Unixでは/、Windowsでは\）を考慮したパス操作のためのユーティリティを提供します。ファイルシステムパスを扱う際には、通常こちらのパッケージを使用します。

Clean関数

pathおよびpath/filepathパッケージの両方にClean関数が存在し、その基本的な目的はパスを正規化することです。正規化とは、パスをその意味を変えずに最も短く、かつ標準的な形式に変換するプロセスを指します。

Clean関数は以下のルールに従ってパスを正規化します（Goのドキュメントより）：

1. 連続するスラッシュを1つにまとめる（例: a//b -> a/b）。
2. .（カレントディレクトリ）要素を削除する（例: a/./b -> a/b）。
3. ..（親ディレクトリ）要素を解決する（例: a/b/../c -> a/c）。
4. ルートパスの先頭にある..要素を削除する（例: /../a -> /a）。

このコミット以前のドキュメントでは、上記のルールは明記されていましたが、末尾のスラッシュの扱いについては明示されていませんでした。Clean関数は、通常、末尾のスラッシュを削除します（例: a/ -> a）。ただし、ルートディレクトリを表すパス（例: Unixの/、WindowsのC:\）の場合のみ、末尾のスラッシュが保持されます。この挙動は、パスの同一性を判断する上で非常に重要であり、ドキュメントに明記されるべきでした。

技術的詳細

このコミットは、path.Cleanとpath/filepath.Cleanのドキュメント文字列に、末尾のスラッシュの扱いに関する記述を追加することで、この曖昧さを解消しています。

具体的には、以下の文言が追加されました。

• src/pkg/path/filepath/path.go (filepath.Cleanのドキュメント):

  // The returned path ends in a slash only if it represents a root directory,
  // such as "/" on Unix or `C:\` on Windows.
  

• src/pkg/path/path.go (path.Cleanのドキュメント):

  // The returned path ends in a slash only if it is the root "/".
  

これらの追加により、Clean関数が通常は末尾のスラッシュを削除するが、ルートディレクトリを示すパスの場合にのみ保持するという挙動が明確に示されました。これにより、開発者はClean関数の出力形式について正確な期待を持つことができ、パスの比較や結合などの操作において誤解を避けることができます。

この変更は、関数の内部的なロジックを変更するものではなく、あくまでドキュメントの正確性と完全性を向上させるものです。しかし、ライブラリの利用者がその挙動を正しく理解するためには、このようなドキュメントの改善は非常に重要です。

コアとなるコードの変更箇所

このコミットによる変更は、Goの標準ライブラリのソースコード内のドキュメントコメントに限定されています。

src/pkg/path/filepath/path.go の変更

--- a/src/pkg/path/filepath/path.go
+++ b/src/pkg/path/filepath/path.go
@@ -30,6 +30,9 @@ const (
 //	   that is, replace "/.." by "/" at the beginning of a path,
 //         assuming Separator is '/'.
 //
+// The returned path ends in a slash only if it represents a root directory,
+// such as "/" on Unix or `C:\` on Windows.
+//
 // If the result of this process is an empty string, Clean
 // returns the string ".".
 //

src/pkg/path/path.go の変更

--- a/src/pkg/path/path.go
+++ b/src/pkg/path/path.go
@@ -21,6 +21,8 @@ import (
 //	4. Eliminate .. elements that begin a rooted path:
 //	   that is, replace "/.." by "/" at the beginning of a path.
 //
+// The returned path ends in a slash only if it is the root "/".
+//
 // If the result of this process is an empty string, Clean
 // returns the string ".".
 //

コアとなるコードの解説

追加されたドキュメントコメントは、Clean関数の出力形式に関する重要な仕様を明記しています。

• filepath.Cleanの場合:

  // The returned path ends in a slash only if it represents a root directory,
  // such as "/" on Unix or `C:\` on Windows.
  

  この行は、filepath.Cleanが返すパスが末尾にスラッシュを持つのは、それがルートディレクトリ（Unixでは/、WindowsではC:\など）を表す場合のみであることを明確にしています。例えば、C:\foo\のようなパスはC:\fooに正規化され、末尾のスラッシュは削除されます。しかし、C:\はC:\のままです。

• path.Cleanの場合:

  // The returned path ends in a slash only if it is the root "/".
  

  こちらはpath.Clean（Unixスタイルパス用）のドキュメントで、よりシンプルに、返されるパスが末尾にスラッシュを持つのは、それがルートパスである/の場合のみであることを示しています。例えば、foo/bar/はfoo/barに正規化されますが、/は/のままです。

これらの追加により、Clean関数の「末尾のスラッシュを削除する」という一般的な挙動と、「ルートパスの場合のみ保持する」という例外が明確に区別され、開発者がこの関数をより正確に理解し、利用できるようになりました。

関連リンク

• Go Issue #3492: path: document that Clean deletes trailing slashes. (このコミットが修正したIssue)
  • https://github.com/golang/go/issues/3492
• Go Code Review (CL) 6112044: path: document that Clean deletes trailing slashes. (このコミットに対応するGoのコードレビューシステムのエントリ)
  • https://golang.org/cl/6112044

参考にした情報源リンク

• Go言語 path パッケージ公式ドキュメント:
  • https://pkg.go.dev/path
• Go言語 path/filepath パッケージ公式ドキュメント:
  • https://pkg.go.dev/path/filepath
• Go言語のソースコード (GitHub):
  • https://github.com/golang/go
• Go言語のIssueトラッカー:
  • https://github.com/golang/go/issues
• Go Code Review:
  • https://go.googlesource.com/go/+/refs/heads/master/doc/contribute.html#code_reviews