Custom Menu Commands
Aretext allows you to define custom menu items to run shell commands. This provides a simple, yet powerful, way to extend the editor.
Adding Custom Menu Comands
You can add new menu commands by editing the config file to add this rule:
- name: custom menu rule pattern: "**/myproject/**" config: menuCommands: - name: my custom menu command shellCmd: echo 'hello world!' | less mode: terminal # or "silent" or "insert" or "fileLocations"
After restarting the editor, the new command will be available in the command menu. Selecting the new command will launch a shell to execute the given command (in this case, echoing "hello world").
The shell program can be configured by environment variables:
$ARETEXT_SHELL has highest priority, then
$SHELL. If neither environment variable is set, aretext uses
The "mode" parameter controls how aretext handles the command's input and output. The table below shows the available modes:
|insert||none||insert into document||paste from system clipboard, insert snippet, comment/uncomment selection, ...|
|insertChoice||none||insert choice menu||choose a word to insert from a dictionary like
|fileLocations||none||file location menu||grep for word under cursor, ...|
|workingDir||none||working directory menu||select the current working directory from a preset list|
In addition, the following environment variables are provided to the shell command:
$FILEPATHis the absolute path to the current file.
$WORDis the current word under the cursor.
$LINEis the line number of the cursor, starting from one.
$COLUMNis the column position of the cursor in bytes, starting from one.
$SELECTIONis the currently selected text (if any).
If there are multiple commands with the same name, only the last of these commands will appear in the menu.
Build a project with make
Add a menu command to build a project using
make. Piping to
less allows us to page through the output.
- name: custom make cmd pattern: "**/myproject/**" config: menuCommands: - name: build shellCmd: make | less save: true # save the file before running `make`
Copy and paste using the system clipboard
Most systems provide command-line utilities for interacting with the system clipboard. Custom menu commands can invoke these tools to copy the current selection and paste into the document.
On Linux (Wayland):
- name: linux wayland clipboard commands pattern: "**" config: menuCommands: - name: copy to clipboard shellCmd: wl-copy "$SELECTION" mode: silent - name: paste from clipboard shellCmd: wl-paste mode: insert
- name: macos clipboard commands pattern: "**" config: menuCommands: - name: copy to clipboard shellCmd: printenv SELECTION | pbcopy mode: silent - name: paste from clipboard shellCmd: pbpaste mode: insert
- name: tmux clipboard commands pattern: "**" config: menuCommands: - name: copy to clipboard shellCmd: printenv SELECTION | tmux load-buffer - mode: silent - name: paste from clipboard shellCmd: tmux show-buffer mode: insert
Format the current file
Many programming languages provide command line tools to automatically format code. You can add a custom menu command to run these tools on the current file.
For example, this command uses
go fmt to format a Go file:
- name: custom fmt command pattern: "**/*.go" config: menuCommands: - name: go fmt current file shellCmd: go fmt $FILEPATH | less save: true # save the file before running `go fmt`
Git blame the current file
When working in a git repository, you might want to know who last edited a line of code. You can find this using
git blame on the current file.
- name: git blame command pattern: "**" config: menuCommands: - name: git blame shellCmd: git blame "$FILEPATH" | less +$LINE
Insert a snippet
You can add a custom menu command to insert a snippet of code.
For example, suppose you have written a template for a Go test. You can then create a menu command to
cat the contents of the file into the document:
- name: custom snippet command pattern: "**/*.go" config: menuCommands: - name: insert test snippet shellCmd: cat ~/snippets/go-test.go mode: insert
Grep for the word under the cursor
You can add a custom menu command to grep for the word under the cursor. The following example uses ripgrep to perform the search:
- name: custom grep command pattern: "**" config: menuCommands: - name: rg word shellCmd: rg $WORD --vimgrep # or `grep $WORD -n -R .` mode: fileLocations
Once the search has completed, aretext loads the locations into a searchable menu. This allows you to easily navigate to a particular result.
The "fileLocations" mode works with any command that outputs file locations as lines with the format:
<file>:<line>:<col>:<snippet>. You can use grep, ripgrep, or a script you write yourself!
Open a document in a new tmux window
If you use tmux, you can add a custom menu command to open the current document in a new window.