UwDiff 操作マニュアル（1.0.0）

このページは GitHub の 操作マニュアル（docs/manual.ja.md） と同じ内容です。版が上がったときは GitHub の方が先に新しくなります。
［UwDiff のトップへ］

UwDiff は、2 つのファイル（または 2 つのフォルダ）を比べて、どこが違うかを出す道具です。
形式（テキスト・CSV・TSV・圧縮ファイル・Word・Excel・PDF）、文字コード（UTF-8・Shift-JIS〔CP932〕・EUC-JP・UTF-16）、
大きさ（1 本 10GB 級）、本数（数千〜数万本のフォルダ）を問いません。画面（UwDiff）と CLI（uvd）が同じ比べ方をします。

1. 入れ方

.NET を別に入れる必要はありません。CLI をどこからでも使うには、uvd のある場所を PATH に足すか、リンクを置きます
（mac の例: ln -s /Applications/UwDiff.app/Contents/MacOS/uvd /usr/local/bin/uvd）。

2. 画面（UwDiff）

1. 「旧」「新」にファイルかフォルダを入れる（「ファイル…」「フォルダ…」で選ぶか、窓へ落とす。2 つ一緒に落とすと旧・新に入る）。
2. 比べ方を選ぶ。
3. キー列を入れると表（CSV・TSV・Excel）として照合する（例 点名、複数なら 点名,種別）。空ならテキストとして比べる。
4. 「空白の量を無視」「空白をすべて無視」「大文字・小文字を無視」はテキストの比較で効く。
5. 「順番を問わない」は行の順番を見ずに、どの行が増えた・減ったかだけを比べる。
6. 旧・新がどちらもフォルダのときは、旧の行の右の「含める」、新の行の右の「除く」に指定を入れられる（例 **/*.csv,**/*.log・.git,*.tmp。CLI の -include・-exclude と同じで、書き方は UwView の uvf と同じ。3-5 を参照）。ファイルのときは入力できない。
7. 「比べる」。結果はタブで開く（いくつでも並べられる。× で閉じる）。

メニュー・言語・コマンドライン

• メニューは mac ではメニューバー（UwDiff・ファイル・ヘルプ）、Windows・Linux では窓の上（設定と「UwDiff について」はファイル・ヘルプの中）。
• UwDiff: UwDiff について（版・ビルド番号）／設定…（⌘,）
• ファイル: 旧を開く…（⌘O）／新を開く…／比べる（⌘Enter）／コマンドライン…（⇧⌘K）／結果を開く…（uvd -result・-open が書いたフォルダ）／閉じる（⌘W）／すべて閉じる
• ヘルプ: 使い方／最新情報／お問い合わせ／GitHub／コマンドライン設定…
• 言語: 「設定…」で日本語・英語を切り替える（開いているタブもその場で替わる。選んだ言語は覚えておく。初めは OS の言語）。CLI の出力は日本語のまま。
• コマンドライン…: uvd の引数を打って実行する。比べた結果は新しいタブで開く（uvd … -open と同じ）。
• コマンドライン設定…: ターミナルで uvd と打つだけで使えるようにする（mac・Linux は /usr/local/bin/uvd のリンク、Windows はユーザーの PATH）。
• ボタンや欄にマウスを置くと、説明（ツールチップ）が出る。

テキストの結果

• 左に旧、右に新。消えた行は赤、増えた行は緑。変わった行は左右に並び、変わった文字を濃く塗る。
• 「変更の所だけ」を入れると、同じ行が続く所を前後 3 行だけ残して畳む（外すと全部の行）。
• 「◀ 前の変更」「次の変更 ▶」（F7・Shift+F7）で変更の所へ飛ぶ。
• 10GB のファイルでも、画面に出ている行だけを読むので軽い。

表の結果

• 差分を 1 行ずつ（区分・キー・列・旧値・新値）。追加は緑、削除は赤、変更は黄。
• 「区分」で絞る。「キー・値で探す」に文字を入れて Enter で探す。
• 採る変更を選んで反映する: 採らない行のチェックを外し（「すべて採る」「すべて外す」もある）、「採った変更を反映…」で保存先を選ぶ。
  旧のファイルに、採った変更だけを当てた新しいファイルを書く（元のファイルは変えない。旧の文字コード・区切り・改行・引用符・行の順番を保つ）。
  Excel のシートの照合と「順番を問わない」比較は、差分の一覧まで（反映はしない）。

