// dokumentacja powłoki

HackerOS Shell.

hsh to nowoczesna powłoka napisana w całości w Rust — szybka, bezpieczna i gotowa do codziennej pracy bez fallbacku do /bin/sh. Obsługuje pełne skryptowanie POSIX, natywne potoki, kolorowanie składni i inteligentne podpowiedzi.

Rust · tokio async
Zero sh fallback
BSD-3-Clause
20 motywów
01

Pierwsze kroki

hsh uruchamia się jak każda inna powłoka. Można go ustawić jako domyślną powłokę lub uruchamiać bezpośrednio.

shell
# Uruchomienie interaktywne
hsh

# Wykonanie pojedynczego polecenia
hsh -c 'echo "hello hsh"'

# Dry-run — sprawdź co zostałoby wykonane
hsh --dry-run

# Wersja
hsh --version

# Ustawienie jako domyślna powłoka
chsh -s $(which hsh)
hsh — ~/projects/myapp
17:42:11   ~/projects/myapp   (⎇ main ✗)     git  commit  -m  "fix memory leak"   → git push origin main   [master 2c4f891] fix memory leak 17:42:14   ~/projects/myapp   (⎇ main ↑1)   
02

Główne funkcje

Natywne potoki
Potoki przez pipe(2) + fork w Rust. Zero wywołań /bin/sh.
🎨
Kolorowanie składni
Podświetlanie w czasie rzeczywistym: komendy, flagi, ścieżki, zmienne.
🧠
SmartHints
Podpowiedzi uczymy się z historii. Fish-like inline suggestions.
🔢
Arytmetyka
Pełny parser $(( )): operatory, potęgowanie, porównania, zmienne.
📜
Skrypty POSIX
if/for/while/case/funkcje bez fallbacku. Własny parser AST.
🛡️
Guard niebezpiecznych
Detekcja rm -rf /, fork bomb i innych. Wymaga potwierdzenia.
🎯
20 motywów
Gruvbox, Dracula, Nord, Catppuccin, Tokyo Night i wiele więcej.
⏱️
Czas wykonania
Automatycznie pokazuje czas dla komend trwających dłużej niż 2s.
03

Budowa promptu

Prompt hsh składa się z segmentów, które wyświetlają się kontekstowo — pojawią się tylko gdy są istotne.

SegmentZawartośćWarunek wyświetlenia
17:42:11Aktualny czas HH:MM:SSzawsze
~/projectsSkrócona ścieżka (~ zamiast $HOME)zawsze
(⎇ main ✗)Gałąź git + status dirty/ahead/behindw repozytorium git
✗ [1]Exit code ostatniej komendykod ≠ 0
2.3sCzas wykonania komendyczas ≥ 2000ms
cpu:72% mem:85%Obciążenie systemuCPU > 70% lub RAM > 80%
Tryb rootuid == 0
[2]Głębokość zagnieżdżenia powłokiHSH_DEPTH > 0
Znak zachęty (zielony/czerwony)zawsze

Kolory git

StanKolorZnaczenie
zielonyCzyste drzewo robocze, zsynchronizowane z remote
żółtySą commity do push/pull (ahead/behind)
czerwonyNiezacommitowane zmiany (dirty)
💡 Dane git są pobierane asynchronicznie w tle co 2 sekundy — prompt nigdy nie blokuje się na wolnym repozytorium.
04

Zmienne powłoki

Ustawianie i odczyt

hsh
# Zmienna lokalna (widoczna tylko w hsh)
FOO=bar

# Eksport do środowiska
export FOO=bar

# Inline — tylko dla jednej komendy
LANG=pl_PL.UTF-8 man grep

# Odczyt
echo $FOO
echo ${FOO}

Modyfikatory

hsh
# Wartość domyślna gdy pusta/nieustawiona
echo ${FOO:-domyślna}

# Alternatywa gdy ustawiona
echo ${FOO:+alternatywa}

# Błąd gdy pusta (przerywa skrypt przy -e)
echo ${FOO:?Zmienna FOO jest wymagana}

Zmienne specjalne

ZmiennaZnaczenie
$?Exit code ostatniej komendy
$$PID bieżącego procesu hsh
$0Nazwa powłoki (hsh)
$#Liczba argumentów pozycyjnych
$@, $*Wszystkie argumenty pozycyjne
$1, $2, …Kolejne argumenty pozycyjne
$RANDOMLosowa liczba całkowita
$SECONDSSekundy od uruchomienia hsh
$PWDBieżący katalog
$OLDPWDPoprzedni katalog (przed cd)

Podstawianie komend

