primera versión funcional

2026-05-18 10:09:28 +02:00
parent b5cbf0a419
commit ecb2a0c500
5 changed files with 655 additions and 2 deletions
@@ -1,3 +1,112 @@
 # repoman

-Utilitat per clonar masivament repositoris de gitea
+> Utilitat per clonar masivament repositoris de gitea
+
+Lista los repositorios de un usuario u organización en un servidor **Gitea**, los cruza con los que ya tengas clonados en una carpeta local y te deja clonar los que falten desde una lista navegable.
+
+## Uso
+
+```bash
+repoman /ruta/local [<usuario-o-org>]
+```
+
+El segundo argumento es opcional si tienes `default_owner` en la config.
+
+### Interacción
+
+Una vez dentro de la lista:
+
+| Tecla | Acción |
+|---|---|
+| `↑` / `↓` / `j` / `k` | mover cursor |
+| `PgUp` / `PgDn` | saltar 10 |
+| `g` / `G` | inicio / final |
+| `Space` | marcar / desmarcar el repo bajo el cursor |
+| `a` | marcar todos los que aún no estén en local |
+| `n` | desmarcar todo |
+| `Enter` | clonar los marcados (en paralelo) |
+| `r` | refrescar (vuelve a consultar al servidor) |
+| `q` / `Ctrl-C` | salir |
+
+Iconos de estado:
+
+- `○ remoto` — está en el servidor, no clonado localmente
+- `☑ marcado` — pendiente de clonar
+- `⟳ clonando…` — clone en curso
+- `✓ clonado` — éxito
+- `✗ <err>` — clone fallido (motivo abreviado)
+- `● en local` — ya existía en local
+- `◇ sólo local` — está en local pero no en el servidor
+- `🔒` — repo privado
+
+## Configuración
+
+Se carga **siempre** desde `~/.config/repoman/config.toml` (respeta `XDG_CONFIG_HOME`):
+
+```toml
+[server]
+url = "https://gitea.example.com"
+# token = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"   # opcional, para repos privados
+# default_owner = "tu-usuario"                  # opcional, omite el argumento
+# clone_protocol = "https"                      # "https" (por defecto) o "ssh"
+```
+
+El **token** se genera en Gitea en *Settings → Applications → Generate New Token* con el scope `read:repository` como mínimo. Sin token sólo verás repos públicos.
+
+## Requisitos en el sistema
+
+Necesarios siempre:
+
+- `python3` (≥ 3.11, por `tomllib` en stdlib)
+- `git`
+
+Para desarrollar (con venv):
+
+- `python3-venv`
+
+Para compilar a binario con Nuitka (`./build.sh`):
+
+- `python3-dev` — cabeceras `Python.h`
+- `gcc` — compilador C
+- `patchelf` — necesario para el modo `--onefile` en Linux
+
+En Debian/Ubuntu:
+
+```bash
+sudo apt install python3 python3-venv python3-dev git gcc patchelf
+```
+
+## Desarrollo (con venv)
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -r requirements.txt
+.venv/bin/python repoman.py /ruta/local mi-usuario
+```
+
+## Compilar a binario standalone
+
+```bash
+./build.sh
+```
+
+Genera `dist/repoman`, un único ejecutable autocontenido (lleva Python, rich y readchar dentro), más un `dist/repoman-vX.Y.Z-linux-arch.tar.gz` listo para distribuir. Para instalarlo en tu PATH:
+
+```bash
+cp dist/repoman ~/.local/bin/
+```
+
+## Ficheros
+
+- `repoman.py` — script principal
+- `requirements.txt` — dependencias Python (`rich`, `readchar`)
+- `build.sh` — compila el binario con Nuitka
+- `README.md` — este fichero
+- `.venv/` — virtualenv local (no en git)
+- `dist/` — binarios compilados (no en git)
+
+## Notas
+
+- La detección de "ya clonado" compara primero la URL del `origin` con la `clone_url`/`ssh_url` del servidor; si no hay match, cae a comparar por nombre. Eso evita falsos positivos cuando tienes carpetas que se llaman igual pero apuntan a otro servidor.
+- Los clones se ejecutan en paralelo (máx. 4 a la vez).
+- Se usa el endpoint `GET /api/v1/repos/search?owner=<x>` con paginación de 50 en 50, así sirve tanto para usuarios como para organizaciones.