フォルダの結果

• 旧だけ（赤）・新だけ（緑）・違う（黄）・同じ の一覧。「区分」で絞る（既定は違いだけ）。
• 「違う」の行をダブルクリックすると、その 1 組を新しいタブで比べる（キー列が入っていて CSV なら表として）。

3. CLI（uvd）

uvd 旧 新 [-o 差分]                         テキストの比較（unified diff）
uvd 旧 新 -key 列名 [-o 差分.csv]           表をキー列で照合する
uvd 旧 新 -unordered [-o 差分.csv]          行の順番を問わずに比べる
uvd 旧フォルダ 新フォルダ [-o 一覧.csv]      フォルダどうしを比べる
uvd apply 旧 新 差分.csv -o 結果             表の差分（採る行だけ残したもの）を旧に反映する
uvd … -open                                  結果を画面で開く（画面はもう一度比べない）
uvd -open                                    画面を開く
uvd -h                                       オプションの一覧

終了コードは diff と同じ: 0 = 同じ、1 = 違いあり、2 = エラー（uvd apply は 0 = すべて反映、1 = 反映しなかったものがある）。

3-1. テキストの比較

uvd 旧.log 新.log -o 差分.diff
uvd 旧.log.gz 新.log.zst -o -            （圧縮のまま。-o - で標準出力へ）
uvd 仕様_v1.docx 仕様_v2.docx -o 差分.diff

• 出力は diff -u と同じ形（patch で旧に当てると新になる）。前後の行数は -U 行数（既定 3）。
• -b（空白の量の違いを無視）・-w（空白をすべて無視）・-i（英字の大文字・小文字を区別しない）。
• 改行コード（\r\n と \n）の違いは既定で無視する。違いとみなすなら -strict-eol。ファイルの最後に改行が無いことは違いとして出す。
• 巨大なファイルでも、違いの所の前後だけを持って 1 回読みで比べる。1 か所で数百万行が入れ替わるような所は、その範囲を「置き換え」として出すことがある（正しい差分だが、最小とは限らない）。

3-2. 表の比較（キー照合）

uvd 旧.csv 新.csv -key 点名 -o 差分.csv
uvd 旧.csv 新.tsv -key 点名,種別 -o 差分.csv
uvd 台帳_9月.xlsx 台帳_10月.xlsx -key 点名 -o 差分.csv

• 出力は 区分,キー列…,列,旧値,新値（UTF-8）。区分は 追加・削除・変更（変わったセルごとに 1 行）。Excel のときは区分の次に「シート」の列。
• 行の順番が違ってもキーで対応付ける。列は見出しの名前で対応付ける（並びが違ってもよい）。旧だけ・新だけの列は、相手を空として比べる。
• キーは見出しの名前か #1 のような列番号。複数列の組み合わせもよい。キーが重複している値の数を出す（-nodup で数えない）。
• 値は文字列のまま比べる（先頭の 0・長い数字・日付らしい値を変えない）。Excel は表示されている値で比べる（元の値なら -raw）。
• 区切りは .tsv・.tab はタブ、.csv はカンマ、ほかは見出しの行から決める（-d tab などで固定）。引用符を使わない TSV は -quote off。
• メモリ: 相手がまだ来ていない行（待ち行）が -mem（既定は実メモリの 4 割）を超えたら一時ファイル（-tmp、既定は OS の一時フォルダ）へ逃がして続ける。止まらないが遅くなる。

3-3. 採った変更の反映（apply）

1. 照合する: uvd 旧.csv 新.csv -key 点名 -o 差分.csv
2. 差分.csv から採らない行を消す（Excel で開いて行を消して保存してもよい。CP932・タブ区切り・UTF-16 で保存し直したものも読む）。

3. 反映する: uvd apply 旧.csv 新.csv 差分.csv -o 結果.csv

4. 削除: そのキーの行を書かない。変更: そのセルだけを新値にする。追加: 新からその行を取り、旧の列の並びに直して末尾に足す。

5. 旧の文字コード・BOM・区切り・改行・引用符・行の順番を保つ。変えない行はバイト単位でそのまま。
6. 旧の今の値が差分の旧値と違うセル、新値が旧の文字コードで書けない値、見つからないキー、旧に無い列への変更は、当てずに知らせる（終了コード 1）。

3-4. 順番を問わない比較

