gh-nvm.txt

*gh.nvim* gh.nvim

Author:   Louis DeLosSantos <louis.delos@gmail.com>
Homepage: <https://github.com/ldelossa/gh.nvim>
License:  MIT license

             ██████╗ ██╗  ██╗   ███╗   ██╗██╗   ██╗██╗███╗   ███╗
            ██╔════╝ ██║  ██║   ████╗  ██║██║   ██║██║████╗ ████║
            ██║  ███╗███████║   ██╔██╗ ██║██║   ██║██║██╔████╔██║
            ██║   ██║██╔══██║   ██║╚██╗██║╚██╗ ██╔╝██║██║╚██╔╝██║ Powered by
            ╚██████╔╝██║  ██║██╗██║ ╚████║ ╚████╔╝ ██║██║ ╚═╝ ██║ litee.nvim
             ╚═════╝ ╚═╝  ╚═╝╚═╝╚═╝  ╚═══╝  ╚═══╝  ╚═╝╚═╝     ╚═╝
====================================================================================
CONTENTS                                                         *litee-contents*

  1     Intro.........................................|gh-intro|
  3     Usage And Features............................|gh-usage|
  4     Commands......................................|gh-commands|
  6     Config........................................|gh-config|
  7     Highlights....................................|gh-highlights|
  7     Debugging.....................................|gh-debugging|

====================================================================================
INTRODUCTION                                                              *gh-intro*

GH.nvim, initially, is a plugin for interactive code reviews which take place
on the GitHub platform. 

This plugin was created due to the repeat frustration of performing code reviews
of complex changes in the GitHub web UI. 

The mentioned frustration seemed to boil down to a few major drawbacks which GH.nvim
sets out to fix. These are:

1) Lack of context during code review
    When viewing a pull request in a large code base its very likely that you're
    not sure of the full context of the change. The patch may change the way a 
    function works, but you are not aware all the places this function may be 
    called. Its difficult to safely say that the patch is OK and approve it.

    To alleviate this, GH.nvim will make the pull request code locally available
    on your file system.

2) Lack of sufficient editor tools like LSP
    Because the pull request's code is made locally available all your LSP tools
    work as normal. 

    In my previous point, this means performing a LSP call to understand all the 
    usages of the editing function is now possible. 

3) Lack of automation when attempting to view the full context of a pull request.
    GH.nvim automates the process of making the pull request's code locally available.
    To do this, GH.nvim embeds a `git` CLI wrapper. 

    When a pull request is opened in GH.nvim the remote is added locally, the 
    branch is fetched, and the repo is checked out to the pull request's HEAD.

4) Inability to edit and run the code in the pull request.
    Because the pull request's code is made available locally, its completely 
    editable in your familiar `neovim` instance. 

    This works for both for writing reviews and responding to reviews of your
    pull request. 

    You can build up a diff while responding to review comments, stash them, 
    check out your branch, and rebase those changes into your PR and push again.
    Much handier then jumping back and forth between `neovim` and a browser.

    Additionally, since the code is local and checked out on your file system,
    you can now run any local development environments that may exist. The 
    environment will be running the pull request's code and you can perform sanity
    checks easily.

GH.nvim is a "commit-wise" review tool. This means you browse the changed files
by their commits. This will feel familiar to those who immediately click on the
"commits" tab on the GitHub UI to view the incremental changes of the pull request.

GH.nvim holds the opinion that this is the correct way to do a code review and 
and the TUI emphasizes this workflow.

====================================================================================
Usage And Features                                                        *gh-usage*

GH.nvim initially focuses on pull request code reviews. The plugin has been designed
to make the process of review coding seamless with `neovim` editing. The following 
walk through will give a overview of GH.nvim's features and how to use the.

