ドキュメント

コマンドライン

pullmark というひとつのコマンドが、ファイルとフォルダを アプリに手渡します。ターミナルの前にいる人間のために、そして、あなたの目の前に文書を置きたい エージェントやスクリプトのために。

コマンドをインストールする

PullMark をどう手に入れたかで、コマンドの入れ方も決まります。

• Homebrew — すでに入っています。cask が pullmark を brew の prefix にリンクします。
• DMG — 設定 (⌘,) →「一般」 を開いて 「pullmark コマンドをインストール…」 をクリックしてください。コマンドが /usr/local/bin にリンクされます（認証を求められることがあります）。
• ソースのチェックアウト — make install-cli （置き場所を選ぶなら BIN_DIR=~/bin を付けてください）。

基本のことだけなら、どちらにせよインストールは要りません—— open -a PullMark README.md ~/notes が macOS 自身を通して 同じことをしてくれます。

使い方

pullmark                     # PullMark を起動（または前面に）
pullmark <path> ...          # ファイルやフォルダを開く
pullmark --diff <path> ...   # HEAD との差分をレンダリングして開く
pullmark --diff=<ref> <path> ...
                             # … ブランチ・タグ・コミットとの差分で
pullmark --diff=<r1>..<r2> <path> ...
                             # 2 つの ref のファイルを、どちらも固定して
pullmark --diff-with=<file> <path> ...
                             # … ディスク上の別ファイルとの差分で
pullmark -h, --help          # 組み込みのリファレンス
pullmark --version           # アプリのバージョンを表示

開くと何が起きるか

ルールはあえて退屈にしてあります。スクリプトが安心して頼れるように。

• ファイルは、サイドバーの 「開いているファイル」セクションにピン留めされた項目として 並び、最後に渡したファイルが表示されます。
• フォルダは——git のワークツリーも含めて—— 「場所」になります。中の Markdown ファイルを ブラウズできるツリーです。
• すでに起動している？ すべては最前面のウィンドウで開きます。アプリの 2 つ目のインスタンスが立ち上がることはありません。
• 相対パスはカレントディレクトリを基準に解決され、~ は いつもどおり使えます。
• 存在しないパスがひとつでもあれば、コマンド全体が中止されます—— メッセージと終了コード 1 を返して。中途半端に開くことはありません。

ワークツリーと、ひとつのファイルを指し示すこと

フォルダとファイルを一緒に渡せば、両方のふるまいが同時に起きます。フォルダは「場所」として 開き、ファイルはピン留めされて表示される。「このワークツリーを開いて、このドキュメントを見せて」 のレシピは、これで全部です。

$ pullmark ~/wt/feature ~/wt/feature/docs/plan.md

ワークツリーのツリーは「場所」に着地し（ワークツリーもただの git チェックアウトなので、 ブランチチップ付きで）、plan.md は「開いているファイル」にピン留めされてレンダリングされます。 右クリックして 「Location 内に表示」 を選べば、ツリーの中のその居場所へ飛べます。 「場所」がすでに開いていたときも同じです——その中にあるファイルを開いても、世界がもうひとつ できることはなく、作業セットに 1 行が増えるだけです。

フォルダとファイルの組み合わせに順番は関係ありませんが、表示されるのは最後に渡した ファイルです。画面に出したい文書は、最後に置いてください。

シェルから、レンダリングされた差分を

--diff は、それぞれのファイルを比較しながら開きます——作業中の内容を 直近のコミットと突き合わせ、プルリクエストとまったく同じ、レンダリングされた単語単位の差分として。 --diff=<ref> なら、代わりにブランチ・タグ・コミット SHA と比べます。アプリの 「比較」機能——ツールバーの時計とシェブロンのボタン——へのシェルからの入り口であり、 「エージェントはこの文書に何をしたのか」への最速の答えです。

$ pullmark --diff docs/plan.md            # 直近の編集が変えたもの
$ pullmark --diff=main README.md          # 現在のファイルと main
$ pullmark --diff=v1.0..main README.md    # 2 つのリビジョン間、どちらも固定
$ pullmark --diff-with=old.md new.md      # 2 つのファイル、old.md が基準
$ pullmark --diff ~/wt/feature ~/wt/feature/docs/plan.md
                                          # ワークツリーと、差分の plan.md

一緒に渡したフォルダは変わらず「場所」として開きますし、どの形にも、ツールバーの 「比較」メニューにアプリ内の双子がいます（「リビジョンを比較…」と 「ファイルと比較…」を含めて）。--diff と --diff-with はあくまでフラグであってサブコマンドではないので、たまたま diff という名前のファイルは、いつもどおりただ開きます。

終了コード

例

$ pullmark README.md                      # ファイルをひとつ読む
$ pullmark ~/notes                        # フォルダをブラウズする
$ pullmark docs specs/design.md           # 「場所」ひとつと文書ひとつ
$ pullmark ~/wt/feature docs/plan.md      # ワークツリーと、見せたい文書
$ pullmark --diff docs/plan.md            # 直近の編集が変えたもの
$ pullmark -- --weird-filename.md         # -- でオプション解析を終える

エージェント向けのメモ

PullMark をエージェントやスクリプトに組み込むなら。

• コマンドは、macOS がオープンを受け付けた時点で戻ります——アプリのレンダリングは 待ちません。
• 同じものを二度開いても冪等です。すでに開いているファイルやフォルダは、複製されずに 選択されます。
• すべてが最前面のウィンドウに着地するのは設計どおりで、ひとつのウィンドウを見ている 人間のところへ、開いたものが順に届きます。
• 文書を編集したあとの pullmark --diff <file> は、あなたが何を 変えたのかを人間の目の前に置くための 1 行です——レンダリングされ、変わった単語が ハイライトされた姿で。