# OCI2Git
[][documentation]
[](https://crates.io/crates/oci2git)
[](https://github.com/Virviil/oci2git/blob/master/LICENSE)
[](https://crates.io/crates/oci2git)
[//]: # (mock for future test.yaml)
[//]: # ([](https://github.com/Virviil/oci2git/actions))
A Rust application that converts container images (Docker, etc.) to Git repositories. Each container layer is represented as a Git commit, preserving the history and structure of the original image.
## Features
- Analyze Docker images and extract layer information
- Create a Git repository where each image layer is represented as a commit
- Support for empty layers (ENV, WORKDIR, etc.) as empty commits
- Complete metadata extraction to Markdown format
- Extensible architecture for supporting different container engines
## Use Cases
### Layer Diffing
When troubleshooting container issues, you can use Git's powerful diffing capabilities to identify exactly what changed between any two layers. By running `git diff` between commits, engineers can see precisely which files were added, modified, or deleted, making it much easier to understand the impact of each Dockerfile instruction and locate problematic changes.
### Origin Tracking
Using `git blame`, developers can quickly determine which layer introduced a specific file or line of code. This is particularly valuable when diagnosing issues with configuration files or dependencies. Instead of manually inspecting each layer, you can immediately trace the origin of any file back to its source layer and corresponding Dockerfile instruction.
### File Lifecycle Tracking
OCI2Git enables you to follow a specific file's journey throughout the container image's history. You can observe when a file was initially created, how it was modified across layers, and if/when it was eventually removed. This comprehensive view helps understand file evolution without having to manually track changes across potentially dozens of layers.
To track the history of a file in your container image — including when it first appeared, was changed, or deleted — you can use these Git commands after conversion:
```bash
# 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
```
These commands make it simple to trace any file's complete history across container layers without the complexity of manually extracting and comparing layer tarballs.
### Multi-Layer Analysis
Sometimes the most insightful comparisons come from examining changes across multiple non-consecutive layers. With OCI2Git, you can use Git's comparison tools to analyze how components evolved over multiple build stages, identifying patterns that might be invisible when looking only at adjacent layers.
### Layer Exploration
By using `git checkout` to move to any specific commit, you can examine the container filesystem exactly as it existed at that layer. This allows developers to inspect the precise state of files and directories at any point in the image's creation process, providing invaluable context when debugging or examining container behavior.
### Multi-Image Analysis
When working with multiple container images that share common ancestry, OCI2Git intelligently creates branches only when the images actually diverge. This allows you to analyze multiple related images in a single repository while preserving their common history.
```bash
# 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 automatically detects shared layers between images and creates a branching structure that reflects their common base. The Git history will show:
- A common trunk containing all shared layers
- Separate branches that diverge only when the images actually differ
- Clear visualization of where images share common ancestry vs. where they become unique
- Smart duplicate handling: if the exact same image is processed twice, the algorithm detects this before the final metadata commit and skips creating a duplicate branch
This approach is particularly valuable for:
- **Image Family Analysis**: Understanding how different variants of an image (different versions, architectures, or configurations) relate to each other
- **Base Image Impact**: Seeing exactly how changes to a base image affect multiple derived images
- **Optimization Opportunities**: Identifying shared components that could be better leveraged across image variants
### Additional Use Cases
- **Security Auditing**: Identify exactly when vulnerable packages or configurations were introduced and trace them back to specific build instructions.
- **Image Optimization**: Analyze layer structures to find redundant operations or large files that could be consolidated, helping to reduce image size.
- **Dependency Management**: Monitor when dependencies were added, upgraded, or removed across the image history.
- **Build Process Improvement**: Examine layer composition to optimize Dockerfile instructions for better caching and smaller image size.
- **Cross-Image Comparison**: Convert multiple related images to Git repositories and use Git's comparison tools to analyze their differences and commonalities.
## Installation
### From Source
```bash
# Clone the repository
git clone https://github.com/virviil/oci2git.git
cd oci2git
# Install locally
cargo install --path .
```
### From Crates.io
```bash
cargo install oci2git
```
## Usage
```bash
oci2git [OPTIONS]