name: push description: Comprehensive Git push operations including basic push, force push safety protocols, tag pushing, remote management, and troubleshooting. Use when pushing commits, managing remotes, pushing tags, resolving push conflicts, handling rejected pushes, or dealing with force push scenarios. Covers push strategies, branch protection, upstream configuration, and push --force-with-lease best practices. allowed-tools: Read, Bash, Glob, Grep

Git Push

Comprehensive guidance for Git push operations, from basic pushes to force push safety protocols and remote management.

Overview

This skill provides complete guidance for Git push operations, emphasizing safety protocols (especially for force pushes), remote management, and troubleshooting common push scenarios. It complements the git-commit skill (which handles commit creation) by focusing exclusively on push operations and remote synchronization.

When to Use This Skill

This skill should be used when:

Pushing commits - Basic push operations to remote repositories
Force pushing - Rewriting history with safety protocols (force-with-lease)
Pushing tags - Annotated tags, lightweight tags, tag workflows
Managing remotes - Adding, removing, renaming, configuring remote repositories
Troubleshooting pushes - Rejected pushes, conflicts, authentication issues
Upstream configuration - Setting up tracking branches, push.autoSetupRemote
Branch protection - Understanding protected branches and push restrictions

Trigger keywords: push, force push, force-with-lease, remote, upstream, tracking branch, rejected push, push --force, git push origin, push tags, remote add

Prerequisites

This skill assumes:

Git is installed (verify with git --version)
Repository initialized (local repo with .git/ directory)
Remote configured (typically origin for GitHub/GitLab/Bitbucket)
Basic Git knowledge (commits, branches, remotes)

For Git installation help, see the setup skill.

Quick Start

Basic Push

# Push current branch to remote (if upstream is configured)
git push

# Push and set upstream for first-time push
git push -u origin feature-branch

# Push specific branch to remote
git push origin main

Safe Force Push

# Safe force push (recommended - only overwrites if no one else pushed)
git push --force-with-lease

# Safest force push (recommended for maximum safety)
git push --force-with-lease --force-if-includes

# Force-with-lease for specific branch
git push --force-with-lease origin feature-branch

Push Tags

# Push specific tag
git push origin v1.0.0

# Push all tags
git push --tags

# Push commits + annotated tags pointing to them
git push --follow-tags

Core Capabilities

1. Basic Push Operations

Push local commits to remote repositories for collaboration and backup.

Essential commands:

# Push current branch (upstream must be configured)
git push

# Push and set upstream (first-time push)
git push -u origin feature-branch

# Push specific branch
git push origin main

# Dry run (preview without pushing)
git push --dry-run

📖 For detailed configuration: See references/push-configuration.md for upstream setup, push strategies, and advanced options.

2. Force Push Safety Protocols

Rewrite remote history safely when necessary (after rebasing, amending, or squashing commits).

CRITICAL SAFETY RULES:

✅ ONLY force push on feature branches (your personal work)
✅ ALWAYS use --force-with-lease (not --force)
❌ NEVER force push to main/master/develop (shared branches)
❌ NEVER force push if others are working on the same branch

Safe force push commands:

# ✅ SAFE: Only overwrites if no one else pushed since your last fetch
git push --force-with-lease

# ✅ SAFEST: Maximum safety with force-if-includes
git push --force-with-lease --force-if-includes

📖 For comprehensive safety guidance: See references/force-push-safety.md for detailed safety protocols, pre-push checklist, recovery procedures, and branch protection.

3. Tag Pushing

Push version tags to remote for releases and milestones.

Quick commands:

# Create and push annotated tag (recommended for releases)
git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

# Push all tags
git push --tags

# Push commits + annotated tags (recommended)
git push --follow-tags

📖 For complete tag workflows: See references/tag-pushing.md for tag types, strategies, aliases, and best practices.

4. Remote Management

Configure and manage remote repositories for push/fetch operations.

Quick commands:

git remote -v                    # List remotes
git remote add origin <url>      # Add remote
git remote set-url origin <url>  # Change URL
git remote rename origin upstream # Rename remote

📖 For detailed remote management: See references/remote-management.md for configuration, fork workflows, and credential management.

5. Troubleshooting Push Issues

Diagnose and resolve common push failures and conflicts.

Common issues - quick fixes:

# Rejected push (non-fast-forward)
git pull --rebase && git push

# Authentication failure
ssh -T git@github.com  # Test SSH
git remote set-url origin git@github.com:username/repo.git

