From c761ba51c055b6c02cbb0b90c8dd78390710b103 Mon Sep 17 00:00:00 2001 From: Admin Date: Mon, 3 Aug 2026 13:07:43 +0000 Subject: [PATCH] Add workflow-en.md --- workflow-en.md | 263 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 263 insertions(+) create mode 100644 workflow-en.md diff --git a/workflow-en.md b/workflow-en.md new file mode 100644 index 0000000..301bf5f --- /dev/null +++ b/workflow-en.md @@ -0,0 +1,263 @@ +# 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 "your-email@intecion.net" + # 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 git@git.intecion.net + ``` + "Hi ! 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://git@git.intecion.net: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 +``` \ No newline at end of file