Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 22 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
<h1 align="center">diffnote</h1>
<p align="center"><strong>Turn local Git changes into a reviewable pull request summary.</strong></p>

[![CI](https://github.com/LucasXlab/diffnote/actions/workflows/ci.yml/badge.svg)](https://github.com/LucasXlab/diffnote/actions/workflows/ci.yml) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![Version](https://img.shields.io/badge/source-v0.1.0-6b7280.svg)](https://github.com/LucasXlab/diffnote/blob/main/pyproject.toml) ![Runtime](https://img.shields.io/badge/Python-3.8%2B-3776ab.svg) [![Stars](https://img.shields.io/github/stars/LucasYanzy/diffnote?style=flat)](https://github.com/LucasXlab/diffnote/stargazers)
[![CI](https://github.com/LucasXlab/diffnote/actions/workflows/ci.yml/badge.svg)](https://github.com/LucasXlab/diffnote/actions/workflows/ci.yml) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![Version](https://img.shields.io/badge/source-v0.1.0-6b7280.svg)](https://github.com/LucasXlab/diffnote/blob/main/pyproject.toml) ![Runtime](https://img.shields.io/badge/Python-3.8%2B-3776ab.svg) [![Stars](https://img.shields.io/github/stars/LucasXlab/diffnote?style=flat)](https://github.com/LucasXlab/diffnote/stargazers)

[English](README.md) · [简体中文](README.zh-CN.md)

Expand All @@ -21,10 +21,17 @@ Writing a PR description after the coding is finished is easy to postpone. diffn

## Quick start

```bash
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.

Expand All @@ -34,7 +41,7 @@ Bucket source, tests, docs, configuration and migrations; surface file and line-

### Export a draft

Generate terminal, Markdown or JSON output. Titles and risk signals are heuristics, not a semantic code review.
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

Expand All @@ -49,8 +56,15 @@ 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

```mermaid
Expand All @@ -75,6 +89,12 @@ 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](CONTRIBUTING.md). Report reproducible problems in [Issues](https://github.com/LucasXlab/diffnote/issues). Follow [SECURITY.md](SECURITY.md) for sensitive reports.

Expand Down
11 changes: 9 additions & 2 deletions README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
<h1 align="center">diffnote</h1>
<p align="center"><strong>将本地 Git 改动整理成便于审阅的 PR 摘要。</strong></p>

[![CI](https://github.com/LucasXlab/diffnote/actions/workflows/ci.yml/badge.svg)](https://github.com/LucasXlab/diffnote/actions/workflows/ci.yml) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![Version](https://img.shields.io/badge/source-v0.1.0-6b7280.svg)](https://github.com/LucasXlab/diffnote/blob/main/pyproject.toml) ![Runtime](https://img.shields.io/badge/Python-3.8%2B-3776ab.svg) [![Stars](https://img.shields.io/github/stars/LucasYanzy/diffnote?style=flat)](https://github.com/LucasXlab/diffnote/stargazers)
[![CI](https://github.com/LucasXlab/diffnote/actions/workflows/ci.yml/badge.svg)](https://github.com/LucasXlab/diffnote/actions/workflows/ci.yml) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![Version](https://img.shields.io/badge/source-v0.1.0-6b7280.svg)](https://github.com/LucasXlab/diffnote/blob/main/pyproject.toml) ![Runtime](https://img.shields.io/badge/Python-3.8%2B-3776ab.svg) [![Stars](https://img.shields.io/github/stars/LucasXlab/diffnote?style=flat)](https://github.com/LucasXlab/diffnote/stargazers)

[English](README.md) · [简体中文](README.zh-CN.md)

Expand Down Expand Up @@ -36,7 +36,7 @@ python3 scripts/demo.py

### 导出初稿

输出终端、Markdown 或 JSON;标题与风险信号来自启发式规则,不代替语义审查。
输出终端、Markdown 或 JSON;用 `--markdown --save body.md` 可保存文件,成功时标准输出为空。标题与风险信号来自启发式规则,不代替语义审查。

### 可选模型润色

Expand All @@ -51,8 +51,15 @@ diffnote --staged
diffnote --base main --markdown
diffnote --range main..HEAD --json
diffnote --commits 2
diffnote --markdown --save body.md
diffnote --color
diffnote --no-color
```

默认仅在标准输出连接终端时使用 ANSI 颜色;`--color` 强制开启,`--no-color` 禁用。

破坏性变更提示只读取 `--commits`、`--range` 或 `--base` 所选比较范围内的 `!:` 提交标记,不再截断为最近 25 个提交。纯工作区或暂存摘要不套用历史提交标记;公共 API 路径提示仍对所有模式生效。

## 架构

```mermaid
Expand Down
Binary file modified assets/demo.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified assets/demo.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified assets/social-preview.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified demo.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion demo/terminal.txt
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ $ diffnote --no-color
diffnote — PR / changelog summary
──────────────────────────────────────────
2 files changed (+2 / -1)
Suggested title: fix: round checkout amounts
Suggested title: fix: update implementation
Changelog section: fix

Changes by area
Expand Down
16 changes: 15 additions & 1 deletion src/diffnote/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,20 @@ def get_diff(args, cwd):
return gitutil.get_diff_text("HEAD", cwd=cwd, staged=args.staged)


def get_selected_commit_messages(args, cwd):
if args.commits:
revision_range = f"HEAD~{args.commits}..HEAD"
elif args.range:
base, _, head = args.range.partition("..")
revision_range = f"{base}..{head or 'HEAD'}"
elif args.base:
revision_range = f"{args.base}..HEAD"
else:
# Working-tree and staged changes have no commit subjects of their own.
return []
return gitutil.get_commit_messages(n=None, cwd=cwd, revision_range=revision_range)


def main(argv=None):
parser = build_parser()
args = parser.parse_args(argv)
Expand All @@ -80,7 +94,7 @@ def main(argv=None):
print("diffnote: no file changes parsed.", file=sys.stderr)
return 0

commit_messages = gitutil.get_commit_messages(cwd=cwd)
commit_messages = get_selected_commit_messages(args, cwd)
summary = analyze.build_summary(files, commit_messages)

llm_prose = None
Expand Down
16 changes: 12 additions & 4 deletions src/diffnote/gitutil.py
Original file line number Diff line number Diff line change
Expand Up @@ -45,10 +45,18 @@ def get_range_diff(base, head="HEAD", cwd=None):
return proc.stdout


def get_commit_messages(n=25, cwd=None):
proc = _run(
["log", "-n", str(n), "--no-merges", "--pretty=format:%s"], cwd=cwd
)
def get_commit_messages(n=25, cwd=None, revision_range=None):
"""Read commit subjects, optionally restricted to an explicit comparison.

Pass n=None to include every commit in a selected range.
"""
args = ["log", "--no-merges", "--pretty=format:%s"]
if n is not None:
args.extend(["-n", str(n)])
if revision_range is not None:
args.append(revision_range)
args.append("--")
proc = _run(args, cwd=cwd)
return [m for m in proc.stdout.splitlines() if m.strip()]


Expand Down
111 changes: 111 additions & 0 deletions tests/test_commit_scope.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,111 @@
"""Regression coverage for commit markers belonging to the selected diff."""

import json
import subprocess

import pytest

from diffnote import cli


def _git(repo, *args):
return subprocess.check_output(["git", *args], cwd=repo, text=True).strip()


def _init(repo):
_git(repo, "init", "-q", "-b", "main")
_git(repo, "config", "user.name", "Scope Fixture")
_git(repo, "config", "user.email", "fixture@example.invalid")


def _commit(repo, message, text):
(repo / "README.md").write_text(text, encoding="utf-8")
_git(repo, "add", "README.md")
_git(repo, "-c", "commit.gpgsign=false", "commit", "-qm", message)


def _summary(args, capsys):
assert cli.main([*args, "--json"]) == 0
return json.loads(capsys.readouterr().out)


def _is_breaking(summary):
return any(risk["label"] == "possible breaking change"
for risk in summary["risks"])


@pytest.mark.parametrize("args", [
[],
["--staged"],
["--commits", "1"],
["--range", "old-marker..docs-end"],
["--base", "old-marker"],
])
def test_old_breaking_marker_does_not_contaminate_selected_docs(
tmp_path, monkeypatch, capsys, args,
):
_init(tmp_path)
_commit(tmp_path, "feat!: retire an old API", "# Original\n")
_git(tmp_path, "tag", "old-marker")
_commit(tmp_path, "docs: clarify wording", "# Clarified\n")
_git(tmp_path, "tag", "docs-end")
(tmp_path / "README.md").write_text("# Current docs\n", encoding="utf-8")
_git(tmp_path, "add", "README.md")
monkeypatch.chdir(tmp_path)

summary = _summary(args, capsys)

assert summary["total_files"] == 1
assert not _is_breaking(summary)
assert summary["title"] != "feat!: retire an old API"


def test_range_reads_markers_from_selected_branch_instead_of_head(
tmp_path, monkeypatch, capsys,
):
_init(tmp_path)
_commit(tmp_path, "docs: initial", "# Initial\n")
_git(tmp_path, "tag", "start")
_git(tmp_path, "checkout", "-qb", "feature")
_commit(tmp_path, "feat!: remove legacy response", "# New response\n")
_git(tmp_path, "tag", "feature-end")
_git(tmp_path, "checkout", "-q", "main")
_commit(tmp_path, "docs: sibling branch", "# Sibling\n")
monkeypatch.chdir(tmp_path)

summary = _summary(["--range", "start..feature-end"], capsys)

assert _is_breaking(summary)
assert summary["title"] == "feat!: remove legacy response"


def test_range_excludes_markers_committed_after_its_endpoint(
tmp_path, monkeypatch, capsys,
):
_init(tmp_path)
_commit(tmp_path, "docs: initial", "# Initial\n")
_git(tmp_path, "tag", "start")
_commit(tmp_path, "docs: selected change", "# Selected\n")
_git(tmp_path, "tag", "selected")
_commit(tmp_path, "feat!: later change", "# Later\n")
monkeypatch.chdir(tmp_path)

summary = _summary(["--range", "start..selected"], capsys)

assert not _is_breaking(summary)
assert summary["title"] == "docs: selected change"


def test_commit_selection_is_not_silently_limited_to_25_messages(
tmp_path, monkeypatch, capsys,
):
_init(tmp_path)
_commit(tmp_path, "docs: initial", "# Initial\n")
_commit(tmp_path, "feat!: selected API change", "# API change\n")
for i in range(26):
_commit(tmp_path, "docs: update {}".format(i), "# Update {}\n".format(i))
monkeypatch.chdir(tmp_path)

summary = _summary(["--commits", "27"], capsys)

assert _is_breaking(summary)
Loading