Git Workflow Skill

Quick Start

• /git-workflow commit: Smart commit with auto-splitting
• /git-workflow push: Safe push with auto-sync
• /git-workflow pull: Safe pull with rebase
• /git-workflow branch <name>: Create and switch to branch (safe mode)
• /git-workflow status: Show current Git status with suggestions

Core Features

1. Staged Operation Flows

Automatically select appropriate Git operation flow based on development stage:

2. Smart Commit Splitting

Auto-split logic (minimize user confirmation):

• Analyze file paths and modification intent
• Group by functional relevance (same directory/feature → likely same group)
• Cross-directory modifications (e.g., src/ + docs/) → force split
• Default behavior: Auto-split and commit directly, only prompt if uncertain
• Configurable: User can set GIT_FLOW_AUTO_SPLIT=true/false

Split Logic Example:

Detected 5 file changes:
  Group 1 (feature A): src/auth/oauth2.py, tests/test_oauth2.py
  Group 2 (feature B): src/utils/token.py, tests/test_token.py
  Group 3 (docs): docs/auth.md

Auto-splitting into 3 commits...
  [1/3] feat(auth): add OAuth2 login support
  [2/3] feat(utils): add token utility functions
  [3/3] docs(auth): update auth module documentation

Committing...
✅ All commits created successfully

If uncertain about splitting:

Detected 4 files changed:
  Group 1: src/auth/oauth2.py, src/utils/token.py
  Group 2: tests/test_oauth2.py, tests/test_token.py

Suggested split (uncertain about grouping):
  1. feat(auth): add OAuth2 login and token utils
  2. test(auth): add tests for OAuth2 and token utils

Confirm? [Yes/Adjust/Cancel]

3. Safe Branch Operations

Always sync remote first before creating/switching branches:

1. git fetch origin
2. Check if local has uncommitted changes
   • If yes → auto-stash (if GIT_FLOW_AUTO_STASH=true) or prompt user
3. Check if local branch is behind remote
   • If behind → auto-pull or prompt user
4. Auto-detect if current branch complies with naming conventions

Branch Naming Convention:

• Format: feat/xxx, fix/xxx, refactor/xxx, docs/xxx, test/xxx, chore/xxx
• Auto-generate branch name from commit message or PRD content
• Validate branch name format before creation

Example: Create Branch (Safe Mode):

User: /git-workflow branch feat/user-profile
AI:  Syncing with remote...

     ✅ Remote sync complete
     ✅ Current branch: main (clean working tree)
     Creating branch...
     ✅ Branch created: feat/user-profile
     ✅ Switched to new branch

If local has uncommitted changes:

User: /git-workflow branch feat/user-profile
AI:  Syncing with remote...

     ✅ Remote sync complete
     ⚠️  Uncommitted changes detected:
        M src/auth.py
        ?? new_file.py

     Options:
       1. Auto-stash changes, apply after switch
       2. Cancel and commit changes first

     Choose [1/2]:

4. Normalized Commits

4.1 Commit Message Generation

• Auto-generate conventional commit messages based on diff content
• Format: <type>(<scope>): <subject>
• Subject length limit:
  • English: ≤ 50 characters
  • Chinese: ≤ 25 characters
• Body is optional, only added for complex changes (≤ 72 chars/line, max 3 lines)

4.2 Commit Types

5. Remote Sync

5.1 Safe Pull/Push

Before pull:

• Check if local has uncommitted changes
  • If yes → auto-stash (if configured) or warn user
• Pull strategy: Default to git pull --rebase (keep linear history)
• If divergence detected → prompt user to choose rebase/merge

Before push:

• Check if local is behind remote
  • If behind → auto-pull --rebase first, then push
  • If diverged → prompt user to choose rebase/merge

Example: Push Code to Remote (Safe Mode):

User: /git-workflow push
AI:  Checking status...

     ✅ Current branch: feat/oauth2-login
     ⚠️  Local is behind remote by 2 commits

     Auto-pulling with rebase...
     ✅ Rebase complete, no conflicts
     Pushing...
     ✅ Push successful: feat/oauth2-login → origin/feat/oauth2-login

