From 0779a461794ebfec0690ef5652a67b86407b5571 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=B6rn=20Zaefferer?= <joern.zaefferer@gmail.com>
Date: Sun, 3 May 2020 06:49:27 +0200
Subject: [PATCH] docs/commands: add alias.md (#1697)

* docs/commands: add alias.md

* docs/commands/alias: drop reference to bash
---
 docs/commands/alias.md | 62 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)
 create mode 100644 docs/commands/alias.md

diff --git a/docs/commands/alias.md b/docs/commands/alias.md
new file mode 100644
index 000000000..d0a46eee6
--- /dev/null
+++ b/docs/commands/alias.md
@@ -0,0 +1,62 @@
+# alias
+This command allows you to define shortcuts for other common commands.
+
+The command expects three parameters:
+* the name of alias
+* the parameters as a space-separated list (`[a b ...]`), can be empty (`[]`)
+* the body of the alias as a `{...}` block
+
+## Examples
+
+Define a custom `myecho` command as an alias:
+```shell
+> alias myecho [msg] { echo $msg }
+> myecho "hello world"
+hello world
+```
+
+Since the parameters are well defined, calling the command with the wrong number of parameters will fail properly:
+```shell
+> myecho hello world
+error: myecho unexpected world
+- shell:1:18
+1 | myecho hello world
+  |              ^^^^^ unexpected argument (try myecho -h)
+```
+
+The suggested help command works!
+```shell
+> myecho -h
+
+Usage:
+  > myecho ($msg) {flags}
+
+parameters:
+  ($msg)
+
+flags:
+  -h, --help: Display this help message
+```
+
+## Persistent aliases
+
+Aliases are most useful when they are persistent. For that, add them to your startup config:
+```
+> config --set [startup ["alias myecho [msg] { echo $msg }"]]
+```
+This is fine for the first alias, but since it overwrites the startup config, you need a different approach for additional aliases.
+
+To add a 2nd alias:
+```
+config --get startup | append "alias s [] { git status -sb }" | config --set_into startup
+```
+This first reads the `startup` config (a table of strings), then appends another alias, then sets the `startup` config with the output of the pipeline.
+
+To make this process easier, you could define another alias:
+```
+> alias addalias [alias-string] { config --get startup | append $alias-string | config --set_into startup }
+```
+Then use that to add more aliases:
+```
+addalias "alias s [] { git status -sb }"
+```