hsh
# Nowy styl (zalecany)
FILES=$(ls *.rs)
DATE=$(date +%Y-%m-%d)

# Stary styl (backtick)
HOST=`hostname`

# W środku stringa
echo "Dzisiaj: $(date)"
05

Arytmetyka $(( ))

hsh posiada własny parser wyrażeń arytmetycznych — nie wywołuje żadnego zewnętrznego procesu.

hsh
# Podstawowe działania
echo $(( 2 + 3 ))      # 5
echo $(( 10 / 3 ))     # 3  (dzielenie całkowite)
echo $(( 10 % 3 ))     # 1  (modulo)
echo $(( 2 ** 10 ))    # 1024 (potęgowanie)

# Ze zmiennymi
x=5; y=3
echo $(( x * y + 1 )) # 16

# Przypisanie przez arytmetykę
i=$(( i + 1 ))

# Porównania (zwracają 0 lub 1)
echo $(( x > y ))     # 1
echo $(( x == 5 ))    # 1

# Logika
echo $(( x > 0 && y > 0 ))  # 1
echo $(( x > 10 || y > 0 )) # 1
echo $(( !0 ))               # 1

# Zagnieżdżone
echo $(( (2 + 3) * (4 - 1) )) # 15
OperatorOpisPriorytet
||Logiczne LUBnajniższy
&&Logiczne I
== != < <= > >=Porównania
+ -Dodawanie, odejmowanie
* / %Mnożenie, dzielenie, modulo
**Potęgowanie
- !Jednoargumentowe: negacja, NOTnajwyższy
Dzielenie przez zero i ujemne wykładniki w ** zwracają błąd i przerywają wyrażenie.
06

Przekierowania I/O

Wszystkie przekierowania są implementowane natywnie przez open() + dup2() — bez pośrednictwa /bin/sh.

hsh
# Nadpisz plik
echo "hello" > output.txt

# Dopisz do pliku
echo "world" >> output.txt

# Stdin z pliku
grep error < log.txt

# Stderr do pliku
cmd 2> errors.log

# Stderr → stdout (przekieruj stderr do stdout)
cmd 2>&1

# Stdout i stderr razem do pliku
cmd &> all.log

# Dowolny deskryptor pliku
cmd 3> custom.log
cmd 3>&1
SkładniaDziałanie
> plikstdout → plik (nadpisuje)
>> plikstdout → plik (dopisuje)
< plikstdin ← plik
2> plikstderr → plik
2>&1stderr → tam gdzie stdout
&> plikstdout + stderr → plik
N> plikdeskryptor N → plik
N>&Mdeskryptor N → deskryptor M
<< DELIMheredoc — stdin z literału
<<- DELIMheredoc z usuwaniem tabulatorów
07

Potoki (pipelines)

hsh tworzy potoki przez natywne wywołanie pipe(2) — każdy etap to osobny proces połączony z następnym przez stdout/stdin.

hsh
# Prosty potok
ls -la | grep .rs

# Wielostopniowy
cat log.txt | grep ERROR | sort | uniq | head -20

# Z przekierowaniami na końcu
find . -name '*.rs' | wc -l > count.txt

# Stderr w potoku
cmd 2>&1 | grep error

# Tylko natywne komendy (zero fork na /bin)
find . | grep .rs | wc -l

# Background pipeline
long_cmd | process &
Exit code potoku to exit code ostatniego etapu. Przy set -e niezerowy kod dowolnego etapu przerywa skrypt.
08

Skrypty i kontrola przepływu

hsh zawiera własny parser i interpreter AST — wszystkie konstrukty skryptowe działają bez wywoływania /bin/sh.

if / elif / else

hsh
if [ -f config.toml ]; then
    echo "plik istnieje"
elif [ -d config/ ]; then
    echo "katalog istnieje"
else
    echo "nic nie znaleziono"
fi

for

hsh
# Iteracja po plikach (glob)
for f in *.rs; do
    echo "kompilacja: $f"
done

# Iteracja po liczbach
for i in 1 2 3 4 5; do
    echo $i
done

# Iteracja po wyjściu komendy
for line in $(cat list.txt); do
    process $line
done

while

hsh
i=0
while [ $i -lt 10 ]; do
    echo $i
    i=$(( i + 1 ))
done

case

hsh
case $1 in
    start)
        echo "Uruchamianie..."
        ;;
    stop|halt)
        echo "Zatrzymywanie..."
        ;;
    *)
        echo "Użycie: $0 {start|stop}"
        ;;
esac

Funkcje

