feat: Allow bash users to specify a precmd function (#166)

Allows bash users to run a function before the shell is drawn, by defining a function and setting its name equal to starship_precmd_user_func.

3 files changed, 77 insertions, 1 deletions

diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
index 1bd8bab4c..c06583f3f 100644
--- a/docs/.vuepress/config.js
+++ b/docs/.vuepress/config.js
@@ -9,7 +9,8 @@ module.exports = {
     sidebar: [
       '/',
       ['/guide/', 'Guide'],
-      ['/config/', 'Configuration']
+      ['/config/', 'Configuration'],
+      ['/advanced-config/', 'Advanced Configuration']
     ],
     nav: [
       { text: 'Configuration', link: '/config/' },
diff --git a/docs/advanced-config/README.md b/docs/advanced-config/README.md
new file mode 100644
index 000000000..15a9af22a
--- /dev/null
+++ b/docs/advanced-config/README.md
@@ -0,0 +1,74 @@
+# Advanced Configuration
+
+While Starship is a versatile shell, sometimes you need to do more than edit
+`starship.toml` to get it to do certain things. This page details some of the more
+advanced configuration techniques used in starship.
+
+::: warning
+The configurations in this section are subject to change in future releases of Starship.
+:::
+
+## Custom pre-prompt and pre-execution Commands in Bash
+
+Bash does not have a formal preexec/precmd framework like most other shells.
+Because of this, it is difficult to provide fully customizable hooks in `bash`.
+However, Starship does give you limited ability to insert your own functions
+into the prompt-rendering procedure:
+
+- To run a custom function right before the prompt is drawn, define a new
+  function and then assign its name to `starship_precmd_user_func`. For example,
+  to draw a rocket before the prompt, you would do
+
+```bash
+function blastoff(){
+    echo "🚀"
+}
+starship_precmd_user_func="blastoff"
+```
+
+- To run a custom function right before a command runs, you can use the 
+  [`DEBUG` trap mechanism](https://jichu4n.com/posts/debug-trap-and-prompt_command-in-bash/).
+  However, you **must** trap the DEBUG signal *before* initializing Starship!
+  Starship can preserve the value of the DEBUG trap, but if the trap is overwritten
+  after starship starts up, some functionality will break.
+
+```bash
+function blastoff(){
+    echo "🚀"
+}
+trap blastoff DEBUG     # Trap DEBUG *before* running starship
+eval $(starship init bash)
+```
+
+## Change Window Title
+
+Some shell prompts will automatically change the window title for you (e.g. to 
+reflect your working directory). Fish even does it by default.
+Starship does not do this, but it's fairly straightforward to add this
+functionality to `bash` or `zsh`.
+
+First, define a window title change function (identical in bash and zsh):
+
+```bash
+function set_win_title(){
+    echo -ne "\033]0; YOUR_WINDOW_TITLE_HERE \007"
+}
+```
+
+You can use variables to customize this title (`$USER`, `$HOSTNAME`, and `$PWD`
+are popular choices).
+
+In `bash`, set this function to be the precmd starship function:
+
+```bash
+starship_precmd_user_func="set_win_title"
+```
+
+In `zsh`, add this to the `precmd_functions` array:
+
+```bash
+precmd_functions+=(set_win_title)
+```
+
+If you like the result, add these lines to your shell configuration file 
+(`~/.bashrc` or `~/.zsrhc`) to make it permanent.
diff --git a/src/init.rs b/src/init.rs
index 4aed1f14d..d4afefe00 100644
--- a/src/init.rs
+++ b/src/init.rs
@@ -92,6 +92,7 @@ starship_preexec() {
 };
 starship_precmd() {
     STATUS=$?;
+    "${starship_precmd_user_func-:}";
     if [[ $STARSHIP_START_TIME ]]; then
         STARSHIP_END_TIME=$(date +%s);
         STARSHIP_DURATION=$((STARSHIP_END_TIME - STARSHIP_START_TIME));