Un'applicazione Rust che converte immagini di container (Docker, ecc.) in repository Git e genera una bill of materials del filesystem (fsbom) in YAML. Ogni layer del container è rappresentato come un commit Git, preservando la cronologia e la struttura dell'immagine originale.

Funzionalità

• Analizza immagini Docker ed estrae informazioni sui layer
• Crea un repository Git dove ogni layer dell'immagine è rappresentato come un commit
• Genera una bill of materials del filesystem (fsbom) in YAML con elenco dei file per layer
• Supporta layer vuoti (ENV, WORKDIR, ecc.) come commit vuoti
• Estrazione completa dei metadati in formato Markdown
• Architettura estensibile per supportare diversi motori di container

Casi d'Uso

Differenziazione dei Layer

Durante la risoluzione di problemi con i container, puoi utilizzare le potenti capacità di diff di Git per identificare esattamente cosa è cambiato tra due layer. Eseguendo git diff tra i commit, gli ingegneri possono vedere precisamente quali file sono stati aggiunti, modificati o eliminati, rendendo molto più facile comprendere l'impatto di ogni istruzione Dockerfile e individuare cambiamenti problematici.

Tracciamento dell'Origine

Utilizzando git blame, gli sviluppatori possono determinare rapidamente quale layer ha introdotto uno specifico file o linea di codice. Questo è particolarmente utile quando si diagnosticano problemi con file di configurazione o dipendenze. Invece di ispezionare manualmente ogni layer, puoi immediatamente risalire all'origine di qualsiasi file fino al layer sorgente e alla corrispondente istruzione Dockerfile.

Tracciamento del Ciclo di Vita dei File

OCI2Git consente di seguire l'evoluzione di un file specifico nella cronologia dell'immagine del container. Puoi vedere quando un file è stato creato, come è stato modificato tra i layer e se/quando è stato eventualmente rimosso. Questa visione completa aiuta a comprendere l'evoluzione dei file senza dover tracciare manualmente le modifiche tra decine di layer.

Per tracciare la cronologia di un file nella tua immagine container — inclusi quando è apparso, è stato modificato o eliminato — puoi usare questi comandi Git dopo la conversione:

# Full history of a file (including renames)
git log --follow -- /rootfs/my/file/path
First appearance (i.e. creation) - see which layer introduced the file
git log --diff-filter=A -- /rootfs/my/file/path
All changes made to the file (with diffs)
git log -p --follow -- /rootfs/my/file/path
When the file was deleted
git log --diff-filter=D -- /rootfs/my/file/path
Show short commit info (concise layer history)
git log --follow --oneline -- /rootfs/my/file/path

Questi comandi rendono semplice tracciare la storia completa di qualsiasi file attraverso i livelli del container, senza la complessità di estrarre e confrontare manualmente i tarball dei livelli.

Analisi Multi-Livello

Talvolta i confronti più significativi emergono esaminando le modifiche tra più livelli non consecutivi. Con OCI2Git, puoi utilizzare gli strumenti di confronto di Git per analizzare come i componenti si sono evoluti durante più fasi di build, identificando schemi che potrebbero essere invisibili osservando solo i livelli adiacenti.

Esplorazione dei Livelli

Utilizzando git checkout per spostarti su uno specifico commit, puoi esaminare il filesystem del container esattamente come esisteva in quel livello. Questo permette agli sviluppatori di ispezionare lo stato preciso di file e directory in qualsiasi momento del processo di creazione dell'immagine, fornendo un contesto prezioso durante il debug o l’analisi del comportamento del container.

Analisi Multi-Immagine

Quando si lavora con più immagini container che condividono una discendenza comune, OCI2Git crea intelligentemente dei branch solo quando le immagini effettivamente divergono. Questo ti permette di analizzare più immagini correlate in un unico repository, preservando la loro storia comune.

# Convert first image to create the base repository
oci2git postgres:16.9-alpine3.21 -o alp
Convert second image to the same output folder
oci2git nginx:1.28.0-alpine-slim -o alp

