git-com-structured-commits

name	git-com-structured-commits
description	Use when about to make a git commit or run git commit/git commit --amend. Checks whether git-com is installed and a .git-com.yaml config exists, then creates a structured commit using git-com instead of plain git commit. Trigger phrases: "commit", "commit changes", "make a commit", "git commit", "commit my work", "commit these changes".

When to Use This Skill

Before running git commit or git commit --amend, always check whether git-com should be used instead. Use git-com when ALL of the following are true:

1. which git-com succeeds (git-com is installed)
2. A .git-com.yaml or .git-com.yml exists in the git repository root

If either check fails, fall back to normal git commit.

Steps

1. Detect git-com

which git-com

If this fails, use git commit normally and stop.

2. Ask git-com if it has been configured to run

git-com --has-config

If that returns a non-zero exit code, then do not use git-com. Instead, use git commit as you normally would git-com won't function if there isn't a configuration file in the repository.

3. Get the commit schema

git-com --dump-instructions

This outputs a YAML document under an elements: key. Each key under elements: is a field you must fill in.

Reading the output:

Field	Meaning
type: text	Free-text string value
type: multiline-text	Multi-line string value
type: select	Must be one of options: (unless modifiable: true, then any value is accepted)
type: multi-select	YAML list of values from options: (unless modifiable: true)
type: confirmation	true to proceed, false to abort the commit
required: true	Field must have a non-empty, non-null value
required: false	Field should be null if you have nothing to provide
agent-hint:	Guidance for the value you provide — follow it
instructions:	Describes what the field is asking for

4. Create a temporary answers file

ANSWERS_FILE=$(mktemp -t git-com-answers-XXXXXX.yaml)

Note: ANSWERS_FILE is never at git-com-answers-XXXXXX.yaml It is at the path generated by the mktemp command that uses that string as a template.

Write the answers content to $ANSWERS_FILE.

The answers file is a flat YAML key-value document. It must contain one key for every key listed under elements: in the dump-instructions output.

Rules:

• For required: true elements: provide a value that satisfies the type constraints
• For required: false elements: provide a value or use null if you have nothing to say
• For type: select: value must be from options: unless modifiable: true
• For type: multi-select: value is a YAML list (e.g. [core, docs]) or [] if none
• For type: confirmation: use true to proceed (almost always correct)
• For type: text with data-type: integer: provide an unquoted number or a quoted digit string

Example answers file:

change-type: "fix"
breaking-indicator: null
commit-title: "corrected nil pointer in auth handler"
commit-description: "The handler did not guard against nil session before calling .User()"
code-sections:
  - core
  - auth
ticket-number: null

5. Run git-com with the answers file

git-com --answers "$ANSWERS_FILE"

For amending the last commit instead:

git-com --amend --answers "$ANSWERS_FILE"

5. Clean up

• If the commit succeeded: rm "$ANSWERS_FILE"
• If the commit failed (non-zero exit): leave $ANSWERS_FILE for inspection, report the error

Error Handling

• Validation errors (missing required field, invalid option): git-com prints each error to stderr. Fix the answers file and retry.
• No staged files: git-com exits with code 64. Stage files first, then retry.
• git-com not found or no config: fall back to git commit -m "..." as normal.
• GPG Signing failure: Run the following to figure out how they're they've configured git to sign their commits:

  git config gpg.format
  

  The output of that should be openpgp, ssh, or nothing. If nothing, then the user is using opengpg. If they're using ssh inform them that their ssh keys are not loaded for commit signing. If they're using opengpg inform them that their gpg keys are not loaded for commit signing. In both cases - and if it's an unknown format - tell them that they will have to load their signing keys and tell you when they're ready for you to continue. When you continue you can use the --use-cached-message flag (see below).

Resumbitting Answers After Errors Were encountered

git-com stores a copy of the last commit message whenever a problem is encountered.

Once you, or the user has addressed any errors encountered when trying to commit, you can tell git-com to use the commit message from your last attempt by passing it the --use-cached-message flag. If this returns an error, it means there was no cached message and you'll have to try providing the answers again.

If things have changed since your last attempt and you wish to use a different commit message then pass it the --dont-use-cached-message flag. This will tell it to ignore its cached commit message from the last attempt.