Architecture Decision Records - ADR260201f

2026/02/01

Bypass delle ignore rules come scelta deliberata

Autore: Marco Orlandin, Architect
Data: 01 Febbraio 2026
Status: Implementato
Progetto: git-side (open-source, sviluppato per Solexma LLC)
Constraint principali: I file side-tracked sono per definizione in .gitignore, nessuna modifica ai file di ignore del repo principale, comportamento prevedibile

Contesto e problema

I file che git-side traccia sono, nella stragrande maggioranza dei casi, esplicitamente ignorati dal repo principale. BACKLOG.md è in .gitignore. La cartella scratch/ è in .gitignore. Le config locali dell'IDE sono nel global gitignore.

Questo crea un paradosso operativo: git-side deve versionare file che Git è stato istruito a ignorare.

Le ignore rules di Git operano su più livelli:

  • .gitignore del progetto
  • .gitignore nelle sottodirectory
  • Global gitignore (core.excludesFile)
  • System-wide gitignore

Un git add normale rifiuta di aggiungere file che corrispondono a qualsiasi di queste regole. git-side deve bypassarle tutte.

Requisiti non funzionali

  • Aggiungere qualsiasi file al side repo, indipendentemente dalle ignore rules
  • Non modificare mai .gitignore o il global gitignore
  • Comportamento deterministico: nessun file rifiutato silenziosamente
  • Chiarezza semantica: l'utente deve capire perché il bypass è necessario

Opzioni valutate

Opzione 1: Modificare temporaneamente .gitignore

  • Pro: Il git add standard funzionerebbe senza flag speciali.
  • Contro: Modifica un file del repo principale (anche se temporaneamente). Rischio di commit accidentale della modifica. Race condition se l'utente lavora in parallelo. Viola il principio di zero inquinamento.

Opzione 2: Usare un gitignore custom per il side repo

  • Pro: Isolamento delle regole.
  • Contro: Il side repo con --work-tree nella directory del progetto eredita comunque le ignore rules del progetto. Non risolve il problema.

Opzione 3: Gestire un indice separato senza passare per git add

  • Pro: Controllo totale sul contenuto dell'indice.
  • Contro: Reimplementazione di logica che Git già gestisce. Complessità sproporzionata. Rischio di bug su edge case (symlink, permessi, encoding).

Opzione 4: git add -f (force)

  • Pro: Flag standard Git, documentato, stabile. Bypassa tutte le ignore rules in un colpo. Nessuna modifica ai file di ignore. Semantica chiara.
  • Contro: Nessuno significativo nel contesto di git-side. Il flag è pensato esattamente per questo caso d'uso.

Decisione

Scelto git add -f per tutte le operazioni di staging nel side repo.

Motivazioni principali:

  1. Semanticamente corretto: "ignorato dal repo principale" non significa "non versionabile". Sono due concetti distinti.
  2. Standard Git: -f è un flag documentato, stabile, nessun hack.
  3. Zero effetti collaterali: non modifica nessun file di ignore, non cambia il comportamento del repo principale.
  4. Universale: bypassa tutti i livelli di ignore (progetto, globale, sistema) in un colpo.

Implementazione passo-passo

  1. Add singolo: git add -f <path> per file e directory aggiunti esplicitamente con git side add.
  2. Auto sync, pass 1: git add -f -u per aggiornare file già tracciati (modifiche e cancellazioni).
  3. Auto sync, pass 2: git add -f <path> per ogni path in .side-tracked, per catturare nuovi file nelle directory tracciate.
  4. Due passaggi separati: La separazione tra update (-u) e add esplicito è necessaria perché -u non aggiunge nuovi file, e git add -f senza -u non gestisce le cancellazioni.

Conseguenze osservate

  • Nessun file è mai stato rifiutato dal side repo a causa di ignore rules.
  • Il two-pass staging (update + add) gestisce correttamente tutti i casi: file nuovi, modificati, cancellati, rinominati.
  • L'approccio "directory come container semantico" funziona bene: quando si traccia una directory, tutti i nuovi file al suo interno vengono catturati automaticamente.
  • Lezioni apprese:
    • La distinzione "ignorato dal repo principale" vs "non versionabile" è fondamentale. Confonderli è un errore di design.
    • git add -f non è un workaround, è lo strumento giusto per il lavoro giusto.
    • Il two-pass staging è un pattern che risolve elegantemente l'asimmetria tra -u (solo update) e add esplicito (solo nuovi file).

Stack utilizzato

  • Linguaggio: Rust (Edition 2024, MSRV 1.85)
  • Git: git add -f, git add -f -u

Quando considerare questo approccio

Se il tuo tool deve versionare file che sono deliberatamente esclusi dal tracking principale:

  • File in .gitignore che hanno comunque bisogno di storia
  • Config locali, metadata di progetto, file generati
  • Qualsiasi contesto in cui "ignorato" significa "non condiviso", non "non importante"

Il force add è la soluzione standard. Non servono hack o workaround.

Hai un caso simile? Contattami. Valutiamo insieme come gestire i file che cadono fuori dal perimetro del repo principale.

Torna indietro