CAF - Content Addressable Filesystem

A lightweight version control system similar to Git, written in Python and C++. CAF serves as an educational project for understanding how complex distributed version control systems work under the hood.

🌟 Project Overview

CAF (Content Addressable Filesystem) is a simplified version control system that implements core Git-like functionality including:

• Repository initialization and management
• File content hashing and storage
• Commit creation and tracking
• Branch management
• File system operations with content-addressable storage

The project demonstrates the fundamental concepts behind modern version control systems, including content-addressable storage, object models, and distributed workflows.

🏗️ Architecture

CAF is built as a hybrid Python/C++ system:

• Python Layer: Command-line interface, high-level repository operations, and user-facing functionality
• C++ Core: High-performance hashing, object storage, and low-level file operations
• Integration: Python bindings using pybind11 for seamless interoperability

Key Components

• caf/: Python CLI application and command implementations
• libcaf/: Core C++ library with Python bindings
• tests/: Comprehensive test suite for both Python and C++ components

🚀 Quick Start

Prerequisites

• Docker (recommended for consistent environment)
• Python 3.10+
• CMake 3.15+ and C++17 compiler

Using Docker (Recommended)

1. Build and run the development container:

   make run

2. Attach to the container:

   make attach

3. Deploy the project inside the container:

   make deploy

4. Run tests to verify setup:

   make test

   or

   pytest

💻 Usage

Basic Commands

Initialize a new repository:

caf init

Create a commit:

caf commit --author "Your Name" --message "Initial commit"

Hash a file and optionally store it:

caf hash_file path/to/file.txt --write

Manage branches:

caf add_branch feature-branch
caf delete_branch old-branch
caf branch                    # List all branches
caf branch_exists my-branch   # Check if a branch exists

View repository history and changes:

caf log                       # Show commit log
caf diff commit1 commit2      # Compare two commits

Repository management:

caf delete_repo              # Delete the repository

Get help:

caf --help
caf <command> --help

🧪 Testing

The project includes comprehensive tests for both Python and C++ components:

• Run all tests: make test
• Test with coverage: make test ENABLE_COVERAGE=1(C++ coverage available only if compiled with coverage)

📁 Project Structure

asp-caf-assignment/
├── Dockerfile                # Development environment setup
├── Makefile                  # Build and development commands
├── assignment/               # Assignment source
├── caf/                      # Python CLI application
│   ├── pyproject.toml        # Python package configuration
│   └── caf/                  # CLI source code
│       ├── __main__.py       # Entry point
│       ├── cli.py            # Command-line interface
│       └── cli_commands.py   # Command implementations
├── libcaf/                   # Core C++ library
│   ├── CMakeLists.txt        # CMake build configuration
│   ├── pyproject.toml        # Python package configuration
│   ├── libcaf/               # Python interface and higher-level repo operations
│   │   ├── constants.py      # Constants and configuration
│   │   ├── plumbing.py       # Low-level repo operations
│   │   ├── ref.py            # Reference handling
│   │   └── repository.py     # Repository management and high-level API
│   └── src/                  # C++ source code
│       ├── bind.cpp          # Python bindings
│       ├── blob.h            # Blob object definitions
│       ├── caf.cpp/h         # Low-level C++ implementation
│       ├── commit.h          # Commit object definitions
│       ├── hash_types.cpp/h  # Hashing implementations
│       ├── object_io.cpp/h   # Object I/O operations
│       ├── tree.h            # Tree object definitions
│       └── tree_record.h     # Tree record structures
└── tests/                    # Test suite
    ├── caf/                  # CLI tests
    └── libcaf/               # Core library tests

🔧 Development

Available Make Targets

• make build-container - Build Docker development image
• make run - Start development container
• make attach - Connect to running container
• make stop - Stop running container
• make deploy/deploy-libcaf/deploy-caf - Install libcaf and caf packages, or both
• make test - Run complete test suite (use ENABLE_COVERAGE=1 to collect coverage information)
• make clean - Remove build artifacts

Code Quality

The project follows Python and C++ best practices:

• Type hints in Python code
• Comprehensive test coverage
• Clear documentation and comments
• Consistent code formatting

🎓 Educational Context

This project is part of the Advanced Systems Programming course (ASP) and serves as a hands-on introduction to:

