git

Instruction file imported from whhe/ai-workshop (.cursor/rules/git.mdc). Copyright stays with the author.

Git

Branching

• Prefer working on dedicated branches whose names start with feature- or fix-.

Owner repo exception

Skip branch-name checks and work directly on the current branch only when all three conditions are met:

1. Single remote: The repository has exactly one remote (any name)
2. GitHub remote: That remote's fetch URL points to GitHub (SSH or HTTPS URL)
3. Owner match: The owner in owner/repo equals the current user's GitHub login

Verification steps:

• List remotes: git remote -v — confirm there is exactly one remote, then use its fetch URL
• Parse owner from that URL (SSH: git@github.com:owner/repo.git, HTTPS: https://github.com/owner/repo.git)
• Verify gh availability: which gh
• Verify gh authentication: gh auth status >/dev/null 2>&1
• Get current user: gh api user --jq .login

When to check: Verify these conditions once at the start of a session or before the first code change, not before every operation.

Performance tip: Cache the result of owner verification to avoid repeated API calls within the same session.

Fallback behavior: If any check fails (e.g., gh not installed, not authenticated, network error, zero or multiple remotes, non-GitHub remote, owner mismatch), always apply the default-branch rules below — prefer creating a dedicated branch over direct commits.

Before making code changes on a default branch

For all other repositories, when the current branch is a default branch (main, master, dev, or the repo's equivalent):

1. Ask whether the user wants a new feature-... or fix-... branch before proceeding. Do not assume work should happen on the default branch.
2. If the user agrees to create a branch, before creating it, check whether the local default branch matches its remote tracking branch (e.g. after git fetch, compare main and origin/main).
3. If local is behind or diverges, tell the user to pull/sync first and why. Do not run git pull unless they explicitly ask.
4. Create or switch branches only after explicit user agreement on the steps.

No unsolicited git operations

Unless the user clearly asks, do not decide on your own to:

• git pull or fetch/merge workflows (unless they explicitly ask to pull or sync)
• git commit (unless they explicitly ask to commit or save a commit)
• git push (unless they explicitly ask to push or "commit and push")

If they ask to "submit code" / "commit", a local commit is OK; still no push unless they explicitly ask.

Review before commit

After making code changes, always show the diff to the user and wait for explicit confirmation before committing. The workflow is:

1. Make edits and show the diff.
2. Wait for user to confirm the changes.
3. Only then git commit.
4. Only git push if the user explicitly asks.

"采纳" / "确认" on a proposed change means approval to edit — not to commit or push. Each step requires separate, explicit approval.

Stash

• Before switching branches with uncommitted changes, use git stash to save work. Remind the user to git stash pop after switching back.
• Do not run git stash drop unless the user explicitly asks.

Rebase vs Merge

• Prefer rebase for syncing feature branches with upstream (git rebase main), keeping a linear history.
• Before rebasing, confirm with the user if the branch has been pushed to remote (rebase rewrites history).
• Use merge only for integrating completed feature branches into the default branch.

Issues and Pull Requests

Before creating an issue or PR, always show the full content (title, labels, body) to the user and wait for explicit confirmation before executing the gh command.

Commit message format

All natural-language prose in commit messages—including the subject, body, and footers—must be written in English. Non-English text may appear only as an exact repository identifier, proper name, or quoted user-facing string; all surrounding prose must remain in English.

Use Semantic Commit Messages: feat:, fix:, docs:, refactor:, chore:, test:, style:, perf:, ci:. Subject ≤72 chars; add body for non-trivial changes.

First line: type(scope): title (e.g. feat(permission): enterprise cutover with bug fixes).

Then group changes with - bullets by type:

feat(permission): enterprise cutover with bug fixes

feat:
- Integrate RBAC permission checks in API apps (canvas, chunk, document, kb, tenant)
- Add permission manager UI and form fields for dataset settings

fix:
- Prevent negative doc_num/chunk_num/token_num in kb stats update