diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 730bd60..d265ccd 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -7,7 +7,7 @@ on: jobs: docs: runs-on: ubuntu-latest - if: ${{ github.ref == 'refs/heads/main' }} + if: ${{ github.ref == 'refs/heads/main' || github.ref == 'refs/heads/docs' }} steps: - uses: actions/checkout@v3 - name: panvimdoc @@ -16,6 +16,9 @@ jobs: vimdoc: gp.nvim demojify: true treesitter: true + docmapping: true + docmappingprojectname: false + dedupsubheadings: false - name: Push changes uses: stefanzweifel/git-auto-commit-action@v4 with: diff --git a/README.md b/README.md index e37baa5..b9b2656 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,6 @@ -# Gp.nvim (GPT prompt) Neovim AI plugin - - GitHub GitHub Repo stars GitHub closed issues @@ -11,9 +8,13 @@ GitHub contributors Static Badge +# Gp.nvim (GPT prompt) Neovim AI plugin + -Gp (GPT prompt) provides you ChatGPT like sessions and instructable text/code operations in your favorite editor. +
+ +**ChatGPT like sessions, Instructable text/code operations, Speech to text and Image generation in your favorite editor.**

@@ -24,7 +25,7 @@ Gp (GPT prompt) provides you ChatGPT like sessions and instructable text/code op - [5-min-demo](https://www.youtube.com/watch?v=X-cT7s47PLo) (December 2023) - [older-5-min-demo](https://www.youtube.com/watch?v=wPDcBnQgNCc) (screen capture, no sound) -## Goals and Features +# Goals and Features The goal is to extend Neovim with the **power of GPT models in a simple unobtrusive extensible way.** Trying to keep things as native as possible - reusing and integrating well with the natural features of (Neo)vim. @@ -35,7 +36,7 @@ Trying to keep things as native as possible - reusing and integrating well with - properly working undo (response can be undone with a single `u`) - **Infinitely extensible** via hook functions specified as part of the config - hooks have access to everything in the plugin and are automatically registered as commands - - see [Configuration](#4-configuration) and [Extend functionality](#extend-functionality) sections for details + - see [4. Configuration](#4-configuration) and [Extend functionality](#extend-functionality) sections for details - **Minimum dependencies** (`neovim`, `curl`, `grep` and optionally `sox`) - zero dependencies on other lua plugins to minimize chance of breakage - **ChatGPT like sessions** @@ -54,11 +55,14 @@ Trying to keep things as native as possible - reusing and integrating well with - **Speech to text support** - a mouth is 2-4x faster than fingers when it comes to outputting words - use it where it makes sense (dicating comments and notes, asking gpt questions, giving instructions for code operations, ..) +- **Image generation** + - be even less tempted to open the browser with the ability to generate images directly from Neovim -## Install +# Install -### 1. Install the plugin with your preferred package manager: +## 1. Install the plugin +Snippets for your preferred package manager: ```lua -- lazy.nvim { @@ -89,23 +93,25 @@ use({ }) ``` -### 2. OpenAI API key +## 2. OpenAI API key -Make sure you have OpenAI API key. [Get one here](https://platform.openai.com/account/api-keys) and use it in the [config](#4-configuration). Also consider setting up [usage limits](https://platform.openai.com/account/billing/limits) so you won't get suprised at the end of the month. +Make sure you have OpenAI API key. [Get one here](https://platform.openai.com/account/api-keys) and use it in the [4. Configuration](#4-configuration). Also consider setting up [usage limits](https://platform.openai.com/account/billing/limits) so you won't get suprised at the end of the month. The OpenAI API key can be passed to the plugin in multiple ways: -| Method | Example | Security Level | -|------------------|----------------------------------------------------------------|----------------| -| hardcoded string | `openai_api_key: "sk-...",` | Low | -| default env var | set `OPENAI_API_KEY` environment variable in shell config | Medium | -| custom env var | `openai_api_key = os.getenv("CUSTOM_ENV_NAME"),` | Medium | -| read from file | `openai_api_key = { "cat", "path_to_api_key" },` | Medium-High | -| password manager | `openai_api_key = { "bw", "get", "password", "OAI_API_KEY" },` | High | + +| Method | Example | Security Level | +|------------------------|----------------------------------------------------------------|----------------| +| hardcoded string | `openai_api_key: "sk-...",` | Low | +| default env var | set `OPENAI_API_KEY` environment variable in shell config | Medium | +| custom env var | `openai_api_key = os.getenv("CUSTOM_ENV_NAME"),` | Medium | +| read from file | `openai_api_key = { "cat", "path_to_api_key" },` | Medium-High | +| password manager | `openai_api_key = { "bw", "get", "password", "OAI_API_KEY" },` | High | + If `openai_api_key` is a table, Gp runs it asynchronously to avoid blocking Neovim (password managers can take a second or two). -### 3. Dependencies +## 3. Dependencies The core plugin only needs `curl` installed to make calls to OpenAI API and `grep` for ChatFinder. So Linux, BSD and Mac OS should be covered. @@ -117,82 +123,155 @@ Voice commands (`:GpWhisper*`) depend on `SoX` (Sound eXchange) to handle audio - Redhat/CentOS: `yum install sox` - NixOS: `nix-env -i sox` -### 4. Configuration +## 4. Configuration + +Bellow is a linked snippet with the default values, but I suggest starting with minimal config possible (just `openai_api_key` if you don't have `OPENAI_API_KEY` env set up). Defaults change over time to improve things, options might get deprecated and so on - it's better to change only things where the default doesn't fit your needs. -Bellow are the default values, but I suggest starting with minimal config possible (just `openai_api_key` if you don't have `OPENAI_API_KEY` env set up). Defaults change over time to improve things, options might get deprecated and so on - it's better to change only things where the default doesn't fit your needs. https://github.com/Robitx/gp.nvim/blob/7d802f54fb503f27fc9722656efddb05a533f4cf/lua/gp/config.lua#L8-L350 -## Usage - -### Commands - -- Have ChatGPT experience directly in neovim: - - - `:GpChatNew` - open fresh chat in the current window - (either empty or with the visual selection or specified range as a context) - - `:GpChatPaste` - paste the selection or specified range to the latest chat - (simplifies adding code from multiple files into a single chat buffer) - - `:GpChatToggle` - open chat in toggleable popup window - (the last active chat or a fresh one with selection or a range as a context) - - `:GpChatFinder` - open a dialog to search through chats - - `:GpChatRespond` - request new gpt response for the current chat - - `:GpChatRespond N` - request new gpt response with only last N messages as a context - (using everything from the end up to Nth instance of `🗨:..` => `N=1` is like asking a question in a new chat) - - `:GpChatDelete` - delete the current chat - - when calling `:GpChatNew` or `:GpChatPaste` and `GpChatToggle` you can also specify where to display chat using subcommands: - ![image](https://github.com/Robitx/gp.nvim/assets/8431097/350b38ce-52fb-4df7-b2a5-d6e51581f0c3) - -- Ask GPT and get response to the specified output: - - - `:GpRewrite` - answer replaces the current line, visual selection or range - - `:GpAppend` - answers after the current line, visual selection or range - - `:GpPrepend` - answers before the current line, selection or range - - `:GpEnew` - answers into a new buffer in the current window - - `:GpNew` - answers into new horizontal split window - - `:GpVnew` - answers into new vertical split window - - `:GpTabnew` - answers into new tab - - `:GpPopup` - answers into pop up window - - `:GpImplement` - default example hook command for finishing the code - based on comments provided in visual selection or specified range - - all these command work either: - - - as pure user commands without any other context in normal/insert mode - - with current selection (using whole lines) as a context in visual/Visual mode - - with specified range (such as `%` for the entire current buffer => `:%GpRewrite`) - -- Provide custom context per repository with`:GpContext`: - - - opens `.gp.md` file for given repository in toggable window - - if used with selection/range it appends it to the context file - - supports display targeting subcommands just like `GpChatNew` - - see [Custom instructions](#custom-instructions-per-repository) section - -- Switch between configured agents (model + persona): - - - `:GpNextAgent` - cycle between available agents - - `:GpAgent` - display currently used agents for chat and command instructions - - `:GpAgent XY` - choose new agent based on its name - - commands are context aware (they switch chat or command agent based on the current buffer) - -- Voice commands transcribed by Whisper API: - - `:GpWhisper` - transcription replaces the current line, visual selection or range in the current buffer (use your mouth to ask a question in a chat buffer instead of writing it by hand, dictate some comments for the code, notes or even your next novel) - for the rest of the whisper commands, the transcription is used as an editable prompt for the equivalent non whisper command (`GpWhisperRewrite` dictates instructions for `GpRewrite` etc.): - - `:GpWhisperRewrite` - answer replaces the current line, visual selection or range - - `:GpWhisperAppend` - answers after the current line, visual selection or range - - `:GpWhisperPrepend` - answers before the current line, selection or range - - `:GpWhisperEnew` - answers into new buffer in the current window - - `:GpWhisperNew` - answers into new horizontal split - - `:GpWhisperVnew` - answers into new vertical split - - `:GpWhisperTabnew` - answers into new tab - - `:GpWhisperPopup` - answers into pop up window -- To stop the stream of currently running gpt response you can use `:GpStop` -- Run your own custom hook commands: - - `:GpInspectPlugin` - inspect GPT prompt plugin object - -### GpDone autocommand to run consequent actions +# Usage + +## Chat commands + +#### `:GpChatNew` +Open a fresh chat in the current window. It can be either empty or include the visual selection or specified range as context. This command also supports subcommands for layout specification: + +- `:GpChatNew vsplit` Open a fresh chat in a vertical split window. +- `:GpChatNew split` Open a fresh chat in a horizontal split window. +- `:GpChatNew tabnew` Open a fresh chat in a new tab. +- `:GpChatNew popup` Open a fresh chat in a popup window. + +#### `:GpChatPaste` +Paste the selection or specified range into the latest chat, simplifying the addition of code from multiple files into a single chat buffer. This command also supports subcommands for layout specification: + +- `:GpChatPaste vsplit` Paste into the latest chat in a vertical split window. +- `:GpChatPaste split` Paste into the latest chat in a horizontal split window. +- `:GpChatPaste tab` Paste into the latest chat in a new tab. +- `:GpChatPaste popup` Paste into the latest chat in a popup window. + +#### `:GpChatToggle` +Open chat in a toggleable popup window, showing the last active chat or a fresh one with selection or a range as a context. This command also supports subcommands for layout specification: + +- `:GpChatToggle vsplit` Toggle chat in a vertical split window. +- `:GpChatToggle split` Toggle chat in a horizontal split window. +- `:GpChatToggle tab` Toggle chat in a new tab. +- `:GpChatToggle popup` Toggle chat in a popup window. + +#### `:GpChatFinder` +Open a dialog to search through chats. + +#### `:GpChatRespond` +Request a new GPT response for the current chat. Usin`:GpChatRespond N` request a new GPT response with only the last N messages as context, using everything from the end up to the Nth instance of `🗨:..` (N=1 is like asking a question in a new chat). + +#### `:GpChatDelete` +Delete the current chat. By default requires confirmation before delete, which can be disabled in config using `chat_confirm_delete = false,`. + +## Text/Code commands + +#### `:GpRewrite` +Opens a dialog for entering a prompt. After providing prompt instructions into the dialog, the generated response replaces the current line in normal/insert mode, selected lines in visual mode, or the specified range (e.g., `:%GpRewrite` applies the rewrite to the entire buffer). + +`:GpRewrite {prompt}` Executes directly with specified `{prompt}` instructions, bypassing the dialog. Suitable for mapping repetitive tasks to keyboard shortcuts or for automation using headless Neovim via terminal or shell scripts. + +#### `:GpAppend` +Similar to `:GpRewrite`, but the answer is added after the current line, visual selection, or range. + +#### `:GpPrepend` +Similar to `:GpRewrite`, but the answer is added before the current line, visual selection, or range. + +#### `:GpEnew` +Similar to `:GpRewrite`, but the answer is added into a new buffer in the current window. + +#### `:GpNew` +Similar to `:GpRewrite`, but the answer is added into a new horizontal split window. + +#### `:GpVnew` +Similar to `:GpRewrite`, but the answer is added into a new vertical split window. + +#### `:GpTabnew` +Similar to `:GpRewrite`, but the answer is added into a new tab. + +#### `:GpPopup` +Similar to `:GpRewrite`, but the answer is added into a pop-up window. + +#### `:GpImplement` +Example hook command to develop code from comments in a visual selection or specified range. + +#### `:GpContext` +Provides custom context per repository: + +- opens `.gp.md` file for a given repository in a toggable window. +- appends selection/range to the context file when used in visual/range mode. +- also supports subcommands for layout specification: + + - `:GpContext vsplit` Open `.gp.md` in a vertical split window. + - `:GpContext split` Open `.gp.md` in a horizontal split window. + - `:GpContext tabnew` Open `.gp.md` in a new tab. + - `:GpContext popup` Open `.gp.md` in a popup window. + +- refer to [Custom Instructions](#custom-instructions) for more details. +## Speech commands + +#### `:GpWhisper` +Transcription replaces the current line, visual selection or range in the current buffer. Use your mouth to ask a question in a chat buffer instead of writing it by hand, dictate some comments for the code, notes or even your next novel.. + +For the rest of the whisper commands, the transcription is used as an editable prompt for the equivalent non whisper command - `GpWhisperRewrite` dictates instructions for `GpRewrite` etc. + +#### `:GpWhisperRewrite` +Similar to `:GpRewrite`, but the prompt instruction dialog uses transcribed spoken instructions. + +#### `:GpWhisperAppend` +Similar to `:GpAppend`, but the prompt instruction dialog uses transcribed spoken instructions for adding content after the current line, visual selection, or range. + +#### `:GpWhisperPrepend` +Similar to `:GpPrepend`, but the prompt instruction dialog uses transcribed spoken instructions for adding content before the current line, selection, or range. + +#### `:GpWhisperEnew` +Similar to `:GpEnew`, but the prompt instruction dialog uses transcribed spoken instructions for opening content in a new buffer within the current window. + +#### `:GpWhisperNew` +Similar to `:GpNew`, but the prompt instruction dialog uses transcribed spoken instructions for opening content in a new horizontal split window. + +#### `:GpWhisperVnew` +Similar to `:GpVnew`, but the prompt instruction dialog uses transcribed spoken instructions for opening content in a new vertical split window. + +#### `:GpWhisperTabnew` +Similar to `:GpTabnew`, but the prompt instruction dialog uses transcribed spoken instructions for opening content in a new tab. + +#### `:GpWhisperPopup` +Similar to `:GpPopup`, but the prompt instruction dialog uses transcribed spoken instructions for displaying content in a pop-up window. + +## Agent commands + +#### `:GpNextAgent` +Cycles between available agents based on the current buffer (chat agents if current buffer is a chat and command agents otherwise). The agent setting is persisted on disk across Neovim instances. + +#### `:GpAgent` +Displays currently used agents for chat and command instructions. + +#### `:GpAgent XY` +Choose a new agent based on its name, listing options based on the current buffer (chat agents if current buffer is a chat and command agents otherwise). The agent setting is persisted on disk across Neovim instances. + +## Image commands + +#### `:GpImage` +Opens a dialog for entering a prompt describing wanted images. When the generation is done it opens dialog for storing the image to the disk. + +#### `:GpImageAgent` +Displays currently used image agent (configuration). + +#### `:GpImageAgent XY` +Choose a new "image agent" based on its name. In the context of images, agent is basically a configuration for model, image size, quality and so on. The agent setting is persisted on disk across Neovim instances. + +## Other commands + +#### `:GpStop` +Stops all currently running responses and jobs. + +#### `:GpInspectPlugin` +Inspects the GPT prompt plugin object in a new scratch buffer. + +## GpDone autocommand Commands like `GpRewrite`, `GpAppend` etc. run asynchronously and generate event `GpDone`, so you can define autocmd (like auto formating) to run when gp finishes: @@ -207,7 +286,7 @@ Commands like `GpRewrite`, `GpAppend` etc. run asynchronously and generate event }) ``` -### Custom instructions per repository +## Custom instructions By calling `:GpContext` you can make `.gp.md` markdown file in a root of a repository. Commands such as `:GpRewrite`, `:GpAppend` etc. will respect instructions provided in this file (works better with gpt4, gpt 3.5 doesn't always listen to system commands). For example: @@ -220,7 +299,7 @@ Use Early return/Guard Clauses pattern to avoid excessive nesting. Here is [another example](https://github.com/Robitx/gp.nvim/blob/main/.gp.md). -### Scripting and multifile edits +## Scripting `GpDone` event + `.gp.md` custom instructions provide a possibility to run gp.nvim using headless (neo)vim from terminal or shell script. So you can let gp run edits accross many files if you put it in a loop. @@ -266,11 +345,11 @@ Ahoy there! 5 ``` -### Shortcuts +# Shortcuts There are no default global shortcuts to mess with your own config. Bellow are examples for you to adjust or just use directly. -#### Native +## Native You can use the good old `vim.keymap.set` and paste the following after `require("gp").setup(conf)` call (or anywhere you keep shortcuts if you want them at one place). @@ -355,7 +434,7 @@ vim.keymap.set("v", "wv", ":'<,'>GpWhisperVnew", keymapOptions("Vi vim.keymap.set("v", "wt", ":'<,'>GpWhisperTabnew", keymapOptions("Visual Whisper Tabnew")) ``` -#### Whichkey +## Whichkey Or go more fancy by using [which-key.nvim](https://github.com/folke/which-key.nvim) plugin: @@ -519,7 +598,7 @@ require("which-key").register({ }) ``` -## Extend functionality +# Extend functionality You can extend/override the plugin functionality with your own, by putting functions into `config.hooks`. Hooks have access to everything (see `InspectPlugin` example in defaults) and are diff --git a/doc/gp.nvim.txt b/doc/gp.nvim.txt index 9408ed8..7d0d917 100644 --- a/doc/gp.nvim.txt +++ b/doc/gp.nvim.txt @@ -3,12 +3,29 @@ ============================================================================== Table of Contents *gp.nvim-table-of-contents* - - Goals and Features |gp.nvim-goals-and-features| - - Install |gp.nvim-install| - - Usage |gp.nvim-usage| - - Extend functionality |gp.nvim-extend-functionality| -Gp (GPT prompt) provides you ChatGPT like sessions and instructable text/code -operations in your favorite editor. +1. Goals and Features |gp.nvim-goals-and-features| +2. Install |gp.nvim-install| + - 1. Install the plugin |gp.nvim-1.-install-the-plugin| + - 2. OpenAI API key |gp.nvim-2.-openai-api-key| + - 3. Dependencies |gp.nvim-3.-dependencies| + - 4. Configuration |gp.nvim-4.-configuration| +3. Usage |gp.nvim-usage| + - Chat commands |gp.nvim-chat-commands| + - Text/Code commands |gp.nvim-text/code-commands| + - Agent commands |gp.nvim-agent-commands| + - Image commands |gp.nvim-image-commands| + - Other commands |gp.nvim-other-commands| + - GpDone autocommand |gp.nvim-gpdone-autocommand| + - Custom instructions |gp.nvim-custom-instructions| + - Scripting |gp.nvim-scripting| +4. Shortcuts |gp.nvim-shortcuts| + - Native |gp.nvim-native| + - Whichkey |gp.nvim-whichkey| +5. Extend functionality |gp.nvim-extend-functionality| + + +**ChatGPT like sessions, Instructable text/code operations, Speech to text and +Image generation in your favorite editor.** @@ -18,7 +35,8 @@ YOUTUBE DEMOS ~ - older-5-min-demo (screen capture, no sound) -GOALS AND FEATURES *gp.nvim-goals-and-features* +============================================================================== +1. Goals and Features *gp.nvim-goals-and-features* The goal is to extend Neovim with the **power of GPT models in a simple unobtrusive extensible way.** Trying to keep things as native as possible - @@ -30,7 +48,7 @@ reusing and integrating well with the natural features of (Neo)vim. - properly working undo (response can be undone with a single `u`) - **Infinitely extensible** via hook functions specified as part of the config - hooks have access to everything in the plugin and are automatically registered as commands - - see |gp.nvim-configuration| and |gp.nvim-extend-functionality| sections for details + - see |gp.nvim-4.-configuration| and |gp.nvim-extend-functionality| sections for details - **Minimum dependencies** (`neovim`, `curl`, `grep` and optionally `sox`) - zero dependencies on other lua plugins to minimize chance of breakage - **ChatGPT like sessions** @@ -49,12 +67,17 @@ reusing and integrating well with the natural features of (Neo)vim. - **Speech to text support** - a mouth is 2-4x faster than fingers when it comes to outputting words - use it where it makes sense (dicating comments and notes, asking gpt questions, giving instructions for code operations, ..) +- **Image generation** + - be even less tempted to open the browser with the ability to generate images directly from Neovim + +============================================================================== +2. Install *gp.nvim-install* -INSTALL *gp.nvim-install* +1. INSTALL THE PLUGIN *gp.nvim-1.-install-the-plugin* -1. INSTALL THE PLUGIN WITH YOUR PREFERRED PACKAGE MANAGER: ~ +Snippets for your preferred package manager: >lua -- lazy.nvim @@ -87,40 +110,35 @@ INSTALL *gp.nvim-install* < -2. OPENAI API KEY ~ +2. OPENAI API KEY *gp.nvim-2.-openai-api-key* Make sure you have OpenAI API key. Get one here and use it in the -|gp.nvim-config|. Also consider setting up usage limits +|gp.nvim-4.-configuration|. Also consider setting up usage limits so you won’t get suprised at the end of the month. The OpenAI API key can be passed to the plugin in multiple ways: - ------------------------------------------------------------------------------------------ - Method Example Security - Level - ------------- -------------------------------------------------------------- ------------- - hardcoded openai_api_key: "sk-...", Low - string + --------------------------------------------------------------------------------------------- + Method Example Security + Level + ---------------- -------------------------------------------------------------- ------------- + hardcoded string openai_api_key: "sk-...", Low - default env set OPENAI_API_KEY environment variable in shell config Medium - var + default env var set OPENAI_API_KEY environment variable in shell config Medium - custom env openai_api_key = os.getenv("CUSTOM_ENV_NAME"), Medium - var + custom env var openai_api_key = os.getenv("CUSTOM_ENV_NAME"), Medium - read from openai_api_key = { "cat", "path_to_api_key" }, Medium-High - file + read from file openai_api_key = { "cat", "path_to_api_key" }, Medium-High - password openai_api_key = { "bw", "get", "password", "OAI_API_KEY" }, High - manager - ------------------------------------------------------------------------------------------ + password manager openai_api_key = { "bw", "get", "password", "OAI_API_KEY" }, High + --------------------------------------------------------------------------------------------- If `openai_api_key` is a table, Gp runs it asynchronously to avoid blocking Neovim (password managers can take a second or two). -3. DEPENDENCIES ~ +3. DEPENDENCIES *gp.nvim-3.-dependencies* The core plugin only needs `curl` installed to make calls to OpenAI API and `grep` for ChatFinder. So Linux, BSD and Mac OS should be covered. @@ -135,78 +153,275 @@ recording and processing: - NixOS: `nix-env -i sox` -4. CONFIGURATION ~ +4. CONFIGURATION *gp.nvim-4.-configuration* + +Bellow is a linked snippet with the default values, but I suggest starting with +minimal config possible (just `openai_api_key` if you don’t have +`OPENAI_API_KEY` env set up). Defaults change over time to improve things, +options might get deprecated and so on - it’s better to change only things +where the default doesn’t fit your needs. + -Bellow are the default values, but I suggest starting with minimal config -possible (just `openai_api_key` if you don’t have `OPENAI_API_KEY` env set -up). Defaults change over time to improve things, options might get deprecated -and so on - it’s better to change only things where the default doesn’t fit -your needs. https://github.com/Robitx/gp.nvim/blob/7d802f54fb503f27fc9722656efddb05a533f4cf/lua/gp/config.lua#L8-L350 -USAGE *gp.nvim-usage* - - -COMMANDS ~ - -- Have ChatGPT experience directly in neovim: - - `:GpChatNew` - open fresh chat in the current window - (either empty or with the visual selection or specified range as a context) - - `:GpChatPaste` - paste the selection or specified range to the latest chat - (simplifies adding code from multiple files into a single chat buffer) - - `:GpChatToggle` - open chat in toggleable popup window - (the last active chat or a fresh one with selection or a range as a context) - - `:GpChatFinder` - open a dialog to search through chats - - `:GpChatRespond` - request new gpt response for the current chat - - `:GpChatRespond N` - request new gpt response with only last N messages as a context - (using everything from the end up to Nth instance of `🗨:..` => `N=1` is like asking a question in a new chat) - - `:GpChatDelete` - delete the current chat - when calling `:GpChatNew` or `:GpChatPaste` and `GpChatToggle` you can also - specify where to display chat using subcommands: -- Ask GPT and get response to the specified output: - - `:GpRewrite` - answer replaces the current line, visual selection or range - - `:GpAppend` - answers after the current line, visual selection or range - - `:GpPrepend` - answers before the current line, selection or range - - `:GpEnew` - answers into a new buffer in the current window - - `:GpNew` - answers into new horizontal split window - - `:GpVnew` - answers into new vertical split window - - `:GpTabnew` - answers into new tab - - `:GpPopup` - answers into pop up window - - `:GpImplement` - default example hook command for finishing the code - based on comments provided in visual selection or specified range - all these command work either: - - as pure user commands without any other context in normal/insert mode - - with current selection (using whole lines) as a context in visual/Visual mode - - with specified range (such as `%` for the entire current buffer => `:%GpRewrite`) -- Provide custom context per repository with`:GpContext` - - opens`.gp.md` file for given repository in toggable window - - if used with selection/range it appends it to the context file - - supports display targeting subcommands just like `GpChatNew` - - see |gp.nvim-custom-instructions| section -- Switch between configured agents (model + persona): - - `:GpNextAgent` - cycle between available agents - - `:GpAgent` - display currently used agents for chat and command instructions - - `:GpAgent XY` - choose new agent based on its name - commands are context aware (they switch chat or command agent based on the - current buffer) -- Voice commands transcribed by Whisper API: - - `:GpWhisper` - transcription replaces the current line, visual selection or range in the current buffer (use your mouth to ask a question in a chat buffer instead of writing it by hand, dictate some comments for the code, notes or even your next novel) - for the rest of the whisper commands, the transcription is used as an editable prompt for the equivalent non whisper command (`GpWhisperRewrite` dictates instructions for `GpRewrite` etc.): - - `:GpWhisperRewrite` - answer replaces the current line, visual selection or range - - `:GpWhisperAppend` - answers after the current line, visual selection or range - - `:GpWhisperPrepend` - answers before the current line, selection or range - - `:GpWhisperEnew` - answers into new buffer in the current window - - `:GpWhisperNew` - answers into new horizontal split - - `:GpWhisperVnew` - answers into new vertical split - - `:GpWhisperTabnew` - answers into new tab - - `:GpWhisperPopup` - answers into pop up window -- To stop the stream of currently running gpt response you can use `:GpStop` -- Run your own custom hook commands: - - `:GpInspectPlugin` - inspect GPT prompt plugin object - - -GPDONE AUTOCOMMAND TO RUN CONSEQUENT ACTIONS ~ +============================================================================== +3. Usage *gp.nvim-usage* + + +CHAT COMMANDS *gp.nvim-chat-commands* + + +:GpChatNew *:GpChatNew* + +Open a fresh chat in the current window. It can be either empty or include the +visual selection or specified range as context. This command also supports +subcommands for layout specification: + +- `:GpChatNew vsplit` Open a fresh chat in a vertical split window. +- `:GpChatNew split` Open a fresh chat in a horizontal split window. +- `:GpChatNew tabnew` Open a fresh chat in a new tab. +- `:GpChatNew popup` Open a fresh chat in a popup window. + + +:GpChatPaste *:GpChatPaste* + +Paste the selection or specified range into the latest chat, simplifying the +addition of code from multiple files into a single chat buffer. This command +also supports subcommands for layout specification: + +- `:GpChatPaste vsplit` Paste into the latest chat in a vertical split window. +- `:GpChatPaste split` Paste into the latest chat in a horizontal split window. +- `:GpChatPaste tab` Paste into the latest chat in a new tab. +- `:GpChatPaste popup` Paste into the latest chat in a popup window. + + +:GpChatToggle *:GpChatToggle* + +Open chat in a toggleable popup window, showing the last active chat or a fresh +one with selection or a range as a context. This command also supports +subcommands for layout specification: + +- `:GpChatToggle vsplit` Toggle chat in a vertical split window. +- `:GpChatToggle split` Toggle chat in a horizontal split window. +- `:GpChatToggle tab` Toggle chat in a new tab. +- `:GpChatToggle popup` Toggle chat in a popup window. + + +:GpChatFinder *:GpChatFinder* + +Open a dialog to search through chats. + + +:GpChatRespond *:GpChatRespond* + +Request a new GPT response for the current chat. Usin`:GpChatRespond N` request +a new GPT response with only the last N messages as context, using everything +from the end up to the Nth instance of `🗨:..` (N=1 is like asking a question +in a new chat). + + +:GpChatDelete *:GpChatDelete* + +Delete the current chat. By default requires confirmation before delete, which +can be disabled in config using `chat_confirm_delete = false,`. + + +TEXT/CODE COMMANDS *gp.nvim-text/code-commands* + + +:GpRewrite *:GpRewrite* + +Opens a dialog for entering a prompt. After providing prompt instructions into +the dialog, the generated response replaces the current line in normal/insert +mode, selected lines in visual mode, or the specified range (e.g., +`:%GpRewrite` applies the rewrite to the entire buffer). + +`:GpRewrite {prompt}` Executes directly with specified `{prompt}` instructions, +bypassing the dialog. Suitable for mapping repetitive tasks to keyboard +shortcuts or for automation using headless Neovim via terminal or shell +scripts. + + +:GpAppend *:GpAppend* + +Similar to `:GpRewrite`, but the answer is added after the current line, visual +selection, or range. + + +:GpPrepend *:GpPrepend* + +Similar to `:GpRewrite`, but the answer is added before the current line, +visual selection, or range. + + +:GpEnew *:GpEnew* + +Similar to `:GpRewrite`, but the answer is added into a new buffer in the +current window. + + +:GpNew *:GpNew* + +Similar to `:GpRewrite`, but the answer is added into a new horizontal split +window. + + +:GpVnew *:GpVnew* + +Similar to `:GpRewrite`, but the answer is added into a new vertical split +window. + + +:GpTabnew *:GpTabnew* + +Similar to `:GpRewrite`, but the answer is added into a new tab. + + +:GpPopup *:GpPopup* + +Similar to `:GpRewrite`, but the answer is added into a pop-up window. + + +:GpImplement *:GpImplement* + +Example hook command to develop code from comments in a visual selection or +specified range. + + +:GpContext *:GpContext* + +Provides custom context per repository: + +- opens `.gp.md` file for a given repository in a toggable window. +- appends selection/range to the context file when used in visual/range mode. +- also supports subcommands for layout specification: + - `:GpContext vsplit` Open `.gp.md` in a vertical split window. + - `:GpContext split` Open `.gp.md` in a horizontal split window. + - `:GpContext tabnew` Open `.gp.md` in a new tab. + - `:GpContext popup` Open `.gp.md` in a popup window. +- refer to |gp.nvim-custom-instructions| for more details. ## Speech commands + + +:GpWhisper *:GpWhisper* + +Transcription replaces the current line, visual selection or range in the +current buffer. Use your mouth to ask a question in a chat buffer instead of +writing it by hand, dictate some comments for the code, notes or even your next +novel.. + +For the rest of the whisper commands, the transcription is used as an editable +prompt for the equivalent non whisper command - `GpWhisperRewrite` dictates +instructions for `GpRewrite` etc. + + +:GpWhisperRewrite *:GpWhisperRewrite* + +Similar to `:GpRewrite`, but the prompt instruction dialog uses transcribed +spoken instructions. + + +:GpWhisperAppend *:GpWhisperAppend* + +Similar to `:GpAppend`, but the prompt instruction dialog uses transcribed +spoken instructions for adding content after the current line, visual +selection, or range. + + +:GpWhisperPrepend *:GpWhisperPrepend* + +Similar to `:GpPrepend`, but the prompt instruction dialog uses transcribed +spoken instructions for adding content before the current line, selection, or +range. + + +:GpWhisperEnew *:GpWhisperEnew* + +Similar to `:GpEnew`, but the prompt instruction dialog uses transcribed spoken +instructions for opening content in a new buffer within the current window. + + +:GpWhisperNew *:GpWhisperNew* + +Similar to `:GpNew`, but the prompt instruction dialog uses transcribed spoken +instructions for opening content in a new horizontal split window. + + +:GpWhisperVnew *:GpWhisperVnew* + +Similar to `:GpVnew`, but the prompt instruction dialog uses transcribed spoken +instructions for opening content in a new vertical split window. + + +:GpWhisperTabnew *:GpWhisperTabnew* + +Similar to `:GpTabnew`, but the prompt instruction dialog uses transcribed +spoken instructions for opening content in a new tab. + + +:GpWhisperPopup *:GpWhisperPopup* + +Similar to `:GpPopup`, but the prompt instruction dialog uses transcribed +spoken instructions for displaying content in a pop-up window. + + +AGENT COMMANDS *gp.nvim-agent-commands* + + +:GpNextAgent *:GpNextAgent* + +Cycles between available agents based on the current buffer (chat agents if +current buffer is a chat and command agents otherwise). The agent setting is +persisted on disk across Neovim instances. + + +:GpAgent *:GpAgent* + +Displays currently used agents for chat and command instructions. + + +:GpAgent XY *:GpAgent-XY* + +Choose a new agent based on its name, listing options based on the current +buffer (chat agents if current buffer is a chat and command agents otherwise). +The agent setting is persisted on disk across Neovim instances. + + +IMAGE COMMANDS *gp.nvim-image-commands* + + +:GpImage *:GpImage* + +Opens a dialog for entering a prompt describing wanted images. When the +generation is done it opens dialog for storing the image to the disk. + + +:GpImageAgent *:GpImageAgent* + +Displays currently used image agent (configuration). + + +:GpImageAgent XY *:GpImageAgent-XY* + +Choose a new "image agent" based on its name. In the context of images, agent +is basically a configuration for model, image size, quality and so on. The +agent setting is persisted on disk across Neovim instances. + + +OTHER COMMANDS *gp.nvim-other-commands* + + +:GpStop *:GpStop* + +Stops all currently running responses and jobs. + + +:GpInspectPlugin *:GpInspectPlugin* + +Inspects the GPT prompt plugin object in a new scratch buffer. + + +GPDONE AUTOCOMMAND *gp.nvim-gpdone-autocommand* Commands like `GpRewrite`, `GpAppend` etc. run asynchronously and generate event `GpDone`, so you can define autocmd (like auto formating) to run when gp @@ -224,7 +439,7 @@ finishes: < -CUSTOM INSTRUCTIONS PER REPOSITORY ~ +CUSTOM INSTRUCTIONS *gp.nvim-custom-instructions* By calling `:GpContext` you can make `.gp.md` markdown file in a root of a repository. Commands such as `:GpRewrite`, `:GpAppend` etc. will respect @@ -241,7 +456,7 @@ always listen to system commands). For example: Here is another example . -SCRIPTING AND MULTIFILE EDITS ~ +SCRIPTING *gp.nvim-scripting* `GpDone` event + `.gp.md` custom instructions provide a possibility to run gp.nvim using headless (neo)vim from terminal or shell script. So you can let @@ -290,13 +505,14 @@ resulting `test` file: < -SHORTCUTS ~ +============================================================================== +4. Shortcuts *gp.nvim-shortcuts* There are no default global shortcuts to mess with your own config. Bellow are examples for you to adjust or just use directly. -NATIVE +NATIVE *gp.nvim-native* You can use the good old `vim.keymap.set` and paste the following after `require("gp").setup(conf)` call (or anywhere you keep shortcuts if you want @@ -383,7 +599,7 @@ them at one place). < -WHICHKEY +WHICHKEY *gp.nvim-whichkey* Or go more fancy by using which-key.nvim plugin: @@ -549,7 +765,8 @@ Or go more fancy by using which-key.nvim < -EXTEND FUNCTIONALITY *gp.nvim-extend-functionality* +============================================================================== +5. Extend functionality *gp.nvim-extend-functionality* You can extend/override the plugin functionality with your own, by putting functions into `config.hooks`. Hooks have access to everything (see @@ -709,11 +926,6 @@ The raw plugin text editing method `Prompt` has seven aprameters: - `whisper` - optional string serving as a default for input prompt (for example generated from speech by Whisper) -============================================================================== -1. Links *gp.nvim-links* - -1. *image*: https://github.com/Robitx/gp.nvim/assets/8431097/350b38ce-52fb-4df7-b2a5-d6e51581f0c3 - Generated by panvimdoc vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/lua/gp/config.lua b/lua/gp/config.lua index fe12e97..0caa00d 100644 --- a/lua/gp/config.lua +++ b/lua/gp/config.lua @@ -6,6 +6,11 @@ -------------------------------------------------------------------------------- local config = { + -- Please start with minimal config possible. + -- Just openai_api_key if you don't have OPENAI_API_KEY env set up. + -- Defaults change over time to improve things, options might get deprecated. + -- It's better to change only things where the default doesn't fit your needs. + -- required openai api key (string or table with command and arguments) -- openai_api_key = { "cat", "path_to/openai_api_key" }, -- openai_api_key = { "bw", "get", "password", "OPENAI_API_KEY" },