# github/git-sizer architecture

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

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

## Overview

##### Project type and purpose
- This is an open-source, command-line tool (“git-sizer”) written in Go. Its sole purpose is to analyze a local Git repository, compute size-related metrics (commits, trees, blobs, refs, checkouts, etc.), and flag potential scaling problems.

##### File structure
- Top-level:
- git-sizer.go: entry point (package main)
- go.mod, go.sum: module definitions
- Makefile, scripts/: build, test, release
- .github/: CI workflows (lint, test, release)
- Core packages:
- git/: wrappers for invoking Git and iterating objects (commit, tree, blob, refs)
- counts/: generic counters and “human” formatters for simple metrics
- sizes/: complex size analyzers (footnotes, graphs, grouping)
- meter/: progress reporting / throughput metering
- internal/refopts/: logic for filtering refs, grouping options
- Tests are collocated in each package (e.g., counts_test.go, gitconfig_test.go).
- docs/: BUILDING, RELEASING guidelines.

##### README for additional insights
- Describes the workflow: invoke git-sizer CLI → runs underlying `git` commands → processes objects → outputs tabular or JSON metrics.

##### Detailed capture of essential elements
- Tests and docs as side-components feeding into CI.
- Do not overcrowd: keep each package/component distinct.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Frontend
    CLI["CLI Frontend"]:::core
    click CLI "https://github.com/github/git-sizer/blob/master/git-sizer.go"

    %% Git Invocation Layer
    subgraph "Git Invocation Layer"
        GitCore["git/git.go"]:::core
        click GitCore "https://github.com/github/git-sizer/blob/master/git/git.go"
        GitBin["git/git_bin.go"]:::core
        click GitBin "https://github.com/github/git-sizer/blob/master/git/git_bin.go"
        GitConfig["git/gitconfig.go"]:::core
        click GitConfig "https://github.com/github/git-sizer/blob/master/git/gitconfig.go"
    end

    %% Iterators & Filters
    subgraph "Iterators & Filters"
        subgraph "Object Iterators"
            ObjIter["obj_iter.go"]:::iter
            click ObjIter "https://github.com/github/git-sizer/blob/master/git/obj_iter.go"
            BatchIter["batch_obj_iter.go"]:::iter
            click BatchIter "https://github.com/github/git-sizer/blob/master/git/batch_obj_iter.go"
            HeadIter["obj_head_iter.go"]:::iter
            click HeadIter "https://github.com/github/git-sizer/blob/master/git/obj_head_iter.go"
            Resolver["obj_resolver.go"]:::iter
            click Resolver "https://github.com/github/git-sizer/blob/master/git/obj_resolver.go"
            Commit["commit.go"]:::iter
            click Commit "https://github.com/github/git-sizer/blob/master/git/commit.go"
            Tree["tree.go"]:::iter
            click Tree "https://github.com/github/git-sizer/blob/master/git/tree.go"
            Tag["tag.go"]:::iter
            click Tag "https://github.com/github/git-sizer/blob/master/git/tag.go"
            RefIter["ref_iter.go"]:::iter
            click RefIter "https://github.com/github/git-sizer/blob/master/git/ref_iter.go"
        end
        subgraph "Reference Filtering"
            RefFilter["ref_filter.go"]:::iter
            click RefFilter "https://github.com/github/git-sizer/blob/master/git/ref_filter.go"
            FilterVal["filter_value.go"]:::iter
            click FilterVal "https://github.com/github/git-sizer/blob/master/internal/refopts/filter_value.go"
            FilterGroupVal["filter_group_value.go"]:::iter
            click FilterGroupVal "https://github.com/github/git-sizer/blob/master/internal/refopts/filter_group_value.go"
            RefGroup["ref_group.go"]:::iter
            click RefGroup "https://github.com/github/git-sizer/blob/master/internal/refopts/ref_group.go"
            RefGroupBuilder["ref_group_builder.go"]:::iter
            click RefGroupBuilder "https://github.com/github/git-sizer/blob/master/internal/refopts/ref_group_builder.go"
            ShowGrouper["show_ref_grouper.go"]:::iter
            click ShowGrouper "https://github.com/github/git-sizer/blob/master/internal/refopts/show_ref_grouper.go"
        end
    end

    %% Metric Calculators
    subgraph "Metric Calculators"
        subgraph "Counts Module"
            Counts["counts.go"]:::calc
            click Counts "https://github.com/github/git-sizer/blob/master/counts/counts.go"
            HumanC["human.go"]:::calc
            click HumanC "https://github.com/github/git-sizer/blob/master/counts/human.go"
        end
        subgraph "Sizes Module"
            Sizes["sizes.go"]:::calc
            click Sizes "https://github.com/github/git-sizer/blob/master/sizes/sizes.go"
            Graph["graph.go"]:::calc
            click Graph "https://github.com/github/git-sizer/blob/master/sizes/graph.go"
            Footnotes["footnotes.go"]:::calc
            click Footnotes "https://github.com/github/git-sizer/blob/master/sizes/footnotes.go"
            Grouper["grouper.go"]:::calc
            click Grouper "https://github.com/github/git-sizer/blob/master/sizes/grouper.go"
            ExplicitRoot["explicit_root.go"]:::calc
            click ExplicitRoot "https://github.com/github/git-sizer/blob/master/sizes/explicit_root.go"
            PathResolver["path_resolver.go"]:::calc
            click PathResolver "https://github.com/github/git-sizer/blob/master/sizes/path_resolver.go"
        end
        Meter["meter.go"]:::calc
        click Meter "https://github.com/github/git-sizer/blob/master/meter/meter.go"
    end

    %% Output Formatter
    Output["Output Formatter (table/JSON)"]:::fmt
    click Output "https://github.com/github/git-sizer/blob/master/sizes/output.go"

    %% Utilities
    subgraph "Utilities"
        IsattyEn["isatty_enabled.go"]:::util
        click IsattyEn "https://github.com/github/git-sizer/blob/master/isatty/isatty_enabled.go"
        IsattyDis["isatty_disabled.go"]:::util
        click IsattyDis "https://github.com/github/git-sizer/blob/master/isatty/isatty_disabled.go"
        NegBool["negated_bool_value.go"]:::util
        click NegBool "https://github.com/github/git-sizer/blob/master/negated_bool_value.go"
    end

    %% Build & CI
    subgraph "Build & CI"
        subgraph "Scripts"
            BS["bootstrap"]:::ci
            click BS "https://github.com/github/git-sizer/tree/master/script/bootstrap"
            BD["build"]:::ci
            click BD "https://github.com/github/git-sizer/tree/master/script/build"
            CIBuild["cibuild"]:::ci
            click CIBuild "https://github.com/github/git-sizer/tree/master/script/cibuild"
            EnsureGo["ensure-go-installed.sh"]:::ci
            click EnsureGo "https://github.com/github/git-sizer/blob/master/script/ensure-go-installed.sh"
            GoScript["go"]:::ci
            click GoScript "https://github.com/github/git-sizer/tree/master/script/go"
            GoFmt["gofmt"]:::ci
            click GoFmt "https://github.com/github/git-sizer/tree/master/script/gofmt"
            InstallVendored["install-vendored-go"]:::ci
            click InstallVendored "https://github.com/github/git-sizer/tree/master/script/install-vendored-go"
        end
        subgraph "CI Workflows"
            LintCI["lint.yml"]:::ci
            click LintCI "https://github.com/github/git-sizer/blob/master/.github/workflows/lint.yml"
            TestCI["test.yml"]:::ci
            click TestCI "https://github.com/github/git-sizer/blob/master/.github/workflows/test.yml"
            ReleaseCI["release.yml"]:::ci
            click ReleaseCI "https://github.com/github/git-sizer/blob/master/.github/workflows/release.yml"
        end
    end

    %% Execution Terminal
    Terminal["Terminal (stdout)"]:::external

    %% Data Flow
    CLI -->|"invoke"| GitCore
    GitCore -->|"stream objects"| ObjIter
    ObjIter -->|"objects"| RefFilter
    RefFilter -->|"filtered refs"| Counts
    RefFilter -->|"filtered refs"| Sizes
    RefFilter -->|"filtered refs"| Meter
    Counts -->|"metrics"| Output
    Sizes -->|"metrics"| Output
    Meter -->|"metrics"| Output
    Output -->|"render"| Terminal
    IsattyEn -->|"detect tty"| Output
    IsattyDis -->|"detect tty"| Output

    %% Styles
    classDef core fill:#ADE8F4,stroke:#000,stroke-width:1px
    classDef iter fill:#B7E4C7,stroke:#000,stroke-width:1px
    classDef calc fill:#FFB703,stroke:#000,stroke-width:1px
    classDef fmt fill:#9D4EDD,stroke:#000,stroke-width:1px
    classDef util fill:#E0E0E0,stroke:#000,stroke-width:1px
    classDef ci fill:#CCCCCC,stroke:#000,stroke-width:1px
    classDef external fill:#F0EFEB,stroke:#000,stroke-width:1px
```
