From 490888dd417b157788d26e2d54b0379da1f50150 Mon Sep 17 00:00:00 2001
From: Ewa Czechowska <ewa@kudulab.io>
Date: Fri, 14 Aug 2020 08:34:07 +0100
Subject: [PATCH] update readme with preserving exported bash functions and
 slim the changelog entry #17

---
 CHANGELOG.md | 44 +++-----------------------------------------
 README.md    | 31 +++++++++++++++++++++++++++++++
 2 files changed, 34 insertions(+), 41 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e0cd03d..f095602 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,50 +1,12 @@
 ### 0.9.0 (2020-Aug-13)
 
-* support exported bash functions https://github.com/kudulab/dojo/issues/17
-  **TLDR**:
-  Dojo resulted in an error when any bash function
-   was exported, since 0.9.0 it will succeed. However, in order to preserve all the exported bash functions, you
+* support exported bash functions [#17](https://github.com/kudulab/dojo/issues/17).
+   Earlier, Dojo resulted in an error when any bash function was exported. Now,
+   it will succeed. However, in order to preserve all the exported bash functions, you
    need to run:
    ```
    source /etc/dojo.d/variables/01-bash-functions.sh
    ```
-  **Long vesion**:
-  Whenever a bash function is exported in the following way:
-  ```
-  my_bash_func() {
-	  echo "hello"
-	}
-  export -f my_bash_func
-	```
-  Bash creates an environment variable, in this case:
-  ```
-	BASH_FUNC_my_bash_func%%=() {  echo "hello"
-	}
-  ```
-  So far, when there was any bash function exported, Dojo resulted in an error like:
-  ```
-  13-08-2020 19:53:43 Dojo entrypoint info: Sourcing: /etc/dojo.d/variables/00-multiline-vars.sh
-  /etc/dojo.d/variables/00-multiline-vars.sh: line 1: export: `DOJO_BASH_FUNC_my_bash_func%%=()': not a valid identifier
-  /etc/dojo.d/variables/00-multiline-vars.sh: line 1: export: `{': not a valid identifier
-  /etc/dojo.d/variables/00-multiline-vars.sh: line 1: export: `"hello"': not a valid identifier
-  /etc/dojo.d/variables/00-multiline-vars.sh: line 1: export: `}': not a valid identifier
-  ```
-  This was made visible when using Bats-core v1.2.1, because they exported
-  a bash function [in this PR](https://github.com/bats-core/bats-core/pull/312/files).
-  Dojo interpreted this bash environment variable as a multiline variable and
-  attempted to serialize it with base64. It was fine, but deserialization lead to
-  the error above.
-  Dojo 0.9.0 treats all the environment variables which names start with "BASH_FUNC_"
-  prefix and which values start with "()" as exported bash functions and serializes them into
-  /etc/dojo.d/variables/01-bash-functions.sh file. This file is sourced at
-  a container start. However, the bash functions are not preserved later,
-  because `sudo -E` (used in Dojo entrypoint) does not preserve exported
-  bash functions after ShellShock. See [this](https://unix.stackexchange.com/questions/549140/why-doesnt-sudo-e-preserve-the-function-environment-variables-exported-by-ex) and [this](https://unix.stackexchange.com/a/233097).
-  It was decided that Dojo 0.9.0 should follow the sudo's practice and not try to
-  add a work around leading to bash functions being preserved. But, it was made easy for the end user to preserve them with:
-  ```
-  source /etc/dojo.d/variables/01-bash-functions.sh
-  ```
 
 ### 0.8.0 (2020-Jan-01)
 
diff --git a/README.md b/README.md
index 1578245..83917b5 100644
--- a/README.md
+++ b/README.md
@@ -668,6 +668,37 @@ dojo --docker-options="--init" --image=alpine:3.8 -i=false sh -c "echo 'will sle
 dojo --driver=docker-compose --dcf=./test/test-files/itest-dc.yaml -i=false --image=alpine:3.8 sh -c "echo 'will sleep' && sleep 1d"
 ```
 
+### Preserving exported Bash functions [#17](https://github.com/kudulab/dojo/issues/17)
+
+*Needs Dojo >= 0.9.0*, earlier Dojo versions will result in an error like:
+```
+13-08-2020 19:53:43 Dojo entrypoint info: Sourcing: /etc/dojo.d/variables/00-multiline-vars.sh
+/etc/dojo.d/variables/00-multiline-vars.sh: line 1: export: `DOJO_BASH_FUNC_my_bash_func%%=()': not a valid identifier
+/etc/dojo.d/variables/00-multiline-vars.sh: line 1: export: `{': not a valid identifier
+/etc/dojo.d/variables/00-multiline-vars.sh: line 1: export: `"hello"': not a valid identifier
+/etc/dojo.d/variables/00-multiline-vars.sh: line 1: export: `}': not a valid identifier
+```
+
+---
+
+You may want to have your **locally exported Bash functions available in a Dojo Docker image**. For example, you have defined and exported such a Bash function:
+```
+my_bash_func() {
+  echo "hello"
+}
+export -f my_bash_func
+```
+
+This function (and all the other exported Bash functions) will be saved into the file `/etc/dojo.d/variables/01-bash-functions.sh` inside a Dojo Docker image. This is done automatically, by Dojo, on a container start. In order **to be able to invoke a function in a Dojo Docker image, you have to run**:
+```
+source /etc/dojo.d/variables/01-bash-functions.sh
+```
+
+If you use Dojo and Bats-core v1.2.1, use Dojo >= 0.9.0.
+
+Due to using Sudo in Dojo images standard entrypoint, exported bash functions are not preserved and that is why you have to source the file yourself. Preserving Bash functions by Sudo was removed after Shellshock, see [this](https://unix.stackexchange.com/questions/549140/why-doesnt-sudo-e-preserve-the-function-environment-variables-exported-by-ex) and [this](https://unix.stackexchange.com/a/233097).
+
+
 # FAQ
 
 ### Will Dojo work with any docker image?