151 lines
5.3 KiB
Markdown
151 lines
5.3 KiB
Markdown
# gitploy
|
|
|
|
Outillage git minimal pour fluidifier un déploiement *rolling release* :
|
|
une branche de développement, des branches d'environnement, et deux
|
|
sous-commandes git **transactionnelles** et **sûres**.
|
|
|
|
```bash
|
|
git deploy <remote> <branche...> -m "message" # livrer le dev vers un ou plusieurs environnements
|
|
git hotfix <remote> <branche> -m "message" # corriger un environnement puis rapatrier dans le dev
|
|
```
|
|
|
|
## Modèle de branches
|
|
|
|
- Une **branche de dev** (par défaut `master`) : là où tu travailles et intègres.
|
|
- Des **branches de déploiement** (`prod`, `stage`, …) : une par environnement.
|
|
- Tout passe par un remote (ex. `gitea`) qui déclenche le déploiement serveur.
|
|
|
|
`git deploy` fait avancer une branche d'environnement au niveau du dev (merge).
|
|
`git hotfix` permet de corriger un environnement **sans changer de branche à la
|
|
main**, puis rapatrie automatiquement le correctif dans le dev.
|
|
|
|
## Installation
|
|
|
|
### Au niveau utilisateur (recommandé)
|
|
|
|
gitploy est un *outil* : on l'installe une fois, tous les dépôts en profitent.
|
|
|
|
```bash
|
|
# 1. cloner une fois dans un emplacement stable
|
|
git clone gitea-figureslibres.io:bachir/gitploy.git ~/.local/share/gitploy
|
|
|
|
# 2. exposer les sous-commandes (via un dossier du PATH, ex. ~/.local/bin)
|
|
ln -sf ~/.local/share/gitploy/git-deploy ~/.local/bin/git-deploy
|
|
ln -sf ~/.local/share/gitploy/git-hotfix ~/.local/bin/git-hotfix
|
|
|
|
# 3. complétion (une fois)
|
|
echo 'source "$HOME/.local/share/gitploy/deploy-completion.bash"' >> ~/.bash_completion
|
|
```
|
|
|
|
`git deploy` / `git hotfix` sont alors disponibles dans **tous** tes dépôts,
|
|
sans alias ni `setup`. Mise à jour globale : `git -C ~/.local/share/gitploy pull`.
|
|
|
|
### En submodule (pour figer une version par projet)
|
|
|
|
```bash
|
|
# dans le dépôt qui doit déployer
|
|
git submodule add https://figureslibres.io/gitea/bachir/gitploy.git gitploy
|
|
git submodule update --init
|
|
gitploy/setup # installe des alias git locaux (sans PATH)
|
|
```
|
|
|
|
`setup` installe des **alias git locaux** (`git deploy`, `git hotfix`) pointant
|
|
vers les scripts. git n'exécutant jamais une config versionnée tout seul (par
|
|
sécurité), cette étape est nécessaire à chaque clone — c'est le prix du submodule.
|
|
|
|
## Configuration
|
|
|
|
Stockée dans `git config` (aucun fichier `.env`) :
|
|
|
|
| Clé | Défaut | Rôle |
|
|
|-----|--------|------|
|
|
| `deploy.source` | `master` | Branche de développement |
|
|
| `deploy.push` | `false` | Autorise le push réel (sinon simulation locale) |
|
|
|
|
```bash
|
|
git config deploy.source master
|
|
git config deploy.push true # activer le push réel quand tu es prêt
|
|
```
|
|
|
|
Tant que `deploy.push` est `false`, **rien n'est poussé** : tu peux tout tester
|
|
en local, les scripts affichent le push qu'ils auraient fait.
|
|
|
|
## Utilisation
|
|
|
|
### Déployer le dev vers un environnement
|
|
|
|
```bash
|
|
# tu es sur master
|
|
git deploy gitea prod -m "ajout du bloc contact"
|
|
```
|
|
|
|
1. commit sur `master` (message obligatoire s'il y a des modifs) ;
|
|
2. merge `master` → `prod` ;
|
|
3. push de `prod` (dernière étape) ;
|
|
4. retour sur `master`.
|
|
|
|
> `git deploy` ne pousse **que les branches nommées**, jamais `master` implicitement.
|
|
> Ça évite qu'un bare repo serveur (dont le hook n'attend qu'une branche précise)
|
|
> rejette le push.
|
|
>
|
|
> Pour sauvegarder `master` sur un remote central, inclus-le explicitement dans la
|
|
> liste — il sera poussé tel quel (sans merge) :
|
|
>
|
|
> ```bash
|
|
> git deploy gitea master prod stage -m "message"
|
|
> ```
|
|
|
|
Plusieurs environnements en une commande (commit unique, merges enchaînés,
|
|
**push atomique de toutes les branches nommées à la fin** — tout ou rien) :
|
|
|
|
```bash
|
|
git deploy gitea prod stage -m "ajout du bloc contact"
|
|
```
|
|
|
|
### Corriger un environnement (hotfix)
|
|
|
|
```bash
|
|
# tu es sur master, tu écris le correctif (sans committer)
|
|
git hotfix gitea prod -m "fix: lien du menu"
|
|
```
|
|
|
|
1. met tes modifs de côté (stash) ;
|
|
2. bascule sur `prod`, applique et committe le correctif ;
|
|
3. rapatrie le correctif dans `master` en local (merge) ;
|
|
4. push de `prod` puis retour sur `master`.
|
|
|
|
Résultat : le correctif est sur `prod` (poussé) **et** dans ton `master` local,
|
|
sans embarquer les features non livrées de `master`. Comme `git deploy`, `git
|
|
hotfix` ne pousse **que** la branche d'env, pas `master` : ton `master` distant
|
|
se mettra à jour quand tu le pousseras explicitement.
|
|
|
|
## Sûreté
|
|
|
|
- **Confirmation** : un `git status` + le plan d'action, avec validation `[O/n]`.
|
|
- **Transactionnel** : toutes les mutations locales d'abord ; en cas d'échec
|
|
(conflit, etc.), l'arbre est **restauré à l'identique** (refs, branche
|
|
courante, modifs en cours) et **rien n'est poussé**.
|
|
- **Push en dernier**, **atomique** (`--atomic`, tout ou rien), **jamais forcé**,
|
|
précédé d'un `--dry-run`.
|
|
- **Garde-fous** : remote et branche existants, cible ≠ branche de dev, bonne
|
|
branche de départ, aucun merge/rebase en cours.
|
|
|
|
## Complétion (optionnelle)
|
|
|
|
Complète le remote puis la branche, lus en direct depuis le dépôt :
|
|
|
|
```bash
|
|
# dans ~/.bashrc
|
|
source /chemin/vers/gitploy/deploy-completion.bash
|
|
```
|
|
|
|
## Fichiers
|
|
|
|
| Fichier | Rôle |
|
|
|---------|------|
|
|
| `git-deploy` | Sous-commande `git deploy` |
|
|
| `git-hotfix` | Sous-commande `git hotfix` |
|
|
| `_deploy_lib.sh` | Helpers partagés (config, garde-fous, confirmation) |
|
|
| `deploy-completion.bash` | Complétion bash |
|
|
| `setup` | Installe les alias git (sans PATH) |
|