TURING

gitfactory - documentazione

2 min read

gitfactory — Documentazione

Classe factory Node.js per versionamento di file di catalogo tramite git locale.

Panoramica

gitfactory(basepath) crea un gestore git per cataloghi. Ogni catalogo è una directory sotto basepath. I file vengono scritti temporaneamente in una cartella buffer (xgit/), committati, poi rimossi dal filesystem. Lo storico rimane in git. Supporta hide/restore di versioni tramite metadati in .git/mystate_git.json.

API

gitfactory(basepath)

Restituisce oggetto con i metodi sotto. basepath è il percorso radice dei cataloghi.

isgit (boolean)

true se git è installato e raggiungibile. Se false, tutti i metodi git sono no-op.

checkcatalog(c) → boolean

Verifica che il catalogo c esista e abbia un repo git inizializzato.

addcatalog(c) → boolean

Inizializza un nuovo catalogo git. Crea directory xgit/ e git init. Restituisce false se già esistente o git non disponibile.

delcatalog(c) → boolean

Cancella .git/ e xgit/ del catalogo. Non cancella la directory catalogo stessa.

addfile(c, file, content, user) → boolean

Aggiunge un file al versionamento. Salva il contenuto in xgit/<file>, committa con messaggio utente data, poi cancella il file fisico. Il nome file viene sanitizzato.

versions(c, file, all=false, limit=Infinity) → array

Restituisce versioni di un file. Formato: [{ id, date, msg, hidden }]. Per default esclude versioni nascoste. all=true le include.

getfile(c, file, id) → string

Recupera contenuto di una versione specifica per commit id. Restituisce stringa vuota se non trovato.

hideversion(c, id) → boolean

Nasconde versione (commit id) dalla lista normale. Salva in mystate_git.json.

restoreversion(c, id) → boolean

Rimuove flag hide da una versione.

old_versions(c, file) → array

Variante senza filtro hide (deprecata, usare versions).

Sanitizzazione nomi file

Regole: solo [a-zA-Z0-9-+_.], resto sostituito con _, lowercase, trim.

Attenzione: nomi diversi possono collidere (es. mio-file e mio_file → mio_file).

Limiti noti

  • addfile: typo nel template string del messaggio commit (backtick mancante)
  • getstatefiledata: readFileSync senza encoding — JSON.parse su Buffer funziona ma è fragile
  • versions e old_versions: logica duplicata, differiscono solo per --follow e filtro hide
  • Errori git ingoiati senza log
  • Stato hide in .git/ — delcatalog lo cancella insieme al repo
  • delcatalog non cancella la directory catalogo (consistente? da verificare)

Uso tipico

const { gitfactory } = require('./gitfactory');
const git = gitfactory('/var/data/cataloghi');
 
// Crea catalogo
await git.addcatalog('documenti');
 
// Aggiungi file
await git.addfile('documenti', 'contratto.pdf', buffer, 'agostino');
 
// Versioni
const storico = await git.versions('documenti', 'contratto.pdf');
 
// Recupera
const v1 = await git.getfile('documenti', 'contratto.pdf', storico[0].id);
 
// Nascondi
await git.hideversion('documenti', storico[0].id);

Dipendenze

  • Node.js fs, path, child_process.exec
  • Git installato nel sistema

Backlinks