# Git

# Credenziali Forgejo via HTTPS con `pass` su Arch Linux

Guida per autenticarsi a **Forgejo via HTTPS** (senza SSH) memorizzando le
credenziali in modo cifrato con `pass`, con integrazione automatica in git
tramite **pass-git-helper**.

> Esempio basato sull'host `forgejo.dominio.tdl`. Sostituisci dominio e nome
> utente con i tuoi.

## Prerequisiti

- Arch Linux
- Una chiave GPG (la creiamo se manca)
- Pacchetti: `pass`, un editor (`nano` o `vim`), `pass-git-helper` (AUR)

---

## 1. Genera un token in Forgejo

Non usare la password dell'account. In Forgejo:

`Impostazioni → Applicazioni → Genera nuovo token`

Assegna almeno lo scope di **lettura e scrittura sui repository**
(`read/write:repository`) — serve per il `push` — e copia subito il token
(viene mostrato una sola volta).

Vantaggi del token: è revocabile, ha permessi limitati e funziona anche con
la 2FA attiva.

---

## 2. Prepara GPG e pass

`pass` cifra le credenziali con GPG, quindi serve una chiave.

```bash
# Crea una chiave GPG solo se non ne hai già una
gpg --full-generate-key

# Installa pass e inizializzalo con la tua chiave
sudo pacman -S pass
pass init <ID-o-email-della-tua-chiave-GPG>
```

Per trovare l'ID di una chiave esistente: `gpg --list-secret-keys --keyid-format long`

---

## 3. Salva il token in pass

```bash
pass insert git/forgejo.dominio.tdl
```

Inserisci il **token** come password. Confermalo quando richiesto.

Per verificare il contenuto salvato:

```bash
pass git/forgejo.dominio.tdl
```

La prima riga deve contenere **solo** il token.

---

## 4. Installa pass-git-helper

È disponibile nell'AUR:

```bash
yay -S pass-git-helper
# in alternativa: pipx install pass-git-helper
```

---

## 5. Configura la mappatura host → voce di pass

Crea il file `~/.config/pass-git-helper/git-pass-mapping.ini`:

```ini
[forgejo.dominio.tdl]
target=git/forgejo.dominio.tdl
username=il-tuo-utente
```

> `username` deve essere il tuo **nome utente di login** Forgejo. Specificarlo
> qui evita ambiguità: l'autenticazione avviene con username + token come
> password.

---

## 6. Configura git per usare l'helper

```bash
git config --global credential.helper "$(which pass-git-helper)"
```

Verifica che non ci siano altri helper che interferiscono (es. `store`,
`cache`, libsecret), perché git userebbe il primo che risponde:

```bash
git config --show-origin --get-all credential.helper
```

Se ne trovi più di uno, lascia solo pass-git-helper:

```bash
git config --global --unset-all credential.helper
git config --global credential.helper "$(which pass-git-helper)"
```

---

## 7. Uso quotidiano

Clona e usa i repository via HTTPS normalmente:

```bash
git clone https://forgejo.dominio.tdl/utente/repo.git
cd repo
git pull
git push
```

Alla prima operazione GPG ti chiederà la passphrase (poi gestita da
`gpg-agent`). Nessuna password o token in chiaro sul disco.

---

## Risoluzione problemi

### `vi: comando non trovato` durante `pass edit`

`pass` usa l'editor in `$EDITOR` e, se non impostato, ripiega su `vi`.

Soluzione temporanea:

```bash
EDITOR=nano pass edit git/forgejo.dominio.tdl
```

Soluzione permanente — aggiungi in `~/.bashrc` (o `~/.zshrc`):

```bash
export EDITOR=nano
```

Poi `source ~/.bashrc`.

### `Autenticazione non riuscita` / credenziali rifiutate al push

Verifica cosa restituisce davvero l'helper:

```bash
printf 'protocol=https\nhost=forgejo.dominio.tdl\n\n' | pass-git-helper get
```

Deve stampare due righe:

```
password=<il-tuo-token>
username=<il-tuo-utente>
```

Controlli da fare:

1. **Manca `username=`** → aggiungi `username=` nel file `.ini` (punto 5).
2. **`password=` vuoto o errato** → la voce pass è sbagliata, risalvala
   (`pass insert --multiline git/forgejo.dominio.tdl`, token sulla prima riga,
   poi `Ctrl+D`).
3. **Helper multipli** → vedi punto 6, lascia solo pass-git-helper.
4. **Token scaduto o senza permessi di scrittura** → rigeneralo in Forgejo con
   lo scope corretto e risalvalo.
5. **Credenziali vecchie in cache:**

```bash
git credential-cache exit 2>/dev/null
rm -f ~/.git-credentials 2>/dev/null
```

Test rapido della credenziale senza fare push:

```bash
git ls-remote https://forgejo.dominio.tdl/utente/repo.git
```