OCI2Git rileva automaticamente i layer condivisi tra le immagini e crea una struttura a ramificazione che riflette la loro base comune. La cronologia Git mostrerà:

• Un tronco comune che contiene tutti i layer condivisi
• Ramificazioni separate che divergono solo quando le immagini effettivamente differiscono
• Visualizzazione chiara di dove le immagini condividono una discendenza comune rispetto a dove diventano uniche
• Gestione intelligente dei duplicati: se la stessa immagine viene elaborata due volte, l’algoritmo lo rileva prima del commit finale dei metadati e evita di creare un ramo duplicato

Questo approccio è particolarmente utile per:

• Analisi di Famiglie di Immagini: Comprendere come diverse varianti di un’immagine (diverse versioni, architetture o configurazioni) siano correlate tra loro
• Impatto dell’Immagine Base: Vedere esattamente come le modifiche a un’immagine base influenzino più immagini derivate
• Opportunità di Ottimizzazione: Identificare componenti condivisi che potrebbero essere meglio sfruttati tra le varianti di immagine

Casi d’Uso Aggiuntivi

• Audit di Sicurezza: Identificare esattamente quando pacchetti o configurazioni vulnerabili sono stati introdotti e risalire a specifiche istruzioni di build.
• Ottimizzazione delle Immagini: Analizzare le strutture dei layer per individuare operazioni ridondanti o file di grandi dimensioni che potrebbero essere consolidati, aiutando a ridurre la dimensione dell’immagine.
• Gestione delle Dipendenze: Monitorare quando le dipendenze sono state aggiunte, aggiornate o rimosse nella cronologia dell’immagine.
• Miglioramento del Processo di Build: Esaminare la composizione dei layer per ottimizzare le istruzioni del Dockerfile per un caching migliore e una dimensione dell’immagine più piccola.
• Confronto tra Immagini: Convertire più immagini correlate in repository Git e utilizzare gli strumenti di confronto di Git per analizzare le loro differenze e somiglianze.

Installazione

Gestori di Pacchetti

#### macOS / Linux (Homebrew)

brew tap virviil/oci2git
brew install oci2git

#### Debian / Ubuntu

Scarica e installa il pacchetto .deb dalla versione più recente:

# For amd64 (x86_64)
wget https://github.com/virviil/oci2git/releases/latest/download/oci2git_VERSION_amd64.deb
sudo dpkg -i oci2git_VERSION_amd64.deb
For arm64
wget https://github.com/virviil/oci2git/releases/latest/download/oci2git_VERSION_arm64.deb
sudo dpkg -i oci2git_VERSION_arm64.deb

#### Arch Linux (AUR)

# Using yay
yay -S oci2git-bin
Using paru
paru -S oci2git-bin
Manual installation
git clone https://aur.archlinux.org/oci2git-bin.git
cd oci2git-bin
makepkg -si

Binari precompilati

Scarica il file binario appropriato per la tua piattaforma dalla ultima release:

# Linux x86_64
wget https://github.com/virviil/oci2git/releases/latest/download/oci2git-linux-x86_64.tar.gz
tar xzf oci2git-linux-x86_64.tar.gz
sudo mv oci2git-linux-x86_64 /usr/local/bin/oci2git
chmod +x /usr/local/bin/oci2git
macOS (Apple Silicon)
wget https://github.com/virviil/oci2git/releases/latest/download/oci2git-darwin-aarch64.tar.gz
tar xzf oci2git-darwin-aarch64.tar.gz
sudo mv oci2git-darwin-aarch64 /usr/local/bin/oci2git
chmod +x /usr/local/bin/oci2git

Da Crates.io

cargo install oci2git

Dalla fonte

# Clone the repository
git clone https://github.com/virviil/oci2git.git
cd oci2git
Install locally
cargo install --path .

Utilizzo

oci2git [OPTIONS] 
oci2git convert [OPTIONS] 
oci2git fsbom [OPTIONS] 