• Systems Programming: Working with multi-language codebases
• Version Control Internals: Understanding how Git-like systems work
• Software Architecture: Designing modular, maintainable systems
• Testing and Debugging: Ensuring code quality and reliability
• Build Systems: Managing complex build processes

Students work through various tasks including:

1. Code analysis and architecture mapping
2. Environment setup and testing
3. Debugging and fixing issues
4. Implementing new features (like tagging systems)

🤝 Contributors

Initial Development

• Meshi, Bar and Omer - Initial design and implementation (March 2025)
• Ido - Refactoring, cleanup, consistency and beauty pass (June 2025)
• You? - Your work here! (August 2025)

📚 Learning Resources

To better understand the concepts behind CAF, consider exploring:

Version Control & Systems Programming

• Git Internals - Understanding how Git stores and manages data
• Content-Addressable Storage - The fundamental concept behind Git and CAF
• The Architecture of Open Source Applications - Git - Deep dive into Git's design
• Git Internals - Plumbing and Porcelain (YouTube) - Video explanation of Git's internal structure
• How Git Works Under the Hood - FreeCodeCamp article on Git internals

Python Programming

• Python Tutorial - Official Python tutorial for beginners
• Real Python - Practical Python tutorials and guides
• Python C Extensions - How Python interfaces with C/C++
• Python Type Hints - Modern Python type annotations
• Python Tutorial for Beginners (YouTube) - 6-hour comprehensive Python course
• Python Type Hints Explained (YouTube) - ArjanCodes type hints tutorial
• Automate the Boring Stuff with Python - Free online book for practical Python

C++ Programming

• LearnCpp.com - Comprehensive C++ tutorial from basics to advanced
• C++ Reference - Complete C++ language and library reference
• Modern C++ Features - C++11/14/17/20 features guide
• C++ Tutorial for Beginners (YouTube) - 4-hour complete C++ course
• C++ Weekly (YouTube Channel) - Short weekly C++ tips and tricks
• Back to Basics: RAII and the Rule of Zero (YouTube) - CppCon talk on C++ best practices

Python-C++ Integration

• pybind11 Documentation - Seamless operability between C++11 and Python
• pybind11 Tutorial - Getting started with Python bindings
• Python and C++ Integration (YouTube) - Practical pybind11 tutorial

Core Computer Science Concepts

• Immutable Objects - Understanding immutability in programming
• Hash Functions - Cryptographic and non-cryptographic hashing
• Merkle Trees - Tree structures for data integrity (used in Git)
• Garbage Collection - Automatic memory management
• Hash Functions Explained (YouTube) - MIT OpenCourseWare on hash functions
• Immutable Data Structures (YouTube) - Understanding immutability benefits

Development Tools & Practices

• Docker Getting Started - Containerization fundamentals
• CMake Tutorial - Build system for C++ projects
• pytest Documentation - Python testing framework
• Git Workflow - Collaborative development with Git
• Docker Tutorial for Beginners (YouTube) - TechWorld with Nana Docker course
• CMake Tutorial (YouTube) - Complete CMake guide
• pytest Tutorial (YouTube) - Python testing with pytest
• Interactive Git Tutorial - Visual and interactive Git learning

Systems Programming

• The Linux Programming Interface - Comprehensive systems programming guide
• File Systems - How data is stored and organized
• Systems Programming Course - University of Illinois systems programming wiki

Advanced Topics

• Idempotent Operations - Operations that can be applied multiple times safely
• RAII (Resource Acquisition Is Initialization) - C++ resource management pattern
• Python Memory Management - How Python handles memory allocation
• Memory Management in Python (YouTube) - mCoding deep dive into Python memory
• How Git Works Internally (YouTube) - ByteByteGo Git internals explanation
• The Cherno C++ Series (YouTube) - Comprehensive modern C++ tutorial series
• System Design Concepts (YouTube Channel) - ByteByteGo channel for systems concepts
• Hussein Nasser (YouTube Channel) - Database and systems programming concepts

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

While developed for educational purposes as part of the Advanced Systems Programming course, the code is available under MIT License for learning and reference.

🐛 Issues and Support

If you encounter issues:

1. Check that Docker is running and up to date
2. Ensure all dependencies are properly installed
3. Run the test suite to identify specific problems
4. Consult the course staff for technical assistance

---

Built with ❤️ for learning systems programming and version control internals