Lazygit 键位完全指南：从 Keybindings_pl.md 拆解全局快捷键、分屏操作与自定义绑定原理

Lazygit 键位完全指南：从 Keybindings_pl.md 拆解全局快捷键、分屏操作与自定义绑定原理

【免费下载链接】lazygitsimple terminal UI for git commands项目地址: https://gitcode.com/GitHub_Trending/la/lazygit

Lazygit（simple terminal UI for git commands）通过一套分场景的快捷键体系驱动整个 TUI 界面。本文以仓库中波兰语键位文档 Keybindings_pl.md 为主体，完整继承其 20 余个快捷键分节与全部关键条目，并结合 pkg/config/keybinding.go、pkg/config/keynames.go 等源码，讲清每个键位背后的解析规则、可配置项以及自定义绑定的语法边界。读完本文，你可以熟练覆盖 lazygit 中从提交管理、暂存 staging 到 rebase 冲突处理的全部常用操作，并能在用户配置中安全地改写或禁用任意键位。

文档定位：一份自动生成的权威键位清单

Keybindings_pl.md 文件开头即声明：

This file is auto-generated. To update, make the changes in the pkg/i18n directory and then rungo generate ./...from the project root.

也就是说，所有快捷键文案的唯一事实源在 pkg/i18n 目录（英文原文维护于 pkg/i18n/english.go），各语言 JSON 是机器生成的（见 pkg/i18n/translations/README.md），而docs/keybindings/下的各语言 Markdown 由 pkg/cheatsheet/generator.go 驱动生成。这带来两个实用结论：

• 键位表与程序实际注册的行为严格一致，可直接当作操作手册使用，无需再去翻源码确认某个键的作用；
• 表格里个别条目仍是英文（如Select commits of current branch），属于翻译进度问题，含义以 Keybindings_en.md 为准。

文档按"上下文（context）"组织：同一按键在不同面板（commits、files、branches……）执行不同动作，这正是 lazygit 的context + controller架构在 UI 上的映射（见 pkg/gui/context 与 pkg/gui/controllers）。下面逐节继承原文档内容。

全局快捷键（Globalne skróty klawiszowe）

在任何面板都生效的键位，是最高频的一组。完整继承原文档表格：

其中z/Z的撤销能力依赖 reflog，可在仓库文档 docs/Undoing.md 中找到设计说明；B键触发的 fixup base commit 查找逻辑同样有专门设计文档 docs/Find_Base_Commit_For_Fixup_Design.md 级别的配套说明。

列表导航（Nawigacja panelu listy）

所有侧边列表（分支、远端分支、标签、stash 等）共享这套导航键：

范围选择（range select）配合 cherry-pick 的复制/粘贴（C/V）使用价值很高，详见 docs/Range_Select.md；/触发的是全文搜索提示框，行为说明见 docs/Searching.md。

提交面板（Commity）

这是全文档最长、也是日常使用最密集的一节。逐条继承如下：

fixup/squash 工作流的完整用法参见 docs/Fixup_Commits.md；B键"标记基准提交"的设计背景见 docs/Find_Base_Commit_For_Fixup_Design.md。

主面板：暂存视图（Panel główny, zatwierdzanie）

在 Files 面板选中文件按<enter>进入的主视图，键位随模式变化。暂存（staging）模式：

合并冲突解决模式（Panel główny, scalanie）则换用另一套键：<space>选择 hunk、b同时保留双方 hunk、<up>, k/<down>, j上下 hunk、<left>, h/<right>, l切换冲突文件、z撤销上一次冲突解决、e/o编辑器/默认应用打开、M冲突选项、<esc>回到文件面板。

自定义补丁构建模式（Główny panel, budowanie łatki）与暂存视图共享h/l/v/a/<ctrl+o>/o/e//的布局，差异在于<space>表示"在补丁中切换该行"、d表示"从该提交中移除所选行"（后台跑交互式 rebase，后续提交若改同一行会触发冲突）、<esc>退出补丁构建器。

文件面板（Pliki）

分支、远端、标签、Stash 等侧边面板

本地分支（Lokalne gałęzie）：<ctrl+o>复制分支名；<space>切换分支；n/N新分支/迁移提交到新分支；w新 worktree；o/O创建 PR/查看 PR 选项；G打开 PR；<ctrl+y>复制 PR URL；c按名切换（输入-可回到上一个分支）；-切换到上一个分支；F强制切换（丢弃本地改动）；d删除；rrebase 到所选分支；M合并所选分支到当前分支；ffast-forward；T新标签；s排序；greset；R重命名分支；u上游选项（设置/删除/重置到上游）；<ctrl+t>difftool；0聚焦主视图；<enter>查看提交；/过滤；i显示 git-flow 选项。

