Sobre el proyecto

Muchas veces se suben ramas a producción, se mergean y se quedan abandonadas en local sin que nadie las borre. Con el tiempo se acumulan decenas de ramas que ensucian el output de git branch y dificultan el día a día.

Forgotten Branches escanea cualquier repositorio git, analiza cada rama local y te dice cuáles son seguras de eliminar, cuáles es mejor archivar y cuáles están activas. Ofrece dos interfaces: una Web UI que se abre en el navegador y una Terminal UI (TUI) interactiva con navegación por teclado.

¿Por qué esta herramienta?

• Sin depender de un servidor — Todo se ejecuta en local, sin conexión externa.
• Clasificación inteligente — No solo lista ramas: las clasifica según su estado real (mergeadas, huérfanas, abandonadas...).
• Dos interfaces — Web UI moderna con tema One Dark Pro, y TUI interactiva para la terminal (Ink + React).
• Archivado — Guarda el historial de ramas que ya no necesitas sin perder la referencia.
• Borrado en masa — Limpia decenas de ramas en segundos.
• Protección de ramas — main/master y la rama actual están protegidas contra borrado/archivado.

Plataformas soportadas

• macOS
• Linux
• Windows con WSL

Primeros pasos

Prerrequisitos

• Node.js 18 o superior
• pnpm 9 o superior (npm install -g pnpm)
• Git 2.30 o superior

Instalación

Instalación global (recomendada)

git clone https://github.com/raulfdeztdo/forgottenbranches.git
cd forgottenbranches
chmod +x install.sh update.sh uninstall.sh
./install.sh

El script instala las dependencias, compila el proyecto y registra el comando forgottenbranches de forma global.

Instalación como dependencia de proyecto (npm)

npm install forgottenbranches
# o
pnpm add forgottenbranches

Al instalarlo como dependencia, la herramienta detecta automáticamente el proyecto actual (process.cwd()) y escanea sus ramas sin necesidad de introducir la ruta manualmente.

npx forgottenbranches            # prompt Web/TUI para el proyecto actual
npx forgottenbranches --tui      # TUI directamente
npx forgottenbranches --web      # Web UI directamente

También puedes usarlo como API programática:

import { getBranches, deleteBranch, archiveBranch } from 'forgottenbranches';

const result = await getBranches('/path/to/repo');
console.log(result.branches);

Actualizar

./update.sh

Hace git pull, reinstala dependencias si hay nuevas y recompila. Si ya estás en la última versión te lo indica sin hacer nada.

Uso

# Modo interactivo — elige entre Web UI y Terminal
forgottenbranches

# Web UI directamente (abre el navegador)
forgottenbranches --web

# Terminal UI directamente
forgottenbranches --tui

# Abrir y escanear un repo directamente
forgottenbranches --web /home/usuario/proyectos/mi-app
forgottenbranches --tui /home/usuario/proyectos/mi-app

En el modo interactivo, la aplicación muestra un prompt para elegir entre la interfaz web y la interfaz de terminal.

Estados de las ramas

| Estado | Color | Significado | |--------|-------|-------------| | Active | 🟢 | Actividad reciente, en uso | | Forgotten | 🔴 | Mergeada en main + upstream borrado del remoto | | Orphan | 🟠 | Upstream borrado del remoto, sin mergear | | Merged | 🟡 | Ya está en main, upstream sigue vivo | | Abandoned | ⚪ | Sin actividad en +90 días (o +60 sin upstream) |

Terminal UI (TUI)

La TUI ofrece una experiencia interactiva completa directamente en la terminal, construida con Ink (React para terminal) y React 19.

Navegación por teclado

| Tecla | Acción | |---|---| | ↑ / ↓ | Navegar entre ramas / ciclar filtros | | ← / → | Cambiar campo de ordenación | | ↵ Enter | Expandir/colapsar detalle de rama | | Space | Seleccionar/deseleccionar rama | | Tab | Alternar vista Branches / Archived | | / | Editar la ruta del repositorio | | s | Escanear repositorio | | f | Enfocar filtros (estado y orden) | | a | Archivar rama(s) seleccionada(s) | | d | Eliminar rama(s) seleccionada(s) | | r | Restaurar rama archivada (en vista Archived) | | D | Eliminar permanentemente archivada | | q / Esc | Salir |

Operaciones en masa

