From cc51f486317822cd49244be9d6f3cb55f6b6666f Mon Sep 17 00:00:00 2001 From: gm Date: Thu, 23 Jul 2026 15:13:50 +0900 Subject: [PATCH] Add WezTerm configuration README --- README.md | 152 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 152 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..02452fa --- /dev/null +++ b/README.md @@ -0,0 +1,152 @@ +# WezTerm 설정 + +MobaXterm처럼 SSH 연결과 세션을 빠르게 전환할 수 있도록 구성한 개인 WezTerm 설정입니다. +Windows 사용을 중심으로 하며, 탭/패인 관리, SSH 도메인, 대화형 설정 메뉴와 +GPU 가속 렌더링을 한 파일에 담고 있습니다. + +## 현재 상태 + +- 기본 브랜치: `main` +- 설정 파일: `wezterm.lua` +- 확인 기준: 2026-07-23, `origin/main`과 로컬 브랜치가 동일함 +- 최신 설정 변경 커밋: `59ea062` - SSH 최초 연결 시 중복 탭이 생기는 문제 수정 +- 등록된 SSH 도메인: `du5t` (`172.30.1.41:228`, 사용자 `gm`) +- 시작 동작: 메인 메뉴를 표시하고 첫 번째 SSH 도메인에 한 번 자동 연결 + +현재 홈 디렉터리의 `~/.wezterm.lua`는 저장소 버전보다 이전 상태입니다. 저장소 버전에는 +다음 변경이 더 포함되어 있습니다. + +- SSH 연결에 `AttachDomain`을 사용해 최초 연결 시 중복 탭 방지 +- 메인 메뉴와 설정 메뉴 항목에 아이콘 추가 +- 일반 우클릭, `Shift+우클릭`, `Ctrl+Shift+우클릭` 붙여넣기 지원 + +## 주요 기능 + +- JetBrains Mono와 Noto Sans KR 폰트 폴백 +- Catppuccin Mocha 테마, 투명도 `0.92` +- 호스트별 탭 색상과 프로세스 기반 탭 제목 +- 도메인, 워크스페이스, 접속 경과 시간, 현재 시각을 표시하는 상태바 +- SSH 도메인 및 Unix mux 도메인 +- 폰트, 테마, 투명도, SSH 연결 등을 수정하는 대화형 메뉴 +- 탭/패인, 검색, Copy mode, Quick Select, 워크스페이스 단축키 +- WebGPU 고성능 렌더링, 최대 120 FPS +- Kitty graphics, iTerm2, Sixel 이미지 프로토콜 +- IPv4 주소 Quick Select + +## 설치 + +### Windows + +저장소의 `wezterm.lua`를 사용자 홈의 `.wezterm.lua`로 복사합니다. + +```powershell +Copy-Item .\wezterm.lua $HOME\.wezterm.lua +``` + +### Linux/macOS + +```bash +cp wezterm.lua ~/.wezterm.lua +``` + +기본 폰트인 `JetBrains Mono`와 `Noto Sans KR`을 설치한 뒤 WezTerm을 완전히 종료하고 +다시 실행합니다. 설정 오류는 다음 명령으로 확인할 수 있습니다. + +```bash +wezterm show-config +``` + +## 메뉴 + +WezTerm을 시작하면 메인 메뉴가 열립니다. 등록된 SSH 도메인에 연결하거나 설정 메뉴로 +들어갈 수 있습니다. 메뉴를 닫은 뒤에는 `Leader+m`으로 다시 열 수 있습니다. + +설정 메뉴에서 다음 항목을 직접 변경할 수 있습니다. + +- 폰트 크기, 영문/한글 폰트, 줄 높이, 색상 테마, 창 투명도 +- SSH 도메인 추가 및 수정, 도메인 목록, 통합 런처 +- 스크롤백, 최대 FPS, 탭바 위치, 창 닫기 확인 + +메뉴에서 바꾼 값은 실행 중인 설정 파일에 기록되고 설정이 다시 로드됩니다. SSH 도메인을 +추가하거나 수정한 경우 WezTerm 프로세스를 완전히 종료한 뒤 다시 실행해야 합니다. + +## 단축키 + +Leader 키는 `Ctrl+a`이며, 다음 키를 1초 안에 이어서 누릅니다. + +| 키 | 동작 | +| --- | --- | +| `Ctrl+Shift+t` | 현재 도메인에 새 탭 | +| `Ctrl+Shift+w` | 현재 탭 닫기 | +| `Ctrl+Shift+1/2/3` | 1/2/3번 탭으로 이동 | +| `Leader+\` | 좌우 패인 분할 | +| `Leader+-` | 상하 패인 분할 | +| `Leader+h/j/k/l` | 패인 이동 | +| `Leader+x` | 현재 패인 닫기 | +| `Leader+z` | 현재 패인 확대/복원 | +| `Leader+r` | 패인 크기 조절 모드 | +| `Leader+w` | 워크스페이스 목록 | +| `Leader+s` | SSH 도메인 목록 | +| `Leader+e` | 저장된 실행 메뉴 | +| `Leader+Tab` | 통합 런처 | +| `Leader+m` | 메인 메뉴 | +| `Leader+Enter` | 현재 패인을 새 창으로 이동 | +| `Leader+/` | 스크롤백 검색 | +| `Leader+[` | Copy mode | +| `Leader+Space` | Quick Select | +| `Ctrl+=/-/0` | 폰트 크기 확대/축소/초기화 | +| `Ctrl+Shift+c/v` | 복사/붙여넣기 | + +마우스 동작은 다음과 같습니다. + +| 동작 | 결과 | +| --- | --- | +| 우클릭 | 클립보드 붙여넣기 | +| `Shift+우클릭` | 마우스를 캡처하는 전체 화면 앱에서 붙여넣기 | +| `Ctrl+클릭` | 커서 아래 링크 열기 | +| `Ctrl+Shift+클릭` | 메인 메뉴 | +| `Ctrl+Shift+더블클릭` | 현재 패인을 새 창으로 이동 | + +## SSH 설정 + +현재 첫 번째 SSH 도메인은 시작 시 자동 연결됩니다. + +```lua +config.ssh_domains = { + { + name = "du5t", + remote_address = "172.30.1.41:228", + username = "gm", + multiplexing = "None", + }, +} +``` + +다른 환경에서 사용할 때는 주소와 사용자명을 바꾸거나 해당 항목을 제거합니다. 접속 정보가 +포함되어 있으므로 저장소 공개 범위를 변경하기 전에 내용을 확인해야 합니다. + +Unix mux 세션을 사용하려면 먼저 서버를 실행합니다. + +```bash +wezterm-mux-server --daemonize +``` + +## 사용자 설정 + +자주 실행하는 명령은 `config.launch_menu`에 추가합니다. + +```lua +config.launch_menu = { + { label = "Local bash", args = { "bash", "-l" } }, + { label = "htop", args = { "htop" } }, +} +``` + +WebGPU에서 문제가 생기면 다음 값을 `OpenGL` 또는 `Software`로 변경합니다. + +```lua +config.front_end = "WebGpu" +``` + +새 탭과 분할 패인이 현재 작업 디렉터리를 이어받게 하려면 사용하는 셸에 WezTerm shell +integration을 설정해야 합니다.