远端分支（Zdalne gałęzie）：<ctrl+o>复制分支名；<space>基于远端分支创建并切换本地跟踪分支；n/w新分支/新 worktree；M合并；rrebase；d删除远端分支；u设为上游；s排序；greset；<ctrl+t>difftool；<enter>查看提交；/过滤。

远端（Zdalne）：<enter>查看其分支；n新建远端；d删除远端（不影响本地跟踪分支）；e编辑名称/URL；ffetch；F添加 fork 远端（替换 origin URL 中的 owner，可选检出该远端分支）；/过滤。

标签（Tagi）：<ctrl+o>复制 tag 名；<space>切换为 detached HEAD；n新标签；w新 worktree；d删除（本地/远端选项）；P推送所选 tag（会提示选择远端）；greset；<ctrl+t>difftool；<enter>查看提交；/过滤。

Stash（Schowek）：<space>应用所选 stash 到工作区；gpop（应用并删除）；d删除条目；n从 stash 条目创建新分支（切到 stash 创建时的提交 → 建分支 → 作为额外提交应用 stash）；w新 worktree；r重命名 stash；<enter>查看文件；/过滤。

Worktree（Drzewa pracy）：n新建；<space>切换到所选 worktree；o在编辑器中打开；d删除（同时删除目录与.git内元数据）；/过滤。

Reflog（Dziennik reflog）与Sub-commity两个面板复用提交操作集：<space>切换为 detached HEAD、y复制属性、o浏览器打开、n/N建分支、w新 worktree、greset、C/V复制/粘贴 cherry-pick、<ctrl+r>重置到所选提交、<ctrl+t>difftool、*选择当前分支提交、<enter>查看提交/文件、/搜索。

子模块（Submoduły）：<ctrl+o>复制子模块名；<enter>进入子模块（<esc>返回父仓库）；d删除子模块及其目录；u更新；n新建；e更新 URL；i初始化（之后通常接u下载）；b批量操作选项；/过滤。

其他小面板：输入提示框（Input prompt）只有<enter>确认、<esc>关闭/取消；确认面板（Panel potwierdzenia）另加<ctrl+o>复制内容；状态栏（Status）提供e编辑配置文件、u检查更新、<enter>切换到最近仓库、a/A显示/循环所有分支日志、0聚焦主视图；提交信息面板（Podsumowanie commita）为<enter>确认、<esc>关闭；主视图默认模式（Panel główny, normalny）提供鼠标滚轮上下滚动、<tab>切换视图、<esc>回到侧边面板、/搜索。

自定义键位：语法、源码解析与校验规则

原文档所有键位都可以改写。官方语法参考是 docs/keybindings/Custom_Keybindings.md，而真正实现解析的是 pkg/config/keybinding.go 与 pkg/config/keynames.go。

键位值的书写形式

一个键位可以是：

• 单个可打印字符，如q、?、5。大写字母即 shift+字母，写A而不是<shift+a>；
• 尖括号包裹的特殊键名，如<enter>、<f1>、<up>；
• 带修饰键的组合，如<ctrl+c>、<ctrl+shift+up>；
• 字面量<disabled>，表示禁用该绑定；
• 以上任意值的列表，把多个键绑到同一动作：quit: [q, <ctrl+c>]。

特殊键名对照（摘自 Custom_Keybindings.md，与 pkg/config/keynames.go 中labelByKey表逐项对应）：<f1>–<f12>、<insert>、<delete>、<home>、<end>、<pgup>、<pgdown>、<up>、<down>、<left>、<right>、<tab>、<backtab>、<enter>、<esc>、<backspace>、<space>、<mouse wheel up>、<mouse wheel down>，均可再叠加修饰键（如<ctrl+up>、<alt+enter>）。

修饰键前缀支持长短两种写法且可混用、可乱序：ctrl+/c+、alt+/a+、shift+/s+、meta+/m+；分隔符可用+或-。因此<ctrl+shift+up>、<c+s+up>、<ctrl-shift-up>等价。<minus>与<plus>是-和+在带修饰键时的关键字形式（无修饰键时直接写-、+）。

源码中的解析与校验逻辑

配置层的Keybinding类型定义在 pkg/config/keybinding.go：

