# Documentación: Script de Actualización de Proyectos Git

## Descripción General

`git_pull_projects.sh` es un script de Bash diseñado para automatizar la actualización de proyectos Laravel alojados en servidores cPanel/WHM. Este script complementa al script de setup (`setup_cd_project2.sh`) y facilita la gestión de múltiples proyectos mediante operaciones de `git pull` automatizadas.

---

## Características Principales

### �� Actualización Flexible
- **Proyecto individual**: Actualiza un proyecto específico por nombre
- **Múltiples proyectos**: Actualiza varios proyectos en una sola ejecución
- **Actualización masiva**: Actualiza todos los proyectos disponibles en el servidor
- **Listado de proyectos**: Visualiza todos los proyectos con información detallada

### �� Automatización Inteligente
El script detecta automáticamente cambios críticos después del `git pull` y ejecuta las acciones necesarias:

- **Dependencias de Composer**: Si detecta cambios en `composer.lock`, ejecuta `composer install` automáticamente
- **Migraciones de base de datos**: Si detecta cambios en `database/migrations/`, ejecuta `php artisan migrate --force`
- **Limpieza de caché**: Ejecuta automáticamente:
  - `php artisan config:clear`
  - `php artisan cache:clear`
  - `php artisan view:clear`

### ��️ Manejo Seguro de Cambios Locales
- Detecta cambios sin commitear antes del pull
- Ofrece la opción de hacer `git stash` de forma interactiva
- Permite cancelar la operación para revisar cambios manualmente

### �� Información Detallada
- Muestra la rama actual antes de actualizar
- Lista los últimos 3 commits después de cada actualización
- Proporciona resúmenes de éxito/error al finalizar
- Utiliza colores para facilitar la lectura de los resultados

---

## Requisitos

### Permisos
- **Debe ejecutarse como root** (igual que el script de setup)

### Dependencias
- Bash 4.0 o superior
- Git instalado y configurado
- Composer instalado globalmente
- PHP instalado
- Acceso SSH configurado para clonar repositorios

### Estructura de Proyectos
El script espera que los proyectos sigan la estructura creada por `setup_cd_project2.sh`:
```
/home/{username}/public_html/git-files/{project_name}/.git
```

---

## Instalación

1. **Descargar el script**:
   ```bash
   cd /root
   wget [URL_del_script]/git_pull_projects.sh
   # O usar curl, scp, etc.
   ```

2. **Dar permisos de ejecución**:
   ```bash
   chmod +x git_pull_projects.sh
   ```

3. **Opcional - Mover a directorio en PATH**:
   ```bash
   mv git_pull_projects.sh /usr/local/bin/
   # Ahora puedes ejecutarlo desde cualquier ubicación
   ```

---

## Modos de Uso

### 1. Listar Proyectos Disponibles

Muestra todos los proyectos encontrados en el servidor con información detallada.

**Sintaxis**:
```bash
./git_pull_projects.sh --list
# o
./git_pull_projects.sh -l
```

**Información mostrada**:
- Nombre del proyecto
- Usuario propietario
- Rama actual
- Ruta completa del proyecto
- Último commit (hash y mensaje)
- Total de proyectos encontrados

**Ejemplo de salida**:
```
=========================================
  PROYECTOS DISPONIBLES
=========================================

Proyecto: coke
  Usuario: coke
  Rama: main
  Ruta: /home/coke/public_html/git-files/coke
  Último commit: a1b2c3d - Added new feature

Proyecto: pepsi
  Usuario: pepsi
  Rama: develop
  Ruta: /home/pepsi/public_html/git-files/pepsi
  Último commit: e4f5g6h - Fixed bug in payment

ℹ Total de proyectos encontrados: 2
```

---

### 2. Actualizar un Proyecto Específico

Actualiza un único proyecto por nombre.

**Sintaxis**:
```bash
./git_pull_projects.sh --project <nombre_proyecto>
# o
./git_pull_projects.sh -p <nombre_proyecto>
```

**Ejemplo**:
```bash
./git_pull_projects.sh --project coke
```

**Proceso ejecutado**:
1. Busca el proyecto en el sistema
2. Verifica la rama actual
3. Detecta cambios sin commitear (ofrece hacer stash si es necesario)
4. Ejecuta `git pull`
5. Detecta cambios en `composer.lock` → ejecuta `composer install`
6. Detecta cambios en migrations → ejecuta `php artisan migrate --force`
7. Limpia cachés de Laravel
8. Muestra los últimos 3 commits

