Readable git history, at a glance.
Created by Himeshchanchal Bhattarai Inspired by HTTP status semantics.
STATUS is a commit convention that encodes the reliability and state of a change. It turns your git log into a real-time health dashboard. Instead of guessing if a commit is safe to pull, the code tells you exactly how much to trust it.
301 [Success] status(301): add export endpoint
409 [Warning] status(409): works but fragile, needs review
500 [Failure] status(500): runtime crash on auth middleware
601 [Fixed] status(601): fix null pointer in auth
"Honesty over perfection."
Traditional commit messages tell you what changed. STATUS tells you how it feels.
- Instant Scanning: Spot stable vs. risky changes in milliseconds.
- Risk Transparency: No more "hidden" bugs in a "feat:" commit.
- Team Trust:
409or500signals to teammates: "Don't base your work on this yet." - It reduces bikeshedding by limiting the code to a small, consistent set.
- It makes risk explicit (e.g.,
409for risky,500for broken) so teams don't ship surprises.
Example:
status(301): add export endpoint
status(409): works but risky, needs extra testing
- Install the npm CLI globally (published)
npm install -g status-commit
- Install hooks into your repo (no manual templates needed)
status-commit install --ci --templates
- Commit as usual
git commit -m "status(301): add export endpoint" - Inspect risk + drift (optional)
status-commit scan --limit 200 status-commit report --limit 50 status-commit dashboard --limit 200
Tip: run git commit (without -m) to see the inline STATUS prompt in your editor (prepare hook stays optional).
Below is a short, looping GIF showing the 60-second install and a guided commit.
Recorded with v1.3.0 (2026-02-27) using status-commit install --ci --templates.
With the npm CLI installed, drop into any repo and run:
status-commit installThis writes a commit-msg hook that enforces status(###): ... (codes unchanged).
Useful in CI or before committing:
status-commit commit "status(301): add export endpoint"An extension source is included in vscode-extension/. It provides:
- Autocomplete for
status(###):in commit message editors. - A command:
STATUS Commit: Insert Code(Quick Pick).
cd vscode-extension
npm i -g @vscode/vsce
vsce package
code --install-extension status-commit-0.0.1.vsixOpen the vscode-extension folder in VS Code and press F5.
status(###): short summary
Special case:
status(infinity): short summary
Accepted prefixes: STATUS, Status, status (recommended: status).
Required separator between code and summary: :.
Printable version: Printable Cheat Sheet (PNG)
Top codes:
| Code | When to use |
|---|---|
| STATUS(301) | New feature that works |
| STATUS(601) | Bug fix |
| STATUS(302) | Improvement to existing feature |
| STATUS(201) | Stable change |
| STATUS(300) | Refactor only |
| STATUS(102) | Work in progress |
- Use 1xx when the work is incomplete or experimental.
- Use 103 when the work is blocked or waiting on a dependency.
- Use 104 for research or spike work.
- Use 2xx when the change is working and safe.
- Use 3xx when you improved or refactored something.
- Use 5xx when something is broken or failing.
- Use 6xx when you fixed a failure.
- Use 203 for documentation-only changes.
- Use 409 when it works but is risky or fragile.
- Use 404 for human chaos or debugging madness.
| Category | Code | Meaning |
|---|---|---|
| Initialization | STATUS(001) | Initial commit / project start |
| Initialization | STATUS(002) | Base structure established |
| Initialization | STATUS(003) | Create / delete folder or file |
| Configuration | STATUS(050) | Tooling/Environment config (ESLint, Prettier, etc.) |
| Configuration | STATUS(051) | CI/CD pipeline changes (GitHub Actions, Jenkins) |
| Configuration | STATUS(052) | Dependency added |
| Configuration | STATUS(053) | Dependency removed/updated |
| In Progress | STATUS(101) | Draft or scaffolding added |
| In Progress | STATUS(102) | Partial implementation |
| In Progress | STATUS(103) | Blocked / waiting on dependency |
| In Progress | STATUS(104) | Research / spike / exploration |
| Stable / Working | STATUS(201) | Working as expected |
| Stable / Working | STATUS(202) | Verified with real usage |
| Stable / Working | STATUS(203) | Documentation updated (README, JSDoc, etc.) |
| Stable / Working | STATUS(204) | Production-ready |
| Change / Improvement | STATUS(300) | Refactoring (no functional change) |
| Change / Improvement | STATUS(301) | Feature or capability added |
| Change / Improvement | STATUS(302) | Enhancement or improvement |
| Change / Improvement | STATUS(303) | Performance optimization |
| Change / Improvement | STATUS(304) | UI/UX / Styling changes |
| Change / Improvement | STATUS(305) | Accessibility (a11y) improvement |
| Design / Usage Issues | STATUS(401) | Incorrect data flow or usage |
| Design / Usage Issues | STATUS(403) | Scope or responsibility issue |
| Design / Usage Issues | STATUS(408) | Performance / latency issues identified |
| Design / Usage Issues | STATUS(409) | Works but risky / fragile (needs review or testing) |
| Broken / Failure | STATUS(500) | Not working / runtime failure |
| Broken / Failure | STATUS(502) | Interface or contract mismatch |
| Broken / Failure | STATUS(503) | Security vulnerability or auth failure |
| Recovery | STATUS(601) | Bug or failure fixed |
| Recovery | STATUS(603) | Structure or state corrected |
| Test/ Testing | status(700) | Test file- enhance/ improvement/ created |
| Test-> pass | status(701) | Test pass / can be trusted |
| Test-> fail | status(702) | Test intentionally failing (TDD/Reproducer) |
| Performance | status(801) | Benchmarking / profiling results added |
| Special | STATUS(infinity) | Gold Master / Fully stable, tested, and trusted |
| Special | STATUS(404) | Human State / Chaos (does not indicate code quality) |
Note: Some numeric gaps are intentional and reserved for future codes or team-specific use.
status(301): add export endpoint
status(601): fix null pointer in auth middleware
status(102): scaffold payment flow
status(103): blocked by vendor API changes
status(409): works but risky, needs extra testing
status(203): update README and usage examples
status(infinity): v1.0.0 gold master
status(404): everything is broken except me
status-commit/npm CLI (bin:status-commit) withinstall,scan,report,dashboard.hooks/commit-msgenforced by the CLI installer (codes unchanged).status-codes.jsonprovides machine-readable codes.- VS Code extension remains in
vscode-extension/(unchanged).
A GitHub Action is included at .github/workflows/status-commit.yml to check commit messages in PRs and pushes to main.
- Issue templates live in
.github/ISSUE_TEMPLATE. - A pull request template lives at
.github/pull_request_template.md.
STATUS works perfectly alongside Conventional Commits. While Conventional Commits describe the type of change, STATUS describes the health of the change.
| Convention | Focus | Example |
|---|---|---|
| Conventional | Type/Scope | feat(api): add user export |
| STATUS | Reliability | status(301): add user export |
| Combined | Full Context | status(301): feat(api): add user export |
- Be Honest: If it's broken, code it
500. It's better to know it's broken than to pretend it's finished. - Be Objective: Use the code that matches the current state, not the desired state.
- Be Fast: Don't overthink. If it's a new feature that works, it's
301.
- Do I have to use it for every commit? Only if you enable the hook or CI check.
- Does it replace semantic versioning? No. It is about commit intent, not releases.
- Can I combine this with Conventional Commits? Yes, just add the conventional type after the STATUS prefix.
- What about merge commits? They are allowed and ignored by the hook and CI.
git, commit, conventions, workflow, developer-tools, productivity
- Docs landing page:
docs/(optional). - Website: deploys from
website/via GitHub Actions. Set Pages source to GitHub Actions.
A full website lives in website/ as a Next.js app.
cd website
pnpm install
pnpm devA ready-to-use image is included at assets/social-preview.svg. Export it to PNG and set it in your GitHub repository settings for better sharing.
See CHANGELOG.md.
See CONTRIBUTING.md.
Created and maintained by Himeshchanchal Bhattarai.
Apache-2.0. See LICENSE and NOTICE.