Fileregister: ファイルのタグ付けと参照レイヤーをプレーンテキストで

フォルダとファイル

プレーンテキストによるファイルのタグ付けと参照レイヤー。永続的なIDと、リネームや移動に耐え、別のマシンにも引き継げる自己文書化バインダーを備えています。

［画像: test］

---

何をするものか

ファイルはフォルダ、ディスク、マシンに散らばり、名前さえ変わることがあります。それらに関する知識（どの請求書か、支払済みか、どのプロジェクトに属するかなど）は、あなたの頭の中、ファイル横のスプレッドシート、あるいはアプリのデータベースに存在します。fileregisterは、その知識をプレーンテキストで保持し、名前やパスではなく永続的なIDによってファイルに紐付けます。

registerは、渡されたすべてのファイルに対してレコードを書き込みます。永続的なID、所属するバインダー、追加したフィールドが含まれます。レコードはノートのルートにあるJSONLインデックスに保存され、catで読み取り、grepで検索でき、gitで管理されます。このインデックスが真実の情報源です。

各レコードは、そのバインダーのMarkdownノート内にブロックを持つことができます。ブロックはYAMLフィールド（金額、支払い日、サプライヤー、キャプション）としてデータを保持し、その下の自由テキストにはフィールド以外のすべてが含まれます。フィールドはgrubberとmatterbaseがクエリするものですが、テキストはあなたのためです。これにより、単なるファイルのセットが、プロジェクトのワークブックやフォトアルバムのような自己文書化バインダーに変わります。

各ファイルはmacOSのブックマークによって固定され、独自のストア（~/.local/share/fileregister/bookmarks.json）に保存されます。ブックマークは、リネームや別のディスクへの移動後もファイルを再検索します。壊れた場合、register repairは同じIDで再度バインドし、2台目のMacではregister unmarshalが同様のことを行います。ファイル自体に書き込まれるもの（IDのxattrs、バインダー名、Finderタグ）はインデックスから派生したキャッシュであり、register refreshはそれがずれたりコピーが剥がされたりしたときに再構築します。

OS固有の作業のほとんどは、fileanchorエンジンによって処理されます。これはmacOS向けにリリースされており、Linux版も準備中です。register自体はLinux向けにビルドされ、そこでテストに合格しますが、有用なことを行うにはそのエンジンが必要です。

初めてのセッション

export GRUBBER_NOTES=~/notes         # インデックスとノートの保存場所

register add ~/scans/scan_0043.pdf --binder insurance --aka car-policy
register list insurance
register resolve car-policy           # 現在の名前が何であれ、パスを出力します
open "$(register resolve car-policy)"

ドキュメントをスキャンし、思いついた名前で保存しました。--aka car-policyは、覚えているためのハンドルを与えます。6ヶ月後、ファイルの名前が変更され、別の場所に移動されました。register resolve car-policyは依然としてそのパスを出力し、register of /Volumes/nas/policy-2026.pdfはファイルからIDを読み取り、どのバインダーに含まれているかを報告します。

何ができるか

プロジェクトのドキュメントを収集する。 バインダーはフォルダではなく、レコードのセットです。契約書、2つのスキャン、スプレッドシートは、複数のフォルダにまたがって元の場所に留まり、1つの作業セットを形成します。ファイルをバインダーに追加しても移動せず、同じファイルが複数のバインダーに同時に存在できます。Finderタグもファイルをグループ化できますが、タグは単なる名前です。register listはカウント付きのすべてのバインダーを表示し、register list <binder>はメンバーを表示します。--pathsはパイプ処理のために絶対パスを提供します。

ファイルにデータを添付する。 register promoteは、ファイルごとに1つのYAMLブロックを持つMarkdownノートを書き込み、バインダーに関する情報（金額、支払い日、サプライヤー、キャプションなど）を自由テキストと共に記入します。同じファイルが異なるバインダーで異なるフィールドを持つことができます。register annotateは、スクリプトやGUIからノートを開かずに同様の編集を行います。fileregisterがない場合、このデータは通常、ファイルが移動しても気づかないスプレッドシートに格納されます。

リンクを機能させ続けるようにファイルにリンクする。 はい、Hookmarkのように、ただしデータベースではなくプレーンテキストで。--akaは、ファイル名とは無関係のハンドルをレコードに与えます。register resolve <handle>はそれをパスに戻すため、ハンドルはref:// URL（mi.lanとtickerがインストールされている場合）、Shortcut、またはシェルエイリアスの背後で機能します。ルックアップはレコードを介して行われるため、リンクはリネームや移動に耐えます。ハンドルは後でregister aka <key> --add/--removeで追加または削除できます。

