shahensaifullah/gitflow-cli

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.