diff --git a/docs/bash.rst b/docs/bash.rst index a83b2c1..abae1f5 100644 --- a/docs/bash.rst +++ b/docs/bash.rst @@ -11,6 +11,11 @@ Bash dotfiles At the top of ``.bashrc``, the following files are sourced if they’re present. This keeps things a little more organized and modular: +This modular structure makes it easier to edit specific parts of the +configuration without digging through a single large file. For example if you +want to add your own aliases, edit :file:`.aliases`; for PATH changes edit +:file:`.path`. + .. code-block:: bash for file in ~/.{path,exports,bash_prompt,functions,aliases,extra}; do @@ -50,14 +55,14 @@ Other notable parts of the :file:`.bashrc`: ``.bash_profile`` does only one thing: it sources ``.bashrc``. -.. _.path: +.. _path: ``.path`` --------- This file ends up being lots of ``export PATH="$PATH:/some/other/path"`` lines. It is initially populated to put ``~/opt/bin`` and -``~/mambaforge/condabin`` on the path. As you install more software in other +``~/miniforge/condabin`` on the path. As you install more software in other locations, this is a tidy place to put the various exports. .. _.aliases: @@ -65,7 +70,7 @@ locations, this is a tidy place to put the various exports. ``.aliases`` ------------ -This file keeps aliase separate for easier maintenance. See :file:`.aliases` +This file keeps aliases separate for easier maintenance. See :file:`.aliases` for the commands set for each alias. .. list-table:: @@ -108,9 +113,9 @@ for the commands set for each alias. - Runs the start_agent function (see :file:`.functions` below) * - ``st`` - - If you connect to a host with SSH key fowarding, start a tmux session, + - If you connect to a host with SSH key forwarding, start a tmux session, and then disconnect and reconnect to the remote tmux session, the - ``SSH_AUTH_SOCKET`` path used by tmux is stale, preventing key fowarding. + ``SSH_AUTH_SOCKET`` path used by tmux is stale, preventing key forwarding. This refreshes the path so that key forwarding works. * - ``git-clean-branches-master`` diff --git a/docs/conda.rst b/docs/conda.rst index bee59d0..41e4e3d 100644 --- a/docs/conda.rst +++ b/docs/conda.rst @@ -4,8 +4,8 @@ conda Installing conda ---------------- -To install conda, we use `Mambaforge -`_. Mambaforge is a way of installing +To install conda, we use `Miniforge +`_. Miniforge is a way of installing conda that sets conda-forge as the default (and only) channel, and it includes ``mamba``, a drop-in replacement for conda that is faster and more feature-complete. @@ -46,6 +46,10 @@ environment you want. The solution ------------ +These dotfiles provide ``ca`` (short for "conda activate") which activates +conda on demand only when you need it, rather than automatically activating +upon starting every shell. This avoids I/O slowdown and tmux issues. + 1. **To activate an environment, use** ``ca`` at the time you want to use it. Use ``ca`` by itself to activate the base environment. Use ``ca `` to activate a specific environment. diff --git a/docs/nvim-plugins.rst b/docs/nvim-plugins.rst index d73f442..e9baac0 100644 --- a/docs/nvim-plugins.rst +++ b/docs/nvim-plugins.rst @@ -117,32 +117,35 @@ command line: ``gsv`` (mnemonic: git status viewer). - description * - ``:Git`` - - Opens the main screen for fugitive (hint: use `vim -c ":Git"` from the - command line to jump right into it) + - Opens git status interface in a split window showing modified files, + staged changes, and recent commits. Navigate with j/k (hint: use `vim -c + ":Git"` from command line to jump right into it) * - ``:tab Git`` - - Opens the main screen for fugitive in a new tab, for fullscreen usage; - :kbd:`:q` to get back to what you were editing on before running it. + - Opens git status interface in a new tab for fullscreen usage. Press + :kbd:`:q` to return to previous editing session * - :kbd:`=` - - Toggle visibility of changes + - Toggles visibility of changes (diff) for the file under cursor. Shows + what changed in chunks * - :kbd:`-` (when over a filename) - - Stage or unstage the file + - Stages the file if unstaged, unstages if already staged * - :kbd:`-` (when in a chunk after using ``=``) - - Stage or unstage the chunk + - Stages the chunk if unstaged, unstages if already staged * - :kbd:`-` (in visual select mode (``V``)) - - Stage or unstage **just the selected lines**. Perfect for making - incremental commits. + - Stages or unstages **just the selected lines**. Perfect for making + incremental commits * - :kbd:`cc` - - Commit, opening up a separate buffer in which to write the commit - message + - Opens commit interface in a new buffer. Write your commit message, save + and close (:wq) to complete the commit * - :kbd:`dd` (when over a file) - - Open the file in diff mode (to better see intraline diffs) + - Opens the file in split diff mode showing line-by-line and character-by- + character changes .. plugin-metadata:: :name: vim-fugitive @@ -203,34 +206,39 @@ is "hunk" (the term for a block of changes). - description * - :kbd:`[h` - - Previous change + - Jump to previous change (hunk) in the file * - :kbd:`]h` - - Next change + - Jump to next change (hunk) in the file * - :kbd:`hp` - - Preview hunk (shows floating window of the change, only works in a change) + - Preview hunk: opens floating window showing the diff for the current + change. Move away (j/k) to close. * - :kbd:`hs` - - Stage hunk (or stage lines in visual mode) + - Stage hunk: marks the current change to be included in next commit. In + visual mode, stages only selected lines * - :kbd:`hr` - - Reset hunk (or reset lines in visual mode) + - Reset hunk: discards the current change, reverting to what's in git. In + visual mode, resets only selected lines * - :kbd:`hu` - - Undo stage hunk + - Undo stage hunk: unstages a previously staged hunk * - :kbd:`hS` - - Stage buffer + - Stage entire buffer: marks all changes in the current file for commit * - :kbd:`hR` - - Reset buffer + - Reset entire buffer: discards all changes in the current file * - :kbd:`hb` - - Blame line in floating window + - Shows git blame info for current line in a floating window (who changed + it, when, commit message) - * - :kbd:`hd` - - Diff this file (opens diff mode) + * - :kbd:`hd` + - Opens diff mode showing side-by-side comparison of current file vs git + version Additionally, this supports hunks as text objects using ``ih`` (inside hunk). @@ -341,17 +349,11 @@ Because the experience can be hit-or-miss depending on the language you're using, and the language servers need to be installed, LSP is disabled by default; start it with :kbd:`cl`. -.. warning:: +.. note:: nvim 0.11 changed the way LSPs are handled, making them more natively - integrated. However, this breaks the existing plugin configuration. - - These dotfiles **currently only support nvim <0.11**. - - I experimented with supporting both versions simultaneously. But the files - got complex, and it was a pain to keep switching versions to test everything - on both. So I'm opting to require nvim 0.10 for now. After a little while, - I'll move everything to 0.11+ and require nvim 0.11+. + integrated. These dotfiles now support nvim 0.11+ and are backwards + compatible with 0.10. .. contents:: :local: @@ -389,25 +391,33 @@ commands; mnemonic is "code". * - command - description * - :kbd:`cl` - - Start the LSP server for this buffer + - Starts the Language Server Protocol (LSP) for this buffer, enabling + code completion, diagnostics, and navigation. Mnemonic: [c]ode [l]SP * - :kbd:`ce` - - Show details for the diagnostic + - Opens floating window with detailed explanation of the diagnostic + (error/warning) under cursor. Mnemonic: [c]ode [e]rror * - :kbd:`cv` - - Toggle virtual text diagnostics in buffer + - Toggles inline virtual text showing diagnostic messages at end of lines. + When off, diagnostics only appear in gutter. Mnemonic: [c]ode [v]irtual * - :kbd:`[d` - - Prev diagnostic + - Jumps to previous diagnostic (error/warning/hint) in the buffer * - :kbd:`]d` - - Next diagnostic + - Jumps to next diagnostic (error/warning/hint) in the buffer * - :kbd:`grt` - - Goto definition (e.g., when cursor is over a function) + - Jumps to where the symbol under cursor is defined (e.g., function + definition, class declaration). Mnemonic: [g]o to [r]eference [t]ype * - :kbd:`K` - - Hover help + - Shows hover documentation for the symbol under cursor in a floating + window (function signature, docstring, type info) * - :kbd:`grn` - - Rename all instances of this symbol + - Renames all instances of the symbol under cursor throughout the project. + Opens prompt for new name. Mnemonic: [g]o to [r]eference [n]ame * - :kbd:`grr` - - Goto references + - Opens list of all places where the symbol under cursor is referenced. + Select one to jump to it. Mnemonic: [g]o to [r]eferences [r]eferences * - :kbd:`gra` - - Code action (opens a menu if implemented) + - Opens menu of available code actions for current context (quick fixes, + refactorings, imports). Mnemonic: [g]o to [r]eference [a]ction .. plugin-metadata:: :name: nvim-lspconfig @@ -448,10 +458,12 @@ have that many features yet, either. * - command - description * - ``:Mason`` - - Open the mason interface + - Opens floating window with Mason interface showing available language + servers and tools. Navigate with j/k, press i to install, X to uninstall, + U to update * - :kbd:`i` on an item - - Install + - Install the selected language server or tool .. plugin-metadata:: @@ -479,7 +491,9 @@ plugin. * - command - description * - :kbd:`ct` - - Toggle trouble.nvim window + - Toggles trouble.nvim diagnostic window at bottom of screen, showing all + LSP errors/warnings in your project. Navigate with j/k, Enter to jump to + issue, q to close (or `ct` again). .. plugin-metadata:: :name: trouble @@ -559,17 +573,22 @@ selected file in a new buffer). Hit Esc twice to exit. - description * - :kbd:`ff` - - Find files under this directory. Handy alternative to ``:e`` + - Opens floating window for fuzzy file search under current directory. Type + to filter filenames, press Enter to open selected file, Esc to cancel. + Handy alternative to ``:e`` * - :kbd:`fg` - Search directory for string. This is like using ripgrep, but in vim. Selecting entry takes you right to the line. * - :kbd:`/` - - Fuzzy find within buffer + - Opens floating window for fuzzy search within current buffer. Type to + filter matching lines, Enter to jump to selected line, Esc to cancel * - :kbd:`fc` - - Find code object + - Opens floating window to search for code symbols (functions, classes, + variables) in the current buffer using Treesitter. Type to filter, Enter + to jump to symbol, Esc to cancel Other useful things you can do with Telescope: @@ -604,13 +623,15 @@ Other useful things you can do with Telescope: - description * - :kbd:`fb` - - Toggle file browser + - Toggles file browser sidebar showing directory tree. Navigate with j/k, + Enter to open files/folders, q to close * - :kbd:`-` (within browser) - - Go up a directory. + - Navigate up one directory level * - :kbd:`Enter` (within browser) - - Open file or directory, or close directory + - Opens file in editor, expands directory to show contents, or collapses + open directory The window-switching shortcuts :kbd:`w` and :kbd:`q` (move to windows left and right respectively; see :ref:`toggleterm_ref`) also work. @@ -706,10 +727,13 @@ contents. - description * - :kbd:`a` - - Toggle aerial sidebar + - Toggles aerial navigation sidebar showing code structure outline + (functions, classes, methods). Navigate with j/k, Enter to jump to item, + q to close * - :kbd:`{` and :kbd:`}` - - Jump to prev or next item (function, snakemake rule, markdown section) + - Jump to previous (`{`) or next (`}`) code item in the buffer (function, + class, snakemake rule, markdown section) For navigating complex codebases, there are other keys that are automatically mapped, which you can read about in the `README for aerial @@ -738,7 +762,8 @@ tabs along the top. * - command - description * - :kbd:`b`, then type highlighted letter in tab - - Switch to buffer + - Enters buffer-pick mode: each open buffer tab shows a letter. Type that + letter to switch to the corresponding buffer .. plugin-metadata:: :name: bufferline @@ -834,7 +859,9 @@ useful when reviewing a long RMarkdown file to focus on the narrative text. - description * - :kbd:`rm` - - Toggle [r]ender[m]arkdown on an [r][m]arkdown file + - Toggles render-markdown on/off for the current markdown file. When on, + shows enhanced formatting (bullets, tables, code blocks). When off, shows + raw markdown. Mnemonic: [r]ender [m]arkdown .. plugin-metadata:: :name: render-markdown @@ -1058,32 +1085,37 @@ the terminal use. - description * - :kbd:`t` - - Open terminal to the right. + - Opens a terminal in a vertical split on the right side. Terminal starts + in insert mode ready for commands * - :kbd:`w` - - Move to the right window (assumes it's terminal), and enter insert mode + - Switches focus to the right window (typically the terminal) and enters + insert mode automatically * - :kbd:`q` - - Move to the text buffer to the left, and enter normal mode + - Switches focus back to the left window (typically the text buffer) and + enters normal mode for editing * - :kbd:`cd` - - Send the current RMarkdown code chunk to the terminal, and jump to the - next chunk + - Sends the current RMarkdown code chunk to terminal for execution, then + automatically jumps cursor to the next chunk. Great for interactive data + analysis * - :kbd:`gxx` - - Send the current *line* to the terminal buffer + - Sends the current line under cursor to the terminal and executes it. + Useful for running single commands * - :kbd:`gx` - - Send the current *selection* to the terminal buffer + - Sends the currently selected text (visual mode) to the terminal and + executes it. Useful for running multiple lines - * - :kbd:`k` - - Render the current RMarkdown file to HTML using `knitr::render()`. - Assumes you have knitr installed and you're running R in the terminal - buffer. + * - :kbd:`k` (in RMarkdown file) + - Renders the current RMarkdown file to HTML using `knitr::render()`. + Requires knitr installed and R running in terminal - * - :kbd:`k` - - Run the current Python script in IPython. Assumes you're running - IPython in the terminal buffer. + * - :kbd:`k` (in Python file) + - Runs the current Python script in IPython using `%run` magic command. + Requires IPython running in terminal .. plugin-metadata:: :name: toggleterm diff --git a/docs/starthere.rst b/docs/starthere.rst index c2f518c..6e14e48 100644 --- a/docs/starthere.rst +++ b/docs/starthere.rst @@ -183,16 +183,21 @@ more help on deciding. changed. Please see :ref:`nvim-lua` for more context, rationale, and details on migrating to this new config method. -Plugins are managed via the `lazy.nvim `_ -manager. Simply opening neovim should be sufficient to trigger ``lazy.nvim`` to -bootstrap itself and then download, install, and configure plugins -automatically. +After closing and reopening your terminal from step 2b, now open neovim to +trigger automatic plugin installation. Plugins are managed via the `lazy.nvim +`_ manager, which will bootstrap itself and +then download, install, and configure all plugins automatically. -Or you can run this command to have it quit automatically when it's done: +.. code-block:: bash + + nvim + # Wait for plugins to download and install (you'll see progress messages) + # When everything is finished, quit with :q + +Or run this command to install plugins and quit automatically when done: .. code-block:: bash - # this will open nvim, install plugins, and quit when done nvim +"lua require('lazy').restore({wait=true})" +q .. details:: Details @@ -235,17 +240,17 @@ details on how to activate environments. .. details:: Details - First, this downloads the latest version of `Mambaforge + First, this downloads the latest version of `Miniforge `_, and installs conda and mamba - into :file:`~/mambaforge/condabin`. + into :file:`~/miniforge/condabin`. - Then it adds the line ``export PATH="$PATH:~/mambaforge/condabin"`` to the + Then it adds the line ``export PATH="$PATH:~/miniforge/condabin"`` to the :file:`~/.path` (which you can read more about at :ref:`bash`). If you happen to be on NIH's Biowulf cluster where the home directory is too small to support the installation, this will auto-detect that and install instead to - :file:`/data/$USER/mambaforge/condabin` and add the line ``export - PATH="$PATH:~/data/$USER/mambaforge/condabin`` to the :file:`~/.path` + :file:`/data/$USER/miniforge/condabin` and add the line ``export + PATH="$PATH:~/data/$USER/miniforge/condabin`` to the :file:`~/.path` Finally, ``./setup.sh --set-up-bioconda`` sets up the bioconda and conda-forge channels in the right way as documented by `Bioconda