type Keybinding []string func (k *Keybinding) UnmarshalYAML(node *yaml.Node) error { var ss []string switch node.Kind { case yaml.ScalarNode: // 单键："q" var s string if err := node.Decode(&s); err != nil { return err } ss = []string{s} case yaml.SequenceNode: // 多键：[q, <ctrl+c>] if err := node.Decode(&ss); err != nil { return err } default: return fmt.Errorf("expected a string or a sequence of strings for keybinding, got %v", node.Tag) } // 丢弃空串与 <disabled>，客户端无需特判 *k = lo.Filter(ss, func(s string, _ int) bool { return s != "" && s != "<disabled>" }) return nil }

这段实现解释了三个行为：YAML 里既写字符串又写数组都能通过；<disabled>在反序列化阶段就被过滤掉，所以"禁用"等价于"空列表"；旧版*Alt*字段会经mergeLegacyAlt合并进主字段（同文件 L90-L92），老配置可以平滑升级。

真正把标签解析成可匹配按键的是 pkg/config/keynames.go 的KeyFromLabel，其中两处"看似合理但必须拒绝"的组合值得注意：

1. 裸 rune 上的单独 shift 非法：<shift+a>不会生效，因为终端会把 shift 折叠进字符本身——shift+a 到达程序时就是A。源码注释明确说明应写A（L174-L180）。
2. 大写 ASCII 字母不能带修饰键：<ctrl+A>、<alt+A>均非法，因为 ctrl 码不分大小写（ctrl+a 与 ctrl+A 发送同一字节），CSI-u 协议也以上报未 shift 码点加 shift 修饰的方式表达，应写<ctrl+shift+a>（L182-L190）。

运行时方向由LabelForKey（同文件 L50-L93）负责，把gocui.Key还原为<ctrl+shift+f1>这类人类可读标签，供?菜单显示；配置校验失败时GetValidatedKeyBindingKey会直接log.Fatalf并提示"这应当被用户配置校验捕获"（L200-L207），即非法键位会在启动阶段而非运行中途暴露。

终端兼容性的现实约束

Custom_Keybindings.md 特别指出：组合修饰键依赖较新的终端协议，并非所有终端都支持。文档列举的已知良好支持终端包括 Ghostty、kitty、WezTerm、foot、Konsole、Alacritty、iTerm2、Windows Terminal；macOS 自带的 Terminal.app 与 Git for Windows 的 MinTTY 不支持。在 tmux/screen 中，扩展键位除非多路复用器配置转发否则会被剥离，tmux 3.2+ 需要：

set -g extended-keys on set -as terminal-features 'xterm*:extkeys'

这一点解释了为什么原文档表格中的"（fn+up/shift+k）"这类替代标注存在——它们正是为不支持 CSI-u 协议的终端准备的降级方案。

把键位落到你的配置文件中

键位挂在用户配置的keybinding字段下，结构体见 pkg/config/user_config.go 的KeybindingConfig（字段注释同样指向 Custom_Keybindings.md 说明语法）。一个最小示例，覆盖本文出现过的三类典型改写：

keybinding: global: quit: [q, <ctrl+c>] # 多键绑定（原文默认即是 q 与 <ctrl+c>） refresh: R list: # 例如把范围选择改到别的键；写成 <disabled> 可禁用 toggleRangeSelect: v status: checkForUpdate: <disabled>

配合本文的键位表，推荐的自定义工作流是：在 lazygit 中按?打开键位菜单确认某个动作当前的绑定 → 对照上表找到对应context（global/list/commits/files/branches……即原文档的小节标题）→ 在配置文件中以keybinding.<context>.<action>路径修改，改完重启生效。由于Keybinding类型对单键与多键一视同仁，任何原文档表格中带逗号分隔的按键（如<pgup>, K, <ctrl+u>）在配置中都应写作列表形式[<pgup>, K, <ctrl+u>]。

小结

• Keybindings_pl.md 是一份由 i18n 文案自动生成的权威键位手册，覆盖全局、列表导航、提交、文件、主视图（staging/merge/patch-building）、分支、远端、标签、stash、worktree、reflog、子模块等全部上下文，与程序实际注册键位严格一致；
• 每个可改键位背后是 pkg/config/keybinding.go 的字符串/数组双形态解析 + pkg/config/keynames.go 的标签-按键互转，<shift+字母>、<ctrl+大写字母>这类组合在解析层被明确拒绝并有源码注释解释终端协议原因；
• 组合修饰键受终端协议限制，弱协议终端应依赖J/K、fn+方向键等替代键；tmux 用户需开启 extended-keys 转发；
• 深度工作流文档可按需继续查阅：Fixup_Commits.md、Range_Select.md、Undoing.md、docs/Config.md。

【免费下载链接】lazygitsimple terminal UI for git commands项目地址: https://gitcode.com/GitHub_Trending/la/lazygit