Dependencies:
    GH.nvim relies on the `litee.nvim` framework for building its plugin surface.
    You must include this package for GH.nvim to work.
    https://github.com/ldelossa/litee.nvim

    Additionally, both the `git` and `gh` CLI tools are required for the plugin
    to interface with the git repository and the GitHub API respectively.
    For GitHub Enterprise, make sure to set the environment variable `GH_HOST`.
    https://git-scm.com/
    https://github.com/cli/cli

    It is not mandatory but *highly* recommended to use GH.nvim with either 
    fzf.lua or telescope. This is because GH.nvim uses `vim.ui.select` for most
    of its users inputs. By utilizing fzf.lua or telescope you can configure both
    to override `vim.ui.select` function and provide a fuzzy searcher over all 
    input selections GH.nvim creates. 

    I'm personally an fzf.lua user and you can make this work by adding the following
    line to your fzf.lua config:
        `lua vim.cmd("FzfLua register_ui_select")` 

    GH.nvim is best used with a patched font. Ideally, the patch font has codicons
    support, but icons will work fine with nerd font patches as well.

Code Review Environment:
    GH.nvim *will* modify the `git` repository at the root of the directory 
    `neovim` has been opened too. 

    These modifications include adding the pull request's remotes, checking out
    branches, removing the pull request remotes, and fetching remote content. 

    The suggested way to use `GH.nvim` would be to create a worktree of the target
    repository for code review purposes. If you are not familiar with worktrees,
    they are "linked" but separate repository directories. This allows you to make
    changes to branches without the potential for any issues on our main repository.

    An example using `neovim`'s repo on my system would look like this:

    ```
    $ cd ~/git/c/neovim
    $ git worktree add ../neovim-code-review
    $ cd ../neovim-code-review
    ```
    After the `cd` my host system is inside a git worktree, GH.nvim can modify 
    this repository's `git` state without effecting the original "main" repository.

    This is only a suggestion, GH.nvim will not perform any data loosing operations
    on the underlying repository, however just to be sure, especially while GH.nvim
    is in beta, its suggested to use the worktree approach.

    Additionally, you must be aware of how git will fetch a repository. 

    gh.nvim will use the git_protocol defined in your gh config.
    Run `gh config get git_protocol` to see the current protocol.

Configuration:
    A simplest possible configuration, using all the defaults, will look like 
    this:

    require('litee.lib').setup()
    require('litee.gh').setup()

    This will first configure the `litee.nvim` library and then configure GH.nvim.
    All defaults will be used. For further configuration information see `h: gh-configuration`

Opening a PR:
    After configuring GH.nvim you can open `neovim` to the base repository hosting
    the pull request you'd like to review, or create a review to. 

    The `GHOpenPR` command will open a `vim.ui.select` UI with the first 100 pull
    requests for selection. 

    On selection the main GH.nvim UI will load and present you with a `litee.nvim` 
    panel presenting the PR's details and a buffer with the PR meta data and issue
    comments will be presented. 

The Panel:
    The panel loaded will display some key information. At a high level you'll see
    several trees, outlined below are the ones of most importance. 

    Each section will be described with an example of the tree layout in the 
    panel using a test PR I created for this purpose.

    By default, if the node supports it, pressing the "d" key show a details
    popup with some information. This is useful for quickly displaying comments
    and commit messages.

    Details:
           #1 update readme with first update
            Details:
         ⎸     number:
         ⎸     author:
         ⎸     state:
         ⎸     repo:
         ⎸     base:
         ⎸     head:
         ⎸    labels:
         ⎸ ⎸     bug
         ⎸    assignees:
         ⎸ ⎸     ldelossa
    
        Details describes the general information of the pull request. 
        By hitting "return" on the very first item you'll always be brought
        back to the main pull request buffer. 

        At the main pull request buffer you can see any comments not associated
        with any file diffs, the title of the PR and the body. You can modify
        comments along with edit the title and body of the PR if you authored it.

    Commits:
            Commits:
         ⎸     f86c5d09
         ⎸     943cb016
         ⎸     d0b9c794
         ⎸     37d5f671
         ⎸     0e6ee395

        The commits section displays each commit of the pull request. By hitting
        "return" one one of the commits you'll be taken to a diff of the first
        file changed in the commit and a new panel will open outlining the files
        changed within a commit.

        This is the main way of reviewing code in GH.nvim, you'll move between
        commits and review the changes.

    Conversations:
            Conversations:
         ⎸    newfile:267
         ⎸    newfile:261
         ⎸ ⎸     comment by ldelossa
         ⎸ ⎸     reply by ldelossa
         ⎸ ⎸     reply by ldelossa
         ⎸ ⎸     reply by ldelossa

        The conversations section outlines all conversation threads associated
        with the pull request. 

        By hitting "return" on any of the comments in a thread you'll be brought
        to the diff view with the conversation present for viewing.

    There are other trees that will appear if the data is there, such as "requested reviewers"
    and "assignees". They are mostly informative.