hsh
# Definicja
greet() {
    echo "Cześć, $1! Masz $# argumentów."
}

# Wywołanie
greet Michał

# Funkcja z logiką
is_even() {
    return $(( $1 % 2 ))
}

if is_even 42; then
    echo "parzysta"
fi

Operatory łączenia

hsh
# Wykonaj cmd2 tylko gdy cmd1 się powiodło
make && ./run_tests

# Wykonaj cmd2 tylko gdy cmd1 się nie powiodło
ping -c1 server || echo "serwer niedostępny"

# Zawsze oba
build ; deploy

Opcje powłoki (set)

OpcjaOpis
set -ePrzerwij skrypt gdy jakakolwiek komenda zwróci błąd (errexit)
set -xWypisuj każdą wykonywaną komendę z prefiksem + (xtrace)
set -uTraktuj nieznane zmienne jako błąd (nounset)
set +eWyłącz errexit
09

Heredoc <<

hsh
# Podstawowy heredoc (rozszerza zmienne)
NAME=Michał
cat << EOF
Cześć, $NAME!
Dzisiaj jest $(date +%A).
EOF

# Bez rozszerzania zmiennych (literal)
cat << 'EOF'
To $NIE zostanie rozwinięte.
EOF

# Usuwanie wiodących tabulatorów (<<-)
cat <<- EOF
    Ta linia ma usunięty tab na początku.
    Ta też.
EOF
💡 Heredoc automatycznie rozszerza zmienne $VAR i ${VAR}. Otocz delimiter cudzysłowem (<< 'EOF') żeby wyłączyć rozszerzanie.
10

Wbudowane komendy

KomendaOpis
cd [dir|-]Zmień katalog. - wraca do poprzedniego ($OLDPWD).
exit [kod]Wyjdź z hsh z podanym kodem wyjścia (domyślnie 0).
history [query]Historia komend z timestampami. Z argumentem — fuzzy search.
which NAMEPokaż typ komendy: builtin, alias, lub pełna ścieżka binarium.
type NAMEAlias dla which.
export KEY=VALUstaw zmienną środowiskową. export -p wyświetla wszystkie.
aliasWyświetl wszystkie zdefiniowane aliasy.
unalias NAMEUsuń alias (wymaga restartu — aliasy są ładowane z .hshrc).
set [-e|-x|-u]Ustaw opcje powłoki: errexit, xtrace, nounset.
pushd [dir]Wepchnij bieżący katalog na stos i przejdź do dir.
popdWyskocz katalog ze stosu i przejdź do niego.
dirsWyświetl stos katalogów.
source FILEWykonaj plik w bieżącym kontekście powłoki.
. FILEAlias dla source.
test EXPROceń wyrażenie warunkowe. Zwraca 0 (prawda) lub 1 (fałsz).
[ EXPR ]Alias dla test.
jobsWyświetl listę zadań w tle.
fg [%id]Przenieś zadanie na pierwszy plan.
bg [%id]Wznów zadanie w tle.
stop [%id]Zatrzymaj zadanie (SIGSTOP).
kill [-SIG] %idWyślij sygnał do zadania.
wait [%id]Czekaj na zakończenie zadania.
hsh-helpKrótka pomoc wbudowana.
hsh-docs [temat]Rozbudowana dokumentacja (w terminalu).
hsh-settingsInteraktywna zmiana motywu kolorystycznego.

test — operatory

OperatorZnaczenie
-f PLIKPlik istnieje i jest plikiem regularnym
-d PLIKPlik istnieje i jest katalogiem
-e PLIKPlik istnieje (dowolny typ)
-r / -w / -xPlik jest do odczytu / zapisu / wykonania
-z STRString jest pusty
-n STRString jest niepusty
-L PLIKPlik jest dowiązaniem symbolicznym
-s PLIKPlik ma rozmiar > 0
A = BStringi są równe
A != BStringi są różne
A -eq BLiczby równe
A -ne / -lt / -le / -gt / -ge BPorównania liczbowe
! EXPRNegacja
EXPR -a EXPRLogiczne I (AND)
EXPR -o EXPRLogiczne LUB (OR)
A -nt BPlik A nowszy niż B
A -ot BPlik A starszy niż B
11

Komendy natywne

Następujące komendy są zaimplementowane bezpośrednio w hsh — nie wywołują zewnętrznych binariów nawet gdy są dostępne w $PATH:

