# fabiogen1966/git-samples architecture

> Architecture diagram of the GitHub repository fabiogen1966/git-samples, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fabiogen1966/git-samples
- Repository: https://github.com/fabiogen1966/git-samples

## Overview

##### Project Type and Purpose
- This repository is an open-source educational tool—a suite of Git exercises. Each top-level folder (e.g., basic-branching, basic-commits, basic-revert, etc.) is a self-contained hands-on lesson. Utility scripts in the utils folder orchestrate setup, test harnesses, and resource provisioning for all exercises.

##### File Structure Analysis
- Top-Level Directories
- Each exercise directory (bad-commit, basic-branching, …) contains:
– README.md — exercise instructions
– setup.sh / setup.ps1 — scripts to initialize the exercise repo
– (occasionally) an exercise subfolder with initial files
- utils — shared tooling for generating bare repositories, cloning, seeding resources, and running tests
– clone-remote-to-exercise.*
– make-bare-remote-repo.*
– make-exercise-repo.*
– make-setup.sh (discovers all exercises, invokes setup scripts)
– resources/merge-tst-files.sh — sample files used in merge exercises
– test/test_setup.sh — verifies each setup ran correctly
- No frontend/backend split: this is a CLI/script-based system.
- Core dependencies: POSIX shell (bash), PowerShell for Windows, Git CLI.

##### README Insights
- Top-level README is stub (“a”), no architecture description. We infer architecture from the file layout and patterns in utils and exercise folders.

