# shahensaifullah/gitflow-cli architecture

> Architecture diagram of the GitHub repository shahensaifullah/gitflow-cli, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shahensaifullah/gitflow-cli
- Repository: https://github.com/shahensaifullah/gitflow-cli

## Overview

1. **What this repository is**
   - `gitflow-cli` is a **Bash-based interactive CLI**, not a service or library.
   - Its architecture is centered around **terminal workflows** that wrap standard `git` operations with prompts, summaries, and safety checks.

2. **Deployment/install boundary**
   - `install.sh` is the packaging layer.
   - It copies the scripts into `~/.gitflow/`, creates a launcher symlink in `~/.local/bin/gitflow`, and updates the user’s shell PATH.
   - This means runtime code is **run from the user’s home directory**, while the repo itself is mainly a source bundle.

3. **Entry-point and command routing**
   - The README describes a thin top-level router script, and the tree includes `gpush.sh`, which likely serves that role or a main wrapper.
   - The launcher delegates to feature scripts in `lib/` based on flags like `--pull`, `--checkout`, `--clone`, `--continue`, `--log`, and `--help`.
   - So the system is organized as **command dispatcher + subcommand modules**.

4. **Shared utility layer**
   - `lib/colors.sh` provides shared terminal styling for all flows.
   - `lib/help.sh` and `lib/log.sh` are cross-cutting support modules rather than repo-operation flows.
   - This separation keeps UI formatting and documentation/history concerns out of the Git action scripts.

5. **Core push workflow**
   - `lib/push.sh` is the main orchestration path behind plain `gitflow`.
   - It gathers repo state, shows changed files and diff stats, lets the user stage selectively or all at once, prompts for a commit message, then asks for branch selection and final confirmation.
   - The data flow is: **working tree → staging → commit → branch choice → push → success summary**.

6. **Repository-state detection and bootstrap**
   - If the current folder is not a Git repo, the tool switches into a **bootstrap flow** instead of failing immediately.
   - `lib/init.sh` handles creating a new repo, setting the default branch, and attaching a remote.
   - `lib/clone.sh` handles cloning an existing repository from a Git URL.
   - This is a distinct boundary between **existing-repo operations** and **project setup**.

7. **Pull/sync workflow**
   - `lib/pull.sh` implements `gitflow --pull` and `gitflow --sync`.
   - It fetches remote state, computes ahead/behind counts, and then lets the user choose merge or rebase.
   - The module is intentionally educational and interactive, translating Git history operations into plain-English prompts.

8. **Conflict management boundary**
   - When pull/rebase/merge causes conflicts, the flow transitions into conflict resolution rather than trying to hide it.
   - `lib/continue.sh` completes the operation after the user manually edits files.
   - The conflict handler supports choosing remote changes, local changes, manual fixing, or aborting, which makes it a separate recovery subsystem.

9. **Branch switching and creation**
   - `lib/checkout.sh` handles branch switching and branch creation.
   - The README shows it supports listing branches, direct selection, and shortcut naming like feature/bugfix/hotfix/release prefixes.
   - This module is a branch-management layer, separate from push and pull logic.

10. **Logging and audit trail**
   - Push activity is persisted to `~/.gitflow_history`.
   - `lib/log.sh` reads that history back for `gitflow --log`.
   - So the tool has a small local audit subsystem, independent of Git itself.

11. **External dependencies and scope**
   - The runtime depends on **bash/zsh**, **git**, and a configured local Git environment.
   - It talks to **remote Git repositories** through standard Git operations, with GitHub examples in the README but support implied for any Git remote.
   - There is no backend service, database, or network API layer beyond Git remotes.

12. **How to draw it**
   - The diagram should show:
     - a user in the terminal,
     - the `gitflow` launcher,
     - a dispatcher layer,
     - feature modules in `lib/`,
     - the local repository as the main data source/sink,
     - the user’s home directory for install artifacts and history logs,
     - and the remote Git host as the external boundary.