📝
echo
Flaga -n, sekwencje escape \n \t \r
📍
pwd
Bieżący katalog roboczy
📂
ls
Flagi: -l -a -h, kolorowanie typów plików
🐱
cat
Z kolorowaniem składni przez syntect (base16-ocean.dark)
📁
mkdir
Flaga -p (utwórz katalogi pośrednie)
🗑️
rm
Flagi: -r -rf -f
📋
cp
Flagi: -r -R, kopiowanie między urządzeniami
🚚
mv
Przenoszenie cross-device (copy + delete)
✏️
touch
Utwórz plik lub aktualizuj czas modyfikacji
🌍
env
Wyświetl lub uruchom z zmodyfikowanym środowiskiem
🔍
grep
Flagi: -i -v -c -n, kolorowanie dopasowań
⬆️
head / tail
Flaga -n N, wiele plików
🔢
wc
Flagi: -l -w -c
🖥️
uname
Flagi: -a -s -n -r -m
🔎
find
Opcje -name (glob) i -type
🔄
xargs
Podstawowe xargs z obsługą {}
📐
printf
Formaty %s %d %f %c i sekwencje \n \t
true / false
Zawsze zwraca 0 lub 1
12

Zarządzanie zadaniami

hsh
# Uruchom w tle
long_process &
# [1] 1234

# Wyświetl zadania
jobs
# [1] Running   1234  long_process

# Przenieś na pierwszy plan
fg %1

# Wróć do tła
# (Ctrl+Z zatrzymuje, bg wznawia)
bg %1

# Wyślij sygnał
kill %1             # SIGTERM
kill -KILL %1       # SIGKILL
kill -STOP %1       # zatrzymaj
kill -CONT %1       # wznów

# Czekaj na zakończenie
wait %1
hsh automatycznie sprawdza zakończone zadania po każdej komendzie i wyświetla powiadomienie: [1] Done (0) long_process
13

System podpowiedzi

hsh łączy trzy warstwy podpowiedzi inspirowane fish i zsh:

1. Historia inline (jak fish)

Wpisz kilka pierwszych liter — hsh sugeruje pełną komendę z historii jako szary tekst. Naciśnij żeby zaakceptować.

SmartHints demo
09:15:33   ~/dev     git commit -m "feat: add retry logic" ↑ naciśnij → żeby zaakceptować cały hint

2. Sekwencje (next-command prediction)

Na pustej linii hsh podpowiada komendę, którą zwykle wykonujesz po tej poprzedniej. Dane uczą się automatycznie z Twojej historii.

3. cd preview

Podczas wpisywania cd cz hsh wyświetla pasujące katalogi w bieżącym folderze bezpośrednio w hincie.

Spellcheck

Gdy komenda zwróci exit code 127 (nie znaleziono), hsh używa dystansu Levenshteina do zaproponowania poprawki:

hsh
gti status
hsh: gti: command not found
❓ Czy chodziło Ci o: git status?

Dane SmartHints są zapisywane w ~/.hsh-hints.json i ładowane przy każdym uruchomieniu.

14

Uzupełnianie Tab

KontekstCo uzupełnia Tab
Pierwsze słowoKomendy z $PATH + builtins (posortowane, bez duplikatów)
Po gitadd, commit -m, push origin, pull, status, log --oneline, branch, checkout, …
Po cargobuild, run, test, check, clippy, fmt, doc, publish, …
Po systemctlstart, stop, restart, enable, disable, status, …
Po aptinstall, remove, update, upgrade, search, show, …
Po dockerrun, build, pull, push, ps, images, stop, exec, logs, …
Po npminstall, run, start, test, build, publish, …
Po pipinstall, uninstall, list, show, freeze, …
Po kubectlget, apply, delete, describe, logs, exec, …
ŚcieżkiPliki i katalogi przez FilenameCompleter
💡 Komenda Tab zawsze wyświetla listę pasujących opcji (tryb List) zamiast cyklicznie uzupełniać — łatwiej zobaczyć wszystkie możliwości naraz.
15

Skróty klawiszowe

hsh działa w trybie Emacs (domyślny). Wszystkie standardowe skróty Readline są dostępne.

SkrótDziałanie
/ EndZaakceptuj cały hint / uzupełnienie
Alt+FZaakceptuj jedno słowo hintu (forward-word)
TabUzupełnij komendę, subkomendę lub ścieżkę
Ctrl+RWyszukiwanie wsteczne w historii (reverse search)
Ctrl+LWyczyść ekran
Ctrl+CPrzerwij bieżącą linię lub komendę
Ctrl+DEOF — wyjdź z hsh
Ctrl+ASkocz na początek linii
Ctrl+ESkocz na koniec linii
Ctrl+WUsuń słowo przed kursorem
Ctrl+UUsuń od kursora do początku linii
Ctrl+KUsuń od kursora do końca linii
Alt+BCofnij o jedno słowo
/ Poprzednia / następna komenda w historii
Ctrl+ZZatrzymaj bieżący proces (SIGSTOP) → użyj bg / fg
16

