# svedrin/hgit architecture

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

- Interactive diagram: https://gitdiagram.com/svedrin/hgit
- Repository: https://github.com/svedrin/hgit

## Overview

##### Project type and purpose
- This is an open‑source, opinionated CLI tool (“hgit”) written as shell scripts that wrap Git commands and add GitHub‑aware behaviors.
- It provides a simplified “porcelain” interface to common Git workflows (clone, status, diff, commit, branch, push, PR, etc.), plus bash completion, a small config file, and a test harness.

##### File‑structure analysis
- Top‑level:
– .drone.yml: CI configuration for running tests on pushes
– README.md: full user guide and architecture notes
– hgit.sh: main shell script implementing all “h” subcommands
– hgit_completion.sh: bash completion definitions for the “h” command
– tests.sh: test runner script
- tests/ directory:
– tests/README.md: description of test cases
– individual .txt files: expected command outputs for regression testing

##### Key insights from README
- “hgit” is just a shell wrapper around git; it delegates to Git, manipulates remotes, opens browser for PRs.
- It reads a user config in ~/.hgitrc containing MY_GITHUB_USER.
- It uses standard git commands and GitHub conventions (forking workflow).

##### Main components
a. User / Developer CLI
– Terminal where user types “h <command>”
b. hgit.sh script
– Command dispatcher (case statement for subcommands)
– Business logic for each subcommand
– Reads ~/.hgitrc
c. Bash completion engine
– hgit_completion.sh loaded into shell
– Provides tab completion for subcommands and branch names
d. Underlying Git CLI
– git executable invoked by hgit.sh
– Local repository (./.git directory, working tree)
e. Remote GitHub service
– git@github.com or https://api.github.com for fetch/push
– Browser invocation for PR creation
f. CI/Test harness
– tests.sh runs sample commands, compares output against tests/*.txt
– .drone.yml invokes tests.sh on pipeline events

##### Relationships and interactions
- User → hgit.sh: enters commands; script parses and dispatches
- hgit.sh ↔ ~/.hgitrc: loads user GitHub username
- hgit.sh → git CLI → Local repo: runs git clone/status/diff/commit/branch/push
- hgit.sh → Remote GitHub: fetches forks, opens PR URLs in browser
- hgit_completion.sh ↔ shell: intercepts tab presses, queries hgit.sh for suggestions
- CI system (.drone.yml) → tests.sh → hgit.sh & tests/: validates behavior

##### Architectural patterns & design principles
- Single‑entry point script with subcommand dispatcher (similar to git’s plugin pattern)
- Separation of concerns:
– Dispatch layer (hgit.sh) vs. completion layer (hgit_completion.sh) vs. tests
- Convention over configuration: opinionated defaults for GitHub workflows
- Stateless operations: each “h” command runs and exits; state is in Git metadata
- Extensibility: adding a new subcommand is as simple as adding a new case branch in hgit.sh

## Diagram (Mermaid)

```mermaid
graph TD
    UserCLI["User CLI (Terminal)"]:::external

    subgraph "Shell Environment"
        HGit["hgit.sh"]:::local
        Completion["hgit_completion.sh"]:::local
        Config["~/.hgitrc"]:::config
        Docs["README.md"]:::local
    end

    subgraph "Git Subsystem"
        GitCLI["Git CLI"]:::git
        Repo["Local Repo (.git & Working Tree)"]:::git
    end

    Browser["Browser (opens PR URLs)"]:::external
    Github["GitHub Remote Service"]:::cloud

    subgraph "CI/Test Subsystem"
        Drone[".drone.yml"]:::ci
        TestsSh["tests.sh"]:::local
        TestsDir["tests/"]:::local
        READMEtests["tests/README.md"]:::local
        T1["hgit_basic_d_after_modify.txt"]:::local
        T2["hgit_basic_dc_after_add.txt"]:::local
        T3["hgit_basic_st_after_add.txt"]:::local
        T4["hgit_basic_st_after_modify.txt"]:::local
        T5["hgit_basic_st_before_add.txt"]:::local
    end

    UserCLI -->|"runs"| HGit
    UserCLI -.->|"tab press"| Completion
    Completion -->|"queries suggestions"| HGit
    HGit -->|"loads config"| Config
    HGit -->|"reads docs"| Docs
    HGit -->|"invokes"| GitCLI
    GitCLI -->|"operates on"| Repo
    GitCLI -->|"push/fetch"| Github
    HGit -->|"opens PR"| Browser

    Drone -->|"invokes tests"| TestsSh
    TestsSh -->|"runs commands via"| HGit
    TestsSh -->|"compares output with"| TestsDir
    TestsDir --> READMEtests
    TestsDir --> T1
    TestsDir --> T2
    TestsDir --> T3
    TestsDir --> T4
    TestsDir --> T5

    classDef local fill:#b3ffb3,stroke:#006600
    classDef config fill:#cce5ff,stroke:#004080
    classDef git fill:#ffddb3,stroke:#b36b00
    classDef cloud fill:#e5ccff,stroke:#8000b3
    classDef external fill:#f0f0f0,stroke:#666666
    classDef ci fill:#d9b3ff,stroke:#6600b3

    click HGit "https://github.com/svedrin/hgit/blob/master/hgit.sh"
    click Completion "https://github.com/svedrin/hgit/blob/master/hgit_completion.sh"
    click Drone "https://github.com/svedrin/hgit/blob/master/.drone.yml"
    click TestsSh "https://github.com/svedrin/hgit/blob/master/tests.sh"
    click TestsDir "https://github.com/svedrin/hgit/tree/master/tests/"
    click READMEtests "https://github.com/svedrin/hgit/blob/master/tests/README.md"
    click T1 "https://github.com/svedrin/hgit/blob/master/tests/hgit_basic_d_after_modify.txt"
    click T2 "https://github.com/svedrin/hgit/blob/master/tests/hgit_basic_dc_after_add.txt"
    click T3 "https://github.com/svedrin/hgit/blob/master/tests/hgit_basic_st_after_add.txt"
    click T4 "https://github.com/svedrin/hgit/blob/master/tests/hgit_basic_st_after_modify.txt"
    click T5 "https://github.com/svedrin/hgit/blob/master/tests/hgit_basic_st_before_add.txt"
    click Docs "https://github.com/svedrin/hgit/blob/master/README.md"
```
