¿Qué es SHELL-FORMAT en envsubst?

Cuando me topé envsubst, quería usarlo para reemplazar solo variables específicas y sospeché que el parámetro SHELL-FORMAT podría ser lo que se desea, pero no puedo hacerlo funcionar.

Desafortunadamente, las páginas many infono dan ningún ejemplo de uso y solo dicen

Si se proporciona SHELL-FORMAT, solo se sustituyen las variables de entorno a las que se hace referencia en SHELL-FORMAT

Lo que no me dice cómo hacer referencia a ellos.

Como lo indica el texto, solo tiene que hacer referencia (por ejemplo, por $VARNAMEo ${VARNAME}) a las variables como en un comando de shell habitual. Sin embargo, debe asegurarse de que el shell no los expanda de antemano.

Aquí hay algunos ejemplos para ilustrar esto (suponiendo export FOO=BAR):

$ echo '$FOO$FOO2' | envsubst
BAR

Como puede ver, $ FOO2 ha sido reemplazado por "" porque no estaba definido. Ahora podemos restringir ese reemplazo a solo $ FOO al:

$ echo '$FOO$FOO2' | envsubst '$FOO'
BAR$FOO2

usar en ""lugar de ''llevaría a la sustitución antes de que se desee:

echo '$FOO$FOO2' | envsubst "$FOO"
$FOO$FOO2

(Esto equivale a la llamada efectiva envsubst "BAR"que no detecta variables, por lo que ninguna se reemplaza).

Como mandice la página, todas las variables a las que se hace referencia SHELL-FORMATse reemplazan, por lo que incluso podemos hacer esto:

echo '$FOO$FOO2$FOO3' | envsubst '$FOO some more text ${FOO3}'
BAR$FOO2

Como puede ver, el SHELL-FORMATes bastante flexible.

Finalmente, el parámetro le --variablespermite evaluar qué variables se seleccionan para su sustitución por SHELL-FORMAT:

envsubst --variables '$FOO some more text ${FOO3}'
FOO
FOO3

En el ejemplo de sustitución prematura de arriba, esto habría mostrado el error:

$ envsubst --variables "$FOO"
(empty string returned)

Como se indica en la página man, envsubstno procesa ninguna entrada estándar cuando --variablesestá presente.

Aquí hay algunos ejemplos que me ayudaron a entender cómo usarlo correctamente. Me sorprendió que envustosamente reemplaza las variables mencionadas en el parámetro.

$ export FOOX="foox"
$ export FOOY="fooy"
$ export FOOZ="fooz"

$ echo 'x $FOOX y $FOOY z $FOOZ' | envsubst            
x foox y fooy z fooz

$ echo 'x $FOOX y $FOOY z $FOOZ' | envsubst '$FOOX'
x foox y $FOOY z $FOOZ

$ echo 'x $FOOX y $FOOY z $FOOZ' | envsubst '$FOOX $FOOZ'
x foox y $FOOY z fooz

$ echo 'x $FOOX y $FOOY z $FOOZ' | envsubst '$FOOZ $FOOY'
x $FOOX y fooy z fooz

Tampoco entendí lo que significaba SHELL-FORMAT, todavía no sé por qué se llama así. Pero después de los experimentos anteriores, creo que sé lo que hace.

La palabrería es un poco de confusión. Para reformular el texto de ayuda de forma más meticulosa:

SHELL-FORMATes un argumento opcional de línea de comando de texto que contiene referencias a variables de entorno. Para hacer referencia a una variable de entorno en el texto, prefije el nombre de la variable con a $. Por ejemplo: hace Hello $FOO World $BARreferencia a variables de entorno FOOy BAR. El resto de la cadena se ignora. Si el SHELL-FORMATargumento de la línea de comando está presente, cuando se produce una sustitución de variable en el texto recibido a través de stdin, se limitará a las variables a las que se hace referencia en el SHELL-FORMATargumento de la línea de comando.

Entonces, para responder su pregunta explícitamente: Prefije el nombre de la variable con $.