Motywy kolorystyczne

Zmień motyw przez hsh-settings. Ustawienie zapisuje się natychmiast do ~/.config/hackeros/hsh/theme.json.

default
Miętowo-złoty. Stonowany, nowoczesny.
cosmic
Cyberpunk fiolet + cyan.
nord
Skandynawski błękit. Zimna paleta.
gruvbox
Ciepły retro amber.
dracula
Ciemny fiolet + różowy.
hackeros
Matrix zielony na czarnym.
solarized-dark
Klasyczny solarized.
tokyo-night
Nocny Tokio — niebieski + pomarańczowy.
catppuccin-mocha
Pastelowy mocha.
rose-pine
Ciepły fiolet + różowy.
cyberpunk
Neonowy magenta + cyan.
monokai
Klasyczny Monokai.
everforest
Leśna zieleń. Naturalny, miękki.
kanagawa
Japońska estetyka. Głęboki błękit.
one-dark
Atom One Dark.
ayu-dark
Ayu ciemny — minimalistyczny.
17

Konfiguracja .hshrc

Plik ~/.hshrc używa formatu .hk (HackerOS config). Ładowany przy każdym uruchomieniu interaktywnym.

~/.hshrc
# ── Aliasy ───────────────────────────────────────────────
[aliases]
ll = "ls -lah"
la = "ls -a"
g  = "git"
gs = "git status"
gp = "git push origin"
gl = "git log --oneline --graph"
v  = "vim"
py = "python3"
dc = "docker compose"

# ── Prompt ───────────────────────────────────────────────
[prompt]
# Kolejność segmentów (eksperymentalne)
segment_order = "time, dir, git, mem_cpu"
Plik / ŚcieżkaZawartość
~/.hshrcAliasy i konfiguracja promptu
~/.hsh-history-ts.jsonHistoria z timestampami (JSON)
~/.hsh-hints.jsonDane SmartHints (sekwencje, prefiksy)
~/.hsh-path-cache.jsonCache komend z $PATH (TTL: 5 minut)
~/.hsh-historyHistoria dla rustyline (Ctrl+R)
~/.config/hackeros/hsh/theme.jsonAktywny motyw kolorystyczny
18

Bezpieczeństwo i ochrona

Niebezpieczne komendy

hsh automatycznie wykrywa i blokuje potencjalnie destruktywne komendy. Wymagają wpisania yes:

WzorzecOstrzeżenie
rm -rf /Usunięcie wszystkich plików
rm -rf /*Usunięcie wszystkich plików
dd if=/dev/zero of=/dev/sdaNadpisanie dysku
:(){ :|:& };:Fork bomb — crash systemu
curl | shZdalne wykonanie kodu
wget -O- | bashZdalne wykonanie kodu
chmod -R 777 /Globalne uprawnienia 777
mkfs /dev/sdaFormatowanie dysku

Auto-sudo dla edytorów

Gdy edytujesz plik w /etc/, /usr/, /var/ lub /boot/ przez vi, vim, nano lub emacs — hsh pyta czy chcesz użyć sudo.

Kolorowanie składni — detekcja

Niebezpieczne komendy są wizualnie oznaczane czerwonym migającym tłem już podczas wpisywania, zanim naciśniesz Enter.

19

Flagi startowe

FlagaOpisPrzykład
-c 'cmd'Wykonaj komendę i wyjdźhsh -c 'echo hello'
--dry-runSymuluj — wypisz komendy zamiast wykonywaćhsh --dry-run
--version / -VWyświetl wersję i wyjdźhsh --version

Tryb dry-run

W trybie --dry-run żadna komenda nie jest wykonywana — hsh wypisuje tylko co by zostało wykonane:

hsh --dry-run
 rm -rf build/
[dry-run] rm -rf build/

 export DB_URL=postgres://localhost
[dry-run] export DB_URL=postgres://localhost

 build.sh &
[dry-run] [bg] build.sh
💡 Tryb dry-run jest przydatny do debugowania skryptów — uruchom hsh --dry-run -c ./deploy.sh żeby zobaczyć pełną sekwencję operacji bez ryzyka.
hsh v0.4.0 · HackerOS Shell · Rust + tokio Licencja: BSD-3-Clause
Napisany w Rust. Bez zależności od /bin/sh. Działa wszędzie tam gdzie działa Linux.