# lazygit.nvim: running LazyGit in a floating window from Neovim

> A small Lua plugin that wraps the LazyGit terminal UI in a floating window, with config path overrides, neovim-remote commit editing and Telescope support for submodule work.

**kdheepak/lazygit.nvim** — Plugin for calling lazygit from within neovim.

- Repository: https://github.com/kdheepak/lazygit.nvim
- Stars: 2,367 · Forks: 91
- Language: Lua
- License: MIT
- Published: 2026-10-07 · Updated: 2026-10-07 · Language: en
- Canonical page: https://hysenlabs.com/projects/kdheepak-lazygit-nvim

## What the plugin actually does

lazygit.nvim is a wrapper, and it is worth being clear about where the value sits, because LazyGit itself is where nearly all the behaviour lives. LazyGit is a terminal UI for Git: staging, unstaging, committing, rebasing, branching, resolving conflicts, viewing history. This plugin does not reimplement any of that.

What it adds is the integration. `:LazyGit` opens LazyGit in a floating window in the current working directory, so your editor layout survives instead of being replaced. That is the entire premise, and it is a good one, because LazyGit's own interface assumes it owns the terminal.

There are five commands, and the differences between them are the actual API:

```vim
nnoremap <silent> <leader>gg :LazyGit<CR>
```

`:LazyGit` uses the current working directory. `:LazyGitCurrentFile` starts in the project root of the file you have open, which is the one you want most of the time in a multi-project session. `:LazyGitConfig` opens LazyGit's own config file directly, loading the defaults if you have no config yet, so you can set custom commands without leaving Neovim. `:LazyGitFilter` opens project commits and `:LazyGitFilterCurrentFile` opens commits for the current buffer, both scoped rather than showing the whole log.

There is no releases list at all, which is the first thing to know about the project's maturity signal.

## Installation across four plugin managers

The README documents four installation routes, which says more about the Neovim plugin ecosystem's churn than about this plugin.

With lazy.nvim, the spec includes a `cmd` list so the plugin only loads when one of the commands runs, and the README recommends binding a key inside `keys` so the first invocation is not slow:

```lua
return {
    "kdheepak/lazygit.nvim",
    lazy = true,
    cmd = {
        "LazyGit",
        "LazyGitConfig",
        "LazyGitCurrentFile",
        "LazyGitFilter",
        "LazyGitFilterCurrentFile",
    },
    -- optional for floating window border decoration
    dependencies = {
        "nvim-lua/plenary.nvim",
    },
    keys = {
        { "<leader>lg", "<cmd>LazyGit<cr>", desc = "LazyGit" }
    }
}
```

The version comments are a small history of the ecosystem in themselves: nvim v0.7.2 for vim-plug and packer, nvim v0.8.0 for lazy.nvim, and nvim v0.12 or newer for the built-in package manager, which the README shows using `nvim.pack.add`.

If you are on anything older than the latest Neovim release, the README points at an `nvim-v0.4.3` branch. It also notes that integration with nvr works better on main, which is a fair trade to consider before pinning anything.

plenary.nvim is listed as optional and only for floating window border decoration. Everything else in the plugin works without it.

## The configuration is all window styling

There are seven global variables and they are all about how the float looks or where LazyGit finds its config. None of them change Git behaviour, which keeps the surface small.

```lua
vim.g.lazygit_floating_window_winblend = 0 -- transparency of floating window
vim.g.lazygit_floating_window_scaling_factor = 0.9 -- scaling factor for floating window
vim.g.lazygit_floating_window_border_chars = {'╭','─', '╮', '│', '╯','─', '╰', '│'} -- customize lazygit popup window border characters
vim.g.lazygit_floating_window_use_plenary = 0 -- use plenary.nvim to manage floating window if available
vim.g.lazygit_use_neovim_remote = 1 -- fallback to 0 if neovim-remote is not installed
```

The scaling factor of 0.9 is the setting you will change first, since a 0.9 float inside an already-small terminal leaves very little room for LazyGit's panes. The border characters are the second, and the default set is a rounded box drawn with box-drawing characters.

The config file override is worth knowing about because it lets you keep LazyGit settings next to your Neovim config instead of in a separate dotfile:

```lua
vim.g.lazygit_use_custom_config_file_path = 0 -- config file path is evaluated if this value is 1
vim.g.lazygit_config_file_path = '' -- custom config file path
-- OR
vim.g.lazygit_config_file_path = {} -- table of custom config file paths
```

The final variable is the one with a real use case. `lazygit_on_exit_callback` takes a function that runs when LazyGit exits, and the README gives the reason: refreshing UI elements after LazyGit has made changes. If you have a status line or a file-tree panel that shows Git state, that is how you make it update without manually reloading buffers.

## Getting Neovim back for commits and file edits

This is the section that turns a convenient wrapper into a proper setup, and there are two separate mechanisms.

The first is neovim-remote. With it installed and configured, pressing `C` inside LazyGit opens the commit editor inside your running Neovim instance instead of a detached one. The setup is three pieces: install `neovim-remote` with pip, alias nvim to `nvr` in your shell profile when `NVIM_LISTEN_ADDRESS` is set, and point `VISUAL` and `EDITOR` at the same alias. The README also adds a Vimscript guard so `$GIT_EDITOR` follows:

```bash
if [ -n "$NVIM_LISTEN_ADDRESS" ]; then
    alias nvim=nvr -cc split --remote-wait +'set bufhidden=wipe'
fi
```

The second needs no extra tooling at all. Neovim's own client and server flags let you reuse the current instance, which you enable with an alias:

