Belajar Zellij - Custom Keybindings & Keybinding Conflicts

#Pendahuluan

Selamat datang kembali di series Belajar Zellij! Kalian sudah melewati delapan episode: prasyarat dan setup, sejarah, arsitektur client-server, lifecycle session dan pane, keybinding dan mode system, pane management lanjutan, scrollback dan search, floating panes, dan pada episode 8 kalian berkenalan dengan struktur lengkap config.kdl. Sekarang tibalah waktunya membuat Zellij benar-benar milik kalian: episode 9 ini mengupas tuntas custom keybinding dan konflik yang menyertainya.

Ada enam hal yang akan kalian kuasai di episode ini: (1) sintaks bind dan unbind per mode di dalam block keybinds, (2) clear-defaults untuk membangun keybinding dari nol, (3) multi-action keybind dan multiple modifier, (4) stacked resize, (5) cara mendiagnosis dan menyelesaikan konflik dengan shell serta editor, dan (6) strategi remap yang aman dan berkelanjutan. Semua contoh di bawah merujuk pada Zellij 0.44.x, jadi pastikan versi kalian tidak tertinggal jauh.

Mengapa episode ini penting? Default keybinding Zellij dirancang untuk mayoritas pengguna, tetapi mayoritas bukan berarti kalian. Setiap developer punya editor favorit, kebiasaan, dan workflow yang sudah mengakar. Ketika shortcut Zellij bertabrakan dengan vim, neovim, atau shortcut shell, yang terjadi bukan akhir dunia — melainkan persoalan kolaborasi antara dua aplikasi yang sama-sama haus keyboard. Memahami bagaimana Zellij mengikat, melepas, dan menimpa keybinding adalah keterampilan yang membedakan pemakai biasa dari pemakai power. Mari mulai.

#Anatomi Keybinding di config.kdl

Semua keybinding hidup di dalam block keybinds pada config.kdl. Bedanya dengan prefix key ala tmux: Zellij memakai mode. Setiap mode punya set keybinding sendiri, dan hint-nya selalu tampil di bagian bawah layar. Berikut mode utama yang sudah kalian kenal dari episode 4:

Sintaks dasarnya sederhana: node mode di dalam keybinds, lalu instruksi bind dengan satu atau lebih key, diikuti block berisi satu atau lebih aksi. KDL memakai string dengan double quote, dan aksi diakhiri titik koma.

keybinds {
    normal {
        bind "Ctrl p" { SwitchToMode "Pane"; }
    }
    pane {
        bind "h" "Left" { MoveFocus "Left"; }
        bind "n" { NewPane; SwitchToMode "Normal"; }
    }
    shared_except "locked" {
        bind "Alt n" { NewPane; }
    }
}

Perhatikan tiga hal pada contoh di atas. Pertama, satu bind bisa menampung banyak key: bind "h" "Left" membuat tombol h dan tombol panah kiri menjalankan aksi yang sama. Kedua, satu key bisa memicu banyak aksi: bind "n" { NewPane; SwitchToMode "Normal"; } membuat pane baru lalu langsung kembali ke mode Normal — pola paling umum dalam keybinding Zellij. Ketiga, block shared_except "locked" mendefinisikan keybinding yang berlaku di semua mode kecuali yang disebutkan, sehingga shortcut seperti Alt n bekerja di mana pun kalian berada.

#clear-defaults dan Strategi Membangun dari Nol

Terkadang meng-override per-key tidak cukup. Kalian mungkin ingin memulai dari halaman kosong dan mendefinisikan semuanya sendiri. Zellij menyediakan dua alat: unbind untuk melepas key tertentu, dan atribut clear-defaults=true untuk menghapus seluruh default dalam satu node.

keybinds {
    unbind "Ctrl g"
    normal {
        unbind "Ctrl p" "Ctrl t"
    }
    pane clear-defaults=true {
        bind "h" "Left" { MoveFocus "Left"; }
        bind "l" "Right" { MoveFocus "Right"; }
        bind "j" "Down" { MoveFocus "Down"; }
    }
}

Ada satu hal yang perlu kalian luruskan sejak awal: tidak ada keyword unbind-all di Zellij. Untuk menghapus semua default sekaligus, gunakan keybinds clear-defaults=true pada node keybinds itu sendiri. Perbedaannya dengan menaruh atribut yang sama pada satu mode cukup penting:

Saat memakai clear-defaults=true secara global, kalian bertanggung jawab mendefinisikan ulang jembatan antar mode — misalnya cara masuk mode Pane (Ctrl p), cara kembali ke mode Normal (Esc/Enter), dan kunci Ctrl g untuk Locked. Jika tidak, UI akan terasa "terkunci" karena tidak ada jalan untuk berpindah mode. Ini bukan bug; ini konsekuensi dari meniadakan default.

#Multi-Action Keybind dan Multiple Modifier (0.43)

Zellij sudah lama mendukung banyak aksi dalam satu keybind — misalnya bind "n" { NewPane; SwitchToMode "Normal"; } — tetapi sejak versi 0.43 dukungan ini diperluas secara signifikan. Pertama, aksi NewPane kini menerima argumen "Stacked" sehingga satu keybind bisa langsung membuka pane bertumpuk di atas pane yang sedang difokuskan. Ini persis yang menggerakkan default baru Ctrl p + s.

