Skip to content

docs(git): clarify auto-commit default fallback - #5158

Open
gavenren wants to merge 5 commits into
github:mainfrom
gavenren:docs/5050-auto-commit-default
Open

gavenren wants to merge 5 commits into
github:mainfrom
gavenren:docs/5050-auto-commit-default

Conversation

@gavenren

@gavenren gavenren commented Oct 28, 2026 •

Copy link
Copy Markdown
Contributor

Description

The shipped Git config says auto_commit.default enables all commands, but every listed event is explicitly disabled and prevents that fallback. Align the shipped config, template, README and commit-command instructions: enable listed events individually, or remove an event's entire section to use the default.

Explain the fixed-message tradeoff: removing a section also removes its custom message, so after_specify uses [Spec Kit] Auto-commit after specify. Keep the section with enabled: true to retain its message. Place example boolean comments on separate lines so the actual Bash/Python parsers accept the copied example.

Bump the bundled Git extension and its catalog entry together from 1.0.1 to 1.0.2, making the updated installed instructions available to existing installations. Executable scripts and opt-in semantics are unchanged. This follows the documentation resolution proposed in #5050.

Fixes #5050.

Testing

  • .venv/bin/python -m pytest tests/extensions/git tests/contract/test_bundled_extension_versions.py tests/contract/test_extension_version_guard_script.py -q: 163 passed, 51 skipped. The manifest validation assertion now matches version 1.0.2; the previous assertion fails against the bumped manifest.
  • Extracted the command guide's YAML fence and ran Bash/Python in real temporary Git projects: 6 checks confirm custom messages, the documented fallback message, and explicit disabled events.
  • Earlier example validation: 8 real Git checks pass after moving inline boolean comments; 4 positive checks failed before that correction.
  • The extension version guard fails before the version bump and passes afterward against current main.
  • git diff --check passes. Native Windows/PowerShell execution and the full suite were not run; no executable script was changed.

AI Disclosure

  • I did use AI assistance.

OpenAI Codex in ChatGPT Work Mode acted autonomously on behalf of @gavenren. AI inspected the issue and code, authored the changes, ran the listed checks, and wrote the commits and PR description. The exact underlying model identifier and reasoning settings are unavailable. No human line-by-line review or manual testing is claimed. Each commit includes an Assisted-by: trailer.

Explain that auto_commit.default only applies to events without a section,
and that the shipped explicit disabled entries require enabled: true.
Document removal of the whole event section to restore fallback behavior.

Validation: existing Bash/Python auto-commit parity suite: 11 passed,
1 skipped (root cannot model unreadable files); git diff --check passed.

Fixes github#5050

Assisted-by: OpenAI Codex (model: unknown, autonomous)

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Misleading “enable for all commands” guidance remains in the config copied on fresh installs and in the commit-command documentation.

1 open issue
What changed in this PR

Clarifies the Git extension’s auto-commit guidance for #5050 while preserving the existing opt-in behavior.

Changes:

  • Explains that auto_commit.default applies only when an event’s section is absent.
  • Documents individual event opt-in and whole-section removal for fallback behavior.
  • Leaves executable code and configuration values unchanged.
File Description
extensions/​git/​README.md Explains explicit event settings and how to activate default fallback.
extensions/​git/​config-template.yml Replaces misleading global-toggle comments with event opt-in guidance.

Review effort: Max

Comment on lines +28 to +29
# "default" applies only to events that have no section below.
# Listed events must use "enabled: true" to opt in, even if default is true.
Address PR github#5158 review by correcting the actual copied git-config.yml and
the commit command's configuration example and fallback instructions.

Validation: existing auto-commit parity checks: 11 passed, 1 skipped.
No executable code or configuration values changed.

Assisted-by: OpenAI Codex (model: unknown, autonomous)
@gavenren

Copy link
Copy Markdown
Contributor Author

Addressed the review in 5af3768. The actual config copied on installation (extensions/git/git-config.yml) and the commit command instructions now describe the same absent-section fallback as the template and README. Listed events still require enabled: true; retaining only a custom message also keeps the default from applying. No executable code or configuration values changed.

Re-ran the existing auto-commit parity checks: 11 passed, 1 skipped (the unreadable-file case cannot run as root). git diff --check passed.

AI disclosure: OpenAI Codex acted autonomously on behalf of @gavenren to make these review corrections and run the checks. The exact underlying model and reasoning setting are unavailable; no human review is claimed.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Inline comments in the auto-commit example break boolean parsing, leaving after_specify disabled and preventing fallback if default is changed to true while retaining its comment.

1 open issue
1 previously missed issue

In code that hasn't changed since last review

Low severity Move inline comments off boolean configuration values

extensions/​git/​commands/​speckit.git.commit.md:51

The auto-commit parsers treat the inline comments as part of these boolean values, so copying this example leaves after_specify disabled. Changing default to true while keeping its comment also prevents fallback for unlisted events. Move both comments onto separate lines so the example supports the documented configuration.

Review effort: Max

@mnriem

mnriem commented Oct 28, 2026

Copy link
Copy Markdown
Collaborator

Please address Copilot feedback

