nvim/docs/guides/git-workflow.md

Git Workflow Guide

This guide covers the complete git workflow in Neovim, from making changes to creating pull requests.

Overview

Your config includes:

• Diffview: Side-by-side diffs, file history, merge resolution
• Git-blame: Inline blame annotations
• Gitsigns: Gutter signs, hunk staging
• Octo: GitHub PRs and issues in Neovim
• Lazygit: Full TUI git client (optional)

Daily Git Workflow

1. Check Status

See what's changed:

<leader>gd    Open diffview (all changes)

Or use gitsigns to see hunks in current file:

]h            Jump to next hunk
[h            Jump to previous hunk

2. Stage Changes

Stage Hunks (Gitsigns)

Gitsigns provides inline staging in the current buffer:

]h            Jump to next hunk
[h            Jump to previous hunk
<leader>ghs   Stage hunk under cursor (in normal or visual mode)
<leader>ghr   Reset hunk (undo changes)
<leader>ghS   Stage entire buffer
<leader>ghu   Undo stage hunk
<leader>ghp   Preview hunk inline

Note: The <leader>ghs command works in both normal and visual mode. In visual mode, it stages the selected lines.

Stage in Diffview

Important: To stage/unstage files in diffview, you need to open the main diffview (not file history):

1. Open diffview with <leader>gd (this shows the file panel on the left)
2. Focus the file panel (press <leader>e if needed)
3. Use these keys in the file panel:

-             Toggle stage/unstage file (under cursor)
S             Stage all files
U             Unstage all files
X             Revert file changes
<cr>          Open diff for selected file
<tab>         Toggle file panel

Note: If you see a telescope-like picker, you're in file history mode. Use <leader>gd (without arguments) to open the main diffview with staging capabilities.

3. Review Before Commit

<leader>gd    Open diffview

Navigate files in left panel, review diffs on right.

4. Commit

Close diffview first (<leader>gD), then:

:Git commit   Open commit message editor

Or use terminal/lazygit:

<leader>gg    Open lazygit (if installed)

Viewing History

File History

See all commits that changed current file:

<leader>gf    File history for current file

In history view:

• j/k - Navigate commits
• <cr> - View diff at that commit
• <tab> - Toggle file panel

Branch History

See all commits on current branch:

<leader>gF    Full branch history

Compare to Main

See what's different from main branch:

<leader>gm    Compare to origin/main
<leader>gM    Compare to origin/master

Git Blame

Toggle Inline Blame

<leader>gB    Toggle blame annotations

Shows author and commit info at end of each line.

Investigate a Commit

When blame is on:

<leader>go    Open commit in browser (GitHub)
<leader>gy    Copy commit URL

Working with PRs (Octo)

List PRs

<leader>gpl   List all PRs

Navigate and press <cr> to open.

Create PR

<leader>gpc   Create new PR

This opens a buffer to write PR title and description.

Checkout PR

<leader>gpo   Checkout a PR locally

Select from list of PRs.

Review PR

Start Review

<leader>grs   Start review

Add Comments

In PR file:

<leader>ca    Add comment at cursor

Submit Review

<leader>grc   Submit review

Choose: Approve, Comment, or Request Changes.

Other Review Actions

<leader>grr   Resume review (if interrupted)
<leader>grd   Discard review

Merge PR

<leader>gpm   Merge PR

View in Browser

<leader>gpb   Open PR in browser

Working with Issues (Octo)

List Issues

<leader>gil   List issues

Create Issue

<leader>gic   Create new issue

Open in Browser

<leader>gib   Open issue in browser

Merge Conflicts

Open Merge Tool

When you have conflicts:

:DiffviewOpen

Diffview detects conflicts and shows 3-way merge view.

Resolve Conflicts

In merge view:

• Left: Ours (current branch)
• Center: Result (what you're building)
• Right: Theirs (incoming changes)

Navigate conflicts:

]x            Next conflict
[x            Previous conflict

Choose resolution:

<leader>co    Choose ours
<leader>ct    Choose theirs
<leader>cb    Choose both
<leader>c0    Choose none

Complete Merge

After resolving all conflicts:

:DiffviewClose
:Git add .
:Git commit

Advanced Diffview

Custom Comparisons

Compare any refs:

:DiffviewOpen origin/main...HEAD
:DiffviewOpen HEAD~5
:DiffviewOpen branch1..branch2

Diffview Panel Keys

In the File Panel (left side when open with <leader>gd):

j/k           Navigate files
<cr>          Open diff for selected file
-             Toggle stage/unstage file
S             Stage all files
U             Unstage all files
X             Revert file changes
<tab>         Toggle file panel visibility
<leader>e     Focus file panel
<leader>b     Toggle file panel
R             Refresh file list
L             Show commit log
g?            Show help

In the Diff View (right side):

<tab>         Navigate to next file
<leader>e     Focus file panel
<leader>b     Toggle file panel
g?            Show help

Important: The staging keys (-, S, U) only work in the file panel, not in the diff view itself. Make sure you're focused on the left panel (press <leader>e to focus it).

Common Workflows

Feature Development

1. Create branch (terminal):

   git checkout -b feature/my-feature
   

2. Make changes, stage hunks:

   <leader>ghs   Stage hunk
   

3. Review all changes:

   <leader>gd    Open diffview
   

4. Commit (in terminal or lazygit)

5. Compare to main before PR:

   <leader>gm    Compare to main
   

6. Create PR:

   <leader>gpc   Create PR
   

Code Review

1. List PRs:

   <leader>gpl
   

2. Select and open PR

3. Start review:

   <leader>grs
   

4. Navigate files, add comments

5. Submit:

   <leader>grc
   

Investigating a Bug

1. Find when bug was introduced:

   <leader>gf    File history
   

2. Navigate commits to find the change

3. Check blame for context:

   <leader>gB    Toggle blame
   

4. Open commit in browser:

   <leader>go
   

Resolving Merge Conflicts

1. After git merge with conflicts:

   :DiffviewOpen
   

2. For each conflicting file:

   • Navigate to conflict
   • Choose resolution
   • Move to next

3. When done:

   :DiffviewClose
   git add . && git commit
   

Tips

Quick Hunk Preview

Without opening diffview, you can preview hunks inline:

<leader>ghp   Preview hunk inline (shows diff in floating window)

Understanding Diffview Modes

Diffview has different modes:

1. Main Diffview (<leader>gd): Shows file panel + diff view. Use this for staging/unstaging files.
2. File History (<leader>gf): Shows a picker to select commits. This is read-only.
3. Branch History (<leader>gF): Shows all commits on current branch. This is read-only.

For staging/unstaging, always use <leader>gd (main diffview).

Blame with Commit Message

The inline blame shows:

• Author
• Relative time
• Short commit message

Stashing

Use terminal or lazygit:

git stash
git stash pop

Interactive Rebase

Use terminal (not supported in Neovim):

git rebase -i HEAD~5

Troubleshooting

Octo Not Working

1. Ensure gh CLI is installed
2. Authenticate: gh auth login
3. Check :Octo commands are available

Diffview Slow

For large repos:

• Limit file count in view
• Use specific file paths

Gitsigns Not Showing

1. Verify file is in git repo
2. :Gitsigns debug_messages
3. Check file isn't ignored
4. Ensure lazyvim.plugins.extras.lang.git is enabled in lazyvim.json

Diffview Shows Telescope Picker Instead of File Panel

If <leader>gd shows a picker instead of the file panel:

1. Make sure you're using <leader>gd (not <leader>gf or <leader>gF)
2. <leader>gf opens file history (picker mode) - this is read-only
3. <leader>gd opens main diffview with file panel - use this for staging
4. If file panel isn't visible, press <tab> or <leader>b to toggle it
5. Press <leader>e to focus the file panel before using staging keys

Staging Keys Don't Work in Diffview

The staging keys (-, S, U) are built into diffview.nvim and should work by default. If they don't:

1. Make sure you're in the file panel (left side), not the diff view (right side)
2. Press <leader>e to focus the file panel first
3. Make sure you opened diffview with <leader>gd (not file history)
4. Check if there's a key conflict: run :checkhealth diffview or :Telescope keymaps and search for -
5. If - is mapped elsewhere, it might conflict - diffview keymaps are buffer-local, so conflicts are rare

Note: Diffview's keymaps are set automatically when the file panel is active. If they're not working, there might be a plugin loading issue. Try restarting Neovim or running :Lazy sync.