La idea es simple:

git commit
    ↓
git ftp push
    ↓
FTP/FTPS
    ↓
Hosting actualizado

git-ftp compara el último commit desplegado con el estado actual de Git y sube únicamente los cambios necesarios.

1. Instalación

Windows

Requiere Python 3.10+.

Comprobar Python:

python --version

Instalar:

python -m pip install --upgrade git-ftp

Verificar:

git ftp --version

macOS

Con Homebrew:

brew install git-ftp

Verificar:

git ftp --version

2. Configuración inicial

Ejecutar los comandos desde la raíz del proyecto Git.

URL FTP

Ejemplo:

git config --local git-ftp.url "ftpes://ftp.example.com:21/ruta/remota"

Para FTPS explícito normalmente se utiliza:

ftpes://

Puerto habitual:

21

Importante: ruta FTP

La ruta debe tener en cuenta el home/root del usuario FTP.

Por ejemplo, si el hosting indica:

Usuario: youruser
Home: /home/youruser

y el proyecto está físicamente en:

/home/youruser/accounts.example.com/accounts

la ruta que debe utilizarse desde la sesión FTP puede ser:

/accounts.example.com/accounts

y NO:

/home/youruser/accounts.example.com/accounts

El home del usuario FTP actúa como raíz de su sesión.

3. Configurar usuario

git config --local git-ftp.user "usuario_ftp"

Ejemplo:

git config --local git-ftp.user "youruser"

Configurar contraseña

git config --local git-ftp.password "CONTRASEÑA"

Esto se guarda en la configuración local de Git:

.git/config

No forma parte del repositorio Git.

4. FTPS y error de certificado

Si el servidor utiliza FTPS pero el certificado no coincide con el hostname utilizado, Windows puede mostrar un error como:

TLS verification failed
SEC_E_WRONG_PRINCIPAL

Si se confirma que el servidor es confiable y se necesita omitir la validación:

git config --local git-ftp.insecure true

Después ya no es necesario añadir:

--insecure

en cada comando.

También puede utilizarse temporalmente:

git ftp catchup --insecure

o:

git ftp push --insecure

Preferencia

Si el hosting proporciona un hostname cuyo certificado coincide correctamente, es preferible utilizar ese hostname y mantener la validación TLS.

--insecure debe utilizarse conscientemente porque desactiva la verificación del certificado.

5. .gitignore vs .git-ftp-ignore

Son archivos diferentes.

.gitignore

Controla qué archivos Git ignora.

.git-ftp-ignore

Controla qué archivos git-ftp excluye del deployment.

Ejemplo:

/vendor/
/node_modules/
.env
/cache/
 
keys/private.key
keys/public.key
 
package-lock.json
 
*.log
 
.DS_Store
 
/public/avatars/*
!/public/avatars/.gitkeep

Si un archivo ya está trackeado por Git, que aparezca posteriormente en .gitignore no hace que deje de estar trackeado.

Por eso hay que comprobar qué archivos realmente están bajo control de Git antes de asumir que .gitignore los excluirá del deployment.

6. Proyecto existente en el hosting

Si el proyecto ya está desplegado manualmente y el estado del hosting corresponde al commit actual:

NO utilizar:

git ftp init

porque init está pensado para iniciar el deployment.

Utilizar:

git ftp catchup

Esto registra el commit actual como el último deployment sin volver a subir todo el proyecto.

Ejemplo:

Hosting:
    versión actual
 
Git:
    commit 15ea909
 
git ftp catchup

Resultado:

Last deployment changed from  to 15ea909...

A partir de ese momento git-ftp conoce el punto desde el que debe calcular los cambios.

7. Ver qué archivos cambió el último commit

Para ver únicamente los archivos modificados por el último commit:

git diff --name-only HEAD~1 HEAD

Para ver también el tipo de cambio:

git diff --name-status HEAD~1 HEAD

Ejemplo:

M    src/Views/admin/audit/index.blade.php
A    src/Views/admin/audit/show.blade.php
D    src/Views/OldController.php

Donde:

M = Modified
A = Added
D = Deleted

8. Ver qué va a subir Git FTP

Antes de hacer un deployment real:

git ftp push --dry-run

Este comando no modifica el servidor.

Muestra los archivos que git-ftp considera necesarios sincronizar.

Ejemplo:

1 file to sync:
[1 of 1] Buffered for upload 'src/Views/admin/audit/index.blade.php'.

Es una excelente práctica utilizarlo antes de un deployment importante.

9. Deployment

Después de realizar cambios:

git add .
git commit -m "feat: nueva funcionalidad"

Comprobar primero:

git ftp push --dry-run

Si todo es correcto:

git ftp push

Ejemplo:

1 file to sync:
[1 of 1] Buffered for upload 'src/Views/admin/audit/index.blade.php'.
Uploading ...
Last deployment changed from ... to ...

10. ¿Qué ocurre si hay varios commits?

git-ftp no sube los commits individualmente.

Por ejemplo:

Último deployment
      ↓
commit A
      ↓
commit B
      ↓
commit C
      ↓
commit D ← HEAD

Al ejecutar:

git ftp push

Git-FTP calcula los cambios acumulados y sincroniza el servidor con el estado final de HEAD.

Por lo tanto, no importa si hiciste:

1 commit

o:

10 commits

entre deployments.

El objetivo es que producción termine exactamente en el estado correspondiente al commit actual.

11. Archivos eliminados

Si un archivo que estaba desplegado deja de existir en Git, git-ftp también puede detectar la eliminación y eliminarlo del servidor durante la sincronización.

Por eso es importante revisar:

git ftp push --dry-run

antes de deployments importantes.

12. Configuración actual

Para consultar la configuración FTP del proyecto:

git config --local --list | grep git-ftp

En PowerShell:

git config --local --list | Select-String "git-ftp"

También puedes consultar valores individualmente:

git config --local --get git-ftp.url
git config --local --get git-ftp.user
git config --local --get git-ftp.insecure

13. Flujo diario recomendado

Una vez configurado todo, el flujo normal es simplemente:

git add .
git commit -m "feat: descripción del cambio"
 
git ftp push --dry-run
git ftp push

O, cuando el cambio es trivial y ya estás completamente seguro:

git add .
git commit -m "fix: corregir validación"
 
git ftp push

14. Configuración de ejemplo

git config --local git-ftp.url "ftpes://ftp.example.com:21/app"
git config --local git-ftp.user "usuario"
git config --local git-ftp.password "contraseña"
git config --local git-ftp.insecure true

Después, si el servidor ya contiene exactamente la versión actual:

git ftp catchup

Y posteriormente:

git ftp push --dry-run
git ftp push

Resumen

Regla de oro

Si el hosting ya tiene el proyecto:

git ftp catchup

Si ya está configurado:

git ftp push --dry-run
git ftp push

Y nunca ejecutar git ftp init sobre un proyecto que ya está correctamente desplegado, salvo que se tenga claro que se quiere inicializar un nuevo deployment.