keybinds {
    pane {
        bind "s" { NewPane "Stacked"; SwitchToMode "Normal"; }
        bind "Alt r" "Ctrl Alt r" { NewPane "Right"; SwitchToMode "Normal"; }
    }
}

Kedua, 0.43 menambahkan dukungan multiple modifier. Sebelumnya kalian terbatas pada satu modifier (misalnya Alt r); sekarang kombinasi seperti Ctrl Alt r atau bahkan Ctrl Shift Home bisa diikat. Kemampuan ini berjalan di atas kitty keyboard protocol: Zellij meminta terminal host mengirimkan encoding key yang lebih kaya, sehingga tombol yang sebelumnya tidak bisa dibedakan kini dapat dipisah. Jika terminal kalian belum mendukung protokol ini, Zellij tetap bekerja normal karena protokolnya backward-compatible.

Satu peringatan kecil: dokumen resmi menyatakan bahwa aksi dalam satu keybind tidak memiliki jaminan urutan eksekusi. Untuk keperluan praktis, aksi yang berurutan di baris yang sama hampir selalu dijalankan berurutan, tetapi kalian tidak boleh membangun logika yang bergantung pada jaminan itu. Jika benar-benar membutuhkan urutan ketat, jalankan via Run atau CLI action — topik yang akan kita gali di episode 13.

#Stacked Resize (0.42)

Fitur yang sangat berpengaruh untuk pengalaman resize datang dari versi 0.42: stacked resize. Sebelumnya, resize pane dengan Alt + +/- hanya menggeser batas antar pane dan berhenti ketika bertabrakan. Mulai 0.42, algoritma ini diganti: saat kalian menekan Alt +, Zellij berusaha membesarkan pane sebesar 30% layar; jika tidak memungkinkan di arah mana pun, pane akan menumpuk dengan tetangganya — title pane lain tetap terlihat sebagai tab kecil di bawahnya, sehingga kalian bisa bernavigasi ke sana dengan keyboard atau mouse. Menekan Alt - akan memecah pane keluar dari tumpukan, dan ukuran sebelumnya diingat seperti undo chain.

stacked_resize false

Perilaku ini aktif secara default dan bisa dimatikan dengan stacked_resize false pada root config.kdl. Kombinasi stacked resize (0.42) dan keybinding stacked pane (0.43) membuat Zellij mampu menangani layar padat dengan anggun: pane yang menyempit otomatis menjadi tumpukan, dan pane baru yang dibuka di atas pane bertumpuk ikut bergabung ke dalam tumpukan. Untuk workflow dengan banyak pane kecil — monitoring, log, editor split — fitur ini terasa seperti fitur yang tidak pernah kalian sadari sangat dibutuhkan sampai mencobanya.

#Konflik dengan Shell dan Editor

Inilah jantung episode ini. Konflik terjadi ketika key yang dipakai Zellij juga dimakan oleh aplikasi di dalam pane. Contoh klasik: pemakai vim/neovim yang memakai Ctrl+o untuk lompat ke jumplist, padahal Ctrl+o adalah prefix mode Session Zellij. Contoh lain: Ctrl+w untuk menutup tab di editor, sementara di beberapa setup Zellij memakainya untuk hal lain. Sebelum kalian panik, pahami dulu kebijakan forwarding key Zellij yang berubah di 0.41: tombol yang tidak terikat akan diteruskan verbatim ke terminal selama mode aktif adalah locked atau default_mode (secara default normal). Di mode lain, tombol hanya berefek jika memang terikat. Artinya, di mode Normal, Ctrl+o di vim sebenarnya tidak langsung dimakan Zellij — masalah muncul ketika kalian berpindah ke mode lain, atau ketika kebijakan preset tidak cocok dengan kebiasaan kalian.

Zellij menawarkan beberapa lapis solusi untuk konflik ini:

Preset Unlock-First (non-colliding) yang diperkenalkan di 0.41 adalah solusi menyeluruh: Zellij mulai dalam keadaan terkunci, dan kalian menekan Ctrl+g terlebih dahulu untuk "membuka" antarmuka sebelum mengakses mode. Karena semua mode diakses setelah unlock, hampir tidak ada tabrakan dengan aplikasi di dalam pane. Untuk kalian yang menginginkan kontrol manual, dua pola remap berikut sering menjadi pilihan pemakai vim:

keybinds {
    unbind "Ctrl o"
    shared_except "session" "locked" {
        bind "Ctrl Space" { SwitchToMode "Session"; }
    }
}

keybinds {
    session {
        unbind "Ctrl o"
    }
    shared_except "session" "locked" {
        bind "Alt o" { SwitchToMode "Session"; }
    }
}

