Committing Changes

Overview

ALWAYS use git-spice (gs) for creating commits and branches, and for amending commits. NEVER use raw git commands for these purposes (git commit, git checkout -b, git branch $name).

Why git-spice: Maintains branch relationships and auto-rebases dependent branches. Using raw git breaks stack tracking.

When to Use

Use this skill for ALL commit operations:

• •Creating commits on new or existing branches
• •Amending commits
• •Creating feature branches
• •Stacking branches
• •Recovering from raw git usage

Triggers:

• •User asks to commit changes
• •User asks to create a branch
• •User asks to amend a commit
• •User says "just commit quickly"
• •User already used git commit/checkout

Quick Reference

Branch naming: lowercase-with-hyphens (no /, no uppercase, no user prefixes)

• •If user provides non-conforming name, automatically normalize it and inform them

Commit messages: MUST follow writing-commit-messages guidelines

• •See the reference file in this skill directory

Branching Decision

If user explicitly states their intent, follow it directly:

• •"Commit to this branch" or "commit to current branch" → Use gs commit create
• •"Create new branch" or "commit to new branch" → Use gs branch create
• •No need to check current branch when intent is explicit

If user intent is ambiguous, determine from context:

flowchart TD
    Start[Where am I?] -->|main/master| NewBranch[Create feature branch]
    Start -->|feature branch| Related{Change related<br/>to this feature?}
    Related -->|Yes| Current[Commit to current branch]
    Related -->|No| NewBranch

Stacking: Creating a new branch while on a feature branch automatically stacks it.

Core Commands

Create branch with commit

gs branch create <branch-name> -m "<commit-message>"

• •Commits staged changes to new branch
• •Switches to new branch
• •If on feature branch, stacks automatically

After creating branch: Run gs ls to show branch position in stack (NOT git log).

Example:

# On main
gs branch create fix-login-validation -m "Fix email validation in login form"

# On feature-auth, creating unrelated change
gs branch create update-readme -m "Update installation instructions"
# This stacks update-readme on top of feature-auth

Commit to current branch

gs commit create -m "<commit-message>"

Commits staged changes to current branch.

After committing: Run gs ls to show branch position in stack (NOT git log).

Get current branch name

git branch --show-current

IMPORTANT: gs branch current does NOT exist. git-spice doesn't have a command for showing the current branch. Use standard git command: git branch --show-current

Common use cases:

• •When user asks "what branch am I on?"
• •Debugging branch-related issues
• •When user's commit intent is ambiguous and you need to determine strategy

NOT needed when:

• •User explicitly says "commit to this branch" (intent is clear)
• •User explicitly says "create new branch" (intent is clear)

Amend last commit

# Keep existing message
gs commit amend

# Replace entire message
gs commit amend -m "<new-complete-message>"

CRITICAL: gs commit amend -m REPLACES the entire commit message. If user says "add" or "append" to message, you MUST include the original message + addition.

Example:

# Original message: "Fix login validation"
# User: "Add note about regex update"

# ❌ WRONG: gs commit amend -m "Also updates regex pattern"
# ✅ CORRECT: gs commit amend -m "Fix login validation

Also updates regex pattern"

Stack on specific branch

gs branch create --target <target-branch> <branch-name> -m "<commit-message>"

Useful when current branch isn't the desired base.

Branch Naming Rules

Required:

• •Lowercase only
• •Hyphens to separate words
• •Descriptive (fix-login-bug, add-user-search)

Forbidden:

• •Slashes: feature/login
• •Uppercase: FixLogin
• •User prefixes: john/fix or abg-fix

Why no prefixes: git-spice automatically adds user prefixes if configured. Adding them manually results in double-prefixing (e.g., abg-abg-fix-bug). Just use descriptive names: fix-bug not abg-fix-bug.

NEVER Use Raw Git

❌ NEVER: git checkout -b <branch>

Why: Bypasses git-spice tracking. Branch won't be in the stack.

Instead:

1. •Stage changes: git add <files>
2. •Get commit message: Use writing-commit-messages skill
3. •Create branch: gs branch create <name> -m "<message>"

❌ NEVER: git commit or git commit --amend

Why: Bypasses git-spice rebase. Dependent branches become stale.

Instead:

• •New commit: gs commit create -m "<message>"
• •Amend: gs commit amend or gs commit amend -m "<new-message>"

❌ NEVER: git branch <name>

Why: Creates untracked branch outside stack.

Instead: Use gs branch create with commit.

❌ NEVER: gs branch current

Why: Command doesn't exist. git-spice has no equivalent for this.

Instead: Use git branch --show-current

Common mistake: Assuming every git command has a gs equivalent. Reality: Some operations (like showing current branch) still use standard git.

Red Flags - STOP

If you're about to:

• •Use any git commit command
• •Use git checkout -b
• •Use git branch to create a branch
• •Use gs branch current (doesn't exist)
• •Skip getting a proper commit message
• •Add a prefix like abg-, john/, or user- to branch names
• •Rationalize "just this once" or "it's faster"
• •Assume a gs command exists because "gs does everything"

STOP. Use git-spice commands instead.

Note: git-spice does NOT have every git equivalent. For getting current branch: use git branch --show-current

Recovery: User Already Used Raw Git

Scenario: User ran git checkout -b bad-name and git commit -m "fix"

DO NOT just push it. Fix the violations:

1. •

   Acknowledge the issue: "This branch/commit doesn't follow conventions. Let me fix it before pushing."

2. •

   Check what's committed:

   bash

   git log -1 --oneline
   

3. •

   Fix commit message:

   • •Follow writing-commit-messages guidelines to generate proper message
   • •Amend: gs commit amend -m "<proper-message>"
4. •

   Fix branch name if needed:

   bash

   gs branch rename <proper-name>
   

5. •

   Track in git-spice (if not already tracked):

   bash

   gs branch track
   

Note: After recovery, the branch is properly integrated into git-spice.

Common Mistakes

Pressure Resistance

No exceptions for:

• •Time pressure
• •"Small" changes
• •User preference
• •Emergency fixes

Integration with writing-commit-messages.md

Before ANY commit:

1. •Consult writing-commit-messages in this skill directory
2. •Use those guidelines to generate commit message
3. •Then use gs command with that message

Example workflows:

Explicit: commit to current branch (no branch check needed):

User: "Commit these changes to current branch"
You: [Follow writing-commit-messages.md → craft message]
You: [Run gs commit create -m "<generated-message>"]

Explicit: commit to new branch (no branch check needed):

User: "Commit these changes to new feature branch"
You: [Follow writing-commit-messages.md → craft message]
You: [Run gs branch create <branch-name> -m "<generated-message>"]

Real-World Impact

Without this skill: Agents use raw git, breaking stack relationships, requiring manual rebases, creating tracking confusion.

With this skill: Clean stacked branches, automatic rebases, proper tracking, professional commit history.