Improved flow
This commit is contained in:
Morten Olsen
509
docs/guides/git-workflow.md
Normal file
509
docs/guides/git-workflow.md
Normal file
@@ -0,0 +1,509 @@
|
||||
# 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`.
|
||||
Reference in New Issue
Block a user