nvim-commit

name: nvim-commit description: > Create conventional commits for Neovim plugins that are compatible with release-please and follow SemVer. Use when the user asks to commit changes, make a git commit, or says "/commit" while working in a Neovim plugin project. Analyzes the diff to produce correctly scoped, typed commit messages that release-please can parse into changelog entries and semantic version bumps. Also use when the user asks about commit message format for their Neovim plugin or wants to know what type a change should be. license: MIT allowed-tools: Bash

Neovim Plugin Conventional Commits

Create semantic git commits for Neovim plugins that release-please can parse into changelog sections and correct version bumps.

Why this matters

release-please scans commit messages to decide what goes in the CHANGELOG and whether to bump the patch, minor, or major version. A poorly scoped or mistyped commit either gets ignored or ends up in the wrong changelog section. Every commit message is a contract with the release tooling.

Conventional Commit Format

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

The scope is always present — unlike generic conventional commits where scope is optional, Neovim plugins benefit from always scoping because modules are small and tightly named. Users reading the changelog need to see at a glance which module changed.

Commit Types and SemVer Impact

Scopes

The scope identifies the module or area that changed. It should match the Lua module name under lua/<plugin>/ as closely as possible, since that's what users recognize from the changelog.

Auto-detecting scope from file paths

Map changed files to scopes using these patterns:

When multiple files span different scopes, pick the scope of the primary change. If there is no clear primary scope (e.g., a cross-cutting refactor), use the broadest common scope or omit the scope.

The <plugin> name is the directory name under lua/. Detect it by running ls lua/ and using the single directory found there.

Scope style

• Lowercase, no hyphens or underscores — match the Lua module name as-is
• Examples: config, init, util, health, types
• For nested modules: nes.edit, cli.prompt, terminal

Breaking Changes

Breaking changes bump the major version (or minor if pre-1.0). Signal them with ! after the type/scope:

feat(config)!: rename `disabled` to `enabled`

BREAKING CHANGE: `disabled` option renamed to `enabled` with inverted logic.
Users must update their config.

Or use a BREAKING CHANGE: footer. Both work with release-please. The footer style is preferred when the body needs to explain migration steps, since the ! style keeps the subject line cleaner.

Workflow

1. Detect the plugin name

ls lua/

The single directory under lua/ is the plugin name. Use it to detect scopes from file paths.

2. Analyze the diff

# Staged changes
git diff --staged

# If nothing staged, check working tree
git diff

# File list for scope detection
git diff --name-only --staged || git diff --name-only

3. Stage files if needed

If nothing is staged, check git status --porcelain and stage the changed files. Group logically related changes together — one commit per concern.

Never commit: secrets, .env, credentials, private keys.

4. Determine type and scope

Read the diff and decide:

• Type: based on the nature of the change (new functionality → feat, bug fix → fix, etc.)
• Scope: auto-detect from the file paths using the table above
• Description: one line, present tense, imperative mood, under 72 characters

5. Execute the commit

# Single line
git commit -m "feat(config): add debounce option for status updates"

# With body
git commit -m "$(cat <<'EOF'
feat(health): add check for deprecated options

Warn users when their config contains keys that were removed
in the latest major version.
EOF
)"

# Breaking change
git commit -m "$(cat <<'EOF'
feat(init)!: require explicit setup() call

BREAKING CHANGE: The plugin no longer auto-starts. Users must
call `require('plugin').setup({})` in their config.
EOF
)"

Writing good descriptions

• Present tense, imperative mood: "add option" not "added option" or "adds option"
• Start with a lowercase letter after the colon: feat(util): add debounce helper
• Be specific: "add debounce option to config" beats "add new option"
• Keep under 72 characters (the subject line, including type and scope)
• Don't end with a period

Project files vs local tooling

The .agents/ directory in this project is version-controlled — it contains skill definitions that are part of the repo, just like lua/, doc/, or tests/. Treat files under .agents/ the same as any other project code when staging and committing. Do not suggest skipping or excluding them.

What to avoid

• Don't use chore for actual code changes — it won't appear in the changelog
• Don't combine multiple unrelated changes in one commit (release-please can't separate them)
• Don't use generic scopes like core or misc — use the actual module name
• Don't reference issue numbers in the subject line; put them in the body or footer

Git Safety

• Never update git config
• Never run destructive commands (--force, hard reset) without explicit request
• Never skip hooks (--no-verify) unless asked
• Never force push to main/master
• If commit fails due to hooks, fix and create a new commit (don't amend)