Workflow/workflow-pl.md

Praca z projektem na git.intecion.net

Instrukcja dla kogoś, kto pracuje nad projektem, którego repozytorium mieszka na firmowym Gitea (git.intecion.net). Obejmuje pobranie kodu, codzienny cykl (pobierz zmiany → pracuj → wyślij), i najczęstsze błędy autoryzacji.

Serwer jest wewnętrzny — każda operacja sięgająca do niego wymaga uwierzytelnienia. Masz dwie drogi: HTTPS z tokenem (prostsze na start) albo SSH z kluczem (wygodniejsze na dłużej, bo nie pyta za każdym razem). Wybierz jedną.

---

Jednorazowa konfiguracja dostępu

Droga HTTPS (token)

Nic nie instalujesz — potrzebujesz tylko tokenu.

1. Gitea → awatar → Settings → Applications → Generate New Token.
2. Zakres: write:repository (pozwala czytać i wysyłać kod).
3. Skopiuj token — pokazuje się raz.

Przy pierwszym git push/clone prywatnego repo Git zapyta o dane:

• Username: Twój login w Gitea
• Password: wklej token (nie hasło do konta — Gitea nie przyjmuje hasła przy operacjach git przez HTTPS)

Żeby nie wpisywać za każdym razem, włącz zapamiętywanie:

# macOS — używa Keychain
git config --global credential.helper osxkeychain

# Windows — używa Credential Manager
git config --global credential.helper manager

# Linux/Ubuntu — zapamiętaj w pamięci na 1h (bezpieczniej niż na stałe)
git config --global credential.helper 'cache --timeout=3600'

Droga SSH (klucz)

Jednorazowo więcej pracy, potem zero pytań o hasło.

1. Wygeneruj klucz, jeśli nie masz:

   ssh-keygen -t ed25519 -C "twó[email protected]"
   # Enter na wszystkich pytaniach (domyślna lokalizacja, bez hasła albo z hasłem)
   

2. Skopiuj klucz publiczny:

   # macOS
   pbcopy < ~/.ssh/id_ed25519.pub
   # Linux
   cat ~/.ssh/id_ed25519.pub      # zaznacz i skopiuj
   # Windows (PowerShell)
   Get-Content ~/.ssh/id_ed25519.pub | Set-Clipboard
   

3. Gitea → Settings → SSH / GPG Keys → Add Key → wklej.
4. Sprawdź połączenie (uwaga na port — Gitea może używać niestandardowego):

   ssh -T -p 22222 [email protected]
   

   Odpowiedź „Hi ! You've successfully authenticated" → działa. Permission denied (publickey) → klucz nie dodany albo zły port.

---

Pobranie projektu (pierwszy raz)

Adres repo znajdziesz na stronie repozytorium w Gitea (przycisk Clone). Wybierz zakładkę HTTPS albo SSH, zgodnie z drogą, którą skonfigurowałeś.

# HTTPS
git clone https://git.intecion.net/IntecionSoftware/nazwa-projektu.git

# SSH (port jak w Twoim Gitea)
git clone ssh://[email protected]:22222/IntecionSoftware/nazwa-projektu.git

Co się dzieje: Git łączy się z serwerem (token albo klucz), pobiera całą historię i pliki do nowego katalogu nazwa-projektu.

cd nazwa-projektu
pnpm install          # pobierz zależności (patrz README projektu)

---

Codzienny cykl

Zanim zaczniesz pracę — pobierz cudze zmiany

git pull

Co robi: ściąga z serwera commity, które ktoś inny wypchnął od Twojego ostatniego pobrania, i scala je z Twoją kopią. Rób to na starcie dnia i przed push — inaczej Twój push może zostać odrzucony (patrz niżej).

W trakcie pracy — zapisuj postępy lokalnie

git status            # co zmieniłeś (nic nie wysyła)
git add .             # oznacz zmiany do zapisania
git commit -m "opis czego dotyczy zmiana"

Co się dzieje: commit zapisuje migawkę lokalnie, na Twoim dysku. Serwer jeszcze o niej nie wie. Możesz zrobić kilka commitów, zanim cokolwiek wyślesz.

Gdy skończysz kawałek — wyślij na serwer

git push

Co robi: wysyła Twoje lokalne commity do repozytorium na Gitea, żeby zespół je zobaczył. To pierwsza komenda w tym cyklu, która zmienia stan serwera.

---

Praca na branchu (zalecane)

Zamiast pracować bezpośrednio na main, wydziel gałąź na swoje zmiany — łatwiej o przegląd i mniej konfliktów.

git checkout -b moja-funkcja      # utwórz i przełącz się na nowy branch
# ... praca, commity ...
git push -u origin moja-funkcja   # wyślij branch na serwer (pierwszy raz z -u)

Potem w Gitea otwórz Pull Request z moja-funkcja do main, żeby ktoś przejrzał, zanim trafi do głównej gałęzi.

---

Najczęstsze błędy i co znaczą

