tagi 0.49.1

Orchestrator for Git change shipments

tagi

AI Cost Tracking

• 🤖 LLM usage: $1.2153 (12 commits)
• 👤 Human dev: ~$656 (6.6h @ $100/h, 30min dedup)

Generated on 2026-05-26 using openrouter/qwen/qwen3-coder-next

---

tagi to paczka Python i CLI do orkiestracji wysyłania zmian Git, a nie zamiennik komendy git.

Pozycjonowanie

• Git odpowiada za wykonanie (status, add, commit, push).
• tagi odpowiada za analizę, grupowanie, planowanie i bezpieczne uruchomienie workflow.
• gh/glab odpowiadają za integrację i auth z providerami.

Cel

tagi pomaga zdecydować, co wysłać i jak to opisać, a następnie uruchamia istniejące narzędzia (git, opcjonalnie gh/glab) po jawnym potwierdzeniu użytkownika.

Zasady projektu

• jawność przed magią,
• preview → confirm → execute,
• brak ukrywania realnych komend,
• deterministyczne tagowanie jako domyślne.
• LLM opcjonalnie do redakcji opisów, nie do sterowania logiką wysyłki.

Zakres odpowiedzialności

Co tagi powinien robić

• analizować git status --porcelain i diffy,
• budować grupy zmian na podstawie heurystyk,
• proponować paczki wysyłkowe i plan wykonania,
• generować draft tytułu i treści opisu commita,
• uruchamiać git i opcjonalnie gh/glab dopiero po decyzji użytkownika.

Czego tagi nie powinien robić

• zastępować git add/commit/push,
• implementować własnego modelu stanu repo poza .git,
• ukrywać jakie komendy wykona,
• zmieniać semantyki commit/push,
• zastępować workflow branch/rebase/merge.

Komendy

tagi scan <path> [--grouped] [--by-branch]
tagi list-groups <path>
tagi stats <path>
tagi filter <tags> <path> [--all] [--min-risk FLOAT] [--max-risk FLOAT] [--min-complexity FLOAT] [--max-complexity FLOAT] [--min-impact FLOAT] [--max-impact FLOAT]
tagi file <file_path> <path>
tagi inspect <tag> <path> [--diff]
tagi summary <path> [--output FILE]
tagi safe <path>
tagi init <path>
tagi auth <path> [--provider PROVIDER]
tagi hooks <path> [--install] [--uninstall] [--list]
tagi deps <path> [--cycles] [--critical]
tagi metrics <path> [--output FILE] [--report]
tagi draft <tag> <path> [--template TEMPLATE]
tagi send <path> [tags...] [--dry-run] [--push] [--template TEMPLATE] [--interactive] [--auto-order]
tagi publish <tag> <path> [--dry-run] [--template TEMPLATE]

• scan — analiza zmian w repozytorium (z opcją --grouped do grupowania po tagach)
• list-groups — lista paczek i tagów
• stats — statystyki zmian (liczba plików, linii, rozkład typów i tagów)
• filter — filtrowanie plików po tagach (comma-separated, np. small,docs; --all wymaga wszystkich tagów)
• file — szczegóły pojedynczego pliku (wszystkie tagi, linie zmienione, score ryzyka)
• inspect — podgląd paczki i ryzyka (z opcją --diff do pokazania zmian)
• summary — generuj kompleksowy raport podsumowujący (opcjonalnie zapisz do pliku)
• safe — pokaż bezpieczne zmiany do wysłania najpierw (niskie ryzyko, małe, nie risky/deps/config)
• init — wygeneruj plik konfiguracyjny tagi.toml.example
• auth — sprawdź status autoryzacji GitHub/GitLab (opcjonalnie dla konkretnego providera)
• hooks — zarządzaj integracją git hooks (instalacja, odinstalowanie, lista, status)
• deps — analizuj graf zależności zmian Python (cykle, ścieżka krytyczna, kolejność)
• metrics — zbieraj i wyświetlaj metryki o zmianach (eksport JSON, raport)
• draft — propozycja opisu commita z wyborem szablonu
• send — po potwierdzeniu wykonuje git add i git commit; push jest opcjonalny (z trybem interaktywnym); akceptuje wiele tagów w kolejności priorytetu, np. tagi send . small docs; bez tagów lub z flagą --auto-order sortuje automatycznie od najprostszych do najtrudniejszych
• publish — rozszerzenie o PR/MR przez provider z auto-detection (GitHub/GitLab)

