# jacebrowning/gitman architecture

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

- Interactive diagram: https://gitdiagram.com/jacebrowning/gitman
- Repository: https://github.com/jacebrowning/gitman

## Overview

##### Project type and purpose
- This is a language-agnostic, command-line dependency manager (“Gitman”) written in Python.
- It reads a YAML config file (gitman.yml/.gitman.yml), fetches and checks out Git repos, sets up links, runs post-install scripts, and records locked SHAs.

##### File structure
- bin/: CLI shim scripts (checksum, open, verchew) that invoke the internal gitman module.
- gitman/:
- __main__.py – module entry point
- cli.py – argument parsing, help text
- commands.py – implementations of commands (update, install, uninstall, list, init, etc.)
- models/ – data models (Config, Group, Source)
- git.py – wrapper around Git CLI calls
- shell.py – abstraction for running shell commands
- plugin.py & decorators.py – plugin framework and extension hooks
- common.py, settings.py – shared utilities and defaults
- docs/ & mkdocs.yml – documentation site source.
- tests/ & gitman/tests/ – unit tests for both CLI/API and internal modules.
- configuration files (.gitignore, pyproject.toml, Makefile, CI configs).

##### README for additional insights
- Describes major workflows: init, update, install, list, uninstall.
- Illustrates features: recursive working trees, links, locking SHAs, post-install scripts.

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User"]:::external
    subgraph "CLI Layer"
        Shim["CLI Shim\n(bin scripts)"]:::internal
        Main["__main__.py"]:::internal
        Cli["cli.py"]:::internal
    end
    subgraph "Command Dispatcher & Core Engine"
        Dispatcher["commands.py"]:::internal
        Common["common.py"]:::internal
        Settings["settings.py"]:::internal
    end
    subgraph "Configuration & Models"
        Config["config.py"]:::internal
        Source["source.py"]:::internal
        Group["group.py"]:::internal
    end
    subgraph "Integrations"
        Git["git.py"]:::internal
        Shell["shell.py"]:::internal
    end
    subgraph "Plugin System"
        Plugin["plugin.py"]:::plugin
        Decorators["decorators.py"]:::plugin
    end
    subgraph "External Dependencies"
        GitBin["Git Binary"]:::external
        FS["File System"]:::external
    end

    User -->|invoke| Shim
    Shim --> Main
    Main --> Cli
    Cli -->|parse args| Dispatcher
    Dispatcher -->|load config| Config
    Dispatcher -->|access model| Source
    Dispatcher -->|access model| Group
    Dispatcher -->|use utilities| Common
    Dispatcher -->|use settings| Settings
    Dispatcher -->|clone/fetch/checkout| Git
    Git -->|executes| GitBin
    Dispatcher -->|create links/run scripts| Shell
    Shell -->|operations| FS
    Dispatcher <-->|hook events| Plugin
    Plugin -->|defines hooks| Decorators

    click Shim "https://github.com/jacebrowning/gitman/tree/main/bin/"
    click Main "https://github.com/jacebrowning/gitman/blob/main/gitman/__main__.py"
    click Cli "https://github.com/jacebrowning/gitman/blob/main/gitman/cli.py"
    click Dispatcher "https://github.com/jacebrowning/gitman/blob/main/gitman/commands.py"
    click Common "https://github.com/jacebrowning/gitman/blob/main/gitman/common.py"
    click Settings "https://github.com/jacebrowning/gitman/blob/main/gitman/settings.py"
    click Config "https://github.com/jacebrowning/gitman/blob/main/gitman/models/config.py"
    click Source "https://github.com/jacebrowning/gitman/blob/main/gitman/models/source.py"
    click Group "https://github.com/jacebrowning/gitman/blob/main/gitman/models/group.py"
    click Git "https://github.com/jacebrowning/gitman/blob/main/gitman/git.py"
    click Shell "https://github.com/jacebrowning/gitman/blob/main/gitman/shell.py"
    click Plugin "https://github.com/jacebrowning/gitman/blob/main/gitman/plugin.py"
    click Decorators "https://github.com/jacebrowning/gitman/blob/main/gitman/decorators.py"

    classDef internal fill:#D0E6FF,stroke:#0366d6,color:#000
    classDef plugin fill:#FFD8B0,stroke:#d2691e,color:#000
    classDef external fill:#D0FFD8,stroke:#22863a,color:#000
```
