italiadatacenter/st2idc/README-clone-transform.md

# Clone and Transform Script

Script bash per clonare un repository GitLab usando API e token privato, con sostituzione automatica di stringhe nei file.

## Prerequisiti

- `bash` (4.0+)
- `git`
- `curl` (opzionale, per verificare l'accesso)
- Token privato GitLab con almeno scope `api` o `read_repository`

## Preparazione

### 1. Creare il file `transform.txt`

Crea un file `transform.txt` nella stessa directory dello script con il formato:

```txt
<old_string>=<new_string>
<old_string>=<new_string>
...
```

**Esempio di transform.txt:**

```txt
# Configurazioni di sviluppo verso produzione
DATABASE_HOST=localhost=DATABASE_HOST=prod.example.com
DATABASE_PORT=5432=DATABASE_PORT=5432
API_ENDPOINT=http://localhost:8080=API_ENDPOINT=https://api.prod.com
ENVIRONMENT=development=ENVIRONMENT=production
LOG_LEVEL=debug=LOG_LEVEL=info
SECRET_KEY=dev-secret=SECRET_KEY=prod-secret-key-xyz
```

### 2. Ottenere un token GitLab

1. Accedi a GitLab
2. Vai a **Profile → Access Tokens**
3. Crea un nuovo token con scopes:
   - `api` - accesso completo
   - oppure `read_repository` - solo lettura
4. Copia il token (non sarà più visibile dopo)

### 3. Rendere eseguibile lo script

```bash
chmod +x clone-and-transform.sh
```

## Utilizzo

### Sintassi base

```bash
./clone-and-transform.sh -u <URL> -t <TOKEN> -r <REPO-PATH> -d <DEST-DIR>
```

### Parametri

| Parametro | Breve | Descrizione | Esempio |
|-----------|-------|-------------|---------|
| `--url` | `-u` | URL base di GitLab | `https://gitlab.com` |
| `--token` | `-t` | Token di accesso privato | `glpat-xxxxx` |
| `--repo` | `-r` | Percorso del repository | `mygroup/myproject` |
| `--dest` | `-d` | Directory di destinazione | `./cloned-repo` |
| `--transform` | `-f` | Path del file transform.txt | `./transform.txt` (default) |
| `--help` | `-h` | Mostra l'aiuto | - |

### Esempi di utilizzo

**Esempio 1: Clone con trasformazioni usando file default**

```bash
./clone-and-transform.sh \
    -u https://gitlab.com \
    -t glpat-xxxxxxxxxxxx \
    -r mygroup/myproject \
    -d ./my-cloned-repo
```

**Esempio 2: Clone con file transform.txt personalizzato**

```bash
./clone-and-transform.sh \
    -u https://gitlab.internal.com \
    -t glpat-xxxxxxxxxxxx \
    -r company/backend \
    -d ./backend-clone \
    -f ./custom-transform.txt
```

**Esempio 3: Clone da GitLab Enterprise**

```bash
./clone-and-transform.sh \
    -u https://gitlab.mycompany.com \
    -t glpat-xxxxxxxxxxxx \
    -r products/idcidp \
    -d ./idcidp-prod
```

## Come funziona lo script

1. **Validazione**: Verifica i parametri e l'esistenza di `transform.txt`
2. **Clone**: Clona il repository usando autenticazione OAuth2
3. **Scoperta directory**: Identifica directory `kubernetes`, `containers`, `conf`
4. **Trasformazione**: Per ogni file trovato applica le sostituzioni definite in `transform.txt`
5. **Report**: Mostra il number di file modificati e suggerisce i prossimi passi

### Directory elaborate

Lo script elabora automaticamente questi percorsi:
- `kubernetes/`
- `containers/`
- `conf/`

Se una directory non esiste, viene saltata con un avvertimento.

### File binari

I file binari (immagini, archivi, ecc.) vengono automaticamente saltati per evitare corruzioni.

## Output esempio

```
[INFO] Starting GitLab repository clone and transformation...
[INFO] GitLab URL: https://gitlab.com
[INFO] Repository: mygroup/myproject
[INFO] Destination: ./my-cloned-repo
[INFO] Transform file: ./transform.txt
[INFO] Cloning repository...
[INFO] Repository cloned successfully
[INFO] Found directory: kubernetes
[INFO] Found directory: containers
[INFO] Applying transformations from ./transform.txt...
[INFO] Processing directory: kubernetes
[INFO]   Modified: ./my-cloned-repo/kubernetes/deployment.yaml
[INFO]   Modified: ./my-cloned-repo/kubernetes/service.yaml
[INFO] Processing directory: containers
[INFO] ========== TRANSFORMATION SUMMARY ==========
Total files processed: 12
Files modified: 5
[INFO] ==========================================
[INFO] Transformation completed successfully!

Next steps:
  1. Review changes: cd my-cloned-repo && git diff
  2. Commit changes: git add . && git commit -m 'Apply transformations'
  3. Push changes: git push
```

## Verifica delle modifiche

Dopo l'esecuzione, è consigliato verificare le modifiche:

```bash
cd ./my-cloned-repo
git diff
```

Per vedere solo i file modificati:

```bash
git status
```

## Commit e Push

Se le modifiche sono corrette:

```bash
git add .
git commit -m "Apply environment transformations"
git push
```

## Troubleshooting

### Errore: "Failed to clone repository"

**Causa**: Token non valido o senza permessi

**Soluzione**:
1. Verifica il token nel profilo GitLab
2. Assicurati che il token abbia scope `api`
3. Verifica che il repository sia accessibile con il token

### Errore: "Transform file not found"

**Causa**: Il file `transform.txt` non esiste

**Soluzione**:
1. Crea il file `transform.txt` nella directory dove esegui lo script
2. Usa l'opzione `-f` per specificare un percorso personalizzato

### Nessun file modificato

**Causa**: Le stringhe in `transform.txt` non corrispondono ai file

**Soluzione**:
1. Verifica il contenuto dei file nella directory clonata
2. Assicurati che le stringhe in `transform.txt` siano corrette
3. Usa pattern più generici se necessario

### Errore di escaping in stringhe complesse

Se le stringhe contengono caratteri speciali (barre, ampersand, etc.):

**Lo script gestisce automaticamente l'escaping**, ma se riscontri problemi:
1. Usa sequenze di escape nel file transform.txt
2. Ad esempio, per una barra inversa: `path\\old=path\\new`

## Sicurezza

### Best practices

1. **Non** commettere il token nel repository
2. Usa variabili d'ambiente per il token:
   ```bash
   ./clone-and-transform.sh \
       -u https://gitlab.com \
       -t $GITLAB_TOKEN \
       -r mygroup/myproject \
       -d ./clone
   ```

3. Usa file `.gitignore` per `transform.txt` se contiene dati sensibili:
   ```bash
   echo "transform.txt" >> .gitignore
   ```

4. Revoca il token dopo l'uso se è ad uso singolo

## Opzioni avanzate

### Usare con script di automazione

```bash
#!/bin/bash
export GITLAB_TOKEN="glpat-xxxxx"
export GITLAB_URL="https://gitlab.internal.com"

./clone-and-transform.sh \
    -u $GITLAB_URL \
    -t $GITLAB_TOKEN \
    -r company/backend \
    -d ./backend-clone
```

### Variazione per ambienti multipli

Crea diversi file di trasformazione:
- `transform-dev.txt`
- `transform-qa.txt`
- `transform-prod.txt`

```bash
# Per development
./clone-and-transform.sh \
    -u https://gitlab.com \
    -t $GITLAB_TOKEN \
    -r mygroup/myproject \
    -d ./clone-dev \
    -f transform-dev.txt

# Per production
./clone-and-transform.sh \
    -u https://gitlab.com \
    -t $GITLAB_TOKEN \
    -r mygroup/myproject \
    -d ./clone-prod \
    -f transform-prod.txt
```

## Changelog

### v1.0 (Initial Release)
- Clone repository con token privato
- Applicazione di trasformazioni su directory specifiche
- Supporto per file UTF-8
- Skip automatico file binari
- Output colorato e dettagliato

## Licenza

MIT