ファイルを逆引きする。 register of <file>は、ファイル上のIDから「これは何で、何の一部か？」に答えます。これにより、リネームしても壊れません。

バインダーを順序付ける。 メンバーはノート内のブロックの順序に従います。sort:キーがそれを上書きし、register order moveがそれらを書き込みます。ORDERING.mdを参照してください。

バインダーをアルバムとして、データとして。 register album <binder>は、メンバーを順序通りにJSONラインで出力します。list --jsonラインに位置、フィールド、ファイル（日付、場所、座標、サイズ）が追加されます。ギャラリー、レポート、ウェブページは、それを読み取るものによって構築されます。fileregisterはレンダラーを提供しません。ALBUM.mdを参照してください。

別のマシンでバインダーを再構築する。 register marshalはファイル、ノート、マニフェストをtar.gzにパックします。register unmarshalは反対側で展開し、ファイルを元のパスにミラーリングし、同じバインダー、ハンドル、機能するリンクを持つレコードを再作成します。collections/外のパスへのミラーリングはオプトインかつ明示的（--scatter）であるため、他者からのコンテナが好きな場所に書き込むことはできません。コンテナはOSニュートラルなので、exFAT、-Eなしのrsync、またはxattrを消費するクラウドフォルダを経由して転送できます。

macOS Spotlightを最新の状態に保つ。 register refreshはインデックスからxattrsを書き直し、Spotlightはそこからインデックスを作成します。register auditは両方向のドリフトを報告し、register repairは移動したファイルのブックマークを再バインドし、register cleanupは決定が必要なものをすべてウォークスルーします。それらのいずれもレコードを自動的に削除しません。WHO-WRITES-WHAT.mdは、コマンドごとに、インデックス、ブックマークストア、ファイル、ノートに何が書き込まれるかを示します。

すべてをクエリする。 インデックスはJSONLで、ノートはMarkdownのYAMLであるため、grubberは両方をクエリでき、matterbaseはそれらに対するテーブルビューとクエリビルダーを提供します。WORKFLOWS.mdを参照してください。

1台のMacで作業する場合、ファイルをトピックごとにグループ化し、データを添付しない場合、Finderタグで十分です。

コマンド

register <subcommand> [args...]

その他の例

# セッションバインダー。以下で--binderを省略できます
export REGISTER_BINDER=project-alpha

