Committing

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 use writing-commit-messages skill first

• Use Skill(writing-commit-messages) to load and execute it

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

Why no prefixes: git-spice adds them automatically if configured.

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
• 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:

   git log -1 --oneline
   

3. Fix commit message:

   • Use Skill(writing-commit-messages) to generate proper message
   • Amend: gs commit amend -m "<proper-message>"

4. Fix branch name if needed:

   gs branch rename <proper-name>
   

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

   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

Before ANY commit:

1. Load skill: Skill(writing-commit-messages)
2. Use it to generate commit message
3. Then use gs command with that message

If writing-commit-messages skill unavailable: Ask user for commit message that explains WHY (not what).

Example workflows:

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

User: "Commit these changes to current branch"
You: [Use Skill(writing-commit-messages) → get 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: [Use Skill(writing-commit-messages) → get 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.