nuǝɯ pǝɥsᴉꞁod mǝu

    tmex

    1.0.9 • Public • Published

    A minimalist tmux layout manager - one shell script + tmux + zero other dependencies

     ______   __    __    ______    __  __
    /\__  _\ /\ \  |\ \  /\  ___\  /\_\_\_\
    \/_/\ \/ \ \ \ | \ \ \ \  ___\ \/_/\_\/_
       \ \_\  \ \_\ \ \_\ \ \_____\  /\_\/\_\
        \/_/   \/_/  \/_/  \/_____/  \/_/\/_/  tmux execute
    

    tests shellcheck latest release npm package license

    Contents - Usage | Layout | npm | Install | Tests | License

    Create a dashboard for your project with one command. No messing with configuration files. Just the full power of tmux, plus an easy-yet-flexible layout system:

    tmex -n test lint "npm install"

    tmex demo

    Tailor-made for simplifying unwieldy package.json scripts (though tmex works just as well with any arbitrary commands):

    package.json
    {
      "name": "special-project"
      "scripts": {
        "watch": "parcel index.html",
        "server": "python -m http.server",
        "typecheck" "tsc --watch --noEmit",
    -   "start": "tmux new-session -s $npm_package_name 'npm run watch' \\; split-window 'npm run server' \\; split-window 'npm run typecheck'"
    +   "start": ✨"tmex -n watch server typecheck"✨
      }
    }

    With tmex, npm run start composes watch, server, and typecheck into a single view with ease:

    ┌───────────┬───────────┐
    │ npm run   │ npm run   │
    │ watch     │ server    │
    │           ├───────────┤
    │           │ npm run   │
    │           │ typecheck │
    └───────────┴───────────┘
    session : special-project
    

    Sane defaults. Layouts with any number of panes. Given 8 commands, tmex generates:

    ┌───────┬───────┬───────┐
    │ cmd 1 │ cmd 3 │ cmd 6 │
    │       ├───────┼───────┤
    ├───────┤ cmd 4 │ cmd 7 │
    │ cmd 2 ├───────┼───────┤
    │       │ cmd 5 │ cmd 8 │
    └───────┴───────┴───────┘
    

    Usage

    tmex your-session-name "cmd a" "cmd b" "cmd c" ... etc.

    With options and custom layout provided:

    tmex your-session-name --npm --layout=1224 --transpose "cmd a" "cmd b" "cmd c" ... etc.

    Shorthand:

    tmex your-session-name -nt 1224 "cmd a" "cmd b" "cmd c" ... etc.
                            │     │              │
                  options ──┘     └── layout     └── shell commands

    Session name optional if --npm or -n is set (will default to package name, details below):

    tmex -nt 1224 "cmd a" "cmd b" "cmd c" ... etc.
    

    Full options list (also accessible via tmex -h):

    tmex <session-name>                - session name required unless --npm set; all other args optional
      [-h|--help]
      [-v|--version]
      [[-l|--layout] <1-9,[,],{,}>]    -l, --layout      layout string, each digit represents number of panes in column
      [-t|--transpose]                 -t, --transpose   build layout in left-to-right orientation instead of top-to-bottom
      [-n|--npm]                       -n, --npm         if set, prefix each command with "npm run" for package.json scripts
      [-p|--print]                     -p, --print       emit command as string of tmux args instead of invoking tmux directly
      [-d|--detached]                  -d, --detached    invoke tmux with -d (detached session); useful for piping data to tmex
      [-r|--reattach]                  -r, --reattach    if tmux session already exists, re-attach to it instead of replacing it
      [-s|--shellless]                 -s, --shellless   if set, invoke commands directly with tmux instead of running inside shell
      ["shell command 1"]
      ["shell command 2"]              - shell commands that will be executed in each pane
      ...                                number of shell commands N must not exceed sum of layout
      ["shell command N"]
    

    Layout

    If no layout is provided, a sensible default will be generated to match the number of commands provided. However, layouts are fully customizable via --layout or -l (or as shorthand, the first argument after session name if it is a valid layout):

    tmex your-session-name 1224
    # or
    tmex your-session-name -l 1224
    # or
    tmex your-session-name --layout=1224
    >>>                             │
       1─────2─────2─────4──────────┘
    ┌─────┬─────┬─────┬─────┐
    │     │     │     │  f  │
    │     │  b  │  d  ├─────┤
    │     │     │     │  g  │
    │  a  ├─────┼─────┼─────┤
    │     │     │     │  h  │
    │     │  c  │  e  ├─────┤
    │     │     │     │  i  │
    └─────┴─────┴─────┴─────┘

    Each digit of 1224 specifies the number of panes each column will be split into. To operate on rows instead of columns, transpose layout left-to-right instead of top-to-bottom with --transpose or -t:

    tmex your-session-name --transpose --layout=1224
    >>>                                         │
    ┌───────────────────────┐                   │
    │           a           │ 1─────────────────┘
    ├───────────┬───────────┤ │
    │     b     │     c     │ 2
    ├───────────┼───────────┤ │
    │     d     │     e     │ 2
    ├─────┬─────┼─────┬─────┤ │
    │  f  │  g  │  h  │  i  │ 4
    └─────┴─────┴─────┴─────┘

    Layouts may be arbitrarily complex via sublayouts [xyz] and custom sizing {xyz}:

    tmex your-session-name --layout=1[2{13}1]4{4112}
    >>>                                 │      │
             ┌──────────────────────────┘      │
    ┌─────┬──│────────┬─────┐                  │
    │     │  │        │     │                  │
    │     │ 1│3       │  4─────────────────────┘
    │     │  │        │  │  │
    │     ├──┴────────┼──1──┤
    │     │           ├──1──┤
    │     │           ├──│──┤
    │     │           │  2  │
    └─────┴───────────┴─────┘

    In the example above, the layout 1[2{13}1]4{4112} contains the sublayout 2{13}1 which is constructed in the second column of the full layout. This in turn specifies relative sizing 2{13} for its first 2 panes, meaning the 2nd pane will be 3x the size of the 1st (denoted by 1, 3 in the diagram above). The 3rd column of the full layout 4{4112} also defines custom sizing of panes (denoted by 4, 1, 1, 2 in the diagram above).

    npm

    Simplify package.json scripts via --npm or -n. Commands will be prefixed with npm run (if necessary) and session name will default to $npm_package_name. This will expand to match the name field set in package.json.

    NOTE: tmux replaces ._, :_, \\\ when setting session names, so your final session name may not exactly match the name specified in package.json (or the name you provide via the <session-name> argument at the command line).

    cat package.json | grep name
    >>> "name": "special-project"
    
    tmex -n watch server typecheck
    >>>
    ┌───────────┬───────────┐
    │ npm run   │ npm run   │
    │ watch     │ server    │
    │           ├───────────┤
    │           │ npm run   │
    │           │ typecheck │
    └───────────┴───────────┘
    session : special-project

    Install

    Install as a build tool in a package:

    npm install --save-dev tmex

    Install globally for use with any set of package.json scripts or arbitrary commands:

    npm install -g tmex

    or sans-npm:

    curl -o ~/bin/tmex https://raw.githubusercontent.com/evnp/tmex/master/tmex && chmod +x ~/bin/tmex
    # or /usr/local/bin or other bin of your choice (as long it's in your $PATH)

    tmex has no external dependencies other than tmux, but always read code before downloading to ensure it contains nothing unexpected.

    tmex doesn't install tmux itself, so you'll also want to do that if you don't have tmux yet:

    tmex -n test lint "npm install"
    /Users/evan/bin/tmex: line 694: tmux: command not found
    
    brew install tmux      # OSX
    sudo apt install tmux  # Ubuntu, Debian

    or refer to https://github.com/tmux/tmux/wiki/Installing for install instructions applicable to your platform.

    Tests

    Run once:

    npm install
    npm test

    Use fswatch to re-run tests on file changes:

    brew install fswatch
    npm install
    npm run testw

    Non-OSX: replace brew install fswatch with package manager of choice (see fswatch docs)

    License

    MIT

    Keywords

    none

    Install

    npm i tmex

    DownloadsWeekly Downloads

    179

    Version

    1.0.9

    License

    MIT

    Unpacked Size

    33.6 kB

    Total Files

    4

    Last publish

    Collaborators

    • evnp