Make It Yours Without Making It Opaque

Customization in lazygit is a control problem: how can the interface become faster and more natural without hiding which repository state an action will change? This chapter focuses on the smallest useful adaptations—better findability, a deliberate keybinding, a configuration change, or a context-aware custom command—and then connects them to diff rendering and asynchronous feedback. The reader should leave able to improve a known workflow while preserving its selection, command, output, and verification boundaries.

The temptation is to configure everything at once. A large YAML file can change panel layout, colors, keybindings, editors, refresh behavior, Git options, and external tools, but more control can make the next action harder to predict. Lazygit's own design principles recognize this tension: simplicity favors sensible defaults, power favors support for complex flows, and the codebase itself places a cost on every new option. Customization is most reliable when it removes a specific obstacle instead of creating a second interface that only its author understands.

Find the right state before changing it

Findability is part of correctness. A branch list with dozens of names, a commit history with repeated subjects, or a file view containing both staged and unstaged work all create opportunities to act on the wrong object. Lazygit separates filtering from searching because the two modes serve different purposes. Filtering removes nonmatching entries from a view. Searching keeps the surrounding content and highlights matches, which is deliberate in the commits view because a matching commit is usually meaningful in relation to the commits before and after it.

The distinction changes how a user should read the result. Filtering the Files view to staged or unstaged entries narrows the set of files that can receive attention. Filtering commits by a path narrows the history to commits that changed that path. Searching commits, by contrast, preserves the neighboring graph so the user can understand where the matching commit sits. A short fuzzy query may find a useful item quickly, but fuzzy matching can also return irrelevant results, especially when the query is short. Substring matching is less permissive and can be easier to trust when the exact relationship matters.

Range selection extends the same concern from finding one object to finding a contiguous group. It can support several files or commits for actions that have defined range behavior, and it offers sticky and non-sticky interaction styles. The important question remains semantic: do these adjacent items form one action? A range is not a substitute for deciding what belongs together. It is a way to express that decision once it has been made.

Keybindings then reduce the cost of repeating a known action. Lazygit lets a binding be a printable key, a special key, a modified key, a list of alternatives, or an explicit disabled value. Built-in bindings and their descriptions appear in the help menu, and custom commands can appear there too. A user can therefore adapt the surface to an existing keyboard layout or disable an action that is too easy to trigger accidentally. But a key is only safe when its context is understood.