Main entry points: [`lib/colors.sh`](https://github.com/shahensaifullah/gitflow-cli/blob/main/lib/colors.sh) (Colors), [`lib/push.sh`](https://github.com/shahensaifullah/gitflow-cli/blob/main/lib/push.sh) (Push Flow), [`lib/pull.sh`](https://github.com/shahensaifullah/gitflow-cli/blob/main/lib/pull.sh) (Pull Sync), [`lib/checkout.sh`](https://github.com/shahensaifullah/gitflow-cli/blob/main/lib/checkout.sh) (Checkout)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_terminal["Terminal"]
  node_user(("User<br/>operator"))
end

subgraph group_runtime["Runtime"]
  node_launcher["gitflow<br/>launcher<br/>[gpush.sh]"]
  node_dispatch["Dispatcher<br/>router"]
  node_push["Push Flow<br/>workflow<br/>[push.sh]"]
  node_pull["Pull Sync<br/>workflow<br/>[pull.sh]"]
  node_checkout["Checkout<br/>branching<br/>[checkout.sh]"]
  node_clone["Clone<br/>bootstrap<br/>[clone.sh]"]
  node_init["Init<br/>bootstrap<br/>[init.sh]"]
  node_continue["Continue<br/>recovery<br/>[continue.sh]"]
  node_help["Help<br/>docs<br/>[help.sh]"]
  node_log["Log<br/>history<br/>[log.sh]"]
  node_colors["Colors<br/>ui shared<br/>[colors.sh]"]
end

subgraph group_setup["Setup"]
  node_install["Install<br/>packaging<br/>[install.sh]"]
  node_home[("Home Dir<br/>local install")]
  node_history["History<br/>audit log"]
end

subgraph group_external["External"]
  node_repo[("Git Repo<br/>working tree")]
  node_remote[("Remote Git<br/>git remote")]
end

node_user -->|"run"| node_launcher
node_launcher -->|"route"| node_dispatch
node_dispatch -->|"default"| node_push
node_dispatch -->|"--pull/--sync"| node_pull
node_dispatch -->|"--checkout"| node_checkout
node_dispatch -->|"--clone"| node_clone
node_dispatch -->|"--init"| node_init
node_dispatch -->|"--continue"| node_continue
node_dispatch -->|"--help"| node_help
node_dispatch -->|"--log"| node_log
node_push -->|"read/write"| node_repo
node_push -->|"push"| node_remote
node_pull -->|"sync"| node_repo
node_pull -->|"fetch"| node_remote
node_checkout -->|"switch"| node_repo
node_clone -->|"clone"| node_remote
node_init -->|"create"| node_repo
node_continue -->|"resolve"| node_repo
node_log -->|"read"| node_history
node_install -->|"deploy"| node_home
node_install -->|"symlink"| node_launcher
node_push -->|"style"| node_colors
node_pull -->|"style"| node_colors
node_checkout -->|"style"| node_colors
node_help -->|"style"| node_colors
node_log -->|"style"| node_colors

click node_launcher "https://github.com/shahensaifullah/gitflow-cli/blob/main/gpush.sh"
click node_push "https://github.com/shahensaifullah/gitflow-cli/blob/main/lib/push.sh"
click node_pull "https://github.com/shahensaifullah/gitflow-cli/blob/main/lib/pull.sh"
click node_checkout "https://github.com/shahensaifullah/gitflow-cli/blob/main/lib/checkout.sh"
click node_clone "https://github.com/shahensaifullah/gitflow-cli/blob/main/lib/clone.sh"
click node_init "https://github.com/shahensaifullah/gitflow-cli/blob/main/lib/init.sh"
click node_continue "https://github.com/shahensaifullah/gitflow-cli/blob/main/lib/continue.sh"
click node_help "https://github.com/shahensaifullah/gitflow-cli/blob/main/lib/help.sh"
click node_log "https://github.com/shahensaifullah/gitflow-cli/blob/main/lib/log.sh"
click node_colors "https://github.com/shahensaifullah/gitflow-cli/blob/main/lib/colors.sh"
click node_install "https://github.com/shahensaifullah/gitflow-cli/blob/main/install.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_user toneBlue
class node_launcher,node_dispatch,node_push,node_pull,node_checkout,node_clone,node_init,node_continue,node_help,node_log,node_colors toneAmber
class node_install,node_home,node_history toneMint
class node_repo,node_remote toneRose
```

## Components

### Terminal

Interactive command entry and user prompts

- **User**: operator · Runs gitflow in an interactive shell

### Runtime

Launcher and lib modules that execute git workflows

- [gitflow](https://github.com/shahensaifullah/gitflow-cli/blob/main/gpush.sh): launcher · Top-level command entry script · `gpush.sh`
- **Dispatcher**: router · Routes flags to feature modules
- [Push Flow](https://github.com/shahensaifullah/gitflow-cli/blob/main/lib/push.sh): workflow · Main commit and push orchestration · `lib/push.sh`
- [Pull Sync](https://github.com/shahensaifullah/gitflow-cli/blob/main/lib/pull.sh): workflow · Fetch, compare, and choose merge or rebase · `lib/pull.sh`
- [Checkout](https://github.com/shahensaifullah/gitflow-cli/blob/main/lib/checkout.sh): branching · Switches branches and creates new ones · `lib/checkout.sh`
- [Clone](https://github.com/shahensaifullah/gitflow-cli/blob/main/lib/clone.sh): bootstrap · Clones an existing repository · `lib/clone.sh`
- [Init](https://github.com/shahensaifullah/gitflow-cli/blob/main/lib/init.sh): bootstrap · Creates and prepares a new repository · `lib/init.sh`
- [Continue](https://github.com/shahensaifullah/gitflow-cli/blob/main/lib/continue.sh): recovery · Completes interrupted merge or rebase flows · `lib/continue.sh`
- [Help](https://github.com/shahensaifullah/gitflow-cli/blob/main/lib/help.sh): docs · Shows command usage and guidance · `lib/help.sh`
- [Log](https://github.com/shahensaifullah/gitflow-cli/blob/main/lib/log.sh): history · Reads local push history · `lib/log.sh`
- [Colors](https://github.com/shahensaifullah/gitflow-cli/blob/main/lib/colors.sh): ui shared · Shared terminal styling helpers · `lib/colors.sh`

### Setup

Install-time packaging and user-home artifacts

- [Install](https://github.com/shahensaifullah/gitflow-cli/blob/main/install.sh): packaging · Copies scripts and sets up launcher access · `install.sh`
- **Home Dir**: local install · User home location for installed scripts and history
- **History**: audit log · Local push activity log in the home directory

### External

Local repository and remote git boundary

- **Git Repo**: working tree · Local repository state and files
- **Remote Git**: git remote · External Git hosting or server

## Connections

- User → gitflow: run · User invokes gitflow commands
- gitflow → Dispatcher: route · Launcher delegates flags to the dispatcher
- Dispatcher → Push Flow: default · Default path executes the main push workflow
- Dispatcher → Pull Sync: --pull/--sync · Sync operations go to pull workflow
- Dispatcher → Checkout: --checkout · Branch switching routes to checkout
- Dispatcher → Clone: --clone · Clone requests go to bootstrap clone flow
- Dispatcher → Init: --init · New repository setup routes to init
- Dispatcher → Continue: --continue · Interrupted operations route to continue
- Dispatcher → Help: --help · Help command shows usage guidance
- Dispatcher → Log: --log · History command reads local audit trail
- Push Flow → Git Repo: read/write · Push flow stages, commits, and pushes from the working tree
- Push Flow → Remote Git: push · Commits are sent to the remote Git host
- Pull Sync → Git Repo: sync · Pull flow compares and updates local repository state
- Pull Sync → Remote Git: fetch · Pull flow fetches remote refs and history
- Checkout → Git Repo: switch · Branch operations act on the local repository
- Clone → Remote Git: clone · Clone flow pulls a repository from the remote host
- Init → Git Repo: create · Init flow creates a new local repository
- Continue → Git Repo: resolve · Continue flow resumes after conflict resolution in the repo
- Log → History: read · Log flow reads the local history file
- Install → Home Dir: deploy · Installer places runtime files in the user home directory
- Install → gitflow: symlink · Installer creates launcher access for gitflow
- Push Flow → Colors: style · Push flow uses shared terminal formatting
- Pull Sync → Colors: style · Pull flow uses shared terminal formatting
- Checkout → Colors: style · Checkout flow uses shared terminal formatting
- Help → Colors: style · Help output uses shared terminal formatting
- Log → Colors: style · Log output uses shared terminal formatting