Dividiendo un repositorio Git en dos, preservando el historial de commits

¿Tu monorepo se está llenando demasiado? Quizá quieras separar el backend en su propio repo, pero no quieres perder el historial de commits. Aquí tienes cómo hacerlo con git filter-repo, sin dramas. 🛠️

¿Por qué dividir un repo?

Separar el desarrollo frontend y backend
Open source solo una parte del proyecto
Archivar o retirar un subproyecto
Mantener todo ordenado

Ejemplo de estructura de carpetas

Supón que tienes un monorepo con una carpeta backend y quieres convertirla en un proyecto API independiente.

Antes de dividir:

monorepo/
├── `backend`/
│   └── ...
├── frontend/
│   └── ...
├── docker-compose.yml
├── README.md
└── ...

Después de dividir (en el nuevo repo):

api/
├── src/
├── config/
├── public/
├── .env
├── composer.json
├── README.md
└── ...

La carpeta backend y su contenido pasan a ser la raíz del nuevo repo API, con todo el historial de commits intacto.

Requisitos previos

git filter-repo (pip install git-filter-repo)
Haz un backup de tu repo original (por si lanzas el comando equivocado)

Guía paso a paso

1. Clona tu repo (limpio)

git clone --no-local <ruta-a-tu-repo> <ruta-nuevo-repo>
cd <ruta-nuevo-repo>

2. Filtra el subdirectorio en el nuevo repo

Ejecuta esto en el nuevo repo:

git filter-repo --subdirectory-filter backend

Esto reescribe el repo para que solo queden el historial y los archivos de backend/, y los mueve a la raíz.

NOTA
git filter-repo eliminará el remote ‘origin’, así que podrás añadir el nuevo después.

3. Crea un nuevo repo en GitHub (o donde quieras)

Crea un repo vacío para tu API.

4. Añade el remoto y haz push

git remote add origin <URL_NUEVO_REPO>
git push -u origin master

5. Mueve o copia archivos raíz y .env

Copia los archivos y variables de entorno que necesites desde la raíz del monorepo original (como .env, docker-compose.yml, etc.). Actualiza la documentación para que nadie se pierda.

¿Qué pasa con el repo original?

El repo original se queda igual. Si solo quieres mantener el historial y quitar el backend, borra los archivos relacionados (backend/, docker-compose.yml, etc.) y haz commit como siempre.

Si quieres borrar todo rastro del backend del historial (por open source o temas legales), ejecuta:

git filter-repo --path backend --invert-paths

Esto reescribe el historial y puede romper los clones locales de tu equipo, así que avisa antes de hacerlo.

Consejos

Haz siempre un backup o clona en limpio antes de reescribir el historial
Avisa a tu equipo antes de hacer push forzado
Mira la docu de git filter-repo para más trucos

Referencias

Documentación de git filter-repo

Dividir un repo es una buena forma de mantener tus proyectos limpios y manejables. Con git filter-repo, conservas el historial y la tranquilidad. 🧑‍💻