Selecciona varias ramas con Space y ejecuta la acción (a archivar / d eliminar / r restaurar). Un contador muestra cuántas ramas están seleccionadas y qué acción se ejecutará.

Ramas protegidas

Las ramas main, master y la rama actualmente activa (checked-out) están protegidas contra archivado y eliminación, tanto en la Web UI como en la TUI.

• Indicador visual: icono 🔒 junto al nombre de la rama
• Motivo: tooltip/texto indicando si es "main branch" o "current checked-out branch"
• Acciones bloqueadas: los botones de Archive/Delete se ocultan o muestran un mensaje explicativo

Funcionalidades

• Dos interfaces — Web UI (One Dark Pro) y Terminal UI (Ink + React) con navegación completa por teclado.
• Análisis completo por rama — nombre, upstream, último commit (hash, autor, fecha, mensaje), antigüedad, último checkout del reflog.
• Información de merge — qué commit la mergeó en main, cuándo y con qué mensaje.
• Panel de detalle desplegable — clic en cualquier rama para ver todos los datos (Web UI); ↵ para expandir (TUI).
• Ramas protegidas — main, master y rama actual marcadas con 🔒. No se pueden archivar ni borrar.
• Vista de archivadas — Tab para alternar entre ramas activas y archivadas. Restaurar o eliminar permanentemente.
• Eliminar ramas — individual o en masa, con borrado seguro (-d) o forzado (-D).
• Archivar ramas — crea un tag anotado archive/<nombre> y borra la rama local.
• Desarchivar — restaura la rama desde el tag de archivo.
• Selección múltiple — checkboxes en cada fila con barra de acciones para operar sobre varias ramas a la vez.
• Operaciones en masa en TUI — Space para seleccionar, a/d/r/D para actuar sobre todas las seleccionadas.
• Historial de proyectos — las rutas escaneadas se guardan en localStorage (Web UI).
• Filtros — por nombre de rama y por estado mediante pills interactivas (Web) o teclado (TUI).
• Ordenación — por nombre, fecha de commit, antigüedad o estado (por defecto: activas primero).

Testing

El proyecto incluye una suite completa de tests automatizados que cubren backend, frontend, y flujos end-to-end.

pnpm test              # Unit + integration tests (Vitest)
pnpm test:watch        # Modo watch
pnpm test:ui           # Interfaz visual de Vitest
pnpm test:coverage     # Reporte de cobertura
pnpm test:e2e          # Tests end-to-end (Playwright)
pnpm test:e2e:ui       # Playwright UI
pnpm test:all          # Todos los tests

Estructura de tests

| Capa | Tecnología | Ubicación | |---|---|---| | Lógica git (git.ts) | Vitest + mock child_process | server/src/git.test.ts | | API REST (app.ts) | Vitest + supertest | server/src/app.test.ts | | Componentes React | Vitest + Testing Library + jsdom | client/src/components/*.test.tsx | | End-to-end | Playwright (Chromium) | e2e/*.spec.ts |

Convenciones

• Los tests se co-localizan con el código fuente (src/foo.ts → src/foo.test.ts)
• TDD siempre que sea posible: escribe el test antes del código
• Antes de un PR: pnpm run build && pnpm test && pnpm test:e2e
• Más información en .agents/skills/testing/SKILL.md

Desarrollo

# Instalar dependencias (workspaces server + client en un solo comando)
pnpm install

# Iniciar servidores de desarrollo (Express :3001 + Vite :5173)
pnpm run dev

# Compilar para producción
pnpm run build

El backend escucha en localhost:3001 y el frontend en localhost:5173 con proxy de Vite hacia la API.

Cómo funciona

┌─────────────┐      ┌──────────────┐     ┌───────────┐
│  React UI   │────▶│  Express API │────▶│  git CLI  │
│  (Vite)     │◀────│  (Node.js)   │◀────│  (local)  │
└─────────────┘      └──────────────┘     └───────────┘

El backend Express ejecuta comandos git directamente sobre tus repositorios locales usando child_process. El frontend React muestra los resultados en una interfaz con tema One Dark Pro. En producción, un solo proceso Node.js sirve tanto la API como el frontend compilado — no necesitas arrancar dos procesos.

Todo ocurre en tu máquina. No se envía ningún dato al exterior.

Licencia

Distribuido bajo la licencia MIT. Ver LICENSE para más información.

Contacto

Raúl Fernández Tirado — @raulfdeztdo

Repositorio: https://github.com/raulfdeztdo/forgottenbranches