{{tag>[cli terminal multiplexer tmux config]}}

====== tmux configuration ======
tmux config file의 위치, option scope, key binding, format과 안전한 reload 방법.

===== Summary =====
  * tmux server가 시작될 때 config file을 읽는다.
  * config는 shell script가 아니라 tmux command를 한 줄씩 기록하는 file이다.
  * server, session, window, pane option의 scope를 구분하고 global 변경에는 ''-g''를 명시한다.
  * 기존 server에는 ''source-file''로 다시 읽되, 적용 전에 별도 server에서 syntax를 검증한다.

===== File Locations =====
  * ''~/.tmux.conf'': 전통적인 user config
  * ''$XDG_CONFIG_HOME/tmux/tmux.conf'': XDG user config
  * ''/etc/tmux.conf'': 일반적인 system-wide config 위치이며 build 또는 platform에 따라 다를 수 있다.
  * ''tmux -f PATH'': 지정한 config file로 새 server를 시작한다.

<note important>
정확한 검색 순서와 system config path는 설치된 version의 ''man 1 tmux''를 확인한다. 이미 실행 중인 server는 새 client를 열기만 해서는 config를 자동으로 다시 읽지 않는다.
</note>

===== Syntax =====
<code text>
# comment
set-option -g mouse on
set-window-option -g mode-keys vi
bind-key r source-file ~/.tmux.conf \; display-message "tmux.conf reloaded"
</code>

  * command는 한 줄에 하나씩 쓴다.
  * 공백이 있는 argument는 single quote, double quote 또는 backslash로 quote한다.
  * ''#''로 시작하는 줄은 comment다.
  * 여러 command를 연결할 때는 semicolon을 tmux parser에 전달하도록 escape해야 할 수 있다.
  * tmux config는 shell과 비슷한 quoting 일부를 지원하지만 shell의 ''$()'' 같은 command substitution을 직접 실행하는 script가 아니다.

===== Options =====
==== Scope ====
  * server option: tmux server 전체에 적용한다. 예: ''buffer-limit''.
  * session option: 특정 session 또는 ''-g''를 사용한 global default에 적용한다. 예: ''status'', ''mouse''.
  * window option: 특정 window 또는 global window default에 적용한다. 예: ''mode-keys'', ''automatic-rename''.
  * pane option: pane에 적용한다.
  * user option: ''@name'' 형식이며 plugin이나 user config에서 자유롭게 사용한다.

<code bash>
# 현재 server option
tmux show-options -s

# global session option
tmux show-options -g

# global window option
tmux show-window-options -g
</code>

==== Practical Defaults ====
<code text>
# mouse로 pane 선택, resize, copy mode 사용
set-option -g mouse on

# scrollback line 수
set-option -g history-limit 50000

# window와 pane index를 1부터 시작
set-option -g base-index 1
set-window-option -g pane-base-index 1

# vi-style copy mode
set-window-option -g mode-keys vi

# terminal capability는 실제 terminal과 tmux version에 맞춰 조정
set-option -g default-terminal "tmux-256color"
</code>

<note warning>
''default-terminal''을 무조건 바꾸면 terminfo가 없는 remote host나 오래된 system에서 application 표시가 깨질 수 있다. 먼저 ''infocmp tmux-256color''로 entry가 있는지 확인한다.
</note>

===== Key Bindings =====
<code text>
# prefix table: prefix 다음 r
bind-key r source-file ~/.tmux.conf \; display-message "tmux.conf reloaded"

# prefix 없이 Alt+h/j/k/l로 pane 이동
bind-key -n M-h select-pane -L
bind-key -n M-j select-pane -D
bind-key -n M-k select-pane -U
bind-key -n M-l select-pane -R
</code>

  * ''bind-key''는 기본적으로 ''prefix'' key table에 binding을 만든다.
  * ''-n''은 ''-T root''의 shorthand이며 prefix 없이 key를 처리한다.
  * ''unbind-key KEY''는 binding을 제거한다.
  * ''tmux list-keys -T prefix''와 ''tmux list-keys -T root''로 충돌을 확인한다.

===== Formats =====
tmux format은 ''#{name}'' 문법으로 session, window, pane 상태를 command output과 status line에 삽입한다.

<code text>
set-option -g status-left '#S '
set-option -g status-right '#{?client_prefix,PREFIX ,}%Y-%m-%d %H:%M'
</code>

<code bash>
tmux display-message -p '#{session_name}:#{window_index}.#{pane_index}'
tmux list-panes -a -F '#{pane_id} #{pane_current_command} #{pane_current_path}'
</code>

===== Reload and Validation =====
<code bash>
# 현재 server에 적용
tmux source-file ~/.tmux.conf

# 별도 socket 이름으로 isolated server에서 config 확인
tmux -L config-test -f ~/.tmux.conf new-session -d -s config-test
tmux -L config-test list-sessions
tmux -L config-test kill-server
</code>

<note important>
별도 socket을 사용하면 현재 작업 중인 기본 tmux server에 영향을 주지 않고 config를 확인할 수 있다. 검증용 server만 대상으로 ''kill-server''를 실행한다.
</note>

===== Troubleshooting =====
  * reload 후 변경이 없으면 option scope와 target을 확인한다. 기존 session에는 global default 변경이 즉시 반영되지 않는 option도 있다.
  * ''unknown option'' 또는 ''unknown command''는 설치된 tmux가 config 문법보다 오래된 경우가 많다. ''tmux -V''와 manual을 확인한다.
  * key가 동작하지 않으면 ''tmux list-keys''로 실제 table과 중복 binding을 확인한다.
  * color가 깨지면 바깥 terminal의 ''TERM'', tmux의 ''default-terminal'', host의 terminfo를 함께 확인한다.
  * config가 server 시작을 막으면 ''tmux -f /dev/null'' 또는 별도 최소 config로 원인을 격리한다.

===== See Also =====
  * [[tmux:ko|tmux]]
  * [[tmux:cheatsheet|tmux cheatsheet]]
  * [[https://github.com/tmux/tmux/wiki/Getting-Started#configuring-tmux|Configuring tmux]]
  * [[https://man.openbsd.org/tmux|tmux(1) manual]]

===== History =====
  * codex:: 2026-07-27 Added config locations, syntax, option scope, key bindings, formats, isolated validation, and troubleshooting guidance.

{{indexmenu>.#1|js}}