uvd 旧.log 新.log -unordered -o 差分.csv — 行全体を 1 つの値とみなし、同じ行が何回あるかまで比べる（旧に 3 回・新に 2 回なら 1 回の削除）。空の行は数えない。

3-5. フォルダの比較

uvd 納品_前回/ 納品_今回/ -o 一覧.csv
uvd 旧/ 新/ -include "**/*.{csv,log}" -exclude ".git,*.tmp" -detail 差分たち/ -key 点名
uvd 旧/ 新/ --ignore-file 除外.txt

• 含める（-include）は UwView の uvf のファイルの指定と同じ書き方:
• 区切りはカンマ（名前に空白を含むならカンマで）。カンマが無ければ空白・タブ。; もカンマと同じに扱う。
• *・? はフォルダの区切りをまたがない。** はフォルダを何段でも（0 段も）。{a,b} は「a か b」（例 *.{csv,log}）。[ ] は使えない。
• 旧・新それぞれのフォルダから見たパスに当てる: *.csv は直下だけ、**/*.csv は下の階層も、sub/** は sub の下すべて。空ならすべて。
• 除く（-exclude）は uvf の除外（--ignore-file）と同じ .gitignore の書き方（区切りは含めると同じで、1 つずつが 1 行）:
• / が無ければどの深さの名前にも当たる（.git・*.tmp）。末尾の / はフォルダだけ（build/）。先頭の / は直下から（/sub/deep）。
• ! で取り消し（*.csv,!a.csv は a.csv だけ残す）。フォルダに当たれば、その下をすべて除く。
• --ignore-file ファイル で、.gitignore と同じ書き方のファイルから規則を足せる（何回でも。後に書いたものほど強く、-exclude より弱い）。

• 大文字・小文字は区別する（uvf・git と同じ）。uvf と違い、.gitignore・.ignore や隠しファイルを既定では外さない（比べるときは全部を見る）。

• ファイル名（下の階層も含めた相対パス）で対応付ける。名前の大文字・小文字は Windows・macOS では区別しない。

• 大きさが違えば「違う」、同じなら中身をバイト単位で比べる（ファイルごとに並列）。
• 一覧は 区分,パス,旧の大きさ,新の大きさ,旧の更新日時,新の更新日時。-detail で中身が違うファイルの差分を 1 本ずつ書く（テキストは .diff、-key があり表なら .csv）。

4. 文字コード

• 自動で見分ける: BOM → BOM の無い UTF-16 → UTF-8 → CP932 と EUC-JP。固定するなら -enc（両方）・-enc-old・-enc-new（utf8・cp932・eucjp・utf16le・utf16be）。
• 旧と新が同じ文字コードなら、変換せずにそのまま比べる（速い）。違えば両方を UTF-8 にそろえて比べる（差分の出力も UTF-8）。
  UTF-16 は同じどうしでも UTF-8 に直す。
• NEC 特殊文字・IBM 拡張文字・半角カナも化けない。CP932 で同じ文字に符号が 2 つあるもの（NEC 選定 IBM 拡張と IBM 拡張の「髙」など）は、反映のときは同じ文字として扱う。

5. 形式

Word・Excel・PDF は「取り出した文字」の比較です（書式・図・数式は比べない）。古い .doc・.xls、パスワード付き、文字の無い PDF は読めません。

6. 速さの目安（実測・Mac mini M4・外付け SSD）

条件: Mac mini（Apple M4・10コア・メモリ 32GB）・外付け SSD／uvd 1.0.0／キャッシュを消していない値（10GB × 2 本はメモリに収まらないので cold に近い）。詳しい表と負けの条件は UwDiff の実測（docs/benchmarks.md） にあります。
実測の一覧のページ: UwDiff の実測

7. 困ったとき

• 「1 行が 4MB を超えています」: 引用符の閉じ忘れで、ファイルの残りが 1 つの値になっていることが多い。-quote off を試す。
• 遅い・メモリが足りない: 行の順番がばらばらな巨大な表は、待ち行が大きくなる。-mem を小さくすると一時ファイルへ逃がして続ける。一時ファイルは -tmp で速い場所に。
• 文字化けする: -enc-old・-enc-new で文字コードを固定する。
• 問い合わせ: https://github.com/amru195704/UwDiff/issues

開発者より: アプリ・Kindle本・公開プロジェクトの一覧は GitHub: amru195704 にまとめています。