Improve readme

Author: Mathis-L

CMakeLists.txt

@@ -1,6 +1,6 @@
 cmake_minimum_required(VERSION 3.13)
 
-project(codecrafters-git)
+project(recreate-git)
 
 set(CMAKE_CXX_STANDARD 23) # Enable the C++23 standard
 

README.md

@@ -1,59 +1,174 @@
-[![progress-banner](https://backend.codecrafters.io/progress/git/b764456b-a007-4b20-aeac-f24c9d0c8560)](https://app.codecrafters.io/users/codecrafters-bot?r=2qF)
+# mygit - A C++ Implementation of Core Git Commands
 
-This is a starting point for C++ solutions to the
-["Build Your Own Git" Challenge](https://codecrafters.io/challenges/git).
+**mygit** is a from-scratch implementation of several core Git commands in modern C++23. It was created as a portfolio project to gain a fundamental understanding of Git's internal object model, packfile protocol, and data structures. This project is inspired by the "Build Your Own X" initiative.
 
-In this challenge, you'll build a small Git implementation that's capable of
-initializing a repository, creating commits and cloning a public repository.
-Along the way we'll learn about the `.git` directory, Git objects (blobs,
-commits, trees etc.), Git's transfer protocols and more.
+## Core Workflow Demo
 
-**Note**: If you're viewing this repo on GitHub, head over to
-[codecrafters.io](https://codecrafters.io) to try the challenge.
+This demo shows how to build `mygit` and then use its plumbing commands to create a Git commit from scratch, demonstrating the core object model in action.
 
-# Passing the first stage
+#### Step 1: Build the `mygit` Executable
 
-The entry point for your Git implementation is in `src/main.cpp`. Study and
-uncomment the relevant code, and push your changes to pass the first stage:
+First, clone this repository and run the build script.
 
-```sh
-git commit -am "pass 1st stage" # any msg
-git push origin master
+```bash
+# Clone the repository (replace with your actual repo URL)
+$ git clone https://github.com/Mathis-L/recreate-git.git mygit
+$ cd mygit
+
+# Run the build script
+$ chmod +x build.sh
+$ ./build.sh
+--- Starting mygit build process ---
+Step 1: Configuring with CMake...
+-- The CXX compiler identification is GNU 11.4.0
+...
+Step 2: Building the executable...
+[ 50%] Built target mygit
+...
+[100%] Built target mygit
+
+✅ Build complete!
+   The executable is located at: ./build/mygit
+
+$ export PATH=$PWD/build:$PATH
+$ cd ..
+```
+
+#### Step 2: Create a Commit from Scratch
+
+Now that `mygit` is built, let's use it to create a new project.
+
+```bash
+# Create a new project directory and navigate into it
+$ mkdir my-test-project && cd my-test-project
+
+# Use the 'mygit' we just built to initialize a repository
+$ mygit init
+Initialized empty Git repository in /path/to/my-test-project/.git/
+
+# Create a file and add it to the object database as a "blob"
+$ echo "hello git" > hello.txt
+$ mygit hash-object -w hello.txt
+d90f1b40cf83b5d4313c4155abdaac3265b53026
+
+# Create a "tree" object that captures the state of the directory
+$ mygit write-tree
+7c7394336c9966133c945b63cf476902d28f0b9f
+
+# Create a "commit" object, linking the tree with a message
+$ mygit commit-tree 7c7394336c9966133c945b63cf476902d28f0b9f -m "Initial commit"
+1b2e67a423e8b0ed5d46924d567027582b12367d
+
+# Inspect the final commit object we just created
+$ /mygit cat-file -p 1b2e67a423e8b0ed5d46924d567027582b12367d
+tree 7c7394336c9966133c945b63cf476902d28f0b9f
+author Mathis-L <mathislafon@gmail.com> 1721245200 +0000
+committer Mathis-L <mathislafon@gmail.com> 1721245200 +0000
+
+Initial commit
 ```
 
-That's all!
+## Features & Implemented Commands
+
+This project implements the plumbing and porcelain commands necessary to support a basic `clone` and `inspect` workflow.
+
+*   `init`: Initializes an empty `.git` directory structure.
+*   `cat-file`: Inspects a Git object from the database (`-p` pretty-print option is supported).
+*   `hash-object`: Computes an object ID and optionally creates a blob from a file (`-w` write option is supported).
+*   `ls-tree`: Lists the contents of a tree object (`--name-only` is supported).
+*   `write-tree`: Creates a tree object from the current directory state.
+*   `commit-tree`: Creates a new commit object from a tree, parent, and message.
+*   `clone`: Fetches a complete repository from a remote server over the Smart HTTP protocol.
+
+## Project Foundations: Understanding Git's Internals
+
+To understand how `mygit` works, it is essential to first understand Git's elegant and powerful design. The following document provides a detailed overview of the core concepts that this project implements, from the `.git` directory structure to the fundamental object model.
+
+*   **[📄 Deep Dive: Git's Internal Structure and Object Model](./docs/git_internals.md)**
 
-# Stage 2 & beyond
+## Technical Deep Dive: The Clone Process
 
-Note: This section is for stages 2 and beyond.
+The most complex command implemented is `clone`, which involves a multi-stage conversation with a remote server using Git's Smart HTTP Protocol.
 
-1. Ensure you have `cmake` installed locally
-1. Run `./your_program.sh` to run your Git implementation, which is implemented
-   in `src/main.cpp`.
-1. Commit your changes and run `git push origin master` to submit your solution
-   to CodeCrafters. Test output will be streamed to your terminal.
+For a detailed, step-by-step breakdown of how `mygit` handles reference discovery, packfile negotiation, and delta resolution, please see the **[Git Clone Deep Dive Document](./docs/CLONE_DEEP_DIVE.md)**.
 
-# Testing locally
 
-The `your_program.sh` script is expected to operate on the `.git` folder inside
-the current working directory. If you're running this inside the root of this
-repository, you might end up accidentally damaging your repository's `.git`
-folder.
+## Current Limitations
 
-We suggest executing `your_program.sh` in a different folder when testing
-locally. For example:
+As a learning project, this implementation focuses on the "happy path" and has several limitations compared to the real Git:
+*   `clone` only supports the HTTP/HTTPS protocols. SSH is not supported.
+*   `clone` performs a full, shallow clone and does not support complex history negotiation (i.e., it has no `have` lines).
+*   Plumbing commands like `commit-tree` use hardcoded author information.
+*   There is no concept of an index/staging area (`git add`). `write-tree` works directly from the file system.
 
-```sh
-mkdir -p /tmp/testing && cd /tmp/testing
-/path/to/your/repo/your_program.sh init
+
+## Getting Started
+
+### Prerequisites
+
+You will need a C++23 compatible compiler and the following dependencies:
+*   `build-essential` (for `g++`, `make`, etc.)
+*   `cmake` (version 3.13+)
+*   `libssl-dev` (for SHA-1 hashing)
+*   `zlib1g-dev` (for object compression)
+*   `cpr` (for HTTP requests, installed by the build workflow)
+
+On Debian/Ubuntu, you can install them with:
+```bash
+sudo apt-get update
+sudo apt-get install -y build-essential cmake libssl-dev zlib1g-dev
+```
+
+And for cpr you will have to do : 
+```bash
+# 1. Clone the cpr repository
+git clone https://github.com/libcpr/cpr.git
+cd cpr
+
+# 2. Configure, build, and install the library system-wide
+mkdir build && cd build
+cmake .. -DCPR_USE_SYSTEM_CURL=ON
+cmake --build .
+sudo cmake --install .
+
+# 3. Go back to your original directory
+cd ../..
+```
+
+### Building the Project
+
+A convenience script is provided to build the project.
+
+```bash
+# Make the build script executable
+chmod +x build.sh
+
+# Run the script to configure and build
+./build.sh
 ```
 
-To make this easier to type out, you could add a
-[shell alias](https://shapeshed.com/unix-alias/):
+The final executable will be located at `./build/mygit`.
+
+### Running Tests
 
-```sh
-alias mygit=/path/to/your/repo/your_program.sh
+The project includes a suite of integration tests written as shell scripts. To run them:
+```bash
+# Navigate to the tests directory
+cd tests
 
-mkdir -p /tmp/testing && cd /tmp/testing
-mygit init
+# Make the test scripts executable
+chmod +x *.sh
+
+# Run the main test runner
+./run_all_tests.sh
 ```
+A successful run will end with the message: `✅ All tests passed.`
+
+## Future Work
+
+This project provides a solid foundation. Future work could include implementing more of Git's core features:
+*   **Index Management:** `add`, `rm`
+*   **Status & Diffs:** `status`, `diff`
+*   **Branching & Merging:** `branch`, `checkout`, `merge`
+*   **Protocol Enhancements:** Support for the v2 protocol, SSH.
+

build.sh

@@ -0,0 +1,21 @@
+#!/bin/sh
+# Exit early if any commands fail
+set -e
+
+echo "--- Starting mygit build process ---"
+
+# Ensure all steps are run from within the repository's root directory
+cd "$(dirname "$0")"
+
+# 1. Configure the project with CMake
+echo "Step 1: Configuring with CMake..."
+cmake -B build -S .
+
+# 2. Build the project using the generated build files
+echo "Step 2: Building the executable..."
+cmake --build ./build
+
+echo ""
+echo "✅ Build complete!"
+echo "   The executable is located at: ./build/mygit"
+echo "   You can now run commands, for example: ./build/mygit --help"