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):

   ```bash
   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):

```bash
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`.