register add document.pdf --kind pdf
register add ~/scans/*.pdf --kind pdf        # 一括処理：ブックマーク書き込み1回、追記1回
REGISTER_BINDER= register add document.pdf --aka alpha-brief  # バインダーなし：ハンドル付きのルーズなレコード
register aka alpha-brief --add brief         # 後で2番目のハンドルを追加
register add document.pdf --md               # アノテーションノートも書き込む

register promote                             # バインダー全体のブロック
register promote --id 482910337              # または単一レコード
register annotate project-alpha alpha-brief --set amount=142.50 --set status=paid

register list --inbox                        # アノテーションされていないレコードを持つバインダー
register list project-alpha --paths

register order move project-alpha 482910337 --after 482910901
register album project-alpha --title "Project Alpha, Q1" > alpha.jsonl

register marshal --binder project-alpha --out project-alpha.tar.gz
register unmarshal project-alpha.tar.gz      # 別のマシンで

register refresh --dry-run
register audit --binder project-alpha
register repair --interactive
register cleanup                             # ドリフトを報告、何も変更しない
register cleanup --prune --dry-run           # ブックマークストアから削除されるもの
register reindex --dry-run

インストール

Apple Silicon: 事前ビルドされたバンドルをダウンロードしてください。最新リリースからfileregister-macos-arm64.tar.gzを解凍すると、register、fileanchorエンジン、grubberが含まれるフォルダが得られ、registerが期待するレイアウトになっています。curlで取得するとそのまま実行できます。ブラウザでダウンロードした後、そのフォルダで一度だけクォーランティンフラグをクリアしてください：xattr -dr com.apple.quarantine register libexec。

または自分でビルドします。PATHにfileanchorが既に存在する場合：

go install github.com/rhsev/fileregister/v2/cmd/register@latest

それ以外の場合は、チェックアウトから両方をビルドします：

make fileanchor        # メタデータエンジン（Swiftツールチェーンが必要）
make grubber           # grubberリリースバイナリ、ノートレイヤー用
make install           # デフォルトで~/binにインストール
make install PREFIX=/usr/local/bin

Go言語と、現在のfileanchorビルドにはmacOSが必要です。registerは単一のGoバイナリであり、すべてのサブコマンドはネイティブです。

コンパニオンリリース

registerは、すべてのメタデータ操作のためにfileanchorエンジン（rhsev/fileanchor）を起動するため、実行時には動作するfileanchorが必要です。grubberクエリツール（rhsev/grubber）はMarkdownレイヤーを読み取ります。これがないと、registerはインデックスのみを管理します。コアコマンド（add、list、resolve、audit、repair、refresh、remove）はこれなしで動作します。ノートを読み取るコマンドにはこれが必要です：album、order、annotate、aka、rename、forget、marshal、reindex、cleanup、list --inbox/--curated。これはregisterが独自のMarkdownリーダーを持たないためです。このリリースはfileanchor 1.4.0およびgrubber v0.19.0でテストされています。make fileanchorはタグでエンジンをビルドし、make grubberはgrubberリリースバイナリを.build/にダウンロードし、make installは両方をregisterの隣に配置します。

設定

ノートディレクトリをregisterに指示します：

export GRUBBER_NOTES=~/notes

または、grubber設定セットを再利用します。これは優先され、設定セットのpath:フィールド（~/.config/grubber/config.yaml内）からディレクトリを読み取ります：

export GRUBBER_SET=contracts

オプション：

export REGISTER_BINDER=berlin-2024          # add/remove/promoteのデフォルトバインダー
export GRUBBER_CONFIG=~/path/to/config.yaml # GRUBBER_SETを解決するためだけに使用
export FILEANCHOR=/path/to/fileanchor       # 以下参照
export GRUBBER_BIN=/path/to/grubber         # それ以外はPATH、次にlibexec/registerの隣

ノートを読み取るほとんどのコマンドにはgrubberが必要です（コンパニオンリリース参照）。また、Markdownサイドカーを直接検索するためにも使用します。--from-jsonlはインデックスをそれらと一緒に取り込み、--explode binder --merge-on id,binderは1レコード/ファイルインデックスをメンバーシップごとの行に投影します。

メタデータエンジン

すべてのmacOSメタデータ作業は、fileanchorを介して行われます。これは独自のレポにあるネイティブエンジンで、移動に強いブックマーク、Finderタグ、Spotlightクエリ、xattrsを単一のバッチ標準入出力プロトコルで提供します。コマンドごとに1回実行され、プロセス全体をインプロセスで処理します。これは、add、audit、refresh、repair、renameが各レコードのファイルに触れるため重要です。ファイルごとに起動されるヘルパーは、プロセスの起動にほとんどの時間を費やすことになります。

このレポにはバイナリは出荷されません。make fileanchorはfileanchorをピン留めされたタグでクローンし、SwiftPMでビルドします。make installはCLIの隣に配置します。MakefileのFILEANCHOR_VERSIONを更新すると、新しいエンジンになります。ビルドにはSwiftツールチェーン（XcodeまたはCommand Line Tools）が必要で、macOS 13以降のバイナリが生成されます。

解決順序、最初に一致したものが勝ちます：

1. $FILEANCHOR、明示的なパス
2. PATH上のfileanchor、独自のビルドまたはシステム全体のインストール
3. <bindir>/libexec/fileanchor、make installがregisterの隣に配置するもの

したがって、PATH上の独自のビルドは、インストールされたコピーよりも優先されます。

2つのレイヤー

JSONLインデックスが権威であり、すべてのregister addがそこに書き込みます。Markdownノートは、その上のオプションのアノテーションレイヤーです。register promoteはIDでリンクされたブロックを追加し、インデックスエントリは元の場所に留まります。アノテーションのないレコードは正常であり、register list --inboxはこのようなレコードを持つバインダーを表示します。

バインダーセットが空のレコードはどのバインダーにも属さない（短い用語でルーズレコード）と追跡されます。自動的に削除されることはありません。これは、register addを--binderなしで行った場合、またはregister removeがセットを空にした後に残った場合に発生します。SPEC §Records in no binderを参照してください。

ドキュメント

• SPEC.md: ディスク上のフォーマット、データモデル、設計上の決定事項
• WHO-WRITES-WHAT.md: 各コマンドがインデックス、ブックマークストア、ファイル、ノートに書き込むもの
• WORKFLOWS.md: コレクションの整理とクエリ
• ORDERING.md: sort:キーとregister order
• ALBUM.md: 順序付けられたバインダー、データとして

ライセンス

PolyForm Noncommercial 1.0.0。ソースは利用可能ですが、OSIオープンソースではありません。

非営利目的であれば、自由に読み取り、使用、構築できます。

---

Built on fileanchor。プレーンテキストツールのファミリーの一部。profile pageに概要があります。