Niestandardowe polecenia

Definiuj niestandardowe polecenia i układy workspace, dodając plik cmux.json do katalogu głównego projektu lub ~/.config/cmux/. Polecenia pojawiają się w palecie poleceń.

Lokalizacje plików

cmux szuka konfiguracji w dwóch miejscach:

Per projekt: ./cmux.json — znajduje się w katalogu projektu, ma pierwszeństwo
Globalnie: ~/.config/cmux/cmux.json — stosuje się do wszystkich projektów, uzupełnia polecenia niezdefiniowane lokalnie

Lokalne polecenia zastępują globalne polecenia o tej samej nazwie.

Zmiany są pobierane automatycznie — nie trzeba restartować.

Schemat

Plik cmux.json zawiera tablicę commands. Każde polecenie to albo proste polecenie shell, albo pełna definicja workspace:

cmux.json

{
  "commands": [
    {
      "name": "Start Dev",
      "keywords": ["dev", "start"],
      "workspace": { ... }
    },
    {
      "name": "Run Tests",
      "command": "npm test",
      "confirm": true
    }
  ]
}

Proste polecenia

Proste polecenie uruchamia polecenie shell w aktualnie sfokusowanym terminalu:

cmux.json

{
  "commands": [
    {
      "name": "Run Tests",
      "keywords": ["test", "check"],
      "command": "npm test",
      "confirm": true
    }
  ]
}

Pola

name — Wyświetlane w palecie poleceń (wymagane)
description — Opcjonalny opis
keywords — Dodatkowe terminy wyszukiwania dla palety poleceń
command — Polecenie shell do uruchomienia w sfokusowanym terminalu
confirm — Pokaż okno dialogowe potwierdzenia przed uruchomieniem

Proste polecenia są uruchamiane w bieżącym katalogu roboczym aktywnego terminala. Jeśli polecenie wymaga ścieżek względnych do projektu, dodaj prefiks cd "$(git rev-parse --show-toplevel)" && aby uruchomić z katalogu głównego repozytorium, lub cd /your/path && dla dowolnego konkretnego katalogu.

Polecenia workspace

Polecenie workspace tworzy nowy workspace z niestandardowym układem podziałów, terminali i paneli przeglądarki:

cmux.json

{
  "commands": [
    {
      "name": "Dev Environment",
      "keywords": ["dev", "fullstack"],
      "restart": "confirm",
      "workspace": {
        "name": "Dev",
        "cwd": ".",
        "layout": {
          "direction": "horizontal",
          "split": 0.5,
          "children": [
            {
              "pane": {
                "surfaces": [
                  {
                    "type": "terminal",
                    "name": "Frontend",
                    "command": "npm run dev",
                    "focus": true
                  }
                ]
              }
            },
            {
              "pane": {
                "surfaces": [
                  {
                    "type": "terminal",
                    "name": "Backend",
                    "command": "cargo watch -x run",
                    "cwd": "./server",
                    "env": { "RUST_LOG": "debug" }
                  }
                ]
              }
            }
          ]
        }
      }
    }
  ]
}

Pola workspace

name — Nazwa zakładki workspace (domyślnie nazwa polecenia)
cwd — Katalog roboczy workspace
color — Kolor zakładki workspace
layout — Drzewo układu definiujące podziały i panele

Zachowanie przy restarcie

Kontroluje co się dzieje, gdy workspace o tej samej nazwie już istnieje:

"ignore" — Przełącz do istniejącego workspace (domyślnie)
"recreate" — Zamknij i odtwórz bez pytania
"confirm" — Zapytaj użytkownika przed odtworzeniem

Drzewo układu

Drzewo układu definiuje jak panele są rozmieszczone za pomocą rekurencyjnych węzłów podziału:

Węzeł podziału

Dzieli przestrzeń na dwoje dzieci:

direction — "horizontal" lub "vertical"
split — Pozycja dzielnika od 0.1 do 0.9 (domyślnie 0.5)
children — Dokładnie dwa węzły podrzędne (podział lub panel)

Węzeł panelu

Węzeł liścia zawierający jedną lub więcej powierzchni (zakładki wewnątrz panelu).

Definicja powierzchni

Każda powierzchnia w panelu może być terminalem lub przeglądarką:

type — "terminal" lub "browser"
name — Niestandardowy tytuł zakładki
command — Polecenie shell do automatycznego uruchomienia przy tworzeniu (tylko terminal)
cwd — Katalog roboczy dla tej powierzchni
env — Zmienne środowiskowe jako pary klucz-wartość
url — URL do otwarcia (tylko przeglądarka)
focus — Sfokusuj tę powierzchnię po utworzeniu

Rozwiązanie katalogu roboczego

. lub pominięty — katalog roboczy workspace
./subdir — względem katalogu roboczego workspace
~/path — rozwinięty do katalogu domowego
Ścieżka bezwzględna — używana bez zmian

Pełny przykład

cmux.json

{
  "commands": [
    {
      "name": "Web Dev",
      "description": "Docs site with live preview",
      "keywords": ["web", "docs", "next", "frontend"],
      "restart": "confirm",
      "workspace": {
        "name": "Web Dev",
        "cwd": "./web",
        "color": "#3b82f6",
        "layout": {
          "direction": "horizontal",
          "split": 0.5,
          "children": [
            {
              "pane": {
                "surfaces": [
                  {
                    "type": "terminal",
                    "name": "Next.js",
                    "command": "npm run dev",
                    "focus": true
                  }
                ]
              }
            },
            {
              "direction": "vertical",
              "split": 0.6,
              "children": [
                {
                  "pane": {
                    "surfaces": [
                      {
                        "type": "browser",
                        "name": "Preview",
                        "url": "http://localhost:3777"
                      }
                    ]
                  }
                },
                {
                  "pane": {
                    "surfaces": [
                      {
                        "type": "terminal",
                        "name": "Shell",
                        "env": { "NODE_ENV": "development" }
                      }
                    ]
                  }
                }
              ]
            }
          ]
        }
      }
    },
    {
      "name": "Debug Log",
      "description": "Tail the debug event log from the running dev app",
      "keywords": ["log", "debug", "tail", "events"],
      "restart": "ignore",
      "workspace": {
        "name": "Debug Log",
        "layout": {
          "direction": "horizontal",
          "split": 0.5,
          "children": [
            {
              "pane": {
                "surfaces": [
                  {
                    "type": "terminal",
                    "name": "Events",
                    "command": "tail -f /tmp/cmux-debug.log",
                    "focus": true
                  }
                ]
              }
            },
            {
              "pane": {
                "surfaces": [
                  {
                    "type": "terminal",
                    "name": "Shell"
                  }
                ]
              }
            }
          ]
        }
      }
    },
    {
      "name": "Setup",
      "description": "Initialize submodules and build dependencies",
      "keywords": ["setup", "init", "install"],
      "command": "./scripts/setup.sh",
      "confirm": true
    },
    {
      "name": "Reload",
      "description": "Build and launch the debug app tagged to the current branch",
      "keywords": ["reload", "build", "run", "launch"],
      "command": "./scripts/reload.sh --tag $(git branch --show-current)"
    },
    {
      "name": "Run Unit Tests",
      "keywords": ["test", "unit"],
      "command": "./scripts/test-unit.sh",
      "confirm": true
    }
  ]
}