The Diff View:
    
    The diff view presents patch changes between old and new files. A diff view
    can be used to view the changes of the pull request, review conversations on
    particular lines of a pull request, and create new conversations on particular
    lines of a pull request.

    The diff view will paint icons in the sign columns where comments can be 
    created. To create a comment ensure your mouse is on a line with the "+" mark
    and use the "GHCreateThread" command.

    When the cursor is on a line with with a comment, indicated by a sign in the 
    sign column, you may use the `GHToggleThread` command to open and close it. 
    If there are multiple comments on a line you may move to the next one with 
    the `GHNextThread` command.
    
Convo Buffers:
    
    Conversations happen in various "convo buffers". These buffers provide a way
    to write, edit, and remove comments for a particular diff line or for the 
    pr as a whole. 

    Convo buffers are only modifiable in the text region at the end of the file,
    once text is provided hitting `ctrl-s` will submit the text. 

    Use `ctrl-a` when the cursor is on a comment to open a menu with various
    actions you can perform on a comment.

Code Reviews:
    
    GH.nvim works just like the GitHub UI.

    When a code review has not been started all replies to threads or creations of threads 
    are issued outside of a review. 

    When a code review is started, all comments to threads or creation of threads occur as
    pending until you submit the review. You'll notice this in the panel, as new messages 
    you create are marked as pending.

    If you close GH.nvim and open the PR again without submitting your review, the review
    will automatically be entered. This is the same as GitHub's UI, you'll always be in the
    review until you explicitly submit or cancel the review.

    You can create a review with the `GHStartReview` command, submit it with the `GHSubmitReview` 
    command and cancel it with the `GHDeleteReview` command.

    Submitted code reviews show up in the panel as well. They are selectable, and when selected
    a new panel is opened which groups the conversation threads by the pull request review.

====================================================================================
Commands                                                               *gh-commands*