Architektura (kierunek)

src/tagi/
  scanner/
  cli.py
  config.py
  models/
    change.py
    group.py
    plan.py
  scanner/
    status.py
    diff.py
    files.py
  heuristics/
    tags.py
    scoring.py
    rules.py
  planner/
    grouper.py
    selector.py
    preview.py
  composer/
    commit_message.py
    summary.py
  executor/
    git.py
    publish.py
  providers/
    base.py
    github.py
    gitlab.py
  llm/
    llx_adapter.py

## Przykłady użycia

```bash
# Podstawowe skanowanie
tagi scan /path/to/repo

# Skanowanie z grupowaniem po tagach
tagi scan /path/to/repo --grouped

# Statystyki zmian
tagi stats /path/to/repo

# Filtrowanie po jednym tagu
tagi filter "small" /path/to/repo

# Filtrowanie po wielu tagach (OR logic - pasuje do dowolnego)
tagi filter "small,docs" /path/to/repo

# Filtrowanie po wielu tagach (AND logic - wymaga wszystkich)
tagi filter "config,small" /path/to/repo --all

# Szczegóły pojedynczego pliku
tagi file README.md /path/to/repo

# Podgląd tagu ze statystykami
tagi inspect docs /path/to/repo

# Pokaż bezpieczne zmiany do wysłania najpierw
tagi safe /path/to/repo

# Generuj raport podsumowujący
tagi summary /path/to/repo

# Zapisz raport do pliku
tagi summary /path/to/repo --output report.txt

# Lista grup zmian
tagi list-groups /path/to/repo

# Inspekcja z podglądem diffów
tagi inspect #small /path/to/repo --diff

# Draft z konwencjonalnym formatem
tagi draft small /path/to/repo --template conventional

# Draft z prostym formatem
tagi draft small /path/to/repo --template simple

# Draft z formatem jednej linii
tagi draft small /path/to/repo --template oneline

# Draft z formatem skupionym na plikach
tagi draft small /path/to/repo --template files

# Wysłanie z pushem (szablon detailed)
tagi send small /path/to/repo --push --template detailed

# Opublikuj PR/MR (szablon conventional)
tagi publish small /path/to/repo --template conventional

Konfiguracja

Utwórz plik tagi.toml w katalogu repozytorium:

[rules]
"frontend/" = "#frontend"
"backend/" = "#backend"
"migration/" = "#risky"

[colors]
# Własne kolory dla tagów (nazwy kolorów Rich)
"#frontend" = "blue"
"#backend" = "green"
"#risky" = "red"

[heuristics]
# Własne heurystyki - mapuj wzorce do wielu tagów
"api/" = ["#api", "#backend"]
"cli/" = ["#cli", "#tool"]
"migration/" = ["#risky", "#database"]

[tag_definitions]
# Opisy tagów
"#small" = "Małe zmiany (< 10 linii)"
"#large" = "Duże zmiany (> 100 linii)"
"#risky" = "Zmiany wysokiego ryzyka"

[templates]
# Własne szablony komunikatów commitów
default = "{tag}: {count} plików ({files})"
detailed = "Commit {tag}\n\nZmienione pliki ({count}):\n{files}\n\nWygenerowane przez tagi"

[ignore]
# Wzorce do ignorowania podczas skanowania
["node_modules/", ".git/", "__pycache__/", "*.pyc", ".idea/", ".vscode/"]

Definicja produktu

tagi to orchestrator wysyłania zmian Git: analizuje nie wysłane pliki, grupuje je hashtagami, proponuje sensowne paczki commitów i uruchamia istniejące narzędzia Git/GitHub/GitLab do publikacji.

License

Licensed under Apache-2.0.