more tweaks

2026-04-15 06:04:41 +00:00 · 2026-03-27 18:17:12 -04:00 · 2026-03-27 18:17:12 -04:00 · 25509a48ac
commit 25509a48ac
parent e31b2777f9
7 changed files with 522 additions and 0 deletions
--- a/doc/forge.nvim.txt
+++ b/doc/forge.nvim.txt
@ -0,0 +1,230 @@
+*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: