Lazygit

Lazygit is a TUI for Git. It makes complex operations (interactive rebase, partial staging) accessible via intuitive keyboard shortcuts.

When to Use

• Interactive Terminal Git UI: Fast, keyboard-centric interface for staging, committing, branching, and rebasing.
• Interactive Rebase & Cherry-Picking: Squashing, rewording, dropping, and reordering commits visually.
• Partial Line-by-Line Staging: Staging specific lines or code hunks within modified files via keybindings.
• Git Worktree & Submodule Management: Switching worktrees and managing submodules without memorizing flags.

Quick Start

# Launch lazygit inside any Git repository
lazygit

# Key Navigation:
# 1, 2, 3, 4, 5: Jump between Files, Branches, Commits, Stash panels
# Space: Stage/unstage selected file or hunk
# c: Commit staged changes
# P: Push to upstream
# p: Pull from upstream
# r: Interactive rebase on selected commit

Core Concepts

Core Keybindings & Panel Navigation

Navigating git repository state with single keystrokes:

• 1 through 5: Jump between panels (1: Status, 2: Files, 3: Branches, 4: Commits, 5: Stash).
• Space: Stage/unstage selected file or line.
• a: Stage all modified files.
• c: Open commit message prompt.
• P: Push to remote branch (p: Pull from remote).
• b: Create or checkout branch.
• z: Undo last Git action (uses Git reflog).

Interactive Rebase & Commit Squashing

Streamlining commit histories visually:

1. Press 4 to navigate to the Commits panel.
2. Highlight the base commit before your branch changes.
3. Press i to start an interactive rebase.
4. Highlight commits to modify:
   • s: Squash into previous commit.
   • r: Reword commit message.
   • d: Drop commit entirely.
   • e: Edit commit contents.
5. Press m to open merge / rebase options.

Custom Commands Configuration (config.yml)

Adding customized workflows to Lazygit:

# ~/.config/lazygit/config.yml
gui:
  theme:
    selectedLineBgColor:
      - reverse
  nerdFontsVersion: "3"

customCommands:
  - key: "P"
    command: "git push --force-with-lease origin {{.SelectedLocalBranch.Name}}"
    context: "localBranches"
    description: "Force push with lease safely"
    prompts:
      - type: "confirm"
        title: "Force Push"
        body: "Are you sure you want to force push with lease?"

Common Patterns

Custom Lazygit Commands

Problem: Need one-key git workflow actions (e.g. git standup, prune remote branches).
Solution: Define custom keybindings in ~/.config/lazygit/config.yml.

# ~/.config/lazygit/config.yml
customCommands:
  - key: "P"
    command: "git remote prune origin"
    context: "remotes"
    loadingText: "Pruning stale branches..."
  - key: "b"
    command: 'git branch --merged | grep -v "\*" | xargs -n 1 git branch -d'
    context: "branches"
    prompts:
      - type: "confirm"
        title: "Delete Merged Branches"
        body: "Are you sure you want to delete all merged local branches?"

Best Practices

Do:

• Use v in the diff panel to enter line-by-line staging mode for atomic commits.
• Use git push --force-with-lease rather than raw --force when pushing rebased feature branches.
• Press z in Lazygit to safely undo accidental rebases or commits using the reflog.
• Configure Nerd Fonts support in config.yml for clean file and branch iconography.

Don't:

• Perform interactive rebases on shared public branches (main, production).
• Stage files without reviewing the visual diff panel on the right.
• Leave abandoned rebases in progress; abort with m -> Abort rebase.

Troubleshooting

| Error | Cause | Solution | | :----------------------------------- | :------------------------------------------------------------ | :------------------------------------------------------------------------------------------ | | lazygit: command not found | Binary not installed in system PATH. | Install via brew install lazygit or Linux package manager. | | Rebase conflict screen in Lazygit | Interactive rebase paused due to merge conflict. | Resolve conflicting files, stage with Space, and press m to choose "Continue rebase". | | Cannot push: credentials not found | Git credential helper not configured in terminal environment. | Configure credential cache: git config --global credential.helper osxkeychain (or store). |

References

• Lazygit GitHub