harivansh-afk/forge.nvim
1
0
Fork 0
mirror of https://github.com/harivansh-afk/forge.nvim.git synced 2026-04-15 03:00:46 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
forge.nvim/doc/forge.nvim.txt
Barrett Ruth 25509a48ac
more tweaks
2026-03-27 18:17:12 -04:00

230 lines
9.1 KiB
Text
Raw Blame History

*forge.nvim.txt* Forge-agnostic git workflow for Neovim
Author: Barrett Ruth <br.barrettruth@gmail.com> License: MIT
==============================================================================
INTRODUCTION *forge.nvim*
forge.nvim provides PR, issue, and CI workflows across GitHub, GitLab, and
Codeberg from inside Neovim. It detects the forge from your git remote and
delegates to the appropriate CLI (`gh`, `glab`, or `tea`).
Features: ~
- Forge detection from git remote URL
- PR lifecycle (list, create, checkout, review, merge, approve, draft toggle)
- Issue management (list, browse, close/reopen)
- CI/CD run viewing, log streaming, status filtering
- PR compose buffer with diff stat and template discovery
- Code review via |diffs.nvim| with unified/split toggle
- Commit and branch browsing with forge permalinks
- Worktree creation from PRs
- fzf-lua pickers with contextual keybinds
==============================================================================
CONTENTS *forge-contents*
1. Introduction ............................................... |forge.nvim|
2. Requirements ....................................... |forge-requirements|
3. Setup ..................................................... |forge-setup|
4. Configuration ............................................ |forge-config|
5. Forge Picker ............................................ |forge-picker|
6. Pull Requests ................................................. |forge-pr|
7. Issues .................................................. |forge-issues|
8. CI/CD ...................................................... |forge-ci|
9. Commits ............................................... |forge-commits|
10. Branches .............................................. |forge-branches|
11. Review ................................................ |forge-review|
12. Compose Buffer ........................................ |forge-compose|
13. Highlight Groups .................................... |forge-highlights|
14. Health Check ............................................ |forge-health|
==============================================================================
REQUIREMENTS *forge-requirements*
- Neovim 0.10.0+
- fzf-lua (required)
- One or more forge CLIs:
- `gh` for GitHub
- `glab` for GitLab
- `tea` for Codeberg/Gitea/Forgejo
- vim-fugitive (optional, for fugitive keymaps)
- diffs.nvim (optional, for review mode)
==============================================================================
SETUP *forge-setup*
Install with lazy.nvim: >lua
{
'barrettruth/forge.nvim',
keys = {
{ '<c-g>', mode = { 'n', 'v' } },
},
}
<
Run `:checkhealth forge` to verify CLIs and dependencies.
==============================================================================
CONFIGURATION *forge-config*
Configuration is done via `vim.g.forge`: >lua
vim.g.forge = {
ci = { lines = 10000 },
}
<
*forge-config-ci-lines*
ci.lines ~
Number of log lines to fetch for CI runs. Default: `10000`.
==============================================================================
FORGE PICKER *forge-picker*
*<c-g>*
Press `<c-g>` in normal or visual mode to open the main forge picker. The
picker adapts based on the detected forge and current buffer state.
Available entries: ~
- Pull Requests / Merge Requests
- Issues
- CI / Pipelines
- Browse Remote
- Open File (current file on remote)
- Yank Commit URL / Yank Branch URL
- Commits
- Branches
- Worktrees
==============================================================================
PULL REQUESTS *forge-pr*
The PR picker lists open PRs by default. Toggle state with `<ctrl-o>` to
cycle through open/closed/all.
PR picker keybinds: ~
`<enter>` Checkout PR branch
`<ctrl-d>` Review diff (requires diffs.nvim)
`<ctrl-w>` Create worktree from PR
`<ctrl-t>` View checks/CI status
`<ctrl-x>` Open in browser
`<ctrl-e>` Manage (merge, approve, close, draft toggle)
`<ctrl-a>` Create new PR
`<ctrl-o>` Toggle state filter (open/closed/all)
`<ctrl-r>` Refresh list
PR management actions: ~
Approve, Merge (per available method), Close/Reopen, Draft toggle.
==============================================================================
ISSUES *forge-issues*
Issue picker keybinds: ~
`<enter>` Open in browser
`<ctrl-s>` Close/reopen issue
`<ctrl-o>` Toggle state filter
`<ctrl-r>` Refresh list
==============================================================================
CI/CD *forge-ci*
CI picker shows workflow runs for the current branch.
CI picker keybinds: ~
`<enter>` View logs (tail for in-progress, full for completed)
`<ctrl-x>` Open in browser
`<ctrl-r>` Refresh
Checks picker (from PR): ~
`<enter>` View check logs
`<ctrl-x>` Open in browser
`<ctrl-f>` Filter to failed
`<ctrl-p>` Filter to passed
`<ctrl-n>` Filter to running
`<ctrl-a>` Show all
==============================================================================
COMMITS *forge-commits*
Commit picker keybinds: ~
`<enter>` Checkout commit (detached HEAD)
`<ctrl-d>` Review diff
`<ctrl-x>` Open in browser (requires forge)
`<ctrl-y>` Yank commit hash
==============================================================================
BRANCHES *forge-branches*
Branch picker keybinds: ~
`<ctrl-d>` Review diff against branch
`<ctrl-x>` Open branch on remote (requires forge)
==============================================================================
REVIEW *forge-review*
Review mode requires diffs.nvim. Enter review via `<ctrl-d>` on a PR or
commit.
Review keybinds: ~
`s` Toggle unified/split view
`]q` / `[q` Next/previous quickfix entry (file navigation)
`]l` / `[l` Next/previous loclist entry
Review mode ends automatically when the review buffer is wiped.
==============================================================================
COMPOSE BUFFER *forge-compose*
Creating a PR opens a compose buffer (`forge://pr/new`) with:
- Line 1: PR title (pre-filled from commit subject or branch name)
- Line 3+: PR body (pre-filled from commit body or PR template)
- HTML comment block: metadata (branch info, draft, reviewers, diff stat)
The compose buffer is `filetype=markdown` with `buftype=acwrite`. Write the
buffer (`:w`) to push and create the PR. An empty title or body aborts.
Metadata fields (editable in the comment block): ~
`Draft:` Set to `yes` or `true` to create as draft
`Reviewers:` Comma-separated list of reviewer usernames
Template discovery: ~
forge.nvim searches for PR templates in the repository:
- `.github/pull_request_template.md`
- `.github/PULL_REQUEST_TEMPLATE/` (single file auto-selected, multiple
prompts for choice)
- GitLab/Codeberg equivalents
Fugitive keymaps: ~
From a fugitive buffer, the following keymaps are available:
`cpr` Create PR
`cpd` Create draft PR
`cpf` Create PR instantly (skip compose buffer)
`cpw` Create PR via web browser
==============================================================================
HIGHLIGHT GROUPS *forge-highlights*
The compose buffer uses the following highlight groups:
`ForgeComposeComment` Entire comment block Links to `Comment`
`ForgeComposeBranch` Branch names Links to `Special`
`ForgeComposeForge` Forge name Links to `Type`
`ForgeComposeDraft` Draft status value Links to `DiagnosticWarn`
`ForgeComposeFile` File paths in diff stat Links to `Directory`
`ForgeComposeAdded` Addition indicators (+) Links to `Added`
`ForgeComposeRemoved` Deletion indicators (-) Links to `Removed`
All groups are defined with `default = true` so colorschemes can override them.
==============================================================================
HEALTH CHECK *forge-health*
Run `:checkhealth forge` to verify:
- git is available
- Forge CLIs (`gh`, `glab`, `tea`) and their status
- fzf-lua is installed
- diffs.nvim is available (for review mode)
- vim-fugitive is available (for fugitive keymaps)
==============================================================================
vim:tw=78:ts=8:ft=help:norl:
Reference in a new issue View git blame Copy permalink