# envsubst — Umgebungsvariablen in Texten ersetzen

> Praxis-Guide zu envsubst (GNU gettext): Umgebungsvariablen in Templates und Textdateien ersetzen — sicher, ohne Shell-Expansion.

Source: https://www.jpkc.com/db/cheatsheets/files-text/envsubst/

<!-- PROSE:intro -->
envsubst gehört zu GNU gettext und ersetzt in einem Text alle Referenzen der Form `$VAR` und `${VAR}` durch die Werte gleichnamiger Umgebungsvariablen. Anders als `eval` oder eine Shell führt es dabei **keine** Shell-Expansion durch – keine Befehlssubstitution, kein Globbing, keine Anführungszeichen-Tricks –, sondern tauscht ausschließlich Variablen aus. Genau das macht es zum sicheren Werkzeug, um Templates wie nginx-Konfigurationen, `.env`-Dateien oder Kubernetes-Manifeste mit Werten aus der Umgebung zu füllen. Mit einem Argument wie `'$VAR1 $VAR2'` begrenzt du die Ersetzung auf bestimmte Variablen, sodass andere Platzhalter (etwa nginx-eigene wie `$uri`) unangetastet bleiben. Dieser Guide zeigt dir die Aufrufe, die du im Alltag von Docker-Entrypoints bis CI/CD-Pipelines wirklich brauchst.
<!-- PROSE:intro:end -->

## Grundlegende Verwendung

`envsubst < <template> > <output>` — Ersetzt alle `$VAR`- und `${VAR}`-Referenzen durch ihre Werte.

```bash
envsubst < config.template > config.conf
```

`echo '$HOME' | envsubst` — Ersetzt Variablen in weitergeleitetem Text.

```bash
echo 'Hello $USER, your home is $HOME' | envsubst
```

`envsubst < <template>` — Gibt den ersetzten Inhalt auf stdout aus.

```bash
envsubst < nginx.conf.template
```

`cat <template> | envsubst > <output>` — Leitet ein Template durch envsubst.

```bash
cat docker-compose.yml.tmpl | envsubst > docker-compose.yml
```

## Variablen einschränken

`envsubst '$VAR1 $VAR2' < <template>` — Ersetzt nur bestimmte Variablen (alle anderen bleiben unverändert).

```bash
envsubst '$DB_HOST $DB_PORT' < config.template > config.conf
```

`envsubst '${VAR1}' < <template>` — Ersetzt nur eine einzige bestimmte Variable.

```bash
envsubst '${APP_VERSION}' < version.txt.tmpl > version.txt
```

`envsubst --variables '<shell-format>'` — Listet alle im Argument referenzierten Variablennamen auf.

```bash
envsubst --variables "$(cat nginx.conf.template)"
```

## Docker- und Container-Einsatz

`envsubst < /etc/nginx/conf.d/default.conf.template > /etc/nginx/conf.d/default.conf` — Erzeugt eine nginx-Konfiguration im Docker-Entrypoint.

```bash
envsubst '${NGINX_HOST} ${NGINX_PORT}' < default.conf.template > /etc/nginx/conf.d/default.conf
```

`envsubst < app.env.template > .env` — Erzeugt während des Deployments eine `.env`-Datei aus einem Template.

```bash
envsubst < app.env.template > .env
```

`envsubst '$VAR' < template` — Ersetzt nur ausgewählte Variablen; alle übrigen `${...}`-Referenzen bleiben wörtlich erhalten.

```bash
echo 'Home: $HOME, behalten: ${BUILD_ID}' | envsubst '$HOME'
```

## CI/CD und Skripte

`export VAR=value && envsubst < template > output` — Setzt eine Variable und ersetzt sie in einer Befehlskette.

```bash
export VERSION=1.2.3 && envsubst < manifest.yml.tmpl > manifest.yml
```

`VAR=value envsubst < template` — Definiert eine Variable inline für den envsubst-Aufruf.

```bash
APP_NAME=myapp envsubst < deploy.yaml.tmpl
```

`env $(cat .env | xargs) envsubst < template` — Lädt Variablen aus einer `.env`-Datei und ersetzt sie.

```bash
env $(cat .env | xargs) envsubst < config.template > config.conf
```

`envsubst < k8s/deployment.yaml.tmpl | kubectl apply -f -` — Füllt ein Kubernetes-Manifest und wendet es direkt an.

```bash
export IMAGE_TAG=v2.0 && envsubst < k8s/deployment.yaml.tmpl | kubectl apply -f -
```

## Typische Muster

`for f in *.tmpl; do envsubst < "$f" > "${f%.tmpl}"; done` — Verarbeitet alle Template-Dateien und entfernt die Endung `.tmpl`.

```bash
for f in conf/*.tmpl; do envsubst < "$f" > "${f%.tmpl}"; done
```

`envsubst --variables "$(cat template)" | sort` — Listet alle für ein Template benötigten Variablen auf.

```bash
envsubst --variables "$(cat nginx.conf.template)" | sort
```

`envsubst < template | diff template -` — Zeigt, was in einem Template ersetzt wurde.

```bash
envsubst < config.template | diff config.template -
```

<!-- PROSE:outro -->
## Fazit

Die Stärke von envsubst ist die **sichere, eng begrenzte Ersetzung**: Es tauscht nur `$VAR`/`${VAR}` aus und führt im Gegensatz zu `eval` oder einer Shell keinerlei Befehle aus – ideal, um nicht vertrauenswürdige Templates zu füllen. Übergibst du eine Shell-Format-Zeichenkette wie `'$DB_HOST $DB_PORT'`, beschränkt envsubst die Ersetzung exakt auf diese Variablen; alle anderen Platzhalter (etwa nginx-eigene wie `$uri`) bleiben wörtlich stehen. Beachte dabei eine Falle: Nicht gesetzte Variablen werden kommentarlos durch einen **leeren String** ersetzt, nicht etwa als Fehler gemeldet – prüfe mit `envsubst --variables`, ob wirklich alle benötigten Werte in der Umgebung stehen, bevor du das Ergebnis weiterverwendest. Einen `$$`-Escape für ein literales Dollarzeichen kennt envsubst nicht; um eine Referenz wörtlich zu erhalten, nimmst du sie einfach aus der Liste der zu ersetzenden Variablen heraus.

## Weiterführende Links

- [GNU gettext: envsubst Invocation](https://www.gnu.org/software/gettext/manual/html_node/envsubst-Invocation.html) – offizielle Referenz zu Aufruf und Optionen (englisch)
- [GNU gettext: The Programmer's View](https://www.gnu.org/software/gettext/manual/html_node/index.html) – Handbuch zum gesamten gettext-Paket, zu dem envsubst gehört (englisch)
<!-- PROSE:outro:end -->

## Verwandte Kommandos

- [sed](https://www.jpkc.com/db/cheatsheets/files-text/sed/) – Stream-Editor zum zeilenweisen Suchen und Ersetzen in Textströmen
- [tr](https://www.jpkc.com/db/cheatsheets/files-text/tr/) – ersetzt oder löscht einzelne Zeichen aus einem Textstrom
- [tee](https://www.jpkc.com/db/cheatsheets/files-text/tee/) – schreibt einen Datenstrom gleichzeitig in Datei und auf stdout