How meso1007/tagoly works
1. Project shape
Tagoly is a single-binary Go CLI for Git commit authoring and validation. There is no server component: the runtime boundary is the local terminal, the local Git repository, and the user’s filesystem.
2. CLI entrypoint and command routing
cmd/tagoly/main.go is the top-level entrypoint. The other files under cmd/tagoly/ split the executable into subcommands: interactive commit flow, linting, search, tag dictionary browsing, and hook installation. This is the main surface an architecture diagram should start from.
3. Interactive commit creation flow
The core “write a commit” path is: staged files are inspected, candidate scopes are derived, the user is prompted for type/scope/subject, and a final commit message is assembled in type(scope): subject form. The prompt layer is interactive and terminal-driven, while the generation logic lives in internal packages.
4. Scope detection and message synthesis
internal/generator/scope.go is responsible for turning staged file paths into likely commit scopes. This is one of the main differentiators of the tool: it reduces manual input by deriving scope suggestions from repository structure, then feeds those suggestions into the prompt flow.
5. Git repository boundary
internal/git/git.go is the abstraction layer for talking to Git itself. It is the bridge to repository state and history, likely wrapping operations such as reading staged changes, inspecting commit logs, and invoking commit-related Git commands. All higher-level features depend on this package rather than calling Git directly.
6. Commit message parsing and validation
internal/parser/parser.go and internal/lint/lint.go form the validation boundary. Parser logic understands Tagoly’s commit format, and linting checks that a message or commit range conforms to the expected convention. This validation is reused by the CLI and by the Git hook.
7. Hook installation and enforcement
internal/hook/hook.go manages installation of a commit-msg hook into .git/hooks/. The hook’s job is enforcement: it runs Tagoly lint against the commit message file before the commit is accepted. This keeps policy local to the repository without requiring a central service.
8. Search and tag dictionary features
internal/search/search.go supports querying commit history by type, scope, subject, and limits. cmd/tagoly/tagdict.go exposes the “tag dictionary” experience, which is an interactive way to browse commit types or scopes. These features are read-only over existing Git history, unlike the commit flow.
9. Custom configuration boundary
internal/config/config.go loads custom commit tags from .tagolycustom in the repository root, with a fallback to ~/.tagolycustom. This is the only explicit configuration input shown in the repo and it influences the tag/type choices available in prompts and validation.
10. Operational and distribution layer
The repo is packaged and released as a Go CLI using goreleaser (.goreleaser.yaml) and GitHub Actions (.github/workflows/release.yml). Shell scripts like build.sh, install.sh, and test_syntax.sh support local build/test/release workflows, but they do not change the runtime architecture.
11. Primary data flow to diagram
The main runtime flow is: user input + staged Git state + optional .tagolycustom config → scope/type suggestion and prompt → commit message generation → Git commit or lint/hook validation. Search and tagdict branch off from the same Git history and parsing layers but do not write to the repository.
12. Important architectural boundaries
The key boundaries are: terminal/UI vs. core logic, core logic vs. Git repository access, validation vs. enforcement via hook, and repository-local config vs. user-home fallback config. There are no external APIs or databases involved in normal operation.
Main entry points: main.go tagoly · search.go History search · lint.go Lint · git.go Git bridge
Components 15
CLI surface
Executable entrypoints and subcommands exposed to the terminal.
- tagoly · Top-level command router for the binary.
cmd/tagoly/main.go - Lint · CLI path for validating commit messages or ranges.
cmd/tagoly/lint.go - Search · CLI path for querying commit history.
cmd/tagoly/search.go - Tag dict · Interactive browsing of commit tags and scopes.
cmd/tagoly/tagdict.go - Hook · CLI path for hook installation.
cmd/tagoly/hook.go - History search · Queries commit history by type, scope, subject, and limits.
internal/search/search.go
Core flow
Interactive commit authoring and scope suggestion.
Git boundary
Repository-state access and history reads.
- Git bridge · Wraps repository state, staged files, and history access.
internal/git/git.go
Validation
Parsing, linting, and hook enforcement of commit policy.
Configuration
Repository-local and user-home tag configuration.
- Config · Loads custom tags from repository or home-directory config.
internal/config/config.go
Delivery
Release and packaging automation.
- Release yaml · GoReleaser packaging and release definition.
.goreleaser.yaml - Release workflow · GitHub Actions release automation.
.github/workflows/release.yml
Connections 20
- tagoly → Lint: routes to · Top-level CLI dispatches lint command.
- tagoly → Search: routes to · Top-level CLI dispatches search command.
- tagoly → Tag dict: routes to · Top-level CLI dispatches tag dictionary browsing.
- tagoly → Hook: routes to · Top-level CLI dispatches hook installation.
- tagoly → Prompt: drives · Interactive commit flow starts from the CLI surface.
- Prompt → Scope gen: asks for scopes · Prompt layer consumes derived scope suggestions.
- Scope gen → Git bridge: reads staged files · Scope inference is based on repository state.
- Prompt → Config: loads tags · Custom tags influence prompt choices.
- Lint → Lint: invokes · Lint subcommand delegates to validation engine.
- Search → History search: invokes · Search subcommand delegates to history query layer.
- Tag dict → History search: shares history · Tag dictionary browsing reuses history/search primitives.
- Hook → Hook: installs · Hook subcommand delegates to hook management.
- Lint → Parser: parses · Validation depends on commit message parsing.
- Lint → Git bridge: reads history · Lint can validate commits or ranges from Git.
- History search → Git bridge: reads history · Search queries repository commit history.
- History search → Parser: matches format · Search may filter by parsed commit structure.
- Hook → Lint: enforces · Commit-msg hook runs lint before accepting commits.
- Hook → Git bridge: installs into repo · Hook management targets the local .git directory.
- Parser → Config: uses tags · Parsing and validation are informed by custom tag definitions.
- Release yaml → Release workflow: drives · Release config is consumed by CI packaging workflow.