Workflow/workflow-pl.md

# Praca z projektem na git.intecion.net

> 🇵🇱 Polski · 🇬🇧 [English (maintained)](./workflow-en.md)

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:

```bash
# 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:
   ```bash
   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**:
   ```bash
   # 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):
   ```bash
   ssh -T -p 22222 [email protected]
   ```
   Odpowiedź „Hi <login>! 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ś.

```bash
# 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`.

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

---

## Codzienny cykl

### Zanim zaczniesz pracę — pobierz cudze zmiany

```bash
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

```bash
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

```bash
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.

```bash
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ść:

```bash
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:

```bash
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:

```bash
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:

```bash
git remote -v
```

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

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