Opsi pertama membebaskan Ctrl+o sepenuhnya untuk vim, dengan konsekuensi cara kembali dari mode Session bergeser ke Esc/Enter. Opsi kedua memindahkan leader ke Alt+o, yang lebih aman karena Alt jarang dipakai editor. Pilih salah satu, lalu sesuaikan dengan editor kalian. Untuk kasus AltGr di keyboard non-US yang bermasalah di Windows, matikan dukungan kitty keyboard protocol dengan support_kitty_keyboard_protocol false pada config — solusi yang sudah terbukti menolong banyak pengguna.

Jangan lupa jalan keluar darurat: mode Locked (Ctrl+g) dan aksi Write yang mengirim raw key ke pane. Ketika kalian berada dalam mode tertentu dan ingin sebuah kombinasi diteruskan apa adanya ke aplikasi, Write — misalnya Write 27 111 untuk mengirim Alt+o — adalah cara yang eksplisit dan dapat diprediksi. Pola ini sangat berguna untuk nested Zellij, yang akan dibahas lebih dalam di episode 21.

#Strategi Remap yang Tenang

Menutup episode ini, mari rangkum strategi remap yang sebaiknya kalian terapkan agar tidak berujung pada config yang kacau. Prinsip pertama: mulai dari default, lalu sunting yang perlu. Default Zellij sudah diuji oleh ribuan pengguna; membangun dari nol dengan clear-defaults=true hanya masuk akal jika kalian punya alasan kuat dan siap memeliharanya. Prinsip kedua: jangan mengubah prefix mode tanpa menghitung efeknya — prefix seperti Ctrl p juga dipakai sebagai jalan kembali dari mode Pane, sehingga mengubahnya berarti mengubah dua arah sekaligus.

Prinsip ketiga: konsisten dengan modifier. Jika kalian memutuskan aksi cepat memakai Alt, jangan campur dengan Ctrl Alt di tengah jalan. Kekuatan multiple modifier justru lahir dari keteraturan. Prinsip keempat: dokumentasikan via dotfiles. Simpan ~/.config/zellij/ di repo dotfiles seperti yang akan kita bahas di episode 27, sehingga setiap perubahan keybinding tercatat dalam riwayat git dan mudah disinkronkan ke mesin lain. Terakhir, uji di sesi nyata. Konflik paling berbahaya bukan yang tampak di config, melainkan yang baru terasa setelah tiga puluh menit bekerja — jadi biasakan mencatat tombol yang terasa "ditelan" oleh Zellij dan selesaikan satu per satu.

#Kesalahan Umum (Common Pitfalls)

1. clear-defaults=true global tanpa definisi ulang mode switch. UI terasa terkunci karena tidak ada jalan masuk ke mode Pane/Tab, tidak ada Esc/Enter untuk kembali ke Normal, dan tidak ada Ctrl q untuk quit. Solusi: selalu sertakan binding minimum untuk berpindah mode saat memakai clear-defaults=true.
2. Unbind/remap hanya di satu mode padahal key tersebut bersifat shared_except. Konflik tetap tersisa di mode lain. Solusi: cek block shared_except dan unbind di level keybinds jika ingin melepas key di semua mode.
3. Mencari keyword unbind-all yang tidak ada. Untuk menghapus semua default, gunakan atribut clear-defaults=true pada node keybinds; keyword seperti itu tidak tersedia di Zellij.
4. Menaruh aksi di mode yang salah. Misalnya NewPane di mode Normal — aksi tidak akan pernah terpicu karena mode Normal meneruskan tombol ke shell. Solusi: pelajari tabel mode, dan tempatkan aksi di mode yang memang memilikinya.
5. Mengandalkan urutan aksi dalam satu keybind. Aksi dalam satu bind tidak dijamin berurutan. Jika alur harus presisi (buka pane, ganti nama, dll.), gunakan CLI action atau Run yang dibahas di episode 13.

#Penutup

Di episode 9 ini kalian telah menguasai anatomi keybinding Zellij: bind dan unbind per mode, block shared_except untuk shortcut lintas mode, clear-defaults=true sebagai pengganti "unbind-all" yang tidak ada, multi-action keybind dengan multiple modifier dari 0.43, stacked resize dari 0.42, serta strategi bertingkat untuk menyelesaikan konflik dengan shell dan editor — mulai dari preset non-colliding, ganti leader key, sampai remap manual.

Poin yang harus kalian bawa:

• Keybinding Zellij hidup per mode, dan hint selalu tersedia di status-bar.
• clear-defaults=true menghapus default; wajib definisikan ulang jembatan antar mode.
• Multi-action keybind dan multiple modifier (Ctrl Alt) adalah solusi modern atas konflik key.
• Stacked resize mengubah cara pane menyempit: menumpuk alih-alih menindih.
• Solusi konflik berlapis: non-colliding preset, ganti leader, unbind, atau remap.

Sekarang kalian bisa menekan tombol sesuai keinginan. Di episode 10 berikutnya, kita akan mengatur ruangan — bukan tombol: Layouts KDL dan project workspaces, di mana kalian mendefinisikan pane, tab, ukuran, cwd, environment, dan command dalam satu file layout yang bisa dijalankan dengan zellij -l. Sampai jumpa di episode 10, dan selamat membangun keybinding yang terasa seperti milik kalian!