local commands = {
    -- use a vim.ui.select prompt to open one of the first 100 pull requests.
    {name = "GHOpenPR", callback=pr.open_pull, opts={nargs="?"}},
    -- use a vim.ui.select prompt to open one of the first 100 pull requests.
    {name = "GHOpenPR", callback = pr.open_pull, opts = {nargs="?"}},
    -- open the Pull Request panel in the side bar panel
    {name = "GHOpenToPR", callback = pr.open_to_pr, opts = {}},
    -- open the Pull Request panel in a pop out window
    {name = "GHPopOutPR", callback = pr.popout_to_pr, opts = {}},
    -- open the Commit panel in the side bar panel.
    {name = "GHOpenToCommit", callback = pr.open_to_pr_files, opts = {}},
    -- open the Commit panel in a pop out window
    {name = "GHPopOutCommit", callback = pr.popout_to_pr_files, opts = {}},
    -- collapse the node within the Pull Request panel
    {name = "GHCollapsePR", callback = pr.collapse_pr, opts = {}},
    -- expand the node within the Pull Request panel
    {name = "GHExpandPR", callback = pr.expand_pr, opts = {}},
    -- collapse the node within the Commit panel
    {name = "GHCollapseCommit", callback = pr.collapse_pr_commits, opts = {}},
    -- expand the node within the Commit panel
    {name = "GHExpandCommit", callback = pr.expand_pr_commits, opts = {}},
    -- collapse the node within the Review panel
    {name = "GHCollapseReview", callback = pr.collapse_pr_review, opts = {}},
    -- expand the node within the Review panel
    {name = "GHExpandReview", callback = pr.expand_pr_review, opts = {}},
    -- refresh all details of the PR
    {name = "GHRefreshPR", callback = pr_handlers.on_refresh, opts = {}},
    -- refresh just comments, useful to fresh convo buffers quicker.
    {name = "GHRefreshComments", callback = pr_handlers.refresh_comments, opts = {}},
    -- refresh any open issue buffers, if a PR is opened, this will be ran as part of "GHRefreshPR"
    {name = "GHRefreshIssues", callback = issues.on_refresh, opts = {}},
    -- refresh the notifications buffer if it is open.
    {name = "GHRefreshNotifications", callback = noti.on_refresh, opts = {}},
    -- start a code review
    {name = "GHStartReview", callback = pr.start_review, opts = {}},
    -- submit all pending comments in a code review
    {name = "GHSubmitReview", callback = pr.submit_review, opts = {}},
    -- delete the current code review
    {name = "GHDeleteReview", callback = pr.delete_review, opts = {}},
    -- a convenience function, immediately approve the pull request with an optional comment.
    {name = "GHApproveReview", callback = pr.immediately_approve_review, opts = {}},
    -- open the main Pull Request details convo buffer.
    {name = "GHPRDetails", callback = pr.open_pr_buffer, opts = {}},
    -- when cursor is on a commented line of a diff view, toggle the convo buffer.
    {name = "GHToggleThreads", callback = function() dv.toggle_threads(nil) end, opts = {}},
    -- when cursor is on a commented line of a diff view, move to the next convo buffer
    {name = "GHNextThread", callback = dv.next_thread, opts = {}},
    -- when cursor is on a line which can be commented in a diff view, create a comment
    {name = "GHCreateThread", callback = dv.create_comment, opts = {range=true}},
    -- toggle viewed state of the file being diffed
    {name = "GHToggleViewed", callback = dv.toggle_file_viewed, opts = {}},
    -- close a PR and cleanup any state associated with it (happens on tab and neovim close as well)
    {name = "GHClosePR", callback = pr.close_pull, opts = {}},
    -- close the Commit panel
    {name = "GHCloseCommit", callback = function() pr.close_pr_commits(nil) end, opts = {}},
    -- close the Review panel
    {name = "GHCloseReview", callback = function () pr.close_pr_review(nil) end, opts = {}},
    -- preview the issue or pull request number under the cursor
    {name = "GHPreviewIssue", callback = issues.preview_issue_under_cursor, opts = {}},
    -- Add a label to the currently opened pull request.
    {name = "GHAddLabel", callback = pr.add_label, opts = {}},
    -- Remove a label from the currently opened pull request.
    {name = "GHRemoveLabel", callback = pr.remove_label, opts = {}},
    -- If possible, open the node under the cursor in your web browser.
    {name = "GHViewWeb", callback =  pr.open_node_url, opts = {}},
    -- Open an issue, if a number is provided it will be opened directly, if not
    -- a vim.ui.select with all repo issues is opened for selection.
    {name = "GHOpenIssue", callback = issues.open_issue, opts = {nargs="?"}},
    -- Open a PR you've been requested to review.
    {name = "GHRequestedReview", callback = pr.open_pull_requested_review_user, opts = {}},
    -- Open a PR in the open state which you have reviewed.
    {name = "GHReviewed", callback = pr.open_pull_request_reviewed_by_user, opts = {}},
    -- Search the current repo's PR's utilizing GH search queries. 
    -- Searches are always constrained to the repository Neovim is opened to.
    -- See: https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests
    {name = "GHSearchPRs", callback = pr.search_pulls, opts = {}},
    -- Search the current repo's PR's utilizing GH search queries. 
    -- Searches are always constrained to the repository Neovim is opened to.
    -- See: https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests
    {name = "GHSearchIssues", callback = issues.search_issues, opts = {}},
    -- Open a UI displaying all unread notifications for the repo gh.nvim is opened
    -- to.
    {name = "GHNotifications", callback = noti.open_notifications, opts = {}},
    -- When config["debug_logging"] is set to true, this command will open a buffer
    -- holding all git and gh cli invocations and their outputs.
    {name = "GHOpenDebugBuffer", callback = debug.open_debug_buffer, opts = {}},
}

