Workflow/workflow-en.md

# Working with a project on git.intecion.net

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

A guide for anyone working on a project whose repository lives on the company
Gitea (`git.intecion.net`). Covers getting the code, the daily cycle (pull →
work → push), juggling several projects, and the most common auth errors.

The server is internal — every operation that reaches it needs authentication.
You have two routes: **HTTPS with a token** (simpler to start) or **SSH with a
key** (more convenient long-term, since it doesn't prompt every time). Pick one.

---

## One-time access setup

### HTTPS route (token)

Nothing to install — you only need a token.

1. Gitea → avatar → **Settings → Applications → Generate New Token**.
2. Scope: **`write:repository`** (lets you read and push code).
3. Copy the token — it's shown only once.

On your first `git push`/`clone` of a private repo, Git asks for credentials:
- **Username:** your Gitea login
- **Password:** paste the **token** (not your account password — Gitea doesn't
  accept the password for git operations over HTTPS)

To avoid retyping it every time, enable credential storage:

```bash
# macOS — uses Keychain
git config --global credential.helper osxkeychain

# Windows — uses Credential Manager
git config --global credential.helper manager

# Linux/Ubuntu — cache in memory for 1h (safer than storing plaintext)
git config --global credential.helper 'cache --timeout=3600'
```

### SSH route (key)

More work up front, then no password prompts at all.

1. Generate a key if you don't have one:
   ```bash
   ssh-keygen -t ed25519 -C "[email protected]"
   # Enter through all prompts (default location, with or without a passphrase)
   ```
2. Copy the **public** key:
   ```bash
   # macOS
   pbcopy < ~/.ssh/id_ed25519.pub
   # Linux
   cat ~/.ssh/id_ed25519.pub      # select and copy
   # Windows (PowerShell)
   Get-Content ~/.ssh/id_ed25519.pub | Set-Clipboard
   ```
3. Gitea → **Settings → SSH / GPG Keys → Add Key** → paste.
4. Test the connection (mind the port — Gitea may use a non-standard one):
   ```bash
   ssh -T -p 22222 [email protected]
   ```
   "Hi <login>! You've successfully authenticated" → it works.
   `Permission denied (publickey)` → key not added, or wrong port.

---

## Getting the project (first time)

Find the repo address on its page in Gitea (the **Clone** button). Pick the HTTPS
or SSH tab matching the route you set up.

```bash
# HTTPS
git clone https://git.intecion.net/IntecionSoftware/project-name.git

# SSH (port as in your Gitea)
git clone ssh://[email protected]:22222/IntecionSoftware/project-name.git
```

**What happens:** Git connects to the server (token or key), downloads the full
history and files into a new `project-name` directory.

```bash
cd project-name
pnpm install          # fetch dependencies (see the project's README)
```

---

## The daily cycle

### Before you start — pull others' changes

```bash
git pull
```

**What it does:** downloads commits others pushed since your last pull, and
merges them into your copy. Do it at the start of the day and before every
`push` — otherwise your push may be rejected (see below).

### While working — save progress locally

```bash
git status            # what you changed (sends nothing)
git add .             # mark changes to be saved
git commit -m "describe what the change is about"
```

**What happens:** a commit saves a snapshot **locally**, on your disk. The server
doesn't know about it yet. You can make several commits before sending anything.

### When you finish a piece — send it to the server

```bash
git push
```

**What it does:** sends your local commits to the repository on Gitea, so the
team can see them. This is the first command in the cycle that **changes** the
server's state.

---

## Working on a branch (recommended)

Instead of working straight on `main`, split off a branch for your changes —
easier to review, fewer conflicts.

```bash
git checkout -b my-feature        # create and switch to a new branch
# ... work, commits ...
git push -u origin my-feature     # send the branch to the server (first time with -u)
```

Then open a **Pull Request** in Gitea from `my-feature` into `main`, so someone
reviews it before it lands on the main branch.

---

## Working on several projects at once

Each project is a separate directory with its own repository. There's no single
"switch project" command — you simply `cd` into the project you want to work on.
Git reads its config (server address, branch, history) from whatever directory
you're currently in.

### Where to keep projects

Keep them side by side in one place, e.g.:

```
~/projects/
  client-a/     ← its own repo, its own remote
  client-b/     ← its own repo, its own remote
  ipal-kit/     ← the plugin
```

Switching between them is a change of directory:

```bash
cd ~/projects/client-a
# ... work on A ...

cd ~/projects/client-b
# ... work on B ...
```

Every `git pull` / `git push` / `git status` acts on the project **whose
directory you're currently in**. That's why your first reflex after `cd` should
be checking where you are and in what state.

### After entering a project — get your bearings

Three commands give the full picture:

```bash
pwd                   # which project am I in (full path)
git remote -v         # which repo on Gitea does this push to
git status            # which branch, any unsaved changes
```

`git status` shows the branch at the top (`On branch ...`) — make sure it's the
one you mean to work on before you start committing.

### Pitfalls with multiple projects

- **Pushing to the wrong repo.** If you set up project B by copying project A's
  directory (instead of `git clone`), the remote still points at A's repo — and
  you'll push B's changes into A. Always clone with `git clone`, never by copying
  a directory. Check `git remote -v` on the first push of a new project.
- **Forgotten unsaved changes.** `cd`-ing to another project doesn't lose changes
  in the previous one — they wait in that directory. But it's easy to forget you
  left something uncommitted. `git status` reminds you when you return.
- **Dependencies are per project.** Each project has its own `node_modules`.
  After moving to a project you haven't touched in a while, run `git pull` then
  `pnpm install` — someone may have added dependencies you don't have.

### Quick orientation — which project, which branch

It's worth configuring your prompt to **show the current branch** automatically —
then you always see where you are without typing `git status`.

On macOS/Linux (zsh/bash) most ready-made setups add this (oh-my-zsh, starship).
If you don't have one, starship (`https://starship.rs`) works on all three
systems and shows directory + branch automatically.

### Several projects open in the editor

In WebStorm/VSCode, open each project as a **separate window** (its own directory
as the root). The editor then reads the right `.git` and shows the right branch
in the corner. Opening the parent directory (`~/projects/`) as a single project
mixes repositories — avoid that.

---

## Common errors and what they mean

| Message | What happened | What to do |
|---|---|---|
| `Permission denied (publickey)` | SSH: server doesn't know your key, or wrong port | add the key in Gitea; check the port (`-p 22222`) |
| `remote: Unauthorized` / repeated password prompt | HTTPS: bad token, or you gave your account password instead of the token | use the token as the password; check the `write:repository` scope |
| `failed to push ... non-fast-forward` | someone pushed changes you don't have locally | `git pull` (merge), then `git push` |
| `Updates were rejected because the tip of your current branch is behind` | same as above — you're "behind" the server | `git pull`, resolve any conflicts, `git push` |
| `fatal: repository not found` | wrong address, or no access to the repo in Gitea | check the address (Clone in Gitea); ask for access |
| merge conflict after `git pull` | you and someone else changed the same lines | Git marks the files; edit, `git add`, `git commit` |

### When a push is rejected (non-fast-forward)

This is the most common case. The server has commits you don't — it won't let you
overwrite them. The order:

```bash
git pull              # fetch and merge others' changes
# if there's a conflict: Git shows the files, resolve them, then:
git add .
git commit -m "merge"
git push              # now it goes through
```

Don't force (`git push --force`) on a shared branch (`main`) — you'd overwrite
others' work. Force is only safe on your own branch that nobody else uses.

---

## Checking where your project points

If you're unsure whether a local repo is wired to Gitea:

```bash
git remote -v
```

It shows the server address. It should contain `git.intecion.net`. If it points
elsewhere (e.g. an old GitHub), change it:

```bash
git remote set-url origin https://git.intecion.net/IntecionSoftware/project-name.git
```