# 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: ``` 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 ghs Stage hunk under cursor (in normal or visual mode) ghr Reset hunk (undo changes) ghS Stage entire buffer ghu Undo stage hunk ghp Preview hunk inline ``` **Note**: The `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 `gd` (this shows the file panel on the left) 2. Focus the file panel (press `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 Open diff for selected file Toggle file panel ``` **Note**: If you see a telescope-like picker, you're in file history mode. Use `gd` (without arguments) to open the main diffview with staging capabilities. ### 3. Review Before Commit ``` gd Open diffview ``` Navigate files in left panel, review diffs on right. ### 4. Commit Close diffview first (`gD`), then: ``` :Git commit Open commit message editor ``` Or use terminal/lazygit: ``` gg Open lazygit (if installed) ``` ## Viewing History ### File History See all commits that changed current file: ``` gf File history for current file ``` In history view: - `j/k` - Navigate commits - `` - View diff at that commit - `` - Toggle file panel ### Branch History See all commits on current branch: ``` gF Full branch history ``` ### Compare to Main See what's different from main branch: ``` gm Compare to origin/main gM Compare to origin/master ``` ## Git Blame ### Toggle Inline Blame ``` gB Toggle blame annotations ``` Shows author and commit info at end of each line. ### Investigate a Commit When blame is on: ``` go Open commit in browser (GitHub) gy Copy commit URL ``` ## Working with PRs (Octo) ### List PRs ``` gpl List all PRs ``` Navigate and press `` to open. ### Create PR ``` gpc Create new PR ``` This opens a buffer to write PR title and description. ### Checkout PR ``` gpo Checkout a PR locally ``` Select from list of PRs. ### Review PR #### Start Review ``` grs Start review ``` #### Add Comments In PR file: ``` ca Add comment at cursor ``` #### Submit Review ``` grc Submit review ``` Choose: Approve, Comment, or Request Changes. #### Other Review Actions ``` grr Resume review (if interrupted) grd Discard review ``` ### Merge PR ``` gpm Merge PR ``` ### View in Browser ``` gpb Open PR in browser ``` ## Working with Issues (Octo) ### List Issues ``` gil List issues ``` ### Create Issue ``` gic Create new issue ``` ### Open in Browser ``` 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: ``` co Choose ours ct Choose theirs cb Choose both 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 `gd`): ``` j/k Navigate files Open diff for selected file - Toggle stage/unstage file S Stage all files U Unstage all files X Revert file changes Toggle file panel visibility e Focus file panel b Toggle file panel R Refresh file list L Show commit log g? Show help ``` **In the Diff View** (right side): ``` Navigate to next file e Focus file panel 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 `e` to focus it). ## Common Workflows ### Feature Development 1. Create branch (terminal): ```bash git checkout -b feature/my-feature ``` 2. Make changes, stage hunks: ``` ghs Stage hunk ``` 3. Review all changes: ``` gd Open diffview ``` 4. Commit (in terminal or lazygit) 5. Compare to main before PR: ``` gm Compare to main ``` 6. Create PR: ``` gpc Create PR ``` ### Code Review 1. List PRs: ``` gpl ``` 2. Select and open PR 3. Start review: ``` grs ``` 4. Navigate files, add comments 5. Submit: ``` grc ``` ### Investigating a Bug 1. Find when bug was introduced: ``` gf File history ``` 2. Navigate commits to find the change 3. Check blame for context: ``` gB Toggle blame ``` 4. Open commit in browser: ``` 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: ``` ghp Preview hunk inline (shows diff in floating window) ``` ### Understanding Diffview Modes Diffview has different modes: 1. **Main Diffview** (`gd`): Shows file panel + diff view. Use this for staging/unstaging files. 2. **File History** (`gf`): Shows a picker to select commits. This is read-only. 3. **Branch History** (`gF`): Shows all commits on current branch. This is read-only. For staging/unstaging, always use `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 `gd` shows a picker instead of the file panel: 1. Make sure you're using `gd` (not `gf` or `gF`) 2. `gf` opens file history (picker mode) - this is read-only 3. `gd` opens main diffview with file panel - use this for staging 4. If file panel isn't visible, press `` or `b` to toggle it 5. Press `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 `e` to focus the file panel first 3. Make sure you opened diffview with `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`.