Komunikat	Co się stało	Co zrobić
Permission denied (publickey)	SSH: serwer nie zna Twojego klucza, albo zły port	dodaj klucz w Gitea; sprawdź port (-p 22222)
remote: Unauthorized / prośba o hasło w kółko	HTTPS: token zły lub podałeś hasło konta zamiast tokenu	użyj tokenu jako hasła; sprawdź zakres write:repository
failed to push ... non-fast-forward	ktoś wypchnął zmiany, których nie masz lokalnie	git pull (scal), potem git push
Updates were rejected because the tip of your current branch is behind	to samo co wyżej — jesteś „za" serwerem	git pull, rozwiąż ewentualne konflikty, git push
fatal: repository not found	zły adres, albo brak dostępu do repo w Gitea	sprawdź adres (Clone w Gitea); poproś o dostęp
konflikt scalania po git pull	Ty i ktoś inny zmieniliście ten sam fragment	Git oznaczy pliki; edytuj, git add, git commit

Gdy push zostaje odrzucony (non-fast-forward)

To najczęstszy przypadek. Serwer ma commity, których nie masz — nie pozwoli nadpisać. Kolejność:

git pull              # ściągnij i scal cudze zmiany
# jeśli konflikt: Git pokaże pliki, rozwiąż je, potem:
git add .
git commit -m "scalenie"
git push              # teraz przejdzie

Nie forsuj (git push --force) na wspólnym branchu (main) — nadpisałbyś cudzą pracę. Force jest bezpieczny tylko na własnym branchu, którego nikt inny nie używa.

---

Praca nad kilkoma projektami naraz

Każdy projekt to osobny katalog z własnym repozytorium. Nie ma czegoś takiego jak „przełączenie projektu" jedną komendą — po prostu wchodzisz do katalogu tego projektu, nad którym chcesz pracować. Git czyta konfigurację (adres serwera, gałąź, historię) z katalogu, w którym aktualnie jesteś.

Gdzie trzymać projekty

Trzymaj je obok siebie w jednym miejscu, np.:

~/projekty/
  strona-klienta-a/     ← osobne repo, osobny remote
  strona-klienta-b/     ← osobne repo, osobny remote
  ipal-kit/             ← wtyczka

Przełączenie między nimi to zmiana katalogu:

cd ~/projekty/strona-klienta-a
# ... praca nad A ...

cd ~/projekty/strona-klienta-b
# ... praca nad B ...

Każde git pull / git push / git status działa na projekcie, w którego katalogu aktualnie jesteś. To dlatego pierwszym odruchem po cd powinno być sprawdzenie, gdzie jesteś i w jakim stanie.

Zanim zaczniesz pracę w projekcie — zorientuj się

Po wejściu do katalogu, trzy komendy dają pełny obraz:

pwd                   # w którym projekcie jestem (pełna ścieżka)
git remote -v         # do którego repo na Gitea to wysyła
git status            # na jakiej gałęzi, czy są niezapisane zmiany

git status na górze pokazuje gałąź (On branch ...) — upewnij się, że to ta, na której chcesz pracować, zanim zaczniesz commitować.

Pułapki przy wielu projektach

• Push do złego repo. Jeśli sklonowałeś projekt B, kopiując katalog projektu A (zamiast git clone), remote nadal wskazuje repo A — i wypchniesz zmiany B do repozytorium A. Zawsze klonuj przez git clone, nigdy przez kopiowanie katalogu. Sprawdzaj git remote -v przy pierwszym pushu nowego projektu.
• Niezapisane zmiany przy przełączaniu. cd do innego projektu nie gubi zmian w poprzednim — one czekają w tamtym katalogu. Ale łatwo zapomnieć, że zostawiłeś coś niezacommitowanego. git status przypomni, gdy wrócisz.
• Zależności są per projekt. Każdy projekt ma własny node_modules. Po przejściu do projektu, którego dawno nie ruszałeś, zrób git pull a potem pnpm install — ktoś mógł dodać zależności, których nie masz.

Szybka orientacja — który projekt, która gałąź

Warto skonfigurować, żeby terminal sam pokazywał aktualną gałąź w znaku zachęty — wtedy zawsze widzisz, gdzie jesteś, bez wpisywania git status.

Na macOS/Linux (zsh/bash) dodaje to większość gotowych konfiguracji (oh-my-zsh, starship). Jeśli nie masz — starship (https://starship.rs) działa na wszystkich trzech systemach i pokazuje katalog + gałąź automatycznie.

Wiele projektów otwartych w edytorze

Jeśli używasz WebStorm/VSCode, każdy projekt otwieraj jako osobne okno (osobny katalog jako root). Edytor wtedy czyta właściwy .git i pokazuje właściwą gałąź w rogu. Otwarcie katalogu nadrzędnego (~/projekty/) jako jednego projektu miesza repozytoria — unikaj tego.

Sprawdzenie, gdzie wskazuje Twój projekt

Jeśli nie wiesz, czy repo lokalny jest podpięty do Gitea:

git remote -v

Pokaże adres serwera. Powinien zawierać git.intecion.net. Jeśli wskazuje gdzie indziej (np. stary GitHub), zmień:

git remote set-url origin https://git.intecion.net/IntecionSoftware/nazwa-projektu.git