Skip to content
LucasXlabPublic

About

Turn staged Git changes into an editable PR draft. Offline Python CLI with Markdown/JSON, traceable review signals, and safe file export.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Current maintained source: open the Noah branch · 简体中文. This main branch retains the older 0.1 interface. Follow the explicit branch installation on the maintained README for the new-file report export and reviewed Git handling.

diffnote logo

diffnote

Turn local Git changes into a reviewable pull request summary.

CI License Version Runtime Stars

English · 简体中文

Real CLI output on synthetic fixtures

The demo is captured from the real CLI using synthetic data. Transcript · regenerate with python3 scripts/demo.py.

Why

Writing a PR description after the coding is finished is easy to postpone. diffnote groups a diff by area, highlights rule-based risk signals, and generates a starting point for the reviewer.

Start with Good for Where diffnote helps
git diff --stat Inspect change size diffnote adds grouping and a PR-description draft.
Commit-log changelogs Describe released commits diffnote can also summarize tracked, uncommitted changes.

Quick start

git clone https://github.com/LucasXlab/diffnote.git && cd diffnote
python3 -m pip install .
python3 scripts/demo.py

Install from this checkout to use the reviewed source version. The installed tool has no third-party runtime dependencies; cloning and installation can require network access.

Features

Choose your diff

Summarize tracked working-tree changes, staged changes, a base ref, or a commit range.

Group the work

Bucket source, tests, docs, configuration and migrations; surface file and line-change counts.

Export a draft

Generate terminal, Markdown or JSON output. Save Markdown to a file with --markdown --save body.md; successful saving leaves stdout empty. Titles and risk signals are heuristics, not a semantic code review.

Optional prose

--llm sends a bounded diff excerpt to the configured Ollama endpoint; the default is localhost and unavailable models fall back to rules.

CLI result

Usage

diffnote --staged
diffnote --base main --markdown
diffnote --range main..HEAD --json
diffnote --commits 2
diffnote --markdown --save body.md
diffnote --color
diffnote --no-color

Terminal output uses ANSI colors only when stdout is a terminal. --color forces colors; --no-color disables them.

Breaking-change hints use !: subjects from the selected --commits, --range, or --base comparison, without a 25-commit cutoff. Working-tree and staged-only summaries do not reuse historical commit subjects. Public API path hints still apply in every mode.

Architecture

flowchart LR
A[Local Git diff] --> B[Parse files and hunks]
B --> C[Group areas and risk signals]
C --> D[Terminal / Markdown / JSON]
B -. explicit --llm .-> E[Configured Ollama endpoint]
E --> D
Loading

Privacy and limits

Default operation reads local Git data without network requests. --llm sends up to 6,000 diff characters and a suggested title to DIFFNOTE_OLLAMA (default http://localhost:11434). A remote setting sends that data off the machine. Reports can contain filenames and diff details. See PRIVACY.md for data boundaries.

Development

python3 -m pip install -e ".[test]"
python3 -m pytest -q

The demo uses a temporary fixture and does not inspect your personal repositories or agent homes.

Roadmap

  • Improve error messages for invalid refs and empty histories.
  • Add configurable grouping rules.

Contributing

Read CONTRIBUTING.md. Report reproducible problems in Issues. Follow SECURITY.md for sensitive reports.

License

MIT.

About

Turn staged Git changes into an editable PR draft. Offline Python CLI with Markdown/JSON, traceable review signals, and safe file export.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages