'python/Gitea PyPI Package Registry.md'

git/Git-Historie durchsuchen.md

@@ -0,0 +1,133 @@
+# Git-Historie durchsuchen
+
+## Kurzfassung
+
+`rg` durchsucht normalerweise den aktuellen Dateistand. Auch mit
+`--hidden --no-ignore` wird die eigentliche Git-Historie nicht zuverlässig
+durchsucht: Die historischen Objekte liegen unter `.git/objects` komprimiert
+und über ihre Hashes organisiert.
+
+Für die Git-Historie verwendet man je nach Fragestellung `git log`, `git grep`
+und `git rev-list`.
+
+## Änderungen mit `git log` finden
+
+### Exakte Zeichenfolge: `-S`
+
+Mit `-S` findet man Commits, in denen sich die Anzahl einer exakten
+Zeichenfolge geändert hat — also typischerweise, wenn eine Zeichenfolge
+hinzugefügt oder entfernt wurde:
+
+```bash
+git log --all -S'example_endpoint' --oneline
+```
+
+Die zugehörigen Änderungen anzeigen:
+
+```bash
+git log --all -S'example_endpoint' -p
+```
+
+### Regulärer Ausdruck: `-G`
+
+Mit `-G` sucht Git in hinzugefügten und entfernten Zeilen nach einem regulären
+Ausdruck:
+
+```bash
+git log --all -G'example[_-]endpoint' --oneline
+```
+
+Mit Patch-Ausgabe:
+
+```bash
+git log --all -G'example[_-]endpoint' -p
+```
+
+`--all` bezieht alle Commits ein, die von lokalen Branches, Remote-Tracking-
+Branches und Tags erreichbar sind.
+
+## Vollständige historische Dateistände durchsuchen
+
+`git log -S` und `git log -G` suchen nach Änderungen. Wenn stattdessen jeder
+vollständige Dateistand durchsucht werden soll, kann man `git grep` mit
+`git rev-list` kombinieren:
+
+```bash
+git rev-list --all |
+  while read commit; do
+    git grep -n -E 'example[_-]endpoint' "$commit" -- &&
+      echo "Found in $commit"
+  done
+```
+
+Die Ausgabe enthält die Commit-ID, die betroffene Datei und die Zeilennummer.
+Einen einzelnen historischen Dateistand kann man direkt durchsuchen:
+
+```bash
+git grep -n -E 'example[_-]endpoint' <COMMIT>
+```
+
+Ein Commit kann beispielsweise ein vollständiger Hash, ein Branch-Name oder
+ein Tag sein:
+
+```bash
+git grep -n -E 'example[_-]endpoint' HEAD~10
+git grep -n -E 'example[_-]endpoint' v1.2.0
+```
+
+## Reflog und nicht mehr erreichbare Commits
+
+`--all` findet nur Commits, die noch über Referenzen erreichbar sind. Kürzlich
+gelöschte Branches können zusätzlich über die Reflogs gefunden werden:
+
+```bash
+git log --all --reflog -G'example[_-]endpoint' --oneline
+```
+
+Falls ein Commit weder über Branches, Tags noch Reflogs erreichbar ist, kann
+Git ihn eventuell noch als unerreichbares Objekt kennen:
+
+```bash
+git fsck --full --no-reflogs --unreachable
+```
+
+Nur unerreichbare Commits durchsuchen:
+
+```bash
+git fsck --full --no-reflogs --unreachable |
+  awk '$2 == "commit" { print $3 }' |
+  while read commit; do
+    git grep -n -E 'example[_-]endpoint' "$commit" -- &&
+      echo "Found in $commit"
+  done
+```
+
+Das funktioniert nur, solange die Objekte noch nicht durch Garbage Collection
+entfernt wurden. Bei einem Shallow Clone kann außerdem die ältere Historie
+lokal fehlen.
+
+## `rg` und `.git`
+
+Der Befehl:
+
+```bash
+rg --hidden --no-ignore '/example[\_\-]endpoint'
+```
+
+durchsucht den aktuellen Dateibaum einschließlich normalerweise versteckter
+Dateien. Er durchsucht jedoch nicht sinnvoll die komprimierten historischen
+Git-Objekte unter `.git/objects`.
+
+Für den regulären Ausdruck genügt normalerweise:
+
+```text
+example[_-]endpoint
+```
+
+Der führende `/` ist ein wörtliches Zeichen und sollte nur verwendet werden,
+wenn tatsächlich ein Slash vor `example` gesucht werden soll. Die Backslashes
+vor `_` und `-` sind hier ebenfalls nicht erforderlich.
+
+Für die Suche im aktuellen Dateistand siehe [[Linux/ripgrep_guide]]. Für
+Informationen darüber, warum alte Historie fehlen oder umgeschrieben worden
+kann, siehe [[Git-History-Truncation]].