# Protected branch
git switch -c feature-branch
git push -u origin feature-branch

📖 For comprehensive troubleshooting: See references/troubleshooting.md for detailed diagnosis and solutions.

Common Workflows

Feature Branch Development

git switch -c feature/user-auth
git commit -m "feat(auth): implement authentication"
git push -u origin feature/user-auth  # First push sets upstream
git push  # Subsequent pushes

Rebase and Force Push

git fetch origin
git rebase origin/main
git push --force-with-lease  # Safe force push

Hotfix to Production

git switch main && git pull
git switch -c hotfix/critical-bug
git commit -m "fix: resolve critical bug"
git push -u origin hotfix/critical-bug
gh pr create --title "HOTFIX: ..."

📖 For additional workflows: See references/workflows.md for fork contribution, release tagging, and complex multi-remote scenarios.

Best Practices

Critical Safety Rules:

✅ Always use --force-with-lease (not --force)
✅ Never force push to main/master/develop
✅ Verify no sensitive data before pushing
✅ Run tests before pushing (don't push broken code)

Push Frequency:

✅ Push daily for backup and collaboration
✅ Push after completing logical units of work
❌ Don't push broken code or sensitive data

📖 For comprehensive best practices: See references/best-practices.md for safety protocols, security, collaboration guidelines, and advanced scenarios.

References

Detailed Guides:

references/push-configuration.md - Upstream setup, push strategies, advanced options
references/force-push-safety.md - Force push safety protocols and recovery
references/tag-pushing.md - Tag types, strategies, and workflows
references/remote-management.md - Remote configuration and fork workflows
references/troubleshooting.md - Push issue diagnosis and solutions
references/workflows.md - Common workflow patterns
references/best-practices.md - Safety, security, and collaboration

Related Skills:

git-commit - Commit creation, commit messages, PR workflows
config - Git configuration, aliases, credential management
line-endings - .gitattributes, Git LFS setup

Test Scenarios

Scenario 1: Basic feature branch push

Query: "I made some commits on my feature branch. How do I push them to the remote?"

Expected Behavior:

Skill activates on "push", "feature branch", "commits", "remote"
Provides basic push command with upstream setup
Explains -u flag for first-time push

Scenario 2: Force push after rebase

Query: "I rebased my feature branch onto main. Now push is rejected. What do I do?"

Expected Behavior:

Skill activates on "rebase", "push", "rejected"
Explains why push is rejected (history rewritten)
Recommends git push --force-with-lease with safety explanation
Provides pre-force-push checklist

Scenario 3: Push tags for release

Query: "How do I push my v1.0.0 tag to GitHub?"

Expected Behavior:

Skill activates on "push", "tag", "v1.0.0", "release"
Provides specific tag push command
Explains difference between pushing single tag vs all tags

Scenario 4: Rejected push due to remote changes

Query: "My push was rejected with a message about non-fast-forward. What does that mean?"

Expected Behavior:

Skill activates on "push", "rejected", "non-fast-forward"
Explains cause (someone else pushed first)
Provides solution options (fetch+merge, fetch+rebase, pull --rebase)

Scenario 5: Managing multiple remotes

Query: "I forked a repository. How do I push to my fork but pull from the original?"

Expected Behavior:

Skill activates on "fork", "push", "pull", "remote"
Explains fork workflow with upstream remote
Provides commands to add upstream remote

Multi-Model Testing Notes

Tested with:

Claude Sonnet 4.5: ✅ VERIFIED - Skill activates correctly on all trigger keywords, provides comprehensive push guidance, handles force push safety protocols effectively. Progressive disclosure works well with references loaded on-demand.
Claude Haiku 3.7: 🔄 PENDING TESTING - Need to verify: (1) Skill activation reliability, (2) Force push safety guidance clarity, (3) Progressive disclosure effectiveness.
Claude Opus 3.7: 🔄 PENDING TESTING - Need to verify: (1) Skill activation, (2) Depth of troubleshooting guidance, (3) Reference file loading behavior.

Observations:

Strong trigger keywords ("push", "force push", "remote", "tag", "rejected", "upstream") work well across models
Force push safety protocols clearly articulated with visual warnings
Progressive disclosure implemented: Main file reduced to ~400 lines, detailed content in references/

Last Updated: 2025-11-28

Last Updated

Date: 2025-11-28 Model: claude-opus-4-5-20251101

Audit Status: ✅ PASS (Type A Standard Skill) Content Validation: All technical claims verified against git-scm.com, Perplexity, Microsoft Learn via MCP servers