```bash
# ~/.bashrc
alias vim='nvim --listen /tmp/nvim-server.pipe'
```

Then you tell LazyGit to use it, by setting an edit command template in its config:

```yml
os:
  editCommand: 'nvim'
  editCommandTemplate: '{{editor}} --server /tmp/nvim-server.pipe --remote-tab "$(pwd)/{{filename}}"'
```

With that in place, pressing `e` inside LazyGit opens the file in a new tab in the same Neovim you were already using. If you would rather LazyGit did not use neovim-remote, set `lazygit_use_neovim_remote` to 0.

## The Telescope helper solves a real submodule problem

The last feature in the README is the least obvious and the most specific, so it is worth reading closely.

The Telescope integration tracks every Git repository visited in one Neovim session. The README explains the motivation with a scenario: you have one or more submodules in a project and want to commit changes in both the submodules and the main repository.

The naive workflow is the problem. Open a file inside the submodule, open LazyGit, commit, then open a file in the main repository, change directory, open LazyGit again. Every switch costs you your place. The plugin's answer is to track the repositories you have visited and let you pick among them rather than navigating by hand.

That is a narrow feature aimed at a narrow problem, and it is also the feature most likely to be exactly what you need if you work on a monorepo with submodules. Worth noting that the README's explanation is cut off mid-sentence at the end, so the exact invocation is in the source rather than the documentation.

The rest of the tree is small and conventional: `ftplugin/`, `lua/`, `plugin/`, `tests/`, a `.stylua.toml` and a `.github/` directory. A `tests/` directory with no releases is a slightly unusual combination, and it suggests the project is maintained rather than abandoned. The last push was 2026-09-20, and the licence is MIT.

## How this compares with the alternatives

The README itself names the alternatives: nvim-toggleterm and vim-floaterm as ways to run a terminal command in a floating window without this plugin. Both are general-purpose, so you would configure the LazyGit command yourself. That is a fair trade for a general tool, and a poor one if you want the current-file variant and the on-exit hook.

Against Fugitive and similar Git plugins that work through Neovim's own Git bindings, the comparison is not really about features. Fugitive and its descendants expose Git as a set of buffer commands and statusline operators inside your editor. LazyGit is a full TUI application that owns a screen while it runs. One model is incremental and composable with everything else you do in the editor; the other is a distinct mode with its own keybindings.

Both are legitimate. The choice is about whether you want Git to be part of your editing surface or a separate application you dip into. Plenty of people hold both, using buffer-level Git for routine staging and a TUI for rebases and conflict resolution, and that is a reasonable arrangement.

What lazygit.nvim changes about that is small but real: the TUI now lives in a float you can dismiss back to, the commit editor and file edits can come back to your buffers, and the on-exit callback lets the rest of your config know something changed. Those three things are the plugin's actual contribution, and they are the reason it exists at 2,364 stars with only 91 forks.

## Conclusion

lazygit.nvim is doing one job and doing it in a way you can predict: open the LazyGit TUI in a floating window, keep your buffer arrangement intact, and hand the commit and edit actions back to Neovim. There are no releases to track and no version numbers to reason about, so the plugin is best read rather than pinned, and the 52 open issues against 2,364 stars suggest that is the norm. The two integrations worth setting up before anything else are neovim-remote for commits and nvim --listen for files, because without them LazyGit spawns its own editor instances and you lose the buffer you were working in. Set it up with lazy.nvim, bind one key, and if the float looks wrong start with the scaling factor and border characters, which are the two settings that actually get changed.

## FAQ

### What is lazygit.nvim used for?

It opens the LazyGit terminal Git interface in a floating window over your Neovim session, so your buffers and window layout survive while you stage, commit, rebase or resolve conflicts. The plugin adds the window handling and editor integration; the Git behaviour is LazyGit's.

### Is lazygit.nvim better than vim-fugitive?

They solve the same problem with different models. vim-fugitive and its successors expose Git through Neovim commands and statusline operators, composable with everything else in the editor. LazyGit is a full TUI that owns a screen while it runs. lazygit.nvim does not replace Fugitive so much as make the TUI a less disruptive detour, and plenty of people use both.

### How do I make LazyGit commit messages open in Neovim?

Install neovim-remote, alias nvim to `nvr` in your shell profile, and set `VISUAL` and `EDITOR` to that alias. Pressing `C` inside LazyGit then opens the commit editor in your running Neovim instance. Setting `lazygit_use_neovim_remote` to 0 turns this off.

### How do I make LazyGit open files in the same Neovim instance?

Start Neovim with a socket, usually through an alias like `vim='nvim --listen /tmp/nvim-server.pipe'`, then set `os.editCommandTemplate` in LazyGit's config to call the editor with `--server` and `--remote-tab`. Pressing `e` inside LazyGit then opens the file in a tab in the same instance.

### Which commands does lazygit.nvim provide?

Five: `:LazyGit` for the current directory, `:LazyGitCurrentFile` for the project root of the open file, `:LazyGitConfig` to edit LazyGit's own config, and `:LazyGitFilter` and `:LazyGitFilterCurrentFile` for project-wide and buffer-scoped commits.

## Sources

- [Issues](https://github.com/kdheepak/lazygit.nvim/issues)
- [kdheepak/lazygit.nvim on GitHub](https://github.com/kdheepak/lazygit.nvim)
- [License: MIT](https://github.com/kdheepak/lazygit.nvim/blob/main/LICENSE)
- [README](https://github.com/kdheepak/lazygit.nvim/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/kdheepak-lazygit-nvim