python/Gitea PyPI Package Registry.md

@@ -0,0 +1,262 @@
+# Python-Paket auf Gitea veröffentlichen
+
+Gitea kann als private oder öffentliche PyPI-Registry verwendet werden. Damit lassen sich eigene Python-Pakete bauen, versionieren und in anderen Projekten mit `pip` oder `uv` installieren.
+
+Diese Anleitung verwendet `utils` als Beispielpaket und den Gitea-Server `gitea.schneiderserver.site`.
+
+## Voraussetzungen
+
+- ein Python-Projekt mit `pyproject.toml`
+- ein Gitea-Repository
+- `uv` für Environment, Tests und Build
+- `twine` für das Veröffentlichen
+- ein privater Gitea Personal Access Token
+
+Verwandt: [[uv]] und [[pytest]].
+
+## Paket lokal bauen
+
+Im Projektverzeichnis:
+
+```bash
+uv sync
+uv run pytest
+uv build
+```
+
+Danach liegen normalerweise zwei Dateien in `dist/`:
+
+```text
+dist/utils-0.1.0.tar.gz
+dist/utils-0.1.0-py3-none-any.whl
+```
+
+Vor einem erneuten Build kann `dist/` entfernt werden:
+
+```bash
+rm -rf dist
+uv build
+```
+
+## Gitea-Endpunkte
+
+Der Owner ist der Gitea-Benutzer oder die Organisation, unter der das Paket veröffentlicht wird. Er ist nicht zwingend der Repository-Name.
+
+Publish-Endpunkt:
+
+```text
+https://<gitea-host>/api/packages/<owner>/pypi
+```
+
+Installations-Endpunkt:
+
+```text
+https://<gitea-host>/api/packages/<owner>/pypi/simple
+```
+
+Für den eigenen Server und den Benutzer `mathias` lautet das beispielsweise:
+
+```text
+https://gitea.schneiderserver.site/api/packages/mathias/pypi
+https://gitea.schneiderserver.site/api/packages/mathias/pypi/simple
+```
+
+## Token
+
+`YOUR_GITEA_TOKEN` steht für einen **privaten Personal Access Token** aus Gitea. Es handelt sich nicht um einen öffentlichen Token.
+
+Für das Veröffentlichen wird mindestens eine Berechtigung zum Schreiben von Packages benötigt, typischerweise `write:package`. Für die Installation privater Packages wird `read:package` benötigt. Die genauen Namen können je nach Gitea-Version leicht abweichen.
+
+Den Token niemals:
+
+- in Git committen
+- in eine README schreiben
+- im Chat oder in Logs veröffentlichen
+- dauerhaft direkt in die Shell-History schreiben
+
+Für CI/CD sollte der Token als Gitea-Action-Secret hinterlegt werden, zum Beispiel als `GITEA_TOKEN`.
+
+## Manuell mit Twine veröffentlichen
+
+Twine installieren:
+
+```bash
+uv tool install twine
+```
+
+`~/.pypirc` anlegen oder ergänzen:
+
+```ini
+[distutils]
+index-servers =
+    gitea
+
+[gitea]
+repository = https://gitea.schneiderserver.site/api/packages/mathias/pypi
+username = mathias
+password = YOUR_PRIVATE_GITEA_TOKEN
+```
+
+Anschließend veröffentlichen:
+
+```bash
+python -m twine upload --repository gitea dist/*
+```
+
+Gitea akzeptiert denselben Paketnamen mit derselben Versionsnummer nicht zweimal. Für eine neue Veröffentlichung muss daher zuerst die Version in `pyproject.toml` erhöht werden:
+
+```toml
+version = "0.1.1"
+```
+
+Danach erneut bauen und veröffentlichen:
+
+```bash
+rm -rf dist
+uv build
+python -m twine upload --repository gitea dist/*
+```
+
+## In einem anderen Projekt installieren
+
+### Öffentliches Paket
+
+Wenn das Package und die Registry anonym lesbar sind:
+
+```bash
+pip install \
+  --index-url https://gitea.schneiderserver.site/api/packages/mathias/pypi/simple \
+  utils
+```
+
+### Privates Paket
+
+Für ein privates Package ist ein Token mit `read:package` erforderlich:
+
+```bash
+pip install \
+  --index-url https://<username>:<read-token>@gitea.schneiderserver.site/api/packages/mathias/pypi/simple \
+  utils
+```
+
+Dasselbe funktioniert mit `uv`:
+
+```bash
+uv pip install \
+  --index-url https://<username>:<read-token>@gitea.schneiderserver.site/api/packages/mathias/pypi/simple \
+  utils
+```
+
+Tokens besser nicht direkt in Befehle schreiben, weil sie in der Shell-History oder Prozessliste sichtbar werden können. Für lokale Nutzung besser einen Credential-Helper oder eine geschützte Konfigurationsdatei verwenden; in CI ausschließlich Secrets verwenden.
+
+## `--index-url` und `--extra-index-url`
+
+Für private interne Packages ist `--index-url` vorzuziehen:
+
+```bash
+pip install --index-url <gitea-pypi-simple-url> utils
+```
+
+`--extra-index-url` kann zu Dependency-Confusion-Problemen führen, weil ein gleichnamiges öffentliches Paket von PyPI aufgelöst werden könnte. Falls zusätzlich öffentliche PyPI-Abhängigkeiten gebraucht werden, sollte die Paketquellen-Konfiguration bewusst und projektbezogen eingerichtet werden.
+
+## Git-Tags und Releases
+
+Git-Tag und Paketversion sollten übereinstimmen:
+
+```text
+pyproject.toml: version = "0.1.0"
+Git-Tag:        v0.1.0
+```
+
+Beispiel:
+
+```bash
+git add pyproject.toml
+git commit -m "Release version 0.1.0"
+git tag v0.1.0
+git push origin main
+git push origin v0.1.0
+```
+
+Das Tagging ist nicht zwingend für den manuellen Upload, macht Releases aber nachvollziehbar und kann später als Auslöser für Gitea Actions dienen.
+
+## Automatisierung mit Gitea Actions
+
+Ein Workflow kann bei jedem `v*`-Tag automatisch testen, bauen und veröffentlichen. Die Zugangsdaten gehören als Repository-Secrets in Gitea und nicht in die Workflow-Datei.
+
+Beispiel für `.gitea/workflows/publish.yml`:
+
+```yaml
+name: Publish package
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Install uv
+        run: pip install uv
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run tests
+        run: uv run pytest
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to Gitea
+        env:
+          TWINE_USERNAME: ${{ secrets.GITEA_USERNAME }}
+          TWINE_PASSWORD: ${{ secrets.GITEA_TOKEN }}
+          TWINE_REPOSITORY_URL: https://gitea.schneiderserver.site/api/packages/mathias/pypi
+        run: uv run --with twine twine upload dist/*
+```
+
+Dazu in Gitea die Secrets `GITEA_USERNAME` und `GITEA_TOKEN` konfigurieren.
+
+## Fehlersuche: `404 Not Found`
+
+Bei einem Fehler wie:
+
+```text
+HTTPError: 404 Not Found from https://gitea.schneiderserver.site/api/packages/mathias/pypi
+```
+
+ist der Token wahrscheinlich nicht das Hauptproblem. Ungültige Zugangsdaten führen meistens zu `401 Unauthorized` oder `403 Forbidden`.
+
+Folgende Punkte prüfen:
+
+1. Ist `mathias` exakt der Gitea-Benutzername oder Organisationsname?
+2. Wird der Repository-Owner statt des Repository-Namens verwendet?
+3. Ist die Package Registry in der Gitea-Instanz aktiviert?
+4. Wird der Gitea-Server über einen Reverse Proxy mit einem URL-Präfix betrieben?
+5. Wird der Publish-Endpunkt ohne `/simple` verwendet?
+6. Ist der Token noch gültig und besitzt er `write:package`?
+
+Der Gitea-API-Endpunkt kann unabhängig davon erreichbar sein:
+
+```bash
+curl https://gitea.schneiderserver.site/api/v1/version
+```
+
+Der Publish-Endpunkt antwortet auf einen normalen `GET`-Aufruf möglicherweise mit `405 Method Not Allowed`, weil er nur Upload-Anfragen akzeptiert. Das ist ein Hinweis darauf, dass der Endpunkt existiert; ein `404` deutet eher auf einen falschen Owner, einen falschen Pfad oder eine deaktivierte Registry hin.
+
+## Offizielle Dokumentation
+
+- [Gitea PyPI Package Registry](https://docs.gitea.com/usage/packages/pypi/)
+- [Gitea Package Registry Übersicht](https://docs.gitea.com/usage/packages/overview/)