docs: tmuxinator/teamocil parity analysis and feature comparison #1014
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #1014 +/- ##
=======================================
Coverage 80.11% 80.11%
=======================================
Files 28 28
Lines 2409 2409
Branches 457 457
=======================================
Hits 1930 1930
Misses 356 356
Partials 123 123 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
…amocil Comprehensive side-by-side comparison covering architecture, config keys, CLI commands, hooks, and config file discovery across all three tools.
Documents 12 feature gaps (hooks, stop command, pane sync, pane titles, ERB templating, wemux, debug/dry-run, config management CLIs), import behavior with bug inventory, and WorkspaceBuilder requirements.
Documents v0.x vs v1.x format differences, 3 feature gaps (--here flag, debug mode, shell_command_after), import bugs (v1.x incompatibility, redundant filter loops), and WorkspaceBuilder requirements.
Classifies each config key as difference (translatable) or limitation (needs tmuxp feature). Identifies pre/pre_window bug, missing rvm/pre_tab mappings, and 5 features requiring new tmuxp capabilities.
Documents v0.x-only targeting (v1.x unsupported), string pane TypeError bug, redundant filter loop bug, and 6 missing v1.x key mappings (commands, focus, options, string shorthand).
- Remove duplicate 'Attach on create' row in comparison table, keep
corrected version with '(default: true)' near socket_path
- Annotate pre_tab as (deprecated) in comparison table
- Annotate startup_window as accepting name or index
- Fix pre_tab description: deprecated predecessor, not alias (it was
renamed in tmuxinator, not aliased)
- Clarify startup_window renders as "#{name}:#{value}"
- tmuxinator min tmux is 1.8 (recommended), not 1.5; tmux 2.5 is explicitly unsupported - teamocil has no documented min tmux version - tmuxinator detach is via `attach: false` config or `--no-attach` CLI flag, not `-d` (which doesn't exist in tmuxinator)
- Add socket_path as item 16 (tmuxinator config key not handled) - socket_path takes precedence over socket_name in tmuxinator - tmuxp only accepts socket path via CLI -S flag - Add to summary table as missing Difference
- with_env_var is an import-only fix (tmuxp already has environment key), not a Limitation — moved to new "Import-Only Fixes" section - cmd_separator is irrelevant (tmuxp sends commands individually), clarified it needs no import
- Fix "1.5+" to "1.8+" in architecture description (was already fixed in overview table but missed in prose) - Clarify YAML anchors: tmuxinator enables via YAML.safe_load aliases param, not a config key - Clarify tmuxinator edit is alias of new command
…s equivalent tmuxp doesn't have startup_window/startup_pane keys but achieves the same result via focus: true on individual windows/panes. Add cross-reference annotation so users aren't misled by (none).
- before_script maps to on_project_first_start (runs only when session doesn't exist), not on_project_start (runs every invocation) - Add teamocil --here implementation details: sends cd via send-keys, decrements window count for index calculation
- import-teamocil.md: Code block comment said "Lines 144-149" but the `if "filters"` guard is on line 143, so range is 143-149 - parity-teamocil.md: Referenced "Line 142" for `clear` handling but actual code is lines 140-141 (line 142 is blank)
…, expand CLI table - Fix min tmux: 1.5+ (not "1.8 recommended; not 2.5"), per tmux_version.rb - Note teamocil renames session (rename-session) rather than creating new - Add teamocil auto-generated session name detail - Expand pre_window to show full deprecation chain (rbenv/rvm/pre_tab) - Add synchronize values (true/before/after) - Add --suppress-tmux-version-warning to CLI table - Split deprecated pre/post into separate rows with hook mappings - Fix tmuxp --append flag syntax - Fix pane focus to note startup_pane equivalent
… chain, remove --here - Fix startup_window: accepts name OR index (not just name) - Document pre_window fallback chain: rbenv → rvm → pre_tab → pre_window - Remove section 12 (--here) — this is a teamocil feature, not tmuxinator - Renumber section 13 → 12 - Clarify freeze vs tmuxinator new comparison - Add rvm source reference (project.rb:181) - Add tmuxinator version range to header
…md_separator - Add section 1: teamocil renames session (rename-session), not creates - Note auto-generated session name (teamocil-session-RANDOM) - Add window focus implementation detail (session.rb:24-25) - Add --list and --edit note for teamocil CLI - Reclassify with_env_var and cmd_separator as unverified (not in source) - Add session rename mode to WorkspaceBuilder gaps - Fix line number references (144-149, 147-149, 161-163) - Renumber sections to account for new section 1
… analysis - Fix pre/pre_window mapping: pre → before_script (session-level, runs once), pre_window → shell_command_before (per-pane) - Add template.erb line references for execution order - Expand cli_args fragility analysis (str.replace is unsafe) - Add tmuxinator source references for tmux_options and socket handling
…tale TODOs - with_env_var does not exist in teamocil 1.4.2 source - cmd_separator does not exist in teamocil 1.4.2 source - Both are only in importer docstring TODOs (importers.py:121-123) - Reclassify both as unverified in summary table - Update code issues section to note stale TODOs
Analyze libtmux and tmuxp limitations blocking feature parity with tmuxinator and teamocil. Document dead config keys, importer bugs, and required API additions organized by implementation phase.
…ails - L2: Fix method name (raise_if_dead, not is_alive), document two independent code paths - L4: Fix Pane.select() line number (577, not 581) - T4: Add session rename mode alongside --here, note --append gap - T8: Correct env var expansion scope (works in most values, not just start_directory) - I1: Document isinstance check bug (checks pre type instead of pre_window type)
L1: pane_title is excluded from libtmux's bulk format queries, not
removed from tmux itself — tmux still supports #{pane_title}
(format.c:205) and select-pane -T (added in tmux 2.6).
T1: synchronize before/true insertion point is build() line 320
(after on_window_create hook, before iter_create_panes loop), not
iter_create_windows() line 424 which is inside the generator.
T3: shell_command_after is a window-level key (set by teamocil
importer on window_dict), not per-pane. Correct insertion point
is config_after_window() or after the pane loop in build().
T2: Session-level pane title options insertion is alongside other session options at lines 303-309, not "around line 311". Pane-level title should be set after commands are sent (around line 535), before focus handling at line 536. I7: Stale TODOs are at lines 121 and 123 (not 121-123), since line 122 is `clear` which is a real teamocil feature.
tony
force-pushed
the
tmuxinator-parity
branch
from
304ff40 to
8e9425c
Compare
T1: synchronize-panes became dual-scope (window|pane) in tmux 3.2 (options-table.c:1423). Since tmuxp requires 3.2+, window.set_option() works through option inheritance — panes inherit window-level setting. I5: on_project_first_start → before_script mapping only works for single commands or script paths. Multi-command strings with semicolons fail because Popen runs without shell=True.
I4: Note that v0.x pane width is silently dropped (importers.py:161-163) with no user warning. Pane.resize() exists in libtmux (L4) so this could be preserved. Phase 2/3: Note that builder additions (T1 synchronize, T2 pane titles) require corresponding tmuxinator importer updates to actually import those keys from tmuxinator configs.
Phase 4/5 item numbers now restart per-phase (consistent with Phases 1-3). Previously continued numbering from prior phases. L3 (pre-execution command logging) was a dependency of T9 but was not listed in any phase. Now explicitly listed in Phase 5 before T9.
L3: common.py:291 debug log includes both cmd and stdout (not "only stdout"), but after execution — the blocker is lack of pre-execution logging. I2: Replace misleading /opt/foobar example with accurate demonstration of -L flag leaking into config value.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
docs/comparison.md— comprehensive feature comparison table (tmuxp vs tmuxinator vs teamocil) covering architecture, config keys, CLI commands, hooks, and config file discoverynotes/parity-tmuxinator.md— identifies 12 feature gaps, import bugs, and WorkspaceBuilder requirements for tmuxinator paritynotes/parity-teamocil.md— documents v0.x/v1.x format differences, 3 feature gaps, and import bugsnotes/import-tmuxinator.md— classifies each tmuxinator config key as translatable difference or tmuxp limitation, identifiespre/pre_windowbugnotes/import-teamocil.md— documents v0.x-only importer targeting (v1.x unsupported), string pane TypeError bug, redundant filter loopsKey findings
Importer bugs discovered:
import_tmuxinator: when bothpreandpre_windowexist, writes toshell_command(not a valid tmuxp session key) —precommands silently lostimport_teamocil: targets v0.x format only; v1.x string panes cause TypeError; redundantfor _b inloops in filter handlingtmuxinator feature gaps (12):
Lifecycle hooks (5 hooks vs tmuxp's 1), pane synchronization, pane titles, ERB templating, wemux support, stop/kill command, debug/dry-run, config management CLIs,
--no-pre-windowflagteamocil feature gaps (3):
--hereflag (reuse current window),--debugdry-run mode,shell_command_aftertmuxp advantages (unique features):
Per-pane environment/shell/sleep/history control, plugin system, JSON config, session freeze, workspace search, upward config traversal
Test plan
importers.pyline numbers