# Git and Gitea Management AGENT

## Purpose

This document defines the canonical workflow for managing:

- local Git repositories
- GitHub upstream repositories
- writable Gitea repositories
- read-only Gitea mirror repositories

This file exists to prevent remote confusion, mirror misuse, and branch history corruption.

## 1. Core Principles

### 1.1 One repo, one role
Do not let a single remote repository play multiple conflicting roles.

A repository should be clearly one of:

- upstream source
- writable development remote
- read-only mirror

If a repository is a mirror, treat it as a mirror.
If a repository is writable, treat it as writable.
Do not mix the two.

### 1.2 Never confuse source of truth
The source of truth for official upstream code is the upstream repository, not the writable Gitea dev repo, and not the mirror.

### 1.3 Keep `main` clean
`main` is for syncing upstream only.
Do not pile local feature work directly into `main`.

### 1.4 Local changes belong on dev branches
Local work belongs on branches like:

- `home`
- `feature/*`
- `fix/*`

Do not treat the mirror repo as a development target.

## 2. Remote Roles

### 2.1 Canonical remote names
Use these exact names:

- `upstream` — official upstream source repository
- `gitea` — writable development repository on Gitea

Do not rename them casually.

### 2.2 Role definitions

#### `upstream`
Used only for:

- fetching latest official code
- comparing branch divergence
- updating local `main`

Example:

- `upstream -> https://github.com/QuantumNous/new-api.git`

#### `gitea`
Used only for:

- pushing local branches
- opening PRs on writable Gitea repos
- storing development work

Example:

- `gitea -> ssh://git@100.64.0.8:2222/admin/new-api-dev.git`

#### Read-only mirror repo
If a Gitea repo is configured as a pull mirror, it is read-only for development purposes.

Example:

- `admin/new-api` is a pull mirror of GitHub
- it is for sync / reference / backup
- it is not the target for normal pushes

Do not point `gitea` to a mirror repo.

## 3. Required Repository Topology

For projects that track an open-source upstream and also need private or self-hosted development:

- one upstream repo
- one writable Gitea dev repo
- optional one Gitea mirror repo

Recommended shape:

- `upstream` -> official GitHub repo
- `gitea` -> writable Gitea repo
- optional mirror repo exists separately but is not the main local push target

## 4. Branch Responsibilities

### `main`
Responsibilities:

- track upstream
- remain linear and clean
- only accept upstream sync commits or fast-forward updates

Rules:

- do not do feature development directly on `main`
- do not use `main` as a scratch branch
- prefer `merge --ff-only` when updating from upstream

### `home`
Responsibilities:

- personal development branch
- local operational or infrastructure work
- custom changes that do not belong on clean upstream `main`

Rules:

- rebase or merge onto updated `main`
- push to writable Gitea repo
- do not track upstream directly

### `feature/*`
Responsibilities:

- isolated work branches
- short-lived development branches
- branch off from current `main` or from `home` when appropriate

## 5. Standard Workflow

### 5.1 Inspect repository state
Always inspect first:

```bash
git remote -v
git branch -vv
git status --short
```

If remotes or tracking look wrong, fix them before pushing.

### 5.2 Sync local `main` with upstream
Preferred flow:

```bash
git fetch upstream
git switch main
git merge --ff-only upstream/main
git push gitea main
```

This keeps:

- local `main`
- writable Gitea `main`

aligned with upstream.

### 5.3 Update development branch after upstream sync
If using rebase:

```bash
git switch home
git rebase main
git push --force-with-lease gitea home
```

If using merge:

```bash
git switch home
git merge main
git push gitea home
```

Use `rebase` when clean linear history matters.
Use `merge` when you do not want history rewriting.

### 5.4 Create a new working branch
From updated `main`:

```bash
git switch main
git switch -c feature/<name>
```

Push it:

```bash
git push -u gitea feature/<name>
```

### 5.5 Push local changes
Always push to writable Gitea repo:

```bash
git push gitea <branch>
```

Do not push to mirror repos.

## 6. Fallback Workflow When GitHub Is Unreachable

If local machine cannot access GitHub, but the Gitea mirror is confirmed fresh, the mirror may be used as a temporary fetch source.

Example:

```bash
git fetch ssh://git@100.64.0.8:2222/admin/new-api.git refs/heads/main:refs/remotes/upstream/main
git switch main
git merge --ff-only upstream/main
git push gitea main
```

### Important restriction
Do this only after verifying that the mirror really matches upstream.

Check both sides:

- GitHub main commit
- Gitea mirror main commit

If they differ, do not use the mirror as a substitute for upstream.

## 7. Gitea Mirror Rules

If a Gitea repository is a pull mirror:

- it is a sync target, not a dev target
- pushes may fail or be meaningless
- it should be treated as read-only for development

Use mirror repos for:

- backup
- browsing
- clone acceleration
- temporary upstream fallback when verified fresh

Do not use mirror repos for:

- long-term feature branch work
- main development push target
- authoritative branch ownership

## 8. SSH Rules for Gitea

Use Gitea built-in SSH, not random container SSH assumptions.

Example working clone form:

```bash
git clone ssh://git@100.64.0.8:2222/admin/new-api-dev.git
```

If SSH suddenly breaks after a server-side SSH mapping change:

- verify host port mapping
- verify Gitea built-in SSH port
- refresh local `known_hosts` if host key changed

Example:

```bash
ssh-keygen -R '[100.64.0.8]:2222'
ssh -T -p 2222 git@100.64.0.8
```

## 9. Required Remote Configuration for This Project

Current expected shape:

- `upstream` -> official GitHub repository
- `gitea` -> writable Gitea development repository

Expected result style:

```text
gitea    ssh://git@100.64.0.8:2222/admin/new-api-dev.git (fetch)
gitea    ssh://git@100.64.0.8:2222/admin/new-api-dev.git (push)
upstream https://github.com/QuantumNous/new-api.git (fetch)
upstream https://github.com/QuantumNous/new-api.git (push)
```

Expected tracking style:

- `main` -> `upstream/main`
- `home` -> `gitea/home`

## 10. Forbidden Operations

Do not do the following unless you explicitly know why:

- push local feature work into a pull mirror repo
- remove `upstream` and pretend Gitea mirror is always equal to GitHub
- develop directly on `main`
- rewrite shared branch history without understanding the impact
- force-push `main`
- use mirror repos as the only source of upstream truth
- change remote roles casually

## 11. Minimal Recovery Rules

If repository roles become confused:

1. inspect remotes
2. identify which repo is writable and which is mirrored
3. restore:
   - `upstream` -> official source
   - `gitea` -> writable dev repo
4. restore tracking:
   - `main` -> `upstream/main`
   - dev branch -> `gitea/<branch>`

Useful commands:

```bash
git remote -v
git branch -vv
git config --get branch.main.remote
git config --get branch.main.merge
git config --get remote.pushDefault
```

## 12. Recommended Defaults

Set default push target to writable Gitea:

```bash
git config remote.pushDefault gitea
```

Set `main` tracking to upstream:

```bash
git branch --set-upstream-to=upstream/main main
```

Set dev branch tracking to Gitea:

```bash
git branch --set-upstream-to=gitea/home home
```

## 13. Human Rule

If you cannot explain, in one sentence, which remote is:

- official upstream
- writable dev remote
- mirror

then stop and fix the repository configuration before doing more Git work.