Document the percent sigil

book/aliases.md

@@ -63,42 +63,13 @@ displaying all listed files and folders in a grid.
 ## Replacing Existing Commands Using Aliases
 
 ::: warning Caution!
-When replacing commands it is best to "back up" the command first and avoid recursion error.
+When replacing commands, use the percent sigil `%` to call the builtin command and avoid recursion error.
 :::
 
-How to back up a command like `ls`:
-
-```nu
-alias core-ls = ls    # This will create a new alias core-ls for ls
-```
-
-Now you can use `core-ls` as `ls` in your nu-programming. You will see further down how to use `core-ls`.
-
-The reason you need to use alias is because, unlike `def`, aliases are position-dependent. So, you need to "back up" the old command first with an alias, before re-defining it.
-If you do not backup the command and you replace the command using `def` you get a recursion error.
-
-```nu
-def ls [] { ls }; ls    # Do *NOT* do this! This will throw a recursion error
-
-#output:
-#Error: nu::shell::recursion_limit_reached
-#
-#  × Recursion limit (50) reached
-#     ╭─[C:\Users\zolodev\AppData\Roaming\nushell\config.nu:807:1]
-# 807 │
-# 808 │ def ls [] { ls }; ls
-#     ·           ───┬──
-#     ·              ╰── This called itself too many times
-#     ╰────
-```
-
 The recommended way to replace an existing command is to shadow the command.
 Here is an example shadowing the `ls` command.
 
 ```nu
-# alias the built-in ls command to ls-builtins
-alias ls-builtin = ls
-
 # List the filenames, sizes, and modification times of items in a directory.
 def ls [
     --all (-a),         # Show hidden files
@@ -112,7 +83,7 @@ def ls [
     ...pattern: glob,   # The glob pattern to use.
 ]: [ nothing -> table ] {
     let pattern = if ($pattern | is-empty) { [ '.' ] } else { $pattern }
-    (ls-builtin
+    (%ls
         --all=$all
         --long=$long
         --short-names=$short_names
@@ -125,3 +96,31 @@ def ls [
     ) | sort-by type name -i
 }
 ```
+
+Forgetting the `%` will lead to an error:
+
+```nu
+def ls [] { ls }; ls    # Do *NOT* do this! This will throw a recursion error
+
+#output:
+#Error: nu::shell::recursion_limit_reached
+#
+#  × Recursion limit (50) reached
+#     ╭─[C:\Users\zolodev\AppData\Roaming\nushell\config.nu:807:1]
+# 807 │
+# 808 │ def ls [] { ls }; ls
+#     ·           ───┬──
+#     ·              ╰── This called itself too many times
+#     ╰────
+```
+
+If you want to wrap an already defined (non-built-in) function, you can use alias to "back up" the original
+
+```nu
+alias ls-prev = ls
+def ls [] {
+    ls-prev | table --icons
+}
+```
+
+You can use alias is because, unlike `def`, aliases are position-dependent. So, you can "back up" the old command first with an alias, before re-defining it.