convert — immagine OCI → repository Git

oci2git convert [OPTIONS] 
or simply:
oci2git 

Opzioni: -o, --output

Directory di output per il repository Git [predefinito: ./container_repo] -e, --engine Motore container da utilizzare (docker, nerdctl, tar) [predefinito: docker] -v, --verbose Modalità verbosa (-v per info, -vv per debug, -vvv per trace)

fsbom — Distinta materiali del filesystem

oci2git fsbom [OPTIONS] 

Opzioni: -o, --output

Percorso di output per il file BOM YAML [predefinito: ./fsbom.yml] -e, --engine Motore di container da utilizzare (docker, nerdctl, tar) [predefinito: docker] -v, --verbose Modalità verbosa (-v per info, -vv per debug, -vvv per trace)

Variabili d'Ambiente: TMPDIR Imposta questa variabile d'ambiente per cambiare la posizione predefinita utilizzata per l'elaborazione dati intermedia. Questo dipende dalla piattaforma (ad es. TMPDIR su Unix/macOS, TEMP o TMP su Windows).

Esempi

Converti

Utilizzando il motore Docker (predefinito):

oci2git ubuntu:latest
or explicitly:
oci2git convert ubuntu:latest -o ./ubuntu-repo

Utilizzo di un tarball di immagini già scaricato:

oci2git convert -e tar -o ./ubuntu-repo /path/to/ubuntu-latest.tar

Il motore tar si aspetta un tarball in formato OCI valido, che viene tipicamente creato con docker save:

# Create a tarball from a local Docker image
docker save -o ubuntu-latest.tar ubuntu:latest
Convert the tarball to a Git repository
oci2git convert -e tar -o ./ubuntu-repo ubuntu-latest.tar

Questo creerà un repository Git in ./ubuntu-repo contenente:

• Image.md - Metadati completi sull'immagine in formato Markdown
• rootfs/ - Il contenuto del filesystem dal container

La cronologia Git riflette la cronologia dei layer del container:

• Il primo commit contiene solo il file Image.md con tutti i metadati
• Ogni commit successivo rappresenta un layer dell'immagine originale
• I commit includono il comando Dockerfile come messaggio di commit

Distinta Materiali del Filesystem (fsbom)

Genera un file YAML che elenca ogni file introdotto o modificato per layer:

oci2git fsbom ubuntu:latest -o ubuntu.yml

Utilizzando un tarball:

oci2git fsbom -e tar image.tar -o image-bom.yml

L'output YAML elenca ogni layer con le sue voci etichettate per tipo (file, hardlink, symlink, directory) e stato (n:uid:gid per nuovo, m:uid:gid per modificato). I file eliminati (whiteout OCI) sono esclusi.

layers:
  
index: 0
    
command: "ADD rootfs.tar.gz / # buildkit"
    digest: "sha256:45f3ea58..."
    entries:
      
type: file
        
path: "bin/busybox"
        size: 919304
        mode: 493
        stat: "n:0:0"
      
type: hardlink
        
path: "bin/sh"
        target: "bin/busybox"
        stat: "n:0:0"
      
type: symlink
        
path: "lib64"
        target: "lib"
        stat: "n:0:0"
  
index: 1
    
command: "RUN apk add --no-cache curl"
    digest: "sha256:..."
    entries:
      
type: file
        
path: "usr/bin/curl"
        size: 204800
        mode: 493
        stat: "n:0:0"
      
type: file
        
path: "etc/apk/world"
        size: 32
        mode: 420
        stat: "m:0:0"

Struttura del Repository

repository/
├── .git/
├── Image.md     # Complete image metadata
└── rootfs/      # Filesystem content from the container

Requisiti

• Rust edizione 2021
• Docker CLI (per il supporto del motore Docker)
• Git

Licenza

MIT

[documentazione]: https://docs.rs/oci2git/

--- Tranlated By Open Ai Tx | Last indexed: 2026-04-02 ---