概要

merge_text_files.py は、指定されたルートディレクトリから特定のパターン（デフォルトは *.txt や *.md ）に一致するテキストファイルを検索し、単一のファイルに結合するコマンドラインツールです。結合後のファイルには、元ファイルの相対パスやファイルタイプなどのメタデータがヘッダとして付与されます。

動作原理

本プログラムはデータ処理ユーティリティとして動作し、以下の手順で処理を実行します。

ファイルの探索とフィルタリング 指定されたルートディレクトリ以下を走査し、条件に一致するファイルを収集します。再帰探索フラグ -r が有効な場合はサブディレクトリも探索されます。探索時には、最大ディレクトリ深度 --max-depth および検索パターン --patterns に基づくフィルタリングが行われます。結合結果の出力先ファイルが探索範囲に含まれた場合は、無限ループを避けるため自動的に除外されます。
ファイルの読み込み 収集されたファイルを相対パスの文字列に基づき昇順にソートします。各ファイルを指定されたエンコーディング（デフォルトは utf-8 ）で読み込みます。デコードエラーが発生した場合は、 utf-8-sig エンコーディングを使用し、解釈できない文字を置換（ replace ）するフォールバック処理を行って読み込みを試みます。
ファイルの結合 各ファイルの内容に、区切りとなる文字列（ ===== FILE START ===== 、 ===== CONTENT ===== 、 ===== FILE END ===== ）とメタデータ（ファイルパス、ファイル種別、空のタグリスト [] ）を付与し、出力ファイルに書き込みます。各ファイルの間には、指定された行数（ --blank-lines ）の改行文字列が挿入されます。

依存関係

本プログラムは Python の標準ライブラリのみで構成されており、外部の非標準ライブラリへの依存はありません。

argparse
fnmatch
pathlib
__future__

入出力仕様

本スクリプトの入出力仕様は、コマンドライン引数を通じて制御されます。

位置引数
- root : 探索対象の起点となるルートディレクトリを指定します。
オプション引数
- -o , --output : 結合結果を出力するファイルパスを指定します。デフォルトは merged_files.txt です。
- -p , --patterns : 検索対象のワイルドカードパターンを指定します。空白区切り、またはセミコロン ; 区切りで複数指定可能です。デフォルトは *.txt と *.md です。
- -r , --recursive : このフラグを指定した場合、ディレクトリを再帰的に探索します。
- -d , --max-depth : ルートからの最大探索深度を指定します。 -1 を指定した場合は深さ無制限となります。デフォルトは -1 です。
- --encoding : 入出力時のテキストエンコーディングを指定します。デフォルトは utf-8 です。
- --blank-lines : ファイルの終端と、次のファイル開始の間に挿入する空行の数を指定します。5以上の値が必要です。デフォルトは 5 です。
出力フォーマット 出力される結合ファイルでは、元の各ファイルの内容が以下の形式に整形されて書き込まれます。
- ===== FILE START =====
- path: <ルートディレクトリからの相対パス>
- type: <拡張子から推測されたファイル種別>
- tags: []
- ===== CONTENT =====
- <ファイル本文テキスト>
- ===== FILE END =====

実行例

ディレクトリ target_dir 以下の階層を最大深度 5 まで再帰的に探索し、 *.txt と *.md ファイルを収集して docs_merged.txt に結合する実行例です。

python merge_text_files.py target_dir -o docs_merged.txt -r -d 5 -p "*.txt" "*.md"

複数の検索パターンをセミコロン ; で区切り、単一の文字列として引数に渡すことも可能です。

python merge_text_files.py target_dir -o docs_merged.txt -r -d 5 -p "*.txt;*.md"