using-neovim: search-replace with grug-far

resolve: #77

Author: practicalli-johnny

CHANGELOG.md

@@ -32,6 +32,7 @@
 - dev: book configuration & make task for deploying to staging
 - dev: add scheduled stale issue & pull request check
 - intro: troubleshoot guide with examples
+- using-neovim: search-replace with grug-far
 
 ### Changed
 - ci: spell lychee & repository trufflehog linters warn only (false positives)

docs/using-neovim/search-replace/grug-far.md

@@ -0,0 +1,48 @@
+# Grug Far
+
+A very efficient search and replace tool using the external [ripgrep command](https://github.com/BurntSushi/ripgrep/blob/master/GUIDE.md) line tool.
+
+++spc++ ++"s"++ is the search and replace menu
+
+++"g"++ ++"?"++ for help menu in the Grug-far buffer
+
+
+!!! NOTE "Search and replace with Grug-Far"
+
+    ++spc++ ++"s"++ ++"s"++ to search across the current workspace (project)
+
+    Enter a Search pattern, press ++esc++ and all occurrences across the project are shown
+
+    Enter a Replace pattern, press ++esc++ to see occurrences with their replacement
+
+    ++comma++ ++"r"++ to replace all occurrences with the replace pattern
+
+    ++comma++ ++"j"++ / ++"k"++ replace at current line & move to next / previous change
+
+
+
+??? TIP "Search results in Quicklist"
+    ++comma++ ++"q"++ adds search results to quickfix list to edit occurrences with other Neovim tools
+
+
+## Search buffer
+
+Enter patterns in the **Search** and **Replace** and the results are show in a diff below.
+
+++tab++ and ++shift++ ++tab++ navigate between search buffer sections.
+
+![Grug-Far Search buffer](https://github.com/practicalli/graphic-design/blob/live/editors/neovim/astronvim-5/neovim-search-grug-far-search-dark.png?raw=true){loading=lazy}
+
+??? EXAMPLE "Usefull Ripgrep options for Grug-Far"
+    - `-i/--ignore-case`: ignore case differences, e.g. `rg -i fast` matches `fast`, `fASt`, `FAST`, etc.
+    - `-F/--fixed-strings`: Disable regular expression matching and treat the pattern as a literal string.
+    - `-w/--word-regexp`: pattern matches are surrounded by word boundaries, e.g. `pattern` is `\b(?:pattern)\b`.
+    - `-c/--count`: a count of total matched lines.
+    - `-a/--text`: Search binary files as if they were plain text.
+    - `-U/--multiline`: Permit matches to span multiple lines.
+    - `-z/--search-zip`: Search compressed files (gzip, bzip2, lzma, xz, lz4, brotli, zstd). This is disabled by default.
+    - `-C/--context`: Show the lines surrounding a match.
+    - `-L/--follow`: Follow symbolic links while recursively searching.
+    - `-M/--max-columns`: Limit the length of lines printed by ripgrep.
+
+    [All Ripgrep Options](https://github.com/BurntSushi/ripgrep/blob/master/GUIDE.md#common-options)

docs/using-neovim/search-replace/index.md

@@ -4,8 +4,8 @@ Neovim has several built-in commands to search for patterns in the current buffe
 
 Additional tools that work across all the files in a project:
 
-- ++spc++ ++"s"++ ++"s"++ [search and replace commands using Spectre](#spectre)
-- ++spc++ ++"l"++ ++"r"++ to rename symbols using [Clojure LSP](/neovim/repl-driven-development/refactor-tools/)
+- ++spc++ ++"s"++ ++"s"++ search and replace using [Grug-far](grug-far.md)
+- ++spc++ ++"l"++ ++"r"++ to rename symbols using [Clojure LSP](/neovim/clojure-repl-workflow/refactor-tools/)
 
 > [:fontawesome-solid-book-open: multiple cursors](../multiple-cursors.md) for in-place editing within a buffer
 
@@ -54,34 +54,6 @@ Use search to populate the Neovim quickfix list and change occurrences across al
     Including the `c` option to confirm each replacement
 
 
-
-### Spectre
-
-[:fontawesome-solid-book-open: Spectre](spectre.md){target=_blank} shows occurrences of a pattern throughout all project files, replace individual or all occurrences.
-
-!!! EXAMPLE "Search and replace with Spectre"
-
-    ++spc++ ++"s"++ is the search and replace menu
-
-    Enter a Search pattern and all occurrences across the project are shown
-
-    Enter a Replace pattern to see occurrences with their replacement
-
-    ++"R"++ to replace all occurrences with the replace pattern
-
-    ++"C"++ to replace current occurrence
-
-
-++"q"++ adds the Spectre search results to quickfix list to edit occurrences with other Neovim tools
-
-
-![nvim-spectr](https://github.com/windwp/nvim-spectre/wiki/assets/demospectre.gif)
-
-[:globe_with_meridians: ripgrep](https://github.com/BurntSushi/ripgrep){target=_blank} and [:globe_with_meridians: sed](https://www.gnu.org/software/sed/) are required.
-
-[:globe_with_meridians: Spectre](https://github.com/nvim-pack/nvim-spectre){target=_blank .md-button}
-
-
 <!-- TODO: review :cdo and similar commands
 
     use ack.vim/ag.vim with the :cdo command, an intuitive and near-native project-wide find-and-replace solution is now available.

docs/using-neovim/search-replace/spectre.md

@@ -1,5 +1,7 @@
 # Spectre
 
+!!! WARNING "Not included in Astro 5 - see Grug-Far"
+
 ++spc++ ++"s"++ ++"s"++ to toggle Spectre (open/close) to search and replace tool.
 
 `?` for the Spectre key mappings
@@ -19,7 +21,7 @@
 ![Neovim Spectre search replace](https://github.com/practicalli/graphic-design/blob/live/editors/neovim/screenshots/neovim-search-replace-spectre-search-dark.png?raw=true#only-light){loading=lazy}
 
 
-++"d"++ ++"d"++ to toggle an occurance 
+++"d"++ ++"d"++ to toggle an occurance
 
  ++"R"++ replaces all occurances (after selecting the occurances to change)
 
@@ -35,9 +37,8 @@ A DONE checkbox is show at then end of each selection which has been reaplaced
     Use Git or Neovim undo to rollback changes made by Spectre.
 
 
-[:globe_with_meridians: Spectre](https://github.com/nvim-pack/nvim-spectre){target=_blank} is available via the AstroNvim Community project pack and included in the Practicalli astronvim-config    
+[:globe_with_meridians: Spectre](https://github.com/nvim-pack/nvim-spectre){target=_blank} is available via the AstroNvim Community project pack and included in the Practicalli astronvim-config
 
 [:globe_with_meridians: ripgrep](https://github.com/BurntSushi/ripgrep){target=_blank} and [:globe_with_meridians: sed](https://www.gnu.org/software/sed/) are required.
 
-[:fontawesome-brands-github: Spectre project](https://github.com/nvim-pack/nvim-spectre){target=_blank .md-button}    
-
+[:fontawesome-brands-github: Spectre project](https://github.com/nvim-pack/nvim-spectre){target=_blank .md-button}

mkdocs.yml

@@ -152,6 +152,7 @@ nav:
       - Registers: using-neovim/registers.md
       - Search Replace:
           - using-neovim/search-replace/index.md
+          - Grug-Far: using-neovim/search-replace/grug-far.md
           - Substitute: using-neovim/search-replace/substitute.md
           - Spectre: using-neovim/search-replace/spectre.md
       - Spell Check: neovim-basics/spell-check.md