| 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:
which git-com succeeds (git-com is installed)- 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.