@mnriem mnriem added author-awaiting Waiting on author response triage-nice-to-have Verdict: evidence-backed fix or greenlit feature — land after review labels Oct 28, 2026
The auto-commit example is copied into `git-config.yml`, whose lightweight parsers include inline comments in boolean values. Move the two comments above their keys so listed enable and unlisted-event fallback examples work without changing their values.

Validation: extract the actual fenced example and run both Bash and Python scripts in real temporary Git projects. Four cases per runtime now pass; four positive results failed before. Existing parity tests: 11 passed, 1 root-permission skip. No PowerShell execution is claimed.

Assisted-by: OpenAI Codex (model: unknown, autonomous)
@gavenren

Copy link
Copy Markdown
Contributor Author

Moved both inline boolean comments onto their own lines in 3f3db7f. The example now enables after_specify as written, and changing default to true enables an event with no section. Explicitly disabled events and default:false still skip commits.

Extracted the actual YAML fence and ran the Bash and Python scripts in real temporary Git projects: eight checks pass after the correction; the four positive checks failed before it. The existing auto-commit parity selection passes 11 tests with one unreadable-file skip because this environment runs as root. git diff --check passes. No PowerShell execution is claimed.

AI disclosure: posted on behalf of @gavenren by OpenAI Codex in ChatGPT Work Mode, acting autonomously. AI authored this documentation correction, ran the checks, and wrote this response. The exact underlying model and reasoning setting are unavailable; no human review or manual testing is claimed.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Human assessment is needed to weigh an unpublished minor documentation finding about fallback behavior also changing custom commit messages.

1 open issue

Review effort: Max

@mnriem

mnriem commented Oct 28, 2026

Copy link
Copy Markdown
Collaborator

Please address Copilot feedback

@mnriem

mnriem commented Oct 28, 2026

Copy link
Copy Markdown
Collaborator

Please fix CI/CD version guard issue

Clarify that removing an event section in fixed-message mode also removes its custom message. Show the resulting after_specify fallback message and recommend enabled:true when retaining a custom message.

Increase the bundled git extension and catalog versions together from 1.0.1 to 1.0.2 so the revised installed instructions reach existing installations and satisfy the extension version guard.

Auto-commit parity and version-contract checks pass (49 passed, one root-permission skip). Six real Bash/Python Git checks confirm custom, fallback, and explicitly disabled cases. No executable script or PowerShell behavior changes.

Assisted-by: OpenAI Codex (model: unknown, autonomous)
@gavenren

Copy link
Copy Markdown
Contributor Author

Addressed both follow-ups in 9ccb783. The README, command guide and copied config comments now explain that removing an event section also discards its fixed custom message; after_specify then uses “[Spec Kit] Auto-commit after specify”. The Git extension manifest and bundled catalog now both declare 1.0.2, so the installed instructions can update.

The version guard fails before the bump and passes afterward against current main. Auto-commit parity plus version-contract/guard tests: 49 passed, 1 skipped (root bypasses the unreadable-file fixture). Six real temporary Git checks confirm the custom message, fallback message and explicit-disabled behavior in Bash/Python. git diff --check passes. No executable script or PowerShell behavior was changed; no native Windows execution is claimed.

AI disclosure: posted on behalf of @gavenren by OpenAI Codex in ChatGPT Work Mode, acting autonomously. AI authored the correction, ran the checks and wrote this summary. The exact underlying model and reasoning setting are unavailable; no human review or manual testing is claimed.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The manifest version bump to 1.0.2 leaves the validation test expecting 1.0.1, causing it to fail.

2 open issues

Review effort: Max

id: git
name: "Git Branching Workflow"
version: "1.0.1"
version: "1.0.2"
@mnriem

mnriem commented Oct 28, 2026

Copy link
Copy Markdown
Collaborator

Please address Copilot feedback

Update the manifest validation assertion to 1.0.2 alongside the Git extension's required manifest/catalog version bump.

The old assertion fails against the bumped manifest. The complete Git extension test directory plus bundled-version and version-guard contracts now pass: 163 passed, 51 skipped. No Windows or PowerShell execution is claimed.

Assisted-by: OpenAI Codex (model: unknown, autonomous)
@gavenren

Copy link
Copy Markdown
Contributor Author

Addressed the remaining manifest-version test failure in 7ef05ca: the validation assertion now expects 1.0.2, matching the extension manifest and bundled catalog. The previous assertion fails against that manifest. The complete Git extension test directory plus bundled-version and version-guard contracts pass: 163 passed, 51 skipped. The extension version guard and git diff --check also pass. The PR description now records the full validation. The existing review request for @mnriem remains pending. No native Windows/PowerShell execution is claimed.

AI disclosure: OpenAI Codex in ChatGPT Work Mode acted autonomously on behalf of @gavenren to make this correction, run these checks, and write this comment. The exact underlying model and reasoning settings are unavailable; no human review or manual testing is claimed.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues block the Git auto-commit documentation and version updates.

2 open issues

Review effort: Max

@mnriem

mnriem commented Oct 28, 2026

Copy link
Copy Markdown
Collaborator

Please address Copilot feedback. If it is not applicable, please explain why. If it is already resolved, please explain how.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

author-awaiting Waiting on author response triage-nice-to-have Verdict: evidence-backed fix or greenlit feature — land after review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Bug]: git extension: auto_commit.default: true has no effect with the shipped config template

3 participants