Git Push Workflow Skill

A Claude Code skill for staging changes, creating conventional commits, and pushing to remote branches — with pre-push checks, conflict detection, and upstream tracking.

When to Use This Skill

Choose this skill when:

• Pushing committed changes to the remote repository
• Creating and pushing to a new remote branch
• Handling upstream tracking and push rejections
• Checking for conflicts before pushing
• Setting up push hooks and pre-push verification

Consider alternatives when:

• You need to create a PR after pushing (use a PR creation skill)
• You need to resolve merge conflicts (use a merge conflict skill)
• You need to review code before pushing (use a code review skill)

Quick Start

Copy
# Add to your Claude Code project
claude mcp add git-push

# Stage, commit, and push all changes
claude "push my changes to the remote"

# Push to a specific branch
claude "push to origin/feature-branch"

Copy
# Standard push workflow
git add -A
git commit -m "feat: add notification system"
git push origin feature/notifications

# Push new branch with upstream tracking
git push -u origin feature/notifications

# Check remote status before pushing
git fetch origin
git status  # Shows ahead/behind

Core Concepts

Push Workflow

Step	Check	Action If Failed
1. Stage	Any unstaged changes?	Stage relevant files
2. Commit	Any uncommitted staged changes?	Create commit with message
3. Fetch	Is remote ahead?	Pull/rebase before push
4. Verify	Tests pass? Lint clean?	Fix issues before pushing
5. Push	Push to remote	Handle rejection
6. Confirm	Push succeeded?	Verify with git log --oneline origin/branch

Handling Push Scenarios

Copy
# Scenario: Remote has new commits (push rejected)
git fetch origin
git rebase origin/main  # Rebase your commits on top
git push origin main

# Scenario: No upstream tracking
git push -u origin feature/my-branch

# Scenario: Push to different remote branch name
git push origin local-branch:remote-branch

# Scenario: Delete a remote branch
git push origin --delete old-branch

Pre-Push Verification

Copy
#!/bin/sh
# .git/hooks/pre-push
# Runs before every push

echo "Running pre-push checks..."

# Run tests
npm test || { echo "Tests failed - push aborted"; exit 1; }

# Run linter
npm run lint || { echo "Lint failed - push aborted"; exit 1; }

# Type check
npm run typecheck || { echo "Type check failed - push aborted"; exit 1; }

echo "All checks passed - pushing..."

Configuration

Parameter	Type	Default	Description
verify_before_push	boolean	true	Run tests and lint before pushing
auto_stage	boolean	false	Auto-stage all changes before committing
auto_fetch	boolean	true	Fetch remote before pushing to detect conflicts
set_upstream	boolean	true	Auto-set upstream tracking on first push
commit_format	string	"conventional"	Commit message format: conventional, simple
protected_branches	array	["main", "master"]	Branches that require extra confirmation
force_push	boolean	false	Allow force push (dangerous)

Best Practices

1. Always fetch before pushing — run git fetch origin to check if the remote has new commits; pushing without checking leads to rejected pushes or unintended merge commits.

2. Set upstream tracking on first push — use git push -u origin branch-name the first time so subsequent pushes only need git push without specifying the remote and branch.

3. Never force-push to shared branches — force-pushing to main or any branch others are working on overwrites their commits; only force-push to your own feature branches when necessary.

4. Run pre-push hooks for quality gates — install a pre-push hook that runs tests and linting; catching failures before push saves CI minutes and prevents broken shared branches.

5. Push frequently on feature branches — pushing to your feature branch backs up your work and lets CI run; there's no reason to batch commits on a branch only you use.

Common Issues

Push rejected: non-fast-forward — The remote branch has commits you don't have locally. Run git pull --rebase origin branch-name to replay your commits on top of the remote changes, then push again.

Push takes too long due to large files — Accidentally committed large binaries or node_modules. Remove the large file from history with git filter-branch or git-filter-repo, add it to .gitignore, and push again.

Wrong branch pushed to remote — Pushed local changes to the wrong remote branch. If caught immediately, use git push origin --delete wrong-branch to remove it. If the branch was protected, contact the repository admin.