5.2 Branch Cleanup

• Auto-detect merged local branches
• Prompt before deleting (configurable to auto-delete with GIT_FLOW_AUTO_CLEANUP=true)

6. Conflict Resolution Assistance

• Detect merge/rebase conflicts
• List conflict files
• Provide resolution suggestions based on diff analysis
• No agent calls: Only provide suggestions, user resolves manually

Example:

Conflict detected during rebase:

Conflict files:
  - src/auth/oauth2.py
  - tests/test_oauth2.py

Suggestions:
  1. src/auth/oauth2.py:
     - Incoming changes add OAuth2 support
     - Current changes refactor auth logic
     - Suggestion: Keep both, OAuth2 should call refactored auth logic

  2. tests/test_oauth2.py:
     - Incoming changes add OAuth2 tests
     - Current changes update test fixtures
     - Suggestion: Merge both test cases and update fixtures

Resolve conflicts manually, then run `/git-workflow continue` to continue rebase.

Configuration

Environment variables (can be set in project's .env file or shell):

Workflow Examples

Example 1: Start New Feature

User: /git-workflow branch feat/user-profile
AI:  Syncing with remote...

     ✅ Remote sync complete
     ✅ Current branch: main (clean working tree)
     Creating branch...
     ✅ Branch created: feat/user-profile
     ✅ Switched to new branch

     You can now start developing. Use `/git-workflow commit` to commit changes.

Example 2: Commit Code During Development

User: /git-workflow commit
AI:  Analyzing staged changes...

     Detected 3 files changed:
       Group 1: src/auth/oauth2.py, tests/test_oauth2.py
       Group 2: docs/auth.md

     Auto-splitting into 2 commits...
       [1/2] feat(auth): add OAuth2 login support
       [2/2] docs(auth): update auth module documentation

     Committing...

     [1/2] Creating commit: feat(auth): add OAuth2 login support
     ✅ Commit created: abc123

     [2/2] Creating commit: docs(auth): update auth module documentation
     ✅ Commit created: def456

     ✅ All commits created successfully

Example 3: Push Code to Remote

User: /git-workflow push
AI:  Checking status...

     ✅ Current branch: feat/oauth2-login
     ⚠️  Local is behind remote by 2 commits

     Auto-pulling with rebase...
     ✅ Rebase complete, no conflicts
     Pushing...
     ✅ Push successful: feat/oauth2-login → origin/feat/oauth2-login

Example 4: Pull Latest Changes

User: /git-workflow pull
AI:  Fetching from remote...

     ✅ Remote sync complete
     ✅ Local is behind by 3 commits

     Rebasing...
     ✅ Rebase complete, no conflicts

     ✅ Local branch updated successfully

References

• Git Workflow Specification: Detailed Git workflow specification document

Error Recovery

Merge/Rebase Conflict Cannot Be Resolved

If conflicts are too complex to resolve with suggestions alone:

1. Abort the operation:
   • During rebase: git rebase --abort
   • During merge: git merge --abort
2. Inform the user: "The conflicts are too complex for automated suggestions. I've aborted the [rebase/merge] to return to a clean state."
3. Provide options:
   • Resolve conflicts manually, then retry
   • Use git mergetool for visual conflict resolution
   • Create a new branch and cherry-pick specific commits

Detached HEAD State

If git operations result in a detached HEAD:

1. Do NOT panic — no work is lost.
2. Check state: git log --oneline -5 to see where you are.
3. Recovery:
   • If work was committed on detached HEAD: git branch <name> to save it, then git checkout <branch>
   • If work was NOT committed: git stash, then git checkout <branch>, then git stash pop

Accidental Commit on Wrong Branch

1. Do NOT push.
2. Recovery:

   git log --oneline -3  # identify the commit to move
   git checkout <correct-branch>
   git cherry-pick <commit-hash>
   git checkout <wrong-branch>
   git reset --hard HEAD~1  # remove from wrong branch
   

3. Verify: git log --oneline -3 on both branches.