====================================================================================
Conf                                                                     *gh-config*

Below is the default configuration.

M.config = {
    -- deprecated, around for compatability for now.
    jump_mode   = "invoking",
    -- remap the arrow keys to resize any litee.nvim windows.
    map_resize_keys = false,
    -- do not map any keys inside any gh.nvim buffers.
    disable_keymaps = false,
    -- the icon set to use.
    icon_set = "default",
    -- any custom icons to use.
    icon_set_custom = nil,
    -- whether to register the @username and #issue_number omnifunc completion
    -- in buffers which start with .git/
    git_buffer_completion = true,
    -- background refresh timer interval in milliseconds. defaults to five
    -- minutes.
    refresh_interval = 300000,
    -- list of highlights to be used within the UI.
    highlights = {
        -- the following highlights will highlight threaded messages in conversation
        -- buffers. 
        -- you can alternate between two highlights if desired by setting these
        -- to different highlights.
        thread_separator = "GHThreadSep",
        thread_separator_alt = "GHThreadSepAlt"
    },
    -- log all git and gh cli actions to a buffer.
    -- the buffer can be opened with "GHOpenDebugBuffer" when this is set to true.
    debug_logging = false,
    -- defines keymaps in gh.nvim buffers.
    keymaps = {
        -- when inside a gh.nvim panel, this key will open a node if it has
        -- any futher functionality. for example, hitting <CR> on a commit node
        -- will open the commit's changed files in a new gh.nvim panel.
        open = "<CR>",
        -- when inside a gh.nvim panel, expand a collapsed node
        expand = "zo",
        -- when inside a gh.nvim panel, collpased and expanded node
        collapse = "zc",
        -- when cursor is over a "#1234" formatted issue or PR, open its details
        -- and comments in a new tab.
        goto_issue = "gd",
        -- show any details about a node, typically, this reveals commit messages
        -- and submitted review bodys.
        details = "d",
        -- inside a convo buffer, submit a comment
        submit_comment = "<C-s>",
        -- inside a convo buffer, when your cursor is ontop of a comment, open
        -- up a set of actions that can be performed.
        actions = "<C-a>",
        -- inside a thread convo buffer, resolve the thread.
        resolve_thread = "<C-r>",
        -- inside a gh.nvim panel, if possible, open the node's web URL in your
        -- browser. useful particularily for digging into external failed CI
        -- checks.
        goto_web = "gx",
        -- if selectable, select the object under the cursor for additional operations.
        select = "<leader>",
        -- if selectable, clear all selected items.
        clear_selection = "<leader><leader>",
        -- toggle unread items
        toggle_unread = "u"
    },
}

====================================================================================
Highlights                                                           *gh-highlights*

The following highlights are defined and can be declared by themers. If they
are not declared GH.nvim will set a default which is also listed below.

Highlight               Purpose                                 Default
*******************************************************************************

GHThreadSep             The fg and bg highlight used for a      Pmenu 
                        threaded message.

GHThreadSepAlt          Similar to above but can be used as     Pmenu
                        an alternating color between messages 
                        in a threaded message. For example in 
                        a threaded message with 3 messages the 
                        first will use the GHThreadSep highlight, 
                        second will use GHThreadSepAlt and third 
                        will use GHThreadSep.

====================================================================================
Debugging                                                             *gh-debugging*

It is possible to output all `gh` and `git` cli calls and their output into a 
debug buffer. 

To do this you must set the `debug_logging` field in your user config to `true`.
When this is enabled you can use the `GHOpenDebugBuffer` which will open a buffer
full of cli debug information in a new tab.

The format of a log message is:

[{level}] [{cli}] cmd: {command line} out:\n {returned output} 

Where:

{level}             - "info", "warning", "error"
{cli}               - "gh" or "git" (currently)
{command line}      - the exact cli command ran
{returned output}   - output of the command, if the command outputs json its 
                      typical that it will be converted to a lua table and ran
                      through vim.inspect(), pretty printing the output.