**Ejemplo de salida**:
```
=========================================
  ACTUALIZANDO: coke
=========================================
ℹ Proyecto encontrado en: /home/coke/public_html/git-files/coke
ℹ Usuario: coke
ℹ Rama actual: main
ℹ Ejecutando git pull...
✓ Git pull completado exitosamente
ℹ Detectados cambios en composer.lock, ejecutando composer install...
ℹ Limpiando caché...
✓ Git pull completado exitosamente

ℹ Últimos 3 commits:
a1b2c3d Added new feature
e4f5g6h Fixed bug in payment
i7j8k9l Updated dependencies
```

---

### 3. Actualizar Múltiples Proyectos

Actualiza varios proyectos específicos en una sola ejecución.

**Sintaxis**:
```bash
./git_pull_projects.sh --multiple <proyecto1,proyecto2,proyecto3>
# o
./git_pull_projects.sh -m <proyecto1,proyecto2,proyecto3>
```

**Importante**: Los nombres de proyectos deben estar separados por comas sin espacios.

**Ejemplos**:
```bash
# Actualizar 3 proyectos
./git_pull_projects.sh --multiple coke,pepsi,sprite

# También funciona con espacios alrededor de las comas (se eliminan automáticamente)
./git_pull_projects.sh -m coke, pepsi, sprite
```

**Ejemplo de salida**:
```
=========================================
  ACTUALIZANDO: coke
=========================================
[... proceso de actualización ...]
✓ Git pull completado exitosamente

=========================================
  ACTUALIZANDO: pepsi
=========================================
[... proceso de actualización ...]
✓ Git pull completado exitosamente

=========================================
  ACTUALIZANDO: sprite
=========================================
[... proceso de actualización ...]
✓ Git pull completado exitosamente

=========================================
  RESUMEN
=========================================
✓ Proyectos actualizados: 3
```

---

### 4. Actualizar Todos los Proyectos

Actualiza automáticamente todos los proyectos encontrados en el servidor.

**Sintaxis**:
```bash
./git_pull_projects.sh --all
# o
./git_pull_projects.sh -a
```

**Comportamiento**:
- Escanea todos los directorios de usuarios en `/home/`
- Busca proyectos en `public_html/git-files/*/`
- Actualiza cada proyecto encontrado
- Proporciona un resumen final con totales de éxito/error

**Ejemplo de salida**:
```
=========================================
  ACTUALIZANDO TODOS LOS PROYECTOS
=========================================

=========================================
  ACTUALIZANDO: coke
=========================================
[... proceso ...]
✓ Git pull completado exitosamente

=========================================
  ACTUALIZANDO: pepsi
=========================================
[... proceso ...]
✓ Git pull completado exitosamente

=========================================
  RESUMEN
=========================================
✓ Proyectos actualizados: 2
```

---

### 5. Mostrar Ayuda

Muestra la información de uso del script.

**Sintaxis**:
```bash
./git_pull_projects.sh --help
# o
./git_pull_projects.sh -h
# o simplemente
./git_pull_projects.sh
```

---

## Manejo de Situaciones Especiales

### Cambios Locales Sin Commitear

Si el script detecta cambios sin commitear, mostrará:

```
⚠ El proyecto tiene cambios sin commitear:
 M app/Http/Controllers/UserController.php
 M resources/views/welcome.blade.php
¿Desea hacer stash y continuar? (s/N):
```

**Opciones**:
- **Presionar `s` o `S`**: Hace `git stash` de los cambios y continúa con el pull
- **Presionar `N` o Enter**: Salta el proyecto y continúa con el siguiente (si hay más)

### Errores en Composer o Migraciones

Si `composer install` o las migraciones fallan:
- El script muestra una advertencia pero **NO detiene** el proceso
- Continúa con la limpieza de caché y los siguientes proyectos
- El error se registra en el resumen final

**Ejemplo**:
```
⚠ Error ejecutando composer install
⚠ Error ejecutando migraciones
```

### Proyecto No Encontrado

Si intentas actualizar un proyecto que no existe:
```
✗ Proyecto 'proyecto_inexistente' no encontrado
```

