docs: add Spanish README

README.es-ES.md

@@ -0,0 +1,190 @@
+# gitdeck
+
+`gitdeck` es una interfaz de usuario de terminal sin dependencias para gestionar múltiples repositorios de Git bajo una carpeta.
+
+Escanea un directorio raíz, enumera cada árbol de trabajo de Git que encuentra y le permite actualizar el estado, verificar remotos, hacer pull, push, commit, fetch e inspeccionar el estado/logs de un repositorio o de todos los repositorios.
+
+![gitdeck terminal demo](docs/demo.png)
+
+## Ejecución
+
+Recomendado desde un checkout:
+
+```sh
+uv run gitdeck /ruta/a/proyectos
+```
+
+Por ejemplo:
+
+```sh
+uv run gitdeck ~/git
+```
+
+También puede ejecutar el módulo directamente:
+
+```sh
+python -m gitdeck /ruta/a/proyectos
+```
+
+Desde un checkout:
+
+```sh
+PYTHONPATH=src python -m gitdeck ~/git
+```
+
+O instálelo localmente:
+
+```sh
+python -m pip install -e .
+gitdeck ~/git
+```
+
+## Teclas
+
+| Tecla | Acción |
+| --- | --- |
+| `q` | Salir |
+| `j` / `Down` | Mover selección hacia abajo |
+| `k` / `Up` | Mover selección hacia arriba |
+| `g` | Saltar al primer repositorio |
+| `G` | Saltar al último repositorio |
+| `r` | Actualizar estado de todos los repositorios |
+| `n` | Verificar accesibilidad del remoto del repositorio seleccionado |
+| `N` | Verificar remotos de todos los repositorios |
+| `s` | Mostrar `git status --short --branch` para el repositorio seleccionado |
+| `:` | Ejecutar un comando de Git personalizado en el repositorio seleccionado |
+| `Enter` / `v` | Ver archivos modificados del repositorio seleccionado |
+| `i` | Crear o editar el `.gitignore` del repositorio seleccionado |
+| `l` | Mostrar commits recientes del repositorio seleccionado |
+| `f` | Fetch del repositorio seleccionado |
+| `F` | Fetch de todos los repositorios |
+| `p` | Pull del repositorio seleccionado |
+| `P` | Pull de todos los repositorios |
+| `u` | Push del repositorio seleccionado |
+| `U` | Push de todos los repositorios |
+| `c` | Commit del repositorio seleccionado con `git add -A`; presione `p` en la pantalla de resultado para hacer push |
+| `C` | Commit de todos los repositorios sucios con `git add -A`; presione `p` en la pantalla de resultado para hacer push de los commits exitosos |
+| `?` | Mostrar ayuda |
+
+## Teclas de Vista de Archivos
+
+Presione `Enter` en un repositorio para inspeccionar sus archivos modificados. `v` también funciona.
+
+| Tecla | Acción |
+| --- | --- |
+| `j` / `Down` | Mover selección hacia abajo |
+| `k` / `Up` | Mover selección hacia arriba |
+| `g` | Saltar al primer archivo |
+| `G` | Saltar al último archivo |
+| `Space` / `a` | Preparar (stage) el archivo seleccionado |
+| `A` | Preparar todos los archivos del repositorio inmediatamente |
+| `x` | Deshacer preparación (unstage) del archivo seleccionado |
+| `X` | Deshacer preparación de todos los archivos del repositorio |
+| `c` | Commit de este repositorio con `git add -A`; presione `p` en la pantalla de resultado para hacer push |
+| `p` | Pull de este repositorio |
+| `u` | Push de este repositorio |
+| `:` | Ejecutar un comando de Git personalizado en este repositorio |
+| `b` / `r` | Volver a la lista de repositorios |
+
+Los comandos masivos se ejecutan secuencialmente y continúan aunque un repositorio falle. La salida final se muestra en un panel de detalles desplazable.
+
+## Comandos de Git Personalizados
+
+Presione `:` en un repositorio para ejecutar un comando de Git ad-hoc en ese repositorio. Puede escribir los argumentos o un comando `git ...` completo:
+
+```text
+status --short
+git log --oneline -n 20
+diff --stat
+```
+
+La salida del comando se abre en la vista de detalles desplazable de gitdeck.
+
+## Configuración
+
+Gitdeck lee un archivo de configuración opcional desde `$GITDECK_CONFIG`, o desde:
+
+```text
+~/.config/gitdeck/config
+```
+
+Cree una configuración inicial:
+
+```sh
+uv run gitdeck --write-config
+```
+
+Ejemplo:
+
+```ini
+[keys]
+# Descomente una línea para anular esa acción. Los valores son alias separados por comas.
+# Vista principal:
+# quit = q, Esc
+# help = ?
+# open-files = Enter, v
+# refresh = r
+# check-net = n
+# check-net-all = N
+# status = s
+# log = l
+# edit-gitignore = i
+# fetch = f
+# fetch-all = F
+# pull = p
+# pull-all = P
+# push = u
+# push-all = U
+# commit = c
+# commit-all = C
+# custom-git-command = :
+
+# Vistas de detalle/archivos:
+# back = b, r, Enter
+# stage-file = Space, a
+# stage-all = A
+# unstage-file = x
+# unstage-all = X
+
+[colors]
+# selected_fg = black
+# selected_bg = cyan
+# clean = green
+# dirty = yellow
+# error = red
+# title = cyan
+# staged = cyan
+
+[scan]
+# Vacío significa escaneo recursivo ilimitado.
+# max_depth =
+# ignore_dirs = .git, .hg, .svn, node_modules, .venv, venv
+```
+
+Los nombres de las teclas son alias separados por comas. Definir una acción reemplaza los valores predeterminados de esa acción, por lo que debe incluir cada tecla que desee conservar. Por ejemplo, `push = o` cambia el push del repositorio seleccionado a `o`; `push-all = U` permanece separado a menos que se cambie. Los nombres especiales comunes son `Enter`, `Esc`, `Space`, `Up`, `Down`, `Left`, `Right`, `PgUp` y `PgDn`.
+
+Gitdeck advierte sobre conflictos de teclas dentro del mismo contexto de pantalla. Se permite reutilizar una tecla en diferentes pantallas, como `r` para actualizar en la vista principal y para volver atrás en una vista de detalle.
+
+Los nombres de colores disponibles son `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white` y `default`. `default` utiliza el color predeterminado actual de la terminal.
+
+## Leyenda de Estado
+
+| Indicador | Significado |
+| --- | --- |
+| fila verde | Limpio y sincronizado con el upstream |
+| fila amarilla | Tiene cambios locales, commits adelantados o commits atrasados |
+| fila roja | Error de estado o conflictos de fusión |
+| `S<n>` | Recuento de archivos preparados (staged) |
+| `M<n>` | Recuento de archivos modificados pero no preparados |
+| `?<n>` | Recuento de archivos no rastreados |
+| `!<n>` | Recuento de archivos con conflicto |
+| `+a/-b` | Commits adelantados de / atrasados respecto al upstream |
+| `net ?` | La accesibilidad del remoto aún no se ha verificado; presione `n` o `N` |
+| `<branch> (unborn)` | El repositorio aún no tiene un primer commit |
+
+## Notas
+
+- La accesibilidad remota utiliza `git ls-remote --exit-code <remote> HEAD` con un tiempo de espera corto. Solo se verifica cuando presiona `n` o `N` para evitar ralentizar las actualizaciones normales.
+- Los comandos de commit preparan todos los cambios en el repositorio objetivo antes de realizar el commit.
+- El editor de `.gitignore` utiliza `$VISUAL`, luego `$EDITOR`, y finalmente `vi`. Si el repositorio seleccionado no tiene un `.gitignore`, gitdeck crea uno primero a partir de su plantilla inicial integrada.
+- Los repositorios anidados debajo de un árbol de trabajo descubierto se omiten deliberadamente; esto evita descender en submódulos o repositorios de terceros a menos que ejecute `gitdeck` desde una raíz más estrecha.