a. Main Components
- User Environment (Windows or Unix shell)
- Git CLI
- Utils Module
– Setup Orchestrator (make-setup.sh / .ps1)
– Repo Generators (make-bare-remote-repo, make-exercise-repo)
– Resource Providers (utils/resources)
– Test Harness (utils/test)
- Exercise Repositories (one per lesson)
b. Relationships & Interactions
1. User invokes a top-level setup.sh / setup.ps1
2. The orchestrator script loops through each exercise folder:
– Calls make-bare-remote-repo → creates a bare Git repo in /tmp or exercise-specific path
– Calls make-exercise-repo → clones the bare repo, checks out branches, seeds initial commit files (from utils/resources or exercise/exercise)
3. The orchestrator invokes clone-remote-to-exercise to simulate “remote” and “local” remotes.
4. Once setup is complete, the test harness (utils/test/test_setup.sh) runs Git commands and validates the state matches expected exercise preconditions.
5. User now cd’s into an exercise folder and performs Git commands to solve the task.
c. Architectural Patterns & Design Principles
- Modularity: shared logic lives in utils, exercise-specific logic stays in each folder.
- Script orchestration: a single entrypoint (make-setup.sh) that discovers and initializes all exercises.
- Reproducibility: bare-repo pattern ensures clean, repeatable state.
d. Key Technologies
- Shell scripting (bash) & PowerShell
- Git CLI (init, clone, commit, branch, push/pull)
- POSIX utils (cp, rm)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    UserShell(("User Shell")):::user

    %% Utils Module
    subgraph "Utils Module"
        Orchestrator["Orchestrator\n(make-setup.sh/.ps1)"]:::script
        subgraph "Repo Generator"
            BRRS["make-bare-remote-repo.sh"]:::script
            BRRP["make-bare-remote-repo.ps1"]:::script
            MERS["make-exercise-repo.sh"]:::script
            MERP["make-exercise-repo.ps1"]:::script
        end
        subgraph "Clone-Remote Simulator"
            CRS["clone-remote-to-exercise.sh"]:::script
            CRP["clone-remote-to-exercise.ps1"]:::script
            MFR["make-fake-remote.sh"]:::script
        end
        subgraph "Resource Provider"
            RTP["merge-tst-files.sh"]:::script
            Cred["credentials.txt"]:::repo
            Greet["greeting.txt"]:::repo
        end
        subgraph "Test Harness"
            TestHarness["test_setup.sh"]:::script
        end
    end

    %% Git CLI
    GitCLI[(Git CLI)]:::git

    %% Exercise Repositories
    subgraph "Exercise Repositories" 
        direction TB
        BC["bad-commit/"]:::repo
        BB["basic-branching/"]:::repo
        BCP["basic-cherry-pick/"]:::repo
        BCL["basic-cleaning/"]:::repo
        BCm["basic-commits/"]:::repo
        BR["basic-revert/"]:::repo
        BST["basic-staging/"]:::repo
        BSS["basic-stashing/"]:::repo
    end

    %% Connections
    UserShell -->|"invokes setup.sh/ps1"| Orchestrator
    Orchestrator -->|"calls make-bare-remote-repo"| BRRS
    Orchestrator -->|"calls make-bare-remote-repo"| BRRP
    BRRS -->|"init bare repo"| GitCLI
    BRRP -->|"init bare repo"| GitCLI

    Orchestrator -->|"calls make-exercise-repo"| MERS
    Orchestrator -->|"calls make-exercise-repo"| MERP
    MERS -->|"git clone"| GitCLI
    MERP -->|"git clone"| GitCLI

    Orchestrator -->|"calls clone-remote-to-exercise"| CRS
    Orchestrator -->|"calls clone-remote-to-exercise"| CRP
    Orchestrator -->|"calls make-fake-remote"| MFR
    CRS -->|"simulate remote"| GitCLI
    CRP -->|"simulate remote"| GitCLI
    MFR -->|"create fake remote"| GitCLI

    Orchestrator -->|"provides resources"| RTP
    RTP -->|"seed files"| GitCLI
    RTP -->|"seed files"| BC
    RTP -->|"seed files"| BR

    Orchestrator -->|"invokes test harness"| TestHarness
    TestHarness -->|"runs git commands"| GitCLI
    TestHarness -->|"validates state"| BB
    TestHarness -->|"validates state"| BC
    TestHarness -->|"validates state"| BCP

    GitCLI -->|"operates on"| BC
    GitCLI -->|"operates on"| BB
    GitCLI -->|"operates on"| BCP
    GitCLI -->|"operates on"| BCL
    GitCLI -->|"operates on"| BCm
    GitCLI -->|"operates on"| BR
    GitCLI -->|"operates on"| BST
    GitCLI -->|"operates on"| BSS

    %% Click Events
    click Orchestrator "https://github.com/fabiogen1966/git-samples/blob/master/utils/make-setup.sh"
    click BRRS "https://github.com/fabiogen1966/git-samples/blob/master/utils/make-bare-remote-repo.sh"
    click BRRP "https://github.com/fabiogen1966/git-samples/blob/master/utils/make-bare-remote-repo.ps1"
    click MERS "https://github.com/fabiogen1966/git-samples/blob/master/utils/make-exercise-repo.sh"
    click MERP "https://github.com/fabiogen1966/git-samples/blob/master/utils/make-exercise-repo.ps1"
    click CRS "https://github.com/fabiogen1966/git-samples/blob/master/utils/clone-remote-to-exercise.sh"
    click CRP "https://github.com/fabiogen1966/git-samples/blob/master/utils/clone-remote-to-exercise.ps1"
    click MFR "https://github.com/fabiogen1966/git-samples/blob/master/utils/make-fake-remote.sh"
    click RTP "https://github.com/fabiogen1966/git-samples/blob/master/utils/resources/merge-tst-files.sh"
    click Cred "https://github.com/fabiogen1966/git-samples/blob/master/basic-revert/exercise/credentials.txt"
    click Greet "https://github.com/fabiogen1966/git-samples/blob/master/basic-revert/exercise/greeting.txt"
    click TestHarness "https://github.com/fabiogen1966/git-samples/blob/master/utils/test/test_setup.sh"
    click BC "https://github.com/fabiogen1966/git-samples/tree/master/bad-commit/"
    click BB "https://github.com/fabiogen1966/git-samples/tree/master/basic-branching/"
    click BCP "https://github.com/fabiogen1966/git-samples/tree/master/basic-cherry-pick/"
    click BCL "https://github.com/fabiogen1966/git-samples/tree/master/basic-cleaning/"
    click BCm "https://github.com/fabiogen1966/git-samples/tree/master/basic-commits/"
    click BR "https://github.com/fabiogen1966/git-samples/tree/master/basic-revert/"
    click BST "https://github.com/fabiogen1966/git-samples/tree/master/basic-staging/"
    click BSS "https://github.com/fabiogen1966/git-samples/tree/master/basic-stashing/"

    %% Styles
    classDef script fill:#cce5ff,stroke:#4d89f2,stroke-width:1px
    classDef git fill:#d4edda,stroke:#28a745,stroke-width:1px
    classDef repo fill:#fff3cd,stroke:#ffc107,stroke-width:1px
    classDef user fill:#d3d3d3,stroke:#6c757d,stroke-width:1px
```