---

## Código de Salida

El script utiliza códigos de salida estándar:

- **0**: Ejecución exitosa
- **1**: Error (permisos insuficientes, proyecto no encontrado, etc.)

---

## Seguridad y Buenas Prácticas

### Permisos
- El script **DEBE** ejecutarse como root
- Opera con el usuario correcto usando `su - ${username}`
- Respeta los permisos de archivos y directorios

### Validaciones
- Verifica que los directorios existan antes de operar
- Valida que los proyectos tengan repositorios Git válidos
- Maneja errores de forma segura sin detener todo el proceso

### Colores en Output
El script utiliza códigos ANSI para colores:
- �� Azul: Información general
- �� Verde: Operaciones exitosas
- �� Amarillo: Advertencias
- �� Rojo: Errores

---

## Casos de Uso Comunes

### Actualización Rutinaria Diaria
```bash
# Actualizar todos los proyectos cada día
./git_pull_projects.sh --all
```

### Actualización Después de un Deploy
```bash
# Actualizar solo los proyectos afectados
./git_pull_projects.sh --multiple coke,pepsi
```

### Verificación Antes de Actualizar
```bash
# Listar proyectos para verificar
./git_pull_projects.sh --list

# Actualizar proyecto específico
./git_pull_projects.sh --project coke
```

### Automatización con Cron
```bash
# Añadir a crontab para actualización automática diaria a las 3 AM
0 3 * * * /root/git_pull_projects.sh --all >> /var/log/git_pull_projects.log 2>&1
```

---

## Resolución de Problemas

### Error: "Este script debe ejecutarse como root"
**Causa**: Intentaste ejecutar el script sin privilegios root.
**Solución**:
```bash
sudo su
./git_pull_projects.sh --all
```

### Error: "Proyecto 'xxx' no encontrado"
**Causas posibles**:
1. El nombre del proyecto está mal escrito
2. El proyecto no tiene un repositorio Git
3. La estructura de directorios no coincide con la esperada

**Solución**:
```bash
# Verificar proyectos disponibles
./git_pull_projects.sh --list

# Usar el nombre exacto mostrado
./git_pull_projects.sh --project nombre_correcto
```

### Git Pull Falla
**Causas posibles**:
1. Problemas de red
2. Claves SSH no configuradas
3. Conflictos de merge
4. Rama remota eliminada

**Solución**:
```bash
# Verificar manualmente
su - username
cd ~/public_html/git-files/proyecto
git status
git pull
```

### Composer Install Falla
**Causas posibles**:
1. Falta memoria
2. Dependencias no disponibles
3. composer.json corrupto

**Solución**:
```bash
# Ejecutar manualmente con más detalles
su - username
cd ~/public_html/git-files/proyecto
composer install -vvv
```

---

## Comparación con el Script de Setup

| Característica | setup_cd_project2.sh | git_pull_projects.sh |
|----------------|---------------------|---------------------|
| **Propósito** | Crear nuevos proyectos | Actualizar proyectos existentes |
| **Crea cuenta cPanel** | ✅ Sí | ❌ No |
| **Crea base de datos** | ✅ Sí | ❌ No |
| **Clona repositorio** | ✅ Sí | ❌ No |
| **Git pull** | ❌ No | ✅ Sí |
| **Actualiza dependencias** | ✅ Primera vez | ✅ Si hay cambios |
| **Migraciones** | ✅ Siempre | ✅ Si hay cambios |
| **Múltiples proyectos** | ❌ Uno a la vez | ✅ Sí |
| **Interactivo** | ✅ Solicita datos | ✅ Solo para conflictos |

---

## Notas Adicionales

### Estructura de Directorios
El script busca proyectos en:
```
/home/{usuario}/public_html/git-files/{proyecto}/.git
```

Esta estructura es creada automáticamente por `setup_cd_project2.sh`.

### Compatibilidad
- Compatible con servidores cPanel/WHM
- Funciona con proyectos Laravel
- Puede adaptarse para otros frameworks PHP

### Performance
- El escaneo de proyectos es rápido (< 1 segundo para ~10 proyectos)
- El tiempo de ejecución depende de:
  - Tamaño de los cambios en Git
  - Dependencias de Composer
  - Cantidad de migraciones pendientes

---