pushd

pushd – shell builtin do zarządzania stosem katalogów i szybkiej nawigacji. Dodaje katalog na stos i zwykle przechodzi do niego (zmienia $PWD).
Typowe zastosowania: praca naprzemiennie w kilku ścieżkach (repozytoria, build, logi), skrypty wdrożeniowe, sesje administracyjne.
Dostępne w: bash, zsh, ksh, tcsh (składnia i opcje mogą się różnić). W prostych powłokach (sh/dash) zwykle brak pushd/popd.

Składnia

pushd [-n] [+N | -N | <katalog>]

Bez argumentów: zamienia miejscami dwa pierwsze wpisy stosu (bash) i przechodzi do nowego wierzchołka; wymaga co najmniej dwóch elementów stosu.
+N – rotuje stos tak, by element o indeksie N (od lewej) stał się wierzchołkiem (jak w dirs -v).
-N – rotuje od prawej: element N (od prawej) na wierzchołek (-0 to ostatni element).
<katalog> – dołóż bieżący katalog na stos, a następnie przejdź do wskazanego katalogu.
Warianty użycia: interaktywnie (nawigacja) i w skryptach (z set -e, trap, itp.).

Parametry

Parametr	Opis
`-n`	Nie zmieniaj katalogu – tylko modyfikuj stos (bash).
`+N`	Rotacja: N‑ty element od lewej na wierzchołek.
`-N`	Rotacja: N‑ty element od prawej na wierzchołek.
`-q`	(zsh) Ciche działanie – nie wypisuj stosu po operacji.
`-v`	(zsh) Gadatliwe wypisywanie stosu.

Uwaga: Dokładny zestaw opcji zależy od powłoki; w bash oficjalnie -n oraz indeksy +N/-N.

Przykłady użycia

# 1) Dodaj /etc na stos i przejdź do niego, potem /var/log
pushd /etc
pushd /var/log
dirs -v   # zobacz indeksy
# Efekt: szybkie „skakanie” między katalogami na szczycie stosu.

# 2) Rotacja stosu: wybierz N‑ty katalog bez podawania ścieżki
# Załóżmy: 0=/var/log  1=/etc  2=/home/user/proj
pushd +1  # przejdzie do /etc; stos obrócony
pushd -0  # przejdzie do /home/user/proj (ostatni element)

# 3) Dodaj katalogi bez zmiany bieżącego (bash)
pushd -n ~/src
pushd -n /opt/tools
dirs -v   # 0=PWD, 1=~/src, 2=/opt/tools — nadal w PWD

# 4) Skrypt: bezpieczne wejście/wyjście ze ścieżki roboczej
pushd "$BUILD_DIR" >/dev/null || exit 1
make all
popd >/dev/null
# Efekt: zawsze wrócisz do poprzedniego katalogu po zakończeniu.

Uwagi

Podgląd stosu: dirs (lub dirs -v z indeksami). W bash zawartość jest w tablicy DIRSTACK.
Integracja z cd: W zsh opcja setopt autopushd sprawia, że zwykłe cd automatycznie dodaje poprzedni katalog na stos.
Indeksy są dynamiczne: Po każdej operacji indeksy +N/-N mogą się zmienić – warto sprawdzać dirs -v przed kolejnymi rotacjami.
Przenośność skryptów: Jeśli wymagane są pushd/popd, użyj shebanga wskazującego powłokę z tymi builtinami (np. #!/usr/bin/env bash). sh/dash nie mają tych poleceń.
Ciche operacje: Przekieruj wyjście do /dev/null, aby nie „zaśmiecać” logów w CI (pushd dir >/dev/null).

Najczęściej spotykane błędy i jak je naprawić

Błąd / Komunikat	Przyczyna	Rozwiązanie
`bash: pushd: no other directory`	Za mało elementów na stosie przy wywołaniu bez argumentów	Najpierw użyj `pushd <katalog>` (lub `cd`) by utworzyć stos; sprawdź `dirs -v`.
`bash: pushd: +N: invalid number` / `bad directory stack index`	Indeks poza zakresem lub literówka	Ustal aktualne indeksy `dirs -v` i użyj poprawnego `+N`/`-N`.
`bash: pushd: <katalog>: No such file or directory`	Nieistniejąca ścieżka / brak uprawnień	Zweryfikuj ścieżkę, uprawnienia; użyj pełnej ścieżki lub `~user`.
`command not found: pushd` w skryptach	Uruchamiasz pod `sh`/`dash` (brak builina)	Zmień shebang na `bash`/`zsh` albo użyj odpowiedników (`cd` + własny stos).
Stos „znika” w skrypcie	Użycie podpowłoki `( ... )` – stan nie przechodzi	Uruchamiaj w tej samej powłoce (sourcing `. script.sh`) lub unikaj subshelli.

Linki i źródła

Bash Manual – Directory Stack Builtins – pushd, popd, dirs.
man bash – sekcja SHELL BUILTIN COMMANDS (pushd).
Zsh Manual – pushd – wariant i opcje zsh.
Arch Wiki – Bash prompt and tips – praktyczne wskazówki o stosie katalogów.