# wfxr/forgit architecture

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

- Interactive diagram: https://gitdiagram.com/wfxr/forgit
- Repository: https://github.com/wfxr/forgit

## Overview

##### Project type and purpose
- This is a **lightweight CLI utility** for enhancing interactive Git usage in Unix‐like shells. It is not a client/server or web app, but rather a **shell plugin + wrapper script** that leverages `fzf` and Git to provide interactive selectors and viewers.
- The README confirms key points: it installs as a shell plugin (Bash, Zsh, Fish), provides a `git-forgit` executable in `bin/`, and integrates with `fzf` and Git to implement commands like `ga`, `glo`, `gd`, etc.

##### File structure
- Top‐level directories and scripts
- `bin/git-forgit` – the main CLI entrypoint (shell script with subcommands).
- `completions/` – shell‐completion scripts for Bash, Zsh, Fish.
- `conf.d/` – installation snippets for plugin managers (Homebrew, Fish, etc.).
- `forgit.plugin.sh`, `forgit.plugin.zsh` – shell plugin definitions for Bash/Zsh.
- `forgit.plugin.zsh`, `forgit.plugin.fish`, etc. – fish/Zsh plugin loader.
- Config and CI metadata under `.github/`, linting under `.pre-commit-config.yaml`, and standard licensing/ignore files.
- No backend/frontend split: the architecture revolves around **injection into the shell environment** and **invoking the wrapper script**.

##### README for additional insights
- **Dependencies**: requires `fzf ≥0.49.0` and Git. Optional helpers: `delta`/`diff-so-fancy`, `bat`, `tree`, `emoji-cli`.
- **Plugin integration**: can be loaded by various shell/plugin managers or sourced manually.
- **Environment variables** control behavior (FZF options, Git options, pager, aliases).
- **Commands** are implemented as either shell functions (e.g. `ga`) or subcommands of `git-forgit`.

a. Main components
- User Shell (Bash/Zsh/Fish)
- Shell Plugin Layer (forgit.plugin.* + aliases/functions)
- CLI Wrapper (`bin/git-forgit`)
- Core External Dependencies:
– `fzf` (interactive finder)
– `git` (version control)
- Optional Enhancers (bat, delta, emoji-cli, tree)
- Shell Completions (completion scripts loaded into shell)
- Configuration (environment variables, `conf.d/` snippets)
b. Relationships / interactions
1. **Shell startup**: user’s `.bashrc`/`.zshrc` sources `forgit.plugin.*` or plugin manager loads `conf.d/` scripts.
2. **Aliases & functions**: definitions like `ga`, `glo`, `gcf` invoke either `forgit::add` shell functions or delegate to `git forgit add`.
3. **Execution**: shell function calls `git-forgit` (via direct `bin/git-forgit` path or `git forgit` subcommand).
4. **Wrapper**: `git-forgit` parses subcommand, sets up preview/pager options, invokes `fzf` with configured flags.
5. **fzf**: displays an interactive list (e.g. changed files, branches, commits). User selects; `git-forgit` receives selection.
6. **Git commands**: `git-forgit` runs the appropriate `git` command (e.g. `git add`, `git checkout`) with the chosen arguments.
7. **Optional tools**: if installed and enabled via env vars, `bat`/`delta` provide richer diff or syntax‐highlighted previews; `tree` supplies directory previews.
c. Architectural patterns
- **Plugin architecture**: the tool injects into the shell as a set of functions/aliases + completion scripts.
- **Adapter/Facade**: `git-forgit` wraps `git` and `fzf`, exposing a simplified, interactive interface.
- **Configuration via environment**: clear separation of concerns—defaults in script, overrides through env variables.
d. Technologies / frameworks
- Shell scripting (Bash, Zsh, Fish)
- `fzf` (Go‐based fuzzy finder)
- `git` (C‐based VCS)
- Optional: `bat`, `delta`, `emoji-cli`, `tree`

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Environment"
        Shell["User Shell\n(Bash, Zsh, Fish)"]:::shell
        Env["Environment Variables"]:::config
    end

    Shell -->|"loads"| Loader["Plugin Loader\n(conf.d/)"]:::scripts
    click Loader "https://github.com/wfxr/forgit/tree/main/conf.d/"

    subgraph "Plugin Loader Components"
        Loader --> Shim["Shim Binary\n(conf.d/bin/git-forgit)"]:::binary
        click Shim "https://github.com/wfxr/forgit/tree/main/conf.d/bin/git-forgit"
        Loader --> PluginBash["forgit.plugin.sh"]:::scripts
        click PluginBash "https://github.com/wfxr/forgit/blob/main/forgit.plugin.sh"
        Loader --> PluginZsh["forgit.plugin.zsh"]:::scripts
        click PluginZsh "https://github.com/wfxr/forgit/blob/main/forgit.plugin.zsh"
        Loader --> PluginFish["forgit.plugin.fish"]:::scripts
        click PluginFish "https://github.com/wfxr/forgit/blob/main/conf.d/forgit.plugin.fish"
        Loader --> CompletionsDir["Shell Completions\n(completions/)"]:::scripts
        click CompletionsDir "https://github.com/wfxr/forgit/tree/main/completions/"

        CompletionsDir --> CompletionGeneric["_git-forgit"]:::scripts
        click CompletionGeneric "https://github.com/wfxr/forgit/tree/main/completions/_git-forgit"
        CompletionsDir --> CompletionBash["git-forgit.bash"]:::scripts
        click CompletionBash "https://github.com/wfxr/forgit/blob/main/completions/git-forgit.bash"
        CompletionsDir --> CompletionFish["git-forgit.fish"]:::scripts
        click CompletionFish "https://github.com/wfxr/forgit/blob/main/completions/git-forgit.fish"
    end

    Env --> PluginBash
    Env --> PluginZsh
    Env --> PluginFish
    Env --> Loader

    subgraph "Shell Plugin Layer"
        PluginBash -->|defines| Aliases["Aliases/Functions\n(ga, glo, etc)"]:::scripts
        PluginZsh -->|defines| Aliases
        PluginFish -->|defines| Aliases
    end

    Aliases -->|"invoke"| Wrapper["CLI Wrapper Script\n(bin/git-forgit)"]:::binary
    click Wrapper "https://github.com/wfxr/forgit/tree/main/bin/git-forgit"
    Env --> Wrapper

    subgraph "Core External Dependencies"
        FZF["fzf"]:::external
        GIT["git"]:::external
        Optional["Optional Tools\n(bat, delta, tree, emoji-cli)"]:::external
    end

    Wrapper -->|launches| FZF
    FZF -->|selects| Wrapper
    Wrapper -->|executes| GIT
    Wrapper -->|uses if available| Optional

    classDef shell fill:#ccffcc,stroke:#006600
    classDef scripts fill:#cce5ff,stroke:#004080
    classDef binary fill:#ffe5b4,stroke:#994d00
    classDef external fill:#ffd9cc,stroke:#cc3300
    classDef config fill:#e0e0e0,stroke:#a0a0a0
```
