38 lines (31 loc) · 2.49 KB

Repository Guidelines

Project Structure & Module Organization

cmd/diffk/: CLI entrypoint (binary diffk). Parses flags and prints text/JSON.
pkg/diffkeeper/: Core Go API (session lifecycle, git helpers, errors).
docs/: Design notes and usage (docs/usage.md is the quickest reference).
Session metadata is written to .git/diffkeeper/session.toml; optional .diffkeeper/ is read if present.

Build, Test, and Development Commands

Build: go build ./cmd/diffk (Go 1.22). If cache perms are limited: GOCACHE=$(pwd)/.gocache GOPATH=$(pwd)/.gopath GOMODCACHE=$(pwd)/.gopath/pkg/mod go build ./cmd/diffk
Lint/format: go fmt ./... && go vet ./...
Run: ./diffk status --output json; enable git tracing with --debug.
Quick flow: ./diffk init --mode=new-branch --source main --install-hooks --no-upstream --dirty commit --if-missing && ./diffk commit --title "AI: initial"

Coding Style & Naming Conventions

Go style: gofmt-ed, idiomatic error wrapping; no third‑party deps in core.
Packages: lowercase (diffkeeper); exported types/methods use Go CamelCase; JSON fields use lowerCamel via struct tags.
Branches created by the tool: diffkeeper/<source>/<YYYYMMDD-HHMMSS>; commit titles prefer AI: <imperative>.

Testing Guidelines

Add unit/integration tests under pkg/diffkeeper using go test ./....
For git flows, use t.TempDir() + git init and run helper functions; avoid mutating the real repo.
Aim for critical-path coverage: session start/end, commit (no changes vs paths), squash, merge strategies, stage patch errors.

Commit & Pull Request Guidelines

Commits: small, behavior‑scoped; present‑tense, imperative. Prefer prefixing AI‑authored commits with AI:; squash commits may read Squash: ....
PRs: include what/why, CLI examples (commands and expected output), and any linked issues. Add before/after notes for UX changes.

Security & Configuration Tips

Pre‑push hook（init --install-hooks）阻止推送 diffkeeper/* 分支；临时覆盖 DIFFKEEPER_ALLOW_PUSH=1。
Commands take a process lock under .git/diffkeeper/lock; on LOCKED retry serially.
Do not commit session files unless explicitly required.

Agent‑Specific Instructions

Favor JSON output: --output json; use --debug/--timeout for stability.
Init flows: prefer --if-missing + --dirty commit (or stash when switching source).
Treat non‑zero exit codes as actionable states (error.errorCode present in JSON; see docs/automation.md).