if [[ "$REMOTE_URL" == "github.com" ]]; then echo "GitHub (use 'gh' CLI)" elif [[ "$REMOTE_URL" == "gitlab" ]]; then echo "GitLab (use 'glab' CLI)" else echo "Other platform (use standard git commands)" fi


### 2. Identify Repository Pattern

```bash
# Check if service repo (single commit per branch) or docs/notes repo (multiple logical commits)
git log --oneline -5 | head -3

Single-commit repos (services, libraries, feature branches):

One commit per branch
Amend workflow for updates
Force-push for cleanup

Multi-commit repos (documentation, notes, monorepos):

Multiple logical commits OK
Group related changes together
Regular push workflow

Single-Commit Pattern: Amend Workflow

2. Check Current State

git fetch origin
git rev-list --left-right --count origin/main...HEAD
# or
git rev-list --left-right --count origin/$(target_branch)...HEAD

Output	Meaning	Next Step
`0 0`	No commits yet	Create new commit
`0 1`	1 commit exists	Amend & update
`N 1`	Behind target by N	Rebase first
`N 2+`	Multiple commits	Squash to 1

3. Generate Commit Message

If JIRA/issue ticket convention exists in your repo:

# Extract ticket from branch name
git rev-parse --abbrev-ref HEAD
# Example: feat/PROJ-123-description → [PROJ-123]

# Check recent commit style
git log --oneline -10

# Format: <type>: [<TICKET>] [<component>:] <description>
# Example: feat: [PROJ-123] add user preferences panel

If no ticket system, use general format:

git commit -m "feat: add user preferences panel"
git commit -m "fix: handle null pointer in validation"
git commit -m "docs: update API authentication guide"

4. Execute Based on State

No commit exists (0 0):

git add -A
git commit -m "type: [TICKET] description"
git push -u origin HEAD

Commit exists (0 1) - Amend:

git add -A
git commit --amend -m "type: [TICKET] updated description"
git push --force-with-lease

Behind target (N 1) - Rebase first:

git rebase origin/$(target_branch)
# Resolve conflicts if any
git add -A
git commit --amend -m "type: [TICKET] description"
git push --force-with-lease

Multiple commits (N 2+) - Squash:

git reset --soft origin/$(target_branch)
git commit -m "type: [TICKET] description"
git push --force-with-lease

5. Create/Update Merge/Pull Request (Optional)

Detect and use the appropriate CLI for your platform:

# For GitLab repos (use glab)
glab mr create --fill --yes --assignee @me
glab mr update --assignee @me  # Update existing

# For GitHub repos (use gh)
gh pr create --fill --assignee @me
gh pr edit --add-assignee @me  # Update existing

# For other platforms
# Use web interface or platform-specific CLI

Quick detection:

if git remote get-url origin | grep -q github; then
  gh pr create --fill --assignee @me
elif git remote get-url origin | grep -q gitlab; then
  glab mr create --fill --yes --assignee @me
fi

Multi-Commit Pattern: Group and Ship

2. Review Changes

git status
git diff --stat
git diff --cached  # staged changes

3. Identify Logical Groups

Group related changes by:

Feature/ticket
Component or module
Documentation section
Tool or utility

4. Stage and Commit Each Group

# Group 1: Feature implementation
git add src/features/auth/
git add tests/features/auth/
git commit -m "feat: implement OAuth2 flow"

# Group 2: Bug fixes
git add src/utils/validation.ts
git commit -m "fix: handle edge case in date parsing"

# Group 3: Documentation
git add docs/api/auth.md
git commit -m "docs: add OAuth2 troubleshooting guide"

Each commit should be self-contained and make sense on its own.

5. Push

git push
# or
git push -u origin HEAD  # for new branch

Commit Message Conventions

Common Types

feat: New feature or capability
fix: Bug fix
docs: Documentation updates
refactor: Code restructuring (no behavior change)
test: Test additions or updates
perf: Performance improvements
chore: Maintenance, dependencies, config
ci: CI/CD pipeline changes

With Ticket (if applicable)

type: [TICKET-123] brief description

Without Ticket

type: brief description

Component Scoping (optional)

type: [TICKET] component: description
type: fix: auth: prevent token expiry race condition

Error Handling

Rebase conflicts:

View conflicts: git diff
Fix files manually
Stage resolved files: git add <files>
Continue rebase: git rebase --continue
Then proceed with commit/push

Push rejected (force-with-lease failed):

Someone else pushed to your branch or remote changed
Review incoming changes: git fetch && git log HEAD..origin/HEAD
Pull and rebase: git pull --rebase
If needed, force-push again: git push --force-with-lease

Diverged history:

Use git push --force-with-lease (safer than --force)
Only overwrites remote if it matches expected state
Use --force only if absolutely necessary (and you know why)

Safety Rules

NEVER skip hooks (--no-verify) unless explicitly requested
NEVER use --force alone—always use --force-with-lease for safety
NEVER push directly to main/master/develop (use feature branches + MR/PR workflow)
Test before pushing: Run tests locally to catch issues early

Quick Reference

# View staged changes
git diff --cached

# View all changes
git diff HEAD

# Amend last commit
git commit --amend

# Rebase on target
git rebase origin/main

# Squash last N commits
git rebase -i HEAD~N

# Safe force push
git push --force-with-lease

# Push new branch
git push -u origin HEAD

Related Skills

Commit message generation: Use /commit-message skill to format properly
Git conventions: Check your repo's contributing guide for specific rules
MR/PR workflow: Create and manage merge/pull requests for code review

ship-changes

Ship Changes

Workflow Detection

1. Detect Version Control Platform